0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net>
0003 .. Copyright © 2019-2020 ANSSI
0004
0005 ==================================
0006 Landlock LSM: kernel documentation
0007 ==================================
0008
0009 :Author: Mickaël Salaün
0010 :Date: May 2022
0011
0012 Landlock's goal is to create scoped access-control (i.e. sandboxing). To
0013 harden a whole system, this feature should be available to any process,
0014 including unprivileged ones. Because such process may be compromised or
0015 backdoored (i.e. untrusted), Landlock's features must be safe to use from the
0016 kernel and other processes point of view. Landlock's interface must therefore
0017 expose a minimal attack surface.
0018
0019 Landlock is designed to be usable by unprivileged processes while following the
0020 system security policy enforced by other access control mechanisms (e.g. DAC,
0021 LSM). Indeed, a Landlock rule shall not interfere with other access-controls
0022 enforced on the system, only add more restrictions.
0023
0024 Any user can enforce Landlock rulesets on their processes. They are merged and
0025 evaluated according to the inherited ones in a way that ensures that only more
0026 constraints can be added.
0027
0028 User space documentation can be found here:
0029 Documentation/userspace-api/landlock.rst.
0030
0031 Guiding principles for safe access controls
0032 ===========================================
0033
0034 * A Landlock rule shall be focused on access control on kernel objects instead
0035 of syscall filtering (i.e. syscall arguments), which is the purpose of
0036 seccomp-bpf.
0037 * To avoid multiple kinds of side-channel attacks (e.g. leak of security
0038 policies, CPU-based attacks), Landlock rules shall not be able to
0039 programmatically communicate with user space.
0040 * Kernel access check shall not slow down access request from unsandboxed
0041 processes.
0042 * Computation related to Landlock operations (e.g. enforcing a ruleset) shall
0043 only impact the processes requesting them.
0044
0045 Design choices
0046 ==============
0047
0048 Filesystem access rights
0049 ------------------------
0050
0051 All access rights are tied to an inode and what can be accessed through it.
0052 Reading the content of a directory doesn't imply to be allowed to read the
0053 content of a listed inode. Indeed, a file name is local to its parent
0054 directory, and an inode can be referenced by multiple file names thanks to
0055 (hard) links. Being able to unlink a file only has a direct impact on the
0056 directory, not the unlinked inode. This is the reason why
0057 `LANDLOCK_ACCESS_FS_REMOVE_FILE` or `LANDLOCK_ACCESS_FS_REFER` are not allowed
0058 to be tied to files but only to directories.
0059
0060 Tests
0061 =====
0062
0063 Userspace tests for backward compatibility, ptrace restrictions and filesystem
0064 support can be found here: `tools/testing/selftests/landlock/`_.
0065
0066 Kernel structures
0067 =================
0068
0069 Object
0070 ------
0071
0072 .. kernel-doc:: security/landlock/object.h
0073 :identifiers:
0074
0075 Filesystem
0076 ----------
0077
0078 .. kernel-doc:: security/landlock/fs.h
0079 :identifiers:
0080
0081 Ruleset and domain
0082 ------------------
0083
0084 A domain is a read-only ruleset tied to a set of subjects (i.e. tasks'
0085 credentials). Each time a ruleset is enforced on a task, the current domain is
0086 duplicated and the ruleset is imported as a new layer of rules in the new
0087 domain. Indeed, once in a domain, each rule is tied to a layer level. To
0088 grant access to an object, at least one rule of each layer must allow the
0089 requested action on the object. A task can then only transit to a new domain
0090 that is the intersection of the constraints from the current domain and those
0091 of a ruleset provided by the task.
0092
0093 The definition of a subject is implicit for a task sandboxing itself, which
0094 makes the reasoning much easier and helps avoid pitfalls.
0095
0096 .. kernel-doc:: security/landlock/ruleset.h
0097 :identifiers:
0098
0099 .. Links
0100 .. _tools/testing/selftests/landlock/:
0101 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/
