diff options
Diffstat (limited to 'lib/libc/posix1e/cap.3')
| -rw-r--r-- | lib/libc/posix1e/cap.3 | 353 |
1 files changed, 353 insertions, 0 deletions
diff --git a/lib/libc/posix1e/cap.3 b/lib/libc/posix1e/cap.3 new file mode 100644 index 0000000..4bd0fd9 --- /dev/null +++ b/lib/libc/posix1e/cap.3 @@ -0,0 +1,353 @@ +.\"- +.\" 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 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 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, 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 +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 . |
