| 1 |
.TH CAP_IAB 3 "2025-03-19" "" "Linux Programmer's Manual" |
| 2 |
.SH NAME |
| 3 |
cap_iab_init, cap_iab_dup, cap_iab_get_proc, cap_iab_get_pid, \ |
| 4 |
cap_iab_set_proc, cap_iab_to_text, cap_iab_from_text, \ |
| 5 |
cap_iab_get_vector, cap_iab_compare, cap_iab_set_vector, \ |
| 6 |
cap_iab_fill, cap_proc_root \- inheritable IAB tuple support functions |
| 7 |
.SH SYNOPSIS |
| 8 |
.nf |
| 9 |
#include <sys/capability.h> |
| 10 |
|
| 11 |
cap_iab_t cap_iab_init(void); |
| 12 |
cap_iab_t cap_iab_dup(cap_iab_t iab); |
| 13 |
cap_iab_t cap_iab_get_proc(void); |
| 14 |
cap_iab_t cap_iab_get_pid(pid_t pid); |
| 15 |
int cap_iab_set_proc(cap_iab_t iab); |
| 16 |
char *cap_iab_to_text(cap_iab_t iab); |
| 17 |
cap_iab_t cap_iab_from_text(const char *text); |
| 18 |
cap_flag_value_t cap_iab_get_vector(cap_iab_t iab, cap_iab_vector_t vec, |
| 19 |
cap_value_t val); |
| 20 |
int cap_iab_compare(cap_iab_t a, cap_iab_t b); |
| 21 |
int cap_iab_set_vector(cap_iab_t iab, cap_iab_vector_t vec, cap_value_t val, |
| 22 |
cap_flag_value_t enable); |
| 23 |
int cap_iab_fill(cap_iab_t iab, cap_iab_vector_t vec, |
| 24 |
cap_t set, cap_flag_t flag); |
| 25 |
char *cap_proc_root(const char *root); |
| 26 |
.fi |
| 27 |
.sp |
| 28 |
Link with \fI\-lcap\fP. |
| 29 |
.SH "DESCRIPTION" |
| 30 |
The functions defined in this man page concern the three naively |
| 31 |
inheritable process capability vectors: Inh, Amb and Bound. This |
| 32 |
\fIIAB\fP 3-tuple of capability vectors, captured in type |
| 33 |
\fIcap_iab_t\fP combine to pass capabilities from one process to |
| 34 |
another through |
| 35 |
.BR execve (2) |
| 36 |
system calls. The convolution rules using the IAB tuple are a fail over |
| 37 |
set of rules when the executed file has no configured |
| 38 |
\fIfile-capabilities\fP. |
| 39 |
.PP |
| 40 |
There are some constraints enforced by the kernel with respect to the |
| 41 |
three components of an IAB tuple and the Permitted process capability |
| 42 |
flag. They are: the Inh vector |
| 43 |
.RB ( CAP_IAB_INH ) |
| 44 |
is entirely equal to the process Inheritable flag at all times; the |
| 45 |
Amb vector |
| 46 |
.RB ( CAP_IAB_AMB ) |
| 47 |
contains no more capability values than the intersection of |
| 48 |
the Inh vector and the Permitted flag for the process; and the Bound |
| 49 |
(or \fIblocked\fP) vector |
| 50 |
.RB ( CAP_IAB_BOUND ) |
| 51 |
is the twos-complement of the process bounding vector. |
| 52 |
.PP |
| 53 |
In some environments, it is considered desirable to \fInaively\fP |
| 54 |
inherit capabilities. That is pass capabilities, independent of the |
| 55 |
status of the executed binary, from parent to child through |
| 56 |
\fBexec*\fP system calls. The surviving capabilities become the |
| 57 |
Permitted flag for the post-exec process. This method of inheritance |
| 58 |
differs significantly from the handshake inheritance between a |
| 59 |
pre-exec* process and a file-capability bestowed executable of the |
| 60 |
traditional (POSIX.1e) capability mechanism. |
| 61 |
.PP |
| 62 |
The convolution rules for IAB style inheritance are: I'=I; A'=A&I; |
| 63 |
P'=A&I&P. Where P etc are the pre-exec values and P' etc are the |
| 64 |
post-exec values. |
| 65 |
.PP |
| 66 |
With an understanding of these convolution rules, we can explain how |
| 67 |
.BR libcap (3) |
| 68 |
support for the IAB tuple is managed: the IAB API. |
| 69 |
.PP |
| 70 |
.BR cap_iab_init () |
| 71 |
returns an empty IAB value. That is a \fImostly-harmless\fP tuple. It |
| 72 |
will not block any Permitted file capabilities through exec, but it |
| 73 |
won't bestow any either. The returned \fIcap_iab_t\fP should be freed |
| 74 |
with |
| 75 |
.BR cap_free (3). |
| 76 |
.sp |
| 77 |
.BR cap_iab_dup () |
| 78 |
returns a copy of the specified IAB value. The returned cap_iab_t |
| 79 |
should be freed with |
| 80 |
.BR cap_free (3). |
| 81 |
.sp |
| 82 |
.BR cap_iab_get_proc () |
| 83 |
returns a copy of the IAB value for the current process. The returned |
| 84 |
cap_iab_t should be freed with |
| 85 |
.BR cap_free (3). |
| 86 |
.sp |
| 87 |
.BR cap_iab_get_pid () |
| 88 |
returns a copy of the IAB value for the specified process. The returned |
| 89 |
cap_iab_t should be freed with |
| 90 |
.BR cap_free (3). |
| 91 |
This function defaults to searching |
| 92 |
.BR /proc/ <PID> /status |
| 93 |
for the IAB information, but that location can be overridden using the |
| 94 |
.BR cap_proc_root () |
| 95 |
function. |
| 96 |
.sp |
| 97 |
.BR cap_iab_set_proc () |
| 98 |
can be used to set the IAB value carried by the current process. Such |
| 99 |
a setting will fail if the process is insufficiently capable. To raise |
| 100 |
I bits not present in the P flag, or newly apply B masking, requires |
| 101 |
.B CAP_SETPCAP |
| 102 |
is present in the Permitted flag (the function will temporarily raise |
| 103 |
it in the Effective flag if needed). In all cases, raised A values |
| 104 |
must be present in the intersection of Permitted and Inh values. |
| 105 |
.sp |
| 106 |
.BR cap_iab_to_text () |
| 107 |
will convert an IAB tuple to a canonical IAB text representation. The |
| 108 |
representation is slightly redundant but |
| 109 |
.BR libcap (3) will try to generate |
| 110 |
as short a representation as it is able. |
| 111 |
.sp |
| 112 |
.BR cap_iab_from_text () |
| 113 |
generates an IAB tuple from a text string (likely generated by the |
| 114 |
previous function). The returned IAB tuple should be freed with |
| 115 |
.BR cap_free (). |
| 116 |
.sp |
| 117 |
.BR cap_iab_get_vector () |
| 118 |
can be used to determine the specific capability value of an IAB |
| 119 |
vector. |
| 120 |
.sp |
| 121 |
.BR cap_iab_compare () |
| 122 |
can be used to compare two cap_iab_t tuples. When the return value is |
| 123 |
non-zero, the macro \fBCAP_IAB_DIFFERS\fR(\fIstatus\fR, \fIvector\fR) |
| 124 |
evaluates to non-zero if the returned status differs in its |
| 125 |
.I vector |
| 126 |
components. |
| 127 |
.sp |
| 128 |
.BR cap_iab_set_vector () |
| 129 |
can be used to set a specific vector value to the enable setting. |
| 130 |
.sp |
| 131 |
.BR cap_iab_fill () |
| 132 |
can be used to wholesale copy a |
| 133 |
.I cap_t |
| 134 |
flag value into the vec vector of the IAB tuple. Copying into Amb |
| 135 |
.RB ( CAP_IAB_AMB ) |
| 136 |
in this way may implicitly raise Inh |
| 137 |
.RB ( CAP_IAB_INH ) |
| 138 |
values in the IAB tuple. Similarly copying into the Inh vector may |
| 139 |
implicitly lower Amb values that are not present in the resulting Inh |
| 140 |
vector. |
| 141 |
.sp |
| 142 |
.BR cap_proc_root () |
| 143 |
can be used to determine the current location queried by |
| 144 |
.BR cap_iab_get_pid (). |
| 145 |
Returned values should be released with |
| 146 |
.BR cap_free (3). |
| 147 |
If the argument to |
| 148 |
.BR cap_proc_root () |
| 149 |
is not \fBNULL\fP, a copy of it will become the replacement for |
| 150 |
.BR /proc . |
| 151 |
Note, this function is \fInot\fP thread safe with respect to |
| 152 |
concurrent calls to |
| 153 |
.BR cap_iab_get_pid (). |
| 154 |
.SH "ERRORS" |
| 155 |
The functions returning \fIcap_iab_t\fP values or allocated memory in |
| 156 |
the form of a string return NULL on error. |
| 157 |
|
| 158 |
Integer return values are -1 on error and 0 on success. |
| 159 |
|
| 160 |
In the case of error consult \fIerrno\fP. |
| 161 |
.SH "NOTES" |
| 162 |
.PP |
| 163 |
Unlike the traditional \fIcap_t\fP capability set, the |
| 164 |
IAB tuple, taken together, is incompatible with filesystem capabilities |
| 165 |
created via tools like |
| 166 |
.BR setcap (8). |
| 167 |
That is, the Amb vector of the IAB tuple is rendered moot when an |
| 168 |
executable with a file capability is executed. |
| 169 |
.PP |
| 170 |
Further, there are libcap |
| 171 |
.BR cap_mode (3)s |
| 172 |
that render the Amb vector and its method of process inheritance |
| 173 |
disabled. |
| 174 |
|
| 175 |
.SH "HISTORY" |
| 176 |
The IAB format for inheritable variants of capabilities was first |
| 177 |
developed as the configuration syntax for the \fIpam_cap.so\fP |
| 178 |
Linux-PAM module in libcap-2.29. It was introduced to extend the |
| 179 |
\fIsimple\fP comma separated list of process Inheritable capabilities, |
| 180 |
that the module could besow on an authenticated process tree, to |
| 181 |
include enforced limits on the Bounding vector and introduce support |
| 182 |
for the Amibient vector of capability bits. |
| 183 |
|
| 184 |
While the Inheritable and Bounding vectors were anticipated by the |
| 185 |
POSIX.1e draft that introduced capabilities, the Ambient vector is a |
| 186 |
Linux invention, and incompatible with the POSIX.1e file capability |
| 187 |
model. As such, it was felt that trying to meld together all of the 5 |
| 188 |
capability vectors into one text representation was not going to |
| 189 |
work. Instead the \fIpam_cap.so\fP config syntax was generalized into |
| 190 |
a whole set of libcap functions for bundling together all three |
| 191 |
naively inheritable capabilities: the IAB tuple. The support for this |
| 192 |
debuted in libcap-2.33. |
| 193 |
.SH "REPORTING BUGS" |
| 194 |
Please report bugs via: |
| 195 |
.TP |
| 196 |
https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757 |
| 197 |
.SH "SEE ALSO" |
| 198 |
.BR libcap (3), |
| 199 |
.BR cap_launch (3), |
| 200 |
.BR cap_init (3), |
| 201 |
.BR capabilities (7) |
| 202 |
and |
| 203 |
.BR errno (3). |