Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754647AbbEOGoP (ORCPT ); Fri, 15 May 2015 02:44:15 -0400 Received: from mail.kernel.org ([198.145.29.136]:57988 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753999AbbEOGoL (ORCPT ); Fri, 15 May 2015 02:44:11 -0400 From: Andy Lutomirski To: Serge Hallyn , Andrew Morton Cc: Jarkko Sakkinen , Andrew Lutomirski , "Ted Ts'o" , "Andrew G. Morgan" , Linux API , Mimi Zohar , Michael Kerrisk , Austin S Hemmelgarn , linux-security-module , Aaron Jones , Serge Hallyn , LKML , Markku Savela , Kees Cook , Jonathan Corbet Subject: [PATCH man-pages v2] capabilities.7, prctl.2: Document ambient capabilities Date: Thu, 14 May 2015 23:43:45 -0700 Message-Id: X-Mailer: git-send-email 2.1.0 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 3996 Lines: 110 Signed-off-by: Andy Lutomirski --- There was no v1. I'm calling this v2 to keep it in sync with the kernel patch versioning. man2/prctl.2 | 10 ++++++++++ man7/capabilities.7 | 32 ++++++++++++++++++++++++++------ 2 files changed, 36 insertions(+), 6 deletions(-) diff --git a/man2/prctl.2 b/man2/prctl.2 index b352f6283624..5861e3aefe9a 100644 --- a/man2/prctl.2 +++ b/man2/prctl.2 @@ -949,6 +949,16 @@ had been called. For further information on Intel MPX, see the kernel source file .IR Documentation/x86/intel_mpx.txt . .\" +.TP +.BR PR_CAP_AMBIENT " (since Linux 4.2)" +Reads or changes the ambient capability set. If arg2 is PR_CAP_AMBIENT_RAISE, +then the capability specified in arg3 is added to the ambient set. This will +fail, returning EPERM, if the capability is not already both permitted and +inheritable or if the SECBIT_NO_CAP_AMBIENT_RAISE securebit is set. If arg2 +is PR_CAP_AMBIENT_LOWER, then the capability specified in arg3 is removed +from the ambient set. If arg2 is PR_CAP_AMBIENT_GET, then +.BR prctl (2) +will return 1 if the capability in arg3 is in the ambient set and 0 if not. .SH RETURN VALUE On success, .BR PR_GET_DUMPABLE , diff --git a/man7/capabilities.7 b/man7/capabilities.7 index d75ec65de05b..dae62f0be3b7 100644 --- a/man7/capabilities.7 +++ b/man7/capabilities.7 @@ -697,13 +697,26 @@ a program whose associated file capabilities grant that capability). .IR Inheritable : This is a set of capabilities preserved across an .BR execve (2). -It provides a mechanism for a process to assign capabilities -to the permitted set of the new program during an -.BR execve (2). +Inheritable capabilities remain inheritable when executing any program, +and inheritable capabilities are added to the permitted set when executing +a program that has the corresponding bits set in the file inheritable set. +When executing programs without file capabilities, ambient capabilities .TP .IR Effective : This is the set of capabilities used by the kernel to perform permission checks for the thread. +.TP +.IR Ambient " (since Linux 4.2) :" +This is a set of capabilities that are preserved across an +.BR execve (2) +of a program that does not have file capabilities. The ambient capability +set obeys the invariant that no capability can ever be ambient if it is +not both permitted and inheritable. Ambient capabilities are, with some +exceptions, preserved in the permitted set and added to the effective +set when +.BR execve (2) +is called. The ambient capability set is modified using +.BR prctl (2). .PP A child created via .BR fork (2) @@ -785,10 +798,12 @@ the process using the following algorithm: .in +4n .nf +P'(ambient) = (file has capabilities or is setuid or setgid) ? 0 : P(ambient) + P'(permitted) = (P(inheritable) & F(inheritable)) | - (F(permitted) & cap_bset) + (F(permitted) & cap_bset) | P'(ambient) -P'(effective) = F(effective) ? P'(permitted) : 0 +P'(effective) = F(effective) ? P'(permitted) : P'(ambient) P'(inheritable) = P(inheritable) [i.e., unchanged] @@ -1071,6 +1086,10 @@ an effective or real UID of 0 calls .BR execve (2). (See the subsection .IR "Capabilities and execution of programs by root" .) +.TP +.B SECBIT_NO_CAP_AMBIENT_RAISE +Setting this flag disallows +.BR PR_CAP_AMBIENT_RAISE . .PP Each of the above "base" flags has a companion "locked" flag. Setting any of the "locked" flags is irreversible, @@ -1079,8 +1098,9 @@ corresponding "base" flag. The locked flags are: .BR SECBIT_KEEP_CAPS_LOCKED , .BR SECBIT_NO_SETUID_FIXUP_LOCKED , +.BR SECBIT_NOROOT_LOCKED , and -.BR SECBIT_NOROOT_LOCKED . +.BR SECBIT_NO_CAP_AMBIENT_RAISE . .PP The .I securebits -- 2.1.0 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/