Re: ANN: new LSM guidelines

Re: ANN: new LSM guidelines

[Mickaël Salaün]

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.

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@paul-moore.com> wrote:
> > On Thu, Jul 6, 2023 at 8:32 PM Casey Schaufler <casey@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"?

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

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

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.

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

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

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

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

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

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

Re: ANN: new LSM guidelines

[Paul Moore]

On Wed, Aug 2, 2023 at 2:38 PM Mickaël Salaün <mic@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@paul-moore.com> wrote:
> > > On Thu, Jul 6, 2023 at 8:32 PM Casey Schaufler <casey@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

Re: ANN: new LSM guidelines

[Randy Dunlap]

Hi,

On 8/2/23 14:56, Paul Moore wrote:
> On Wed, Aug 2, 2023 at 2:38 PM Mickaël Salaün <mic@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@paul-moore.com> wrote:
>>>> On Thu, Jul 6, 2023 at 8:32 PM Casey Schaufler <casey@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.

Are you referring to either of these?

https://lore.kernel.org/all/20071026141358.38342c0f@laptopd505.fenrus.org/

https://lore.kernel.org/lkml/20071024191933.53094b81@laptopd505.fenrus.org/

-- 
~Randy

Re: ANN: new LSM guidelines

[Mickaël Salaün]

On Wed, Aug 02, 2023 at 05:56:42PM -0400, Paul Moore wrote:
> On Wed, Aug 2, 2023 at 2:38 PM Mickaël Salaün <mic@digikod.net> wrote:

[...]

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

What about this?

* Every hook must demonstrate its usefulness and be actually used by
  in-kernel code.  This is required to understand the purpose of the LSM
  hooks, their expected semantic, and to be able to guarantee security
  properties throughout kernel code changes (e.g., thanks to regression
  testing).  This means that out-of-tree kernel code and pass-through
  implementations (e.g., BPF LSM) are not eligible for such reference
  implementations.

[...]

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

I think explicitly using "threat model" in this paragraph would be a
good idea.

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

Ok, see my comments in the updated doc.

Re: ANN: new LSM guidelines

[Paul Moore]

On Wed, Aug 2, 2023 at 6:36 PM Randy Dunlap <rdunlap@infradead.org> wrote:
> On 8/2/23 14:56, Paul Moore wrote:
> > 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.
>
> Are you referring to either of these?
>
> https://lore.kernel.org/all/20071026141358.38342c0f@laptopd505.fenrus.org/

Perfect, that is what I was looking for - thank you!

-- 
paul-moore.com

Re: ANN: new LSM guidelines

[Paul Moore]

On Thu, Aug 3, 2023 at 5:44 AM Mickaël Salaün <mic@digikod.net> wrote:
> On Wed, Aug 02, 2023 at 05:56:42PM -0400, Paul Moore wrote:
> > On Wed, Aug 2, 2023 at 2:38 PM Mickaël Salaün <mic@digikod.net> wrote:
>
> [...]
>
> > > > * 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?
>
> What about this?
>
> * Every hook must demonstrate its usefulness and be actually used by
>   in-kernel code.  This is required to understand the purpose of the LSM
>   hooks, their expected semantic, and to be able to guarantee security
>   properties throughout kernel code changes (e.g., thanks to regression
>   testing).  This means that out-of-tree kernel code and pass-through
>   implementations (e.g., BPF LSM) are not eligible for such reference
>   implementations.

Nice.  I made some slight changes while adding it to the doc, take a
look and let me know what you think.

> > > > * 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.
>
> I think explicitly using "threat model" in this paragraph would be a
> good idea.

Okay, I reworked that requirement slightly, please give it a look

-- 
paul-moore.com