345 lines
12 KiB
Groff
345 lines
12 KiB
Groff
.\"-
|
|
.\" 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 <sys/types.h>
|
|
.Fd #include <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 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 .
|