From 75c542d6c6cc48720376862d5496d51509160dfd Mon Sep 17 00:00:00 2001 From: Mickaël Salaün Date: Fri, 6 May 2022 18:10:52 +0200 Subject: landlock: Reduce the maximum number of layers to 16 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The maximum number of nested Landlock domains is currently 64. Because of the following fix and to help reduce the stack size, let's reduce it to 16. This seems large enough for a lot of use cases (e.g. sandboxed init service, spawning a sandboxed SSH service, in nested sandboxed containers). Reducing the number of nested domains may also help to discover misuse of Landlock (e.g. creating a domain per rule). Add and use a dedicated layer_mask_t typedef to fit with the number of layers. This might be useful when changing it and to keep it consistent with the maximum number of layers. Reviewed-by: Paul Moore Link: https://lore.kernel.org/r/20220506161102.525323-3-mic@digikod.net Cc: stable@vger.kernel.org Signed-off-by: Mickaël Salaün --- Documentation/userspace-api/landlock.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index f35552ff19ba..b68e7a51009f 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -267,8 +267,8 @@ restrict such paths with dedicated ruleset flags. Ruleset layers -------------- -There is a limit of 64 layers of stacked rulesets. This can be an issue for a -task willing to enforce a new ruleset in complement to its 64 inherited +There is a limit of 16 layers of stacked rulesets. This can be an issue for a +task willing to enforce a new ruleset in complement to its 16 inherited rulesets. Once this limit is reached, sys_landlock_restrict_self() returns E2BIG. It is then strongly suggested to carefully build rulesets once in the life of a thread, especially for applications able to launch other applications -- cgit v1.2.3 From 6f59abfae35fbbe688ff790ff9638576956d760c Mon Sep 17 00:00:00 2001 From: Mickaël Salaün Date: Fri, 6 May 2022 18:11:00 +0200 Subject: landlock: Document LANDLOCK_ACCESS_FS_REFER and ABI versioning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add LANDLOCK_ACCESS_FS_REFER in the example and properly check to only use it if the current kernel support it thanks to the Landlock ABI version. Move the file renaming and linking limitation to a new "Previous limitations" section. Improve documentation about the backward and forward compatibility, including the rational for ruleset's handled_access_fs. Update the document date. Reviewed-by: Paul Moore Signed-off-by: Mickaël Salaün Link: https://lore.kernel.org/r/20220506161102.525323-11-mic@digikod.net --- Documentation/userspace-api/landlock.rst | 126 ++++++++++++++++++++++++++----- 1 file changed, 106 insertions(+), 20 deletions(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index b68e7a51009f..ae2aea986aa6 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -8,7 +8,7 @@ Landlock: unprivileged access control ===================================== :Author: Mickaël Salaün -:Date: March 2021 +:Date: May 2022 The goal of Landlock is to enable to restrict ambient rights (e.g. global filesystem access) for a set of processes. Because Landlock is a stackable @@ -29,14 +29,15 @@ the thread enforcing it, and its future children. Defining and enforcing a security policy ---------------------------------------- -We first need to create the ruleset that will contain our rules. For this +We first need to define the ruleset that will contain our rules. For this example, the ruleset will contain rules that only allow read actions, but write actions will be denied. The ruleset then needs to handle both of these kind of -actions. +actions. This is required for backward and forward compatibility (i.e. the +kernel and user space may not know each other's supported restrictions), hence +the need to be explicit about the denied-by-default access rights. .. code-block:: c - int ruleset_fd; struct landlock_ruleset_attr ruleset_attr = { .handled_access_fs = LANDLOCK_ACCESS_FS_EXECUTE | @@ -51,9 +52,34 @@ actions. LANDLOCK_ACCESS_FS_MAKE_SOCK | LANDLOCK_ACCESS_FS_MAKE_FIFO | LANDLOCK_ACCESS_FS_MAKE_BLOCK | - LANDLOCK_ACCESS_FS_MAKE_SYM, + LANDLOCK_ACCESS_FS_MAKE_SYM | + LANDLOCK_ACCESS_FS_REFER, }; +Because we may not know on which kernel version an application will be +executed, it is safer to follow a best-effort security approach. Indeed, we +should try to protect users as much as possible whatever the kernel they are +using. To avoid binary enforcement (i.e. either all security features or +none), we can leverage a dedicated Landlock command to get the current version +of the Landlock ABI and adapt the handled accesses. Let's check if we should +remove the `LANDLOCK_ACCESS_FS_REFER` access right which is only supported +starting with the second version of the ABI. + +.. code-block:: c + + int abi; + + abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); + if (abi < 2) { + ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_REFER; + } + +This enables to create an inclusive ruleset that will contain our rules. + +.. code-block:: c + + int ruleset_fd; + ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0); if (ruleset_fd < 0) { perror("Failed to create a ruleset"); @@ -92,6 +118,11 @@ descriptor. return 1; } +It may also be required to create rules following the same logic as explained +for the ruleset creation, by filtering access rights according to the Landlock +ABI version. In this example, this is not required because +`LANDLOCK_ACCESS_FS_REFER` is not allowed by any rule. + We now have a ruleset with one rule allowing read access to ``/usr`` while denying all other handled accesses for the filesystem. The next step is to restrict the current thread from gaining more privileges (e.g. thanks to a SUID @@ -192,6 +223,56 @@ To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target process, a sandboxed process should have a subset of the target process rules, which means the tracee must be in a sub-domain of the tracer. +Compatibility +============= + +Backward and forward compatibility +---------------------------------- + +Landlock is designed to be compatible with past and future versions of the +kernel. This is achieved thanks to the system call attributes and the +associated bitflags, particularly the ruleset's `handled_access_fs`. Making +handled access right explicit enables the kernel and user space to have a clear +contract with each other. This is required to make sure sandboxing will not +get stricter with a system update, which could break applications. + +Developers can subscribe to the `Landlock mailing list +`_ to knowingly update and +test their applications with the latest available features. In the interest of +users, and because they may use different kernel versions, it is strongly +encouraged to follow a best-effort security approach by checking the Landlock +ABI version at runtime and only enforcing the supported features. + +Landlock ABI versions +--------------------- + +The Landlock ABI version can be read with the sys_landlock_create_ruleset() +system call: + +.. code-block:: c + + int abi; + + abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); + if (abi < 0) { + switch (errno) { + case ENOSYS: + printf("Landlock is not supported by the current kernel.\n"); + break; + case EOPNOTSUPP: + printf("Landlock is currently disabled.\n"); + break; + } + return 0; + } + if (abi >= 2) { + printf("Landlock supports LANDLOCK_ACCESS_FS_REFER.\n"); + } + +The following kernel interfaces are implicitly supported by the first ABI +version. Features only supported from a specific version are explicitly marked +as such. + Kernel interface ================ @@ -228,21 +309,6 @@ Enforcing a ruleset Current limitations =================== -File renaming and linking -------------------------- - -Because Landlock targets unprivileged access controls, it is needed to properly -handle composition of rules. Such property also implies rules nesting. -Properly handling multiple layers of ruleset, each one of them able to restrict -access to files, also implies to inherit the ruleset restrictions from a parent -to its hierarchy. Because files are identified and restricted by their -hierarchy, moving or linking a file from one directory to another implies to -propagate the hierarchy constraints. To protect against privilege escalations -through renaming or linking, and for the sake of simplicity, Landlock currently -limits linking and renaming to the same directory. Future Landlock evolutions -will enable more flexibility for renaming and linking, with dedicated ruleset -flags. - Filesystem topology modification -------------------------------- @@ -281,6 +347,26 @@ Memory usage Kernel memory allocated to create rulesets is accounted and can be restricted by the Documentation/admin-guide/cgroup-v1/memory.rst. +Previous limitations +==================== + +File renaming and linking (ABI 1) +--------------------------------- + +Because Landlock targets unprivileged access controls, it needs to properly +handle composition of rules. Such property also implies rules nesting. +Properly handling multiple layers of rulesets, each one of them able to +restrict access to files, also implies inheritance of the ruleset restrictions +from a parent to its hierarchy. Because files are identified and restricted by +their hierarchy, moving or linking a file from one directory to another implies +propagation of the hierarchy constraints, or restriction of these actions +according to the potentially lost constraints. To protect against privilege +escalations through renaming or linking, and for the sake of simplicity, +Landlock previously limited linking and renaming to the same directory. +Starting with the Landlock ABI version 2, it is now possible to securely +control renaming and linking thanks to the new `LANDLOCK_ACCESS_FS_REFER` +access right. + Questions and answers ===================== -- cgit v1.2.3 From 09340cf4135f942d56742b36aaa3c37738aba000 Mon Sep 17 00:00:00 2001 From: Mickaël Salaün Date: Fri, 6 May 2022 18:11:01 +0200 Subject: landlock: Document good practices about filesystem policies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Explain how to set access rights per hierarchy in an efficient and safe way, especially with the LANDLOCK_ACCESS_FS_REFER side effect (i.e. partial ordering and constraints for access rights per hierarchy). Reviewed-by: Paul Moore Signed-off-by: Mickaël Salaün Link: https://lore.kernel.org/r/20220506161102.525323-12-mic@digikod.net --- Documentation/userspace-api/landlock.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index ae2aea986aa6..7b4fe6218132 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -156,6 +156,27 @@ ruleset. Full working code can be found in `samples/landlock/sandboxer.c`_. +Good practices +-------------- + +It is recommended setting access rights to file hierarchy leaves as much as +possible. For instance, it is better to be able to have ``~/doc/`` as a +read-only hierarchy and ``~/tmp/`` as a read-write hierarchy, compared to +``~/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy. +Following this good practice leads to self-sufficient hierarchies that don't +depend on their location (i.e. parent directories). This is particularly +relevant when we want to allow linking or renaming. Indeed, having consistent +access rights per directory enables to change the location of such directory +without relying on the destination directory access rights (except those that +are required for this operation, see `LANDLOCK_ACCESS_FS_REFER` documentation). +Having self-sufficient hierarchies also helps to tighten the required access +rights to the minimal set of data. This also helps avoid sinkhole directories, +i.e. directories where data can be linked to but not linked from. However, +this depends on data organization, which might not be controlled by developers. +In this case, granting read-write access to ``~/tmp/``, instead of write-only +access, would potentially allow to move ``~/tmp/`` to a non-readable directory +and still keep the ability to list the content of ``~/tmp/``. + Layers of file path access rights --------------------------------- -- cgit v1.2.3 From 5e469829baa1b1320e843adf3631edef1d6d2cf2 Mon Sep 17 00:00:00 2001 From: Mickaël Salaün Date: Fri, 13 May 2022 13:27:43 +0200 Subject: landlock: Explain how to support Landlock MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Let's help users by documenting how to enable and check for Landlock in the kernel and the running system. The userspace-api section may not be the best place for this but it still makes sense to put all the user documentation at the same place. Signed-off-by: Mickaël Salaün Link: https://lore.kernel.org/r/20220513112743.156414-1-mic@digikod.net Reviewed-by: Paul Moore --- Documentation/userspace-api/landlock.rst | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index 7b4fe6218132..b8ea59493964 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 .. Copyright © 2017-2020 Mickaël Salaün .. Copyright © 2019-2020 ANSSI -.. Copyright © 2021 Microsoft Corporation +.. Copyright © 2021-2022 Microsoft Corporation ===================================== Landlock: unprivileged access control @@ -18,6 +18,13 @@ is expected to help mitigate the security impact of bugs or unexpected/malicious behaviors in user space applications. Landlock empowers any process, including unprivileged ones, to securely restrict themselves. +We can quickly make sure that Landlock is enabled in the running system by +looking for "landlock: Up and running" in kernel logs (as root): ``dmesg | grep +landlock || journalctl -kg landlock`` . Developers can also easily check for +Landlock support with a :ref:`related system call `. If +Landlock is not currently supported, we need to :ref:`configure the kernel +appropriately `. + Landlock rules ============== @@ -264,6 +271,8 @@ users, and because they may use different kernel versions, it is strongly encouraged to follow a best-effort security approach by checking the Landlock ABI version at runtime and only enforcing the supported features. +.. _landlock_abi_versions: + Landlock ABI versions --------------------- @@ -388,6 +397,24 @@ Starting with the Landlock ABI version 2, it is now possible to securely control renaming and linking thanks to the new `LANDLOCK_ACCESS_FS_REFER` access right. +.. _kernel_support: + +Kernel support +============== + +Landlock was first introduced in Linux 5.13 but it must be configured at build +time with `CONFIG_SECURITY_LANDLOCK=y`. Landlock must also be enabled at boot +time as the other security modules. The list of security modules enabled by +default is set with `CONFIG_LSM`. The kernel configuration should then +contains `CONFIG_LSM=landlock,[...]` with `[...]` as the list of other +potentially useful security modules for the running system (see the +`CONFIG_LSM` help). + +If the running kernel doesn't have `landlock` in `CONFIG_LSM`, then we can +still enable it by adding ``lsm=landlock,[...]`` to +Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader +configuration. + Questions and answers ===================== -- cgit v1.2.3