diff options
author | pjd <pjd@FreeBSD.org> | 2013-11-06 23:59:19 +0000 |
---|---|---|
committer | pjd <pjd@FreeBSD.org> | 2013-11-06 23:59:19 +0000 |
commit | c0de7084412665ddb3651dac3f30c12f0f92ffc5 (patch) | |
tree | 2a99d80ba54e270e253fd948fc8f688d1ce2b819 /lib | |
parent | d11e2d3d82bdc8452c78ec7e9afeb738bf092d4a (diff) | |
download | FreeBSD-src-c0de7084412665ddb3651dac3f30c12f0f92ffc5.zip FreeBSD-src-c0de7084412665ddb3651dac3f30c12f0f92ffc5.tar.gz |
Merge r257633:
- Add manual pages for capability rights (rights(4)), cap_rights_init(3)
family of functions and cap_rights_get(3) function.
- Update remaining Capsicum-related manual pages.
Sponsored by: The FreeBSD Foundation
Reviewed by: bdrewery
Approved by: re (glebius)
Diffstat (limited to 'lib')
-rw-r--r-- | lib/libc/capability/Makefile.inc | 19 | ||||
-rw-r--r-- | lib/libc/capability/cap_rights_init.3 | 241 | ||||
-rw-r--r-- | lib/libc/gen/Makefile.inc | 1 | ||||
-rw-r--r-- | lib/libc/gen/cap_rights_get.3 | 119 | ||||
-rw-r--r-- | lib/libc/sys/cap_ioctls_limit.2 | 6 | ||||
-rw-r--r-- | lib/libc/sys/cap_rights_limit.2 | 570 |
6 files changed, 427 insertions, 529 deletions
diff --git a/lib/libc/capability/Makefile.inc b/lib/libc/capability/Makefile.inc index 934fc8b..85be56a 100644 --- a/lib/libc/capability/Makefile.inc +++ b/lib/libc/capability/Makefile.inc @@ -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 diff --git a/lib/libc/capability/cap_rights_init.3 b/lib/libc/capability/cap_rights_init.3 new file mode 100644 index 0000000..458e9d3 --- /dev/null +++ b/lib/libc/capability/cap_rights_init.3 @@ -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. diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc index a88150c..7053d22 100644 --- a/lib/libc/gen/Makefile.inc +++ b/lib/libc/gen/Makefile.inc @@ -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 \ diff --git a/lib/libc/gen/cap_rights_get.3 b/lib/libc/gen/cap_rights_get.3 new file mode 100644 index 0000000..78f0ba9 --- /dev/null +++ b/lib/libc/gen/cap_rights_get.3 @@ -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. diff --git a/lib/libc/sys/cap_ioctls_limit.2 b/lib/libc/sys/cap_ioctls_limit.2 index 771736a..3d2645c 100644 --- a/lib/libc/sys/cap_ioctls_limit.2 +++ b/lib/libc/sys/cap_ioctls_limit.2 @@ -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. diff --git a/lib/libc/sys/cap_rights_limit.2 b/lib/libc/sys/cap_rights_limit.2 index 225efad..d17533f 100644 --- a/lib/libc/sys/cap_rights_limit.2 +++ b/lib/libc/sys/cap_rights_limit.2 @@ -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 -.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. +.Fa rights +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. |