.\"- .\" Copyright (c) 2000 Robert N. M. Watson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .\" TrustedBSD Project - support for POSIX.1e process capabilities .\" .Dd April 1, 2000 .Dt CAP 3 .Os .Sh NAME .Nm cap .Nd introduction to the POSIX.1e Capability security API .Sh LIBRARY .Lb libc .Sh SYNOPSIS .Fd #include .Fd #include .Sh DESCRIPTION The POSIX.1e Capability interface allows processes to manipulate their capability set, subject to capability manipulation restrictions imposed by the kernel. Using the capability API, a process may request a copy of its capability state, modify the copy of the state, and resubmit the state for use, if permitted. .Pp A variety of functions are provided for manipulating and managing process capability state and working store state: .Bl -tag -width cap_from_textXX .It Fn cap_init This function is described in .Xr cap_init 3 , and may be used to allocate a fresh capability structure with no capability flags set. .It Fn cap_clear This function is described in .Xr cap_clear 3 , and clears all capability flags in a capability structure. .It Fn cap_dup This function is described in .Xr cap_dup 3 , and may be used to duplicate a capability structure. .It Fn cap_free This function is described in .Xr cap_free 3 , and may be used to free a capability structure. .It Fn cap_from_text This function is described in .Xr cap_from_text 3 , and may be used to convert a text-form capability to its internal representation. .It Fn cap_get_flag This function, described in .Xr cap_get_flag 3 , allows retrieval of a capability flag value from capability state in working store. .It Fn cap_get_proc This function, described in .Xr cap_get_proc 3 , allows retrieval of capability state for the current process. .It Fn cap_set_flag This function, described in .Xr cap_set_flag 3 , allows setting of capability flag values in a capability structure held in the working store. .It Fn cap_set_proc This function, described in .Xr cap_set_proc 3 , allows setting of the current process capability state. .It Fn cap_to_text This function, described in .Xr cap_to_text 3 , converts a capability from its internal representation to one that is (more) readable by humans. .El .Pp A number of capabilities exist, each mapping to the ability to violate a particular aspect of the system policy. Each capability in a capability set has three flags, indicating the status of the capability with respect to the file or process it is associated with. .Bl -tag -width CAP_INHERITABLEXX .It Dv CAP_EFFECTIVE If true, the capability will be used as necessary during accesses by the process. .It Dv CAP_INHERITABLE If true, the capability will be passed through .Xr execve 2 invocations as appropriate. .It Dv CAP_PERMITTED If true, the capability is permitted for the process. .El .Pp Capability inheritence occurs when processes invoke the .Xr exec 3 call, resulting in internal invocation of the .Xr execve 2 system call. At that time, a processes capabilities are re-evaluated using a set of fixed algorithms. These algorithms take into account the starting capabilities of the process and the capabilities of the file being executed. .Pp pI` = pI .Pp pP` = (fP & X) | (fI & pI) .Pp pE` = (fE & pP`) .Pp p[IPE] represent the starting processes inheritted, permitted, and effective sets. p'[IPE] represent the new inheritted, permitted, and effective sets. f[IPE] represent the file's inheritted, permitted, and effective sets. X represents a global bounding set, currently un-implemented. .Pp The following capabilities are defined and implemented in .Fx 5.0 : .Pp .Bl -tag -width CAP_MAC_RELABEL_SUBJ .It Dv CAP_CHOWN This capability overrides the restriction that a process cannot change the user ID of a file it owns, and the restriction that the group ID supplied in the .Xr chown 2 function shall be equal to either the group ID or one of the supplementary group IDs of the calling process. .It Dv CAP_DAC_EXECUTE This capability overrides file mode execute access restrictions when accessing an object, and, if .Xr posix1e 3 ACLs are available, this capability overrides the ACL execute access restrictions when accessing an object. .It Dv CAP_DAC_WRITE This capability overrides file mode write access restrictions when access an object, and, if .Xr posix1e 3 ACLs are available, this capability also overrides the ACL write access restrictions when accessing an object. .It Dv CAP_DAC_READ_SEARCH This capability overrides file mode read and search access restrictions when accessing an object, and, if .Xr posix1e 3 ACLs are available, this capability overrides the ACL read and search access restrictions when accessing an object. .It Dv CAP_FOWNER This capability overrides the requirements that the user ID associated with a process be equal to the file owner ID, execpt in the cases where the CAP_FSETID capability is applicable. In general, this capability, when effective, permits a process to perform all the functions that any file owner would have for their files. .It Dv CAP_FSETID This capability overrides the following restrictions: that the effective user ID of the calling process shall match the file owner when setting the set-user-ID (S_ISUID) and set-group-ID (S_ISGID) bits on the file; that the effective group ID or one of the supplementary group IDs of the calling process shall match the group ID of the file when setting the set-group-ID bit of the file; and that the set-user-ID and set-group-ID bits of the file mode shall be cleared upon successful return from .Xr chown 2 . .It Dv CAP_KILL Thie capability shall override the restriction that the real or effective user ID of a process sending a signal must match the real of effective user ID of the receiving process. .It Dv CAP_LINK_DIR This capability is not available on the .Fx platform. On other platforms, this capabiity overrides the restriction that a process cannot create or delete a hard link to a directory. .It Dv CAP_SETFCAP This capability overrides the restriction that a process cannot set the file capability state of a file. .It Dv CAP_SETGID This capability overrides the restriction in the .Xr setgid 2 function that a process cannot change its real group ID or change its effective group ID to a value other than its real group ID. .It Dv CAP_SETUID This capability overrides the restriction in the .Xr setuid 2 function that a process cannot change its real user ID or change its effective user ID to a value other than the current real user ID. .It Dv CAP_MAC_DOWNGRADE This capability override the restriction that no process may downgrade the MAC label of a file. .It Dv CAP_MAC_READ This capability overrides mandatory read access restrictions when accessing objects. .It Dv CAP_MAC_RELABEL_SUBJ This capability overrides the restriction that a process may not modify its own MAC label. .It Dv CAP_MAC_UPGRADE This capability overrides the restriction that no process may upgrade the MAC label of a file. .It Dv CAP_MAC_WRITE This capability overrides the mandatory write access restrictions when accessing objects. .It Dv CAP_AUDIT_CONTROL This capability overrides the restriction that a process cannot modify audit control parameters. .It Dv CAP_AUDIT_WRITE This capability overrides the restriction that a process cannot write data into the system audit trail. .It Dv CAP_SETPCAP This capability overrides the restriction that a process cannot expand its capability set when invoking .Xr cap_set_proc 3 . .It Dv CAP_SYS_SETFFLAG This capability overrides the restriction that a process cannot manipulate the system file flags on a file system object. For portability, equivilent to .Dv CAP_LINUX_IMMUTABLE . .It Dv CAP_NET_BIND_SERVICE This capability overrides network namespace restrictions on process's using the .Xr bind 2 system call. For example, this capability, when effective, can be used by a process to bind a port number below 1024 in the IPv4 or IPv6 port spaces. .It Dv CAP_NET_BROADCAST .It Dv CAP_NET_ADMIN .It Dv CAP_NET_RAW This capability overrides the restriction that a process cannot create a raw socket. .It Dv CAP_IPC_LOCK .It Dv CAP_IPC_OWNER .It Dv CAP_SYS_MODULE This capability overrides the restriction that a process cannot load or unload kernel modules. .It Dv CAP_SYS_RAWIO .It Dv CAP_SYS_CHROOT This capability overrides the restriction that a process cannot invoke the .Xr chroot 2 or .Xr jail 2 system calls. .It Dv CAP_SYS_PTRACE This capability overrides the restriction that a process can only invoke the .Xr ptrace 2 system call to debug another process if the target process has identical real and effective user IDs. .It Dv CAP_SYS_PACCT This capability overrides the restriction that a process cannot enable, configure, or disable system process accounting. .It Dv CAP_SYS_ADMIN .It Dv CAP_SYS_BOOT This capability overrides the restriction that a process cannot invoke the .Xr boot 2 system call. .It Dv CAP_SYS_NICE This capability overrides the restrictions that a process cannot use the .Xr setpriority 2 system call to decrease the priority to below that of itself, or modify the priority of another process. .It Dv CAP_SYS_RESOURCE This capability overrides restrictions on how a process may modify its soft and hard resource limits. .It Dv CAP_SYS_TIME This capability overrides the restriction that a process may not modify the system date and time. .It Dv CAP_SYS_TTY_CONFIG .It Dv CAP_MKNOD This capability overrides the restriction that a process may not create device nodes. .El .Pp Documentation of the internal kernel interfaces backing these calls may be found in .Xr cap 9 . The system calls between the internal interfaces and the public library routines may change over time, and as such are not documented. They are not intended to be called directly without going through the library. .Sh IMPLEMENTATION NOTES Support for POSIX.1e interfaces and features in .Fx is still under development at this time. .Pp POSIX.1e assigns security labels to all objects, extending the security functionality described in POSIX.1. These additional labels provide fine-grained discretionary access control, fine-grained capabilities, and labels necessary for mandatory access control. POSIX.2c describes a set of userland utilities for manipulating these labels. These userland utilities are not bundled with .Fx 5.0 so as to discourage their use in the short term. .\" .Sh FILES .Sh SEE ALSO .Xr cap_clear 3 , .Xr cap_dup 3 , .Xr cap_free 3 , .Xr cap_get_flag 3 , .Xr cap_get_proc 3 , .Xr cap_init 3 , .Xr cap_set_flag 3 , .Xr cap_set_proc 3 , .Xr posix1e 3 , .Xr cap 9 .Sh STANDARDS POSIX.1e is described in IEEE POSIX.1e draft 17. Discussion of the draft continues on the cross-platform POSIX.1e implementation mailing list. To join this list, see the .Fx POSIX.1e implementation page for more information. .Sh HISTORY Support for POSIX.1e Capabilities was developed as part of the TrustedBSD Project. POSIX.1e support was introduced in .Fx 4.0 , and development continues. .Sh AUTHORS .An Robert N M Watson .An Ilmar S Habibulin .Sh BUGS While .Xr posix1e 3 is fully implemented, supporting kernel code is not yet available in the base distribution. It is slated for inclusion prior to .Fx 5.0 .