Signed-off-by: David Drysdale <drysdale@xxxxxxxxxx> --- man7/rights.7 | 525 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 525 insertions(+) create mode 100644 man7/rights.7 diff --git a/man7/rights.7 b/man7/rights.7 new file mode 100644 index 000000000000..33bb8e48d12f --- /dev/null +++ b/man7/rights.7 @@ -0,0 +1,525 @@ +.\" +.\" Copyright (c) 2014 Google, Inc. +.\" Copyright (c) 2012-2013 The FreeBSD Foundation +.\" 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. +.\" +.\" %%%LICENSE_START(BSD_2_CLAUSE) +.\" 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. +.\" %%%LICENSE_END +.\" +.TH RIGHTS 7 2014-05-07 "Linux" "Linux Programmer's Manual" +.SH NAME +Capsicum capability rights for file descriptors +.SH SYNOPSIS +.B #include <linux/capsicum.h> +.SH DESCRIPTION +When a file descriptor is created by a function such as +.BR accept (2), +.BR accept4 (2), +.BR creat (2), +.BR epoll_create (2), +.BR eventfd (2), +.BR mq_open (2), +.BR open (2), +.BR openat (2), +.BR pdfork (2), +.BR pipe (2), +.BR pipe2 (2), +.BR signalfd (2), +.BR socket (2), +.BR socketpair (2) +or +.BR timerfd_create (2), +it implicitly has all Capsicum capability rights. +Those rights can be reduced (but never expanded) by using the +.BR cap_rights_limit (2) +system call. +Once capability rights are reduced, operations on the file descriptor will be +limited to those permitted by the associated rights. +.Pp +The list of primary capability rights is provided below. In addition, +.BR ioctl (2) +and +.BR fcntl (2) +can also be restricted to only allow specific commands. +.PP +The +.I "struct cap_rights" +type is used to store a list of primary capability rights; the +.BR cap_rights_init (3) +family of functions should be used to manage the structure. +.SH RIGHTS +The following rights may be specified in a rights mask: +.TP +.B CAP_ACCEPT +Permit +.BR accept (2) +and +.BR accept4 (2). +.TP +.B CAP_BIND +Permit +.BR bind (2). +Note that sockets can also become bound implicitly as a result of +.BR connect (2) +or +.BR send (2), +and that socket options set with +.BR setsockopt (2) +may also affect binding behavior. +.TP +.B CAP_CONNECT +Permit +.BR connect (2); +also required for +.BR sendto (2) +with a non-NULL destination address. +.TP +.B CAP_CREATE +Permit +.BR openat (2) +with the +.B O_CREAT +flag. +.TP +.B CAP_EVENT +Permit +.BR select (2), +.BR poll (2), +and +.BR epoll (7) +to be used in monitoring the file descriptor for events. +.TP +.B CAP_EXTATTR_DELETE +Permit +.BR fremovexattr (2). +.TP +.B CAP_EXTATTR_GET +Permit +.BR fgetxattr (2). +.TP +.B CAP_EXTATTR_LIST +Permit +.BR flistxattr (2). +.TP +.B CAP_EXTATTR_SET +Permit +.BR fsetxattr (2). +.TP +.B CAP_FCHDIR +Permit +.BR fchdir (2). +.TP +.B CAP_FCHMOD +Permit +.BR fchmod (2) +and +.BR fchmodat (2) +if the +.B CAP_LOOKUP +right is also present. +.TP +.B CAP_FCHMODAT +An alias to +.B CAP_FCHMOD +and +.BR CAP_LOOKUP . +.TP +.B CAP_FCHOWN +Permit +.BR fchown (2) +and +.BR fchownat (2) +if the +.B CAP_LOOKUP +right is also present. +.TP +.B CAP_FCHOWNAT +An alias to +.B CAP_FCHOWN +and +.BR CAP_LOOKUP . +.TP +.B CAP_FCNTL +Permit +.BR fcntl (2). +Note that only the +.BR F_GETFL , +.BR F_SETFL , +.B F_GETOWN , +.B F_SETOWN , +.B F_GETOWN_EX +and +.B F_SETOWN_EX +commands require this capability right. +Also note that the list of permitted commands can be further limited with the +.BR cap_rights_limit (2) +system call. +.TP +.B CAP_FEXECVE +Permit +.BR execveat (2) +and +.BR openat (2) +with the +.B O_EXEC +flag; +.B CAP_READ +is also required. +.TP +.B CAP_FLOCK +Permit +.BR flock (2) +and +.BR fcntl (2) +(with +.BR F_GETLK , +.BR F_SETLK +or +.B F_SETLKW +flag). +.TP +.B CAP_FSTAT +Permit +.BR fstat (2). +.TP +.B CAP_FSTATFS +Permit +.BR fstatfs (2). +.TP +.B CAP_FSYNC +Permit +.BR fsync (2) +and +.BR openat (2) +with the +.B O_SYNC +flag. +.TP +.B CAP_FTRUNCATE +Permit +.BR ftruncate (2) +and +.BR openat (2) +with the +.B O_TRUNC +flag. +.TP +.B CAP_FUTIMES +Permit +.BR futimesat (2) +if the +.B CAP_LOOKUP +right is also present. +.TP +.B CAP_FUTIMESAT +An alias to +.B CAP_FUTIMES +and +.BR CAP_LOOKUP . +.TP +.B CAP_GETPEERNAME +Permit +.BR getpeername (2). +.TP +.B CAP_GETSOCKNAME +Permit +.BR getsockname (2). +.TP +.B CAP_GETSOCKOPT +Permit +.BR getsockopt (2). +.TP +.B CAP_IOCTL +Permit +.BR 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 +.BR cap_rights_limit (2) +system call. +.TP +.B CAP_LINKAT +Permit +.BR linkat (2) +and +.BR renameat (2) +on the destination directory descriptor. +This right includes the +.B CAP_LOOKUP +right. +.TP +.B CAP_LISTEN +Permit +.BR listen (2); +not much use (generally) without +.BR CAP_BIND . +.TP +.B CAP_LOOKUP +Permit the file descriptor to be used as a starting directory for calls such as +.BR linkat (2), +.BR openat (2), +and +.BR unlinkat (2). +.TP +.B CAP_MKDIRAT +Permit +.BR mkdirat (2). +This right includes the +.B CAP_LOOKUP +right. +.TP +.B CAP_MKFIFOAT +Permit +.BR mkfifoat (2). +This right includes the +.B CAP_LOOKUP +right. +.TP +.B CAP_MKNODAT +Permit +.BR mknodat (2). +This right includes the +.B CAP_LOOKUP +right. +.TP +.B CAP_MMAP +Permit +.BR mmap (2) +with the +.B PROT_NONE +protection. +.TP +.B CAP_MMAP_R +Permit +.BR mmap (2) +with the +.B PROT_READ +protection. +This right includes the +.B CAP_READ +and +.B CAP_SEEK +rights. +.TP +.B CAP_MMAP_RW +An alias to +.B CAP_MMAP_R +and +.BR CAP_MMAP_W . +.TP +.B CAP_MMAP_RWX +An alias to +.BR CAP_MMAP_R , +.B CAP_MMAP_W +and +.BR CAP_MMAP_X . +.TP +.B CAP_MMAP_RX +An alias to +.B CAP_MMAP_R +and +.BR CAP_MMAP_X . +.TP +.B CAP_MMAP_W +Permit +.BR mmap (2) +with the +.B PROT_WRITE +protection. +This right includes the +.B CAP_WRITE +and +.B CAP_SEEK +rights. +.TP +.B CAP_MMAP_WX +An alias to +.B CAP_MMAP_W +and +.BR CAP_MMAP_X . +.TP +.B CAP_MMAP_X +Permit +.BR mmap (2) +with the +.B PROT_EXEC +protection. +This right includes the +.B CAP_SEEK +right. +.TP +.B CAP_PDGETPID +Permit +.BR pdgetpid (2). +.TP +.B CAP_PDKILL +Permit +.BR pdkill (2). +.TP +.B CAP_PDWAIT +Permit +.BR pdwait4 (2). +.TP +.B CAP_PEELOFF +Permit +.BR sctp_peeloff (3). +.TP +.B CAP_PREAD +An alias to +.B CAP_READ +and +.BR CAP_SEEK . +.TP +.B CAP_PWRITE +An alias to +.B CAP_SEEK +and +.BR CAP_WRITE . +.TP +.B CAP_READ +Permit +.BR openat (2) +with the +.BR O_RDONLY flag, +.BR read (2), +.BR readv (2), +.BR recv (2), +.BR recvfrom (2), +.BR recvmsg (2), +.BR pread (2) +( +.B CAP_SEEK +is also required), +.BR preadv (2) +( +.B CAP_SEEK +is also required) and related system calls. +.TP +.B CAP_RECV +An alias to +.BR CAP_READ . +.TP +.B CAP_RENAMEAT +Permit +.BR renameat (2). +This right is required on the source directory descriptor. +This right includes the +.B CAP_LOOKUP +right. +.TP +.B CAP_SEEK +Permit operations that seek on the file descriptor, such as +.BR lseek (2), +but also required for I/O system calls that can read or write at any position +in the file, such as +.BR pread (2) +and +.BR pwrite (2). +.TP +.B CAP_SEND +An alias to +.BR CAP_WRITE . +.TP +.B CAP_SETSOCKOPT +Permit +.BR setsockopt (2); +this controls various aspects of socket behavior and may affect binding, +connecting, and other behaviors with global scope. +.TP +.B CAP_SHUTDOWN +Permit explicit +.BR shutdown (2); +closing the socket will also generally shut down any connections on it. +.TP +.B CAP_SYMLINKAT +Permit +.BR symlinkat (2). +This right includes the +.B CAP_LOOKUP +right. +.TP +.B CAP_UNLINKAT +Permit +.BR unlinkat (2) +and +.BR renameat (2). +This right is only required for +.BR renameat (2) +on the destination directory descriptor if the destination object already +exists and will be removed by the rename. +This right includes the +.B CAP_LOOKUP +right. +.TP +.B CAP_WRITE +Allow +.BR openat (2) +with +.B O_WRONLY +and +.B O_APPEND +flags set, +.BR send (2), +.BR sendmsg (2), +.BR sendto (2), +.BR write (2), +.BR writev (2), +.BR pwrite (2), +.BR pwritev (2) +and related system calls. +For +.BR sendto (2) +with a non-NULL connection address, +.B CAP_CONNECT +is also required. +For +.BR openat (2) +with the +.B O_WRONLY +flag, but without the +.B O_APPEND +flag, +.B CAP_SEEK +is also required. +For +.BR pwrite (2) +and +.BR pwritev (2) +.B CAP_SEEK +is also required. +.SH VERSIONS +Capsicum support was originally added to the kernel in version 3.???. +.SH SEE ALSO +.BR cap_enter (3), +.BR cap_fcntls_limit (3), +.BR cap_ioctls_limit (3), +.BR cap_rights_limit (2), +.BR cap_rights_limit (3), +.BR capsicum (7) -- 2.0.0.526.g5318336 -- To unsubscribe from this list: send the line "unsubscribe linux-api" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
