From 1b7270658f354729c66a9c872f37cb8f194b09e5 Mon Sep 17 00:00:00 2001 From: Jonathan Anderson Date: Wed, 20 Jul 2011 13:29:39 +0000 Subject: [PATCH] Add cap_new(2) and cap_getrights(2) symbols to libc. These system calls have already been implemented in the kernel; now we hook up libc symbols so userspace can drive them. Approved by: re (kib), mentor (rwatson) Sponsored by: Google Inc --- lib/libc/sys/Makefile.inc | 3 +- lib/libc/sys/Symbol.map | 2 + lib/libc/sys/cap_new.2 | 474 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 478 insertions(+), 1 deletion(-) create mode 100644 lib/libc/sys/cap_new.2 diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index 008180af3662..ddc157ee1b57 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -77,7 +77,7 @@ ${SPSEUDO}: MAN+= abort2.2 accept.2 access.2 acct.2 adjtime.2 \ aio_cancel.2 aio_error.2 aio_read.2 aio_return.2 \ aio_suspend.2 aio_waitcomplete.2 aio_write.2 \ - bind.2 brk.2 cap_enter.2 chdir.2 chflags.2 \ + bind.2 brk.2 cap_enter.2 cap_new.2 chdir.2 chflags.2 \ chmod.2 chown.2 chroot.2 clock_gettime.2 close.2 closefrom.2 \ connect.2 cpuset.2 cpuset_getaffinity.2 dup.2 execve.2 _exit.2 \ extattr_get_file.2 fcntl.2 fhopen.2 flock.2 fork.2 fsync.2 \ @@ -119,6 +119,7 @@ MAN+= sctp_generic_recvmsg.2 sctp_generic_sendmsg.2 sctp_peeloff.2 \ 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+=chdir.2 fchdir.2 MLINKS+=chflags.2 fchflags.2 chflags.2 lchflags.2 MLINKS+=chmod.2 fchmod.2 chmod.2 fchmodat.2 chmod.2 lchmod.2 diff --git a/lib/libc/sys/Symbol.map b/lib/libc/sys/Symbol.map index cd31f24e4a83..547a2cff9720 100644 --- a/lib/libc/sys/Symbol.map +++ b/lib/libc/sys/Symbol.map @@ -363,6 +363,8 @@ FBSD_1.1 { FBSD_1.2 { cap_enter; cap_getmode; + cap_new; + cap_getrights; getloginclass; posix_fallocate; rctl_get_racct; diff --git a/lib/libc/sys/cap_new.2 b/lib/libc/sys/cap_new.2 new file mode 100644 index 000000000000..7710e12abdfa --- /dev/null +++ b/lib/libc/sys/cap_new.2 @@ -0,0 +1,474 @@ +.\" +.\" Copyright (c) 2008-2010 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed at the University of Cambridge Computer +.\" Laboratory with support from a grant from Google, Inc. +.\" +.\" 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 July 20, 2011 +.Dt CAP_NEW 2 +.Os +.Sh NAME +.Nm cap_new , +.Nm cap_getrights +.Nd System calls to manipulate capabilities +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capability.h +.Ft int +.Fn cap_new "int fd" "cap_rights_t rights" +.Ft int +.Fn cap_getrights "int fd" "cap_rights_t *rightsp" +.Sh DESCRIPTION +Capabilities are special file descriptors derived from an existing file +descriptor, such as one returned by +.Xr fhopen 2 , +.Xr kqueue 2 , +.Xr mq_open 2 , +.Xr open 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 . +.Pp +These system calls, when combined with +.Xr cap_enter 2 , +may be used to construct process sandboxes with highly granular rights +assignment. +.Sh RIGHTS +The following rights may be specified in a new capability rights mask: +.Bl -tag -width CAP_EXTATTR_DELETE +.It Dv CAP_ACCEPT +Permit +.Xr accept 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 2 . +.It Dv CAP_ACL_GET +Permit +.Xr acl_get_fd 2 +and +.Xr acl_get_fd_np 2 . +.It Dv CAP_ACL_SET +Permit +.Xr acl_set_fd 2 +and +.Xr acl_set_fd_np 2 . +.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_CONNECT +Permit +.Xr connect 2 ; +also required for +.Xr sendto 2 +with a non-NULL destination address. +.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 ; +.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 . +.It Dv CAP_FCHMOD +Permit +.Xr fchmod 2 . +.It Dv CAP_FCHOWN +Permit +.Xr fchown 2 . +.It Dv CAP_FCNTL +Permit +.Xr fcntl 2 ; +be aware that this call provides indirect access to other operations, such as +.Xr flock 2 . +.It Dv CAP_FLOCK +Permit +.Xr flock 2 +and related calls. +.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 . +.It Dv CAP_FSTATFS +Permit +.Xr fstatfs 2 . +.It Dv CAP_FSYNC +Permit +.Xr aio_fsync 2 +and +.Xr fsync 2 . +.Pp +.It Dv CAP_FTRUNCATE +Permit +.Xr ftruncate 2 . +.It Dv CAP_FUTIMES +Permit +.Xr futimes 2 . +.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. +.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_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 . +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 2 . +.It Dv CAP_MAC_SET +Permit +.Xr mac_set_fd 2 . +.It Dv CAP_MMAP +Permit +.Xr mmap 2 ; +specific invocations may also require +.Dv CAP_READ +or +.Dv CAP_WRITE . +.Pp +.It Dv CAP_PDGETPID +Permit +.Xr pdgetpid 2 . +.It Dv CAP_PDKILL +Permit +.Xr pdkill 2 . +.It Dv CAP_PDWAIT +Permit +.Xr pdwait 2 . +.It Dv CAP_PEELOFF +Permit +.Xr sctp_peeloff 2 . +.It Dv CAP_READ +Allow +.Xr aio_read 2 , +.Xr pread 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr recvfrom 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 +Permit +.Xr frevoke 2 +in certain ABI compatibility modes that support this system call. +.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 +and +.Xr write 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_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_TTYHOOK +Allow configuration of TTY hooks, such as +.Xr snp 4 , +on the file descriptor. +.It Dv CAP_WRITE +Allow +.Xr aio_write 2 , +.Xr pwrite 2 , +.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. +.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 +.Sh ERRORS +.Fn cap_new +may return the following errors: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +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 +.Fa rights +contains requested rights not present in the current rights mask associated +with the capability referenced by +.Fa fd , +if any. +.El +.Pp +.Fn cap_getrights +may return the following errors: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid active descriptor. +.It Bq Er EINVAL +The +.Fa fd +argument is not a capability. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr acl_delete_fd_np 2 , +.Xr acl_get_fd 2 , +.Xr acl_get_fd_np 2 , +.Xr acl_set_fd_np 2 , +.Xr aio_read 2 , +.Xr aio_fsync 2 , +.Xr aio_write 2 , +.Xr bind 2 , +.Xr cap_enter 2 , +.Xr connect 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 mac_get_fd 2 , +.Xr mac_set_fd 2 , +.Xr mmap 2 , +.Xr mq_open 2 , +.Xr open 2 , +.Xr openat 2 , +.Xr pdgetpid 2 , +.Xr pdkill 2 , +.Xr pdwait 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 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 unlinkat 2 , +.Xr write 2 , +.Xr cap_limitfd 3 , +.Xr libcapsicum 3 , +.Xr sem_getvalue 3 , +.Xr sem_post 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 , +.Xr snp 4 +.Sh HISTORY +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.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. +.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.