2 .\" Copyright (c) 2000 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" TrustedBSD Project - support for POSIX.1e process capabilities
35 .Nd introduction to the POSIX.1e Capability security API
39 .Fd #include <sys/types.h>
40 .Fd #include <sys/capability.h>
42 The POSIX.1e Capability interface allows processes to manipulate their
43 capability set, subject to capability manipulation restrictions imposed
44 by the kernel. Using the capability API, a process may request a copy
45 of its capability state, modify the copy of the state, and resubmit the
46 state for use, if permitted.
48 A variety of functions are provided for manipulating and managing
49 process capability state and working store state:
50 .Bl -tag -width cap_from_textXX
52 This function is described in
54 and may be used to allocate a fresh capability structure with no capability
57 This function is described in
59 and clears all capability flags in a capability structure.
61 This function is described in
63 and may be used to duplicate a capability structure.
65 This function is described in
67 and may be used to free a capability structure.
69 This function is described in
71 and may be used to convert a text-form capability to its internal
74 This function, described in
76 allows retrieval of a capability flag value from capability state in
79 This function, described in
81 allows retrieval of capability state for the current process.
83 This function, described in
85 allows setting of capability flag values in a capability structure held
88 This function, described in
90 allows setting of the current process capability state.
92 This function, described in
94 converts a capability from its internal representation to one that is
95 (more) readable by humans.
98 A number of capabilities exist, each mapping to the ability to violate
99 a particular aspect of the system policy.
100 Each capability in a capability set has three flags, indicating the
101 status of the capability with respect to the file or process it is
103 .Bl -tag -width CAP_INHERITABLEXX
105 If true, the capability will be used as necessary during accesses by
107 .It Dv CAP_INHERITABLE
108 If true, the capability will be passed through
110 invocations as appropriate.
112 If true, the capability is permitted for the process.
115 Capability inheritence occurs when processes invoke the
117 call, resulting in internal invocation of the
120 At that time, a processes capabilities are re-evaluated using a set of
122 These algorithms take into account the starting capabilities of the process
123 and the capabilities of the file being executed.
127 pP` = (fP & X) | (fI & pI)
131 p[IPE] represent the starting processes inheritted, permitted, and
133 p'[IPE] represent the new inheritted, permitted, and effective sets.
134 f[IPE] represent the file's inheritted, permitted, and effective sets.
135 X represents a global bounding set, currently un-implemented.
137 The following capabilities are defined and implemented in
140 .Bl -tag -width CAP_MAC_RELABEL_SUBJ
142 This capability overrides the restriction that a process cannot change the
143 user ID of a file it owns, and the restriction that the group ID supplied in
146 function shall be equal to either the group ID or one of the supplementary
147 group IDs of the calling process.
148 .It Dv CAP_DAC_EXECUTE
149 This capability overrides file mode execute access restrictions when accessing
152 ACLs are available, this capability overrides the ACL execute access
153 restrictions when accessing an object.
155 This capability overrides file mode write access restrictions when access an
158 ACLs are available, this capability also overrides the ACL write access
159 restrictions when accessing an object.
160 .It Dv CAP_DAC_READ_SEARCH
161 This capability overrides file mode read and search access restrictions
162 when accessing an object, and, if
164 ACLs are available, this capability overrides the ACL read and search access
165 restrictions when accessing an object.
167 This capability overrides the requirements that the user ID associated
168 with a process be equal to the file owner ID, execpt in the cases where the
169 CAP_FSETID capability is applicable.
170 In general, this capability, when effective, permits a process to perform
171 all the functions that any file owner would have for their files.
173 This capability overrides the following restrictions: that the effective
174 user ID of the calling process shall match the file owner when setting the
175 set-user-ID (S_ISUID) and set-group-ID (S_ISGID) bits on the file; that
176 the effective group ID or one of the supplementary group IDs of the calling
177 process shall match the group ID of the file when setting the set-group-ID
178 bit of the file; and that the set-user-ID and set-group-ID bits of the file
179 mode shall be cleared upon successful return from
182 Thie capability shall override the restriction that the real or effective
183 user ID of a process sending a signal must match the real of effective user
184 ID of the receiving process.
186 This capability is not available on the
189 On other platforms, this capabiity overrides the restriction that a process
190 cannot create or delete a hard link to a directory.
192 This capability overrides the restriction that a process cannot
193 set the file capability state of a file.
195 This capability overrides the restriction in the
197 function that a process cannot change its real group ID or change its
198 effective group ID to a value other than its real group ID.
200 This capability overrides the restriction in the
202 function that a process cannot change its real user ID or change its
203 effective user ID to a value other than the current real user ID.
204 .It Dv CAP_MAC_DOWNGRADE
205 This capability override the restriction that no process may downgrade
206 the MAC label of a file.
208 This capability overrides mandatory read access restrictions when accessing
210 .It Dv CAP_MAC_RELABEL_SUBJ
211 This capability overrides the restriction that a process may not modify
213 .It Dv CAP_MAC_UPGRADE
214 This capability overrides the restriction that no process may upgrade the
217 This capability overrides the mandatory write access restrictions when
219 .It Dv CAP_AUDIT_CONTROL
220 This capability overrides the restriction that a process cannot modify
221 audit control parameters.
222 .It Dv CAP_AUDIT_WRITE
223 This capability overrides the restriction that a process cannot write data
224 into the system audit trail.
226 This capability overrides the restriction that a process cannot expand its
227 capability set when invoking
229 .It Dv CAP_SYS_SETFFLAG
230 This capability overrides the restriction that a process cannot manipulate
231 the system file flags on a file system object.
232 For portability, equivilent to
233 .Dv CAP_LINUX_IMMUTABLE .
234 .It Dv CAP_NET_BIND_SERVICE
235 This capability overrides network namespace restrictions on process's
239 For example, this capability, when effective, can be used by a process to
240 bind a port number below 1024 in the IPv4 or IPv6 port spaces.
241 .It Dv CAP_NET_BROADCAST
244 This capability overrides the restriction that a process cannot create a
248 .It Dv CAP_SYS_MODULE
249 This capability overrides the restriction that a process cannot load or
250 unload kernel modules.
252 .It Dv CAP_SYS_CHROOT
253 This capability overrides the restriction that a process cannot invoke the
258 .It Dv CAP_SYS_PTRACE
259 This capability overrides the restriction that a process can only invoke
262 system call to debug another process if the target process has identical
263 real and effective user IDs.
265 This capability overrides the restriction that a process cannot enable,
266 configure, or disable system process accounting.
269 This capability overrides the restriction that a process cannot invoke
274 This capability overrides the restrictions that a process cannot use the
276 system call to decrease the priority to below that of itself, or modify the
277 priority of another process.
278 .It Dv CAP_SYS_RESOURCE
279 This capability overrides restrictions on how a process may modify its
280 soft and hard resource limits.
282 This capability overrides the restriction that a process may not modify the
283 system date and time.
284 .It Dv CAP_SYS_TTY_CONFIG
286 This capability overrides the restriction that a process may not create
290 Documentation of the internal kernel interfaces backing these calls may
293 The system calls between the internal interfaces and the public library
294 routines may change over time, and as such are not documented. They are
295 not intended to be called directly without going through the library.
296 .Sh IMPLEMENTATION NOTES
297 Support for POSIX.1e interfaces and features in
299 is still under development at this time.
301 POSIX.1e assigns security labels to all objects, extending the security
302 functionality described in POSIX.1. These additional labels provide
303 fine-grained discretionary access control, fine-grained capabilities,
304 and labels necessary for mandatory access control. POSIX.2c describes
305 a set of userland utilities for manipulating these labels. These userland
306 utilities are not bundled with
308 so as to discourage their
309 use in the short term.
323 POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion
324 of the draft continues on the cross-platform POSIX.1e implementation
325 mailing list. To join this list, see the
327 POSIX.1e implementation
328 page for more information.
330 Support for POSIX.1e Capabilities was developed as part of the TrustedBSD
332 POSIX.1e support was introduced in
334 and development continues.
336 .An Robert N M Watson
337 .An Ilmar S Habibulin
341 is fully implemented, supporting kernel code is not yet available in the
343 It is slated for inclusion prior to