From 39508405f6e6c8ce8a0f4bf93b344610d9051043 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=BCnther=20Noack?= Date: Thu, 27 Nov 2025 12:51:36 +0100 Subject: landlock: Document LANDLOCK_RESTRICT_SELF_TSYNC MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for LANDLOCK_RESTRICT_SELF_TSYNC. It does not need to go into the main example, but it has a section in the ABI compatibility notes. In the HTML rendering, the main reference is the system call documentation, which is included from the landlock.h header file. Cc: Andrew G. Morgan Cc: John Johansen Cc: Paul Moore Signed-off-by: Günther Noack Link: https://lore.kernel.org/r/20251127115136.3064948-4-gnoack@google.com [mic: Update date] Signed-off-by: Mickaël Salaün --- Documentation/userspace-api/landlock.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index 1d0c2c15c22e..90bb0778666d 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 2025 +:Date: November 2025 The goal of Landlock is to enable restriction of ambient rights (e.g. global filesystem or network access) for a set of processes. Because Landlock @@ -604,6 +604,14 @@ Landlock audit events with the ``LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF``, sys_landlock_restrict_self(). See Documentation/admin-guide/LSM/landlock.rst for more details on audit. +Thread synchronization (ABI < 8) +-------------------------------- + +Starting with the Landlock ABI version 8, it is now possible to +enforce Landlock rulesets across all threads of the calling process +using the ``LANDLOCK_RESTRICT_SELF_TSYNC`` flag passed to +sys_landlock_restrict_self(). + .. _kernel_support: Kernel support -- cgit v1.2.3 From 6100f2904e0ea1f2c832ab6e93573fae47d3b13e Mon Sep 17 00:00:00 2001 From: Samasth Norway Ananda Date: Tue, 27 Jan 2026 19:18:10 -0800 Subject: landlock: Add backwards compatibility for restrict flags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add backwards compatibility handling for the restrict flags introduced in ABI version 7. This is shown as a separate code block (similar to the ruleset_attr handling in the switch statement) because restrict flags are passed to landlock_restrict_self() rather than being part of the ruleset attributes. Also fix misleading description of the /usr rule which incorrectly stated it "only allow[s] reading" when the code actually allows both reading and executing (LANDLOCK_ACCESS_FS_EXECUTE is included in allowed_access). Signed-off-by: Samasth Norway Ananda Reviewed-by: Günther Noack Link: https://lore.kernel.org/r/20260128031814.2945394-2-samasth.norway.ananda@oracle.com [mic: Rebased and fixed conflict] Signed-off-by: Mickaël Salaün --- Documentation/userspace-api/landlock.rst | 32 +++++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 9 deletions(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index 90bb0778666d..2c1af0c930d4 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: November 2025 +:Date: January 2026 The goal of Landlock is to enable restriction of ambient rights (e.g. global filesystem or network access) for a set of processes. Because Landlock @@ -142,11 +142,11 @@ This enables the creation of an inclusive ruleset that will contain our rules. } We can now add a new rule to this ruleset thanks to the returned file -descriptor referring to this ruleset. The rule will only allow reading the -file hierarchy ``/usr``. Without another rule, write actions would then be -denied by the ruleset. To add ``/usr`` to the ruleset, we open it with the -``O_PATH`` flag and fill the &struct landlock_path_beneath_attr with this file -descriptor. +descriptor referring to this ruleset. The rule will allow reading and +executing the file hierarchy ``/usr``. Without another rule, write actions +would then be denied by the ruleset. To add ``/usr`` to the ruleset, we open +it with the ``O_PATH`` flag and fill the &struct landlock_path_beneath_attr with +this file descriptor. .. code-block:: c @@ -191,10 +191,24 @@ number for a specific action: HTTPS connections. err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_NET_PORT, &net_port, 0); +When passing a non-zero ``flags`` argument to ``landlock_restrict_self()``, a +similar backwards compatibility check is needed for the restrict flags +(see sys_landlock_restrict_self() documentation for available flags): + +.. code-block:: c + + __u32 restrict_flags = LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON; + if (abi < 7) { + /* Clear logging flags unsupported before ABI 7. */ + restrict_flags &= ~(LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF | + LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON | + LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF); + } + The next step is to restrict the current thread from gaining more privileges (e.g. through a SUID binary). We now have a ruleset with the first rule -allowing read access to ``/usr`` while denying all other handled accesses for -the filesystem, and a second rule allowing HTTPS connections. +allowing read and execute access to ``/usr`` while denying all other handled +accesses for the filesystem, and a second rule allowing HTTPS connections. .. code-block:: c @@ -208,7 +222,7 @@ The current thread is now ready to sandbox itself with the ruleset. .. code-block:: c - if (landlock_restrict_self(ruleset_fd, 0)) { + if (landlock_restrict_self(ruleset_fd, restrict_flags)) { perror("Failed to enforce ruleset"); close(ruleset_fd); return 1; -- cgit v1.2.3 From fe72ce6710cba088b67e3279de87d7341fafc357 Mon Sep 17 00:00:00 2001 From: Samasth Norway Ananda Date: Tue, 27 Jan 2026 19:18:11 -0800 Subject: landlock: Add errata documentation section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add errata section with code examples for querying errata and a warning that most applications should not check errata. Use kernel-doc directives to include errata descriptions from the header files instead of manual links. Also enhance existing DOC sections in security/landlock/errata/abi-*.h files with Impact sections, and update the code comment in syscalls.c to remind developers to update errata documentation when applicable. This addresses the gap where the kernel implements errata tracking but provides no user-facing documentation on how to use it, while improving the existing technical documentation in-place rather than duplicating it. Signed-off-by: Samasth Norway Ananda Reviewed-by: Günther Noack Link: https://lore.kernel.org/r/20260128031814.2945394-3-samasth.norway.ananda@oracle.com [mic: Cosmetic fix] Signed-off-by: Mickaël Salaün --- Documentation/userspace-api/landlock.rst | 65 ++++++++++++++++++++++++++++++-- 1 file changed, 62 insertions(+), 3 deletions(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index 2c1af0c930d4..13134bccdd39 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -445,9 +445,68 @@ system call: 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. +All Landlock kernel interfaces are supported by the first ABI version unless +explicitly noted in their documentation. + +Landlock errata +--------------- + +In addition to ABI versions, Landlock provides an errata mechanism to track +fixes for issues that may affect backwards compatibility or require userspace +awareness. The errata bitmask can be queried using: + +.. code-block:: c + + int errata; + + errata = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_ERRATA); + if (errata < 0) { + /* Landlock not available or disabled */ + return 0; + } + +The returned value is a bitmask where each bit represents a specific erratum. +If bit N is set (``errata & (1 << (N - 1))``), then erratum N has been fixed +in the running kernel. + +.. warning:: + + **Most applications should NOT check errata.** In 99.9% of cases, checking + errata is unnecessary, increases code complexity, and can potentially + decrease protection if misused. For example, disabling the sandbox when an + erratum is not fixed could leave the system less secure than using + Landlock's best-effort protection. When in doubt, ignore errata. + +.. kernel-doc:: security/landlock/errata/abi-4.h + :doc: erratum_1 + +.. kernel-doc:: security/landlock/errata/abi-6.h + :doc: erratum_2 + +.. kernel-doc:: security/landlock/errata/abi-1.h + :doc: erratum_3 + +How to check for errata +~~~~~~~~~~~~~~~~~~~~~~~ + +If you determine that your application needs to check for specific errata, +use this pattern: + +.. code-block:: c + + int errata = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_ERRATA); + if (errata >= 0) { + /* Check for specific erratum (1-indexed) */ + if (errata & (1 << (erratum_number - 1))) { + /* Erratum N is fixed in this kernel */ + } else { + /* Erratum N is NOT fixed - consider implications for your use case */ + } + } + +**Important:** Only check errata if your application specifically relies on +behavior that changed due to the fix. The fixes generally make Landlock less +restrictive or more correct, not more restrictive. Kernel interface ================ -- cgit v1.2.3