Provided by: libcap-dev_2.66-5ubuntu2_amd64 bug

NAME

       #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);

       Link with -lcap.

DESCRIPTION

       The  functions  defined  in  this  man  page concern the three naively inheritable process
       capability vectors: Inh, Amb and Bound. This IAB 3-tuple of capability  vectors,  captured
       in  type  cap_iab_t  combine  to  pass  capabilities  from  one process to another through
       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 file-capabilities.

       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  blocked) vector is the twos-complement of the process
       bounding vector.

       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 a pre-exec* process and a file-capability bestowed executable  of  the
       traditional (POSIX.1e) capability mechanism.

       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.

       With an understanding of these convolution rules, we can explain how libcap(3) support for
       the IAB tuple is managed: the IAB API.

       cap_iab_init()  returns  an  empty IAB value. That is a mostly-harmless tuple. It will not
       block any Permitted file capabilities through exec, but it won't bestow  any  either.  The
       returned cap_iab_t should be freed with cap_free(3).

       cap_iab_dup() returns a copy of the specified IAB value.  The returned cap_iab_t should be
       freed with cap_free(3).

       cap_iab_get_proc() returns a copy of the IAB value for the current process.  The  returned
       cap_iab_t should be freed with cap_free(3).

       cap_iab_get_pid() returns a copy of the IAB value for the specified process.  The returned
       cap_iab_t should be freed with cap_free(3).

       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.

       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.

       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 cap_free(3).

       The text format accepted by 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 pam_cap.so config file.

       cap_iab_get_vector() can be used to determine the specific  capability  value  of  an  IAB
       vector.

       cap_iab_compare()  can  be  used to compare two cap_iab_t tuples. When the return value is
       non-zero, the macro CAP_IAB_DIFFERS(status, vector) evaluates to non-zero if the  returned
       status differs in its vector components.

       cap_iab_set_vector() can be used to set a specific vector value to the enable setting.

       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.

ERRORS

       The functions returning cap_iab_t 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 errno.

NOTES

       Unlike   the  traditional  cap_t  capability  set,  the  IAB  tuple,  taken  together,  is
       incompatible with filesystem capabilities created via tools like setcap(8).  That is,  the
       Amb  vector of the IAB tuple is rendered moot when an executable with a file capability is
       executed.

       Further, there are libcap cap_mode(3)s that render  the  Amb  vector  and  its  method  of
       process inheritance disabled.

HISTORY

       The  IAB  format  for  inheritable  variants  of  capabilities  was first developed as the
       configuration syntax for the pam_cap.so Linux-PAM module in libcap-2.29. It was introduced
       to  extend  the  simple 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  pam_cap.so  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.

REPORTING BUGS

       Please report bugs via:

       https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757

SEE ALSO

       libcap(3), cap_launch(3), cap_init(3), capabilities(7) and errno(3).

                                            2021-11-17                                 CAP_IAB(3)