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                     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. -1 means
58       capng has not been initted properly, -2 means a failure  requesting  to
59       keep  capabilities  across  the  uid change, -3 means that applying the
60       intermediate capabilities failed, -4  means  changing  gid  failed,  -5
61       means  dropping  supplemental  groups failed, -6 means changing the uid
62       failed, -7 means dropping the ability  to  retain  caps  across  a  uid
63       change  failed,  -8  means  clearing  the bounding set failed, -9 means
64       dropping CAP_SETPCAP failed, -10 means initializing supplemental groups
65       failed.
66
67       Note:  the  only  safe action to do upon failure of this function is to
68       probably exit. This is because you are likely in a situation with  par‐
69       tial permissions and not what you intended.
70
71

SEE ALSO

73       capng_update(3), capng_apply(3), prctl(2), capabilities(7)
74
75

AUTHOR

77       Steve Grubb
78
79
80
81Red Hat                            Feb 2018                 CAPNG_CHANGE_ID(3)
Impressum