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
20       option 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
29       exact  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                     After changing the uid and gid, clear  the  bounding  set
48                     regardless to the internal representation already setup.
49
50

RETURN VALUE

52       This  returns  0  on success and a negative number on failure. -1 means
53       capng has not been initted properly, -2 means a failure  requesting  to
54       keep  capabilities  across  the  uid change, -3 means that applying the
55       intermediate capabilities failed, -4  means  changing  gid  failed,  -5
56       means  dropping  supplemental  groups failed, -6 means changing the uid
57       failed, -7 means dropping the ability  to  retain  caps  across  a  uid
58       change  failed,  -8  means  clearing  the bounding set failed, -9 means
59       dropping CAP_SETPCAP failed, -10 means initializing supplemental groups
60       failed.
61
62       Note:  the  only  safe action to do upon failure of this function is to
63       probably exit. This is because you are likely in a situation with  par‐
64       tial permissions and not what you intended.
65
66

SEE ALSO

68       capng_update(3), capng_apply(3), prctl(2), capabilities(7)
69
70

AUTHOR

72       Steve Grubb
73
74
75
76Red Hat                            Feb 2018                 CAPNG_CHANGE_ID(3)
Impressum