From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1760564AbaGYNsl (ORCPT ); Fri, 25 Jul 2014 09:48:41 -0400 Received: from mail-wi0-f202.google.com ([209.85.212.202]:47550 "EHLO mail-wi0-f202.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1760496AbaGYNsb (ORCPT ); Fri, 25 Jul 2014 09:48:31 -0400 From: David Drysdale To: linux-security-module@vger.kernel.org, linux-kernel@vger.kernel.org, Greg Kroah-Hartman Cc: Alexander Viro , Meredydd Luff , Kees Cook , James Morris , Andy Lutomirski , Paolo Bonzini , Paul Moore , Christoph Hellwig , linux-api@vger.kernel.org, David Drysdale Subject: [PATCH 4/6] cap_rights_limit.2: limit FD rights for Capsicum Date: Fri, 25 Jul 2014 14:47:11 +0100 Message-Id: <1406296033-32693-16-git-send-email-drysdale@google.com> X-Mailer: git-send-email 2.0.0.526.g5318336 In-Reply-To: <1406296033-32693-1-git-send-email-drysdale@google.com> References: <1406296033-32693-1-git-send-email-drysdale@google.com> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Signed-off-by: David Drysdale --- man2/cap_rights_limit.2 | 241 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 241 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..450bbdc6f86d --- /dev/null +++ b/man2/cap_rights_limit.2 @@ -0,0 +1,241 @@ +.\" +.\" 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 +.sp +.BI "int cap_rights_limit(int " fd ", const struct cap_rights *" rights , +.BI " unsigned int " fcntls , +.BI " int " nioctls ", unsigned int *" ioctls ); +.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, as a +.I cap_rights +structure: +.in +4n +.nf + +#define CAP_RIGHTS_VERSION_00 0 +#define CAP_RIGHTS_VERSION_01 1 +#define CAP_RIGHTS_VERSION_02 2 +#define CAP_RIGHTS_VERSION_03 3 +#define CAP_RIGHTS_VERSION CAP_RIGHTS_VERSION_00 +struct cap_rights { + __u64 cr_rights[CAP_RIGHTS_VERSION + 2]; +}; +.fi +.in +.PP +The contents of the +.I cr_rights +array are encoded as follows. +.IP \(bu +The top 2 bits of +.I cr_rights[0] +hold the array size minus 2, allowing for an array size between 2 and 5 inclusive. +.IP \(bu +The top 2 bits of the other +.I cr_rights +entries are zero. +.IP \(bu +The following 5 bits of each array entry indicate its position in the array, +from 0b00001 for entry [0], 0b00010 for entry [1], up to 0b10000 for entry [4]. +.IP \(bu +The remaining 57 bits of each array entry identify a particular primary +right. +.PP +This encoding allows for future expansion in the number of distinct rights; +for example, a +.I cap_rights +structure holding the +.B CAP_READ +and +.B CAP_BINDAT +rights would have contents of +.in +4n +.nf +0x0200000000000001 0x0400000000001000 +.fi +.in +as a version 0 array, but would be encoded in a larger version 1 array as +.in +4n +.nf +0x4200000000000001 0x0400000000001000 0x0800000000000000. +.fi +.in +.PP +User programs should prepare the contents of the +.I cap_rights +structure with the +.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, some specific +.BR fcntl (2) +commands can be selectively disallowed with the +.I fcntls +argument. The following flags may be specified in the +.I fcntls +argument for this: +.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. +.PP +However, note that +.BR fcntl (2) +commands that are analogous to other system calls +(such as +.B F_DUPFD +or +.BR F_GETPIPE_SZ ) +are not controlled by the +.B CAP_FCNTL +right and so do not have corresponding values in the +.I fcntls +argument. +.PP +If a file descriptor is granted the +.B CAP_IOCTL +capability right, the list of allowed +.BR ioctl (2) +commands can be selectively reduced (but never expanded) using the +.I nioctls +and +.I ioctls +arguments. +The +.I ioctls +argument is an array of +.BR ioctl (2) +command values and the +.I nioctls +argument specifies the number of elements in the array. +.PP +If the +.I nioctls +argument is -1 or 0, the +.I ioctls +argument is ignored, and either all +.BR ioctl (2) +operations or no +.BR ioctl (2) +operations (respectively) will be allowed. +.PP +Capsicum capability rights assigned to a file descriptor can be obtained with the +.BR cap_rights_get (2) +system call. +.SH RETURN VALUE +.BR cap_rights_limit () +returns zero on success. On error, -1 is returned and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +.I fd +isn't a valid open file descriptor. +.TP +.B EINVAL +An invalid set of rights has been requested in +.IR rights . +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOTCAPABLE +The arguments contain capability rights not present for the given file descriptor (Capsicum +capability rights list can only be reduced, never expanded). +.SH VERSION +Capsicum support was added to the kernel in version 3.???. +.SH SEE ALSO +.BR cap_enter (2), +.BR cap_rights_get (2), +.BR cap_rights_init (3), +.BR capsicum (7), +.BR rights (7) -- 2.0.0.526.g5318336