o Introduce a pile more documentation about capabilities, including

identification and descriptions of most capabilities, current inheritence
  rules, etc.  More to follow.

Reviewed by:	sheldonh
Obtained from:	TrustedBSD Project
This commit is contained in:
Robert Watson 2000-12-11 15:25:49 +00:00
parent b24f640551
commit 6fd0cf5eb0
Notes: svn2git 2020-12-20 02:59:44 +00:00
svn path=/head/; revision=69859
2 changed files with 426 additions and 12 deletions

View File

@ -23,7 +23,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\" $FreeBSD$
.\"
.\" TrustedBSD Project - support for POSIX.1e process capabilities
.\"
@ -45,7 +45,7 @@ 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_get_flagXX
.Bl -tag -width cap_from_textXX
.It Fn cap_init
This function is described in
.Xr cap_init 3 ,
@ -63,6 +63,11 @@ and may be used to duplicate a capability structure.
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 ,
@ -81,17 +86,213 @@ in the working store.
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 the FreeBSD 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 syscalls between the internal interfaces and the public library
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
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
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
@ -129,5 +330,11 @@ POSIX.1e support was introduced in
and development continues.
.Sh AUTHORS
.An Robert N M Watson
.An Ilmar S Habibulin
.Sh BUGS
These features are not yet included in the base FreeBSD distribution.
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 .

View File

@ -23,7 +23,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\" $FreeBSD$
.\"
.\" TrustedBSD Project - support for POSIX.1e process capabilities
.\"
@ -45,7 +45,7 @@ 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_get_flagXX
.Bl -tag -width cap_from_textXX
.It Fn cap_init
This function is described in
.Xr cap_init 3 ,
@ -63,6 +63,11 @@ and may be used to duplicate a capability structure.
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 ,
@ -81,17 +86,213 @@ in the working store.
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 the FreeBSD 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 syscalls between the internal interfaces and the public library
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
FreeBSD's support for POSIX.1e interfaces and features is still under
development at this time.
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
@ -129,5 +330,11 @@ POSIX.1e support was introduced in
and development continues.
.Sh AUTHORS
.An Robert N M Watson
.An Ilmar S Habibulin
.Sh BUGS
These features are not yet included in the base FreeBSD distribution.
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 .