[PATCH 1/1] Describe the new namespaced file capabilities.

[Serge Hallyn]

---
 man7/user_namespaces.7 | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7
index 0c99df0..b1dd027 100644
--- a/man7/user_namespaces.7
+++ b/man7/user_namespaces.7
@@ -208,6 +208,41 @@ further removed descendant user namespaces as well.
 .\"
 .\" ============================================================
 .\"
+.SS File capabilities in user namespaces
+Until v4.9, writing file capabilities required the writer to possess
+.BR CAP_SETFCAP
+targeted at the initial user namespace.  In v4.10 a new version (v3) of the
+file capability extended attribute was introduced, which targets the
+capabilities at a namespace root userid.  This means that a task executing the
+file will receive elevated privilege only if it is running in a namespace whose
+root is mapped to the specified target uid.  If a task does not have
+.BR CAP_SETFCAP
+toward the user namespace which owns the filesystem hosting the file, then it
+can only write file capabilities targeted at uids mapped in the task's own
+namespace.
+
+As a detailed example, assume a user namespace where uid 0 is mapped to host
+uid 100000.  Root in the container writes a file capability.  If the file
+capability xattr is v2, then a v3 capability xattr targeted to 100000 will be
+written.
+
+If instead a v3 capability xattr is written, then the kernel will verify that
+the writer is privileged with
+.BR CAP_SETFCAP
+over its own namespace and that the file owner's uid and gid are mapped into
+the current task's namespace.
+
+The capability target uid which is written to disk is mapped into the
+filesystem's user namespace.  Therefore, in the above example, if uid 0 in the
+namespace (100000 on the host) mounted the filesystem, the target uid value
+actually written will be converted back to 0 (the mapped value for host uid
+100000).  In this case the mount will be treated as foreign for any tasks in
+the initial user namespace, so that the file capability (as well as setuid and
+setgid bits) will be ignored, preventing a leak of privilege.
+
+.\"
+.\" ============================================================
+.\"
 .SS Effect of capabilities within a user namespace
 Having a capability inside a user namespace
 permits a process to perform operations (that require privilege)
-- 
2.7.4