[PATCH v9 6/9] landlock: Add documentation for LANDLOCK_ADD_RULE_NO_INHERIT

[Justin Suess]

Add documentation of the flag to the userspace API, describing the
functionality of the flag and parent directory protections.

Signed-off-by: Justin Suess <utilityemal77 at gmail.com>
---

Notes:
    Changes since v8:
    - Expanded the userspace-api documentation: the conservative seal
      (same-directory renames and hard links denied; rules keyed by inode),
      the best-effort ancestor walk, guidance to discard a partially applied
      policy on error, and the threat-model paragraph.
    - Updated the ABI references to version 11.
    - Rebased onto mic/next.

 Documentation/userspace-api/landlock.rst | 44 ++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index 5a63d4476c1c..01623e0ab95d 100644
--- a/Documentation/userspace-api/landlock.rst
+++ b/Documentation/userspace-api/landlock.rst
@@ -789,6 +789,50 @@ when at least one sys_landlock_add_rule() call is made for it with the
 ``LANDLOCK_ADD_RULE_QUIET`` flag, additional add-rule calls for the same
 object without this flag do not clear it.
 
+Filesystem inheritance suppression (ABI < 11)
+---------------------------------------------
+
+Starting with the Landlock ABI version 11, it is possible to prevent a
+directory or file from inheriting its parent's access grants by using the
+``LANDLOCK_ADD_RULE_NO_INHERIT`` flag passed to sys_landlock_add_rule().
+This is useful for policies where a parent directory needs broader access
+than its children.
+
+To mitigate sandbox-restart attacks, the tagged inode and all of its
+ancestors up to the VFS root cannot be removed, renamed, reparented, or
+linked into or out of other directories.
+
+This seal is intentionally conservative: every rename, removal or link
+operation that targets a sealed inode is denied, including same-directory
+renames and hard links that do not change the inode's parent.  Landlock rules
+are keyed by inode, so such operations could not by themselves bypass a seal,
+but denying them as well keeps enforcement simple and leaves no edge cases
+that could weaken the guarantee.
+
+Inheritance of access grants from descendants of an inode tagged with
+``LANDLOCK_ADD_RULE_NO_INHERIT`` is unaffected: such descendants continue
+to inherit from the tagged inode normally, unless they also carry this
+flag.
+
+Because sealing an inode also seals all of its ancestors, the kernel walks
+the path up to the VFS root while adding such a rule, sealing each ancestor in
+turn.  This walk is best effort: it is not serialized against concurrent
+renames, so a rename that reparents one of the ancestors while the walk is in
+progress may leave the seal incomplete.
+
+Similarly, if sys_landlock_add_rule() returns an error while adding a
+``LANDLOCK_ADD_RULE_NO_INHERIT`` rule (for example because of memory
+pressure), the ruleset may have been left with the rule's object and only some
+of its ancestors sealed.  Such a ruleset should be discarded rather than
+enforced.
+
+This is not a security concern.  Changes to the filesystem hierarchy between
+the time a ruleset is built and the time it is enforced are outside of
+Landlock's threat model: a ruleset only describes the restrictions that take
+effect once it is enforced, and what happens to the hierarchy beforehand is
+not controlled by Landlock.  Once enforced, the seals that were established
+deny the topology changes they cover.
+
 .. _kernel_support:
 
 Kernel support
-- 
2.54.0