On Mon, Jun 30, 2014 at 3:28 AM, David Drysdale <drysdale@xxxxxxxxxx> wrote: > Signed-off-by: David Drysdale <drysdale@xxxxxxxxxx> > --- > man2/cap_rights_limit.2 | 171 ++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 171 insertions(+) > create mode 100644 man2/cap_rights_limit.2 > > diff --git a/man2/cap_rights_limit.2 b/man2/cap_rights_limit.2 > new file mode 100644 > index 000000000000..3484ee1076aa > --- /dev/null > +++ b/man2/cap_rights_limit.2 > @@ -0,0 +1,171 @@ > +.\" > +.\" Copyright (c) 2008-2010 Robert N. M. Watson > +.\" Copyright (c) 2012-2013 The FreeBSD Foundation > +.\" Copyright (c) 2013-2014 Google, Inc. > +.\" All rights reserved. > +.\" > +.\" %%%LICENSE_START(BSD_2_CLAUSE) > +.\" 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 CAP_RIGHTS_LIMIT 2 2014-05-07 "Linux" "Linux Programmer's Manual" > +.SH NAME > +cap_rights_limit \- limit Capsicum capability rights > +.SH SYNOPSIS > +.nf > +.B #include <sys/capsicum.h> > +.sp > +.BI "int cap_rights_limit(int " fd ", const struct cap_rights *" rights , > +.BI " unsigned int " fcntls , > +.BI " int " nioctls ", unsigned int *" ioctls ); Am I missing the docs for struct cap_rights somewhere? > +.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 () > +system call. > +Once Capsicum capability rights are reduced, operations on the file descriptor > +.I fd > +will be limited to those permitted by the remainder of the arguments. > +.PP > +The > +.I rights > +argument describes the primary rights for the file descriptor, and > +should be prepared using > +.BR cap_rights_init (3) > +family of functions. The complete list of primary rights can be found in the > +.BR rights (7) > +manual page. > +.PP > +If a file descriptor is granted the > +.B CAP_FCNTL > +primary capability right, the list of allowed > +.BR fcntl (2) > +commands can be selectively reduced (but never expanded) with the > +.I fcntls > +argument. The following flags may be specified in the > +.I fcntls > +argument: > +.TP > +.B CAP_FCNTL_GETFL > +Permit > +.B F_GETFL > +command. > +.TP > +.B CAP_FCNTL_SETFL > +Permit > +.B F_SETFL > +command. > +.TP > +.B CAP_FCNTL_GETOWN > +Permit > +.B F_GETOWN > +command. > +.TP > +.B CAP_FCNTL_SETOWN > +Permit > +.B F_SETOWN > +command. > +.PP > +A value of > +.B CAP_FCNTL_ALL > +for the > +.I fcntls > +argument leaves the set of allowed > +.BR fcntl (2) > +commands unchanged. What about the locking fcntl operations? (Arguably the old crappy POSIX lock operations should be flat-out disallowed on capability fds, but I see nothing wrong with selectively allowing the new open file description locks.) --Andy -- 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
