[RFC] LSM deprecation / removal policies

[Paul Moore]

On Fri, May 2, 2025 at 4:01 PM Paul Moore <paul at paul-moore.com> wrote:
>
> Hello all,
>
> We've worked in the past to document some of our policies and
> guidelines, the result can be seen at the link below (also listed in
> MAINTAINERS):
>
> - https://github.com/LinuxSecurityModule/kernel/blob/main/README.md
>
> However, one of the areas that has been missing from this guidance,
> are policies on deprecating and removing LSM hooks as well as LSMs
> themselves ...

Here are some slight revisions to the earlier draft text based on
feedback.  I'm also including a section on LSM hook modifications as
suggested by Casey.  As usual, feedback is encouraged.

## Modifying LSM Hooks

Changing the parameters, return value, or calling locations of an existing LSM
hook can impact individual in-kernel LSMs as well as ongoing development
efforts that have not yet landed in the upstream Linux kernel.  Developers that
wish to change a LSM hook should work with existing in-kernel LSMs, related
development efforts, and any associated subsystems to ensure that the
individual LSMs are properly transitioned to the new hook.  Any existing kernel
selftests should also be updated as necessary to ensure they continue to
work properly.

Due to the potential for cross LSM and cross subsystem conflicts when changing
LSM hooks, it is possible that patches which modify LSM hooks may be staged, or
delayed, for a period of time to allow for a more manageable transition.

## Removing LSM Hooks

If a LSM hook is no longer used by any in-kernel LSMs, there is no ongoing work
in progress involving the hook, and no expectation of future work that will use
the hook, the LSM community may consider removal of the LSM hook.  The decision
to ultimately remove the LSM hook should balance ongoing maintenance and
performance concerns with the social challenges of reintroducing the hook if
it is needed at a later date.

In the case where a Linux kernel selftest has been created to verify the proper
behavior of a LSM hook, the presence of the selftest alone should not prevent
removal of the LSM hook.

## Removing LSMs

If a LSM has not been actively maintained for a period of time such that it is
becoming a maintenance burden for other developers, or there are serious
concerns about the LSM's ability to deliver on its stated purpose, the LSM
community may consider deprecating and ultimately removing the LSM from the
Linux kernel.  However, before considering deprecation, the LSM community
should make every reasonable effort to find a suitable maintainer for the LSM
while also surveying the major Linux distributions to better understand the
impact a deprecation would have on the downstream distro/user experience.  If
deprecation remains the only viable option, the following process should be
used as a starting point for deprecating the LSM:

* The LSM's Kconfig description should indicate that the LSM is being
deprecated and the LSM should not be built into the kernel by default.

* Entries in Documentation/API/obsolete should be created for any user visible
interfaces associated with the LSM.

* When the LSM is enabled at boot or runtime, it should display a message on
the console that it is now deprecated and will be removed at some point in the
future.  While the message should be displayed without delaying the boot at
first, after one or two kernel releases it may be helpful to add a small,
e.g. five second, delay after displaying the message to draw attention to the
deprecation notice.  The delay can be increased in successive kernel releases
until it reaches a level than any reasonable user wouldn't be able to ignore,
e.g. 30 seconds.

* Finally, after an additional two to three kernel releases, after any
deadlines listed in the Documentation/API/obsolete entries, and once the LSM
community is satisfied that all users running modern kernels have migrated away
from the LSM, the LSM can be removed from the Linux kernel and any entries in
Documentation/API/obsolete can be moved to Documentation/API/removed.

It is important to note that the steps above are intended as basic guidance for
a generic LSM; it is likely that changes, including additional actions, will be
needed for individual LSMs based on their design, implementation, and
downstream usage.  The LSM community should take the process above as input,
but ultimately the process should be tailored to the LSM being deprecated and
the associated environment.

-- 
paul-moore.com