Re: [PATCH 2/3] landlock: Document Landlock errata mechanism

[Günther Noack]

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@xxxxxxxxxx>
> ---
>  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