ANN: new LSM guidelines

[Paul Moore]

On Wed, Aug 2, 2023 at 2:38 PM Mickaël Salaün <mic at digikod.net> wrote:
>
> I like this guideline. I guess this is your goal and I think it should
> be part of Documentation/security/lsm.rst (and move the introduction
> part of lsm-development.rst into lsm.rst) and get a few SoB.

Thanks for the review and comments.  Responses below, but I'll post an
updated guidance doc in just a bit incorporating your feedback as well
as those of a few others who sent me comments off-list.

As far as moving this guidance into Documentation/security, yes, that
is the ultimate goal.  In fact I have a todo item to go through all of
Documentation/security and give it a good cleaning/review/edit,
although please don't expect that anytime soon :/

> On Tue, Aug 01, 2023 at 06:47:12PM -0400, Paul Moore wrote:
> > 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
>
> Why "generally"?

Good point, I'll remove that.

> > 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.
>
> We should also avoid falling in the other extreme which is to add
> different argument just-in-case. For instance, there is no need to add a
> "flags" argument to a kernel API if there is no flag for now, especially
> if there are only a few users of this hook.
>
> I would say that we want generic-as-possible hooks (e.g. well
> positioned) but not with useless arguments.

Agreed, although I think that's hard to properly describe that in a
sentence or two.  It's going to be impossible to capture every
requirement in this doc (I added a new paragraph explaining this in
the latest revision), so I think we can just leave this as-is for now.

If it does become a problem we can work a bit harder on describing
what makes a "good" LSM hook.

> > * 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.
>
> To avoid misunderstanding, I think it would be better and more generic
> to focus on the out-of-tree nature of hook implementations.  We might
> also want to give some pointers for the reason(s) why out-of-tree LSMs
> use cases are not supported.

I'm open to new language here if you have some particular wording in mind?

> > ## 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:
>
> If we go for a kernel documentation patch, it might be better to put
> most of this historic paragraph into the patch description.

Agree.

I was looking for the original comments from Arjan but couldn't find
them in an archive anywhere, if anyone has a pointer it would be great
to share that.

> > * 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.
>
> I guess defining the threat model would be a good first step (and we
> should probably add this kind of description for current LSMs as well).

I believe that should be captured in the "requirements, goals, and
expected uses" portion of the requirement above, but if you believe it
should be more explicit let me know.

> > * 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.
>
> I would also add tests! For new kernel developments, especially those
> focused on security, the interfaces should be well tested, part of
> kselftests, and run at least for each kernel release (if possible with
> the KernelCI infrastructure).  A good test coverage should be a minimal
> requirement, even if this is not enough.  Additionally, syzkaller should
> be able to efficiently fuzz these interfaces, which may require some
> tuning.

I added a test suite requirement to the latest revision.  I didn't
explicitly require kselftests, as not all current LSMs with tests make
use of kselftest, but I do think requiring some type of test suite is
important.

> Extending the kernel documentation should not stop developers to write
> man pages as well. ;)

Of course not!  While I'm a big believer in manpages, I don't believe
that we need to make that an explicit requirement.  However, I would
expect that the documentation we do require would make it easier to
produce useful manpages.

> It might also be useful to add some standalone tools in samples/

Or in a separate standalone public repo if the tools are significantly
large (see the requirement below).

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