.\"-
.\" 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 .