[PATCH bpf-next 13/13] lsm: Document the LSM policy kptr hooks

[Justin Suess <utilityemal77@gmail.com>]

Describe the split of responsibilities in lsm-development.rst: an LSM
exposes policy operations to any kernel-internal caller through
generic LSM hooks. The BPF subsystem owns the strongly typed kfuncs
built on top of them, and the providing LSM only implements ordinary
LSM hooks.

Cc: Paul Moore <paul@paul-moore.com>
Cc: Casey Schaufler <casey@schaufler-ca.com>
Signed-off-by: Justin Suess <utilityemal77@gmail.com>
---

Notes:
    This attempts to clarify some of the conclusions in what an LSM
    can and can't do from Paul and Casey's feedback and make it hard
    documentation. Let me know if another place is more deserving of it.

 Documentation/security/lsm-development.rst | 27 ++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/Documentation/security/lsm-development.rst b/Documentation/security/lsm-development.rst
index 5895e529da7f..fc3af206e795 100644
--- a/Documentation/security/lsm-development.rst
+++ b/Documentation/security/lsm-development.rst
@@ -15,3 +15,30 @@ see ``security/security.c`` and associated structures:
 
 .. kernel-doc:: security/security.c
    :export:
+
+LSM policy kptr hooks and BPF kfuncs
+====================================
+
+The LSM framework implements an interface for individual LSMs to
+expose their configuration through BPF kfuncs and kptrs. An LSM
+may not export any kfunc or other BPF interface directly.
+
+An LSM wishing to expose a BPF kfunc must reuse an existing security
+hook or implement a new sufficiently generic LSM hook for the desired
+interface. The hooks are then called from kfunc definitions in
+``kernel/bpf``. This allows LSM hooks to remain sufficiently generic
+while allowing BPF programs to take advantage of the strong typing
+and runtime checking offered by the BPF verifier.
+
+The LSM providing an operation implements the operation's hook with
+``LSM_HOOK_INIT()`` like any other hook. A BPF program calling an
+LSM kfunc therefore reaches the LSM the same way every other
+kernel caller does: through an LSM hook. The hooks backing kfuncs
+follow the usual rules for new LSM hooks: their contract must be
+LSM agnostic so that other LSMs could provide a meaningful
+implementation of the same operation.
+
+Whether the LSM providing an operation is built in and active is a
+runtime property: the kfuncs are always registered when
+``CONFIG_BPF_LSM`` is enabled. BPF program loading is thus
+independent of the boot-time LSM configuration.
-- 
2.54.0