[PATCH 1/3] landlock: Add missing ABI 7 case in documentation example

[PATCH 1/3] landlock: Add missing ABI 7 case in documentation example

[Samasth Norway Ananda]

Add the missing case 6 and case 7 handling in the ABI version
compatibility example to properly handle LANDLOCK_RESTRICT_SELF_LOG_*
flags for kernels with ABI < 7.

This introduces the supported_restrict_flags variable which is
initialized with LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON, removed
in case 6 for ABI < 7, and passed to landlock_restrict_self() to
enable logging on supported kernels.

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 <samasth.norway.ananda@oracle.com>
---
 Documentation/userspace-api/landlock.rst | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index 1d0c2c15c22e..b8caac299056 100644
--- a/Documentation/userspace-api/landlock.rst
+++ b/Documentation/userspace-api/landlock.rst
@@ -97,6 +97,8 @@ version, and only use the available subset of access rights:
 .. code-block:: c
 
     int abi;
+    /* Tracks which landlock_restrict_self() flags are supported */
+    int supported_restrict_flags = LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON;
 
     abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION);
     if (abi < 0) {
@@ -127,6 +129,17 @@ version, and only use the available subset of access rights:
         /* Removes LANDLOCK_SCOPE_* for ABI < 6 */
         ruleset_attr.scoped &= ~(LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET |
                                  LANDLOCK_SCOPE_SIGNAL);
+        __attribute__((fallthrough));
+    case 6:
+        /*
+         * Removes LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON for ABI < 7.
+         * Note: This modifies supported_restrict_flags, not ruleset_attr,
+         * because logging flags are passed to landlock_restrict_self().
+         */
+        supported_restrict_flags &= ~LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON;
+        __attribute__((fallthrough));
+    case 7:
+        break;
     }
 
 This enables the creation of an inclusive ruleset that will contain our rules.
@@ -142,8 +155,9 @@ 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
+descriptor referring to this ruleset.  The rule will allow reading and
+executing files in the ``/usr`` hierarchy.  Without another rule, write actions
+and other operations (make_dir, remove_file, etc.) 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.
@@ -193,7 +207,7 @@ number for a specific action: HTTPS connections.
 
 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
+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, supported_restrict_flags)) {
         perror("Failed to enforce ruleset");
         close(ruleset_fd);
         return 1;
-- 
2.50.1

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

[Samasth Norway Ananda]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 5927 bytes --]

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.

Signed-off-by: Samasth Norway Ananda <samasth.norway.ananda@oracle.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
+~~~~~~~~~~~~
+
+**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)`.
+
+*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.
+
 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

[PATCH 3/3] landlock: Document audit blocker field format

[Samasth Norway Ananda]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 3175 bytes --]

Add comprehensive documentation for the ``blockers`` field format
in AUDIT_LANDLOCK_ACCESS records, including all possible prefixes
(fs., net., scope.) and their meanings.

Also fix a typo and update the documentation date to reflect these
changes.

Signed-off-by: Samasth Norway Ananda <samasth.norway.ananda@oracle.com>
---
 Documentation/admin-guide/LSM/landlock.rst | 34 ++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/Documentation/admin-guide/LSM/landlock.rst b/Documentation/admin-guide/LSM/landlock.rst
index 9e61607def08..f1ea67cff9da 100644
--- a/Documentation/admin-guide/LSM/landlock.rst
+++ b/Documentation/admin-guide/LSM/landlock.rst
@@ -6,7 +6,7 @@ Landlock: system-wide management
 ================================
 
 :Author: Mickaël Salaün
-:Date: March 2025
+:Date: December 2025
 
 Landlock can leverage the audit framework to log events.
 
@@ -38,6 +38,36 @@ AUDIT_LANDLOCK_ACCESS
         domain=195ba459b blockers=fs.refer path="/usr/bin" dev="vda2" ino=351
         domain=195ba459b blockers=fs.make_reg,fs.refer path="/usr/local" dev="vda2" ino=365
 
+    The ``blockers`` field uses dot-separated prefixes to indicate the type of
+    restriction that caused the denial:
+
+    **fs.*** - Filesystem access rights (ABI 1+):
+        - fs.execute, fs.write_file, fs.read_file, fs.read_dir
+        - fs.remove_dir, fs.remove_file
+        - fs.make_char, fs.make_dir, fs.make_reg, fs.make_sock
+        - fs.make_fifo, fs.make_block, fs.make_sym
+        - fs.refer (ABI 2+)
+        - fs.truncate (ABI 3+)
+        - fs.ioctl_dev (ABI 5+)
+
+    **net.*** - Network access rights (ABI 4+):
+        - net.bind_tcp - TCP port binding was denied
+        - net.connect_tcp - TCP connection was denied
+
+    **scope.*** - IPC scoping restrictions (ABI 6+):
+        - scope.abstract_unix_socket - Abstract UNIX socket connection denied
+        - scope.signal - Signal sending denied
+
+    Multiple blockers can appear in a single event (comma-separated) when
+    multiple access rights are missing. For example, creating a regular file
+    in a directory that lacks both ``make_reg`` and ``refer`` rights would show
+    ``blockers=fs.make_reg,fs.refer``.
+
+    The object identification fields (path, dev, ino for filesystem; opid,
+    ocomm for signals) depend on the type of access being blocked and provide
+    context about what resource was involved in the denial.
+
+
 AUDIT_LANDLOCK_DOMAIN
     This record type describes the status of a Landlock domain.  The ``status``
     field can be either ``allocated`` or ``deallocated``.
@@ -86,7 +116,7 @@ This command generates two events, each identified with a unique serial
 number following a timestamp (``msg=audit(1729738800.268:30)``).  The first
 event (serial ``30``) contains 4 records.  The first record
 (``type=LANDLOCK_ACCESS``) shows an access denied by the domain `1a6fdc66f`.
-The cause of this denial is signal scopping restriction
+The cause of this denial is signal scoping restriction
 (``blockers=scope.signal``).  The process that would have receive this signal
 is the init process (``opid=1 ocomm="systemd"``).
 
-- 
2.50.1

Re: [PATCH 1/3] landlock: Add missing ABI 7 case in documentation example

[Günther Noack]

Hello!

On Tue, Dec 16, 2025 at 01:02:42PM -0800, Samasth Norway Ananda wrote:
> Add the missing case 6 and case 7 handling in the ABI version
> compatibility example to properly handle LANDLOCK_RESTRICT_SELF_LOG_*
> flags for kernels with ABI < 7.
> 
> This introduces the supported_restrict_flags variable which is
> initialized with LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON, removed
> in case 6 for ABI < 7, and passed to landlock_restrict_self() to
> enable logging on supported kernels.
> 
> 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 <samasth.norway.ananda@oracle.com>

Thank you for sending a patch, much appreciated!

You are right to point this out - the logging aspect is a bit hard to
spot when reading the current documentation starting from the code
example.


> ---
>  Documentation/userspace-api/landlock.rst | 22 ++++++++++++++++++----
>  1 file changed, 18 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index 1d0c2c15c22e..b8caac299056 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -97,6 +97,8 @@ version, and only use the available subset of access rights:
>  .. code-block:: c
>  
>      int abi;
> +    /* Tracks which landlock_restrict_self() flags are supported */
> +    int supported_restrict_flags = LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON;

This might be confusing, as there are actually more supported flags:
ABI v7 does not only introduce LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON,
but also LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF and
LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF.

I am unconvinced whether it is a good idea to set these flags in the
first example that we have in the documentation, especially if we
don't discuss what these flags do there.  If we suggest the wrong
default flags in the example, people might use them in their
production code without realizing what they do.  The way that the
logging flags are designed, the assumption was that most users should
be able to pass 0 as flags to landlock_restrict_self() and still get
the relevant parts of the audit logging.

But you are right that an implementation that *does pass* logging
flags will want check the ABI and not pass them on older kernels.

To throw in a constructive suggestion: we could also have "backwards
compatibility for restrict flags" section between the existing case
analysis and the landlock_restrict_self() call?  It could then say
something like

    When passing a non-zero `flags` argument to
    landlock_restrict_self(), the following backwards compatibility
    check needs to be taken into account:

      /*
       * Desired restriction flags, see section suchandsuch.
       * This value is only an example and differs by use case.
       */
      int restrict_flags = LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON;
      if (abi < 7) {
        /* clear the necessary bits */
        restrict_flags &= ~...;
      }

Readers who do not need to pass any flags could then skip over that
section (I assume these are most readers).  The readers who *do* want
to pass flags could merge that logic into the bigger case analysis
themselves, but for the sake of explaining it we would not mix up that
explanation with the access right discussion that much.

WDYT?

>      abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION);
>      if (abi < 0) {
> @@ -127,6 +129,17 @@ version, and only use the available subset of access rights:
>          /* Removes LANDLOCK_SCOPE_* for ABI < 6 */
>          ruleset_attr.scoped &= ~(LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET |
>                                   LANDLOCK_SCOPE_SIGNAL);
> +        __attribute__((fallthrough));
> +    case 6:
> +        /*
> +         * Removes LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON for ABI < 7.
> +         * Note: This modifies supported_restrict_flags, not ruleset_attr,
> +         * because logging flags are passed to landlock_restrict_self().
> +         */
> +        supported_restrict_flags &= ~LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON;

If this should be a generic example, we would have to clear the other
two flags here as well.

> +        __attribute__((fallthrough));
> +    case 7:
> +        break;
>      }

Thanks,
–Günther

Re: [External] : Re: [PATCH 1/3] landlock: Add missing ABI 7 case in documentation example

[samasth.norway.ananda]

On 12/23/25 2:22 PM, Günther Noack wrote:
> Hello!
> 
> On Tue, Dec 16, 2025 at 01:02:42PM -0800, Samasth Norway Ananda wrote:
>> Add the missing case 6 and case 7 handling in the ABI version
>> compatibility example to properly handle LANDLOCK_RESTRICT_SELF_LOG_*
>> flags for kernels with ABI < 7.
>>
>> This introduces the supported_restrict_flags variable which is
>> initialized with LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON, removed
>> in case 6 for ABI < 7, and passed to landlock_restrict_self() to
>> enable logging on supported kernels.
>>
>> 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 <samasth.norway.ananda@oracle.com>
> 
> Thank you for sending a patch, much appreciated!
> 
> You are right to point this out - the logging aspect is a bit hard to
> spot when reading the current documentation starting from the code
> example.
> 
> 
>> ---
>>   Documentation/userspace-api/landlock.rst | 22 ++++++++++++++++++----
>>   1 file changed, 18 insertions(+), 4 deletions(-)
>>
>> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
>> index 1d0c2c15c22e..b8caac299056 100644
>> --- a/Documentation/userspace-api/landlock.rst
>> +++ b/Documentation/userspace-api/landlock.rst
>> @@ -97,6 +97,8 @@ version, and only use the available subset of access rights:
>>   .. code-block:: c
>>   
>>       int abi;
>> +    /* Tracks which landlock_restrict_self() flags are supported */
>> +    int supported_restrict_flags = LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON;
> 
> This might be confusing, as there are actually more supported flags:
> ABI v7 does not only introduce LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON,
> but also LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF and
> LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF.
> 
> I am unconvinced whether it is a good idea to set these flags in the
> first example that we have in the documentation, especially if we
> don't discuss what these flags do there.  If we suggest the wrong
> default flags in the example, people might use them in their
> production code without realizing what they do.  The way that the
> logging flags are designed, the assumption was that most users should
> be able to pass 0 as flags to landlock_restrict_self() and still get
> the relevant parts of the audit logging.
> 
> But you are right that an implementation that *does pass* logging
> flags will want check the ABI and not pass them on older kernels.
> 
> To throw in a constructive suggestion: we could also have "backwards
> compatibility for restrict flags" section between the existing case
> analysis and the landlock_restrict_self() call?  It could then say
> something like
> 
>      When passing a non-zero `flags` argument to
>      landlock_restrict_self(), the following backwards compatibility
>      check needs to be taken into account:
> 
>        /*
>         * Desired restriction flags, see section suchandsuch.
>         * This value is only an example and differs by use case.
>         */
>        int restrict_flags = LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON;
>        if (abi < 7) {
>          /* clear the necessary bits */
>          restrict_flags &= ~...;
>        }
> 
> Readers who do not need to pass any flags could then skip over that
> section (I assume these are most readers).  The readers who *do* want
> to pass flags could merge that logic into the bigger case analysis
> themselves, but for the sake of explaining it we would not mix up that
> explanation with the access right discussion that much.
> 
> WDYT?

Ah got it. Thanks for pointing it out Günther.
I agree with your suggestion. I will update the documentation to follow 
that approach and send out a v2 soon

> 
>>       abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION);
>>       if (abi < 0) {
>> @@ -127,6 +129,17 @@ version, and only use the available subset of access rights:
>>           /* Removes LANDLOCK_SCOPE_* for ABI < 6 */
>>           ruleset_attr.scoped &= ~(LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET |
>>                                    LANDLOCK_SCOPE_SIGNAL);
>> +        __attribute__((fallthrough));
>> +    case 6:
>> +        /*
>> +         * Removes LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON for ABI < 7.
>> +         * Note: This modifies supported_restrict_flags, not ruleset_attr,
>> +         * because logging flags are passed to landlock_restrict_self().
>> +         */
>> +        supported_restrict_flags &= ~LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON;
> 
> If this should be a generic example, we would have to clear the other
> two flags here as well.

To avoid confusion. I'll follow the above approach you suggested and 
remove this part from the case section.

Thanks,
Samasth.

> 
>> +        __attribute__((fallthrough));
>> +    case 7:
>> +        break;
>>       }
> 
> Thanks,
> –Günther

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@oracle.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

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

[Mickaël Salaün]

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@oracle.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
>