Message-ID: <20251223.4aaf05850b4c@gnoack.org>
Date: Wed, 24 Dec 2025 00:08:39 +0100
From: Günther Noack <gnoack3000@...il.com>
To: Samasth Norway Ananda <samasth.norway.ananda@...cle.com>
Cc: mic@...ikod.net, gnoack@...gle.com,
	linux-security-module@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH 2/3] landlock: Document Landlock errata mechanism

Hello!

On Tue, Dec 16, 2025 at 01:02:43PM -0800, Samasth Norway Ananda wrote:
> Add comprehensive documentation for the Landlock errata mechanism,
> including how to query errata using LANDLOCK_CREATE_RULESET_ERRATA
> and detailed descriptions of all three existing errata.
> 
> Also update the code comment in syscalls.c to remind developers to
> update errata documentation when applicable, and update the
> documentation date to reflect this new content.
> 
> This addresses the gap where the kernel implements errata tracking
> but provides no user-facing documentation on how to use it.

Thank you very much, this is absolutely right that this was missing
and overall, this is an excellent change!  I have only some nit-picks
and smaller questions below.

> 
> Signed-off-by: Samasth Norway Ananda <samasth.norway.ananda@...cle.com>
> ---
>  Documentation/userspace-api/landlock.rst | 99 +++++++++++++++++++++++-
>  security/landlock/syscalls.c             |  4 +-
>  2 files changed, 101 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index b8caac299056..d1f7dd30395d 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: December 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
> @@ -445,6 +445,103 @@ system call:
>          printf("Landlock supports LANDLOCK_ACCESS_FS_REFER.\n");
>      }
>  
> +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.
> +
> +Known Errata
> +~~~~~~~~~~~~

I see that the following sections are based on the descriptions in
security/landlock/errata/abi-*.h.  These header files have docstrings
with "DOC:" identifiers -- would it not be possible to improve that
documentation in-place and link that from the user documentation?

I like the structured approach with the "Impact" section.  This seems
useful for readers who want to evaluate whether they are affected.

> +
> +**Erratum 1: TCP socket identification (ABI 4)**
> +
> +Fixed an issue where IPv4 and IPv6 stream sockets (e.g., SMC, MPTCP, or SCTP)
> +were incorrectly restricted by TCP access rights during :manpage:`bind(2)` and
> +:manpage:`connect(2)` operations.
> +
> +*Impact:* In kernels without this fix, using ``LANDLOCK_ACCESS_NET_BIND_TCP``
> +or ``LANDLOCK_ACCESS_NET_CONNECT_TCP`` would incorrectly restrict non-TCP
> +stream protocols.
> +
> +*How to check:*
> +
> +.. code-block:: c
> +
> +    if (errata & (1 << 0)) {
> +        /* Erratum 1 is fixed - TCP restrictions only apply to TCP */
> +        /* Safe to use non-TCP stream protocols */
> +    }
> +
> +**Erratum 2: Scoped signal handling (ABI 6)**
> +
> +Fixed an issue where signal scoping (``LANDLOCK_SCOPE_SIGNAL``) was overly
> +restrictive, preventing sandboxed threads from signaling other threads within
> +the same process if they belonged to different Landlock domains.
> +
> +*Impact:* Without this fix, signal scoping could break multi-threaded
> +applications that expect threads within the same process to freely signal
> +each other, as documented in :manpage:`nptl(7)` and :manpage:`libpsx(3)`.

Maybe to help explain the impact: The problem only manifests when the
userspace process is itself using libpsx(3) or an equivalent mechanism
to enforce a Landlock policy on multiple (already running) threads at
once.  Programs which enforce a Landlock policy at startup time and
only then become multithreaded are not affected.

> +
> +*How to check:*
> +
> +.. code-block:: c
> +
> +    if (errata & (1 << 1)) {
> +        /* Erratum 2 is fixed - threads can signal within same process */
> +        /* Safe to use LANDLOCK_SCOPE_SIGNAL with multi-threaded apps */
> +    }
> +
> +**Erratum 3: Disconnected directory handling (ABI 1)**
> +
> +Fixed an issue with disconnected directories that occur when a directory is
> +moved outside the scope of a bind mount. The fix ensures that evaluated access
> +rights include both those from the disconnected file hierarchy down to its
> +filesystem root and those from the related mount point hierarchy.
> +
> +*Impact:* Without this fix, it was possible to widen access rights through
> +rename or link actions involving disconnected directories, potentially
> +bypassing ``LANDLOCK_ACCESS_FS_REFER`` restrictions.
> +
> +*How to check:*
> +
> +.. code-block:: c
> +
> +    if (errata & (1 << 2)) {
> +        /* Erratum 3 is fixed - disconnected directories handled correctly */
> +        /* LANDLOCK_ACCESS_FS_REFER restrictions cannot be bypassed */
> +    }
> +
> +When to Check Errata
> +
> +Applications should check for specific errata when:
> +
> +1. Using features that were relaxed or had their behavior changed (like
> +   erratum 2 with signal scoping in multi-threaded applications).
> +2. Relying on specific security guarantees that may not have been fully
> +   enforced in earlier implementations (like erratum 3 with refer restrictions).
> +3. Using network restrictions and need to ensure other protocols aren't
> +   incorrectly blocked (erratum 1).
> +
> +Most applications using Landlock's best-effort approach don't need to check
> +errata, as the fixes generally make Landlock less restrictive or more correct,
> +not more restrictive.
> +

This section looks good to me as well.

>  The following kernel interfaces are implicitly supported by the first ABI
>  version.  Features only supported from a specific version are explicitly marked
>  as such.
> diff --git a/security/landlock/syscalls.c b/security/landlock/syscalls.c
> index 0116e9f93ffe..cf5ba7715916 100644
> --- a/security/landlock/syscalls.c
> +++ b/security/landlock/syscalls.c
> @@ -157,9 +157,11 @@ static const struct file_operations ruleset_fops = {
>  /*
>   * The Landlock ABI version should be incremented for each new Landlock-related
>   * user space visible change (e.g. Landlock syscalls).  This version should
> - * only be incremented once per Linux release, and the date in
> + * only be incremented once per Linux release. When incrementing, the date in
>   * Documentation/userspace-api/landlock.rst should be updated to reflect the
>   * UAPI change.
> + * If the change involves a fix that requires userspace awareness, also update
> + * the errata documentation in Documentation/userspace-api/landlock.rst.
>   */
>  const int landlock_abi_version = 7;
>  
> -- 
> 2.50.1
> 

I think this is a very good change.  My main open question here is
whether we can link this with the header documentation instead of
duplicating the documentation in two places.

Thanks!
–Günther

Powered by blists - more mailing lists