1CAP_GET_PROC(3)            Linux Programmer's Manual           CAP_GET_PROC(3)
2
3
4

NAME

6       cap_get_proc,  cap_set_proc,  capgetp,  cap_get_bound,  cap_drop_bound,
7       cap_get_ambient, cap_set_ambient,  cap_reset_ambient,  cap_get_secbits,
8       cap_set_secbits,     cap_get_mode,     cap_set_mode,     cap_mode_name,
9       cap_get_pid, cap_setuid, cap_setgroups  -  capability  manipulation  on
10       processes
11

SYNOPSIS

13       #include <sys/capability.h>
14
15       cap_t cap_get_proc(void);
16
17       int cap_set_proc(cap_t cap_p);
18
19       int cap_get_bound(cap_value_t cap);
20
21       CAP_IS_SUPPORTED(cap_value_t cap);
22
23       int cap_drop_bound(cap_value_t cap);
24
25       int cap_get_ambient(cap_value_t cap);
26
27       int cap_set_ambient(cap_value_t cap, cap_flag_value_t value);
28
29       int cap_reset_ambient(void);
30
31       CAP_AMBIENT_SUPPORTED();
32
33       unsigned cap_get_secbits(void);
34
35       int cap_set_secbits(unsigned bits);
36
37       cap_mode_t cap_get_mode(void);
38
39       const char *cap_mode_name(cap_mode_t mode);
40
41       int cap_set_mode(cap_mode_t mode);
42
43       #include <sys/types.h>
44
45       cap_t cap_get_pid(pid_t pid);
46
47       int cap_setuid(uid_t uid);
48
49       int cap_setgroups(gid_t gid, size_t ngroups, const gid_t groups);
50
51       Link with -lcap.
52

DESCRIPTION

54       cap_get_proc()  allocates  a  capability state in working storage, sets
55       its state to that of the calling process, and returns a pointer to this
56       newly  created capability state.  The caller should free any releasable
57       memory, when the capability state  in  working  storage  is  no  longer
58       required, by calling cap_free() with the cap_t as an argument.
59
60       cap_set_proc()  sets  the values for all capability flags for all capa‐
61       bilities to the capability state identified by cap_p.  The new capabil‐
62       ity  state of the process will be completely determined by the contents
63       of cap_p upon successful return from this function.   If  any  flag  in
64       cap_p is set for any capability not currently permitted for the calling
65       process, the function will  fail,  and  the  capability  state  of  the
66       process will remain unchanged.
67
68       cap_get_pid() returns cap_t, see cap_init(3), with the process capabil‐
69       ities of the process indicated by pid.  (If pid is 0, then the  calling
70       process's  capabilities  are  returned.)   This information can also be
71       obtained from the /proc/<pid>/status file.
72
73       cap_get_bound() with a cap as an argument returns the current value  of
74       this  bounding  set  capability flag in effect for the calling process.
75       This operation is unprivileged.  Note,  a  macro  function  CAP_IS_SUP‐
76       PORTED(cap_value_t  cap)  is provided that evaluates to true (1) if the
77       system supports the specified capability, cap.  If the system does  not
78       support  the  capability,  this function returns 0. This macro works by
79       testing for an error condition with cap_get_bound().
80
81       cap_drop_bound() can be used to lower the specified bounding set  capa‐
82       bility,  cap.  To complete successfully, the prevailing effective capa‐
83       bility set must have a raised CAP_SETPCAP.
84
85       cap_get_ambient() returns the prevailing value of the specified ambient
86       capability,  or  -1  if  the capability is not supported by the running
87       kernel.  A macro CAP_AMBIENT_SUPPORTED() uses this function  to  deter‐
88       mine if ambient capabilities are supported by the kernel.
89
90       cap_set_ambient()  sets  the specified ambient capability to a specific
91       value. To complete successfully, the  prevailing  effective  capability
92       set must have a raised CAP_SETPCAP.  Further, to raise a specific ambi‐
93       ent capability the  inheritable  and  permitted  sets  of  the  calling
94       process  must contain the specified capability, and raised ambient bits
95       will only be retained as long as this remains true.
96
97       cap_reset_ambient() resets all of  the  ambient  capabilities  for  the
98       calling  process  to their lowered value. To complete successfully, the
99       prevailing effective capability set must  have  a  raised  CAP_SETPCAP.
100       Note,  the  ambient  set is intended to operate in a legacy environment
101       where the application has limited awareness of capabilities in general.
102       Executing  a  file  with associated filesystem capabilities, the kernel
103       will implicitly reset the ambient set of the process. Also, changes  to
104       the  inheritable  set  by the program code without explicitly fixing up
105       the ambient set can also drop ambient bits.
106
107       cap_get_secbits() returns the securebits of the calling process.  These
108       bits affect the way in which the calling process implements things like
109       setuid-root fixup and ambient capabilities.
110
111       cap_set_secbits() attempts to modify  the  securebits  of  the  calling
112       process.  Note  CAP_SETPCAP must be in the effective capability set for
113       this to  be  effective.  Some  settings  lock  the  sub-states  of  the
114       securebits,  so attempts to set values may be denied by the kernel even
115       when the CAP_SETPCAP capability is raised.
116
117       To help manage the complexity of the securebits, libcap provides a com‐
118       bined  securebit  and  capability  set  concept  called  a libcap mode.
119       cap_get_mode() attempts to summarize the prevailing  security  environ‐
120       ment in the form of a numerical cap_mode_t value. A text representation
121       of the mode can be obtained via the cap_mode_name() function. The  vast
122       majority  of combinations of these values are not well defined in terms
123       of  a  libcap  mode,  and  for  these  states  cap_get_mode()   returns
124       (cap_mode_t)0  which  cap_get_name() identifies as ``UNCERTAIN''.  Sup‐
125       ported   modes   are:   CAP_MODE_NOPRIV,    CAP_MODE_PURE1E_INIT    and
126       CAP_MODE_PURE1E.
127
128       cap_set_mode() can be used to set the desired mode. The permitted capa‐
129       bility CAP_SETPCAP is required for this function to succeed.
130
131       cap_setuid() is a convenience function for the setuid(2)  system  call.
132       Where  cap_setuid()  arranges  for the right effective capability to be
133       raised in order to perform the system call, and also arranges  to  pre‐
134       serve  the  availability  of  permitted  capabilities after the uid has
135       changed. Following this call all effective capabilities are lowered.
136
137       cap_setgroups() is a convenience function for performing both setgid(2)
138       and setgroups(2) calls in one call. The cap_setgroups() call raises the
139       right effective capability for the duration of the  call,  and  empties
140       the effective capability set before returning.
141

RETURN VALUE

143       The  functions cap_get_proc() and cap_get_pid() return a non-NULL value
144       on success, and NULL on failure.
145
146       The function cap_get_bound() returns -1 if the requested capability  is
147       unknown,  otherwise the return value reflects the current state of that
148       capability in the prevailing bounding set. Note, a macro function,
149
150       The  all  of  the  setting  functions  such   as   cap_set_proc()   and
151       cap_drop_bound() return zero for success, and -1 on failure.
152
153       On failure, errno is set to EINVAL, EPERM, or ENOMEM.
154

CONFORMING TO

156       cap_set_proc()  and  cap_get_proc()  are  specified  in  the  withdrawn
157       POSIX.1e draft specification.  cap_get_pid() is a Linux extension.
158

NOTES

160       Neither glibc, nor the Linux kernel honors POSIX semantics for  setting
161       capabilities  and  securebits  in  the  presence  of pthreads. That is,
162       changing capability sets, by default, only affect the  running  thread.
163       To  be meaningfully secure, however, the capability sets should be mir‐
164       rored by all threads within a common program because  threads  are  not
165       memory  isolated.  As  a workaround for this, libcap is packaged with a
166       separate POSIX semantics system call library: libpsx.  If your  program
167       uses  POSIX  threads,  to achieve meaningful POSIX semantics capability
168       manipulation, you should link your program with:
169
170       ld ... -lcap -lpsx -lpthread --wrap=pthread_create
171
172       or,
173
174       gcc ... -lcap -lpsx -lpthread -Wl,-wrap,pthread_create
175
176       When linked this way, due to linker magic, libcap  uses  psx_syscall(3)
177       and psx_syscall6(3) to perform state setting system calls.
178
179   capgetp() and capsetp()
180       The library also supports the deprecated functions:
181
182       int capgetp(pid_t pid, cap_t cap_d);
183
184       int capsetp(pid_t pid, cap_t cap_d);
185
186       capgetp()  attempts  to  obtain the capabilities of some other process;
187       storing the capabilities in a pre-allocated cap_d.  See cap_init()  for
188       information  on  allocating  an  empty capability set. This function is
189       deprecated; you should use cap_get_pid().
190
191       capsetp() attempts to set the capabilities of the calling porcess or of
192       some other process(es), pid.  Note that setting capabilities of another
193       process is only possible on older kernels that do not provide VFS  sup‐
194       port  for  setting file capabilities.  See capset(2) for information on
195       which kernels provide such support.
196
197       If pid is positive it refers to a specific process;  if it is zero,  it
198       refers  to  the  calling process; -1 refers to all processes other than
199       the calling process and process '1' (typically init(8)); other negative
200       values refer to the -pid process group.
201
202       In order to use this function, the kernel must support it and the call‐
203       ing process must have CAP_SETPCAP raised in  its  Effective  capability
204       set. The capabilities set in the target process(es) are those contained
205       in cap_d.
206
207       Kernels that support filesystem capabilities redefine the semantics  of
208       CAP_SETPCAP  and  on  such  systems, capsetp() will always fail for any
209       target not equal to the calling process.  capsetp()  returns  zero  for
210       success, and -1 on failure.
211
212       On  kernels  where it is (was) supported, capsetp() should be used with
213       care.  It existed, primarily, to overcome an early lack of support  for
214       capabilities in the filesystems supported by Linux.  Note that on older
215       kernels where capsetp() could  be  used  to  set  the  capabilities  of
216       another  process,  the only processes that had CAP_SETPCAP available to
217       them by default were processes started as kernel  threads.   (Typically
218       this  includes init(8), kflushd and kswapd.) A kernel recompilation was
219       needed to modify this default.
220

EXAMPLE

222       The code segment below raises the CAP_FOWNER and CAP_SETFCAP  effective
223       capabilities for the caller:
224
225           ...
226           cap_t caps;
227           const cap_value_t cap_list[2] = {CAP_FOWNER, CAP_SETFCAP};
228
229           if (!CAP_IS_SUPPORTED(CAP_SETFCAP))
230               /* handle error */
231
232           caps = cap_get_proc();
233           if (caps == NULL)
234               /* handle error */;
235
236           if (cap_set_flag(caps, CAP_EFFECTIVE, 2, cap_list, CAP_SET) == -1)
237               /* handle error */;
238
239           if (cap_set_proc(caps) == -1)
240               /* handle error */;
241
242           if (cap_free(caps) == -1)
243               /* handle error */;
244           ...
245
246       Alternatively,  to  completely  drop  privilege  in  a program launched
247       setuid-root but wanting to run as a specific user ID etc. in such a way
248       that neither it, nor any of its children can acquire privilege again:
249
250           ...
251           uid_t nobody = 65534;
252           const gid_t groups[] = {65534};
253
254           if (cap_setgroups(groups[0], 1, groups) != 0)
255               /* handle error */;
256           if (cap_setuid(nobody) != 0)
257               /* handle error */;
258
259           /*
260            * privilege is still available here
261            */
262
263           if (cap_set_mode(CAP_MODE_NOPRIV) != 0)
264               /* handle error */
265           ...
266
267       Note, the above sequence can be performed by the capsh tool as follows:
268
269       sudo /sbin/capsh --user=nobody --mode=NOPRIV --print
270
271       where --print displays the resulting privilege state.
272

SEE ALSO

274       libcap(3),    libpsx(3),   capsh(1),   cap_clear(3),   cap_copy_ext(3),
275       cap_from_text(3), cap_get_file(3), cap_init(3),  psx_syscall(3),  capa‐
276       bilities(7).
277
278
279
280                                  2019-12-21                   CAP_GET_PROC(3)
Impressum