Debian Codegraph @

doc/cap_text_formats.7

raw
1 .TH CAP_TEXT_FORMATS 7 "2025-03-19" "" "Linux Programmer's Manual"
2 .SH "CAPABILITY TEXT FORMATS"
3 The capability library
4 .BR libcap (3)
5 employs two string formats for representing capabilities: the original
6 text format for the standard capability `Set' and supported by the
7 .BR getcap (8),
8 .BR setcap (8)
9 and
10 .BR capsh (8)
11 command line tools; and the
12 IAB-tuple text format, which is usable by the
13 .BR pam_cap (8)
14 Linux-PAM module,
15 .BR captree (8) and
16 .BR capsh (8).
17 These text formats have extensive support in
18 .BR libcap (3),
19 and the
20 .B 'kernel.org/pub/linux/libs/security/libcap/cap'
21 Go package.
22 .SH "THE CAPABILITY SET TEXT FORMAT"
23 This text format is specified in the defunct POSIX.1e draft [1] that
24 introduced capabilities. It is able to represent both process and file
25 capabilities.
26 .PP
27 The textual representation of capability sets consists of one or more
28 whitespace-separated
29 .IR clauses .
30 Each clause specifies some operations on a capability set; the set
31 starts out with all capabilities lowered, and the meaning of the
32 string is the state of the capability set after all the clauses have
33 been applied in order.
34 .PP
35 Each clause consists of a list of comma-separated capability names
36 (or the word
37 .RB ` all '),
38 followed by an
39 .IR action-list .
40 An action-list consists of a sequence of
41 .I operator flag
42 pairs. Legal operators are:
43 .RB ` = "', '" + "', and `" \- "'."
44 Legal flags are:
45 .RB ` e "', `" i "', and `" p "'."
46 These flags are case-sensitive and specify the Effective, Inheritable
47 and Permitted sets respectively.
48 .PP
49 In the capability name lists, all names are case-insensitive. The
50 special name
51 .RB ` all '
52 specifies all capabilities; it is equivalent to a list naming every
53 capability individually.
54 .PP
55 Unnamed capabilities can also be specified by number. This feature
56 ensures that libcap can support capabilities that were not allocated
57 at the time libcap was compiled. However, generally upgrading libcap
58 will add names for recently allocated capabilities.
59 .PP
60 The
61 .RB ` = '
62 operator indicates that the listed capabilities are first reset in
63 all three capability sets. The subsequent flags (which are optional
64 when associated with this operator) indicate that the listed
65 capabilities for the corresponding set are to be raised. For example:
66 "all=p" means lower every capability in the Effective and Inheritable
67 sets but raise all of the Permitted capabilities;
68 or, "cap_fowner=ep" means raise the Effective and Permitted
69 override-file-ownership capability, while lowering this Inheritable
70 capability.
71 .PP
72 In the case that the leading operator is
73 .RB ` = ',
74 and no list of capabilities is provided, the action-list is assumed to
75 refer to `all' capabilities. For example, the following three
76 clauses are equivalent to each other (and indicate a completely empty
77 capability set): "all="; "="; "cap_chown,<every-other-capability>=".
78 .PP
79 The operators, `+' and `\-' both require an explicit preceding
80 capability list and one or more explicit trailing flags. The `+'
81 operator will raise all of the listed capabilities in the flagged
82 capability sets. The `\-' operator will lower all of the listed
83 capabilities in the flagged capability sets. For example:
84 "all+p" will raise all of the Permitted capabilities and
85 "cap_fowner\-i" will lower the override-file-ownership in the Inheritable set.
86 .PP
87 The action list can consist of multiple
88 .I operator flag
89 pairs; the actions are performed in left-to-right order.
90 Thus, for example,
91 "cap_fowner+p\-i"
92 is equivalent to "cap_fowner+p cap_fowner\-i".
93 As another example,
94 "cap_fowner+pe\-i" and "cap_fowner=+pe" are equivalent.
95 .SH "THE IAB TUPLE TEXT FORMAT"
96 This format is a pure Linux extension. It started out life as the
97 format used by
98 .BR pam_cap (8)
99 and can be employed by
100 .BR capsh (8).
101 .PP
102 The IAB tuple text format is a comma separated list of capability
103 values. Each capability is prefixed by nothing (or %) (Inh); ! (Bound,
104 but think Blocked); ^ (Amb). Or, some combination thereof. Since the
105 Amb vector is constrained to be no greater than the Inh vector, ^ is
106 equivalent to %^. Further, unless B is non-zero, % can be omitted. The
107 following are legal text representations: "!%cap_chown" (Bound but
108 Inh), "!cap_chown,^cap_chown" (Bound,
109 Inh+Amb). "cap_setuid,!cap_chown" (Inh, Bound). As noted above, this
110 text representation is used in the configuration file syntax (see
111 .BR capability.conf (5))
112 for the
113 .BR pam_cap (8)
114 Linux-PAM security module.
115 .SH "SEE ALSO"
116 [1] A copy of the last POSIX.1e draft for security extensions can be
117 downloaded from the https://sites.google.com/site/fullycapable/
118 website. Please report bugs as directed at that site.
119 .PP
120 Related manual pages:
121 .BR libcap (3),
122 .BR capsh (1),
123 .BR setcap (8),
124 .BR getcap (8),
125 .BR captree (8),
126 .BR pam_cap (8),
127 .BR cap_from_text (3),
128 .BR cap_iab (3).
129