diff options
Diffstat (limited to 'doc/cap_iab.3')
| -rw-r--r-- | doc/cap_iab.3 | 140 |
1 files changed, 89 insertions, 51 deletions
diff --git a/doc/cap_iab.3 b/doc/cap_iab.3 index a453428..3e6282d 100644 --- a/doc/cap_iab.3 +++ b/doc/cap_iab.3 @@ -1,27 +1,28 @@ -.TH CAP_IAB 3 "2021-03-10" "" "Linux Programmer's Manual" +.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. @@ -32,42 +33,45 @@ inheritable process capability vectors: Inh, Amb and Bound. This \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 +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 set and the Permitted process capability +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 the Amb vector contains no more +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; 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. +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 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. +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 & ~B; -P'=A & ~B. Where P etc are the pre-exec values and P' etc are the +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 set is managed: the IAB API. +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 and capabilities through exec, but it won't bestow any -either. The returned cap_iab_t should be freed with +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 () @@ -75,31 +79,41 @@ 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 and a superset of P values over the A and -I vectors. +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 set to a canonical text representation. The +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 set from a text string (likely generated by the -previous function). The returned IAB set should be freed with +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); ^ (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" +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 @@ -107,14 +121,35 @@ for the \fIpam_cap.so\fP config file. 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 set. Copying into Amb in this way may implicitly raise Inh -values in the IAB set. Similarly copying into the Inh vector may +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. @@ -125,10 +160,10 @@ 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 +IAB tuple, 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 +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 @@ -142,19 +177,22 @@ 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. +include enforced limits on the Bounding vector and introduce support +for the Amibient vector of capability bits. -While the Inheritable and Bounding sets were anticipated by the -POSIX.1e draft that introduced capabilities, the Ambient set is a +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 set. The support for this +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), |