ANN: new LSM guidelines

[Paul Moore]

On Wed, Aug 2, 2023 at 6:00 PM Paul Moore <paul at paul-moore.com> wrote:
> On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul at paul-moore.com> wrote:
> > I've updated the README.md doc based on the feedback, and copied the
> > two new sections below for easier review.  If anyone has any
> > additional feedback or concerns, please let me know.
>
> Another update based on feedback received (thanks everyone!).  Just as
> before, I welcome any comments or feedback you are able to share.

MOAR UPDATES!

## New LSM Hook Guidelines

While LSM hooks are considered outside of the Linux kernel's stable API
promise, in order to limit unnecessary churn within the kernel we do try to
minimize changes to the set of LSM hooks.  With that in mind, we have the
following requirements for new LSM hooks:

* Hooks should be designed to be LSM agnostic.  While it is possible that only
one LSM might implement the hook at the time of submission, the hook's behavior
should be generic enough that other LSMs could provide a meaningful
implementation.

* The hook must be documented with a function header block that conforms to
the kernel documentation style.  At a minimum the documentation should explain
the parameters, return values, a brief overall description, any special
considerations for the callers, and any special considerations for the LSM
implementations.

* New LSM hooks must demonstrate their usefulness by providing a meaningful
implementation for at least one in-kernel LSM.  The goal is to demonstrate the
purpose and expected semantics of the hooks.  Out of tree kernel code, and pass
through implementations, such as the BPF LSM, are not eligible for LSM hook
reference implementations.

It is important to note that these requirements are not complete, due to the
ever changing nature of the Linux kernel and the unique nature of each LSM
hook.  Ultimately, new LSM hooks are added to the kernel at the discretion of
the maintainers and reviewers.

## New LSM Guidelines

Historically we have had few requirements around new LSM additions, with
Arjan van de Ven being the first to describe a basic protocol for accepting new
LSMs into the Linux kernel[^1].  In an attempt to document Arjan's basic ideas
and update them for modern Linux kernel development, here are a list of
requirements for new LSM submissions:

* The new LSM's author(s) must commit to maintain and support the new LSM for
an extended period of time.  While the authors may be currently employed to
develop and support the LSM, there is an expectation upstream that support will
continue beyond the author's employment with the original company, or the
company's backing of the LSM.

* The new LSM must be sufficiently unique to justify the additional work
involved in reviewing, maintaining, and supporting the LSM.  It is reasonable
for there to be a level of overlap between LSMs, but either the security model
or the admin/user experience must be significantly unique.

* New LSMs must include documentation providing a clear explanation of the
LSM's requirements, goals, and expected uses.  The documentation does not need
to rise to the level of a formal security model, but it should include a basic
threat model with a description of the mitigations provided by the LSM.  Both
the threat model and the LSM mitigations must be considered "reasonable" by
the LSM community as a whole.

* Any user visible interfaces provided by the LSM must be well documented.  It
is important to remember the user visible APIs are considered to be "forever
APIs" by the Linux kernel community; do not add an API that cannot be supported
for the next 20+ years.

* New LSMs must be accompanied by a publicly available test suite to verify
basic functionality and help identify regressions.  Test coverage does not need
to reach a specific percentage, but core functionality and any user interfaces
should be well covered by the test suite.  Maintaining the test suite in a
public git repository is preferable over tarball snapshots.  Integrating the
test suite with existing automated Linux kernel testing services is encouraged.

* The LSM implementation must follow general Linux kernel coding practices,
faithfully implement the security model and APIs described in the
documentation, and be free of any known defects at the time of submission.

* Any userspace tools or patches created in support of the LSM must be publicly
available, with a public git repository preferable over a tarball snapshot.

It is important to note that these requirements are not complete, due to the
ever changing nature of the Linux kernel and the unique nature of each LSM.
Ultimately, new LSMs are added to the kernel at the discretion of the
maintainers and reviewers.

[^1]: https://lore.kernel.org/all/20071026141358.38342c0f@laptopd505.fenrus.org

-- 
paul-moore.com