From 7a536207483e677f1075e529cbd396dd649b2cdc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nikola=20Forr=C3=B3?= <nforro@redhat.com>
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