xref: /aosp_15_r20/external/libcap/progs/capshdoc.c (revision 2810ac1b38eead2603277920c78344c84ddf3aff)
1 #include <stdio.h>
2 
3 #include "./capshdoc.h"
4 
5 /*
6  * A line by line explanation of each named capability value
7  */
8 static const char *explanation0[] = {  /* cap_chown = 0 */
9     "Allows a process to arbitrarily change the user and",
10     "group ownership of a file.",
11     NULL
12 };
13 static const char *explanation1[] = {  /* cap_dac_override = 1 */
14     "Allows a process to override of all Discretionary",
15     "Access Control (DAC) access, including ACL execute",
16     "access. That is read, write or execute files that the",
17     "process would otherwise not have access to. This",
18     "excludes DAC access covered by CAP_LINUX_IMMUTABLE.",
19     NULL
20 };
21 static const char *explanation2[] = {  /* cap_dac_read_search = 2 */
22     "Allows a process to override all DAC restrictions",
23     "limiting the read and search of files and",
24     "directories. This excludes DAC access covered by",
25     "CAP_LINUX_IMMUTABLE.",
26     NULL
27 };
28 static const char *explanation3[] = {  /* cap_fowner = 3 */
29     "Allows a process to perform operations on files, even",
30     "where file owner ID should otherwise need be equal to",
31     "the UID, except where CAP_FSETID is applicable. It",
32     "doesn't override MAC and DAC restrictions.",
33     "",
34     "This capability permits the deletion of a file owned",
35     "by another UID in a directory protected by the sticky",
36     "(t) bit.",
37     NULL
38 };
39 static const char *explanation4[] = {  /* cap_fsetid = 4 */
40     "Allows a process to set the S_ISUID and S_ISUID bits of",
41     "the file permissions, even when the process' effective",
42     "UID or GID/supplementary GIDs do not match that of the",
43     "file.",
44     NULL
45 };
46 static const char *explanation5[] = {  /* cap_kill = 5 */
47     "Allows a process to send a kill(2) signal to any other",
48     "process - overriding the limitation that there be a",
49     "[E]UID match between source and target process.",
50     NULL
51 };
52 static const char *explanation6[] = {  /* cap_setgid = 6 */
53     "Allows a process to freely manipulate its own GIDs:",
54     "  - arbitrarily set the GID, EGID, REGID, RESGID values",
55     "  - arbitrarily set the supplementary GIDs",
56     "  - allows the forging of GID credentials passed over a",
57     "    socket",
58     NULL
59 };
60 static const char *explanation7[] = {  /* cap_setuid = 7 */
61     "Allows a process to freely manipulate its own UIDs:",
62     "  - arbitrarily set the UID, EUID, REUID and RESUID",
63     "    values",
64     "  - allows the forging of UID credentials passed over a",
65     "    socket",
66     NULL
67 };
68 static const char *explanation8[] = {  /* cap_setpcap = 8 */
69     "Allows a process to freely manipulate its inheritable",
70     "capabilities.",
71     "",
72     "Linux supports the POSIX.1e Inheritable set, the POXIX.1e (X",
73     "vector) known in Linux as the Bounding vector, as well as",
74     "the Linux extension Ambient vector.",
75     "",
76     "This capability permits dropping bits from the Bounding",
77     "vector (ie. raising B bits in the libcap IAB",
78     "representation). It also permits the process to raise",
79     "Ambient vector bits that are both raised in the Permitted",
80     "and Inheritable sets of the process. This capability cannot",
81     "be used to raise Permitted bits, Effective bits beyond those",
82     "already present in the process' permitted set, or",
83     "Inheritable bits beyond those present in the Bounding",
84     "vector.",
85     "",
86     "[Historical note: prior to the advent of file capabilities",
87     "(2008), this capability was suppressed by default, as its",
88     "unsuppressed behavior was not auditable: it could",
89     "asynchronously grant its own Permitted capabilities to and",
90     "remove capabilities from other processes arbitrarily. The",
91     "former leads to undefined behavior, and the latter is better",
92     "served by the kill system call.]",
93     NULL
94 };
95 static const char *explanation9[] = {  /* cap_linux_immutable = 9 */
96     "Allows a process to modify the S_IMMUTABLE and",
97     "S_APPEND file attributes.",
98     NULL
99 };
100 static const char *explanation10[] = {  /* cap_net_bind_service = 10 */
101     "Allows a process to bind to privileged ports:",
102     "  - TCP/UDP sockets below 1024",
103     "  - ATM VCIs below 32",
104     NULL
105 };
106 static const char *explanation11[] = {  /* cap_net_broadcast = 11 */
107     "Allows a process to broadcast to the network and to",
108     "listen to multicast.",
109     NULL
110 };
111 static const char *explanation12[] = {  /* cap_net_admin = 12 */
112     "Allows a process to perform network configuration",
113     "operations:",
114     "  - interface configuration",
115     "  - administration of IP firewall, masquerading and",
116     "    accounting",
117     "  - setting debug options on sockets",
118     "  - modification of routing tables",
119     "  - setting arbitrary process, and process group",
120     "    ownership on sockets",
121     "  - binding to any address for transparent proxying",
122     "    (this is also allowed via CAP_NET_RAW)",
123     "  - setting TOS (Type of service)",
124     "  - setting promiscuous mode",
125     "  - clearing driver statistics",
126     "  - multicasing",
127     "  - read/write of device-specific registers",
128     "  - activation of ATM control sockets",
129     NULL
130 };
131 static const char *explanation13[] = {  /* cap_net_raw = 13 */
132     "Allows a process to use raw networking:",
133     "  - RAW sockets",
134     "  - PACKET sockets",
135     "  - binding to any address for transparent proxying",
136     "    (also permitted via CAP_NET_ADMIN)",
137     NULL
138 };
139 static const char *explanation14[] = {  /* cap_ipc_lock = 14 */
140     "Allows a process to lock shared memory segments for IPC",
141     "purposes.  Also enables mlock and mlockall system",
142     "calls.",
143     NULL
144 };
145 static const char *explanation15[] = {  /* cap_ipc_owner = 15 */
146     "Allows a process to override IPC ownership checks.",
147     NULL
148 };
149 static const char *explanation16[] = {  /* cap_sys_module = 16 */
150     "Allows a process to initiate the loading and unloading",
151     "of kernel modules. This capability can effectively",
152     "modify kernel without limit.",
153     NULL
154 };
155 static const char *explanation17[] = {  /* cap_sys_rawio = 17 */
156     "Allows a process to perform raw IO:",
157     "  - permit ioper/iopl access",
158     "  - permit sending USB messages to any device via",
159     "    /dev/bus/usb",
160     NULL
161 };
162 static const char *explanation18[] = {  /* cap_sys_chroot = 18 */
163     "Allows a process to perform a chroot syscall to change",
164     "the effective root of the process' file system:",
165     "redirect to directory \"/\" to some other location.",
166     NULL
167 };
168 static const char *explanation19[] = {  /* cap_sys_ptrace = 19 */
169     "Allows a process to perform a ptrace() of any other",
170     "process.",
171     NULL
172 };
173 static const char *explanation20[] = {  /* cap_sys_pacct = 20 */
174     "Allows a process to configure process accounting.",
175     NULL
176 };
177 static const char *explanation21[] = {  /* cap_sys_admin = 21 */
178     "Allows a process to perform a somewhat arbitrary",
179     "grab-bag of privileged operations. Over time, this",
180     "capability should weaken as specific capabilities are",
181     "created for subsets of CAP_SYS_ADMINs functionality:",
182     "  - configuration of the secure attention key",
183     "  - administration of the random device",
184     "  - examination and configuration of disk quotas",
185     "  - setting the domainname",
186     "  - setting the hostname",
187     "  - calling bdflush()",
188     "  - mount() and umount(), setting up new SMB connection",
189     "  - some autofs root ioctls",
190     "  - nfsservctl",
191     "  - VM86_REQUEST_IRQ",
192     "  - to read/write pci config on alpha",
193     "  - irix_prctl on mips (setstacksize)",
194     "  - flushing all cache on m68k (sys_cacheflush)",
195     "  - removing semaphores",
196     "  - Used instead of CAP_CHOWN to \"chown\" IPC message",
197     "    queues, semaphores and shared memory",
198     "  - locking/unlocking of shared memory segment",
199     "  - turning swap on/off",
200     "  - forged pids on socket credentials passing",
201     "  - setting readahead and flushing buffers on block",
202     "    devices",
203     "  - setting geometry in floppy driver",
204     "  - turning DMA on/off in xd driver",
205     "  - administration of md devices (mostly the above, but",
206     "    some extra ioctls)",
207     "  - tuning the ide driver",
208     "  - access to the nvram device",
209     "  - administration of apm_bios, serial and bttv (TV)",
210     "    device",
211     "  - manufacturer commands in isdn CAPI support driver",
212     "  - reading non-standardized portions of PCI",
213     "    configuration space",
214     "  - DDI debug ioctl on sbpcd driver",
215     "  - setting up serial ports",
216     "  - sending raw qic-117 commands",
217     "  - enabling/disabling tagged queuing on SCSI",
218     "    controllers and sending arbitrary SCSI commands",
219     "  - setting encryption key on loopback filesystem",
220     "  - setting zone reclaim policy",
221     NULL
222 };
223 static const char *explanation22[] = {  /* cap_sys_boot = 22 */
224     "Allows a process to initiate a reboot of the system.",
225     NULL
226 };
227 static const char *explanation23[] = {  /* cap_sys_nice = 23 */
228     "Allows a process to maipulate the execution priorities",
229     "of arbitrary processes:",
230     "  - those involving different UIDs",
231     "  - setting their CPU affinity",
232     "  - alter the FIFO vs. round-robin (realtime)",
233     "    scheduling for itself and other processes.",
234     NULL
235 };
236 static const char *explanation24[] = {  /* cap_sys_resource = 24 */
237     "Allows a process to adjust resource related parameters",
238     "of processes and the system:",
239     "  - set and override resource limits",
240     "  - override quota limits",
241     "  - override the reserved space on ext2 filesystem",
242     "    (this can also be achieved via CAP_FSETID)",
243     "  - modify the data journaling mode on ext3 filesystem,",
244     "    which uses journaling resources",
245     "  - override size restrictions on IPC message queues",
246     "  - configure more than 64Hz interrupts from the",
247     "    real-time clock",
248     "  - override the maximum number of consoles for console",
249     "    allocation",
250     "  - override the maximum number of keymaps",
251     NULL
252 };
253 static const char *explanation25[] = {  /* cap_sys_time = 25 */
254     "Allows a process to perform time manipulation of clocks:",
255     "  - alter the system clock",
256     "  - enable irix_stime on MIPS",
257     "  - set the real-time clock",
258     NULL
259 };
260 static const char *explanation26[] = {  /* cap_sys_tty_config = 26 */
261     "Allows a process to manipulate tty devices:",
262     "  - configure tty devices",
263     "  - perform vhangup() of a tty",
264     NULL
265 };
266 static const char *explanation27[] = {  /* cap_mknod = 27 */
267     "Allows a process to perform privileged operations with",
268     "the mknod() system call.",
269     NULL
270 };
271 static const char *explanation28[] = {  /* cap_lease = 28 */
272     "Allows a process to take leases on files.",
273     NULL
274 };
275 static const char *explanation29[] = {  /* cap_audit_write = 29 */
276     "Allows a process to write to the audit log via a",
277     "unicast netlink socket.",
278     NULL
279 };
280 static const char *explanation30[] = {  /* cap_audit_control = 30 */
281     "Allows a process to configure audit logging via a",
282     "unicast netlink socket.",
283     NULL
284 };
285 static const char *explanation31[] = {  /* cap_setfcap = 31 */
286     "Allows a process to set capabilities on files.",
287     "Permits a process to uid_map the uid=0 of the",
288     "parent user namespace into that of the child",
289     "namespace. Also, permits a process to override",
290     "securebits locks through user namespace",
291     "creation.",
292     NULL
293 };
294 static const char *explanation32[] = {  /* cap_mac_override = 32 */
295     "Allows a process to override Manditory Access Control",
296     "(MAC) access. Not all kernels are configured with a MAC",
297     "mechanism, but this is the capability reserved for",
298     "overriding them.",
299     NULL
300 };
301 static const char *explanation33[] = {  /* cap_mac_admin = 33 */
302     "Allows a process to configure the Mandatory Access",
303     "Control (MAC) policy. Not all kernels are configured",
304     "with a MAC enabled, but if they are this capability is",
305     "reserved for code to perform administration tasks.",
306     NULL
307 };
308 static const char *explanation34[] = {  /* cap_syslog = 34 */
309     "Allows a process to configure the kernel's syslog",
310     "(printk) behavior.",
311     NULL
312 };
313 static const char *explanation35[] = {  /* cap_wake_alarm = 35 */
314     "Allows a process to trigger something that can wake the",
315     "system up.",
316     NULL
317 };
318 static const char *explanation36[] = {  /* cap_block_suspend = 36 */
319     "Allows a process to block system suspends - prevent the",
320     "system from entering a lower power state.",
321     NULL
322 };
323 static const char *explanation37[] = {  /* cap_audit_read = 37 */
324     "Allows a process to read the audit log via a multicast",
325     "netlink socket.",
326     NULL
327 };
328 static const char *explanation38[] = {  /* cap_perfmon = 38 */
329     "Allows a process to enable observability of privileged",
330     "operations related to performance. The mechanisms",
331     "include perf_events, i915_perf and other kernel",
332     "subsystems.",
333     NULL
334 };
335 static const char *explanation39[] = {  /* cap_bpf = 39 */
336     "Allows a process to manipulate aspects of the kernel",
337     "enhanced Berkeley Packet Filter (BPF) system. This is",
338     "an execution subsystem of the kernel, that manages BPF",
339     "programs. CAP_BPF permits a process to:",
340     "  - create all types of BPF maps",
341     "  - advanced verifier features:",
342     "    - indirect variable access",
343     "    - bounded loops",
344     "    - BPF to BPF function calls",
345     "    - scalar precision tracking",
346     "    - larger complexity limits",
347     "    - dead code elimination",
348     "    - potentially other features",
349     "",
350     "Other capabilities can be used together with CAP_BFP to",
351     "further manipulate the BPF system:",
352     "  - CAP_PERFMON relaxes the verifier checks as follows:",
353     "    - BPF programs can use pointer-to-integer",
354     "      conversions",
355     "    - speculation attack hardening measures can be",
356     "      bypassed",
357     "    - bpf_probe_read to read arbitrary kernel memory is",
358     "      permitted",
359     "    - bpf_trace_printk to print the content of kernel",
360     "      memory",
361     "  - CAP_SYS_ADMIN permits the following:",
362     "    - use of bpf_probe_write_user",
363     "    - iteration over the system-wide loaded programs,",
364     "      maps, links BTFs and convert their IDs to file",
365     "      descriptors.",
366     "  - CAP_PERFMON is required to load tracing programs.",
367     "  - CAP_NET_ADMIN is required to load networking",
368     "    programs.",
369     NULL
370 };
371 static const char *explanation40[] = {  /* cap_checkpoint_restore = 40 */
372     "Allows a process to perform checkpoint",
373     "and restore operations. Also permits",
374     "explicit PID control via clone3() and",
375     "also writing to ns_last_pid.",
376     NULL
377 };
378 const char **explanations[] = {
379     explanation0,
380     explanation1,
381     explanation2,
382     explanation3,
383     explanation4,
384     explanation5,
385     explanation6,
386     explanation7,
387     explanation8,
388     explanation9,
389     explanation10,
390     explanation11,
391     explanation12,
392     explanation13,
393     explanation14,
394     explanation15,
395     explanation16,
396     explanation17,
397     explanation18,
398     explanation19,
399     explanation20,
400     explanation21,
401     explanation22,
402     explanation23,
403     explanation24,
404     explanation25,
405     explanation26,
406     explanation27,
407     explanation28,
408     explanation29,
409     explanation30,
410     explanation31,
411     explanation32,
412     explanation33,
413     explanation34,
414     explanation35,
415     explanation36,
416     explanation37,
417     explanation38,
418     explanation39,
419     explanation40,
420 };
421 
422 const int capsh_doc_limit = 41;
423