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