ANN: new LSM guidelines

[Mickaël Salaün]

On Thu, Aug 03, 2023 at 05:38:23PM -0400, Paul Moore wrote:
> 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!

With some optional nitpicking, looks good to me!

> 
> ## 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

I'm not sure it is worth specifying the "not need" part, for tests and
documentation paragraphs.

> 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.

This paragraph sounds a lot like the last paragraph of the LSM hook
section, but I don't have a better suggestion.

> 
> [^1]: https://lore.kernel.org/all/20071026141358.38342c0f@laptopd505.fenrus.org
> 
> -- 
> paul-moore.com