From 7a536207483e677f1075e529cbd396dd649b2cdc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nikola=20Forr=C3=B3?= Date: Wed, 3 Aug 2016 12:58:59 +0200 Subject: [PATCH] prctl.2, capabilities.7: document ambient capabilities --- man-pages/man2/prctl.2 | 77 +++++++++++++++++++++++++++++++++++++++++++ man-pages/man7/capabilities.7 | 51 ++++++++++++++++++++++++---- 2 files changed, 122 insertions(+), 6 deletions(-) diff --git a/man-pages/man2/prctl.2 b/man-pages/man2/prctl.2 index 92eecf9..cd6daef 100644 --- a/man-pages/man2/prctl.2 +++ b/man-pages/man2/prctl.2 @@ -844,6 +844,42 @@ 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.3)" +.\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08 +Reads or changes the ambient capability set, according to the value of +.IR arg2 , +which must be one of the following: +.RS +.TP +.B PR_CAP_AMBIENT_RAISE +The capability specified in +.I arg3 +is added to the ambient set. +The specified capability must already be present in +both the permitted and the inheritable sets of the process. +This operation is not permitted if the +.B SECBIT_NO_CAP_AMBIENT_RAISE +securebit is set. +.TP +.B PR_CAP_AMBIENT_LOWER +The capability specified in +.I arg3 +is removed from the ambient set. +.TP +.B PR_CAP_AMBIENT_IS_SET +The +.BR prctl (2) +call returns 1 if the capability in +.I arg3 +is in the ambient set and 0 if it is not. +.TP +.BR PR_CAP_AMBIENT_CLEAR_ALL +All capabilities will be removed from the ambient set. +This operation requires setting +.I arg3 +to zero. +.RE .SH RETURN VALUE On success, .BR PR_GET_DUMPABLE , @@ -853,6 +889,7 @@ On success, .BR PR_GET_TIMING , .BR PR_GET_SECUREBITS , .BR PR_MCE_KILL_GET , +.BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET , and (if it returns) .BR PR_GET_SECCOMP return the nonnegative values described above. @@ -949,6 +986,31 @@ is not 0, .BR PR_SET_PTRACER_ANY , or the PID of an existing process. .TP +.B EINVAL +.I option +is +.B PR_CAP_AMBIENT +and an unused argument +.RI ( arg4 , +.IR arg5 , +or, +in the case of +.BR PR_CAP_AMBIENT_CLEAR_ALL , +.IR arg3 ) +is nonzero; or +.IR arg2 +has an invalid value; +or +.IR arg2 +is +.BR PR_CAP_AMBIENT_LOWER , +.BR PR_CAP_AMBIENT_RAISE , +or +.BR PR_CAP_AMBIENT_IS_SET +and +.IR arg3 +does not specify a valid capability. +.TP .B EPERM .I option is @@ -1030,6 +1092,21 @@ capability. .\" .BR PR_SET_SECCOMP , .\" and secure computing mode is already 1. .TP +.B EPERM +.IR option +is +.BR PR_CAP_AMBIENT +and +.IR arg2 +is +.BR PR_CAP_AMBIENT_RAISE , +but either the capability specified in +.IR arg3 +is not present in the process's permitted and inheritable capability sets, +or the +.B PR_CAP_AMBIENT_LOWER +securebit has been set. +.TP .B ENXIO .I option was diff --git a/man-pages/man7/capabilities.7 b/man-pages/man7/capabilities.7 index 2c3377e..c340245 100644 --- a/man-pages/man7/capabilities.7 +++ b/man-pages/man7/capabilities.7 @@ -659,13 +659,40 @@ 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. +.IP +Because inheritable capabilities are not generally preserved across +.BR execve (2) +when running as a non-root user, applications that wish to run helper +programs with elevated capabilities should consider using +ambient capabilities, described below. .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.3):" +.\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08 +This is a set of capabilities that are preserved across an +.BR execve (2) +of a program that is not privileged. +The ambient capability set obeys the invariant that no capability +can ever be ambient if it is not both permitted and inheritable. + +The ambient capability set can be directly modified using +.BR prctl (2). +Ambient capabilities are automatically lowered if either of +the corresponding permitted or inheritable capabilities is lowered. + +Executing a program that changes UID or GID due to the +set-user-ID or set-group-ID bits or executing a program that has +any file capabilities set will clear the ambient set. +Ambient capabilities are added to the permitted set and +assigned to the effective set when +.BR execve (2) +is called. .PP A child created via .BR fork (2) @@ -747,10 +774,12 @@ the process using the following algorithm: .in +4n .nf +P'(ambient) = (file is privileged) ? 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] @@ -769,6 +798,9 @@ denotes a file capability set .IP cap_bset is the value of the capability bounding set (described below). .RE +.PP +A privileged file is one that has capabilities or +has the set-user-ID or set-group-ID bit set. .\" .SS Capabilities and execution of programs by root In order to provide an all-powerful @@ -1029,6 +1061,12 @@ 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 raising ambient capabilities via the +.BR prctl (2) +.BR PR_CAP_AMBIENT_RAISE +operation. .PP Each of the above "base" flags has a companion "locked" flag. Setting any of the "locked" flags is irreversible, @@ -1037,8 +1075,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.7.4