165 lines
6.1 KiB
Groff
165 lines
6.1 KiB
Groff
.TH CAP_IAB 3 "2021-03-10" "" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
.nf
|
|
#include <sys/capability.h>
|
|
|
|
cap_iab_t cap_iab_init(void);
|
|
|
|
cap_iab_t cap_iab_get_proc(void);
|
|
|
|
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_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);
|
|
|
|
.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 set 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 set and the Permitted process capability
|
|
flag. They are: the Inh vector is entirely equal to the process
|
|
Inheritable flag at all times; the the Amb vector contains no more
|
|
capability values than the intersection of the Inh vector and the
|
|
Permitted flag for the process; no Amb value blocked in the Bound
|
|
Vector will survive
|
|
.BR execve (2);
|
|
and the Bound (or \fIblocked\fP) vector is the twos-complement of the
|
|
process bounding set.
|
|
.PP
|
|
In some environments, it is considered desirable to naively inherit
|
|
capabilities. That is pass capabilities, independent of the status of
|
|
the executed binary, from parent to child through exec* 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 pre-exec* process and
|
|
file-capability bestowed executable of the traditional capability
|
|
mechanism.
|
|
.PP
|
|
The convolution rules for IAB style inheritance are: I'=I; A'= A & ~B;
|
|
P'=A & ~B. 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 set 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 and capabilities through exec, but it won't bestow any
|
|
either. 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_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 and a superset of P values over the A and
|
|
I vectors.
|
|
.sp
|
|
.BR cap_iab_to_text ()
|
|
will convert an IAB set 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 set from a text string (likely generated by the
|
|
previous function). The returned IAB set 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); ^ (Amb). Or, some
|
|
combination thereof. Since the Amb vector is constrained to be no
|
|
greater than the Inh set, ^ is equivalent to %^. Further, unless B is
|
|
non-zero, % can be omitted. The following are legal text
|
|
representations: "!%cap_chown" (Bound but Inh),
|
|
"!cap_setuid,^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_set_vector ()
|
|
can be used to set a specific vector value to the enable setting.
|
|
.BR cap_iab_fill ()
|
|
can be used to wholesale copy a cap_t flag value into the vec vector
|
|
of the IAB set. Copying into Amb in this way may implicitly raise Inh
|
|
values in the IAB set. Similarly copying into the Inh vector may
|
|
implicitly lower Amb values that are not present in the resulting Inh
|
|
vector.
|
|
.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 set, taken together, is incompatible with filesystem capabilities
|
|
created via tools like
|
|
.BR setcap (8).
|
|
That is, the Amb vector of the IAB set 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 set and introduce support for
|
|
the Amibient set of capability bits.
|
|
|
|
While the Inheritable and Bounding sets were anticipated by the
|
|
POSIX.1e draft that introduced capabilities, the Ambient set 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 set. The support for this
|
|
debuted in libcap-2.33.
|
|
|
|
.SH "SEE ALSO"
|
|
.BR libcap (3),
|
|
.BR cap_launch (3),
|
|
.BR cap_init (3),
|
|
.BR capabilities (7)
|
|
and
|
|
.BR errno (3).
|