ANN: new LSM guidelines

[Paul Moore]

On Fri, Jul 7, 2023 at 6:02 PM Paul Moore <paul at paul-moore.com> wrote:
> On Thu, Jul 6, 2023 at 8:32 PM Casey Schaufler <casey at schaufler-ca.com> wrote:
> > On 7/6/2023 1:42 PM, Paul Moore wrote:
> > > Hello all,
> > >
> > > With some renewed interest in submitting new LSMs including in the
> > > upstream Linux Kernel I thought it might be a good idea to document
> > > some of our longstanding guidelines around submitting new LSMs.  I'm
> > > posting this mostly as a FYI for those who are working on new LSM
> > > submissions, but also to solicit feedback from everyone on the list
> > > regarding what we should ask of new LSMs.  If you think I'm missing
> > > something important, or believe I've added an unfair requirement,
> > > please let me know.
> > >
> > > I've added the guidelines to the README.md at the top of the LSM tree,
> > > but to make life easier for those reviewing the guidelines I'm
> > > copy-n-pasting them below ...

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.

## New LSM Hook Guidelines

While LSM hooks are generally considered outside of the Linux Kernel's stable
API promise, due to the nature of the LSM hooks we try to minimize changes to
the 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.

* There must be at least one LSM implementation of the hook included in the
submission to act as a reference for additional LSM implementations.  The
reference implementation must be for one of the upstream, in-kernel LSMs; while
the BPF LSM is an upstream LSM, it's nature precludes it from being eligible as
one of the in-kernel LSMs.

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

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

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

-- 
paul-moore.com