| 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). |