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: March 2026 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 92.. _scoped-flags-interaction: 93 94Interaction between scoped flags and other access rights 95-------------------------------------------------------- 96 97The ``scoped`` flags in &struct landlock_ruleset_attr restrict the 98use of *outgoing* IPC from the created Landlock domain, while they 99permit reaching out to IPC endpoints *within* the created Landlock 100domain. 101 102In the future, scoped flags *may* interact with other access rights, 103e.g. so that abstract UNIX sockets can be allow-listed by name, or so 104that signals can be allow-listed by signal number or target process. 105 106When introducing ``LANDLOCK_ACCESS_FS_RESOLVE_UNIX``, we defined it to 107implicitly have the same scoping semantics as a 108``LANDLOCK_SCOPE_PATHNAME_UNIX_SOCKET`` flag would have: connecting to 109UNIX sockets within the same domain (where 110``LANDLOCK_ACCESS_FS_RESOLVE_UNIX`` is used) is unconditionally 111allowed. 112 113The reasoning is: 114 115* Like other IPC mechanisms, connecting to named UNIX sockets in the 116 same domain should be expected and harmless. (If needed, users can 117 further refine their Landlock policies with nested domains or by 118 restricting ``LANDLOCK_ACCESS_FS_MAKE_SOCK``.) 119* We reserve the option to still introduce 120 ``LANDLOCK_SCOPE_PATHNAME_UNIX_SOCKET`` in the future. (This would 121 be useful if we wanted to have a Landlock rule to permit IPC access 122 to other Landlock domains.) 123* But we can postpone the point in time when users have to deal with 124 two interacting flags visible in the userspace API. (In particular, 125 it is possible that it won't be needed in practice, in which case we 126 can avoid the second flag altogether.) 127* If we *do* introduce ``LANDLOCK_SCOPE_PATHNAME_UNIX_SOCKET`` in the 128 future, setting this scoped flag in a ruleset does *not reduce* the 129 restrictions, because access within the same scope is already 130 allowed based on ``LANDLOCK_ACCESS_FS_RESOLVE_UNIX``. 131 132Tests 133===== 134 135Userspace tests for backward compatibility, ptrace restrictions and filesystem 136support can be found here: `tools/testing/selftests/landlock/`_. 137 138Kernel structures 139================= 140 141Object 142------ 143 144.. kernel-doc:: security/landlock/object.h 145 :identifiers: 146 147Filesystem 148---------- 149 150.. kernel-doc:: security/landlock/fs.h 151 :identifiers: 152 153Process credential 154------------------ 155 156.. kernel-doc:: security/landlock/cred.h 157 :identifiers: 158 159Ruleset and domain 160------------------ 161 162A domain is a read-only ruleset tied to a set of subjects (i.e. tasks' 163credentials). Each time a ruleset is enforced on a task, the current domain is 164duplicated and the ruleset is imported as a new layer of rules in the new 165domain. Indeed, once in a domain, each rule is tied to a layer level. To 166grant access to an object, at least one rule of each layer must allow the 167requested action on the object. A task can then only transit to a new domain 168that is the intersection of the constraints from the current domain and those 169of a ruleset provided by the task. 170 171The definition of a subject is implicit for a task sandboxing itself, which 172makes the reasoning much easier and helps avoid pitfalls. 173 174.. kernel-doc:: security/landlock/ruleset.h 175 :identifiers: 176 177.. kernel-doc:: security/landlock/domain.h 178 :identifiers: 179 180Additional documentation 181======================== 182 183* Documentation/userspace-api/landlock.rst 184* Documentation/admin-guide/LSM/landlock.rst 185* https://landlock.io 186 187.. Links 188.. _tools/testing/selftests/landlock/: 189 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/ 190