Date: Wed, 6 Nov 2013 23:59:19 +0000 (UTC) From: Pawel Jakub Dawidek <pjd@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-10@freebsd.org Subject: svn commit: r257771 - in stable/10: lib/libc/capability lib/libc/gen lib/libc/sys share/man/man4 Message-ID: <201311062359.rA6NxJ1N004947@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: pjd Date: Wed Nov 6 23:59:19 2013 New Revision: 257771 URL: http://svnweb.freebsd.org/changeset/base/257771 Log: 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) Added: stable/10/lib/libc/capability/cap_rights_init.3 - copied unchanged from r257633, head/lib/libc/capability/cap_rights_init.3 stable/10/lib/libc/gen/cap_rights_get.3 - copied unchanged from r257633, head/lib/libc/gen/cap_rights_get.3 stable/10/share/man/man4/rights.4 - copied unchanged from r257633, head/share/man/man4/rights.4 Modified: stable/10/lib/libc/capability/Makefile.inc stable/10/lib/libc/gen/Makefile.inc stable/10/lib/libc/sys/cap_ioctls_limit.2 stable/10/lib/libc/sys/cap_rights_limit.2 stable/10/share/man/man4/Makefile stable/10/share/man/man4/capsicum.4 Directory Properties: stable/10/lib/libc/ (props changed) stable/10/share/man/man4/ (props changed) Modified: stable/10/lib/libc/capability/Makefile.inc ============================================================================== --- stable/10/lib/libc/capability/Makefile.inc Wed Nov 6 23:44:52 2013 (r257770) +++ stable/10/lib/libc/capability/Makefile.inc Wed Nov 6 23:59:19 2013 (r257771) @@ -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 Copied: stable/10/lib/libc/capability/cap_rights_init.3 (from r257633, head/lib/libc/capability/cap_rights_init.3) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/10/lib/libc/capability/cap_rights_init.3 Wed Nov 6 23:59:19 2013 (r257771, copy of r257633, head/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. Modified: stable/10/lib/libc/gen/Makefile.inc ============================================================================== --- stable/10/lib/libc/gen/Makefile.inc Wed Nov 6 23:44:52 2013 (r257770) +++ stable/10/lib/libc/gen/Makefile.inc Wed Nov 6 23:59:19 2013 (r257771) @@ -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 \ Copied: stable/10/lib/libc/gen/cap_rights_get.3 (from r257633, head/lib/libc/gen/cap_rights_get.3) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ stable/10/lib/libc/gen/cap_rights_get.3 Wed Nov 6 23:59:19 2013 (r257771, copy of r257633, head/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. Modified: stable/10/lib/libc/sys/cap_ioctls_limit.2 ============================================================================== --- stable/10/lib/libc/sys/cap_ioctls_limit.2 Wed Nov 6 23:44:52 2013 (r257770) +++ stable/10/lib/libc/sys/cap_ioctls_limit.2 Wed Nov 6 23:59:19 2013 (r257771) @@ -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 fi .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. Modified: stable/10/lib/libc/sys/cap_rights_limit.2 ============================================================================== --- stable/10/lib/libc/sys/cap_rights_limit.2 Wed Nov 6 23:44:52 2013 (r257770) +++ stable/10/lib/libc/sys/cap_rights_limit.2 Wed Nov 6 23:59:19 2013 (r257771) @@ -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 f .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, oper 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 descripto 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 , *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201311062359.rA6NxJ1N004947>