Debian Codegraph @

doc/cap_iab.3

raw
1 .TH CAP_IAB 3 "2025-03-19" "" "Linux Programmer's Manual"
2 .SH NAME
3 cap_iab_init, cap_iab_dup, cap_iab_get_proc, cap_iab_get_pid, \
4 cap_iab_set_proc, cap_iab_to_text, cap_iab_from_text, \
5 cap_iab_get_vector, cap_iab_compare, cap_iab_set_vector, \
6 cap_iab_fill, cap_proc_root \- inheritable IAB tuple support functions
7 .SH SYNOPSIS
8 .nf
9 #include <sys/capability.h>
10
11 cap_iab_t cap_iab_init(void);
12 cap_iab_t cap_iab_dup(cap_iab_t iab);
13 cap_iab_t cap_iab_get_proc(void);
14 cap_iab_t cap_iab_get_pid(pid_t pid);
15 int cap_iab_set_proc(cap_iab_t iab);
16 char *cap_iab_to_text(cap_iab_t iab);
17 cap_iab_t cap_iab_from_text(const char *text);
18 cap_flag_value_t cap_iab_get_vector(cap_iab_t iab, cap_iab_vector_t vec,
19 cap_value_t val);
20 int cap_iab_compare(cap_iab_t a, cap_iab_t b);
21 int cap_iab_set_vector(cap_iab_t iab, cap_iab_vector_t vec, cap_value_t val,
22 cap_flag_value_t enable);
23 int cap_iab_fill(cap_iab_t iab, cap_iab_vector_t vec,
24 cap_t set, cap_flag_t flag);
25 char *cap_proc_root(const char *root);
26 .fi
27 .sp
28 Link with \fI\-lcap\fP.
29 .SH "DESCRIPTION"
30 The functions defined in this man page concern the three naively
31 inheritable process capability vectors: Inh, Amb and Bound. This
32 \fIIAB\fP 3-tuple of capability vectors, captured in type
33 \fIcap_iab_t\fP combine to pass capabilities from one process to
34 another through
35 .BR execve (2)
36 system calls. The convolution rules using the IAB tuple are a fail over
37 set of rules when the executed file has no configured
38 \fIfile-capabilities\fP.
39 .PP
40 There are some constraints enforced by the kernel with respect to the
41 three components of an IAB tuple and the Permitted process capability
42 flag. They are: the Inh vector
43 .RB ( CAP_IAB_INH )
44 is entirely equal to the process Inheritable flag at all times; the
45 Amb vector
46 .RB ( CAP_IAB_AMB )
47 contains no more capability values than the intersection of
48 the Inh vector and the Permitted flag for the process; and the Bound
49 (or \fIblocked\fP) vector
50 .RB ( CAP_IAB_BOUND )
51 is the twos-complement of the process bounding vector.
52 .PP
53 In some environments, it is considered desirable to \fInaively\fP
54 inherit capabilities. That is pass capabilities, independent of the
55 status of the executed binary, from parent to child through
56 \fBexec*\fP system calls. The surviving capabilities become the
57 Permitted flag for the post-exec process. This method of inheritance
58 differs significantly from the handshake inheritance between a
59 pre-exec* process and a file-capability bestowed executable of the
60 traditional (POSIX.1e) capability mechanism.
61 .PP
62 The convolution rules for IAB style inheritance are: I'=I; A'=A&I;
63 P'=A&I&P. Where P etc are the pre-exec values and P' etc are the
64 post-exec values.
65 .PP
66 With an understanding of these convolution rules, we can explain how
67 .BR libcap (3)
68 support for the IAB tuple is managed: the IAB API.
69 .PP
70 .BR cap_iab_init ()
71 returns an empty IAB value. That is a \fImostly-harmless\fP tuple. It
72 will not block any Permitted file capabilities through exec, but it
73 won't bestow any either. The returned \fIcap_iab_t\fP should be freed
74 with
75 .BR cap_free (3).
76 .sp
77 .BR cap_iab_dup ()
78 returns a copy of the specified IAB value. The returned cap_iab_t
79 should be freed with
80 .BR cap_free (3).
81 .sp
82 .BR cap_iab_get_proc ()
83 returns a copy of the IAB value for the current process. The returned
84 cap_iab_t should be freed with
85 .BR cap_free (3).
86 .sp
87 .BR cap_iab_get_pid ()
88 returns a copy of the IAB value for the specified process. The returned
89 cap_iab_t should be freed with
90 .BR cap_free (3).
91 This function defaults to searching
92 .BR /proc/ <PID> /status
93 for the IAB information, but that location can be overridden using the
94 .BR cap_proc_root ()
95 function.
96 .sp
97 .BR cap_iab_set_proc ()
98 can be used to set the IAB value carried by the current process. Such
99 a setting will fail if the process is insufficiently capable. To raise
100 I bits not present in the P flag, or newly apply B masking, requires
101 .B CAP_SETPCAP
102 is present in the Permitted flag (the function will temporarily raise
103 it in the Effective flag if needed). In all cases, raised A values
104 must be present in the intersection of Permitted and Inh values.
105 .sp
106 .BR cap_iab_to_text ()
107 will convert an IAB tuple to a canonical IAB text representation. The
108 representation is slightly redundant but
109 .BR libcap (3) will try to generate
110 as short a representation as it is able.
111 .sp
112 .BR cap_iab_from_text ()
113 generates an IAB tuple from a text string (likely generated by the
114 previous function). The returned IAB tuple should be freed with
115 .BR cap_free ().
116 .sp
117 .BR cap_iab_get_vector ()
118 can be used to determine the specific capability value of an IAB
119 vector.
120 .sp
121 .BR cap_iab_compare ()
122 can be used to compare two cap_iab_t tuples. When the return value is
123 non-zero, the macro \fBCAP_IAB_DIFFERS\fR(\fIstatus\fR, \fIvector\fR)
124 evaluates to non-zero if the returned status differs in its
125 .I vector
126 components.
127 .sp
128 .BR cap_iab_set_vector ()
129 can be used to set a specific vector value to the enable setting.
130 .sp
131 .BR cap_iab_fill ()
132 can be used to wholesale copy a
133 .I cap_t
134 flag value into the vec vector of the IAB tuple. Copying into Amb
135 .RB ( CAP_IAB_AMB )
136 in this way may implicitly raise Inh
137 .RB ( CAP_IAB_INH )
138 values in the IAB tuple. Similarly copying into the Inh vector may
139 implicitly lower Amb values that are not present in the resulting Inh
140 vector.
141 .sp
142 .BR cap_proc_root ()
143 can be used to determine the current location queried by
144 .BR cap_iab_get_pid ().
145 Returned values should be released with
146 .BR cap_free (3).
147 If the argument to
148 .BR cap_proc_root ()
149 is not \fBNULL\fP, a copy of it will become the replacement for
150 .BR /proc .
151 Note, this function is \fInot\fP thread safe with respect to
152 concurrent calls to
153 .BR cap_iab_get_pid ().
154 .SH "ERRORS"
155 The functions returning \fIcap_iab_t\fP values or allocated memory in
156 the form of a string return NULL on error.
157
158 Integer return values are -1 on error and 0 on success.
159
160 In the case of error consult \fIerrno\fP.
161 .SH "NOTES"
162 .PP
163 Unlike the traditional \fIcap_t\fP capability set, the
164 IAB tuple, taken together, is incompatible with filesystem capabilities
165 created via tools like
166 .BR setcap (8).
167 That is, the Amb vector of the IAB tuple is rendered moot when an
168 executable with a file capability is executed.
169 .PP
170 Further, there are libcap
171 .BR cap_mode (3)s
172 that render the Amb vector and its method of process inheritance
173 disabled.
174
175 .SH "HISTORY"
176 The IAB format for inheritable variants of capabilities was first
177 developed as the configuration syntax for the \fIpam_cap.so\fP
178 Linux-PAM module in libcap-2.29. It was introduced to extend the
179 \fIsimple\fP comma separated list of process Inheritable capabilities,
180 that the module could besow on an authenticated process tree, to
181 include enforced limits on the Bounding vector and introduce support
182 for the Amibient vector of capability bits.
183
184 While the Inheritable and Bounding vectors were anticipated by the
185 POSIX.1e draft that introduced capabilities, the Ambient vector is a
186 Linux invention, and incompatible with the POSIX.1e file capability
187 model. As such, it was felt that trying to meld together all of the 5
188 capability vectors into one text representation was not going to
189 work. Instead the \fIpam_cap.so\fP config syntax was generalized into
190 a whole set of libcap functions for bundling together all three
191 naively inheritable capabilities: the IAB tuple. The support for this
192 debuted in libcap-2.33.
193 .SH "REPORTING BUGS"
194 Please report bugs via:
195 .TP
196 https://bugzilla.kernel.org/buglist.cgi?component=libcap&list_id=1090757
197 .SH "SEE ALSO"
198 .BR libcap (3),
199 .BR cap_launch (3),
200 .BR cap_init (3),
201 .BR capabilities (7)
202 and
203 .BR errno (3).