ANN: new LSM guidelines

ANN: new LSM guidelines

[Paul Moore]

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:

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

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

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

The entire README.md file, including the guidelines above, can also be
viewed in your browser at the link below:

* https://github.com/LinuxSecurityModule/kernel/blob/main/README.md

-- 
paul-moore.com

Re: ANN: new LSM guidelines

[Casey Schaufler]

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

Some commitment to maintaining the LSM for a reasonable time must be
provided. Although this should probably be implicit in the use cases
and goals, changes in product direction or employment status can leave
an LSM orphaned before its time.

New LSM hooks introduced need to be generically usable. Use of LSM
specific data should be avoided. The hook should include data at a
granularity that can accommodate the existing LSMs as well as the
new one. The data granularity must be appropriate for the sub-system
from which it is called.

>
> The entire README.md file, including the guidelines above, can also be
> viewed in your browser at the link below:
>
> * https://github.com/LinuxSecurityModule/kernel/blob/main/README.md
>

Re: ANN: new LSM guidelines

[Paul Moore]

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:
> >
> > * 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.
> >
> > * 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.
> >
> > * 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.
>
> Some commitment to maintaining the LSM for a reasonable time must be
> provided. Although this should probably be implicit in the use cases
> and goals, changes in product direction or employment status can leave
> an LSM orphaned before its time.

That's a good point, likely worth mentioning.  We're currently being
bit by that with SafeSetID, so the implicit understanding may need to
be made a bit more explicit.

> New LSM hooks introduced need to be generically usable. Use of LSM
> specific data should be avoided. The hook should include data at a
> granularity that can accommodate the existing LSMs as well as the
> new one. The data granularity must be appropriate for the sub-system
> from which it is called.

I hadn't thought of adding a section on adding new LSM hooks, but that
seems like a good idea too.  Thanks.

-- 
paul-moore.com

Re: ANN: new LSM guidelines

[Paul Moore]

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

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

[Paul Moore]

On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul@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.

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

* 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, its nature precludes it from being eligible as
one of the in-kernel LSMs.

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

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

[Mickaël Salaün]

On Wed, Aug 02, 2023 at 06:00:22PM -0400, Paul Moore wrote:
> On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul@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.
> 
> ## New LSM Hook Guidelines
> 
> While LSM hooks are considered outside of the Linux Kernel's stable API

s/Kernel/kernel/g

[...]

> * New LSMs must be accompanied by a 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.  Integration with existing automated Linux Kernel
> testing services is encouraged.

I'd suggest to require tests to be publicly available and easy (or not
too difficult) to run for the sake of sanity of other kernel developers
that might need to quickly fix (critical) bugs even without the help of
the maintainer (who might be unavailable for various reasons).  I guess
you could argue that decent kernel code needs a reasonable bus factor
protection, but making tests available and easy to use is a quality
guarantee.

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 06:00:22PM -0400, Paul Moore wrote:
> > On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul@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.
> >
> > ## New LSM Hook Guidelines
> >
> > While LSM hooks are considered outside of the Linux Kernel's stable API
>
> s/Kernel/kernel/g

Done for the entire doc.

> > * New LSMs must be accompanied by a 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.  Integration with existing automated Linux Kernel
> > testing services is encouraged.
>
> I'd suggest to require tests to be publicly available and easy (or not
> too difficult) to run for the sake of sanity of other kernel developers
> that might need to quickly fix (critical) bugs even without the help of
> the maintainer (who might be unavailable for various reasons).

Good point.  We mention a public repository for associated userspace
tools/patches, we should do the same for the tests.  While I also
agree that the tests should be easy to setup and run, I'm not sure I
want to put that as a requirement simply because it is so hard to
properly quantify.

> I guess
> you could argue that decent kernel code needs a reasonable bus factor
> protection, but making tests available and easy to use is a quality
> guarantee.

At one point I debated adding a requirement about having a "community"
behind new LSM submissions, but I worry that would introduce a
chicken/egg problem.  In theory, if a LSM is properly documented, has
meaningful tests, and is reasonably coded, any interested party could
pick it up if the original author/maintainer ceased maintaining the
code.

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

Re: ANN: new LSM guidelines

[Paul Moore]

On Wed, Aug 2, 2023 at 6:00 PM Paul Moore <paul@paul-moore.com> wrote:
> On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul@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

Re: 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@paul-moore.com> wrote:
> > On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul@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

Re: ANN: new LSM guidelines

[Paul Moore]

On Fri, Aug 4, 2023 at 3:58 AM Mickaël Salaün <mic@digikod.net> wrote:
>
> 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@paul-moore.com> wrote:
> > > On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul@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!

Great, thanks for your help with the reviews, suggestions, etc.  I
think the guidelines are much better now than when we started.

> > ## New LSM Guidelines

...

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

My goal with that was to try and not scare people away with a
tremendous documentation and/or testing burden to start.  I'd like to
keep it in the doc, but I understand your point.

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

That's because it is pretty much the same paragraph :)

I agree, it would be nice if there were a little more different, but
given that the purpose is the same for each paragraph I'm not sure
spending a lot of time to make them read significantly different is
going to accomplish a lot.

-- 
paul-moore.com

Re: ANN: new LSM guidelines

[Paul Moore]

On Thu, Aug 3, 2023 at 5:38 PM Paul Moore <paul@paul-moore.com> wrote:
>
> On Wed, Aug 2, 2023 at 6:00 PM Paul Moore <paul@paul-moore.com> wrote:
> > On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul@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

...

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

Based on some off-list discussions, I've added some text to the end of
the paragraph above to allow for a reasonable plan of succession in
cases where the original LSM authors are not able to commit to long
term support.  Just as before, comments are always welcome :)

Here is the new paragraph:

"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 authors' employment with the original company, or the
company's backing of the LSM.  If the authors are not able to commit to
supporting the LSM for an extended period of time, a reasonable succession plan
must be submitted along with the LSM."

-- 
paul-moore.com

Re: ANN: new LSM guidelines

[Casey Schaufler]

On 9/7/2023 3:12 PM, Paul Moore wrote:
> On Thu, Aug 3, 2023 at 5:38 PM Paul Moore <paul@paul-moore.com> wrote:
>> On Wed, Aug 2, 2023 at 6:00 PM Paul Moore <paul@paul-moore.com> wrote:
>>> On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul@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
> ..
>
>> ## 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.
> Based on some off-list discussions, I've added some text to the end of
> the paragraph above to allow for a reasonable plan of succession in
> cases where the original LSM authors are not able to commit to long
> term support.  Just as before, comments are always welcome :)
>
> Here is the new paragraph:
>
> "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 authors' employment with the original company, or the
> company's backing of the LSM.  If the authors are not able to commit to
> supporting the LSM for an extended period of time, a reasonable succession plan
> must be submitted along with the LSM."

This makes it sound like LSMs are always developed for corporate use.
While that is generally true, we should acknowledge that the "sponsor"
of an LSM could be a corporation/government, a foundation or a hobbyist.
A large, comprehensive LSM from a billion dollar corporation in support
of a specific product should require more commitment than a small, targeted
LSM of general interest from joe@schlobotnit.org. I trust that we would
have the wisdom to make such a distinction, but I don't think we want to
scare off developers by making it sound like an LSM is something that only
a corporation can provide a support plan for.

Re: ANN: new LSM guidelines

[Paul Moore]

On Fri, Sep 8, 2023 at 12:03 PM Casey Schaufler <casey@schaufler-ca.com> wrote:
> On 9/7/2023 3:12 PM, Paul Moore wrote:
> > On Thu, Aug 3, 2023 at 5:38 PM Paul Moore <paul@paul-moore.com> wrote:
> >> On Wed, Aug 2, 2023 at 6:00 PM Paul Moore <paul@paul-moore.com> wrote:
> >>> On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul@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
> > ..
> >
> >> ## 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.
> > Based on some off-list discussions, I've added some text to the end of
> > the paragraph above to allow for a reasonable plan of succession in
> > cases where the original LSM authors are not able to commit to long
> > term support.  Just as before, comments are always welcome :)
> >
> > Here is the new paragraph:
> >
> > "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 authors' employment with the original company, or the
> > company's backing of the LSM.  If the authors are not able to commit to
> > supporting the LSM for an extended period of time, a reasonable succession plan
> > must be submitted along with the LSM."
>
> This makes it sound like LSMs are always developed for corporate use.

I'll agree that I could probably phrase the paragraph above s little
better, but I disagree with the assertion that the paragraph implies
"LSMs are always developed for corporate use".

How about the following:

"The new LSM's author(s) must commit to maintain and support the new LSM for
an extended period of time; this applies both to authors that are employed to
develop and maintain a LSM as well as those that develop and maintain a LSM on
their own time.  If the authors are currently supporting a LSM as part of their
employment, there is an expectation upstream that support will continue beyond
the authors' tenure at their current company.  In either case, if the authors
are unable to commit to supporting the LSM for an extended period of time, a
reasonable succession plan must be submitted along with the LSM."

-- 
paul-moore.com

Re: ANN: new LSM guidelines

[Casey Schaufler]

On 9/8/2023 10:29 AM, Paul Moore wrote:
> On Fri, Sep 8, 2023 at 12:03 PM Casey Schaufler <casey@schaufler-ca.com> wrote:
>> On 9/7/2023 3:12 PM, Paul Moore wrote:
>>> On Thu, Aug 3, 2023 at 5:38 PM Paul Moore <paul@paul-moore.com> wrote:
>>>> On Wed, Aug 2, 2023 at 6:00 PM Paul Moore <paul@paul-moore.com> wrote:
>>>>> On Tue, Aug 1, 2023 at 6:47 PM Paul Moore <paul@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
>>> ..
>>>
>>>> ## 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.
>>> Based on some off-list discussions, I've added some text to the end of
>>> the paragraph above to allow for a reasonable plan of succession in
>>> cases where the original LSM authors are not able to commit to long
>>> term support.  Just as before, comments are always welcome :)
>>>
>>> Here is the new paragraph:
>>>
>>> "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 authors' employment with the original company, or the
>>> company's backing of the LSM.  If the authors are not able to commit to
>>> supporting the LSM for an extended period of time, a reasonable succession plan
>>> must be submitted along with the LSM."
>> This makes it sound like LSMs are always developed for corporate use.
> I'll agree that I could probably phrase the paragraph above s little
> better, but I disagree with the assertion that the paragraph implies
> "LSMs are always developed for corporate use".
>
> How about the following:
>
> "The new LSM's author(s) must commit to maintain and support the new LSM for
> an extended period of time; this applies both to authors that are employed to
> develop and maintain a LSM as well as those that develop and maintain a LSM on
> their own time.  If the authors are currently supporting a LSM as part of their
> employment, there is an expectation upstream that support will continue beyond
> the authors' tenure at their current company.  In either case, if the authors
> are unable to commit to supporting the LSM for an extended period of time, a
> reasonable succession plan must be submitted along with the LSM."

Better. Thank you.

Re: ANN: new LSM guidelines

[Tetsuo Handa]

On 2023/08/03 7:00, Paul Moore wrote:
> * 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.

s/work/burden/ ?

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

What is the definition of "publicly" here? Everyone can download related resources
including the source code etc. anonymously (e.g. without asking for creating user
account and/or buying subscriptions ) ?



If one of userspace tools designed for the new LSM depends on the LSM ID, when can
the author of the new LSM obtain the stable LSM ID for that LSM ?

This might trigger a catch-22 situation while reviewing, for the author of such
userspace tools will not be able to publish on a publicly available git repository
without the stable LSM ID whereas LSM people say that only in-tree LSMs get the
stable LSM ID. If userspace tools needs to be publicly available while reviewing,
a stable LSM ID must be assigned for that LSM in order to allow userspace tools
being published on a publicly available git repository by the moment the author
of a new LSM proposes that LSM to the community for review.

I'm still against the "only in-tree LSMs get the stable LSM ID" part. As long as
someone developed an LSM in a manner that is publicly available, a stable LSM ID
should be assigned, regardless of whether that LSM succeeds in becoming one of
in-tree LSMs.

Re: ANN: new LSM guidelines

[Serge E. Hallyn]

On Sat, Sep 09, 2023 at 09:46:02AM +0900, Tetsuo Handa wrote:
> On 2023/08/03 7:00, Paul Moore wrote:
> > * 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.
> 
> s/work/burden/ ?
> 
> > * 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.
> 
> What is the definition of "publicly" here? Everyone can download related resources
> including the source code etc. anonymously (e.g. without asking for creating user
> account and/or buying subscriptions ) ?

Hm, that's a good point actually.  I would say that one must be able to fully
administer it with free (in both senses) tools, which must be used (let's aim
for the moon) in an included testsuite.  However, that doesn't need to be true
of "any" support tools.  If the author wants to sell some improved tools,  I
think that's good.  But again, the free tools must always be able to configure
every aspect of the LSM.

-serge

Re: ANN: new LSM guidelines

[Paul Moore]

On Fri, Sep 8, 2023 at 8:46 PM Tetsuo Handa
<penguin-kernel@i-love.sakura.ne.jp> wrote:
> On 2023/08/03 7:00, Paul Moore wrote:
> > * 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.
>
> s/work/burden/ ?

Possibly, although I think I prefer "work" here since it has a more
positive connotation than "burden".

> > * 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.
>
> What is the definition of "publicly" here? Everyone can download related resources
> including the source code etc. anonymously (e.g. without asking for creating user
> account and/or buying subscriptions ) ?

I agree with Serge that you bring up a very good point, and I think
the requirement of being able to download and use the tools without
requiring a account, subscription, etc. is a good one.

I've replaced that guideline with the following:

"If new userspace tools, or patches to existing tools, are necessary to
configure, operate, or otherwise manage the LSM, these tools or patches must
be publicly available without download restrictions requiring accounts,
subscriptions, etc.  Maintaining these tools or patches in a public git
repository is preferable over tarball snapshots."

I made a similar edit to the test suite guidelines:

"New LSMs must be accompanied by a test suite to verify basic functionality
and help identify regressions.  The test suite must be publicly available
without download restrictions requiring accounts, subscriptions, etc.  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."

What do you think?

> If one of userspace tools designed for the new LSM depends on the LSM ID, when can
> the author of the new LSM obtain the stable LSM ID for that LSM ?

A permanent LSM ID is assigned to LSMs when they are merged into the
upstream LSM tree.  This is no different than any other kernel defined
macro constant, enum, magic number, etc. that is shared between kernel
and userspace and is considered part of the kernel's API.

LSM developers creating userspace tooling that makes use of the LSM ID
numbers should use the macro name and not the number, this should
allow the tooling to support the permanent LSM ID with a simple
recompile.

I understand you are opposed to the numeric LSM ID as part of the
kernel's API, but I believe this is both the correct way forward, and
consistent with other kernel APIs.  It is your right to disagree, but
I have yet to see a reason to revisit this decision and respectfully
request that you accept this and refrain from revisiting this argument
unless you have new information which would warrant a new discussion.

-- 
paul-moore.com

Re: ANN: new LSM guidelines

[Tetsuo Handa]

On 2023/09/12 5:04, Paul Moore wrote:
>> If one of userspace tools designed for the new LSM depends on the LSM ID, when can
>> the author of the new LSM obtain the stable LSM ID for that LSM ?
> 
> A permanent LSM ID is assigned to LSMs when they are merged into the
> upstream LSM tree.  This is no different than any other kernel defined
> macro constant, enum, magic number, etc. that is shared between kernel
> and userspace and is considered part of the kernel's API.

Then, your

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

is an ultimately unfair requirement, for the combination of

  Ultimately, new LSMs are added to the kernel at the discretion of the maintainers
  and reviewers.

and

  A permanent LSM ID is assigned to LSMs when they are merged into the upstream
  LSM tree.

causes locking out not-yet-in-tree and out-of-tree LSMs.

> I understand you are opposed to the numeric LSM ID as part of the
> kernel's API, but I believe this is both the correct way forward, and
> consistent with other kernel APIs.  It is your right to disagree, but
> I have yet to see a reason to revisit this decision and respectfully
> request that you accept this and refrain from revisiting this argument
> unless you have new information which would warrant a new discussion.

I'm not against the numeric LSM ID itself. I'm against the policy for assigning
numeric LSM ID. The numeric LSM ID can become the correct way forward only if
the following problem is solved.



A market is not a location where only products that passed a patent examination
are available. There are always products which failed to pass a patent examination.
But you are trying to make products which failed to pass a patent examination into
unavailable state, by requiring each product to get a barcode number which is assigned
to only products that passed a patent examination. Such situation is a regression
compared to requiring each product to have a product name.

A Linux kernel is not a program where only codes that passed a patent examination
can be loaded and executed. There are always programs which failed to pass a patent
examination. But you are trying to make programs which failed to pass a patent
examination into unavailable state, by requiring each program to get an identifier
which is assigned to only programs that passed a patent examination.

LSMs are one of programs designed for the Linux kernel. That is, there are always
LSMs which failed to become one of in-tree LSMs. But you are trying to make LSMs
which failed to pass a patent examination into unavailable state, by requiring
each LSM to get an LSM ID which is assigned to only programs that passed a patent
examination.

> LSM developers creating userspace tooling that makes use of the LSM ID
> numbers should use the macro name and not the number, this should
> allow the tooling to support the permanent LSM ID with a simple
> recompile.

"Using the macro name and not the number" is the catch-22 situation. The problem is
that LSMs which are under review for becoming one of in-tree LSMs (and LSMs which
failed to become one of in-tree LSMs due to the patent examination) cannot rely on
the macro from the code in the public git repository due to lack of a stable number
for that macro.

When someone wants to try the userspace tooling, you are saying that that someone
can use -DLSM_NUMERIC_ID_FOR_THAT_LSM_MODULE=... argument to gcc when compiling
the userspace, without saying the ... part. The consequence will be conflicts
between multiple LSMs and/or non-working userspace tools. This will not facilitate
use of the LSM interface.



Whether LSM ID is "consistent with other kernel APIs" is completely irrelevant.

The LSM ID must behave like PCI device IDs and/or entries in /etc/services .
That is, whether the device driver and/or networking services are available
in the upstream kernel is irrelevant. PCI device drivers which are not available
in the upstream kernel are allowed to be loaded. The LSM ID database must behave
like the list of all LSMs which are publicly available in the world, rather than
what LSMs are permitted to be loaded and what userspace tools can work.

The current LSM ID is designed for locking out all products which are not available
in the upstream market. The concept of LSM ID must be changed to allow any product
to be publicly available from somewhere in the world. Otherwise, use of numeric ID
(and the "LSM syscall patchset" which uses the numeric ID) is a complete garbage.



The LSM ID is not a API. The LSM ID is a publicly available database.
Passing a patent examination must not be a requirement for assigning a stable LSM ID.
The LSM ID numbers must be available to all publicly available LSMs.

That is, either get rid of the patent examination requirement (so that whatever
proposed LSMs can become in-tree as long as maintaining and supporting the new
LSM for an extended period of time are committed), or assign the LSM ID by an
independent organization rather than at the discretion of the maintainers and
reviewers (so that whatever LSM can obtain a stable LSM ID regardless of whether
that LSM succeeds in becoming one of in-tree LSMs).

Re: ANN: new LSM guidelines

[Paul Moore]

On Mon, Sep 11, 2023 at 9:29 PM Tetsuo Handa
<penguin-kernel@i-love.sakura.ne.jp> wrote:
> On 2023/09/12 5:04, Paul Moore wrote:
> >> If one of userspace tools designed for the new LSM depends on the LSM ID, when can
> >> the author of the new LSM obtain the stable LSM ID for that LSM ?
> >
> > A permanent LSM ID is assigned to LSMs when they are merged into the
> > upstream LSM tree.  This is no different than any other kernel defined
> > macro constant, enum, magic number, etc. that is shared between kernel
> > and userspace and is considered part of the kernel's API.
>
> Then, your
>
>   * 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.
>
> is an ultimately unfair requirement, for the combination of
>
>   Ultimately, new LSMs are added to the kernel at the discretion of the maintainers
>   and reviewers.
>
> and
>
>   A permanent LSM ID is assigned to LSMs when they are merged into the upstream
>   LSM tree.
>
> causes locking out not-yet-in-tree and out-of-tree LSMs.

As discussed many times prior, I consider in-tree, upstreamed LSMs my
priority when it comes to decision making.  LSMs which are under
development and are working to be merged come next, and LSMs which
have decided to remain out-of-tree remain last.  I do not
intentionally plan to make life difficult for the out-of-tree LSMs,
but if that happens as a result of design decisions intended to
benefit in-tree LSMs that is acceptable as far as I am concerned.  You
are free to disagree, but I believe the policy I've described here is
consistent with the bulk of the other kernel subsystems and I have no
plans to change this policy.

> > I understand you are opposed to the numeric LSM ID as part of the
> > kernel's API, but I believe this is both the correct way forward, and
> > consistent with other kernel APIs.  It is your right to disagree, but
> > I have yet to see a reason to revisit this decision and respectfully
> > request that you accept this and refrain from revisiting this argument
> > unless you have new information which would warrant a new discussion.
>
> I'm not against the numeric LSM ID itself. I'm against the policy for assigning
> numeric LSM ID. The numeric LSM ID can become the correct way forward only if
> the following problem is solved.
>
> A market is not a location where only products that passed a patent examination
> are available ...

Once again, we've already discussed this many, many times: out-of-tree
LSMs are not the priority and that is not going to change.  One
corollary of this is that we are not going to assign LSM IDs to LSMs
that remain out-of-tree as this would negatively impact the LSM layer
by cluttering/depleting the LSM ID space.  LSMs that are working
towards integration with the upstream Linux kernel can self-assign a
temporary LSM ID which will be finalized upon merging in the LSM tree.
Based on all of the arguments you have already submitted - and let us
be very clear: you are the only one speaking out against this - I see
no reason to change this policy.

> The LSM ID is not a API. The LSM ID is a publicly available database.

By every definition of "API" that I have ever seen, the LSM ID *is*
part of the proposed LSM syscall API.

In my last email in this thread I asked you to refrain from revisiting
old arguments.  Unfortunately you either chose to reject that request
or you mistakenly thought your latest email was presenting new ideas
as opposed to a slight reframing of your existing objections.  I am
sorry that we have reached this point, but I am done discussing this
with you Tetsuo; unless I see any new arguments from you this will be
my last reply to you on this topic.

-- 
paul-moore.com

Re: ANN: new LSM guidelines

[Casey Schaufler]

On 9/12/2023 11:08 AM, Paul Moore wrote:
> On Mon, Sep 11, 2023 at 9:29 PM Tetsuo Handa
> <penguin-kernel@i-love.sakura.ne.jp> wrote:
>> On 2023/09/12 5:04, Paul Moore wrote:
>>>> If one of userspace tools designed for the new LSM depends on the LSM ID, when can
>>>> the author of the new LSM obtain the stable LSM ID for that LSM ?
>>> A permanent LSM ID is assigned to LSMs when they are merged into the
>>> upstream LSM tree.  This is no different than any other kernel defined
>>> macro constant, enum, magic number, etc. that is shared between kernel
>>> and userspace and is considered part of the kernel's API.
>> Then, your
>>
>>   * 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.
>>
>> is an ultimately unfair requirement, for the combination of
>>
>>   Ultimately, new LSMs are added to the kernel at the discretion of the maintainers
>>   and reviewers.
>>
>> and
>>
>>   A permanent LSM ID is assigned to LSMs when they are merged into the upstream
>>   LSM tree.
>>
>> causes locking out not-yet-in-tree and out-of-tree LSMs.
> As discussed many times prior, I consider in-tree, upstreamed LSMs my
> priority when it comes to decision making.  LSMs which are under
> development and are working to be merged come next, and LSMs which
> have decided to remain out-of-tree remain last.  I do not
> intentionally plan to make life difficult for the out-of-tree LSMs,
> but if that happens as a result of design decisions intended to
> benefit in-tree LSMs that is acceptable as far as I am concerned.  You
> are free to disagree, but I believe the policy I've described here is
> consistent with the bulk of the other kernel subsystems and I have no
> plans to change this policy.
>
>>> I understand you are opposed to the numeric LSM ID as part of the
>>> kernel's API, but I believe this is both the correct way forward, and
>>> consistent with other kernel APIs.  It is your right to disagree, but
>>> I have yet to see a reason to revisit this decision and respectfully
>>> request that you accept this and refrain from revisiting this argument
>>> unless you have new information which would warrant a new discussion.
>> I'm not against the numeric LSM ID itself. I'm against the policy for assigning
>> numeric LSM ID. The numeric LSM ID can become the correct way forward only if
>> the following problem is solved.
>>
>> A market is not a location where only products that passed a patent examination
>> are available ...
> Once again, we've already discussed this many, many times: out-of-tree
> LSMs are not the priority and that is not going to change.  One
> corollary of this is that we are not going to assign LSM IDs to LSMs
> that remain out-of-tree as this would negatively impact the LSM layer
> by cluttering/depleting the LSM ID space.  LSMs that are working
> towards integration with the upstream Linux kernel can self-assign a
> temporary LSM ID which will be finalized upon merging in the LSM tree.
> Based on all of the arguments you have already submitted - and let us
> be very clear: you are the only one speaking out against this - I see
> no reason to change this policy.

I won't say this is a great idea, or that I endorse it, but we could
allocate a range of LSM ID values ( 10000 - 10999 ? ) that we promise
will never be given to an upstream LSM. We wouldn't make any guarantees
about conflicts otherwise. These could be used by LSMs before they are
accepted upstream or by LSMs that don't have upstream aspirations. I
seriously doubt that anyone using such an LSM is going to be mixing
multiple such LSMs without being capable of managing ID conflicts.

Just a thought.

>> The LSM ID is not a API. The LSM ID is a publicly available database.
> By every definition of "API" that I have ever seen, the LSM ID *is*
> part of the proposed LSM syscall API.
>
> In my last email in this thread I asked you to refrain from revisiting
> old arguments.  Unfortunately you either chose to reject that request
> or you mistakenly thought your latest email was presenting new ideas
> as opposed to a slight reframing of your existing objections.  I am
> sorry that we have reached this point, but I am done discussing this
> with you Tetsuo; unless I see any new arguments from you this will be
> my last reply to you on this topic.
>

Re: ANN: new LSM guidelines

[Paul Moore]

On Tue, Sep 12, 2023 at 2:40 PM Casey Schaufler <casey@schaufler-ca.com> wrote:
> On 9/12/2023 11:08 AM, Paul Moore wrote:
> >
> > Once again, we've already discussed this many, many times: out-of-tree
> > LSMs are not the priority and that is not going to change.  One
> > corollary of this is that we are not going to assign LSM IDs to LSMs
> > that remain out-of-tree as this would negatively impact the LSM layer
> > by cluttering/depleting the LSM ID space.  LSMs that are working
> > towards integration with the upstream Linux kernel can self-assign a
> > temporary LSM ID which will be finalized upon merging in the LSM tree.
> > Based on all of the arguments you have already submitted - and let us
> > be very clear: you are the only one speaking out against this - I see
> > no reason to change this policy.
>
> I won't say this is a great idea, or that I endorse it, but we could
> allocate a range of LSM ID values ( 10000 - 10999 ? ) that we promise
> will never be given to an upstream LSM. We wouldn't make any guarantees
> about conflicts otherwise. These could be used by LSMs before they are
> accepted upstream or by LSMs that don't have upstream aspirations. I
> seriously doubt that anyone using such an LSM is going to be mixing
> multiple such LSMs without being capable of managing ID conflicts.

Not a crazy idea.  I had debated something similar, a reserved
"private use" or "experimentation" range; there is definitely
precedence for that in other areas, e.g. network protocols.  What held
me back is that invariably folks will want to create long-term
persistent registrations against this space for their out-of-tree LSMs
which would require some sort of unofficial, adhoc registration
authority which starts to get a bit silly in my opinion (the
registration authority for the Linux kernel API is the upstream Linux
kernel community).

Temporary assignments while a LSM is undergoing the review-revision
cycle on its way to being merged is something different and if we need
a couple of reserved numbers for that (one or two MAX) we can consider
that, but I don't expect this to be a major problem in practice.  LSMs
that are in this transient pre-merge state shouldn't be used for
production purposes and thus a LSM ID change on merging shouldn't be a
problem.

-- 
paul-moore.com

Re: ANN: new LSM guidelines

[Paul Moore]

On Tue, Sep 12, 2023 at 3:00 PM Paul Moore <paul@paul-moore.com> wrote:
> On Tue, Sep 12, 2023 at 2:40 PM Casey Schaufler <casey@schaufler-ca.com> wrote:
> > On 9/12/2023 11:08 AM, Paul Moore wrote:
> > >
> > > Once again, we've already discussed this many, many times: out-of-tree
> > > LSMs are not the priority and that is not going to change.  One
> > > corollary of this is that we are not going to assign LSM IDs to LSMs
> > > that remain out-of-tree as this would negatively impact the LSM layer
> > > by cluttering/depleting the LSM ID space.  LSMs that are working
> > > towards integration with the upstream Linux kernel can self-assign a
> > > temporary LSM ID which will be finalized upon merging in the LSM tree.
> > > Based on all of the arguments you have already submitted - and let us
> > > be very clear: you are the only one speaking out against this - I see
> > > no reason to change this policy.
> >
> > I won't say this is a great idea, or that I endorse it, but we could
> > allocate a range of LSM ID values ( 10000 - 10999 ? ) that we promise
> > will never be given to an upstream LSM. We wouldn't make any guarantees
> > about conflicts otherwise. These could be used by LSMs before they are
> > accepted upstream or by LSMs that don't have upstream aspirations. I
> > seriously doubt that anyone using such an LSM is going to be mixing
> > multiple such LSMs without being capable of managing ID conflicts.
>
> Not a crazy idea.  I had debated something similar, a reserved
> "private use" or "experimentation" range; there is definitely
> precedence for that in other areas, e.g. network protocols.  What held
> me back is that invariably folks will want to create long-term
> persistent registrations against this space for their out-of-tree LSMs
> which would require some sort of unofficial, adhoc registration
> authority which starts to get a bit silly in my opinion (the
> registration authority for the Linux kernel API is the upstream Linux
> kernel community).
>
> Temporary assignments while a LSM is undergoing the review-revision
> cycle on its way to being merged is something different and if we need
> a couple of reserved numbers for that (one or two MAX) we can consider
> that, but I don't expect this to be a major problem in practice.  LSMs
> that are in this transient pre-merge state shouldn't be used for
> production purposes and thus a LSM ID change on merging shouldn't be a
> problem.

Just to avoid any confusion on this, a reserved range at this point in
time is currently a NACK from my perspective.  I am open to consider
reserving one, maybe two, ID numbers in the future for in-development
LSMs if we start having problems, but I will need to see persistent
problems first.

-- 
paul-moore.com

Re: ANN: new LSM guidelines

[Tetsuo Handa]

On 9/12/2023 11:08 AM, Paul Moore wrote:
> Once again, we've already discussed this many, many times: out-of-tree
> LSMs are not the priority and that is not going to change.  One
> corollary of this is that we are not going to assign LSM IDs to LSMs
> that remain out-of-tree as this would negatively impact the LSM layer
> by cluttering/depleting the LSM ID space.  LSMs that are working
> towards integration with the upstream Linux kernel can self-assign a
> temporary LSM ID which will be finalized upon merging in the LSM tree.
> Based on all of the arguments you have already submitted - and let us
> be very clear: you are the only one speaking out against this - I see
> no reason to change this policy.

The sane and the better usage of LSM ID is to register any publicly available
LSMs. If LSM ID serves as an index for what LSMs are available in the world,
by maintaining "the LSM module name, the LSM ID value, short description about
that LSM module, the public git repository or web site for more information
about that LSM module" pairs, people can easily find what LSMs could be used
for their purpose, and developers can avoid re-inventing similar LSM modules
which are already available somewhere in the world (and optionally helps
avoiding module name collisions with any publicly available LSMs).

If you worry about cluttering/depleting the LSM ID space, don't assign
64 bits for LSM ID; the LSM community won't accept 100+ LSMs for in-tree.

+/**
+ * struct lsm_id - Identify a Linux Security Module.
+ * @lsm: name of the LSM, must be approved by the LSM maintainers
+ * @id: LSM ID number from uapi/linux/lsm.h
+ *
+ * Contains the information that identifies the LSM.
+ */
+struct lsm_id {
+	const char	*name;
+	u64		id;
+};

Developers will more likely to abuse LSM ID (as if randomly generated GUID, or
something like 0xdeadbeef) if the LSM community does not allow out-of-tree
LSM modules to have a persistent registration. Once some value is assigned and
published via a publicly available git repository by the LSM module author,
the merit of "LSM: Identify modules by more than name" will be lost.

> As discussed many times prior, I consider in-tree, upstreamed LSMs my
> priority when it comes to decision making.  LSMs which are under
> development and are working to be merged come next, and LSMs which
> have decided to remain out-of-tree remain last.  I do not
> intentionally plan to make life difficult for the out-of-tree LSMs,
> but if that happens as a result of design decisions intended to
> benefit in-tree LSMs that is acceptable as far as I am concerned.  You
> are free to disagree, but I believe the policy I've described here is
> consistent with the bulk of the other kernel subsystems and I have no
> plans to change this policy.

I don't care if out-of-tree code encounters build failures like
https://sourceware.org/bugzilla/show_bug.cgi?id=30831 due to changing
in-kernel APIs. That's what remaining out-of-tree means. But they have
the rights/freedom to fix and load and run their code using their resources.

In-tree Linux kernel developers do not prevent out-of-tree Linux kernel
developers from loading and running their out-of-tree code. I absolutely
resist if out-of-tree code encounters loss of ability to load and run
that code (e.g. sys_init_module() prevents out-of-tree modules from
loading because your priority of out-of-tree modules is the lowest).

Although LKM-based LSM modules are not currently supported, people have
the rights/freedom to load and run out-of-tree LSM modules by rebuilding
their kernels.

Those who develop a kernel module have rights/freedom to give any name.
But as a whole, developers try to avoid identifier collisions.

You are intentionally making life difficult for the out-of-tree LSMs, by
requiring an LSM ID (and facilitating LSM ID collisions). No matter how
priority of out-of-tree LSMs is low for you, what you are about to merge
goes against the "developers try to avoid identifier collisions" effort.

Introducing a numeric identifier is a good opportunity for permanently
eliminating possibility of identifier collisions. But current usage of this
numeric identifier is designed for facilitating possibility of identifier
collisions.

Re: ANN: new LSM guidelines

[Tetsuo Handa]

On 2023/09/13 4:00, Paul Moore wrote:
> On Tue, Sep 12, 2023 at 2:40 PM Casey Schaufler <casey@schaufler-ca.com> wrote:
>> On 9/12/2023 11:08 AM, Paul Moore wrote:
>>>
>>> Once again, we've already discussed this many, many times: out-of-tree
>>> LSMs are not the priority and that is not going to change.  One
>>> corollary of this is that we are not going to assign LSM IDs to LSMs
>>> that remain out-of-tree as this would negatively impact the LSM layer
>>> by cluttering/depleting the LSM ID space.

Like Kees Cook said, we don't need to worry about depleting the LSM ID space
because lsm_id::id is a u64. We only need to worry about cluttering/conflicting
the values.

>>>                                            LSMs that are working
>>> towards integration with the upstream Linux kernel can self-assign a
>>> temporary LSM ID which will be finalized upon merging in the LSM tree.

A review might take years (like we did with the pathname based access control
in the past). What userspace would want to use of long-term non-persistent
registrations? At the stage of publishing an LSM (and userspace tools which
make use of LSM ID value), the LSM ID value should be long-term persistent
registrations. Recompiling userspace tools every time is no good.

>>> Based on all of the arguments you have already submitted - and let us
>>> be very clear: you are the only one speaking out against this - I see
>>> no reason to change this policy.
>>
>> I won't say this is a great idea, or that I endorse it, but we could
>> allocate a range of LSM ID values ( 10000 - 10999 ? ) that we promise
>> will never be given to an upstream LSM. We wouldn't make any guarantees
>> about conflicts otherwise. These could be used by LSMs before they are
>> accepted upstream or by LSMs that don't have upstream aspirations. I
>> seriously doubt that anyone using such an LSM is going to be mixing
>> multiple such LSMs without being capable of managing ID conflicts.
> 
> Not a crazy idea.  I had debated something similar, a reserved
> "private use" or "experimentation" range; there is definitely
> precedence for that in other areas, e.g. network protocols.  What held
> me back is that invariably folks will want to create long-term
> persistent registrations against this space for their out-of-tree LSMs
> which would require some sort of unofficial, adhoc registration
> authority which starts to get a bit silly in my opinion (the
> registration authority for the Linux kernel API is the upstream Linux
> kernel community).

Not silly at all. I do want to create long-term persistent registrations
against this space for any publicly available LSMs.

The sane and the better usage of LSM ID is to register any publicly available
LSMs. If LSM ID serves as an index for what LSMs are available in the world,
by maintaining "the LSM module name, the LSM ID value, short description about
that LSM module, the public git repository or web site for more information
about that LSM module" pairs, people can easily find what LSMs could be used
for their purpose, and developers can avoid re-inventing similar LSM modules
which are already available somewhere in the world (and optionally helps
avoiding module name collisions with any publicly available LSMs).

> 
> Temporary assignments while a LSM is undergoing the review-revision
> cycle on its way to being merged is something different and if we need
> a couple of reserved numbers for that (one or two MAX) we can consider
> that, but I don't expect this to be a major problem in practice.  LSMs
> that are in this transient pre-merge state shouldn't be used for
> production purposes and thus a LSM ID change on merging shouldn't be a
> problem.

It is possible that more than 3 LSMs concurrently get under the review;
reserving 2 at most can deplete the reserved LSM ID space.

No userspace tools want to recompile due to unstable LSM ID values.
Temporary assignments is no good.

Re: ANN: new LSM guidelines

[Kees Cook]

On Mon, Sep 25, 2023 at 09:55:47AM +0900, Tetsuo Handa wrote:
> On 2023/09/13 4:00, Paul Moore wrote:
> > On Tue, Sep 12, 2023 at 2:40 PM Casey Schaufler <casey@schaufler-ca.com> wrote:
> >> On 9/12/2023 11:08 AM, Paul Moore wrote:
> >>>
> >>> Once again, we've already discussed this many, many times: out-of-tree
> >>> LSMs are not the priority and that is not going to change.  One
> >>> corollary of this is that we are not going to assign LSM IDs to LSMs
> >>> that remain out-of-tree as this would negatively impact the LSM layer
> >>> by cluttering/depleting the LSM ID space.
> 
> Like Kees Cook said, we don't need to worry about depleting the LSM ID space
> because lsm_id::id is a u64. We only need to worry about cluttering/conflicting
> the values.

Right, this will go one of two ways:

1) author: "Hello, here is a new LSM I'd like to upstream, here it is. I assigned
            it the next LSM ID."
   maintainer(s): "Okay, sounds good. *review*"

2) author: "Hello, here is an LSM that has been in active use at $Place,
            and we have $Xxx many userspace applications that we cannot easily
            rebuild. We used LSM ID $Value that is far away from the sequential
            list of LSM IDs, and we'd really prefer to keep that assignment."
  maintainer(s): "Okay, sounds good. *review*"

No problems detected.

-Kees

-- 
Kees Cook

Re: ANN: new LSM guidelines

[Tetsuo Handa]

On 2023/09/25 10:32, Kees Cook wrote:
> On Mon, Sep 25, 2023 at 09:55:47AM +0900, Tetsuo Handa wrote:
>> On 2023/09/13 4:00, Paul Moore wrote:
>>> On Tue, Sep 12, 2023 at 2:40 PM Casey Schaufler <casey@schaufler-ca.com> wrote:
>>>> On 9/12/2023 11:08 AM, Paul Moore wrote:
>>>>>
>>>>> Once again, we've already discussed this many, many times: out-of-tree
>>>>> LSMs are not the priority and that is not going to change.  One
>>>>> corollary of this is that we are not going to assign LSM IDs to LSMs
>>>>> that remain out-of-tree as this would negatively impact the LSM layer
>>>>> by cluttering/depleting the LSM ID space.
>>
>> Like Kees Cook said, we don't need to worry about depleting the LSM ID space
>> because lsm_id::id is a u64. We only need to worry about cluttering/conflicting
>> the values.
> 
> Right, this will go one of two ways:
> 
> 1) author: "Hello, here is a new LSM I'd like to upstream, here it is. I assigned
>             it the next LSM ID."
>    maintainer(s): "Okay, sounds good. *review*"
> 
> 2) author: "Hello, here is an LSM that has been in active use at $Place,
>             and we have $Xxx many userspace applications that we cannot easily
>             rebuild. We used LSM ID $Value that is far away from the sequential
>             list of LSM IDs, and we'd really prefer to keep that assignment."
>   maintainer(s): "Okay, sounds good. *review*"
> 
> No problems detected.

No problem if what you wrote above is the policy. What is important is that the assigned
LSM ID value remains available for that LSM. "Okay, sounds good." has to be the only
requirement for assigning long-term persistent registrations. Whether that LSM succeeds
to become in-tree must be irrelevant for assigning permanently available LSM ID value.

It is not clear whether the proposed LSM ID value is added to include/uapi/linux/lsm.h file
of the upstream Linux kernel (it is required for avoid cluttering/conflicting) before
the LSM module which wants to use that LSM ID value succeeds to become in-tree.

But if LSM ID serves as an index for what LSMs are available in the world,
by maintaining "the LSM module name, the LSM ID value, short description about
that LSM module, the public git repository or web site for more information
about that LSM module" pairs (e.g. somewhere in the LSM community's Wiki rather than
in include/uapi/linux/lsm.h ), people can easily find what LSMs could be used
for their purpose, and developers can avoid re-inventing similar LSM modules
which are already available somewhere in the world.

That's what I said

  Since the LSM community cannot accept all of proposed LSMs due to limited resources,
  the LSM community is responsible for allowing whatever proposed LSMs (effectively any
  publicly available LSMs) to live as out-of-tree LSMs, by approving the LSM name and
  assigning a permanent LSM ID number.

in https://lkml.kernel.org/r/94743c22-bc76-e741-e577-3e0845423f69@I-love.SAKURA.ne.jp .

Casey and Paul, do you agree to change your policy for assigning LSM ID ?

Re: ANN: new LSM guidelines

[Paul Moore]

On Mon, Sep 25, 2023 at 12:32 AM Tetsuo Handa
<penguin-kernel@i-love.sakura.ne.jp> wrote:
>
> Casey and Paul, do you agree to change your policy for assigning LSM ID ?

No LSM ID value is guaranteed until it is present in a tagged release
from Linus' tree, and once a LSM ID is present in a tagged release
from Linus' tree it should not change.  That's *the* policy.

-- 
paul-moore.com