| 1 |
.\" Copyright 2002, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH Capabilities 7 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
capabilities \- overview of Linux capabilities |
| 9 |
.SH DESCRIPTION |
| 10 |
For the purpose of performing permission checks, |
| 11 |
traditional UNIX implementations distinguish two categories of processes: |
| 12 |
.I privileged |
| 13 |
processes (whose effective user ID is 0, referred to as superuser or root), |
| 14 |
and |
| 15 |
.I unprivileged |
| 16 |
processes (whose effective UID is nonzero). |
| 17 |
Privileged processes bypass all kernel permission checks, |
| 18 |
while unprivileged processes are subject to full permission |
| 19 |
checking based on the process's credentials |
| 20 |
(usually: effective UID, effective GID, and supplementary group list). |
| 21 |
.P |
| 22 |
Starting with Linux 2.2, Linux divides the privileges traditionally |
| 23 |
associated with superuser into distinct units, known as |
| 24 |
.IR capabilities , |
| 25 |
which can be independently enabled and disabled. |
| 26 |
Capabilities are a per-thread attribute. |
| 27 |
.\" |
| 28 |
.SS Capabilities list |
| 29 |
The following list shows the capabilities implemented on Linux, |
| 30 |
and the operations or behaviors that each capability permits: |
| 31 |
.TP |
| 32 |
.BR CAP_AUDIT_CONTROL " (since Linux 2.6.11)" |
| 33 |
Enable and disable kernel auditing; |
| 34 |
change auditing filter rules; |
| 35 |
retrieve auditing status and filtering rules. |
| 36 |
.TP |
| 37 |
.BR CAP_AUDIT_READ " (since Linux 3.16)" |
| 38 |
.\" commit a29b694aa1739f9d76538e34ae25524f9c549d59 |
| 39 |
.\" commit 3a101b8de0d39403b2c7e5c23fd0b005668acf48 |
| 40 |
Allow reading the audit log via a multicast netlink socket. |
| 41 |
.TP |
| 42 |
.BR CAP_AUDIT_WRITE " (since Linux 2.6.11)" |
| 43 |
Write records to kernel auditing log. |
| 44 |
.\" FIXME Add FAN_ENABLE_AUDIT |
| 45 |
.TP |
| 46 |
.BR CAP_BLOCK_SUSPEND " (since Linux 3.5)" |
| 47 |
Employ features that can block system suspend |
| 48 |
.RB ( epoll (7) |
| 49 |
.BR EPOLLWAKEUP , |
| 50 |
.IR /proc/sys/wake_lock ). |
| 51 |
.TP |
| 52 |
.BR CAP_BPF " (since Linux 5.8)" |
| 53 |
Employ privileged BPF operations; |
| 54 |
see |
| 55 |
.BR bpf (2) |
| 56 |
and |
| 57 |
.BR bpf\-helpers (7). |
| 58 |
.IP |
| 59 |
This capability was added in Linux 5.8 to separate out |
| 60 |
BPF functionality from the overloaded |
| 61 |
.B CAP_SYS_ADMIN |
| 62 |
capability. |
| 63 |
.TP |
| 64 |
.BR CAP_CHECKPOINT_RESTORE " (since Linux 5.9)" |
| 65 |
.\" commit 124ea650d3072b005457faed69909221c2905a1f |
| 66 |
.PD 0 |
| 67 |
.RS |
| 68 |
.IP \[bu] 3 |
| 69 |
Update |
| 70 |
.I /proc/sys/kernel/ns_last_pid |
| 71 |
(see |
| 72 |
.BR pid_namespaces (7)); |
| 73 |
.IP \[bu] |
| 74 |
employ the |
| 75 |
.I set_tid |
| 76 |
feature of |
| 77 |
.BR clone3 (2); |
| 78 |
.\" FIXME There is also some use case relating to |
| 79 |
.\" prctl_set_mm_exe_file(); in the 5.9 sources, see |
| 80 |
.\" prctl_set_mm_map(). |
| 81 |
.IP \[bu] |
| 82 |
read the contents of the symbolic links in |
| 83 |
.IR /proc/ pid /map_files |
| 84 |
for other processes. |
| 85 |
.RE |
| 86 |
.PD |
| 87 |
.IP |
| 88 |
This capability was added in Linux 5.9 to separate out |
| 89 |
checkpoint/restore functionality from the overloaded |
| 90 |
.B CAP_SYS_ADMIN |
| 91 |
capability. |
| 92 |
.TP |
| 93 |
.B CAP_CHOWN |
| 94 |
Make arbitrary changes to file UIDs and GIDs (see |
| 95 |
.BR chown (2)). |
| 96 |
.TP |
| 97 |
.B CAP_DAC_OVERRIDE |
| 98 |
Bypass file read, write, and execute permission checks. |
| 99 |
(DAC is an abbreviation of "discretionary access control".) |
| 100 |
.TP |
| 101 |
.B CAP_DAC_READ_SEARCH |
| 102 |
.PD 0 |
| 103 |
.RS |
| 104 |
.IP \[bu] 3 |
| 105 |
Bypass file read permission checks and |
| 106 |
directory read and execute permission checks; |
| 107 |
.IP \[bu] |
| 108 |
invoke |
| 109 |
.BR open_by_handle_at (2); |
| 110 |
.IP \[bu] |
| 111 |
use the |
| 112 |
.BR linkat (2) |
| 113 |
.B AT_EMPTY_PATH |
| 114 |
flag to create a link to a file referred to by a file descriptor. |
| 115 |
.RE |
| 116 |
.PD |
| 117 |
.TP |
| 118 |
.B CAP_FOWNER |
| 119 |
.PD 0 |
| 120 |
.RS |
| 121 |
.IP \[bu] 3 |
| 122 |
Bypass permission checks on operations that normally |
| 123 |
require the filesystem UID of the process to match the UID of |
| 124 |
the file (e.g., |
| 125 |
.BR chmod (2), |
| 126 |
.BR utime (2)), |
| 127 |
excluding those operations covered by |
| 128 |
.B CAP_DAC_OVERRIDE |
| 129 |
and |
| 130 |
.BR CAP_DAC_READ_SEARCH ; |
| 131 |
.IP \[bu] |
| 132 |
set inode flags (see |
| 133 |
.BR FS_IOC_SETFLAGS (2const)) |
| 134 |
on arbitrary files; |
| 135 |
.IP \[bu] |
| 136 |
set Access Control Lists (ACLs) on arbitrary files; |
| 137 |
.IP \[bu] |
| 138 |
ignore directory sticky bit on file deletion; |
| 139 |
.IP \[bu] |
| 140 |
modify |
| 141 |
.I user |
| 142 |
extended attributes on sticky directory owned by any user; |
| 143 |
.IP \[bu] |
| 144 |
specify |
| 145 |
.B O_NOATIME |
| 146 |
for arbitrary files in |
| 147 |
.BR open (2) |
| 148 |
and |
| 149 |
.BR fcntl (2). |
| 150 |
.RE |
| 151 |
.PD |
| 152 |
.TP |
| 153 |
.B CAP_FSETID |
| 154 |
.PD 0 |
| 155 |
.RS |
| 156 |
.IP \[bu] 3 |
| 157 |
Don't clear set-user-ID and set-group-ID mode |
| 158 |
bits when a file is modified; |
| 159 |
.IP \[bu] |
| 160 |
set the set-group-ID bit for a file whose GID does not match |
| 161 |
the filesystem or any of the supplementary GIDs of the calling process. |
| 162 |
.RE |
| 163 |
.PD |
| 164 |
.TP |
| 165 |
.B CAP_IPC_LOCK |
| 166 |
.\" FIXME . As at Linux 3.2, there are some strange uses of this capability |
| 167 |
.\" in other places; they probably should be replaced with something else. |
| 168 |
.PD 0 |
| 169 |
.RS |
| 170 |
.IP \[bu] 3 |
| 171 |
Lock memory |
| 172 |
.RB ( mlock (2), |
| 173 |
.BR mlockall (2), |
| 174 |
.BR mmap (2), |
| 175 |
.BR shmctl (2)); |
| 176 |
.IP \[bu] |
| 177 |
Allocate memory using huge pages |
| 178 |
.RB ( memfd_create (2), |
| 179 |
.BR mmap (2), |
| 180 |
.BR shmctl (2)). |
| 181 |
.RE |
| 182 |
.PD |
| 183 |
.TP |
| 184 |
.B CAP_IPC_OWNER |
| 185 |
Bypass permission checks for operations on System V IPC objects. |
| 186 |
.TP |
| 187 |
.B CAP_KILL |
| 188 |
Bypass permission checks for sending signals (see |
| 189 |
.BR kill (2)). |
| 190 |
This includes use of the |
| 191 |
.BR ioctl (2) |
| 192 |
.B KDSIGACCEPT |
| 193 |
operation. |
| 194 |
.\" FIXME . CAP_KILL also has an effect for threads + setting child |
| 195 |
.\" termination signal to other than SIGCHLD: without this |
| 196 |
.\" capability, the termination signal reverts to SIGCHLD |
| 197 |
.\" if the child does an exec(). What is the rationale |
| 198 |
.\" for this? |
| 199 |
.TP |
| 200 |
.BR CAP_LEASE " (since Linux 2.4)" |
| 201 |
Establish leases on arbitrary files (see |
| 202 |
.BR fcntl (2)). |
| 203 |
.TP |
| 204 |
.B CAP_LINUX_IMMUTABLE |
| 205 |
Set the |
| 206 |
.B FS_APPEND_FL |
| 207 |
and |
| 208 |
.B FS_IMMUTABLE_FL |
| 209 |
inode flags (see |
| 210 |
.BR FS_IOC_SETFLAGS (2const)). |
| 211 |
.TP |
| 212 |
.BR CAP_MAC_ADMIN " (since Linux 2.6.25)" |
| 213 |
Allow MAC configuration or state changes. |
| 214 |
Implemented for the Smack Linux Security Module (LSM). |
| 215 |
.TP |
| 216 |
.BR CAP_MAC_OVERRIDE " (since Linux 2.6.25)" |
| 217 |
Override Mandatory Access Control (MAC). |
| 218 |
Implemented for the Smack LSM. |
| 219 |
.TP |
| 220 |
.BR CAP_MKNOD " (since Linux 2.4)" |
| 221 |
Create special files using |
| 222 |
.BR mknod (2). |
| 223 |
.TP |
| 224 |
.B CAP_NET_ADMIN |
| 225 |
Perform various network-related operations: |
| 226 |
.PD 0 |
| 227 |
.RS |
| 228 |
.IP \[bu] 3 |
| 229 |
interface configuration; |
| 230 |
.IP \[bu] |
| 231 |
administration of IP firewall, masquerading, and accounting; |
| 232 |
.IP \[bu] |
| 233 |
modify routing tables; |
| 234 |
.IP \[bu] |
| 235 |
bind to any address for transparent proxying; |
| 236 |
.IP \[bu] |
| 237 |
set type-of-service (TOS); |
| 238 |
.IP \[bu] |
| 239 |
clear driver statistics; |
| 240 |
.IP \[bu] |
| 241 |
set promiscuous mode; |
| 242 |
.IP \[bu] |
| 243 |
enabling multicasting; |
| 244 |
.IP \[bu] |
| 245 |
use |
| 246 |
.BR setsockopt (2) |
| 247 |
to set the following socket options: |
| 248 |
.BR SO_DEBUG , |
| 249 |
.BR SO_MARK , |
| 250 |
.B SO_PRIORITY |
| 251 |
(for a priority outside the range 0 to 6), |
| 252 |
.BR SO_RCVBUFFORCE , |
| 253 |
and |
| 254 |
.BR SO_SNDBUFFORCE . |
| 255 |
.RE |
| 256 |
.PD |
| 257 |
.TP |
| 258 |
.B CAP_NET_BIND_SERVICE |
| 259 |
Bind a socket to Internet domain privileged ports |
| 260 |
(port numbers less than 1024). |
| 261 |
.TP |
| 262 |
.B CAP_NET_BROADCAST |
| 263 |
(Unused) Make socket broadcasts, and listen to multicasts. |
| 264 |
.\" FIXME Since Linux 4.2, there are use cases for netlink sockets |
| 265 |
.\" commit 59324cf35aba5336b611074028777838a963d03b |
| 266 |
.TP |
| 267 |
.B CAP_NET_RAW |
| 268 |
.PD 0 |
| 269 |
.RS |
| 270 |
.IP \[bu] 3 |
| 271 |
Use RAW and PACKET sockets; |
| 272 |
.IP \[bu] |
| 273 |
bind to any address for transparent proxying. |
| 274 |
.RE |
| 275 |
.PD |
| 276 |
.\" Also various IP options and setsockopt(SO_BINDTODEVICE) |
| 277 |
.TP |
| 278 |
.BR CAP_PERFMON " (since Linux 5.8)" |
| 279 |
Employ various performance-monitoring mechanisms, including: |
| 280 |
.RS |
| 281 |
.IP \[bu] 3 |
| 282 |
.PD 0 |
| 283 |
call |
| 284 |
.BR perf_event_open (2); |
| 285 |
.IP \[bu] |
| 286 |
employ various BPF operations that have performance implications. |
| 287 |
.RE |
| 288 |
.PD |
| 289 |
.IP |
| 290 |
This capability was added in Linux 5.8 to separate out |
| 291 |
performance monitoring functionality from the overloaded |
| 292 |
.B CAP_SYS_ADMIN |
| 293 |
capability. |
| 294 |
See also the kernel source file |
| 295 |
.IR Documentation/admin\-guide/perf\-security.rst . |
| 296 |
.TP |
| 297 |
.B CAP_SETGID |
| 298 |
.RS |
| 299 |
.PD 0 |
| 300 |
.IP \[bu] 3 |
| 301 |
Make arbitrary manipulations of process GIDs and supplementary GID list; |
| 302 |
.IP \[bu] |
| 303 |
forge GID when passing socket credentials via UNIX domain sockets; |
| 304 |
.IP \[bu] |
| 305 |
write a group ID mapping in a user namespace (see |
| 306 |
.BR user_namespaces (7)). |
| 307 |
.PD |
| 308 |
.RE |
| 309 |
.TP |
| 310 |
.BR CAP_SETFCAP " (since Linux 2.6.24)" |
| 311 |
Set arbitrary capabilities on a file. |
| 312 |
.IP |
| 313 |
.\" commit db2e718a47984b9d71ed890eb2ea36ecf150de18 |
| 314 |
Since Linux 5.12, |
| 315 |
this capability is also needed |
| 316 |
to map user ID 0 in a new user namespace; |
| 317 |
see |
| 318 |
.BR user_namespaces (7) |
| 319 |
for details. |
| 320 |
.TP |
| 321 |
.B CAP_SETPCAP |
| 322 |
If file capabilities are supported (i.e., since Linux 2.6.24): |
| 323 |
add any capability from the calling thread's bounding set |
| 324 |
to its inheritable set; |
| 325 |
drop capabilities from the bounding set (via |
| 326 |
.BR prctl (2) |
| 327 |
.BR PR_CAPBSET_DROP ); |
| 328 |
make changes to the |
| 329 |
.I securebits |
| 330 |
flags. |
| 331 |
.IP |
| 332 |
If file capabilities are not supported (i.e., before Linux 2.6.24): |
| 333 |
grant or remove any capability in the |
| 334 |
caller's permitted capability set to or from any other process. |
| 335 |
(This property of |
| 336 |
.B CAP_SETPCAP |
| 337 |
is not available when the kernel is configured to support |
| 338 |
file capabilities, since |
| 339 |
.B CAP_SETPCAP |
| 340 |
has entirely different semantics for such kernels.) |
| 341 |
.TP |
| 342 |
.B CAP_SETUID |
| 343 |
.RS |
| 344 |
.PD 0 |
| 345 |
.IP \[bu] 3 |
| 346 |
Make arbitrary manipulations of process UIDs |
| 347 |
.RB ( setuid (2), |
| 348 |
.BR setreuid (2), |
| 349 |
.BR setresuid (2), |
| 350 |
.BR setfsuid (2)); |
| 351 |
.IP \[bu] |
| 352 |
forge UID when passing socket credentials via UNIX domain sockets; |
| 353 |
.IP \[bu] |
| 354 |
write a user ID mapping in a user namespace (see |
| 355 |
.BR user_namespaces (7)). |
| 356 |
.PD |
| 357 |
.RE |
| 358 |
.\" FIXME CAP_SETUID also an effect in exec(); document this. |
| 359 |
.TP |
| 360 |
.B CAP_SYS_ADMIN |
| 361 |
.IR Note : |
| 362 |
this capability is overloaded; |
| 363 |
see |
| 364 |
.I Notes to kernel developers |
| 365 |
below. |
| 366 |
.IP |
| 367 |
.PD 0 |
| 368 |
.RS |
| 369 |
.IP \[bu] 3 |
| 370 |
Perform a range of system administration operations including: |
| 371 |
.BR quotactl (2), |
| 372 |
.BR mount (2), |
| 373 |
.BR umount (2), |
| 374 |
.BR pivot_root (2), |
| 375 |
.BR swapon (2), |
| 376 |
.BR swapoff (2), |
| 377 |
.BR sethostname (2), |
| 378 |
and |
| 379 |
.BR setdomainname (2); |
| 380 |
.IP \[bu] |
| 381 |
perform privileged |
| 382 |
.BR syslog (2) |
| 383 |
operations (since Linux 2.6.37, |
| 384 |
.B CAP_SYSLOG |
| 385 |
should be used to permit such operations); |
| 386 |
.IP \[bu] |
| 387 |
perform |
| 388 |
.B VM86_REQUEST_IRQ |
| 389 |
.BR vm86 (2) |
| 390 |
command; |
| 391 |
.IP \[bu] |
| 392 |
access the same checkpoint/restore functionality that is governed by |
| 393 |
.B CAP_CHECKPOINT_RESTORE |
| 394 |
(but the latter, weaker capability is preferred for accessing |
| 395 |
that functionality). |
| 396 |
.IP \[bu] |
| 397 |
perform the same BPF operations as are governed by |
| 398 |
.B CAP_BPF |
| 399 |
(but the latter, weaker capability is preferred for accessing |
| 400 |
that functionality). |
| 401 |
.IP \[bu] |
| 402 |
employ the same performance monitoring mechanisms as are governed by |
| 403 |
.B CAP_PERFMON |
| 404 |
(but the latter, weaker capability is preferred for accessing |
| 405 |
that functionality). |
| 406 |
.IP \[bu] |
| 407 |
perform |
| 408 |
.B IPC_SET |
| 409 |
and |
| 410 |
.B IPC_RMID |
| 411 |
operations on arbitrary System V IPC objects; |
| 412 |
.IP \[bu] |
| 413 |
override |
| 414 |
.B RLIMIT_NPROC |
| 415 |
resource limit; |
| 416 |
.IP \[bu] |
| 417 |
perform operations on |
| 418 |
.I trusted |
| 419 |
and |
| 420 |
.I security |
| 421 |
extended attributes (see |
| 422 |
.BR xattr (7)); |
| 423 |
.IP \[bu] |
| 424 |
use |
| 425 |
.BR lookup_dcookie (2); |
| 426 |
.IP \[bu] |
| 427 |
use |
| 428 |
.BR ioprio_set (2) |
| 429 |
to assign |
| 430 |
.B IOPRIO_CLASS_RT |
| 431 |
and (before Linux 2.6.25) |
| 432 |
.B IOPRIO_CLASS_IDLE |
| 433 |
I/O scheduling classes; |
| 434 |
.IP \[bu] |
| 435 |
forge PID when passing socket credentials via UNIX domain sockets; |
| 436 |
.IP \[bu] |
| 437 |
exceed |
| 438 |
.IR /proc/sys/fs/file\-max , |
| 439 |
the system-wide limit on the number of open files, |
| 440 |
in system calls that open files (e.g., |
| 441 |
.BR accept (2), |
| 442 |
.BR execve (2), |
| 443 |
.BR open (2), |
| 444 |
.BR pipe (2)); |
| 445 |
.IP \[bu] |
| 446 |
employ |
| 447 |
.B CLONE_* |
| 448 |
flags that create new namespaces with |
| 449 |
.BR clone (2) |
| 450 |
and |
| 451 |
.BR unshare (2) |
| 452 |
(but, since Linux 3.8, |
| 453 |
creating user namespaces does not require any capability); |
| 454 |
.IP \[bu] |
| 455 |
access privileged |
| 456 |
.I perf |
| 457 |
event information; |
| 458 |
.IP \[bu] |
| 459 |
call |
| 460 |
.BR setns (2) |
| 461 |
(requires |
| 462 |
.B CAP_SYS_ADMIN |
| 463 |
in the |
| 464 |
.I target |
| 465 |
namespace); |
| 466 |
.IP \[bu] |
| 467 |
call |
| 468 |
.BR fanotify_init (2); |
| 469 |
.IP \[bu] |
| 470 |
perform privileged |
| 471 |
.B KEYCTL_CHOWN |
| 472 |
and |
| 473 |
.B KEYCTL_SETPERM |
| 474 |
.BR keyctl (2) |
| 475 |
operations; |
| 476 |
.IP \[bu] |
| 477 |
perform |
| 478 |
.BR madvise (2) |
| 479 |
.B MADV_HWPOISON |
| 480 |
operation; |
| 481 |
.IP \[bu] |
| 482 |
employ the |
| 483 |
.B TIOCSTI |
| 484 |
.BR ioctl (2) |
| 485 |
to insert characters into the input queue of a terminal other than |
| 486 |
the caller's controlling terminal; |
| 487 |
.IP \[bu] |
| 488 |
employ the obsolete |
| 489 |
.BR nfsservctl (2) |
| 490 |
system call; |
| 491 |
.IP \[bu] |
| 492 |
employ the obsolete |
| 493 |
.BR bdflush (2) |
| 494 |
system call; |
| 495 |
.IP \[bu] |
| 496 |
perform various privileged block-device |
| 497 |
.BR ioctl (2) |
| 498 |
operations; |
| 499 |
.IP \[bu] |
| 500 |
perform various privileged filesystem |
| 501 |
.BR ioctl (2) |
| 502 |
operations; |
| 503 |
.IP \[bu] |
| 504 |
perform privileged |
| 505 |
.BR ioctl (2) |
| 506 |
operations on the |
| 507 |
.I /dev/random |
| 508 |
device (see |
| 509 |
.BR random (4)); |
| 510 |
.IP \[bu] |
| 511 |
install a |
| 512 |
.BR seccomp (2) |
| 513 |
filter without first having to set the |
| 514 |
.I no_new_privs |
| 515 |
thread attribute; |
| 516 |
.IP \[bu] |
| 517 |
modify allow/deny rules for device control groups; |
| 518 |
.IP \[bu] |
| 519 |
employ the |
| 520 |
.BR ptrace (2) |
| 521 |
.B PTRACE_SECCOMP_GET_FILTER |
| 522 |
operation to dump tracee's seccomp filters; |
| 523 |
.IP \[bu] |
| 524 |
employ the |
| 525 |
.BR ptrace (2) |
| 526 |
.B PTRACE_SETOPTIONS |
| 527 |
operation to suspend the tracee's seccomp protections (i.e., the |
| 528 |
.B PTRACE_O_SUSPEND_SECCOMP |
| 529 |
flag); |
| 530 |
.IP \[bu] |
| 531 |
perform administrative operations on many device drivers; |
| 532 |
.IP \[bu] |
| 533 |
modify autogroup nice values by writing to |
| 534 |
.IR /proc/ pid /autogroup |
| 535 |
(see |
| 536 |
.BR sched (7)). |
| 537 |
.RE |
| 538 |
.PD |
| 539 |
.TP |
| 540 |
.B CAP_SYS_BOOT |
| 541 |
Use |
| 542 |
.BR reboot (2) |
| 543 |
and |
| 544 |
.BR kexec_load (2). |
| 545 |
.TP |
| 546 |
.B CAP_SYS_CHROOT |
| 547 |
.RS |
| 548 |
.PD 0 |
| 549 |
.IP \[bu] 3 |
| 550 |
Use |
| 551 |
.BR chroot (2); |
| 552 |
.IP \[bu] |
| 553 |
change mount namespaces using |
| 554 |
.BR setns (2). |
| 555 |
.PD |
| 556 |
.RE |
| 557 |
.TP |
| 558 |
.B CAP_SYS_MODULE |
| 559 |
.RS |
| 560 |
.PD 0 |
| 561 |
.IP \[bu] 3 |
| 562 |
Load and unload kernel modules |
| 563 |
(see |
| 564 |
.BR init_module (2) |
| 565 |
and |
| 566 |
.BR delete_module (2)); |
| 567 |
.IP \[bu] |
| 568 |
before Linux 2.6.25: |
| 569 |
drop capabilities from the system-wide capability bounding set. |
| 570 |
.PD |
| 571 |
.RE |
| 572 |
.TP |
| 573 |
.B CAP_SYS_NICE |
| 574 |
.PD 0 |
| 575 |
.RS |
| 576 |
.IP \[bu] 3 |
| 577 |
Lower the process nice value |
| 578 |
.RB ( nice (2), |
| 579 |
.BR setpriority (2)) |
| 580 |
and change the nice value for arbitrary processes; |
| 581 |
.IP \[bu] |
| 582 |
set real-time scheduling policies for calling process, |
| 583 |
and set scheduling policies and priorities for arbitrary processes |
| 584 |
.RB ( sched_setscheduler (2), |
| 585 |
.BR sched_setparam (2), |
| 586 |
.BR sched_setattr (2)); |
| 587 |
.IP \[bu] |
| 588 |
set CPU affinity for arbitrary processes |
| 589 |
.RB ( sched_setaffinity (2)); |
| 590 |
.IP \[bu] |
| 591 |
set I/O scheduling class and priority for arbitrary processes |
| 592 |
.RB ( ioprio_set (2)); |
| 593 |
.IP \[bu] |
| 594 |
apply |
| 595 |
.BR migrate_pages (2) |
| 596 |
to arbitrary processes and allow processes |
| 597 |
to be migrated to arbitrary nodes; |
| 598 |
.\" FIXME CAP_SYS_NICE also has the following effect for |
| 599 |
.\" migrate_pages(2): |
| 600 |
.\" do_migrate_pages(mm, &old, &new, |
| 601 |
.\" capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE); |
| 602 |
.\" |
| 603 |
.\" Document this. |
| 604 |
.IP \[bu] |
| 605 |
apply |
| 606 |
.BR move_pages (2) |
| 607 |
to arbitrary processes; |
| 608 |
.IP \[bu] |
| 609 |
use the |
| 610 |
.B MPOL_MF_MOVE_ALL |
| 611 |
flag with |
| 612 |
.BR mbind (2) |
| 613 |
and |
| 614 |
.BR move_pages (2). |
| 615 |
.RE |
| 616 |
.PD |
| 617 |
.TP |
| 618 |
.B CAP_SYS_PACCT |
| 619 |
Use |
| 620 |
.BR acct (2). |
| 621 |
.TP |
| 622 |
.B CAP_SYS_PTRACE |
| 623 |
.PD 0 |
| 624 |
.RS |
| 625 |
.IP \[bu] 3 |
| 626 |
Trace arbitrary processes using |
| 627 |
.BR ptrace (2); |
| 628 |
.IP \[bu] |
| 629 |
inspect sensitive information of other processes via |
| 630 |
.I /proc |
| 631 |
(e.g., reading |
| 632 |
.IR /proc/ pid /maps , |
| 633 |
.IR /proc/ pid /mem , |
| 634 |
or reading symbolic links |
| 635 |
.IR /proc/ pid /exe , |
| 636 |
.IR /proc/ pid /fd/* ); |
| 637 |
.IP \[bu] |
| 638 |
apply |
| 639 |
.BR get_robust_list (2) |
| 640 |
to arbitrary processes; |
| 641 |
.IP \[bu] |
| 642 |
transfer data to or from the memory of arbitrary processes using |
| 643 |
.BR process_vm_readv (2) |
| 644 |
and |
| 645 |
.BR process_vm_writev (2); |
| 646 |
.IP \[bu] |
| 647 |
inspect processes using |
| 648 |
.BR kcmp (2); |
| 649 |
.IP \[bu] |
| 650 |
perform other privileged process-inspection and debugging operations. |
| 651 |
(See uses of the |
| 652 |
.IR ptrace_may_access () |
| 653 |
kernel function.) |
| 654 |
.RE |
| 655 |
.PD |
| 656 |
.TP |
| 657 |
.B CAP_SYS_RAWIO |
| 658 |
.PD 0 |
| 659 |
.RS |
| 660 |
.IP \[bu] 3 |
| 661 |
Perform I/O port operations |
| 662 |
.RB ( iopl (2) |
| 663 |
and |
| 664 |
.BR ioperm (2)); |
| 665 |
.IP \[bu] |
| 666 |
access |
| 667 |
.IR /proc/kcore ; |
| 668 |
.IP \[bu] |
| 669 |
employ the |
| 670 |
.B FIBMAP |
| 671 |
.BR ioctl (2) |
| 672 |
operation; |
| 673 |
.IP \[bu] |
| 674 |
open devices for accessing x86 model-specific registers (MSRs, see |
| 675 |
.BR msr (4)); |
| 676 |
.IP \[bu] |
| 677 |
update |
| 678 |
.IR /proc/sys/vm/mmap_min_addr ; |
| 679 |
.IP \[bu] |
| 680 |
create memory mappings at addresses below the value specified by |
| 681 |
.IR /proc/sys/vm/mmap_min_addr ; |
| 682 |
.IP \[bu] |
| 683 |
map files in |
| 684 |
.IR /proc/bus/pci ; |
| 685 |
.IP \[bu] |
| 686 |
open |
| 687 |
.I /dev/mem |
| 688 |
and |
| 689 |
.IR /dev/kmem ; |
| 690 |
.IP \[bu] |
| 691 |
perform various SCSI device commands; |
| 692 |
.IP \[bu] |
| 693 |
perform certain operations on |
| 694 |
.BR hpsa (4) |
| 695 |
and |
| 696 |
.BR cciss (4) |
| 697 |
devices; |
| 698 |
.IP \[bu] |
| 699 |
perform a range of device-specific operations on other devices. |
| 700 |
.RE |
| 701 |
.PD |
| 702 |
.TP |
| 703 |
.B CAP_SYS_RESOURCE |
| 704 |
.PD 0 |
| 705 |
.RS |
| 706 |
.IP \[bu] 3 |
| 707 |
Use reserved space on ext2 filesystems; |
| 708 |
.IP \[bu] |
| 709 |
make |
| 710 |
.BR ioctl (2) |
| 711 |
calls controlling ext3 journaling; |
| 712 |
.IP \[bu] |
| 713 |
override disk quota limits; |
| 714 |
.IP \[bu] |
| 715 |
increase resource limits (see |
| 716 |
.BR setrlimit (2)); |
| 717 |
.IP \[bu] |
| 718 |
override |
| 719 |
.B RLIMIT_NPROC |
| 720 |
resource limit; |
| 721 |
.IP \[bu] |
| 722 |
override maximum number of consoles on console allocation; |
| 723 |
.IP \[bu] |
| 724 |
override maximum number of keymaps; |
| 725 |
.IP \[bu] |
| 726 |
allow more than 64hz interrupts from the real-time clock; |
| 727 |
.IP \[bu] |
| 728 |
raise |
| 729 |
.I msg_qbytes |
| 730 |
limit for a System V message queue above the limit in |
| 731 |
.I /proc/sys/kernel/msgmnb |
| 732 |
(see |
| 733 |
.BR msgop (2) |
| 734 |
and |
| 735 |
.BR msgctl (2)); |
| 736 |
.IP \[bu] |
| 737 |
allow the |
| 738 |
.B RLIMIT_NOFILE |
| 739 |
resource limit on the number of "in-flight" file descriptors |
| 740 |
to be bypassed when passing file descriptors to another process |
| 741 |
via a UNIX domain socket (see |
| 742 |
.BR unix (7)); |
| 743 |
.IP \[bu] |
| 744 |
override the |
| 745 |
.I /proc/sys/fs/pipe\-size\-max |
| 746 |
limit when setting the capacity of a pipe using the |
| 747 |
.B F_SETPIPE_SZ |
| 748 |
.BR fcntl (2) |
| 749 |
command; |
| 750 |
.IP \[bu] |
| 751 |
use |
| 752 |
.B F_SETPIPE_SZ |
| 753 |
to increase the capacity of a pipe above the limit specified by |
| 754 |
.IR /proc/sys/fs/pipe\-max\-size ; |
| 755 |
.IP \[bu] |
| 756 |
override |
| 757 |
.IR /proc/sys/fs/mqueue/queues_max , |
| 758 |
.IR /proc/sys/fs/mqueue/msg_max , |
| 759 |
and |
| 760 |
.I /proc/sys/fs/mqueue/msgsize_max |
| 761 |
limits when creating POSIX message queues (see |
| 762 |
.BR mq_overview (7)); |
| 763 |
.IP \[bu] |
| 764 |
employ the |
| 765 |
.BR prctl (2) |
| 766 |
.B PR_SET_MM |
| 767 |
operation; |
| 768 |
.IP \[bu] |
| 769 |
set |
| 770 |
.IR /proc/ pid /oom_score_adj |
| 771 |
to a value lower than the value last set by a process with |
| 772 |
.BR CAP_SYS_RESOURCE . |
| 773 |
.RE |
| 774 |
.PD |
| 775 |
.TP |
| 776 |
.B CAP_SYS_TIME |
| 777 |
Set system clock |
| 778 |
.RB ( settimeofday (2), |
| 779 |
.BR stime (2), |
| 780 |
.BR adjtimex (2)); |
| 781 |
set real-time (hardware) clock. |
| 782 |
.TP |
| 783 |
.B CAP_SYS_TTY_CONFIG |
| 784 |
Use |
| 785 |
.BR vhangup (2); |
| 786 |
employ various privileged |
| 787 |
.BR ioctl (2) |
| 788 |
operations on virtual terminals. |
| 789 |
.TP |
| 790 |
.BR CAP_SYSLOG " (since Linux 2.6.37)" |
| 791 |
.RS |
| 792 |
.PD 0 |
| 793 |
.IP \[bu] 3 |
| 794 |
Perform privileged |
| 795 |
.BR syslog (2) |
| 796 |
operations. |
| 797 |
See |
| 798 |
.BR syslog (2) |
| 799 |
for information on which operations require privilege. |
| 800 |
.IP \[bu] |
| 801 |
View kernel addresses exposed via |
| 802 |
.I /proc |
| 803 |
and other interfaces when |
| 804 |
.I /proc/sys/kernel/kptr_restrict |
| 805 |
has the value 1. |
| 806 |
(See the discussion of the |
| 807 |
.I kptr_restrict |
| 808 |
in |
| 809 |
.BR proc (5).) |
| 810 |
.PD |
| 811 |
.RE |
| 812 |
.TP |
| 813 |
.BR CAP_WAKE_ALARM " (since Linux 3.0)" |
| 814 |
Trigger something that will wake up the system (set |
| 815 |
.B CLOCK_REALTIME_ALARM |
| 816 |
and |
| 817 |
.B CLOCK_BOOTTIME_ALARM |
| 818 |
timers). |
| 819 |
.\" |
| 820 |
.SS Past and current implementation |
| 821 |
A full implementation of capabilities requires that: |
| 822 |
.IP \[bu] 3 |
| 823 |
For all privileged operations, |
| 824 |
the kernel must check whether the thread has the required |
| 825 |
capability in its effective set. |
| 826 |
.IP \[bu] |
| 827 |
The kernel must provide system calls allowing a thread's capability sets to |
| 828 |
be changed and retrieved. |
| 829 |
.IP \[bu] |
| 830 |
The filesystem must support attaching capabilities to an executable file, |
| 831 |
so that a process gains those capabilities when the file is executed. |
| 832 |
.P |
| 833 |
Before Linux 2.6.24, only the first two of these requirements are met; |
| 834 |
since Linux 2.6.24, all three requirements are met. |
| 835 |
.\" |
| 836 |
.SS Notes to kernel developers |
| 837 |
When adding a new kernel feature that should be governed by a capability, |
| 838 |
consider the following points. |
| 839 |
.IP \[bu] 3 |
| 840 |
The goal of capabilities is divide the power of superuser into pieces, |
| 841 |
such that if a program that has one or more capabilities is compromised, |
| 842 |
its power to do damage to the system would be less than the same program |
| 843 |
running with root privilege. |
| 844 |
.IP \[bu] |
| 845 |
You have the choice of either creating a new capability for your new feature, |
| 846 |
or associating the feature with one of the existing capabilities. |
| 847 |
In order to keep the set of capabilities to a manageable size, |
| 848 |
the latter option is preferable, |
| 849 |
unless there are compelling reasons to take the former option. |
| 850 |
(There is also a technical limit: |
| 851 |
the size of capability sets is currently limited to 64 bits.) |
| 852 |
.IP \[bu] |
| 853 |
To determine which existing capability might best be associated |
| 854 |
with your new feature, review the list of capabilities above in order |
| 855 |
to find a "silo" into which your new feature best fits. |
| 856 |
One approach to take is to determine if there are other features |
| 857 |
requiring capabilities that will always be used along with the new feature. |
| 858 |
If the new feature is useless without these other features, |
| 859 |
you should use the same capability as the other features. |
| 860 |
.IP \[bu] |
| 861 |
.I Don't |
| 862 |
choose |
| 863 |
.B CAP_SYS_ADMIN |
| 864 |
if you can possibly avoid it! |
| 865 |
A vast proportion of existing capability checks are associated |
| 866 |
with this capability (see the partial list above). |
| 867 |
It can plausibly be called "the new root", |
| 868 |
since on the one hand, it confers a wide range of powers, |
| 869 |
and on the other hand, |
| 870 |
its broad scope means that this is the capability |
| 871 |
that is required by many privileged programs. |
| 872 |
Don't make the problem worse. |
| 873 |
The only new features that should be associated with |
| 874 |
.B CAP_SYS_ADMIN |
| 875 |
are ones that |
| 876 |
.I closely |
| 877 |
match existing uses in that silo. |
| 878 |
.IP \[bu] |
| 879 |
If you have determined that it really is necessary to create |
| 880 |
a new capability for your feature, |
| 881 |
don't make or name it as a "single-use" capability. |
| 882 |
Thus, for example, the addition of the highly specific |
| 883 |
.B CAP_SYS_PACCT |
| 884 |
was probably a mistake. |
| 885 |
Instead, try to identify and name your new capability as a broader |
| 886 |
silo into which other related future use cases might fit. |
| 887 |
.\" |
| 888 |
.SS Thread capability sets |
| 889 |
Each thread has the following capability sets containing zero or more |
| 890 |
of the above capabilities: |
| 891 |
.TP |
| 892 |
.I Permitted |
| 893 |
This is a limiting superset for the effective |
| 894 |
capabilities that the thread may assume. |
| 895 |
It is also a limiting superset for the capabilities that |
| 896 |
may be added to the inheritable set by a thread that does not have the |
| 897 |
.B CAP_SETPCAP |
| 898 |
capability in its effective set. |
| 899 |
.IP |
| 900 |
If a thread drops a capability from its permitted set, |
| 901 |
it can never reacquire that capability (unless it |
| 902 |
.BR execve (2)s |
| 903 |
either a set-user-ID-root program, or |
| 904 |
a program whose associated file capabilities grant that capability). |
| 905 |
.TP |
| 906 |
.I Inheritable |
| 907 |
This is a set of capabilities preserved across an |
| 908 |
.BR execve (2). |
| 909 |
Inheritable capabilities remain inheritable when executing any program, |
| 910 |
and inheritable capabilities are added to the permitted set when executing |
| 911 |
a program that has the corresponding bits set in the file inheritable set. |
| 912 |
.IP |
| 913 |
Because inheritable capabilities are not generally preserved across |
| 914 |
.BR execve (2) |
| 915 |
when running as a non-root user, applications that wish to run helper |
| 916 |
programs with elevated capabilities should consider using |
| 917 |
ambient capabilities, described below. |
| 918 |
.TP |
| 919 |
.I Effective |
| 920 |
This is the set of capabilities used by the kernel to |
| 921 |
perform permission checks for the thread. |
| 922 |
.TP |
| 923 |
.IR Bounding " (per-thread since Linux 2.6.25)" |
| 924 |
The capability bounding set is a mechanism that can be used |
| 925 |
to limit the capabilities that are gained during |
| 926 |
.BR execve (2). |
| 927 |
.IP |
| 928 |
Since Linux 2.6.25, this is a per-thread capability set. |
| 929 |
In older kernels, the capability bounding set was a system wide attribute |
| 930 |
shared by all threads on the system. |
| 931 |
.IP |
| 932 |
For more details, see |
| 933 |
.I Capability bounding set |
| 934 |
below. |
| 935 |
.TP |
| 936 |
.IR Ambient " (since Linux 4.3)" |
| 937 |
.\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08 |
| 938 |
This is a set of capabilities that are preserved across an |
| 939 |
.BR execve (2) |
| 940 |
of a program that is not privileged. |
| 941 |
The ambient capability set obeys the invariant that no capability |
| 942 |
can ever be ambient if it is not both permitted and inheritable. |
| 943 |
.IP |
| 944 |
The ambient capability set can be directly modified using |
| 945 |
.BR prctl (2). |
| 946 |
Ambient capabilities are automatically lowered if either of |
| 947 |
the corresponding permitted or inheritable capabilities is lowered. |
| 948 |
.IP |
| 949 |
Executing a program that changes UID or GID due to the |
| 950 |
set-user-ID or set-group-ID bits or executing a program that has |
| 951 |
any file capabilities set will clear the ambient set. |
| 952 |
Ambient capabilities are added to the permitted set and |
| 953 |
assigned to the effective set when |
| 954 |
.BR execve (2) |
| 955 |
is called. |
| 956 |
If ambient capabilities cause a process's permitted and effective |
| 957 |
capabilities to increase during an |
| 958 |
.BR execve (2), |
| 959 |
this does not trigger the secure-execution mode described in |
| 960 |
.BR ld.so (8). |
| 961 |
.P |
| 962 |
A child created via |
| 963 |
.BR fork (2) |
| 964 |
inherits copies of its parent's capability sets. |
| 965 |
For details on how |
| 966 |
.BR execve (2) |
| 967 |
affects capabilities, see |
| 968 |
.I Transformation of capabilities during execve() |
| 969 |
below. |
| 970 |
.P |
| 971 |
Using |
| 972 |
.BR capset (2), |
| 973 |
a thread may manipulate its own capability sets; |
| 974 |
see |
| 975 |
.I Programmatically adjusting capability sets |
| 976 |
below. |
| 977 |
.P |
| 978 |
Since Linux 3.2, the file |
| 979 |
.I /proc/sys/kernel/cap_last_cap |
| 980 |
.\" commit 73efc0394e148d0e15583e13712637831f926720 |
| 981 |
exposes the numerical value of the highest capability |
| 982 |
supported by the running kernel; |
| 983 |
this can be used to determine the highest bit |
| 984 |
that may be set in a capability set. |
| 985 |
.\" |
| 986 |
.SS File capabilities |
| 987 |
Since Linux 2.6.24, the kernel supports |
| 988 |
associating capability sets with an executable file using |
| 989 |
.BR setcap (8). |
| 990 |
The file capability sets are stored in an extended attribute (see |
| 991 |
.BR setxattr (2) |
| 992 |
and |
| 993 |
.BR xattr (7)) |
| 994 |
named |
| 995 |
.IR "security.capability" . |
| 996 |
Writing to this extended attribute requires the |
| 997 |
.B CAP_SETFCAP |
| 998 |
capability. |
| 999 |
The file capability sets, |
| 1000 |
in conjunction with the capability sets of the thread, |
| 1001 |
determine the capabilities of a thread after an |
| 1002 |
.BR execve (2). |
| 1003 |
.P |
| 1004 |
The three file capability sets are: |
| 1005 |
.TP |
| 1006 |
.IR Permitted " (formerly known as " forced ): |
| 1007 |
These capabilities are automatically permitted to the thread, |
| 1008 |
regardless of the thread's inheritable capabilities. |
| 1009 |
.TP |
| 1010 |
.IR Inheritable " (formerly known as " allowed ): |
| 1011 |
This set is ANDed with the thread's inheritable set to determine which |
| 1012 |
inheritable capabilities are enabled in the permitted set of |
| 1013 |
the thread after the |
| 1014 |
.BR execve (2). |
| 1015 |
.TP |
| 1016 |
.IR Effective : |
| 1017 |
This is not a set, but rather just a single bit. |
| 1018 |
If this bit is set, then during an |
| 1019 |
.BR execve (2) |
| 1020 |
all of the new permitted capabilities for the thread are |
| 1021 |
also raised in the effective set. |
| 1022 |
If this bit is not set, then after an |
| 1023 |
.BR execve (2), |
| 1024 |
none of the new permitted capabilities is in the new effective set. |
| 1025 |
.IP |
| 1026 |
Enabling the file effective capability bit implies |
| 1027 |
that any file permitted or inheritable capability that causes a |
| 1028 |
thread to acquire the corresponding permitted capability during an |
| 1029 |
.BR execve (2) |
| 1030 |
(see |
| 1031 |
.I Transformation of capabilities during execve() |
| 1032 |
below) will also acquire that |
| 1033 |
capability in its effective set. |
| 1034 |
Therefore, when assigning capabilities to a file |
| 1035 |
.RB ( setcap (8), |
| 1036 |
.BR cap_set_file (3), |
| 1037 |
.BR cap_set_fd (3)), |
| 1038 |
if we specify the effective flag as being enabled for any capability, |
| 1039 |
then the effective flag must also be specified as enabled |
| 1040 |
for all other capabilities for which the corresponding permitted or |
| 1041 |
inheritable flag is enabled. |
| 1042 |
.\" |
| 1043 |
.SS File capability extended attribute versioning |
| 1044 |
To allow extensibility, |
| 1045 |
the kernel supports a scheme to encode a version number inside the |
| 1046 |
.I security.capability |
| 1047 |
extended attribute that is used to implement file capabilities. |
| 1048 |
These version numbers are internal to the implementation, |
| 1049 |
and not directly visible to user-space applications. |
| 1050 |
To date, the following versions are supported: |
| 1051 |
.TP |
| 1052 |
.B VFS_CAP_REVISION_1 |
| 1053 |
This was the original file capability implementation, |
| 1054 |
which supported 32-bit masks for file capabilities. |
| 1055 |
.TP |
| 1056 |
.BR VFS_CAP_REVISION_2 " (since Linux 2.6.25)" |
| 1057 |
.\" commit e338d263a76af78fe8f38a72131188b58fceb591 |
| 1058 |
This version allows for file capability masks that are 64 bits in size, |
| 1059 |
and was necessary as the number of supported capabilities grew beyond 32. |
| 1060 |
The kernel transparently continues to support the execution of files |
| 1061 |
that have 32-bit version 1 capability masks, |
| 1062 |
but when adding capabilities to files that did not previously |
| 1063 |
have capabilities, or modifying the capabilities of existing files, |
| 1064 |
it automatically uses the version 2 scheme |
| 1065 |
(or possibly the version 3 scheme, as described below). |
| 1066 |
.TP |
| 1067 |
.BR VFS_CAP_REVISION_3 " (since Linux 4.14)" |
| 1068 |
.\" commit 8db6c34f1dbc8e06aa016a9b829b06902c3e1340 |
| 1069 |
Version 3 file capabilities are provided |
| 1070 |
to support namespaced file capabilities (described below). |
| 1071 |
.IP |
| 1072 |
As with version 2 file capabilities, |
| 1073 |
version 3 capability masks are 64 bits in size. |
| 1074 |
But in addition, the root user ID of namespace is encoded in the |
| 1075 |
.I security.capability |
| 1076 |
extended attribute. |
| 1077 |
(A namespace's root user ID is the value that user ID 0 |
| 1078 |
inside that namespace maps to in the initial user namespace.) |
| 1079 |
.IP |
| 1080 |
Version 3 file capabilities are designed to coexist |
| 1081 |
with version 2 capabilities; |
| 1082 |
that is, on a modern Linux system, |
| 1083 |
there may be some files with version 2 capabilities |
| 1084 |
while others have version 3 capabilities. |
| 1085 |
.P |
| 1086 |
Before Linux 4.14, |
| 1087 |
the only kind of file capability extended attribute |
| 1088 |
that could be attached to a file was a |
| 1089 |
.B VFS_CAP_REVISION_2 |
| 1090 |
attribute. |
| 1091 |
Since Linux 4.14, |
| 1092 |
the version of the |
| 1093 |
.I security.capability |
| 1094 |
extended attribute that is attached to a file |
| 1095 |
depends on the circumstances in which the attribute was created. |
| 1096 |
.P |
| 1097 |
Starting with Linux 4.14, a |
| 1098 |
.I security.capability |
| 1099 |
extended attribute is automatically created as (or converted to) |
| 1100 |
a version 3 |
| 1101 |
.RB ( VFS_CAP_REVISION_3 ) |
| 1102 |
attribute if both of the following are true: |
| 1103 |
.IP \[bu] 3 |
| 1104 |
The thread writing the attribute resides in a noninitial user namespace. |
| 1105 |
(More precisely: the thread resides in a user namespace other |
| 1106 |
than the one from which the underlying filesystem was mounted.) |
| 1107 |
.IP \[bu] |
| 1108 |
The thread has the |
| 1109 |
.B CAP_SETFCAP |
| 1110 |
capability over the file inode, |
| 1111 |
meaning that (a) the thread has the |
| 1112 |
.B CAP_SETFCAP |
| 1113 |
capability in its own user namespace; |
| 1114 |
and (b) the UID and GID of the file inode have mappings in |
| 1115 |
the writer's user namespace. |
| 1116 |
.P |
| 1117 |
When a |
| 1118 |
.B VFS_CAP_REVISION_3 |
| 1119 |
.I security.capability |
| 1120 |
extended attribute is created, the root user ID of the creating thread's |
| 1121 |
user namespace is saved in the extended attribute. |
| 1122 |
.P |
| 1123 |
By contrast, creating or modifying a |
| 1124 |
.I security.capability |
| 1125 |
extended attribute from a privileged |
| 1126 |
.RB ( CAP_SETFCAP ) |
| 1127 |
thread that resides in the |
| 1128 |
namespace where the underlying filesystem was mounted |
| 1129 |
(this normally means the initial user namespace) |
| 1130 |
automatically results in the creation of a version 2 |
| 1131 |
.RB ( VFS_CAP_REVISION_2 ) |
| 1132 |
attribute. |
| 1133 |
.P |
| 1134 |
Note that the creation of a version 3 |
| 1135 |
.I security.capability |
| 1136 |
extended attribute is automatic. |
| 1137 |
That is to say, when a user-space application writes |
| 1138 |
.RB ( setxattr (2)) |
| 1139 |
a |
| 1140 |
.I security.capability |
| 1141 |
attribute in the version 2 format, |
| 1142 |
the kernel will automatically create a version 3 attribute |
| 1143 |
if the attribute is created in the circumstances described above. |
| 1144 |
Correspondingly, when a version 3 |
| 1145 |
.I security.capability |
| 1146 |
attribute is retrieved |
| 1147 |
.RB ( getxattr (2)) |
| 1148 |
by a process that resides inside a user namespace that was created by the |
| 1149 |
root user ID (or a descendant of that user namespace), |
| 1150 |
the returned attribute is (automatically) |
| 1151 |
simplified to appear as a version 2 attribute |
| 1152 |
(i.e., the returned value is the size of a version 2 attribute and does |
| 1153 |
not include the root user ID). |
| 1154 |
These automatic translations mean that no changes are required to |
| 1155 |
user-space tools (e.g., |
| 1156 |
.BR setcap (1) |
| 1157 |
and |
| 1158 |
.BR getcap (1)) |
| 1159 |
in order for those tools to be used to create and retrieve version 3 |
| 1160 |
.I security.capability |
| 1161 |
attributes. |
| 1162 |
.P |
| 1163 |
Note that a file can have either a version 2 or a version 3 |
| 1164 |
.I security.capability |
| 1165 |
extended attribute associated with it, but not both: |
| 1166 |
creation or modification of the |
| 1167 |
.I security.capability |
| 1168 |
extended attribute will automatically modify the version |
| 1169 |
according to the circumstances in which the extended attribute is |
| 1170 |
created or modified. |
| 1171 |
.\" |
| 1172 |
.SS Transformation of capabilities during execve() |
| 1173 |
During an |
| 1174 |
.BR execve (2), |
| 1175 |
the kernel calculates the new capabilities of |
| 1176 |
the process using the following algorithm: |
| 1177 |
.P |
| 1178 |
.in +4n |
| 1179 |
.EX |
| 1180 |
P'(ambient) = (file is privileged) ? 0 : P(ambient) |
| 1181 |
\& |
| 1182 |
P'(permitted) = (P(inheritable) & F(inheritable)) | |
| 1183 |
(F(permitted) & P(bounding)) | P'(ambient) |
| 1184 |
\& |
| 1185 |
P'(effective) = F(effective) ? P'(permitted) : P'(ambient) |
| 1186 |
\& |
| 1187 |
P'(inheritable) = P(inheritable) [i.e., unchanged] |
| 1188 |
\& |
| 1189 |
P'(bounding) = P(bounding) [i.e., unchanged] |
| 1190 |
.EE |
| 1191 |
.in |
| 1192 |
.P |
| 1193 |
where: |
| 1194 |
.RS 4 |
| 1195 |
.TP |
| 1196 |
P() |
| 1197 |
denotes the value of a thread capability set before the |
| 1198 |
.BR execve (2) |
| 1199 |
.TP |
| 1200 |
P'() |
| 1201 |
denotes the value of a thread capability set after the |
| 1202 |
.BR execve (2) |
| 1203 |
.TP |
| 1204 |
F() |
| 1205 |
denotes a file capability set |
| 1206 |
.RE |
| 1207 |
.P |
| 1208 |
Note the following details relating to the above capability |
| 1209 |
transformation rules: |
| 1210 |
.IP \[bu] 3 |
| 1211 |
The ambient capability set is present only since Linux 4.3. |
| 1212 |
When determining the transformation of the ambient set during |
| 1213 |
.BR execve (2), |
| 1214 |
a privileged file is one that has capabilities or |
| 1215 |
has the set-user-ID or set-group-ID bit set. |
| 1216 |
.IP \[bu] |
| 1217 |
Prior to Linux 2.6.25, |
| 1218 |
the bounding set was a system-wide attribute shared by all threads. |
| 1219 |
That system-wide value was employed to calculate the new permitted set during |
| 1220 |
.BR execve (2) |
| 1221 |
in the same manner as shown above for |
| 1222 |
.IR P(bounding) . |
| 1223 |
.P |
| 1224 |
.IR Note : |
| 1225 |
during the capability transitions described above, |
| 1226 |
file capabilities may be ignored (treated as empty) |
| 1227 |
for the same reasons that the set-user-ID and set-group-ID bits are ignored; |
| 1228 |
see |
| 1229 |
.BR execve (2). |
| 1230 |
File capabilities are similarly ignored if the kernel was booted with the |
| 1231 |
.I no_file_caps |
| 1232 |
option. |
| 1233 |
.P |
| 1234 |
.IR Note : |
| 1235 |
according to the rules above, |
| 1236 |
if a process with nonzero user IDs performs an |
| 1237 |
.BR execve (2) |
| 1238 |
then any capabilities that are present in |
| 1239 |
its permitted and effective sets will be cleared. |
| 1240 |
For the treatment of capabilities when a process with a |
| 1241 |
user ID of zero performs an |
| 1242 |
.BR execve (2), |
| 1243 |
see |
| 1244 |
.I Capabilities and execution of programs by root |
| 1245 |
below. |
| 1246 |
.\" |
| 1247 |
.SS Safety checking for capability-dumb binaries |
| 1248 |
A capability-dumb binary is an application that has been |
| 1249 |
marked to have file capabilities, but has not been converted to use the |
| 1250 |
.BR libcap (3) |
| 1251 |
API to manipulate its capabilities. |
| 1252 |
(In other words, this is a traditional set-user-ID-root program |
| 1253 |
that has been switched to use file capabilities, |
| 1254 |
but whose code has not been modified to understand capabilities.) |
| 1255 |
For such applications, |
| 1256 |
the effective capability bit is set on the file, |
| 1257 |
so that the file permitted capabilities are automatically |
| 1258 |
enabled in the process effective set when executing the file. |
| 1259 |
The kernel recognizes a file which has the effective capability bit set |
| 1260 |
as capability-dumb for the purpose of the check described here. |
| 1261 |
.P |
| 1262 |
When executing a capability-dumb binary, |
| 1263 |
the kernel checks if the process obtained all permitted capabilities |
| 1264 |
that were specified in the file permitted set, |
| 1265 |
after the capability transformations described above have been performed. |
| 1266 |
(The typical reason why this might |
| 1267 |
.I not |
| 1268 |
occur is that the capability bounding set masked out some |
| 1269 |
of the capabilities in the file permitted set.) |
| 1270 |
If the process did not obtain the full set of |
| 1271 |
file permitted capabilities, then |
| 1272 |
.BR execve (2) |
| 1273 |
fails with the error |
| 1274 |
.BR EPERM . |
| 1275 |
This prevents possible security risks that could arise when |
| 1276 |
a capability-dumb application is executed with less privilege than it needs. |
| 1277 |
Note that, by definition, |
| 1278 |
the application could not itself recognize this problem, |
| 1279 |
since it does not employ the |
| 1280 |
.BR libcap (3) |
| 1281 |
API. |
| 1282 |
.\" |
| 1283 |
.SS Capabilities and execution of programs by root |
| 1284 |
.\" See cap_bprm_set_creds(), bprm_caps_from_vfs_cap() and |
| 1285 |
.\" handle_privileged_root() in security/commoncap.c (Linux 5.0 source) |
| 1286 |
In order to mirror traditional UNIX semantics, |
| 1287 |
the kernel performs special treatment of file capabilities when |
| 1288 |
a process with UID 0 (root) executes a program and |
| 1289 |
when a set-user-ID-root program is executed. |
| 1290 |
.P |
| 1291 |
After having performed any changes to the process effective ID that |
| 1292 |
were triggered by the set-user-ID mode bit of the binary\[em]e.g., |
| 1293 |
switching the effective user ID to 0 (root) because |
| 1294 |
a set-user-ID-root program was executed\[em]the |
| 1295 |
kernel calculates the file capability sets as follows: |
| 1296 |
.IP (1) 5 |
| 1297 |
If the real or effective user ID of the process is 0 (root), |
| 1298 |
then the file inheritable and permitted sets are ignored; |
| 1299 |
instead they are notionally considered to be all ones |
| 1300 |
(i.e., all capabilities enabled). |
| 1301 |
(There is one exception to this behavior, described in |
| 1302 |
.I Set-user-ID-root programs that have file capabilities |
| 1303 |
below.) |
| 1304 |
.IP (2) |
| 1305 |
If the effective user ID of the process is 0 (root) or |
| 1306 |
the file effective bit is in fact enabled, |
| 1307 |
then the file effective bit is notionally defined to be one (enabled). |
| 1308 |
.P |
| 1309 |
These notional values for the file's capability sets are then used |
| 1310 |
as described above to calculate the transformation of the process's |
| 1311 |
capabilities during |
| 1312 |
.BR execve (2). |
| 1313 |
.P |
| 1314 |
Thus, when a process with nonzero UIDs |
| 1315 |
.BR execve (2)s |
| 1316 |
a set-user-ID-root program that does not have capabilities attached, |
| 1317 |
or when a process whose real and effective UIDs are zero |
| 1318 |
.BR execve (2)s |
| 1319 |
a program, the calculation of the process's new |
| 1320 |
permitted capabilities simplifies to: |
| 1321 |
.P |
| 1322 |
.in +4n |
| 1323 |
.EX |
| 1324 |
P'(permitted) = P(inheritable) | P(bounding) |
| 1325 |
\& |
| 1326 |
P'(effective) = P'(permitted) |
| 1327 |
.EE |
| 1328 |
.in |
| 1329 |
.P |
| 1330 |
Consequently, the process gains all capabilities in its permitted and |
| 1331 |
effective capability sets, |
| 1332 |
except those masked out by the capability bounding set. |
| 1333 |
(In the calculation of P'(permitted), |
| 1334 |
the P'(ambient) term can be simplified away because it is by |
| 1335 |
definition a proper subset of P(inheritable).) |
| 1336 |
.P |
| 1337 |
The special treatments of user ID 0 (root) described in this subsection |
| 1338 |
can be disabled using the securebits mechanism described below. |
| 1339 |
.\" |
| 1340 |
.\" |
| 1341 |
.SS Set-user-ID-root programs that have file capabilities |
| 1342 |
There is one exception to the behavior described in |
| 1343 |
.I Capabilities and execution of programs by root |
| 1344 |
above. |
| 1345 |
If (a) the binary that is being executed has capabilities attached and |
| 1346 |
(b) the real user ID of the process is |
| 1347 |
.I not |
| 1348 |
0 (root) and |
| 1349 |
(c) the effective user ID of the process |
| 1350 |
.I is |
| 1351 |
0 (root), then the file capability bits are honored |
| 1352 |
(i.e., they are not notionally considered to be all ones). |
| 1353 |
The usual way in which this situation can arise is when executing |
| 1354 |
a set-UID-root program that also has file capabilities. |
| 1355 |
When such a program is executed, |
| 1356 |
the process gains just the capabilities granted by the program |
| 1357 |
(i.e., not all capabilities, |
| 1358 |
as would occur when executing a set-user-ID-root program |
| 1359 |
that does not have any associated file capabilities). |
| 1360 |
.P |
| 1361 |
Note that one can assign empty capability sets to a program file, |
| 1362 |
and thus it is possible to create a set-user-ID-root program that |
| 1363 |
changes the effective and saved set-user-ID of the process |
| 1364 |
that executes the program to 0, |
| 1365 |
but confers no capabilities to that process. |
| 1366 |
.\" |
| 1367 |
.SS Capability bounding set |
| 1368 |
The capability bounding set is a security mechanism that can be used |
| 1369 |
to limit the capabilities that can be gained during an |
| 1370 |
.BR execve (2). |
| 1371 |
The bounding set is used in the following ways: |
| 1372 |
.IP \[bu] 3 |
| 1373 |
During an |
| 1374 |
.BR execve (2), |
| 1375 |
the capability bounding set is ANDed with the file permitted |
| 1376 |
capability set, and the result of this operation is assigned to the |
| 1377 |
thread's permitted capability set. |
| 1378 |
The capability bounding set thus places a limit on the permitted |
| 1379 |
capabilities that may be granted by an executable file. |
| 1380 |
.IP \[bu] |
| 1381 |
(Since Linux 2.6.25) |
| 1382 |
The capability bounding set acts as a limiting superset for |
| 1383 |
the capabilities that a thread can add to its inheritable set using |
| 1384 |
.BR capset (2). |
| 1385 |
This means that if a capability is not in the bounding set, |
| 1386 |
then a thread can't add this capability to its |
| 1387 |
inheritable set, even if it was in its permitted capabilities, |
| 1388 |
and thereby cannot have this capability preserved in its |
| 1389 |
permitted set when it |
| 1390 |
.BR execve (2)s |
| 1391 |
a file that has the capability in its inheritable set. |
| 1392 |
.P |
| 1393 |
Note that the bounding set masks the file permitted capabilities, |
| 1394 |
but not the inheritable capabilities. |
| 1395 |
If a thread maintains a capability in its inheritable set |
| 1396 |
that is not in its bounding set, |
| 1397 |
then it can still gain that capability in its permitted set |
| 1398 |
by executing a file that has the capability in its inheritable set. |
| 1399 |
.P |
| 1400 |
Depending on the kernel version, the capability bounding set is either |
| 1401 |
a system-wide attribute, or a per-process attribute. |
| 1402 |
.P |
| 1403 |
.B "Capability bounding set from Linux 2.6.25 onward" |
| 1404 |
.P |
| 1405 |
From Linux 2.6.25, the |
| 1406 |
.I "capability bounding set" |
| 1407 |
is a per-thread attribute. |
| 1408 |
(The system-wide capability bounding set described below no longer exists.) |
| 1409 |
.P |
| 1410 |
The bounding set is inherited at |
| 1411 |
.BR fork (2) |
| 1412 |
from the thread's parent, and is preserved across an |
| 1413 |
.BR execve (2). |
| 1414 |
.P |
| 1415 |
A thread may remove capabilities from its capability bounding set using the |
| 1416 |
.BR prctl (2) |
| 1417 |
.B PR_CAPBSET_DROP |
| 1418 |
operation, provided it has the |
| 1419 |
.B CAP_SETPCAP |
| 1420 |
capability. |
| 1421 |
Once a capability has been dropped from the bounding set, |
| 1422 |
it cannot be restored to that set. |
| 1423 |
A thread can determine if a capability is in its bounding set using the |
| 1424 |
.BR prctl (2) |
| 1425 |
.B PR_CAPBSET_READ |
| 1426 |
operation. |
| 1427 |
.P |
| 1428 |
Removing capabilities from the bounding set is supported only if file |
| 1429 |
capabilities are compiled into the kernel. |
| 1430 |
Before Linux 2.6.33, |
| 1431 |
file capabilities were an optional feature configurable via the |
| 1432 |
.B CONFIG_SECURITY_FILE_CAPABILITIES |
| 1433 |
option. |
| 1434 |
Since Linux 2.6.33, |
| 1435 |
.\" commit b3a222e52e4d4be77cc4520a57af1a4a0d8222d1 |
| 1436 |
the configuration option has been removed |
| 1437 |
and file capabilities are always part of the kernel. |
| 1438 |
When file capabilities are compiled into the kernel, the |
| 1439 |
.B init |
| 1440 |
process (the ancestor of all processes) begins with a full bounding set. |
| 1441 |
If file capabilities are not compiled into the kernel, then |
| 1442 |
.B init |
| 1443 |
begins with a full bounding set minus |
| 1444 |
.BR CAP_SETPCAP , |
| 1445 |
because this capability has a different meaning when there are |
| 1446 |
no file capabilities. |
| 1447 |
.P |
| 1448 |
Removing a capability from the bounding set does not remove it |
| 1449 |
from the thread's inheritable set. |
| 1450 |
However it does prevent the capability from being added |
| 1451 |
back into the thread's inheritable set in the future. |
| 1452 |
.P |
| 1453 |
.B "Capability bounding set prior to Linux 2.6.25" |
| 1454 |
.P |
| 1455 |
Before Linux 2.6.25, the capability bounding set is a system-wide |
| 1456 |
attribute that affects all threads on the system. |
| 1457 |
The bounding set is accessible via the file |
| 1458 |
.IR /proc/sys/kernel/cap\-bound . |
| 1459 |
(Confusingly, this bit mask parameter is expressed as a |
| 1460 |
signed decimal number in |
| 1461 |
.IR /proc/sys/kernel/cap\-bound .) |
| 1462 |
.P |
| 1463 |
Only the |
| 1464 |
.B init |
| 1465 |
process may set capabilities in the capability bounding set; |
| 1466 |
other than that, the superuser (more precisely: a process with the |
| 1467 |
.B CAP_SYS_MODULE |
| 1468 |
capability) may only clear capabilities from this set. |
| 1469 |
.P |
| 1470 |
On a standard system the capability bounding set always masks out the |
| 1471 |
.B CAP_SETPCAP |
| 1472 |
capability. |
| 1473 |
To remove this restriction (dangerous!), modify the definition of |
| 1474 |
.B CAP_INIT_EFF_SET |
| 1475 |
in |
| 1476 |
.I include/linux/capability.h |
| 1477 |
and rebuild the kernel. |
| 1478 |
.P |
| 1479 |
The system-wide capability bounding set feature was added |
| 1480 |
to Linux 2.2.11. |
| 1481 |
.\" |
| 1482 |
.\" |
| 1483 |
.\" |
| 1484 |
.SS Effect of user ID changes on capabilities |
| 1485 |
To preserve the traditional semantics for transitions between |
| 1486 |
0 and nonzero user IDs, |
| 1487 |
the kernel makes the following changes to a thread's capability |
| 1488 |
sets on changes to the thread's real, effective, saved set, |
| 1489 |
and filesystem user IDs (using |
| 1490 |
.BR setuid (2), |
| 1491 |
.BR setresuid (2), |
| 1492 |
or similar): |
| 1493 |
.IP \[bu] 3 |
| 1494 |
If one or more of the real, effective, or saved set user IDs |
| 1495 |
was previously 0, and as a result of the UID changes all of these IDs |
| 1496 |
have a nonzero value, |
| 1497 |
then all capabilities are cleared from the permitted, effective, and ambient |
| 1498 |
capability sets. |
| 1499 |
.IP \[bu] |
| 1500 |
If the effective user ID is changed from 0 to nonzero, |
| 1501 |
then all capabilities are cleared from the effective set. |
| 1502 |
.IP \[bu] |
| 1503 |
If the effective user ID is changed from nonzero to 0, |
| 1504 |
then the permitted set is copied to the effective set. |
| 1505 |
.IP \[bu] |
| 1506 |
If the filesystem user ID is changed from 0 to nonzero (see |
| 1507 |
.BR setfsuid (2)), |
| 1508 |
then the following capabilities are cleared from the effective set: |
| 1509 |
.BR CAP_CHOWN , |
| 1510 |
.BR CAP_DAC_OVERRIDE , |
| 1511 |
.BR CAP_DAC_READ_SEARCH , |
| 1512 |
.BR CAP_FOWNER , |
| 1513 |
.BR CAP_FSETID , |
| 1514 |
.B CAP_LINUX_IMMUTABLE |
| 1515 |
(since Linux 2.6.30), |
| 1516 |
.BR CAP_MAC_OVERRIDE , |
| 1517 |
and |
| 1518 |
.B CAP_MKNOD |
| 1519 |
(since Linux 2.6.30). |
| 1520 |
If the filesystem UID is changed from nonzero to 0, |
| 1521 |
then any of these capabilities that are enabled in the permitted set |
| 1522 |
are enabled in the effective set. |
| 1523 |
.P |
| 1524 |
If a thread that has a 0 value for one or more of its user IDs wants |
| 1525 |
to prevent its permitted capability set being cleared when it resets |
| 1526 |
all of its user IDs to nonzero values, it can do so using the |
| 1527 |
.B SECBIT_KEEP_CAPS |
| 1528 |
securebits flag described below. |
| 1529 |
.\" |
| 1530 |
.SS Programmatically adjusting capability sets |
| 1531 |
A thread can retrieve and change its permitted, effective, and inheritable |
| 1532 |
capability sets using the |
| 1533 |
.BR capget (2) |
| 1534 |
and |
| 1535 |
.BR capset (2) |
| 1536 |
system calls. |
| 1537 |
However, the use of |
| 1538 |
.BR cap_get_proc (3) |
| 1539 |
and |
| 1540 |
.BR cap_set_proc (3), |
| 1541 |
both provided in the |
| 1542 |
.I libcap |
| 1543 |
package, |
| 1544 |
is preferred for this purpose. |
| 1545 |
The following rules govern changes to the thread capability sets: |
| 1546 |
.IP \[bu] 3 |
| 1547 |
If the caller does not have the |
| 1548 |
.B CAP_SETPCAP |
| 1549 |
capability, |
| 1550 |
the new inheritable set must be a subset of the combination |
| 1551 |
of the existing inheritable and permitted sets. |
| 1552 |
.IP \[bu] |
| 1553 |
(Since Linux 2.6.25) |
| 1554 |
The new inheritable set must be a subset of the combination of the |
| 1555 |
existing inheritable set and the capability bounding set. |
| 1556 |
.IP \[bu] |
| 1557 |
The new permitted set must be a subset of the existing permitted set |
| 1558 |
(i.e., it is not possible to acquire permitted capabilities |
| 1559 |
that the thread does not currently have). |
| 1560 |
.IP \[bu] |
| 1561 |
The new effective set must be a subset of the new permitted set. |
| 1562 |
.SS The securebits flags: establishing a capabilities-only environment |
| 1563 |
.\" For some background: |
| 1564 |
.\" see http://lwn.net/Articles/280279/ and |
| 1565 |
.\" http://article.gmane.org/gmane.linux.kernel.lsm/5476/ |
| 1566 |
Starting with Linux 2.6.26, |
| 1567 |
and with a kernel in which file capabilities are enabled, |
| 1568 |
Linux implements a set of per-thread |
| 1569 |
.I securebits |
| 1570 |
flags that can be used to disable special handling of capabilities for UID 0 |
| 1571 |
.RI ( root ). |
| 1572 |
These flags are as follows: |
| 1573 |
.TP |
| 1574 |
.B SECBIT_KEEP_CAPS |
| 1575 |
Setting this flag allows a thread that has one or more 0 UIDs to retain |
| 1576 |
capabilities in its permitted set |
| 1577 |
when it switches all of its UIDs to nonzero values. |
| 1578 |
If this flag is not set, |
| 1579 |
then such a UID switch causes the thread to lose all permitted capabilities. |
| 1580 |
This flag is always cleared on an |
| 1581 |
.BR execve (2). |
| 1582 |
.IP |
| 1583 |
Note that even with the |
| 1584 |
.B SECBIT_KEEP_CAPS |
| 1585 |
flag set, the effective capabilities of a thread are cleared when it |
| 1586 |
switches its effective UID to a nonzero value. |
| 1587 |
However, |
| 1588 |
if the thread has set this flag and its effective UID is already nonzero, |
| 1589 |
and the thread subsequently switches all other UIDs to nonzero values, |
| 1590 |
then the effective capabilities will not be cleared. |
| 1591 |
.IP |
| 1592 |
The setting of the |
| 1593 |
.B SECBIT_KEEP_CAPS |
| 1594 |
flag is ignored if the |
| 1595 |
.B SECBIT_NO_SETUID_FIXUP |
| 1596 |
flag is set. |
| 1597 |
(The latter flag provides a superset of the effect of the former flag.) |
| 1598 |
.IP |
| 1599 |
This flag provides the same functionality as the older |
| 1600 |
.BR prctl (2) |
| 1601 |
.B PR_SET_KEEPCAPS |
| 1602 |
operation. |
| 1603 |
.TP |
| 1604 |
.B SECBIT_NO_SETUID_FIXUP |
| 1605 |
Setting this flag stops the kernel from adjusting the process's |
| 1606 |
permitted, effective, and ambient capability sets when |
| 1607 |
the thread's effective and filesystem UIDs are switched between |
| 1608 |
zero and nonzero values. |
| 1609 |
See |
| 1610 |
.I Effect of user ID changes on capabilities |
| 1611 |
above. |
| 1612 |
.TP |
| 1613 |
.B SECBIT_NOROOT |
| 1614 |
If this bit is set, then the kernel does not grant capabilities |
| 1615 |
when a set-user-ID-root program is executed, or when a process with |
| 1616 |
an effective or real UID of 0 calls |
| 1617 |
.BR execve (2). |
| 1618 |
(See |
| 1619 |
.I Capabilities and execution of programs by root |
| 1620 |
above.) |
| 1621 |
.TP |
| 1622 |
.B SECBIT_NO_CAP_AMBIENT_RAISE |
| 1623 |
Setting this flag disallows raising ambient capabilities via the |
| 1624 |
.BR prctl (2) |
| 1625 |
.B PR_CAP_AMBIENT_RAISE |
| 1626 |
operation. |
| 1627 |
.P |
| 1628 |
Each of the above "base" flags has a companion "locked" flag. |
| 1629 |
Setting any of the "locked" flags is irreversible, |
| 1630 |
and has the effect of preventing further changes to the |
| 1631 |
corresponding "base" flag. |
| 1632 |
The locked flags are: |
| 1633 |
.BR SECBIT_KEEP_CAPS_LOCKED , |
| 1634 |
.BR SECBIT_NO_SETUID_FIXUP_LOCKED , |
| 1635 |
.BR SECBIT_NOROOT_LOCKED , |
| 1636 |
and |
| 1637 |
.BR SECBIT_NO_CAP_AMBIENT_RAISE_LOCKED . |
| 1638 |
.P |
| 1639 |
The |
| 1640 |
.I securebits |
| 1641 |
flags can be modified and retrieved using the |
| 1642 |
.BR prctl (2) |
| 1643 |
.B PR_SET_SECUREBITS |
| 1644 |
and |
| 1645 |
.B PR_GET_SECUREBITS |
| 1646 |
operations. |
| 1647 |
The |
| 1648 |
.B CAP_SETPCAP |
| 1649 |
capability is required to modify the flags. |
| 1650 |
Note that the |
| 1651 |
.B SECBIT_* |
| 1652 |
constants are available only after including the |
| 1653 |
.I <linux/securebits.h> |
| 1654 |
header file. |
| 1655 |
.P |
| 1656 |
The |
| 1657 |
.I securebits |
| 1658 |
flags are inherited by child processes. |
| 1659 |
During an |
| 1660 |
.BR execve (2), |
| 1661 |
all of the flags are preserved, except |
| 1662 |
.B SECBIT_KEEP_CAPS |
| 1663 |
which is always cleared. |
| 1664 |
.P |
| 1665 |
An application can use the following call to lock itself, |
| 1666 |
and all of its descendants, |
| 1667 |
into an environment where the only way of gaining capabilities |
| 1668 |
is by executing a program with associated file capabilities: |
| 1669 |
.P |
| 1670 |
.in +4n |
| 1671 |
.EX |
| 1672 |
prctl(PR_SET_SECUREBITS, |
| 1673 |
/* SECBIT_KEEP_CAPS off */ |
| 1674 |
SECBIT_KEEP_CAPS_LOCKED | |
| 1675 |
SECBIT_NO_SETUID_FIXUP | |
| 1676 |
SECBIT_NO_SETUID_FIXUP_LOCKED | |
| 1677 |
SECBIT_NOROOT | |
| 1678 |
SECBIT_NOROOT_LOCKED); |
| 1679 |
/* Setting/locking SECBIT_NO_CAP_AMBIENT_RAISE |
| 1680 |
is not required */ |
| 1681 |
.EE |
| 1682 |
.in |
| 1683 |
.\" |
| 1684 |
.\" |
| 1685 |
.SS Per-user-namespace \[dq]set-user-ID-root\[dq] programs |
| 1686 |
A set-user-ID program whose UID matches the UID that |
| 1687 |
created a user namespace will confer capabilities |
| 1688 |
in the process's permitted and effective sets |
| 1689 |
when executed by any process inside that namespace |
| 1690 |
or any descendant user namespace. |
| 1691 |
.P |
| 1692 |
The rules about the transformation of the process's capabilities during the |
| 1693 |
.BR execve (2) |
| 1694 |
are exactly as described in |
| 1695 |
.I Transformation of capabilities during execve() |
| 1696 |
and |
| 1697 |
.I Capabilities and execution of programs by root |
| 1698 |
above, |
| 1699 |
with the difference that, in the latter subsection, "root" |
| 1700 |
is the UID of the creator of the user namespace. |
| 1701 |
.\" |
| 1702 |
.\" |
| 1703 |
.SS Namespaced file capabilities |
| 1704 |
.\" commit 8db6c34f1dbc8e06aa016a9b829b06902c3e1340 |
| 1705 |
Traditional (i.e., version 2) file capabilities associate |
| 1706 |
only a set of capability masks with a binary executable file. |
| 1707 |
When a process executes a binary with such capabilities, |
| 1708 |
it gains the associated capabilities (within its user namespace) |
| 1709 |
as per the rules described in |
| 1710 |
.I Transformation of capabilities during execve() |
| 1711 |
above. |
| 1712 |
.P |
| 1713 |
Because version 2 file capabilities confer capabilities to |
| 1714 |
the executing process regardless of which user namespace it resides in, |
| 1715 |
only privileged processes are permitted to associate capabilities with a file. |
| 1716 |
Here, "privileged" means a process that has the |
| 1717 |
.B CAP_SETFCAP |
| 1718 |
capability in the user namespace where the filesystem was mounted |
| 1719 |
(normally the initial user namespace). |
| 1720 |
This limitation renders file capabilities useless for certain use cases. |
| 1721 |
For example, in user-namespaced containers, |
| 1722 |
it can be desirable to be able to create a binary that |
| 1723 |
confers capabilities only to processes executed inside that container, |
| 1724 |
but not to processes that are executed outside the container. |
| 1725 |
.P |
| 1726 |
Linux 4.14 added so-called namespaced file capabilities |
| 1727 |
to support such use cases. |
| 1728 |
Namespaced file capabilities are recorded as version 3 (i.e., |
| 1729 |
.BR VFS_CAP_REVISION_3 ) |
| 1730 |
.I security.capability |
| 1731 |
extended attributes. |
| 1732 |
Such an attribute is automatically created in the circumstances described |
| 1733 |
in |
| 1734 |
.I File capability extended attribute versioning |
| 1735 |
above. |
| 1736 |
When a version 3 |
| 1737 |
.I security.capability |
| 1738 |
extended attribute is created, |
| 1739 |
the kernel records not just the capability masks in the extended attribute, |
| 1740 |
but also the namespace root user ID. |
| 1741 |
.P |
| 1742 |
As with a binary that has |
| 1743 |
.B VFS_CAP_REVISION_2 |
| 1744 |
file capabilities, a binary with |
| 1745 |
.B VFS_CAP_REVISION_3 |
| 1746 |
file capabilities confers capabilities to a process during |
| 1747 |
.BR execve (). |
| 1748 |
However, capabilities are conferred only if the binary is executed by |
| 1749 |
a process that resides in a user namespace whose |
| 1750 |
UID 0 maps to the root user ID that is saved in the extended attribute, |
| 1751 |
or when executed by a process that resides in a descendant of such a namespace. |
| 1752 |
.\" |
| 1753 |
.\" |
| 1754 |
.SS Interaction with user namespaces |
| 1755 |
For further information on the interaction of |
| 1756 |
capabilities and user namespaces, see |
| 1757 |
.BR user_namespaces (7). |
| 1758 |
.SH STANDARDS |
| 1759 |
No standards govern capabilities, but the Linux capability implementation |
| 1760 |
is based on the withdrawn |
| 1761 |
.UR https:\://archive.org\:/details\:/posix_1003.1e\-990310 |
| 1762 |
POSIX.1e draft standard |
| 1763 |
.UE . |
| 1764 |
.SH NOTES |
| 1765 |
When attempting to |
| 1766 |
.BR strace (1) |
| 1767 |
binaries that have capabilities (or set-user-ID-root binaries), |
| 1768 |
you may find the |
| 1769 |
.I \-u <username> |
| 1770 |
option useful. |
| 1771 |
Something like: |
| 1772 |
.P |
| 1773 |
.in +4n |
| 1774 |
.EX |
| 1775 |
.RB $ " sudo strace \-o trace.log \-u ceci ./myprivprog" |
| 1776 |
.EE |
| 1777 |
.in |
| 1778 |
.P |
| 1779 |
From Linux 2.5.27 to Linux 2.6.26, |
| 1780 |
.\" commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27 removed |
| 1781 |
.\" CONFIG_SECURITY_CAPABILITIES |
| 1782 |
capabilities were an optional kernel component, |
| 1783 |
and could be enabled/disabled via the |
| 1784 |
.B CONFIG_SECURITY_CAPABILITIES |
| 1785 |
kernel configuration option. |
| 1786 |
.P |
| 1787 |
The |
| 1788 |
.IR /proc/ pid /task/TID/status |
| 1789 |
file can be used to view the capability sets of a thread. |
| 1790 |
The |
| 1791 |
.IR /proc/ pid /status |
| 1792 |
file shows the capability sets of a process's main thread. |
| 1793 |
Before Linux 3.8, nonexistent capabilities were shown as being |
| 1794 |
enabled (1) in these sets. |
| 1795 |
Since Linux 3.8, |
| 1796 |
.\" 7b9a7ec565505699f503b4fcf61500dceb36e744 |
| 1797 |
all nonexistent capabilities (above |
| 1798 |
.BR CAP_LAST_CAP ) |
| 1799 |
are shown as disabled (0). |
| 1800 |
.P |
| 1801 |
The |
| 1802 |
.I libcap |
| 1803 |
package provides a suite of routines for setting and |
| 1804 |
getting capabilities that is more comfortable and less likely |
| 1805 |
to change than the interface provided by |
| 1806 |
.BR capset (2) |
| 1807 |
and |
| 1808 |
.BR capget (2). |
| 1809 |
This package also provides the |
| 1810 |
.BR setcap (8) |
| 1811 |
and |
| 1812 |
.BR getcap (8) |
| 1813 |
programs. |
| 1814 |
It can be found at |
| 1815 |
.br |
| 1816 |
.UR https:\://git.kernel.org\:/pub\:/scm\:/libs\:/libcap\:/libcap.git\:/refs/ |
| 1817 |
.UE . |
| 1818 |
.P |
| 1819 |
Before Linux 2.6.24, and from Linux 2.6.24 to Linux 2.6.32 if |
| 1820 |
file capabilities are not enabled, a thread with the |
| 1821 |
.B CAP_SETPCAP |
| 1822 |
capability can manipulate the capabilities of threads other than itself. |
| 1823 |
However, this is only theoretically possible, |
| 1824 |
since no thread ever has |
| 1825 |
.B CAP_SETPCAP |
| 1826 |
in either of these cases: |
| 1827 |
.IP \[bu] 3 |
| 1828 |
In the pre-2.6.25 implementation the system-wide capability bounding set, |
| 1829 |
.IR /proc/sys/kernel/cap\-bound , |
| 1830 |
always masks out the |
| 1831 |
.B CAP_SETPCAP |
| 1832 |
capability, and this can not be changed |
| 1833 |
without modifying the kernel source and rebuilding the kernel. |
| 1834 |
.IP \[bu] |
| 1835 |
If file capabilities are disabled (i.e., the kernel |
| 1836 |
.B CONFIG_SECURITY_FILE_CAPABILITIES |
| 1837 |
option is disabled), then |
| 1838 |
.B init |
| 1839 |
starts out with the |
| 1840 |
.B CAP_SETPCAP |
| 1841 |
capability removed from its per-process bounding |
| 1842 |
set, and that bounding set is inherited by all other processes |
| 1843 |
created on the system. |
| 1844 |
.SH SEE ALSO |
| 1845 |
.BR capsh (1), |
| 1846 |
.BR setpriv (1), |
| 1847 |
.BR prctl (2), |
| 1848 |
.BR setfsuid (2), |
| 1849 |
.BR cap_clear (3), |
| 1850 |
.BR cap_copy_ext (3), |
| 1851 |
.BR cap_from_text (3), |
| 1852 |
.BR cap_get_file (3), |
| 1853 |
.BR cap_get_proc (3), |
| 1854 |
.BR cap_init (3), |
| 1855 |
.BR capgetp (3), |
| 1856 |
.BR capsetp (3), |
| 1857 |
.BR libcap (3), |
| 1858 |
.BR proc (5), |
| 1859 |
.BR credentials (7), |
| 1860 |
.BR pthreads (7), |
| 1861 |
.BR user_namespaces (7), |
| 1862 |
.BR captest (8), \" from libcap-ng |
| 1863 |
.BR filecap (8), \" from libcap-ng |
| 1864 |
.BR getcap (8), |
| 1865 |
.BR getpcaps (8), |
| 1866 |
.BR netcap (8), \" from libcap-ng |
| 1867 |
.BR pscap (8), \" from libcap-ng |
| 1868 |
.BR setcap (8) |
| 1869 |
.P |
| 1870 |
.I include/linux/capability.h |
| 1871 |
in the Linux kernel source tree |