204 lines
7.4 KiB
Plaintext
204 lines
7.4 KiB
Plaintext
.TH CAP_IAB 3 "2025-03-19" "" "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
|
|
.RB ( CAP_IAB_INH )
|
|
is entirely equal to the process Inheritable flag at all times; the
|
|
Amb vector
|
|
.RB ( CAP_IAB_AMB )
|
|
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
|
|
.RB ( CAP_IAB_BOUND )
|
|
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. To raise
|
|
I bits not present in the P flag, or newly apply B masking, requires
|
|
.B CAP_SETPCAP
|
|
is present in the Permitted flag (the function will temporarily raise
|
|
it in the Effective flag if needed). In all cases, raised A values
|
|
must be present in the intersection of Permitted and Inh values.
|
|
.sp
|
|
.BR cap_iab_to_text ()
|
|
will convert an IAB tuple to a canonical IAB text representation. The
|
|
representation is slightly redundant but
|
|
.BR libcap (3) 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 ().
|
|
.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
|
|
.I cap_t
|
|
flag value into the vec vector of the IAB tuple. Copying into Amb
|
|
.RB ( CAP_IAB_AMB )
|
|
in this way may implicitly raise Inh
|
|
.RB ( CAP_IAB_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).
|