doc/cap_iab.3

.TH CAP_IAB 3 "2022-10-16" "" "Linux Programmer's Manual"
.SH NAME
cap_iab_init, cap_iab_dup, cap_iab_get_proc, cap_iab_get_pid, \
cap_iab_set_proc, cap_iab_to_text, cap_iab_from_text, \
cap_iab_get_vector, cap_iab_compare, cap_iab_set_vector, \
cap_iab_fill, cap_proc_root \- inheritable IAB tuple support functions
.SH SYNOPSIS
.nf
#include <sys/capability.h>

cap_iab_t cap_iab_init(void);
cap_iab_t cap_iab_dup(cap_iab_t iab);
cap_iab_t cap_iab_get_proc(void);
cap_iab_t cap_iab_get_pid(pid_t pid);
int cap_iab_set_proc(cap_iab_t iab);
char *cap_iab_to_text(cap_iab_t iab);
cap_iab_t cap_iab_from_text(const char *text);
cap_flag_value_t cap_iab_get_vector(cap_iab_t iab, cap_iab_vector_t vec,
    cap_value_t val);
int cap_iab_compare(cap_iab_t a, cap_iab_t b);
int cap_iab_set_vector(cap_iab_t iab, cap_iab_vector_t vec, cap_value_t val,
    cap_flag_value_t enable);
int cap_iab_fill(cap_iab_t iab, cap_iab_vector_t vec,
    cap_t set, cap_flag_t flag);
char *cap_proc_root(const char *root);
.fi
.sp
Link with \fI\-lcap\fP.
.SH "DESCRIPTION"
The functions defined in this man page concern the three naively
inheritable process capability vectors: Inh, Amb and Bound. This
\fIIAB\fP 3-tuple of capability vectors, captured in type
\fIcap_iab_t\fP combine to pass capabilities from one process to
another through
.BR execve (2)
system calls. The convolution rules using the IAB tuple are a fail over
set of rules when the executed file has no configured
\fIfile-capabilities\fP.
.PP
There are some constraints enforced by the kernel with respect to the
three components of an IAB tuple and the Permitted process capability
flag. They are: the Inh vector is entirely equal to the process
Inheritable flag at all times; the Amb vector contains no more
capability values than the intersection of the Inh vector and the
Permitted flag for the process; and the Bound (or \fIblocked\fP)
vector is the twos-complement of the process bounding vector.
.PP
In some environments, it is considered desirable to \fInaively\fP
inherit capabilities. That is pass capabilities, independent of the
status of the executed binary, from parent to child through
\fBexec*\fP system calls. The surviving capabilities become the
Permitted flag for the post-exec process. This method of inheritance
differs significantly from the handshake inheritance between a
pre-exec* process and a file-capability bestowed executable of the
traditional (POSIX.1e) capability mechanism.
.PP
The convolution rules for IAB style inheritance are: I'=I; A'=A&I;
P'=A&I&P. Where P etc are the pre-exec values and P' etc are the
post-exec values.
.PP
With an understanding of these convolution rules, we can explain how
.BR libcap (3)
support for the IAB tuple is managed: the IAB API.
.PP
.BR cap_iab_init ()
returns an empty IAB value. That is a \fImostly-harmless\fP tuple. It
will not block any Permitted file capabilities through exec, but it
won't bestow any either. The returned \fIcap_iab_t\fP should be freed
with
.BR cap_free (3).
.sp
.BR cap_iab_dup ()
returns a copy of the specified IAB value.  The returned cap_iab_t
should be freed with
.BR cap_free (3).
.sp
.BR cap_iab_get_proc ()
returns a copy of the IAB value for the current process.  The returned
cap_iab_t should be freed with
.BR cap_free (3).
.sp
.BR cap_iab_get_pid ()
returns a copy of the IAB value for the specified process.  The returned
cap_iab_t should be freed with
.BR cap_free (3).
This function defaults to searching
.BR /proc/ <PID> /status
for the IAB information, but that location can be overridden using the
.BR cap_proc_root ()
function.
.sp
.BR cap_iab_set_proc ()
can be used to set the IAB value carried by the current process. Such
a setting will fail if the process is insufficiently capable. The
process requires CAP_SETPCAP raised in the E flag and a superset of P
and I values over those in the A vectors.
.sp
.BR cap_iab_to_text ()
will convert an IAB tuple to a canonical text representation. The
representation is slightly redundant but libcap will try to generate
as short a representation as it is able.
.sp
.BR cap_iab_from_text ()
generates an IAB tuple from a text string (likely generated by the
previous function). The returned IAB tuple should be freed with
.BR cap_free (3).
.sp
The text format accepted by
.BR cap_iab_from_text ()
is a comma separated list of capability values. Each capability is
prefixed by nothing (or %) (Inh); ! (Bound, but think Blocked); ^
(Amb). Or, some combination thereof.  Since the Amb vector is
constrained to be no greater than the Inh vector, ^ is equivalent to
%^. Further, unless B is non-zero, % can be omitted. The following are
legal text representations: "!%cap_chown" (Bound but Inh),
"!cap_chown,^cap_chown" (Bound, Inh+Amb). "cap_setuid,!cap_chown"
(Inh, Bound). As noted above, this text representation is the syntax
for the \fIpam_cap.so\fP config file.
.sp
.BR cap_iab_get_vector ()
can be used to determine the specific capability value of an IAB
vector.
.sp
.BR cap_iab_compare ()
can be used to compare two cap_iab_t tuples. When the return value is
non-zero, the macro \fBCAP_IAB_DIFFERS\fR(\fIstatus\fR, \fIvector\fR)
evaluates to non-zero if the returned status differs in its
.I vector
components.
.sp
.BR cap_iab_set_vector ()
can be used to set a specific vector value to the enable setting.
.sp
.BR cap_iab_fill ()
can be used to wholesale copy a cap_t flag value into the vec vector
of the IAB tuple. Copying into Amb in this way may implicitly raise Inh
values in the IAB tuple. Similarly copying into the Inh vector may
implicitly lower Amb values that are not present in the resulting Inh
vector.
.sp
.BR cap_proc_root ()
can be used to determine the current location queried by
.BR cap_iab_get_pid ().
Returned values should be released with
.BR cap_free (3).
If the argument to
.BR cap_proc_root ()
is not \fBNULL\fP, a copy of it will become the replacement for
.BR /proc .
Note, this function is \fInot\fP thread safe with respect to
concurrent calls to
.BR cap_iab_get_pid ().
.SH "ERRORS"
The functions returning \fIcap_iab_t\fP values or allocated memory in
the form of a string return NULL on error.

Integer return values are -1 on error and 0 on success.

In the case of error consult \fIerrno\fP.
.SH "NOTES"
.PP
Unlike the traditional \fIcap_t\fP capability set, the
IAB tuple, taken together, is incompatible with filesystem capabilities
created via tools like
.BR setcap (8).
That is, the Amb vector of the IAB tuple is rendered moot when an
executable with a file capability is executed.
.PP
Further, there are libcap
.BR cap_mode (3)s
that render the Amb vector and its method of process inheritance
disabled.

.SH "HISTORY"
The IAB format for inheritable variants of capabilities was first
developed as the configuration syntax for the \fIpam_cap.so\fP
Linux-PAM module in libcap-2.29. It was introduced to extend the
\fIsimple\fP comma separated list of process Inheritable capabilities,
that the module could besow on an authenticated process tree, to
include enforced limits on the Bounding vector and introduce support
for the Amibient vector of capability bits.

While the Inheritable and Bounding vectors were anticipated by the
POSIX.1e draft that introduced capabilities, the Ambient vector is a
Linux invention, and incompatible with the POSIX.1e file capability
model. As such, it was felt that trying to meld together all of the 5
capability vectors into one text representation was not going to
work. Instead the \fIpam_cap.so\fP config syntax was generalized into
a whole set of libcap functions for bundling together all three
naively inheritable capabilities: the IAB tuple. The support for this
debuted in libcap-2.33.
.SH "REPORTING BUGS"
Please report bugs via:
.TP
https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757
.SH "SEE ALSO"
.BR libcap (3),
.BR cap_launch (3),
.BR cap_init (3),
.BR capabilities (7)
and
.BR errno (3).