summaryrefslogtreecommitdiff
path: root/Documentation/userspace-api
diff options
context:
space:
mode:
authorMickaël Salaün <mic@digikod.net>2022-05-06 18:11:01 +0200
committerMickaël Salaün <mic@digikod.net>2022-05-23 13:28:01 +0200
commit09340cf4135f942d56742b36aaa3c37738aba000 (patch)
treece6655b5ebeeb899e291374c94fa81d839527e75 /Documentation/userspace-api
parent6f59abfae35fbbe688ff790ff9638576956d760c (diff)
landlock: Document good practices about filesystem policies
Explain how to set access rights per hierarchy in an efficient and safe way, especially with the LANDLOCK_ACCESS_FS_REFER side effect (i.e. partial ordering and constraints for access rights per hierarchy). Reviewed-by: Paul Moore <paul@paul-moore.com> Signed-off-by: Mickaël Salaün <mic@digikod.net> Link: https://lore.kernel.org/r/20220506161102.525323-12-mic@digikod.net
Diffstat (limited to 'Documentation/userspace-api')
-rw-r--r--Documentation/userspace-api/landlock.rst21
1 files changed, 21 insertions, 0 deletions
diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index ae2aea986aa6..7b4fe6218132 100644
--- a/Documentation/userspace-api/landlock.rst
+++ b/Documentation/userspace-api/landlock.rst
@@ -156,6 +156,27 @@ ruleset.
Full working code can be found in `samples/landlock/sandboxer.c`_.
+Good practices
+--------------
+
+It is recommended setting access rights to file hierarchy leaves as much as
+possible. For instance, it is better to be able to have ``~/doc/`` as a
+read-only hierarchy and ``~/tmp/`` as a read-write hierarchy, compared to
+``~/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy.
+Following this good practice leads to self-sufficient hierarchies that don't
+depend on their location (i.e. parent directories). This is particularly
+relevant when we want to allow linking or renaming. Indeed, having consistent
+access rights per directory enables to change the location of such directory
+without relying on the destination directory access rights (except those that
+are required for this operation, see `LANDLOCK_ACCESS_FS_REFER` documentation).
+Having self-sufficient hierarchies also helps to tighten the required access
+rights to the minimal set of data. This also helps avoid sinkhole directories,
+i.e. directories where data can be linked to but not linked from. However,
+this depends on data organization, which might not be controlled by developers.
+In this case, granting read-write access to ``~/tmp/``, instead of write-only
+access, would potentially allow to move ``~/tmp/`` to a non-readable directory
+and still keep the ability to list the content of ``~/tmp/``.
+
Layers of file path access rights
---------------------------------