Message-ID: <20251226.ahpooghah4Ph@digikod.net>
Date: Fri, 26 Dec 2025 19:53:27 +0100
From: Mickaël Salaün <mic@...ikod.net>
To: Günther Noack <gnoack3000@...il.com>
Cc: Samasth Norway Ananda <samasth.norway.ananda@...cle.com>, 
	gnoack@...gle.com, linux-security-module@...r.kernel.org, 
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH 2/3] landlock: Document Landlock errata mechanism

On Wed, Dec 24, 2025 at 12:08:39AM +0100, Günther Noack wrote:
> 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?

Yes please, if the current abi-*.h doc is not enough, please extend it.

> 
> 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 */
> > +    }

This "How to check" subsection should be common to all errata.

> > +
> > +**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).

This is correct but it should only be useful to a few programs.  We need
to be careful to avoid making developers feel that they should check
errata, whereas in 99.9% of cases it is not required, it increases
complexity, and potentially decrease protection if misused (e.g. if
erratum is not applied, a program could erroneously disable the sandbox
or some restrictions).  I think we should have a warning note to
highlight that (i.e. in doubt, ignore errata).

> > +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.

It's not related to the best-effort approach.

> > +
> 
> 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.

I like it too.  We should leverage the comments to avoid duplicating doc
though.

> 
> Thanks!
> –Günther
> 

Powered by blists - more mailing lists