Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
landlock: Add errata documentation section
Add errata section with code examples for querying errata and a warning
that most applications should not check errata. Use kernel-doc directives
to include errata descriptions from the header files instead of manual
links.
Also enhance existing DOC sections in security/landlock/errata/abi-*.h
files with Impact sections, and update the code comment in syscalls.c
to remind developers to update errata documentation when applicable.
This addresses the gap where the kernel implements errata tracking
but provides no user-facing documentation on how to use it, while
improving the existing technical documentation in-place rather than
duplicating it.
Signed-off-by: Samasth Norway Ananda <samasth.norway.ananda@oracle.com>
Reviewed-by: Günther Noack <gnoack3000@gmail.com>
Link: https://lore.kernel.org/r/20260128031814.2945394-3-samasth.norway.ananda@oracle.com
[mic: Cosmetic fix]
Signed-off-by: Mickaël Salaün <mic@digikod.net>
authored by
Samasth Norway Ananda
and committed by
Mickaël Salaün
fe72ce67
6100f290
+90
-4
+62
-3
Documentation/userspace-api/landlock.rst
+62
-3
Documentation/userspace-api/landlock.rst
···
445
445
printf("Landlock supports LANDLOCK_ACCESS_FS_REFER.\n");
446
446
}
447
447
448
-
The following kernel interfaces are implicitly supported by the first ABI
449
-
version. Features only supported from a specific version are explicitly marked
450
-
as such.
448
+
All Landlock kernel interfaces are supported by the first ABI version unless
449
+
explicitly noted in their documentation.
450
+
451
+
Landlock errata
452
+
---------------
453
+
454
+
In addition to ABI versions, Landlock provides an errata mechanism to track
455
+
fixes for issues that may affect backwards compatibility or require userspace
456
+
awareness. The errata bitmask can be queried using:
457
+
458
+
.. code-block:: c
459
+
460
+
int errata;
461
+
462
+
errata = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_ERRATA);
463
+
if (errata < 0) {
464
+
/* Landlock not available or disabled */
465
+
return 0;
466
+
}
467
+
468
+
The returned value is a bitmask where each bit represents a specific erratum.
469
+
If bit N is set (``errata & (1 << (N - 1))``), then erratum N has been fixed
470
+
in the running kernel.
471
+
472
+
.. warning::
473
+
474
+
**Most applications should NOT check errata.** In 99.9% of cases, checking
475
+
errata is unnecessary, increases code complexity, and can potentially
476
+
decrease protection if misused. For example, disabling the sandbox when an
477
+
erratum is not fixed could leave the system less secure than using
478
+
Landlock's best-effort protection. When in doubt, ignore errata.
479
+
480
+
.. kernel-doc:: security/landlock/errata/abi-4.h
481
+
:doc: erratum_1
482
+
483
+
.. kernel-doc:: security/landlock/errata/abi-6.h
484
+
:doc: erratum_2
485
+
486
+
.. kernel-doc:: security/landlock/errata/abi-1.h
487
+
:doc: erratum_3
488
+
489
+
How to check for errata
490
+
~~~~~~~~~~~~~~~~~~~~~~~
491
+
492
+
If you determine that your application needs to check for specific errata,
493
+
use this pattern:
494
+
495
+
.. code-block:: c
496
+
497
+
int errata = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_ERRATA);
498
+
if (errata >= 0) {
499
+
/* Check for specific erratum (1-indexed) */
500
+
if (errata & (1 << (erratum_number - 1))) {
501
+
/* Erratum N is fixed in this kernel */
502
+
} else {
503
+
/* Erratum N is NOT fixed - consider implications for your use case */
504
+
}
505
+
}
506
+
507
+
**Important:** Only check errata if your application specifically relies on
508
+
behavior that changed due to the fix. The fixes generally make Landlock less
509
+
restrictive or more correct, not more restrictive.
451
510
452
511
Kernel interface
453
512
================
+8
security/landlock/errata/abi-1.h
+8
security/landlock/errata/abi-1.h
···
12
12
* hierarchy down to its filesystem root and those from the related mount point
13
13
* hierarchy. This prevents access right widening through rename or link
14
14
* actions.
15
+
*
16
+
* Impact:
17
+
*
18
+
* Without this fix, it was possible to widen access rights through rename or
19
+
* link actions involving disconnected directories, potentially bypassing
20
+
* ``LANDLOCK_ACCESS_FS_REFER`` restrictions. This could allow privilege
21
+
* escalation in complex mount scenarios where directories become disconnected
22
+
* from their original mount points.
15
23
*/
16
24
LANDLOCK_ERRATUM(3)
+7
security/landlock/errata/abi-4.h
+7
security/landlock/errata/abi-4.h
···
11
11
* :manpage:`bind(2)` and :manpage:`connect(2)` operations. This change ensures
12
12
* that only TCP sockets are subject to TCP access rights, allowing other
13
13
* protocols to operate without unnecessary restrictions.
14
+
*
15
+
* Impact:
16
+
*
17
+
* In kernels without this fix, using ``LANDLOCK_ACCESS_NET_BIND_TCP`` or
18
+
* ``LANDLOCK_ACCESS_NET_CONNECT_TCP`` would incorrectly restrict non-TCP
19
+
* stream protocols (SMC, MPTCP, SCTP), potentially breaking applications
20
+
* that rely on these protocols while using Landlock network restrictions.
14
21
*/
15
22
LANDLOCK_ERRATUM(1)
+10
security/landlock/errata/abi-6.h
+10
security/landlock/errata/abi-6.h
···
15
15
* interaction between threads of the same process should always be allowed.
16
16
* This change ensures that any thread is allowed to send signals to any other
17
17
* thread within the same process, regardless of their domain.
18
+
*
19
+
* Impact:
20
+
*
21
+
* This problem only manifests when the userspace process is itself using
22
+
* :manpage:`libpsx(3)` or an equivalent mechanism to enforce a Landlock policy
23
+
* on multiple already-running threads at once. Programs which enforce a
24
+
* Landlock policy at startup time and only then become multithreaded are not
25
+
* affected. Without this fix, signal scoping could break multi-threaded
26
+
* applications that expect threads within the same process to freely signal
27
+
* each other.
18
28
*/
19
29
LANDLOCK_ERRATUM(2)
+3
-1
security/landlock/syscalls.c
+3
-1
security/landlock/syscalls.c
···
158
158
/*
159
159
* The Landlock ABI version should be incremented for each new Landlock-related
160
160
* user space visible change (e.g. Landlock syscalls). This version should
161
-
* only be incremented once per Linux release, and the date in
161
+
* only be incremented once per Linux release. When incrementing, the date in
162
162
* Documentation/userspace-api/landlock.rst should be updated to reflect the
163
163
* UAPI change.
164
+
* If the change involves a fix that requires userspace awareness, also update
165
+
* the errata documentation in Documentation/userspace-api/landlock.rst .
164
166
*/
165
167
const int landlock_abi_version = 8;
166
168