Documentation/security/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 ==================================
   6 Landlock LSM: kernel documentation
   7 ==================================
   8
   9 :Author: Mickaël Salaün
  10 :Date: September 2022
  11
  12 Landlock's goal is to create scoped access-control (i.e. sandboxing).  To
  13 harden a whole system, this feature should be available to any process,
  14 including unprivileged ones.  Because such process may be compromised or
  15 backdoored (i.e. untrusted), Landlock's features must be safe to use from the
  16 kernel and other processes point of view.  Landlock's interface must therefore
  17 expose a minimal attack surface.
  18
  19 Landlock is designed to be usable by unprivileged processes while following the
  20 system security policy enforced by other access control mechanisms (e.g. DAC,
  21 LSM).  Indeed, a Landlock rule shall not interfere with other access-controls
  22 enforced on the system, only add more restrictions.
  23
  24 Any user can enforce Landlock rulesets on their processes.  They are merged and
  25 evaluated according to the inherited ones in a way that ensures that only more
  26 constraints can be added.
  27
  28 User space documentation can be found here:
  29 Documentation/userspace-api/landlock.rst.
  30
  31 Guiding 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
  45 Design choices
  46 ==============
  47
  48 Filesystem access rights
  49 ------------------------
  50
  51 All access rights are tied to an inode and what can be accessed through it.
  52 Reading the content of a directory does not imply to be allowed to read the
  53 content of a listed inode.  Indeed, a file name is local to its parent
  54 directory, and an inode can be referenced by multiple file names thanks to
  55 (hard) links.  Being able to unlink a file only has a direct impact on the
  56 directory, not the unlinked inode.  This is the reason why
  57 ``LANDLOCK_ACCESS_FS_REMOVE_FILE`` or ``LANDLOCK_ACCESS_FS_REFER`` are not
  58 allowed to be tied to files but only to directories.
  59
  60 Tests
  61 =====
  62
  63 Userspace tests for backward compatibility, ptrace restrictions and filesystem
  64 support can be found here: `tools/testing/selftests/landlock/`_.
  65
  66 Kernel structures
  67 =================
  68
  69 Object
  70 ------
  71
  72 .. kernel-doc:: security/landlock/object.h
  73     :identifiers:
  74
  75 Filesystem
  76 ----------
  77
  78 .. kernel-doc:: security/landlock/fs.h
  79     :identifiers:
  80
  81 Ruleset and domain
  82 ------------------
  83
  84 A domain is a read-only ruleset tied to a set of subjects (i.e. tasks'
  85 credentials).  Each time a ruleset is enforced on a task, the current domain is
  86 duplicated and the ruleset is imported as a new layer of rules in the new
  87 domain.  Indeed, once in a domain, each rule is tied to a layer level.  To
  88 grant access to an object, at least one rule of each layer must allow the
  89 requested action on the object.  A task can then only transit to a new domain
  90 that is the intersection of the constraints from the current domain and those
  91 of a ruleset provided by the task.
  92
  93 The definition of a subject is implicit for a task sandboxing itself, which
  94 makes the reasoning much easier and helps avoid pitfalls.
  95
  96 .. kernel-doc:: security/landlock/ruleset.h
  97     :identifiers:
  98
  99 .. Links
 100 .. _tools/testing/selftests/landlock/:
 101    https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/testing/selftests/landlock/