Message-ID: <20251216210248.4150777-2-samasth.norway.ananda@oracle.com>
Date: Tue, 16 Dec 2025 13:02:43 -0800
From: Samasth Norway Ananda <samasth.norway.ananda@...cle.com>
To: mic@...ikod.net, gnoack@...gle.com
Cc: linux-security-module@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: [PATCH 2/3] landlock: Document Landlock errata mechanism

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@...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
+~~~~~~~~~~~~
+
+**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

Powered by blists - more mailing lists