Documentation/userspace-api/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 .. Copyright © 2021-2022 Microsoft Corporation
14 filesystem or network access) for a set of processes.  Because Landlock
16 new security layers in addition to the existing system-wide access-controls.
23 ``dmesg | grep landlock || journalctl -kb -g landlock`` .
33 perform.  A set of rules is aggregated in a ruleset, which can then restrict
48 ----------------------------------------
52 For this example, the ruleset will contain rules that only allow filesystem
59 to be explicit about the denied-by-default access rights.
61 .. code-block:: c
90 on, it is safer to follow a best-effort security approach.  Indeed, we
97 .. code-block:: c
134 .. code-block:: c
145 descriptor referring to this ruleset.  The rule will only allow reading the
151 .. code-block:: c
181 For network access-control, we can add a set of rules that allow to use a port
184 .. code-block:: c
199 .. code-block:: c
209 .. code-block:: c
228 --------------
230 It is recommended to set access rights to file hierarchy leaves as much as
232 read-only hierarchy and ``~/tmp/`` as a read-write hierarchy, compared to
233 ``~/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy.
234 Following this good practice leads to self-sufficient hierarchies that do not
236 relevant when we want to allow linking or renaming.  Indeed, having consistent
242 Having self-sufficient hierarchies also helps to tighten the required access
243 rights to the minimal set of data.  This also helps avoid sinkhole directories,
246 In this case, granting read-write access to ``~/tmp/``, instead of write-only
247 access, would potentially allow moving ``~/tmp/`` to a non-readable directory
251 ---------------------------------
253 Each time a thread enforces a ruleset on itself, it updates its Landlock domain
265 -------------------------
276 access to multiple file hierarchies at the same time, whether these hierarchies
284 and merge hierarchies are standalone and each contains their own set of files
287 Landlock users should then only think about file hierarchies they want to allow
291 -----------
295 Documentation/userspace-api/seccomp_filter.rst) or any other LSM dealing with
308 -------------------
310 A sandboxed process has less privileges than a non-sandboxed process and must
314 access rights, which means the tracee must be in a sub-domain of the tracer.
317 -----------
321 for a set of actions by specifying it on a ruleset.  For example, if a
323 non-sandboxed process through abstract :manpage:`unix(7)` sockets, we can
326 non-sandboxed process, we can specify this restriction with
329 A sandboxed process can connect to a non-sandboxed process when its domain is
332 Moreover, If a process is scoped to send signal to a non-scoped process, it can
338 scenario, a non-connected datagram socket cannot send data (with
341 A process with a scoped domain can inherit a socket created by a non-scoped
346 be added to allow access to resources or processes outside of the scope.
349 ----------------
353 overlap in non-intuitive ways.  It is recommended to always specify both of
369 ---------------------------------------
391 ----------------------------------
404 encouraged to follow a best-effort security approach by checking the Landlock
410 ---------------------
415 .. code-block:: c
443 -------------
445 .. kernel-doc:: include/uapi/linux/landlock.h
449 ----------------------
451 .. kernel-doc:: security/landlock/syscalls.c
454 .. kernel-doc:: include/uapi/linux/landlock.h
458 -------------------
460 .. kernel-doc:: security/landlock/syscalls.c
463 .. kernel-doc:: include/uapi/linux/landlock.h
468 -------------------
470 .. kernel-doc:: security/landlock/syscalls.c
477 --------------------------------
484 -------------------
488 come from a user-visible filesystem (e.g. pipe, socket), but can still be
498 --------------
509 ------------
512 by the Documentation/admin-guide/cgroup-v1/memory.rst.
515 -------------
519 means specifically that pre-existing file descriptors like stdin, stdout and
531 Landlock's IOCTL support is coarse-grained at the moment, but may become more
532 fine-grained in the future.  Until then, users are advised to establish the
540 -----------------------------------
557 -------------------------
566 ------------------------------
569 bind and connect actions to only a set of allowed ports thanks to the new
574 ----------------------
585 ------------------------------
592 ----------------
603 Build time configuration
604 ------------------------
607 time with ``CONFIG_SECURITY_LANDLOCK=y``.  Landlock must also be enabled at boot
608 time like other security modules.  The list of security modules enabled by
609 default is set with ``CONFIG_LSM``.  The kernel configuration should then
614 Boot time configuration
615 -----------------------
619 Documentation/admin-guide/kernel-parameters.rst in the boot loader
622 For example, if the current built-in configuration is:
624 .. code-block:: console
626     $ zgrep -h "^CONFIG_LSM=" "/boot/config-$(uname -r)" /proc/config.gz 2>/dev/null
631 .. code-block:: console
633     $ sed -n 's/.*\(\<lsm=\S\+\).*/\1/p' /proc/cmdline
636 ...we should configure the boot loader to set a cmdline extending the ``lsm``
644 .. code-block:: console
646     # dmesg | grep landlock || journalctl -kb -g landlock
652 The kernel may be configured at build time to always load the ``lockdown`` and
658 ---------------
660 To be able to explicitly allow TCP operations (e.g., adding a network rule with
670 ---------------------------------------
675 <https://www.ndss-symposium.org/ndss2003/traps-and-pitfalls-practical-problems-system-call-interpos…
678 -------------------------------------
681 access-control and then miss useful features for such use case (e.g. no
682 fine-grained restrictions).  Moreover, their complexity can lead to security