[RFC PATCH 9/9] Loadpol LSM: add a minimal documentation

[Simon THOBY]

Introduce a minimal documentation for Loadpol, presenting the policy
format and the two user interfaces: the securityfs policy file and the
sysctl.

Signed-off-by: Simon THOBY <git at nightmared.fr>
---
 Documentation/admin-guide/LSM/Loadpol.rst | 81 +++++++++++++++++++++++
 Documentation/admin-guide/LSM/index.rst   |  1 +
 2 files changed, 82 insertions(+)
 create mode 100644 Documentation/admin-guide/LSM/Loadpol.rst

diff --git a/Documentation/admin-guide/LSM/Loadpol.rst b/Documentation/admin-guide/LSM/Loadpol.rst
new file mode 100644
index 000000000000..0aa24a8d393c
--- /dev/null
+++ b/Documentation/admin-guide/LSM/Loadpol.rst
@@ -0,0 +1,81 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+Loadpol
+=======
+
+Loadpol is a Linux Security Module that enforces a user-provided policy
+when decided whether a dynamic module can be loaded or not.
+
+The policy can be read and rewritten at ``/sys/kernel/security/loadpol/policy``.
+
+A default policy is created that contains the current list of blacklisted modules,
+and a catch-all entry that allow loading any module.
+
+Policy format
+=============
+
+The policy is defined as a set of line-separated entries.
+Each entry define the conditions for a match (the origin of the load request and
+the name of the kernel module), and the action to take when the load request
+matches the entry.
+
+
+Entry syntax: ``[origin=(userspace|kernel|kernel,userspace)] [module=<module_name>] action=(allow|deny)``
+
+There are two matching conditions:
+
+``origin``:
+    Load Requests can come from two origins:
+
+    * ``userspace`` (ie. a program in userspace called modprobe/insmod)
+    * ``kernel`` (the kernel requested the module directly by calling
+      ``request_module(...)``, e.g. loading a filesystem when performing a
+      ``-o loop`` mount).
+
+    When unspecified, the condition defaults to ``kernel,userspace`` (which means
+    that both origins match).
+
+``module``:
+    Name of the kernel module being matched. The name can contain wilcards.
+    Beware, module aliases do not work!
+
+There are two possible actions:
+
+* ``allow``: permit the load of the kernel module.
+* ``deny``: reject the load of the kernel module and emit an audit log.
+
+The policy is not greedy: as soon as a match is found, the evaluation terminates
+with the result of that match. So be very careful with the order of your entries.
+
+The main use cases of the policy will probably be to define an allowlist
+(here, we allow ``module_a`` and any module starting with ``module_b`` loaded
+by the user)::
+
+	module==module_a action=allow
+	origin==user module==module_b* action=deny
+	action=deny
+
+But other mechanisms are possible, like a denylist
+(here we block ``module_a``, ``module_b`` if it is loaded by the kernel and
+any module starting with ``module_c`` loaded by the user)::
+
+	module==module_a action=deny
+	origin==kernel module==module_b action=deny
+	origin==user module==module_c* action=deny
+	action=allow
+
+Policy lock
+===========
+
+In order to protect the policy from tampering, a sysctl is provided to
+lock-in-place the currently-loaded policy.
+
+The ``security.loadpol.locked`` can take 2 values:
+
+0 - default:
+    the policy can be reloaded at runtime by any administrator.
+
+1 - locked:
+    the policy cannot be updated or modified, and loadpol cannot be disabled
+    without rebooting.
diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index b44ef68f6e4d..01d36670d8ad 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -42,6 +42,7 @@ subdirectories.
 
    apparmor
    LoadPin
+   Loadpol
    SELinux
    Smack
    tomoyo
-- 
2.49.0