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