diff options
Diffstat (limited to 'lib/libc/posix1e/cap.3')
| -rw-r--r-- | lib/libc/posix1e/cap.3 | 353 |
1 files changed, 0 insertions, 353 deletions
diff --git a/lib/libc/posix1e/cap.3 b/lib/libc/posix1e/cap.3 deleted file mode 100644 index f4fd4f8..0000000 --- a/lib/libc/posix1e/cap.3 +++ /dev/null @@ -1,353 +0,0 @@ -.\"- -.\" 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 -.In sys/types.h -.In sys/capability.h -.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 indent -.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 override -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 indent -.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 inheritance 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 inherited, permitted, and -effective sets. -p'[IPE] represent the new inherited, permitted, and effective sets. -f[IPE] represent the file's inherited, 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 indent -.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, except 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 -This 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 capability 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, equivalent 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 -This capability overrides the restriction that a process cannot -modify network interface data. -.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 -This capability overrides the restriction that a process cannot -read or write directly to -.Pa /dev/mem . -.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 -This capability overrides the restriction that a process cannot -perform system administrative tasks. -.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 -This capability overrides the restriction that a process may not -modify TTY configuration settings. -.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 . |
