system/freebsd-src
system/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src synced 2024-09-06 17:18:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

- Add manual pages for capability rights (rights(4)), cap_rights_init(3)

Browse source 
family of functions and cap_rights_get(3) function.
- Update remaining Capsicum-related manual pages.

Reviewed by:	bdrewery
MFC after:	3 days
This commit is contained in:
Pawel Jakub Dawidek 2013-11-04 14:10:22 +00:00
parent 6ab0d9cf41
commit 6f62d278e8
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=257633
9 changed files with 1113 additions and 534 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
lib/libc/capability/Makefile.inc
View file

@ -1,19 +1,18 @@
# $FreeBSD$
# capability sources
.PATH: ${.CURDIR}/../../sys/kern
.PATH: ${.CURDIR}/../../sys/kern ${.CURDIR}/capability
SRCS+= subr_capability.c
SYM_MAPS+= ${.CURDIR}/capability/Symbol.map
#MAN+= cap_rights_init.3
#MLINKS+=cap_rights_init.3 cap_rights_set.3
#MLINKS+=cap_rights_init.3 cap_rights_clear.3
#MLINKS+=cap_rights_init.3 cap_rights_is_set.3
#MLINKS+=cap_rights_init.3 cap_rights_is_valid.3
#MLINKS+=cap_rights_init.3 cap_rights_merge.3
#MLINKS+=cap_rights_init.3 cap_rights_remove.3
#MLINKS+=cap_rights_init.3 cap_rights_contains.3
MAN+= cap_rights_init.3
MLINKS+=cap_rights_init.3 cap_rights_set.3
MLINKS+=cap_rights_init.3 cap_rights_clear.3
MLINKS+=cap_rights_init.3 cap_rights_is_set.3
MLINKS+=cap_rights_init.3 cap_rights_is_valid.3
MLINKS+=cap_rights_init.3 cap_rights_merge.3
MLINKS+=cap_rights_init.3 cap_rights_remove.3
MLINKS+=cap_rights_init.3 cap_rights_contains.3

241
lib/libc/capability/cap_rights_init.3 Normal file
View file

@ -0,0 +1,241 @@
.\"
.\" Copyright (c) 2013 The FreeBSD Foundation
.\" All rights reserved.
.\"
.\" This documentation was 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 September 23, 2013
.Dt CAP_RIGHTS_INIT 3
.Os
.Sh NAME
.Nm cap_rights_init ,
.Nm cap_rights_set ,
.Nm cap_rights_clear ,
.Nm cap_rights_is_set ,
.Nm cap_rights_is_valid ,
.Nm cap_rights_merge ,
.Nm cap_rights_remove ,
.Nm cap_rights_contains
.Nd manage cap_rights_t structure
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/capability.h
.Ft cap_rights_t *
.Fn cap_rights_init "cap_rights_t *rights" "..."
.Ft cap_rights_t *
.Fn cap_rights_set "cap_rights_t *rights" "..."
.Ft cap_rights_t *
.Fn cap_rights_clear "cap_rights_t *rights" "..."
.Ft bool
.Fn cap_rights_is_set "const cap_rights_t *rights" "..."
.Ft bool
.Fn cap_rights_is_valid "const cap_rights_t *rights"
.Ft cap_rights_t *
.Fn cap_rights_merge "cap_rights_t *dst" "const cap_rights_t *src"
.Ft cap_rights_t *
.Fn cap_rights_remove "cap_rights_t *dst" "const cap_rights_t *src"
.Ft bool
.Fn cap_rights_contains "const cap_rights_t *big" "const cap_rights_t *little"
.Sh DESCRIPTION
The functions documented here allow to manage the
.Vt cap_rights_t
structure.
.Pp
Capability rights should be separated with comma when passed to the
.Fn cap_rights_init ,
.Fn cap_rights_set ,
.Fn cap_rights_clear
and
.Fn cap_rights_is_set
functions.
For example:
.Bd -literal
cap_rights_set(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT, CAP_SEEK);
.Ed
.Pp
The complete list of the capability rights can be found in the
.Xr rights 4
manual page.
.Pp
The
.Fn cap_rights_init
function initialize provided
.Vt cap_rights_t
structure.
Only properly initialized structure can be passed to the remaining functions.
For convenience the structure can be filled with capability rights instead of
calling the
.Fn cap_rights_set
function later.
For even more convenience pointer to the given structure is returned, so it can
be directly passed to
.Xr cap_rights_limit 2 :
.Bd -literal
cap_rights_t rights;
if (cap_rights_limit(fd, cap_rights_init(&rights, CAP_READ, CAP_WRITE)) < 0)
err(1, "Unable to limit capability rights");
.Ed
.Pp
The
.Fn cap_rights_set
function adds the given capability rights to the given
.Vt cap_rights_t
structure.
.Pp
The
.Fn cap_rights_clear
function removes the given capability rights from the given
.Vt cap_rights_t
structure.
.Pp
The
.Fn cap_rights_is_set
function checks if all the given capability rights are set for the given
.Vt cap_rights_t
structure.
.Pp
The
.Fn cap_rights_is_valid
function verifies if the given
.Vt cap_rights_t
structure is valid.
.Pp
The
.Fn cap_rights_merge
function merges all capability rights present in the
.Fa src
structure into the
.Fa dst
structure.
.Pp
The
.Fn cap_rights_remove
function removes all capability rights present in the
.Fa src
structure from the
.Fa dst
structure.
.Pp
The
.Fn cap_rights_contains
function checks if the
.Fa big
structure contains all capability rights present in the
.Fa little
structure.
.Sh RETURN VALUES
The functions never fail.
In case an invalid capability right or an invalid
.Vt cap_rights_t
structure is given as an argument, the program will be aborted.
.Pp
The
.Fn cap_rights_init ,
.Fn cap_rights_set
and
.Fn cap_rights_clear
functions return pointer to the
.Vt cap_rights_t
structure given in the
.Fa rights
argument.
.Pp
The
.Fn cap_rights_merge
and
.Fn cap_rights_remove
functions return pointer to the
.Vt cap_rights_t
structure given in the
.Fa dst
argument.
.Pp
The
.Fn cap_rights_is_set
returns
.Va true
if all the given capability rights are set in the
.Fa rights
argument.
.Pp
The
.Fn cap_rights_is_valid
function performs various checks to see if the given
.Vt cap_rights_t
structure is valid and returns
.Va true
if it is.
.Pp
The
.Fn cap_rights_contains
function returns
.Va true
if all capability rights set in the
.Fa little
structure are also present in the
.Fa big
structure.
.Sh EXAMPLES
The following example demonstrates how to prepare a
.Vt cap_rights_t
structure to be passed to the
.Xr cap_rights_limit 2
system call.
.Bd -literal
cap_rights_t rights;
int fd;
fd = open("/tmp/foo", O_RDWR);
if (fd < 0)
err(1, "open() failed");
cap_rights_init(&rights, CAP_FSTAT, CAP_READ);
if (allow_write_and_seek)
cap_rights_set(&rights, CAP_WRITE, CAP_SEEK);
if (dont_allow_seek)
cap_rights_clear(&rights, CAP_SEEK);
if (cap_rights_limit(fd, &rights) < 0 && errno != ENOSYS)
err(1, "cap_rights_limit() failed");
.Ed
.Sh SEE ALSO
.Xr cap_rights_limit 2 ,
.Xr open 2 ,
.Xr capsicum 4 ,
.Xr rights 4
.Sh HISTORY
Support for capabilities and capabilities mode was developed as part of the
.Tn TrustedBSD
Project.
.Sh AUTHORS
This family of functions was created by
.An Pawel Jakub Dawidek Aq pawel@dawidek.net
under sponsorship from the FreeBSD Foundation.

1
lib/libc/gen/Makefile.inc
View file

@ -170,6 +170,7 @@ SYM_MAPS+=${.CURDIR}/gen/Symbol.map
MAN+= alarm.3 \
arc4random.3 \
basename.3 \
cap_rights_get.3 \
cap_sandboxed.3 \
check_utility_compat.3 \
clock.3 \

119
lib/libc/gen/cap_rights_get.3 Normal file
View file

@ -0,0 +1,119 @@
.\"
.\" Copyright (c) 2013 The FreeBSD Foundation
.\" All rights reserved.
.\"
.\" This documentation was 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 September 23, 2013
.Dt CAP_RIGHTS_GET 3
.Os
.Sh NAME
.Nm cap_rights_get
.Nd obtain capability rights
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/capability.h
.Ft int
.Fn cap_rights_get "int fd" "cap_rights_t *rights"
.Sh DESCRIPTION
The
.Nm cap_rights_get
function allows to obtain current capability rights for the given descriptor.
The function will fill the
.Fa rights
argument with all capability rights if they were not limited or capability
rights configured during the last successful call of
.Xr cap_rights_limit 2
on the given descriptor.
.Pp
The
.Fa rights
argument can be inspected using
.Xr cap_rights_init 3
family of functions.
.Pp
The complete list of the capability rights can be found in the
.Xr rights 4
manual page.
.Sh RETURN VALUES
.Rv -std
.Sh EXAMPLES
The following example demonstrates how to limit file descriptor capability
rights and how to obtain them.
.Bd -literal
cap_rights_t setrights, getrights;
int fd;
memset(&setrights, 0, sizeof(setrights));
memset(&getrights, 0, sizeof(getrights));
fd = open("/tmp/foo", O_RDONLY);
if (fd < 0)
err(1, "open() failed");
cap_rights_init(&setrights, CAP_FSTAT, CAP_READ);
if (cap_rights_limit(fd, &setrights) < 0 && errno != ENOSYS)
err(1, "cap_rights_limit() failed");
if (cap_rights_get(fd, &getrights) < 0 && errno != ENOSYS)
err(1, "cap_rights_get() failed");
assert(memcmp(&setrights, &getrights, sizeof(setrights)) == 0);
.Ed
.Sh ERRORS
.Fn cap_rights_get
succeeds unless:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa fd
argument is not a valid active descriptor.
.It Bq Er EFAULT
The
.Fa rights
argument points at an invalid address.
.El
.Sh SEE ALSO
.Xr cap_rights_limit 2 ,
.Xr cap_rights_init 3 ,
.Xr errno 2 ,
.Xr open 2 ,
.Xr assert 3 ,
.Xr err 3 ,
.Xr memcmp 3 ,
.Xr memset 3 ,
.Xr capsicum 4 ,
.Xr rights 4
.Sh HISTORY
Support for capabilities and capabilities mode was developed as part of the
.Tn TrustedBSD
Project.
.Sh AUTHORS
This function was created by
.An Pawel Jakub Dawidek Aq pawel@dawidek.net
under sponsorship of the FreeBSD Foundation.

6
lib/libc/sys/cap_ioctls_limit.2
View file

@ -58,7 +58,7 @@ argument is an array of
commands and the
.Fa ncmds
argument specifies the number of elements in the array.
There might be up to
There can be up to
.Va 256
elements in the array.
.Pp
@ -92,7 +92,7 @@ system call was never called for this file descriptor), the
.Fn cap_ioctls_get
system call will return
.Dv CAP_IOCTLS_ALL
and won't modify the buffer pointed out by the
and won't modify the buffer pointed to by the
.Fa cmds
argument.
.Sh RETURN VALUES
@ -100,7 +100,7 @@ argument.
.Pp
The
.Fn cap_ioctls_get
function, if successfull, returns the total number of allowed ioctl commands or
function, if successful, returns the total number of allowed ioctl commands or
the value
.Dv CAP_IOCTLS_ALL
if all ioctls commands are allowed.

570
lib/libc/sys/cap_rights_limit.2
View file

@ -36,19 +36,18 @@
.Dt CAP_RIGHTS_LIMIT 2
.Os
.Sh NAME
.Nm cap_rights_limit ,
.Nm cap_rights_get
.Nd manage capability rights
.Nm cap_rights_limit
.Nd limit capability rights
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/capability.h
.Ft int
.Fn cap_rights_limit "int fd" "cap_rights_t rights"
.Ft int
.Fn cap_rights_get "int fd" "cap_rights_t *rightsp"
.Fn cap_rights_limit "int fd" "const cap_rights_t *rights"
.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 ,
@ -57,7 +56,7 @@ When a file descriptor is created by a function such as
.Xr pdfork 2 ,
.Xr pipe 2 ,
.Xr shm_open 2 ,
.Xr socket 2 ,
.Xr socket 2
or
.Xr socketpair 2 ,
it is assigned all capability rights.
@ -68,429 +67,48 @@ Once capability rights are reduced, operations on the file descriptor will be
limited to those permitted by
.Fa rights .
.Pp
A bitmask of capability rights assigned to a file descriptor can be obtained with
the
.Fn cap_rights_get
system call.
.Sh RIGHTS
The following rights may be specified in a rights mask:
.Bl -tag -width CAP_EXTATTR_DELETE
.It Dv CAP_ACCEPT
Permit
.Xr accept 2
and
.Xr accept4 2 .
.It Dv CAP_ACL_CHECK
Permit checking of an ACL on a file descriptor; there is no cross-reference
for this system call.
.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.
.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.
.It Dv CAP_CREATE
Permit
.Xr openat 2
with the
.Dv O_CREAT
flag.
.\" XXXPJD: Doesn't exist anymore.
.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_FEXECVE
Permit
.Xr fexecve 2
and
.Xr openat 2
with the
.Dv O_EXEC
flag;
.Dv CAP_READ
will also be required.
.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 .
.It Dv CAP_CHFLAGSAT
An alias to
.Dv CAP_FCHFLAGS .
.It Dv CAP_FCHMOD
Permit
.Xr fchmod 2
and
.Xr fchmodat 2 .
.It Dv CAP_FCHMODAT
An alias to
.Dv CAP_FCHMOD .
.It Dv CAP_FCHOWN
Permit
.Xr fchown 2
and
.Xr fchownat 2 .
.It Dv CAP_FCHOWNAT
An alias to
.Dv CAP_FCHOWN .
.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_FLOCK
Permit
.Xr flock 2 ,
.Xr fcntl 2
(with
.Dv F_GETLK ,
.Dv F_SETLK
or
.Dv F_SETLKW
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 .
.It Dv CAP_FSTATAT
An alias to
.Dv CAP_FSTAT .
.It Dv CAP_FSTATFS
Permit
.Xr fstatfs 2 .
.It Dv CAP_FSYNC
Permit
.Xr aio_fsync 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 futimes 2
and
.Xr futimesat 2 .
.It Dv CAP_FUTIMESAT
An alias to
.Dv CAP_FUTIMES .
.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.
.\" XXXPJD: Doesn't exist anymore.
.It Dv CAP_KEVENT
Permit
.Xr kevent 2 ;
.Dv CAP_EVENT
is also required on file descriptors that will be monitored using
.Xr kevent 2 .
.It Dv CAP_LINKAT
Permit
.Xr linkat 2
and
.Xr renameat 2 .
This right is required for the destination directory descriptor.
.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 .
.It Dv CAP_MKFIFOAT
Permit
.Xr mkfifoat 2 .
.It Dv CAP_MKNODAT
Permit
.Xr mknodat 2 .
.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 also implies
.Dv CAP_READ
and
.Dv CAP_SEEK
rights.
.It Dv CAP_MMAP_W
Permit
.Xr mmap 2
with the
.Dv PROT_WRITE
protection.
This also implies
.Dv CAP_WRITE
and
.Dv CAP_SEEK
rights.
.It Dv CAP_MMAP_X
Permit
.Xr mmap 2
with the
.Dv PROT_EXEC
protection.
This also implies
.Dv CAP_SEEK
right.
.It Dv CAP_MMAP_RW
Implies
.Dv CAP_MMAP_R
and
.Dv CAP_MMAP_W .
.It Dv CAP_MMAP_RX
Implies
.Dv CAP_MMAP_R
and
.Dv CAP_MMAP_X .
.It Dv CAP_MMAP_WX
Implies
.Dv CAP_MMAP_W
and
.Dv CAP_MMAP_X .
.It Dv CAP_MMAP_RWX
Implies
.Dv CAP_MMAP_R ,
.Dv CAP_MMAP_W
and
.Dv CAP_MMAP_X .
.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 .
.\" XXXPJD: Not documented.
.It Dv CAP_POLL_EVENT
.\" XXXPJD: Not documented.
.It Dv CAP_POST_EVENT
.It Dv CAP_PREAD
Implies
.Dv CAP_SEEK
and
.Dv CAP_READ .
.It Dv CAP_PWRITE
Implies
.Dv CAP_SEEK
and
.Dv CAP_WRITE .
.It Dv CAP_READ
Allow
.Xr aio_read 2 ,
.Xr openat
with the
.Dv O_RDONLY flag,
.Xr read 2 ,
.Xr recv 2 ,
.Xr recvfrom 2 ,
.Xr recvmsg 2
and related system calls.
.It Dv CAP_RECV
An alias to
.Dv CAP_READ .
.It Dv CAP_RENAMEAT
Permit
.Xr renameat 2 .
This right is required for the source directory descriptor.
.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 .
.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.
.It Dv CAP_WRITE
Allow
.Xr aio_write 2 ,
.Xr openat 2
with
.Dv O_WRONLY
and
.Dv O_APPEND
flags,
.Xr send 2 ,
.Xr sendmsg 2 ,
.Xr sendto 2 ,
.Xr write 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.
.El
The
.Fa rights
argument should be prepared using
.Xr cap_rights_init 3
family of functions.
.Pp
Capability rights assigned to a file descriptor can be obtained with the
.Xr cap_rights_get 3
function.
.Pp
The complete list of the capability rights can be found in the
.Xr rights 4
manual page.
.Sh RETURN VALUES
.Rv -std
.Sh EXAMPLES
The following example demonstrates how to limit file descriptor capability
rights to allow reading only.
.Bd -literal
cap_rights_t rights;
char buf[1];
int fd;
fd = open("/tmp/foo", O_RDWR);
if (fd < 0)
err(1, "open() failed");
if (cap_enter() < 0)
err(1, "cap_enter() failed");
cap_rights_init(&setrights, CAP_READ);
if (cap_rights_limit(fd, &setrights) < 0)
err(1, "cap_rights_limit() failed");
buf[0] = 'X';
if (write(fd, buf, sizeof(buf)) > 0)
errx(1, "write() succeeded!");
if (read(fd, buf, sizeof(buf)) < 0)
err(1, "read() failed");
.Ed
.Sh ERRORS
.Fn cap_rights_limit
succeeds unless:
@ -503,106 +121,32 @@ argument is not a valid active descriptor.
An invalid right has been requested in
.Fa rights .
.It Bq Er ENOTCAPABLE
The
.Fa rights
contains requested rights not present in the current rights mask associated
with the given file descriptor.
.El
.Pp
.Fn cap_rights_get
succeeds unless:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa fd
argument is not a valid active descriptor.
.It Bq Er EFAULT
The
.Fa rightsp
argument points at an invalid address.
argument contains capability rights not present for the given file descriptor.
Capability rights list can only be reduced, never expanded.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr aio_fsync 2 ,
.Xr aio_read 2 ,
.Xr aio_write 2 ,
.Xr bind 2 ,
.Xr bindat 2 ,
.Xr accept4 2 ,
.Xr cap_enter 2 ,
.Xr cap_fcntls_limit 2 ,
.Xr cap_ioctls_limit 2 ,
.Xr cap_rights_limit 2 ,
.Xr connect 2 ,
.Xr connectat 2 ,
.Xr dup 2 ,
.Xr dup2 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 fchown 2 ,
.Xr fcntl 2 ,
.Xr fexecve 2 ,
.Xr fhopen 2 ,
.Xr flock 2 ,
.Xr fpathconf 2 ,
.Xr fstat 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 pwrite 2 ,
.Xr read 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 acl_delete_fd_np 3 ,
.Xr acl_get_fd 3 ,
.Xr acl_get_fd_np 3 ,
.Xr acl_set_fd_np 3 ,
.Xr cap_limitfd 3 ,
.Xr libcapsicum 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 cap_rights_get 3 ,
.Xr cap_rights_init 3 ,
.Xr err 3 ,
.Xr capsicum 4 ,
.Xr snp 4
.Xr rights 4
.Sh HISTORY
Support for capabilities and capabilities mode was developed as part of the
.Tn TrustedBSD
@ -611,9 +155,3 @@ Project.
This function was created by
.An Pawel Jakub Dawidek Aq pawel@dawidek.net
under sponsorship of the FreeBSD Foundation.
.Sh BUGS
This man page should list the set of permitted system calls more specifically
for each capability right.
.Pp
Capability rights sometimes have unclear indirect impacts, which should be
documented, or at least hinted at.

1
share/man/man4/Makefile
View file

@ -382,6 +382,7 @@ MAN= aac.4 \
rc.4 \
re.4 \
rgephy.4 \
rights.4 \
rl.4 \
rndtest.4 \
route.4 \

16
share/man/man4/capsicum.4
View file

@ -26,7 +26,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd September 17, 2013
.Dd October 19, 2013
.Dt CAPSICUM 4
.Os
.Sh NAME
@ -58,8 +58,8 @@ memory mappings or file descriptors, may be used.
Once set, the flag is inherited by future children processes, and may not be
cleared.
.It capabilities
File descriptors that wrap other file descriptors, masking operations that can
be called on them; for example, a file descriptor returned by
Limit operations that can be called on file descriptors.
For example, a file descriptor returned by
.Xr open 2
may be refined using
.Xr cap_rights_limit 2
@ -69,6 +69,9 @@ and
.Xr write 2
can be called, but not
.Xr fchmod 2 .
The complete list of the capability rights can be found in the
.Xr rights 4
manual page.
.El
.Pp
In some cases,
@ -88,8 +91,9 @@ associated with file descriptors; described in greater detail in
.El
.Sh SEE ALSO
.Xr cap_enter 2 ,
.Xr cap_fcntls_limit 2 ,
.Xr cap_getmode 2 ,
.Xr cap_rights_get 2 ,
.Xr cap_ioctls_limit 2 ,
.Xr cap_rights_limit 2 ,
.Xr fchmod 2 ,
.Xr open 2 ,
@ -100,6 +104,7 @@ associated with file descriptors; described in greater detail in
.Xr read 2 ,
.Xr shm_open 2 ,
.Xr write 2 ,
.Xr cap_rights_get 3 ,
.Xr procdesc 4
.Sh HISTORY
.Nm
@ -117,7 +122,8 @@ at the University of Cambridge, and
.An "Ben Laurie" Aq benl@FreeBSD.org
and
.An "Kris Kennaway" Aq kris@FreeBSD.org
at Google, Inc.
at Google, Inc., and
.An "Pawel Jakub Dawidek" Aq pawel@dawidek.net .
.Sh BUGS
.Nm
is considered experimental in

674
share/man/man4/rights.4 Normal file
View file

@ -0,0 +1,674 @@
.\"
.\" 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 September 23, 2013
.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.
.Pp
.Sh RIGHTS
The following rights may be specified in a rights mask:
.Bl -tag -width CAP_EXTATTR_DELETE
.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.
.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 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 futimes 2
and
.Xr futimesat 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_KEVENT_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_KEVENT_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
Permit
.Xr linkat 2
and
.Xr renameat 2
on the destination 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
Permit
.Xr renameat 2 .
This right is required on the source 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
This manual page was created by
.An Pawel Jakub Dawidek Aq pawel@dawidek.net
under sponsorship from the FreeBSD Foundation based on
.Xr cap_new 2
manual page by
.An "Robert Watson" Aq rwatson@FreeBSD.org .