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

2 files changed, 426 insertions, 12 deletions

diff --git a/lib/libc/posix1e/cap.3 b/lib/libc/posix1e/cap.3
index 22da6df644d6..15925859ae7d 100644
--- a/lib/libc/posix1e/cap.3
+++ b/lib/libc/posix1e/cap.3
@@ -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 .
diff --git a/lib/libposix1e/cap.3 b/lib/libposix1e/cap.3
index 22da6df644d6..15925859ae7d 100644
--- a/lib/libposix1e/cap.3
+++ b/lib/libposix1e/cap.3
@@ -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 .