diff options
Diffstat (limited to 'lib/libc')
-rw-r--r-- | lib/libc/include/compat.h | 2 | ||||
-rw-r--r-- | lib/libc/sys/Makefile.inc | 8 | ||||
-rw-r--r-- | lib/libc/sys/Symbol.map | 7 | ||||
-rw-r--r-- | lib/libc/sys/cap_enter.2 | 38 | ||||
-rw-r--r-- | lib/libc/sys/cap_fcntls_limit.2 | 127 | ||||
-rw-r--r-- | lib/libc/sys/cap_ioctls_limit.2 | 158 | ||||
-rw-r--r-- | lib/libc/sys/cap_rights_limit.2 (renamed from lib/libc/sys/cap_new.2) | 382 | ||||
-rw-r--r-- | lib/libc/sys/dup.2 | 6 |
8 files changed, 584 insertions, 144 deletions
diff --git a/lib/libc/include/compat.h b/lib/libc/include/compat.h index 7694540..3739fe1 100644 --- a/lib/libc/include/compat.h +++ b/lib/libc/include/compat.h @@ -42,6 +42,8 @@ __sym_compat(__semctl, freebsd7___semctl, FBSD_1.0); __sym_compat(msgctl, freebsd7_msgctl, FBSD_1.0); __sym_compat(shmctl, freebsd7_shmctl, FBSD_1.0); +__sym_compat(cap_getrights, cap_rights_get, FBSD_1.2); + #undef __sym_compat #endif /* __LIBC_COMPAT_H__ */ diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index 9f216dc..03c0090 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -93,7 +93,9 @@ MAN+= abort2.2 \ bind.2 \ brk.2 \ cap_enter.2 \ - cap_new.2 \ + cap_fcntls_limit.2 \ + cap_ioctls_limit.2 \ + cap_rights_limit.2 \ chdir.2 \ chflags.2 \ chmod.2 \ @@ -270,7 +272,9 @@ MLINKS+=access.2 eaccess.2 \ access.2 faccessat.2 MLINKS+=brk.2 sbrk.2 MLINKS+=cap_enter.2 cap_getmode.2 -MLINKS+=cap_new.2 cap_getrights.2 +MLINKS+=cap_fcntls_limit.2 cap_fcntls_get.2 +MLINKS+=cap_ioctls_limit.2 cap_ioctls_get.2 +MLINKS+=cap_rights_limit.2 cap_rights_get.2 MLINKS+=chdir.2 fchdir.2 MLINKS+=chflags.2 fchflags.2 \ chflags.2 lchflags.2 diff --git a/lib/libc/sys/Symbol.map b/lib/libc/sys/Symbol.map index d126255..7738e46 100644 --- a/lib/libc/sys/Symbol.map +++ b/lib/libc/sys/Symbol.map @@ -364,7 +364,6 @@ FBSD_1.2 { cap_enter; cap_getmode; cap_new; - cap_getrights; getloginclass; pdfork; pdgetpid; @@ -379,6 +378,12 @@ FBSD_1.2 { }; FBSD_1.3 { + cap_fcntls_get; + cap_fcntls_limit; + cap_ioctls_get; + cap_ioctls_limit; + cap_rights_get; + cap_rights_limit; cap_sandboxed; clock_getcpuclockid2; ffclock_getcounter; diff --git a/lib/libc/sys/cap_enter.2 b/lib/libc/sys/cap_enter.2 index c3cefe8..3369669 100644 --- a/lib/libc/sys/cap_enter.2 +++ b/lib/libc/sys/cap_enter.2 @@ -58,8 +58,10 @@ or .Xr pdfork 2 will be placed in capability mode from inception. .Pp -When combined with capabilities created with -.Xr cap_new 2 , +When combined with +.Xr cap_rights_limit 2 , +.Xr cap_ioctls_limit 2 , +.Xr cap_fcntls_limit 2 , .Fn cap_enter may be used to create kernel-enforced sandboxes in which appropriately-crafted applications or application components may be run. @@ -71,11 +73,6 @@ sandbox. Creating effective process sandboxes is a tricky process that involves identifying the least possible rights required by the process and then passing those rights into the process in a safe manner. -See the CAVEAT -section of -.Xr cap_new 2 -for why this is particularly tricky with UNIX file descriptors as the -canonical representation of a right. Consumers of .Fn cap_enter should also be aware of other inherited rights, such as access to VM @@ -87,8 +84,33 @@ to create a runtime environment inside the sandbox that has as few implicitly acquired rights as possible. .Sh RETURN VALUES .Rv -std cap_enter cap_getmode +.Sh ERRORS +The +.Fn cap_enter +and +.Fn cap_getmode +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er ENOSYS +The kernel is compiled without: +.Pp +.Cd "options CAPABILITY_MODE" +.El +.Pp +The +.Fn cap_getmode +system call may also return the following error: +.Bl -tag -width Er +.It Bq Er EFAULT +Pointer +.Fa modep +points outside the process's allocated address space. +.El .Sh SEE ALSO -.Xr cap_new 2 , +.Xr cap_fcntls_limit 2 , +.Xr cap_ioctls_limit 2 , +.Xr cap_rights_limit 2 , .Xr fexecve 2 , .Xr cap_sandboxed 3 , .Xr capsicum 4 diff --git a/lib/libc/sys/cap_fcntls_limit.2 b/lib/libc/sys/cap_fcntls_limit.2 new file mode 100644 index 0000000..8fa7463 --- /dev/null +++ b/lib/libc/sys/cap_fcntls_limit.2 @@ -0,0 +1,127 @@ +.\" +.\" Copyright (c) 2012 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship +.\" 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 20, 2012 +.Dt CAP_FCNTLS_LIMIT 2 +.Os +.Sh NAME +.Nm cap_fcntls_limit , +.Nm cap_fcntls_get +.Nd manage allowed fcntl commands +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capability.h +.Ft int +.Fn cap_fcntls_limit "int fd" "uint32_t fcntlrights" +.Ft int +.Fn cap_fcntls_get "int fd" "uint32_t *fcntlrightsp" +.Sh DESCRIPTION +If a file descriptor is granted the +.Dv CAP_FCNTL +capability right, the list of allowed +.Xr fcntl 2 +commands can be selectively reduced (but never expanded) with the +.Fn cap_fcntls_limit +system call. +.Pp +A bitmask of allowed fcntls commands for a given file descriptor can be obtained +with the +.Fn cap_fcntls_get +system call. +.Sh FLAGS +The following flags may be specified in the +.Fa fcntlrights +argument or returned in the +.Fa fcntlrightsp +argument: +.Bl -tag -width CAP_FCNTL_GETOWN +.It Dv CAP_FCNTL_GETFL +Permit +.Dv F_GETFL +command. +.It Dv CAP_FCNTL_SETFL +Permit +.Dv F_SETFL +command. +.It Dv CAP_FCNTL_GETOWN +Permit +.Dv F_GETOWN +command. +.It Dv CAP_FCNTL_SETOWN +Permit +.Dv F_SETOWN +command. +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Fn cap_fcntls_limit +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EINVAL +An invalid flag has been passed in +.Fa fcntlrights . +.It Bq Er ENOTCAPABLE +.Fa fcntlrights +would expand the list of allowed +.Xr fcntl 2 +commands. +.El +.Pp +.Fn cap_fcntls_get +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EFAULT +The +.Fa fcntlrightsp +argument points at an invalid address. +.El +.Sh SEE ALSO +.Xr cap_ioctls_limit 2 , +.Xr cap_rights_limit 2 , +.Xr fcntl 2 +.Sh HISTORY +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Pp +.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 new file mode 100644 index 0000000..5eca18c --- /dev/null +++ b/lib/libc/sys/cap_ioctls_limit.2 @@ -0,0 +1,158 @@ +.\" +.\" Copyright (c) 2012 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship +.\" 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 20, 2012 +.Dt CAP_IOCTLS_LIMIT 2 +.Os +.Sh NAME +.Nm cap_ioctls_limit , +.Nm cap_ioctls_get +.Nd manage allowed ioctl commands +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capability.h +.Ft int +.Fn cap_ioctls_limit "int fd" "const unsigned long *cmds" "size_t ncmds" +.Ft ssize_t +.Fn cap_ioctls_get "int fd" "unsigned long *cmds" "size_t maxcmds" +.Sh DESCRIPTION +If a file descriptor is granted the +.Dv CAP_IOCTL +capability right, the list of allowed +.Xr ioctl 2 +commands can be selectively reduced (but never expanded) with the +.Fn cap_ioctls_limit +system call. +The +.Fa cmds +argument is an array of +.Xr ioctl 2 +commands and the +.Fa ncmds +argument specifies the number of elements in the array. +There might be up to +.Va 256 +elements in the array. +.Pp +The list of allowed ioctl commands for a given file descriptor can be obtained +with the +.Fn cap_ioctls_get +system call. +The +.Fa cmds +argument points at memory that can hold up to +.Fa maxcmds +values. +The function populates the provided buffer with up to +.Fa maxcmds +elements, but always returns the total number of ioctl commands allowed for the +given file descriptor. +The total number of ioctls commands for the given file descriptor can be +obtained by passing +.Dv NULL as the +.Fa cmds +argument and +.Va 0 +as the +.Fa maxcmds +argument. +If all ioctl commands are allowed +.Dv ( CAP_IOCTL +capability right is assigned to the file descriptor and the +.Fn cap_ioctls_limit +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 +.Fa cmds +argument. +.Sh RETURN VALUES +.Rv -std cap_ioctls_limit +.Pp +The +.Fn cap_ioctls_limit +function, if successfull, returns the total number of allowed ioctl commands or +the value +.Dv INT_MAX +if all ioctls commands are allowed. +On failure the value +.Va -1 +is returned and the global variable errno is set to indicate the error. +.Sh ERRORS +.Fn cap_ioctls_limit +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EFAULT +The +.Fa cmds +argument points at an invalid address. +.It Bq Er EINVAL +The +.Fa ncmds +argument is greater than +.Va 256 . +.It Bq Er ENOTCAPABLE +.Fa cmds +would expand the list of allowed +.Xr ioctl 2 +commands. +.El +.Pp +.Fn cap_ioctls_get +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EFAULT +The +.Fa cmds +argument points at invalid address. +.El +.Sh SEE ALSO +.Xr cap_fcntls_limit 2 , +.Xr cap_rights_limit 2 , +.Xr ioctl 2 +.Sh HISTORY +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Pp +.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_new.2 b/lib/libc/sys/cap_rights_limit.2 index a18fd3b..d8d8777 100644 --- a/lib/libc/sys/cap_new.2 +++ b/lib/libc/sys/cap_rights_limit.2 @@ -1,10 +1,14 @@ .\" .\" 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: @@ -28,76 +32,48 @@ .\" .\" $FreeBSD$ .\" -.Dd July 20, 2011 -.Dt CAP_NEW 2 +.Dd February 23, 2013 +.Dt CAP_RIGHTS_LIMIT 2 .Os .Sh NAME -.Nm cap_new , -.Nm cap_getrights -.Nd System calls to manipulate capabilities +.Nm cap_rights_limit , +.Nm cap_rights_get +.Nd manage capability rights .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/capability.h .Ft int -.Fn cap_new "int fd" "cap_rights_t rights" +.Fn cap_rights_limit "int fd" "cap_rights_t rights" .Ft int -.Fn cap_getrights "int fd" "cap_rights_t *rightsp" +.Fn cap_rights_get "int fd" "cap_rights_t *rightsp" .Sh DESCRIPTION -Capabilities are special file descriptors derived from an existing file -descriptor, such as one returned by +When a file descriptor is created by a function such as .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 , -but with a restricted set of permitted operations determined by a rights -mask set when the capability is created. -These restricted rights cannot be changed after the capability is created, -although further capabilities with yet more restricted rights may be created -from an existing capability. -In every other sense, a capability behaves in the same way as the file -descriptor it was created from. -.Pp -.Fn cap_new -creates a new capability for the existing file descriptor -.Fa fd , -and returns a file descriptor for it. -Operations on the capability will be limited to those permitted by -.Fa rights , -which is static for the lifetime of the capability. -If -.Fa fd -refers to an existing capability, then -.Fa rights -must be equal to or a subset of the rights on that capability. -As with -.Xr dup 2 -and -.Xr dup2 2 , -many properties are shared between the new capability and the existing file -descriptor, including open file flags, blocking disposition, and file offset. -Many applications will prefer to use the -.Xr cap_limitfd 3 -library call, part of -.Xr libcapsicum 3 , -as it offers a more convenient interface. -.Pp -.Fn cap_getrights -queries the rights associated with the capability referred to by file -descriptor -.Fa fd . +it is assigned all capability rights. +Those rights can be reduced (but never expanded) by using the +.Fn cap_rights_limit +system call. +Once capability rights are reduced, operations on the file descriptor will be +limited to those permitted by +.Fa rights . .Pp -These system calls, when combined with -.Xr cap_enter 2 , -may be used to construct process sandboxes with highly granular rights -assignment. +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 new capability rights mask: +The following rights may be specified in a rights mask: .Bl -tag -width CAP_EXTATTR_DELETE .It Dv CAP_ACCEPT Permit @@ -134,6 +110,13 @@ Permit also required for .Xr sendto 2 with a non-NULL destination address. +.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 , @@ -143,7 +126,12 @@ and to be used in monitoring the file descriptor for events. .It Dv CAP_FEXECVE Permit -.Xr fexecve 2 ; +.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 @@ -166,19 +154,49 @@ Permit .Xr fchflags 2 . .It Dv CAP_FCHMOD Permit -.Xr fchmod 2 . +.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 . +.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 ; -be aware that this call provides indirect access to other operations, such as -.Xr flock 2 . +.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 -and related calls. +.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 . @@ -186,22 +204,42 @@ Permit Permit UFS background-fsck operations on the descriptor. .It Dv CAP_FSTAT Permit -.Xr fstat 2 . +.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 aio_fsync 2 , +.Xr fsync 2 and -.Xr fsync 2 . -.Pp +.Xr openat 2 +with +.Dv O_FSYNC +or +.Dv O_SYNC +flag. .It Dv CAP_FTRUNCATE Permit -.Xr ftruncate 2 . +.Xr ftruncate 2 +and +.Xr openat 2 +with the +.Dv O_TRUNC +flag. .It Dv CAP_FUTIMES Permit -.Xr futimes 2 . +.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 . @@ -216,42 +254,106 @@ 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 +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 . -Note that these calls are not available in capability mode as they manipulate -a global name space; see -.Xr cap_enter 2 -for details. .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 ; -specific invocations may also require +.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 -or -.Dv CAP_WRITE . -.Pp +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 . @@ -264,30 +366,46 @@ Permit .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 pread 2 , +.Xr openat +with the +.Dv O_RDONLY flag, .Xr read 2 , .Xr recv 2 , .Xr recvfrom 2 , -.Xr recvmsg 2 , +.Xr recvmsg 2 and related system calls. -.Pp -For files and other seekable objects, -.Dv CAP_SEEK -may also be required. -.It Dv CAP_REVOKE +.It Dv CAP_RECV +An alias to +.Dv CAP_READ . +.It Dv CAP_RENAMEAT Permit -.Xr frevoke 2 -in certain ABI compatibility modes that support this system call. +.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 modify the file offset, such as -.Xr read 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 write 2 . +.Xr pwrite 2 . .It Dv CAP_SEM_GETVALUE Permit .Xr sem_getvalue 3 . @@ -299,6 +417,9 @@ 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 ; @@ -308,49 +429,56 @@ connecting, and other behaviors with global scope. 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 pwrite 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. -.Pp -For files and other seekable objects, -.Dv CAP_SEEK -may also be required. -.Pp 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 -.Sh CAVEAT -The -.Fn cap_new -system call and the capabilities it creates may be used to assign -fine-grained rights to sandboxed processes running in capability mode. -However, the semantics of objects accessed via file descriptors are complex, -so caution should be exercised in passing object capabilities into sandboxes. .Sh RETURN VALUES -If successful, -.Fn cap_new -returns a non-negative integer, termed a file descriptor. -It returns -1 on failure, and sets -.Va errno -to indicate the error. -.Pp -.Rv -std cap_getrights +.Rv -std .Sh ERRORS -.Fn cap_new -may return the following errors: +.Fn cap_rights_limit +succeeds unless: .Bl -tag -width Er .It Bq Er EBADF The @@ -359,29 +487,23 @@ argument is not a valid active descriptor. .It Bq Er EINVAL An invalid right has been requested in .Fa rights . -.It Bq Er EMFILE -The process has already reached its limit for open file descriptors. -.It Bq Er ENFILE -The system file table is full. -.It Bq Er EPERM +.It Bq Er ENOTCAPABLE .Fa rights contains requested rights not present in the current rights mask associated -with the capability referenced by -.Fa fd , -if any. +with the given file descriptor. .El .Pp -.Fn cap_getrights -may return the following 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 EINVAL +.It Bq Er EFAULT The -.Fa fd -argument is not a capability. +.Fa rightsp +argument points at an invalid address. .El .Sh SEE ALSO .Xr accept 2 , @@ -390,6 +512,9 @@ argument is not a capability. .Xr aio_write 2 , .Xr bind 2 , .Xr cap_enter 2 , +.Xr cap_fcntls_limit 2 , +.Xr cap_ioctls_limit 2 , +.Xr cap_rights_limit 2 , .Xr connect 2 , .Xr dup 2 , .Xr dup2 2 , @@ -421,6 +546,7 @@ argument is not a capability. .Xr mq_open 2 , .Xr open 2 , .Xr openat 2 , +.Xr pdfork 2 , .Xr pdgetpid 2 , .Xr pdkill 2 , .Xr pdwait4 2 , @@ -432,6 +558,7 @@ argument is not a capability. .Xr recv 2 , .Xr recvfrom 2 , .Xr recvmsg 2 , +.Xr renameat 2 , .Xr sctp_peeloff 2 , .Xr select 2 , .Xr send 2 , @@ -442,6 +569,7 @@ argument is not a capability. .Xr shutdown 2 , .Xr socket 2 , .Xr socketpair 2 , +.Xr symlinkat 2 , .Xr unlinkat 2 , .Xr write 2 , .Xr acl_delete_fd_np 3 , @@ -462,11 +590,11 @@ argument is not a capability. Support for capabilities and capabilities mode was developed as part of the .Tn TrustedBSD Project. +.Pp .Sh AUTHORS -These functions and the capability facility were created by -.An "Robert N. M. Watson" -at the University of Cambridge Computer Laboratory with support from a grant -from Google, Inc. +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. diff --git a/lib/libc/sys/dup.2 b/lib/libc/sys/dup.2 index 7a07c21..6e1de20 100644 --- a/lib/libc/sys/dup.2 +++ b/lib/libc/sys/dup.2 @@ -115,11 +115,6 @@ and is a valid descriptor, then .Fn dup2 is successful, and does nothing. -.Pp -The related -.Xr cap_new 2 -system call allows file descriptors to be duplicated with restrictions on -their use. .Sh RETURN VALUES The value -1 is returned if an error occurs in either call. The external variable @@ -152,7 +147,6 @@ argument is negative or exceeds the maximum allowable descriptor number .El .Sh SEE ALSO .Xr accept 2 , -.Xr cap_new 2 , .Xr close 2 , .Xr fcntl 2 , .Xr getdtablesize 2 , |