Debian Codegraph @

doc/cap_get_proc.3

raw
1 .TH CAP_GET_PROC 3 "2024-11-09" "" "Linux Programmer's Manual"
2 .SH NAME
3 cap_get_proc, cap_set_proc, capgetp, cap_get_bound, cap_drop_bound, \
4 cap_get_ambient, cap_set_ambient, cap_reset_ambient, \
5 cap_get_secbits, cap_set_secbits, cap_get_mode, cap_set_mode, \
6 cap_mode_name, cap_get_pid, cap_setuid, cap_prctl, cap_prctlw, cap_setgroups \
7 \- capability manipulation on processes
8 .SH SYNOPSIS
9 .nf
10 #include <sys/capability.h>
11
12 cap_t cap_get_proc(void);
13 int cap_set_proc(cap_t cap_p);
14
15 int cap_get_bound(cap_value_t cap);
16 CAP_IS_SUPPORTED(cap_value_t cap);
17
18 int cap_drop_bound(cap_value_t cap);
19 int cap_get_ambient(cap_value_t cap);
20 int cap_set_ambient(cap_value_t cap, cap_flag_value_t value);
21 int cap_reset_ambient(void);
22 CAP_AMBIENT_SUPPORTED();
23
24 unsigned cap_get_secbits(void);
25 int cap_set_secbits(unsigned bits);
26 cap_mode_t cap_get_mode(void);
27 const char *cap_mode_name(cap_mode_t mode);
28 int cap_prctl(long int pr_cmd, long int arg1, long int arg2,
29 long int arg3, long int arg4, long int arg5);
30 int cap_prctlw(long int pr_cmd, long int arg1, long int arg2,
31 long int arg3, long int arg4, long int arg5);
32 int cap_set_mode(cap_mode_t mode);
33
34 #include <sys/types.h>
35
36 cap_t cap_get_pid(pid_t pid);
37 int cap_setuid(uid_t uid);
38 int cap_setgroups(gid_t gid, size_t ngroups, const gid_t groups);
39 .fi
40 .sp
41 Link with \fI\-lcap\fP.
42 .SH DESCRIPTION
43 .BR cap_get_proc ()
44 allocates a capability state in working storage, sets its state to
45 that of the calling process, and returns a pointer to this newly
46 created capability state. The caller should free any releasable
47 memory, when the capability state in working storage is no longer
48 required, by calling
49 .BR cap_free ()
50 with the
51 .I cap_t
52 as an argument.
53 .PP
54 .BR cap_set_proc ()
55 sets the values for all capability flags for all capabilities to the
56 capability state identified by
57 .IR cap_p .
58 The new capability state of the process will be completely determined by
59 the contents of
60 .I cap_p
61 upon successful return from this function. If any flag in
62 .I cap_p
63 is set for any capability not currently permitted for the calling process,
64 the function will fail, and the capability state of the process will remain
65 unchanged.
66 .PP
67 .BR cap_get_pid ()
68 returns a
69 .IR cap_t ,
70 see
71 .BR cap_init (3),
72 with the process capabilities of the process known to the caller as
73 .IR pid .
74 If
75 .I pid
76 is 0, then the calling process's capabilities are returned.
77 This information can also be obtained from the
78 .I /proc/<pid>/status
79 file. (The entries in that file can be translated with the
80 .BI "capsh \-\-decode=" XXX
81 command line.) When the caller is operating within a
82 .RB ( CLONE_NEWPID )
83 namespace, the numerical
84 .I pid
85 argument is interpreted in the range of that namespace. As such, the
86 caller's idea of the target
87 .I pid
88 may differ from that of the target process when they are operating in
89 different pid namespaces. See
90 .BR pid_namespaces (7)
91 for details.
92 Further, the returned
93 .I cap_t
94 value holds the capabilities that the target
95 .I pid
96 thinks it has. If the target is operating in a
97 .RB ( CLONE_NEWUSER )
98 namespace, the system wide privilege of those user namespace
99 capabilities may be substantially reduced. See
100 .BR user_namespaces (7)
101 for details.
102 .PP
103 .BR cap_get_bound ()
104 with a
105 .I cap
106 as an argument returns the current value of this bounding set
107 capability flag in effect for the calling process. This operation is
108 unprivileged. Note, a macro function
109 .BR "CAP_IS_SUPPORTED(cap_value_t " cap )
110 is provided that evaluates to true (1) if the system supports the
111 specified capability,
112 .IR cap .
113 If the system does not support the capability, this function returns
114 0. This macro works by testing for an error condition with
115 .BR cap_get_bound ().
116 .PP
117 .BR cap_drop_bound ()
118 can be used to lower the specified bounding set capability,
119 .BR cap .
120 To complete successfully, the prevailing
121 .I effective
122 capability set must have a raised
123 .BR CAP_SETPCAP .
124 .PP
125 .BR cap_get_ambient ()
126 returns the prevailing value of the specified ambient capability, or
127 -1 if the capability is not supported by the running kernel. A macro
128 .BR CAP_AMBIENT_SUPPORTED ()
129 uses this function to determine if ambient capabilities are supported
130 by the kernel.
131 .PP
132 .BR cap_set_ambient ()
133 sets the specified ambient capability to a specific value. To raise a
134 specific ambient capability the
135 .IR inheritable " and " permitted
136 flags of the calling process must contain the specified capability
137 value. Raised ambient bits will only be retained as long as this
138 remains true of the inheritable and permitted flags.
139 .PP
140 .BR cap_reset_ambient ()
141 resets all of the ambient capabilities for the calling process to
142 their lowered value. Note, the ambient set is intended to operate in a
143 legacy environment where the application has limited awareness of
144 capabilities in general. Executing a file, with associated filesystem
145 capabilities, the kernel will implicitly reset the ambient set of the
146 process. Further, changes to the inheritable set by the program code
147 without explicitly fixing up the ambient set can also drop ambient
148 bits.
149 .PP
150 .BR cap_get_secbits ()
151 returns the securebits of the calling process. These bits affect the
152 way in which the calling process implements things like setuid-root
153 fixup and ambient capabilities.
154 .PP
155 .BR cap_set_secbits ()
156 attempts to modify the securebits of the calling process. Note
157 .B CAP_SETPCAP
158 must be in the effective capability set for this to be effective. Some
159 settings lock the sub-states of the securebits, so attempts to set values
160 may be denied by the kernel even when the
161 .B CAP_SETPCAP
162 capability is raised.
163 .PP
164 To help manage the complexity of the securebits, libcap provides a
165 combined securebit and capability set concept called a libcap mode.
166 .BR cap_get_mode ()
167 attempts to summarize the prevailing security environment in the form
168 of a numerical
169 .B cap_mode_t
170 value. A text representation of the mode can be obtained via the
171 .BR cap_mode_name ()
172 function. The vast majority of combinations of these values are not well
173 defined in terms of a libcap mode, and for these states
174 .BR cap_get_mode ()
175 returns
176 .RB ( cap_mode_t )0
177 which
178 .BR cap_get_name ()
179 identifies as
180 .RI `` UNCERTAIN ''.
181 Supported modes are:
182 .BR CAP_MODE_NOPRIV ", " CAP_MODE_HYBRID ", " CAP_MODE_PURE1E " and "
183 .BR CAP_MODE_PURE1E_INIT .
184 .PP
185 .BR cap_prctl ()
186 can be used to read state via the \fBprctl\fI()\fP system call.
187 .PP
188 .BR cap_prctlw ()
189 can be used to write state via the \fBprctl\fI()\fP system call.
190 .PP
191 .BR cap_set_mode ()
192 can be used to set the desired mode. The permitted capability
193 .B CAP_SETPCAP
194 is required for this function to succeed.
195 .PP
196 .BR cap_setuid ()
197 is a convenience function for the
198 .BR setuid (2)
199 system call. Where
200 .BR cap_setuid ()
201 arranges for the right effective capability to be raised in order to
202 perform the system call, and also arranges to preserve the
203 availability of permitted capabilities after the uid has
204 changed. Following this call all effective capabilities are lowered.
205 .PP
206 .BR cap_setgroups ()
207 is a convenience function for performing both
208 .BR setgid (2)
209 and
210 .BR setgroups (2)
211 calls in one call. The
212 .BR cap_setgroups ()
213 call raises the right effective capability for the duration of the
214 call, and empties the effective capability set before returning.
215 .SH "RETURN VALUE"
216 The functions
217 .BR cap_get_proc ()
218 and
219 .BR cap_get_pid ()
220 return a non-NULL value on success, and NULL on failure.
221 .PP
222 The function
223 .BR cap_get_bound ()
224 returns \-1 if the requested capability is unknown, otherwise the
225 return value reflects the current state of that capability in the
226 prevailing bounding set. Note, a macro function,
227 .PP
228 The all of the setting functions such as
229 .BR cap_set_proc ()
230 and
231 .BR cap_drop_bound ()
232 return zero for success, and \-1 on failure.
233 .PP
234 On failure,
235 .I errno
236 is set to
237 .BR EINVAL ,
238 .BR EPERM ,
239 or
240 .BR ENOMEM .
241 .SH "CONFORMING TO"
242 .BR cap_set_proc ()
243 and
244 .BR cap_get_proc ()
245 are specified in the withdrawn POSIX.1e draft specification.
246 .BR cap_get_pid ()
247 is a Linux extension.
248 .SH "NOTES"
249 Neither glibc, nor the Linux kernel honors POSIX semantics for setting
250 capabilities and securebits in the presence of pthreads. That is,
251 changing capability sets, by default, only affect the running
252 thread. To be meaningfully secure, however, the capability sets should
253 be mirrored by all threads within a common program because threads are
254 not memory isolated. As a workaround for this,
255 .B libcap
256 is packaged with a separate POSIX semantics system call library:
257 .BR libpsx .
258 If your program uses POSIX threads, to achieve meaningful POSIX
259 semantics capability manipulation, you should link your program with:
260 .sp
261 .B ld ... \-lcap $(pkg-config \-\-libs \-\-cflags libpsx)
262 .sp
263 or,
264 .sp
265 .B gcc ... \-lcap $(pkg-config \-\-libs \-\-cflags libpsx)
266 .sp
267 When linked this way, due to linker magic, libcap uses
268 .BR psx_syscall "(3) and " psx_syscall6 (3)
269 to perform state setting system calls. Notably, this also ensures that
270 .BI cap_prctlw ()
271 can be used to ensure process control bits are shared over all threads
272 of a single process.
273 .SS capgetp() and capsetp()
274 The library also supports the deprecated functions:
275 .PP
276 .BI "int capgetp(pid_t " pid ", cap_t " cap_d );
277 .PP
278 .BI "int capsetp(pid_t " pid ", cap_t " cap_d );
279 .PP
280 .BR capgetp ()
281 attempts to obtain the capabilities of some other process; storing the
282 capabilities in a pre-allocated
283 .IR cap_d .
284 See
285 .BR cap_init ()
286 for information on allocating an empty capability set. This function
287 is deprecated; you should use
288 .BR cap_get_pid ().
289 .PP
290 .BR capsetp ()
291 attempts to set the capabilities of the calling process or of
292 some other process(es),
293 .IR pid .
294 Note that setting capabilities of another process is only possible on older
295 kernels that do not provide VFS support for setting file capabilities.
296 See
297 .BR capset (2)
298 for information on which kernels provide such support.
299 .PP
300 If
301 .I pid
302 is positive it refers to a specific process; if it is zero, it refers
303 to the calling process; \-1 refers to all processes other than the
304 calling process and process '1' (typically
305 .BR init (8));
306 other negative values refer to the
307 .I \-pid
308 process group.
309 .PP
310 In order to use this function, the kernel must support
311 it and the calling process must have
312 .B CAP_SETPCAP
313 raised in its Effective capability set. The capabilities set in the
314 target process(es) are those contained in
315 .IR cap_d .
316 .PP
317 Kernels that support filesystem capabilities redefine the semantics of
318 .B CAP_SETPCAP
319 and on such systems,
320 .BR capsetp ()
321 will always fail for any target not
322 equal to the calling process.
323 .BR capsetp ()
324 returns zero for success, and \-1 on failure.
325 .PP
326 On kernels where it is (was) supported,
327 .BR capsetp ()
328 should be used with care. It existed, primarily, to overcome an early
329 lack of support for capabilities in the filesystems supported by
330 Linux. Note that on older kernels where
331 .BR capsetp ()
332 could be used to set the capabilities of another process,
333 the only processes that had
334 .B CAP_SETPCAP
335 available to them by default were processes started as kernel threads.
336 (Typically this includes
337 .BR init (8),
338 kflushd and kswapd.) A kernel recompilation was needed to modify
339 this default.
340 .SH EXAMPLE
341 The code segment below raises the
342 .B CAP_FOWNER
343 and
344 .B CAP_SETFCAP
345 effective capabilities for the caller:
346 .nf
347
348 ...
349 cap_t caps;
350 const cap_value_t cap_list[2] = {CAP_FOWNER, CAP_SETFCAP};
351
352 if (!CAP_IS_SUPPORTED(CAP_SETFCAP))
353 /* handle error */
354
355 caps = cap_get_proc();
356 if (caps == NULL)
357 /* handle error */;
358
359 if (cap_set_flag(caps, CAP_EFFECTIVE, 2, cap_list, CAP_SET) == \-1)
360 /* handle error */;
361
362 if (cap_set_proc(caps) == \-1)
363 /* handle error */;
364
365 if (cap_free(caps) == \-1)
366 /* handle error */;
367 ...
368
369 .fi
370 Alternatively, to completely drop privilege in a program launched
371 setuid-root but wanting to run as a specific user ID etc. in such a
372 way that neither it, nor any of its children can acquire privilege
373 again:
374 .nf
375
376 ...
377 uid_t nobody = 65534;
378 const gid_t groups[] = {65534};
379
380 if (cap_setgroups(groups[0], 1, groups) != 0)
381 /* handle error */;
382 if (cap_setuid(nobody) != 0)
383 /* handle error */;
384
385 /*
386 * privilege is still available here
387 */
388
389 if (cap_set_mode(CAP_MODE_NOPRIV) != 0)
390 /* handle error */
391 ...
392
393 .fi
394 Note, the above sequence can be performed by the
395 .B capsh
396 tool as follows:
397 .sp
398 .B sudo capsh \-\-user=nobody \-\-mode=NOPRIV \-\-print
399 .sp
400 where
401 .B \-\-print
402 displays the resulting privilege state.
403 .SH "SEE ALSO"
404 .BR libcap (3),
405 .BR libpsx (3),
406 .BR capsh (1),
407 .BR cap_clear (3),
408 .BR cap_copy_ext (3),
409 .BR cap_from_text (3),
410 .BR cap_get_file (3),
411 .BR cap_init (3),
412 .BR namespaces (7),
413 .BR pid_namespaces (7),
414 .BR user_namespaces (7),
415 .BR psx_syscall (3),
416 .BR capabilities (7).