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@xxxxxxxxxxxxx>
---
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
