landlock.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2.. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net>
  3.. Copyright © 2019-2020 ANSSI
  4
  5==================================
  6Landlock LSM: kernel documentation
  7==================================
  8
  9:Author: Mickaël Salaün
 10:Date: September 2025
 11
 12Landlock's goal is to create scoped access-control (i.e. sandboxing).  To
 13harden a whole system, this feature should be available to any process,
 14including unprivileged ones.  Because such a process may be compromised or
 15backdoored (i.e. untrusted), Landlock's features must be safe to use from the
 16kernel and other processes point of view.  Landlock's interface must therefore
 17expose a minimal attack surface.
 18
 19Landlock is designed to be usable by unprivileged processes while following the
 20system security policy enforced by other access control mechanisms (e.g. DAC,
 21LSM).  A Landlock rule shall not interfere with other access-controls enforced
 22on the system, only add more restrictions.
 23
 24Any user can enforce Landlock rulesets on their processes.  They are merged and
 25evaluated against inherited rulesets in a way that ensures that only more
 26constraints can be added.
 27
 28User space documentation can be found here:
 29Documentation/userspace-api/landlock.rst.
 30
 31Guiding principles for safe access controls
 32===========================================
 33
 34* A Landlock rule shall be focused on access control on kernel objects instead
 35  of syscall filtering (i.e. syscall arguments), which is the purpose of
 36  seccomp-bpf.
 37* To avoid multiple kinds of side-channel attacks (e.g. leak of security
 38  policies, CPU-based attacks), Landlock rules shall not be able to
 39  programmatically communicate with user space.
 40* Kernel access check shall not slow down access request from unsandboxed
 41  processes.
 42* Computation related to Landlock operations (e.g. enforcing a ruleset) shall
 43  only impact the processes requesting them.
 44* Resources (e.g. file descriptors) directly obtained from the kernel by a
 45  sandboxed process shall retain their scoped accesses (at the time of resource
 46  acquisition) whatever process uses them.
 47  Cf. `File descriptor access rights`_.
 48* Access denials shall be logged according to system and Landlock domain
 49  configurations.  Log entries must contain information about the cause of the
 50  denial and the owner of the related security policy.  Such log generation
 51  should have a negligible performance and memory impact on allowed requests.
 52
 53Design choices
 54==============
 55
 56Inode access rights
 57-------------------
 58
 59All access rights are tied to an inode and what can be accessed through it.
 60Reading the content of a directory does not imply to be allowed to read the
 61content of a listed inode.  Indeed, a file name is local to its parent
 62directory, and an inode can be referenced by multiple file names thanks to
 63(hard) links.  Being able to unlink a file only has a direct impact on the
 64directory, not the unlinked inode.  This is the reason why
 65``LANDLOCK_ACCESS_FS_REMOVE_FILE`` or ``LANDLOCK_ACCESS_FS_REFER`` are not
 66allowed to be tied to files but only to directories.
 67
 68File descriptor access rights
 69-----------------------------
 70
 71Access rights are checked and tied to file descriptors at open time.  The
 72underlying principle is that equivalent sequences of operations should lead to
 73the same results, when they are executed under the same Landlock domain.
 74
 75Taking the ``LANDLOCK_ACCESS_FS_TRUNCATE`` right as an example, it may be
 76allowed to open a file for writing without being allowed to
 77:manpage:`ftruncate` the resulting file descriptor if the related file
 78hierarchy doesn't grant that access right.  The following sequences of
 79operations have the same semantic and should then have the same result:
 80
 81* ``truncate(path);``
 82* ``int fd = open(path, O_WRONLY); ftruncate(fd); close(fd);``
 83
 84Similarly to file access modes (e.g. ``O_RDWR``), Landlock access rights
 85attached to file descriptors are retained even if they are passed between
 86processes (e.g. through a Unix domain socket).  Such access rights will then be
 87enforced even if the receiving process is not sandboxed by Landlock.  Indeed,
 88this is required to keep access controls consistent over the whole system, and
 89this avoids unattended bypasses through file descriptor passing (i.e. confused
 90deputy attack).
 91
 92Tests
 93=====
 94
 95Userspace tests for backward compatibility, ptrace restrictions and filesystem
 96support can be found here: `tools/testing/selftests/landlock/`_.
 97
 98Kernel structures
 99=================
100
101Object
102------
103
104.. kernel-doc:: security/landlock/object.h
105    :identifiers:
106
107Filesystem
108----------
109
110.. kernel-doc:: security/landlock/fs.h
111    :identifiers:
112
113Process credential
114------------------
115
116.. kernel-doc:: security/landlock/cred.h
117    :identifiers:
118
119Ruleset and domain
120------------------
121
122A domain is a read-only ruleset tied to a set of subjects (i.e. tasks'
123credentials).  Each time a ruleset is enforced on a task, the current domain is
124duplicated and the ruleset is imported as a new layer of rules in the new
125domain.  Indeed, once in a domain, each rule is tied to a layer level.  To
126grant access to an object, at least one rule of each layer must allow the
127requested action on the object.  A task can then only transit to a new domain
128that is the intersection of the constraints from the current domain and those
129of a ruleset provided by the task.
130
131The definition of a subject is implicit for a task sandboxing itself, which
132makes the reasoning much easier and helps avoid pitfalls.
133
134.. kernel-doc:: security/landlock/ruleset.h
135    :identifiers:
136
137.. kernel-doc:: security/landlock/domain.h
138    :identifiers:
139
140Additional documentation
141========================
142
143* Documentation/userspace-api/landlock.rst
144* Documentation/admin-guide/LSM/landlock.rst
145* https://landlock.io
146
147.. Links
148.. _tools/testing/selftests/landlock/:
149   https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/