Index: share/man/man4 =================================================================== --- share/man/man4 (revision 257731) +++ share/man/man4 (working copy) Property changes on: share/man/man4 ___________________________________________________________________ Modified: svn:mergeinfo Merged /head/share/man/man4:r257633 Index: share/man/man4/capsicum.4 =================================================================== --- share/man/man4/capsicum.4 (revision 257731) +++ share/man/man4/capsicum.4 (working copy) @@ -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 gre .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 gre .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 Index: share/man/man4/Makefile =================================================================== --- share/man/man4/Makefile (revision 257731) +++ share/man/man4/Makefile (working copy) @@ -382,6 +382,7 @@ MAN= aac.4 \ rc.4 \ re.4 \ rgephy.4 \ + rights.4 \ rl.4 \ rndtest.4 \ route.4 \ Index: share/man/man4/rights.4 =================================================================== --- share/man/man4/rights.4 (revision 0) +++ share/man/man4/rights.4 (working copy) @@ -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 . Property changes on: share/man/man4/rights.4 ___________________________________________________________________ Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Index: lib/libc =================================================================== --- lib/libc (revision 257731) +++ lib/libc (working copy) Property changes on: lib/libc ___________________________________________________________________ Modified: svn:mergeinfo Merged /head/lib/libc:r257633 Index: lib/libc/gen/Makefile.inc =================================================================== --- lib/libc/gen/Makefile.inc (revision 257731) +++ lib/libc/gen/Makefile.inc (working copy) @@ -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 \ Index: lib/libc/gen/cap_rights_get.3 =================================================================== --- lib/libc/gen/cap_rights_get.3 (revision 0) +++ lib/libc/gen/cap_rights_get.3 (working copy) @@ -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. Property changes on: lib/libc/gen/cap_rights_get.3 ___________________________________________________________________ Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Index: lib/libc/sys/cap_ioctls_limit.2 =================================================================== --- lib/libc/sys/cap_ioctls_limit.2 (revision 257731) +++ lib/libc/sys/cap_ioctls_limit.2 (working copy) @@ -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 descrip .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. Index: lib/libc/sys/cap_rights_limit.2 =================================================================== --- lib/libc/sys/cap_rights_limit.2 (revision 257731) +++ lib/libc/sys/cap_rights_limit.2 (working copy) @@ -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 su .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 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. +argument contains capability rights not present for the given file descriptor. +Capability rights list can only be reduced, never expanded. .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. -.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. Index: lib/libc/capability/Makefile.inc =================================================================== --- lib/libc/capability/Makefile.inc (revision 257731) +++ lib/libc/capability/Makefile.inc (working copy) @@ -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 +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 - +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 Index: lib/libc/capability/cap_rights_init.3 =================================================================== --- lib/libc/capability/cap_rights_init.3 (revision 0) +++ lib/libc/capability/cap_rights_init.3 (working copy) @@ -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. Property changes on: lib/libc/capability/cap_rights_init.3 ___________________________________________________________________ Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property