[PATCH 0/2] doc: LSM: update usage document for current LSM stacking

[PATCH 0/2] doc: LSM: update usage document for current LSM stacking

[Lincoln Wallace]

The LSM usage document (Documentation/admin-guide/LSM/index.rst) has
not kept up with the LSM stacking infrastructure. It still describes
CONFIG_DEFAULT_SECURITY, which no longer exists, and its description
of the module ordering in /sys/kernel/security/lsm does not match
what the framework actually does.

Patch 1 updates the selection mechanism description to CONFIG_LSM and
the "lsm=" parameter, keeping "security=" documented as the deprecated
legacy option. This revisits an earlier attempt by Randy Dunlap [1]
that was rejected for treating the two parameters as equivalent; the
new text keeps them distinct.

Patch 2 fixes the ordering description: lockdown precedes capability
when CONFIG_SECURITY_LOCKDOWN_LSM_EARLY is enabled, the integrity
modules are always placed at the end of the list, and the remaining
modules follow the order given by CONFIG_LSM or "lsm=".

[1] https://lore.kernel.org/r/20250114225156.10458-1-rdunlap@infradead.org

Lincoln Wallace (2):
  doc: LSM: describe CONFIG_LSM and lsm= as the selection mechanism
  doc: LSM: fix module ordering description for /sys/kernel/security/lsm

 Documentation/admin-guide/LSM/index.rst | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

-- 
2.53.0

[PATCH 1/2] doc: LSM: describe CONFIG_LSM and lsm= as the selection mechanism

[Lincoln Wallace]

The LSM usage document states that security modules are selectable at
build time via CONFIG_DEFAULT_SECURITY and can be overridden at boot
time via the "security=..." kernel command line argument.

CONFIG_DEFAULT_SECURITY no longer exists: LSMs are enabled via
CONFIG_LSM, an ordered list of the LSMs to initialize, which can be
overridden at boot time with the "lsm=" parameter. The "security="
parameter remains as a deprecated way to choose a legacy "major"
security module, and is ignored when "lsm=" is specified; see commit
89a9684ea158 ("LSM: Ignore "security=" when "lsm=" is specified").

A previous attempt replaced "security=" with "lsm=" in place [1],
which was rejected because the parameters are not equivalent:
"security=" selects a single major module while the built-in
CONFIG_LSM list otherwise remains active, whereas "lsm=" must list
every LSM to enable.

Update the paragraph to describe CONFIG_LSM and "lsm=" as the current
selection mechanism, keeping "security=" documented as the deprecated
legacy option, matching the wording in kernel-parameters.txt.

Link: https://lore.kernel.org/r/20250114225156.10458-1-rdunlap@infradead.org [1]

Signed-off-by: Lincoln Wallace <locnnil0@gmail.com>
---
 Documentation/admin-guide/LSM/index.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index b44ef68f6e4d..c24310c709dc 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -6,9 +6,11 @@ The Linux Security Module (LSM) framework provides a mechanism for
 various security checks to be hooked by new kernel extensions. The name
 "module" is a bit of a misnomer since these extensions are not actually
 loadable kernel modules. Instead, they are selectable at build-time via
-CONFIG_DEFAULT_SECURITY and can be overridden at boot-time via the
-``"security=..."`` kernel command line argument, in the case where multiple
-LSMs were built into a given kernel.
+CONFIG_LSM, an ordered list of the LSMs to enable, and can be
+overridden at boot-time via the ``"lsm=..."`` kernel command line
+argument. The ``"security=..."`` kernel command line argument remains
+available to choose a legacy "major" security module, but has been
+deprecated by the ``"lsm=..."`` parameter.
 
 The primary users of the LSM interface are Mandatory Access Control
 (MAC) extensions which provide a comprehensive security policy. Examples
-- 
2.53.0

[PATCH 2/2] doc: LSM: fix module ordering description for /sys/kernel/security/lsm

[Lincoln Wallace]

The LSM usage document states that the capability module will always
be first in /sys/kernel/security/lsm, followed by any "minor" modules
and then the one "major" module.

This does not match the current LSM infrastructure:

 - When CONFIG_SECURITY_LOCKDOWN_LSM_EARLY is enabled, lockdown is
   initialized as an early LSM, before all other modules including
   capability, and appears first in the list.

 - The integrity modules (e.g. IMA and EVM) register with
   LSM_ORDER_LAST and are always placed at the end of the list,
   regardless of the position of the major module.

 - The relative order of the remaining modules is not fixed by the
   framework; it follows CONFIG_LSM or the "lsm=" kernel command
   line parameter.

Rewrite the paragraph to describe the actual ordering: lockdown
first when early lockdown is enabled, capability otherwise,
integrity modules at the end, and the remaining modules in the
configured order.

Signed-off-by: Lincoln Wallace <locnnil0@gmail.com>
---
 Documentation/admin-guide/LSM/index.rst | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index c24310c709dc..9518495edfbc 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -27,9 +27,15 @@ man-pages project.
 A list of the active security modules can be found by reading
 ``/sys/kernel/security/lsm``. This is a comma separated list, and
 will always include the capability module. The list reflects the
-order in which checks are made. The capability module will always
-be first, followed by any "minor" modules (e.g. Yama) and then
-the one "major" module (e.g. SELinux) if there is one configured.
+order in which checks are made. The capability module will be
+first, unless CONFIG_SECURITY_LOCKDOWN_LSM_EARLY is enabled, in
+which case the lockdown module will precede it. The integrity
+modules (e.g. IMA and EVM), if enabled in the kernel
+configuration, are always placed at the end of the list. Any
+other "minor" modules (e.g. Yama) and the one "major" module
+(e.g. SELinux), if there is one configured, appear in between,
+in the order given by CONFIG_LSM or the ``"lsm=..."`` kernel
+command line parameter.
 
 Process attributes associated with "major" security modules should
 be accessed and maintained using the special files in ``/proc/.../attr``.
-- 
2.53.0