Index: head/share/man/man4/rights.4
===================================================================
--- head/share/man/man4/rights.4	(revision 316035)
+++ head/share/man/man4/rights.4	(revision 316036)
@@ -1,713 +1,713 @@
 .\"
 .\" Copyright (c) 2008-2010 Robert N. M. Watson
 .\" Copyright (c) 2012-2013 The FreeBSD Foundation
 .\" All rights reserved.
 .\"
 .\" This software was developed at the University of Cambridge Computer
 .\" Laboratory with support from a grant from Google, Inc.
 .\"
 .\" Portions of this documentation were written by Pawel Jakub Dawidek
 .\" under sponsorship from the FreeBSD Foundation.
 .\"
 .\" 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$
 .\"
 .Dd August 17, 2016
 .Dt RIGHTS 4
 .Os
 .Sh NAME
 .Nm Capability rights
 .Nd Capsicum capability rights for file descriptors
 .Sh DESCRIPTION
 When a file descriptor is created by a function such as
 .Xr accept 2 ,
 .Xr accept4 2 ,
 .Xr fhopen 2 ,
 .Xr kqueue 2 ,
 .Xr mq_open 2 ,
 .Xr open 2 ,
 .Xr openat 2 ,
 .Xr pdfork 2 ,
 .Xr pipe 2 ,
 .Xr shm_open 2 ,
 .Xr socket 2
 or
 .Xr socketpair 2 ,
 it is assigned all capability rights.
 Those rights can be reduced (but never expanded) by using the
 .Xr cap_rights_limit 2 ,
 .Xr cap_fcntls_limit 2 and
 .Xr cap_ioctls_limit 2
 system calls.
 Once capability rights are reduced, operations on the file descriptor will be
 limited to those permitted by rights.
 .Pp
 The complete list of capability rights is provided below.
 The
 .Vt cap_rights_t
 type is used to store list of capability rights.
 The
 .Xr cap_rights_init 3
 family of functions should be used to manage the structure.
 .Sh RIGHTS
 The following rights may be specified in a rights mask:
 .Bl -tag -width CAP_RENAMEAT_SOURCE
 .It Dv CAP_ACCEPT
 Permit
 .Xr accept 2
 and
 .Xr accept4 2 .
 .It Dv CAP_ACL_CHECK
 Permit
 .Xr acl_valid_fd_np 3 .
 .It Dv CAP_ACL_DELETE
 Permit
 .Xr acl_delete_fd_np 3 .
 .It Dv CAP_ACL_GET
 Permit
 .Xr acl_get_fd 3
 and
 .Xr acl_get_fd_np 3 .
 .It Dv CAP_ACL_SET
 Permit
 .Xr acl_set_fd 3
 and
 .Xr acl_set_fd_np 3 .
 .It Dv CAP_BIND
 Permit
 .Xr bind 2 .
 Note that sockets can also become bound implicitly as a result of
 .Xr connect 2
 or
 .Xr send 2 ,
 and that socket options set with
 .Xr setsockopt 2
 may also affect binding behavior.
 .It Dv CAP_BINDAT
 Permit
 .Xr bindat 2 .
 This right has to be present on the directory descriptor.
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .It Dv CAP_CHFLAGSAT
 An alias to
 .Dv CAP_FCHFLAGS
 and
 .Dv CAP_LOOKUP .
 .It Dv CAP_CONNECT
 Permit
 .Xr connect 2 ;
 also required for
 .Xr sendto 2
 with a non-NULL destination address.
 .It Dv CAP_CONNECTAT
 Permit
 .Xr connectat 2 .
 This right has to be present on the directory descriptor.
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .It Dv CAP_CREATE
 Permit
 .Xr openat 2
 with the
 .Dv O_CREAT
 flag.
 .It Dv CAP_EVENT
 Permit
 .Xr select 2 ,
 .Xr poll 2 ,
 and
 .Xr kevent 2
 to be used in monitoring the file descriptor for events.
 .It Dv CAP_EXTATTR_DELETE
 Permit
 .Xr extattr_delete_fd 2 .
 .It Dv CAP_EXTATTR_GET
 Permit
 .Xr extattr_get_fd 2 .
 .It Dv CAP_EXTATTR_LIST
 Permit
 .Xr extattr_list_fd 2 .
 .It Dv CAP_EXTATTR_SET
 Permit
 .Xr extattr_set_fd 2 .
 .It Dv CAP_FCHDIR
 Permit
 .Xr fchdir 2 .
 .It Dv CAP_FCHFLAGS
 Permit
 .Xr fchflags 2
 and
 .Xr chflagsat 2
 if the
 .Dv CAP_LOOKUP
 right is also present.
 .It Dv CAP_FCHMOD
 Permit
 .Xr fchmod 2
 and
 .Xr fchmodat 2
 if the
 .Dv CAP_LOOKUP
 right is also present.
 .It Dv CAP_FCHMODAT
 An alias to
 .Dv CAP_FCHMOD
 and
 .Dv CAP_LOOKUP .
 .It Dv CAP_FCHOWN
 Permit
 .Xr fchown 2
 and
 .Xr fchownat 2
 if the
 .Dv CAP_LOOKUP
 right is also present.
 .It Dv CAP_FCHOWNAT
 An alias to
 .Dv CAP_FCHOWN
 and
 .Dv CAP_LOOKUP .
 .It Dv CAP_FCNTL
 Permit
 .Xr fcntl 2 .
 Note that only the
 .Dv F_GETFL ,
 .Dv F_SETFL ,
 .Dv F_GETOWN
 and
 .Dv F_SETOWN
 commands require this capability right.
 Also note that the list of permitted commands can be further limited with the
 .Xr cap_fcntls_limit 2
 system call.
 .It Dv CAP_FEXECVE
 Permit
 .Xr fexecve 2
 and
 .Xr openat 2
 with the
 .Dv O_EXEC
 flag;
 .Dv CAP_READ
-is also be required.
+is also required.
 .It Dv CAP_FLOCK
 Permit
 .Xr flock 2 ,
 .Xr fcntl 2
 (with
 .Dv F_GETLK ,
 .Dv F_SETLK ,
 .Dv F_SETLKW
 or
 .Dv F_SETLK_REMOTE
 flag) and
 .Xr openat 2
 (with
 .Dv O_EXLOCK
 or
 .Dv O_SHLOCK
 flag).
 .It Dv CAP_FPATHCONF
 Permit
 .Xr fpathconf 2 .
 .It Dv CAP_FSCK
 Permit UFS background-fsck operations on the descriptor.
 .It Dv CAP_FSTAT
 Permit
 .Xr fstat 2
 and
 .Xr fstatat 2
 if the
 .Dv CAP_LOOKUP
 right is also present.
 .It Dv CAP_FSTATAT
 An alias to
 .Dv CAP_FSTAT
 and
 .Dv CAP_LOOKUP .
 .It Dv CAP_FSTATFS
 Permit
 .Xr fstatfs 2 .
 .It Dv CAP_FSYNC
 Permit
 .Xr aio_fsync 2 ,
 .Xr fdatasync 2 ,
 .Xr fsync 2
 and
 .Xr openat 2
 with
 .Dv O_FSYNC
 or
 .Dv O_SYNC
 flag.
 .It Dv CAP_FTRUNCATE
 Permit
 .Xr ftruncate 2
 and
 .Xr openat 2
 with the
 .Dv O_TRUNC
 flag.
 .It Dv CAP_FUTIMES
 Permit
 .Xr futimens 2
 and
 .Xr futimes 2 ,
 and permit
 .Xr futimesat 2
 and
 .Xr utimensat 2
 if the
 .Dv CAP_LOOKUP
 right is also present.
 .It Dv CAP_FUTIMESAT
 An alias to
 .Dv CAP_FUTIMES
 and
 .Dv CAP_LOOKUP .
 .It Dv CAP_GETPEERNAME
 Permit
 .Xr getpeername 2 .
 .It Dv CAP_GETSOCKNAME
 Permit
 .Xr getsockname 2 .
 .It Dv CAP_GETSOCKOPT
 Permit
 .Xr getsockopt 2 .
 .It Dv CAP_IOCTL
 Permit
 .Xr ioctl 2 .
 Be aware that this system call has enormous scope, including potentially
 global scope for some objects.
 The list of permitted ioctl commands can be further limited with the
 .Xr cap_ioctls_limit 2
 system call.
 .It Dv CAP_KQUEUE
 An alias to
 .Dv CAP_KQUEUE_CHANGE
 and
 .Dv CAP_KQUEUE_EVENT .
 .It Dv CAP_KQUEUE_CHANGE
 Permit
 .Xr kevent 2
 on a
 .Xr kqueue 2
 descriptor that modifies list of monitored events (the
 .Fa changelist
 argument is non-NULL).
 .It Dv CAP_KQUEUE_EVENT
 Permit
 .Xr kevent 2
 on a
 .Xr kqueue 2
 descriptor that monitors events (the
 .Fa eventlist
 argument is non-NULL).
 .Dv CAP_EVENT
 is also required on file descriptors that will be monitored using
 .Xr kevent 2 .
 .It Dv CAP_LINKAT_SOURCE
 Permit
 .Xr linkat 2
 on the source directory descriptor.
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .Pp
 Warning:
 .Dv CAP_LINKAT_SOURCE
 makes it possible to link files in a directory for which file
 descriptors exist that have additional rights.
 For example,
 a file stored in a directory that does not allow
 .Dv CAP_READ
 may be linked in another directory that does allow
 .Dv CAP_READ ,
 thereby granting read access to a file that is otherwise unreadable.
 .It Dv CAP_LINKAT_TARGET
 Permit
 .Xr linkat 2
 on the target directory descriptor.
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .It Dv CAP_LISTEN
 Permit
 .Xr listen 2 ;
 not much use (generally) without
 .Dv CAP_BIND .
 .It Dv CAP_LOOKUP
 Permit the file descriptor to be used as a starting directory for calls such as
 .Xr linkat 2 ,
 .Xr openat 2 ,
 and
 .Xr unlinkat 2 .
 .It Dv CAP_MAC_GET
 Permit
 .Xr mac_get_fd 3 .
 .It Dv CAP_MAC_SET
 Permit
 .Xr mac_set_fd 3 .
 .It Dv CAP_MKDIRAT
 Permit
 .Xr mkdirat 2 .
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .It Dv CAP_MKFIFOAT
 Permit
 .Xr mkfifoat 2 .
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .It Dv CAP_MKNODAT
 Permit
 .Xr mknodat 2 .
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .It Dv CAP_MMAP
 Permit
 .Xr mmap 2
 with the
 .Dv PROT_NONE
 protection.
 .It Dv CAP_MMAP_R
 Permit
 .Xr mmap 2
 with the
 .Dv PROT_READ
 protection.
 This right includes the
 .Dv CAP_READ
 and
 .Dv CAP_SEEK
 rights.
 .It Dv CAP_MMAP_RW
 An alias to
 .Dv CAP_MMAP_R
 and
 .Dv CAP_MMAP_W .
 .It Dv CAP_MMAP_RWX
 An alias to
 .Dv CAP_MMAP_R ,
 .Dv CAP_MMAP_W
 and
 .Dv CAP_MMAP_X .
 .It Dv CAP_MMAP_RX
 An alias to
 .Dv CAP_MMAP_R
 and
 .Dv CAP_MMAP_X .
 .It Dv CAP_MMAP_W
 Permit
 .Xr mmap 2
 with the
 .Dv PROT_WRITE
 protection.
 This right includes the
 .Dv CAP_WRITE
 and
 .Dv CAP_SEEK
 rights.
 .It Dv CAP_MMAP_WX
 An alias to
 .Dv CAP_MMAP_W
 and
 .Dv CAP_MMAP_X .
 .It Dv CAP_MMAP_X
 Permit
 .Xr mmap 2
 with the
 .Dv PROT_EXEC
 protection.
 This right includes the
 .Dv CAP_SEEK
 right.
 .It Dv CAP_PDGETPID
 Permit
 .Xr pdgetpid 2 .
 .It Dv CAP_PDKILL
 Permit
 .Xr pdkill 2 .
 .It Dv CAP_PDWAIT
 Permit
 .Xr pdwait4 2 .
 .It Dv CAP_PEELOFF
 Permit
 .Xr sctp_peeloff 2 .
 .It Dv CAP_PREAD
 An alias to
 .Dv CAP_READ
 and
 .Dv CAP_SEEK .
 .It Dv CAP_PWRITE
 An alias to
 .Dv CAP_SEEK
 and
 .Dv CAP_WRITE .
 .It Dv CAP_READ
 Permit
 .Xr aio_read 2
 .Dv ( CAP_SEEK
 is also required),
 .Xr openat 2
 with the
 .Dv O_RDONLY flag,
 .Xr read 2 ,
 .Xr readv 2 ,
 .Xr recv 2 ,
 .Xr recvfrom 2 ,
 .Xr recvmsg 2 ,
 .Xr pread 2
 .Dv ( CAP_SEEK
 is also required),
 .Xr preadv 2
 .Dv ( CAP_SEEK
 is also required) and related system calls.
 .It Dv CAP_RECV
 An alias to
 .Dv CAP_READ .
 .It Dv CAP_RENAMEAT_SOURCE
 Permit
 .Xr renameat 2
 on the source directory descriptor.
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .Pp
 Warning:
 .Dv CAP_RENAMEAT_SOURCE
 makes it possible to move files to a directory for which file
 descriptors exist that have additional rights.
 For example,
 a file stored in a directory that does not allow
 .Dv CAP_READ
 may be moved to another directory that does allow
 .Dv CAP_READ ,
 thereby granting read access to a file that is otherwise unreadable.
 .It Dv CAP_RENAMEAT_TARGET
 Permit
 .Xr renameat 2
 on the target directory descriptor.
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .It Dv CAP_SEEK
 Permit operations that seek on the file descriptor, such as
 .Xr lseek 2 ,
 but also required for I/O system calls that can read or write at any position
 in the file, such as
 .Xr pread 2
 and
 .Xr pwrite 2 .
 .It Dv CAP_SEM_GETVALUE
 Permit
 .Xr sem_getvalue 3 .
 .It Dv CAP_SEM_POST
 Permit
 .Xr sem_post 3 .
 .It Dv CAP_SEM_WAIT
 Permit
 .Xr sem_wait 3
 and
 .Xr sem_trywait 3 .
 .It Dv CAP_SEND
 An alias to
 .Dv CAP_WRITE .
 .It Dv CAP_SETSOCKOPT
 Permit
 .Xr setsockopt 2 ;
 this controls various aspects of socket behavior and may affect binding,
 connecting, and other behaviors with global scope.
 .It Dv CAP_SHUTDOWN
 Permit explicit
 .Xr shutdown 2 ;
 closing the socket will also generally shut down any connections on it.
 .It Dv CAP_SYMLINKAT
 Permit
 .Xr symlinkat 2 .
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .It Dv CAP_TTYHOOK
 Allow configuration of TTY hooks, such as
 .Xr snp 4 ,
 on the file descriptor.
 .It Dv CAP_UNLINKAT
 Permit
 .Xr unlinkat 2
 and
 .Xr renameat 2 .
 This right is only required for
 .Xr renameat 2
 on the destination directory descriptor if the destination object already
 exists and will be removed by the rename.
 This right includes the
 .Dv CAP_LOOKUP
 right.
 .It Dv CAP_WRITE
 Allow
 .Xr aio_write 2 ,
 .Xr openat 2
 with
 .Dv O_WRONLY
 and
 .Dv O_APPEND
 flags set,
 .Xr send 2 ,
 .Xr sendmsg 2 ,
 .Xr sendto 2 ,
 .Xr write 2 ,
 .Xr writev 2 ,
 .Xr pwrite 2 ,
 .Xr pwritev 2
 and related system calls.
 For
 .Xr sendto 2
 with a non-NULL connection address,
 .Dv CAP_CONNECT
 is also required.
 For
 .Xr openat 2
 with the
 .Dv O_WRONLY
 flag, but without the
 .Dv O_APPEND
 flag,
 .Dv CAP_SEEK
 is also required.
 For
 .Xr aio_write 2 ,
 .Xr pwrite 2
 and
 .Xr pwritev 2
 .Dv CAP_SEEK
 is also required.
 .El
 .Sh SEE ALSO
 .Xr accept 2 ,
 .Xr accept4 2 ,
 .Xr aio_fsync 2 ,
 .Xr aio_read 2 ,
 .Xr aio_write 2 ,
 .Xr bind 2 ,
 .Xr bindat 2 ,
 .Xr cap_enter 2 ,
 .Xr cap_fcntls_limit 2 ,
 .Xr cap_ioctls_limit 2 ,
 .Xr cap_rights_limit 2 ,
 .Xr chflagsat 2 ,
 .Xr connect 2 ,
 .Xr connectat 2 ,
 .Xr extattr_delete_fd 2 ,
 .Xr extattr_get_fd 2 ,
 .Xr extattr_list_fd 2 ,
 .Xr extattr_set_fd 2 ,
 .Xr fchflags 2 ,
 .Xr fchmod 2 ,
 .Xr fchmodat 2 ,
 .Xr fchown 2 ,
 .Xr fchownat 2 ,
 .Xr fcntl 2 ,
 .Xr fexecve 2 ,
 .Xr fhopen 2 ,
 .Xr flock 2 ,
 .Xr fpathconf 2 ,
 .Xr fstat 2 ,
 .Xr fstatat 2 ,
 .Xr fstatfs 2 ,
 .Xr fsync 2 ,
 .Xr ftruncate 2 ,
 .Xr futimes 2 ,
 .Xr getpeername 2 ,
 .Xr getsockname 2 ,
 .Xr getsockopt 2 ,
 .Xr ioctl 2 ,
 .Xr kevent 2 ,
 .Xr kqueue 2 ,
 .Xr linkat 2 ,
 .Xr listen 2 ,
 .Xr mmap 2 ,
 .Xr mq_open 2 ,
 .Xr open 2 ,
 .Xr openat 2 ,
 .Xr pdfork 2 ,
 .Xr pdgetpid 2 ,
 .Xr pdkill 2 ,
 .Xr pdwait4 2 ,
 .Xr pipe 2 ,
 .Xr poll 2 ,
 .Xr pread 2 ,
 .Xr preadv 2 ,
 .Xr pwrite 2 ,
 .Xr pwritev 2 ,
 .Xr read 2 ,
 .Xr readv 2 ,
 .Xr recv 2 ,
 .Xr recvfrom 2 ,
 .Xr recvmsg 2 ,
 .Xr renameat 2 ,
 .Xr sctp_peeloff 2 ,
 .Xr select 2 ,
 .Xr send 2 ,
 .Xr sendmsg 2 ,
 .Xr sendto 2 ,
 .Xr setsockopt 2 ,
 .Xr shm_open 2 ,
 .Xr shutdown 2 ,
 .Xr socket 2 ,
 .Xr socketpair 2 ,
 .Xr symlinkat 2 ,
 .Xr unlinkat 2 ,
 .Xr write 2 ,
 .Xr writev 2 ,
 .Xr acl_delete_fd_np 3 ,
 .Xr acl_get_fd 3 ,
 .Xr acl_get_fd_np 3 ,
 .Xr acl_set_fd 3 ,
 .Xr acl_set_fd_np 3 ,
 .Xr acl_valid_fd_np 3 ,
 .Xr mac_get_fd 3 ,
 .Xr mac_set_fd 3 ,
 .Xr sem_getvalue 3 ,
 .Xr sem_post 3 ,
 .Xr sem_trywait 3 ,
 .Xr sem_wait 3 ,
 .Xr capsicum 4 ,
 .Xr snp 4
 .Sh HISTORY
 Support for capabilities and capabilities mode was developed as part of the
 .Tn TrustedBSD
 Project.
 .Sh AUTHORS
 .An -nosplit
 This manual page was created by
 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 under sponsorship from the FreeBSD Foundation based on the
 .Xr cap_new 2
 manual page by
 .An Robert Watson Aq Mt rwatson@FreeBSD.org .