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 2021
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 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).  Indeed, a Landlock rule shall not interfere with other access-controls
22enforced on the system, only add more restrictions.
23
24Any user can enforce Landlock rulesets on their processes.  They are merged and
25evaluated according to the inherited ones 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
45Tests
46=====
47
48Userspace tests for backward compatibility, ptrace restrictions and filesystem
49support can be found here: `tools/testing/selftests/landlock/`_.
50
51Kernel structures
52=================
53
54Object
55------
56
57.. kernel-doc:: security/landlock/object.h
58    :identifiers:
59
60Filesystem
61----------
62
63.. kernel-doc:: security/landlock/fs.h
64    :identifiers:
65
66Ruleset and domain
67------------------
68
69A domain is a read-only ruleset tied to a set of subjects (i.e. tasks'
70credentials).  Each time a ruleset is enforced on a task, the current domain is
71duplicated and the ruleset is imported as a new layer of rules in the new
72domain.  Indeed, once in a domain, each rule is tied to a layer level.  To
73grant access to an object, at least one rule of each layer must allow the
74requested action on the object.  A task can then only transit to a new domain
75that is the intersection of the constraints from the current domain and those
76of a ruleset provided by the task.
77
78The definition of a subject is implicit for a task sandboxing itself, which
79makes the reasoning much easier and helps avoid pitfalls.
80
81.. kernel-doc:: security/landlock/ruleset.h
82    :identifiers:
83
84.. Links
85.. _tools/testing/selftests/landlock/:
86   https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/
87