1CAPNG_CHANGE_ID(3)               Libcap-ng API              CAPNG_CHANGE_ID(3)
2
3
4

NAME

6       capng_change_id - change the credentials retaining capabilities
7

SYNOPSIS

9       #include <cap-ng.h>
10
11       int capng_change_id(int uid, int gid, capng_flags_t flag);
12
13

DESCRIPTION

15       This function will change uid and gid to the ones given while retaining
16       the capabilities previously specified in capng_update. It is also  pos‐
17       sible  to  specify -1 for either the uid or gid in which case the func‐
18       tion will not change the uid or gid and leave it "as is". This is  use‐
19       ful  if  you just want the flag options to be applied (assuming the op‐
20       tion doesn't require more privileges that you currently have).
21
22       It is not necessary and perhaps better  if  capng_apply  has  not  been
23       called  prior  to  this  function  so that all necessary privileges are
24       still intact. The caller may be required to have CAP_SETPCAP capability
25       still  active  before  calling  this function or capabilities cannot be
26       changed.
27
28       This function also takes a flag parameter that helps to tailor the  ex‐
29       act  actions  performed  by the function to secure the environment. The
30       option may be or'ed together. The legal values are:
31
32
33              CAPNG_NO_FLAG
34                     Simply change uid and retain specified  capabilities  and
35                     that's all.
36
37              CAPNG_DROP_SUPP_GRP
38                     After  changing id, remove any supplement groups that may
39                     still be in effect from the old uid.
40
41              CAPNG_INIT_SUPP_GRP
42                     After changing id, initialize any supplement groups  that
43                     may   come   with   the   new   account.  If  given  with
44                     CAPNG_DROP_SUPP_GRP it will have no effect.
45
46              CAPNG_CLEAR_BOUNDING
47                     Clear the bounding set regardless to the internal  repre‐
48                     sentation already setup prior to changing the uid/gid.
49
50              CAPNG_CLEAR_AMBIENT
51                     Clear  ambient  capabilities  regardless  of the internal
52                     representation  already  setup  prior  to  changing   the
53                     uid/gid.
54
55

RETURN VALUE

57       This returns 0 on success and a negative number on failure.
58
59              -1 means capng has not been initted properly
60
61              -2  means  a  failure requesting to keep capabilities across the
62              uid change
63
64              -3 means that applying the intermediate capabilities failed
65
66              -4 means changing gid failed
67
68              -5 means dropping supplemental groups failed
69
70              -6 means changing the uid failed
71
72              -7 means dropping the ability to retain caps across a uid change
73              failed
74
75              -8 means clearing the bounding set failed
76
77              -9 means dropping CAP_SETPCAP or ambient capabilities failed
78
79              -10 means initializing supplemental groups failed
80
81       Note:  the  only  safe action to do upon failure of this function is to
82       probably exit. This is because you are likely in a situation with  par‐
83       tial permissions and not what you intended.
84
85

SEE ALSO

87       capng_update(3), capng_apply(3), prctl(2), capabilities(7)
88
89

AUTHOR

91       Steve Grubb
92
93
94
95Red Hat                            Feb 2018                 CAPNG_CHANGE_ID(3)
Impressum