Documentation/process: kernel maintainer PGP guide
Subsystems (2)
PATCH 1/1 Documentation/process: kernel maintainer PGP guide
This guide is an adapted version of the more general "Protecting Code Integrity" guide written and maintained by The Linux Foundation IT for use with open-source projects. It provides the oft-lacking guidance on the following topics:
- how to properly protect one's PGP keys to minimize the risks of them being stolen and used maliciously to impersonate a kernel developer
- how to configure Git to properly use GnuPG
- when and how to use PGP with Git
- how to verify fellow Linux Kernel developer identities
I believe this document should live with the rest of the documentation describing proper processes one should follow when participating in kernel development. Placing it in a wiki on some place like kernel.org would be insufficient for a number of reasons -- primarily, because only a relatively small subset of maintainers have accounts on kernel.org, but also because even those who do rarely remember that such wiki exists. Keeping it with the rest of in-kernel docs should hopefully give it more visibility, but also help keep it up-to-date as tools and processes evolve.
--- Documentation/process/index.rst | 1 + Documentation/process/maintainer-pgp-guide.rst | 899 +++++++++++++++++++++++++ 2 files changed, 900 insertions(+) create mode 100644 Documentation/process/maintainer-pgp-guide.rst
Documentation/process/index.rst +1 -0
@@ -24,6 +24,7 @@ Below are the essential guides that every developer should read. development-process submitting-patches coding-style + maintainer-pgp-guide email-clients kernel-enforcement-statement kernel-driver-statement
Documentation/process/maintainer-pgp-guide.rst new file +899 -0
899 lines not on this page · raw message
Signature · 1 line
2.14.3
Quoted 11 lines · Konstantin Ryabitsev
This guide is an adapted version of the more general "Protecting Code Integrity" guide written and maintained by The Linux Foundation IT for use with open-source projects. It provides the oft-lacking guidance on the following topics:
- how to properly protect one's PGP keys to minimize the risks of them being stolen and used maliciously to impersonate a kernel developer
- how to configure Git to properly use GnuPG
- when and how to use PGP with Git
- how to verify fellow Linux Kernel developer identities
Quoted 9 lines
I believe this document should live with the rest of the documentation describing proper processes one should follow when participating in kernel development. Placing it in a wiki on some place like kernel.org would be insufficient for a number of reasons -- primarily, because only a relatively small subset of maintainers have accounts on kernel.org, but also because even those who do rarely remember that such wiki exists. Keeping it with the rest of in-kernel docs should hopefully give it more visibility, but also help keep it up-to-date as tools and processes evolve.
FWIW, agreed on having this with the kernel documentation.
I can't say I reviewed it, but glancing through I didn't spot any errors either. Lots of good stuff.
Just one nit, I think it would be better to move the Maintainer: bit from the end near the top as a reStructuredText field list. See 'git grep :Author:' under Documentation for examples. Could even add a MAINTAINERS entry to improve your chances of being Cc'd on changes.
BR,
Jani.
Signature · 1 line
Jani Nikula, Intel Open Source Technology Center
Quoted 4 lines · Jani Nikula
Just one nit, I think it would be better to move the Maintainer: bit from the end near the top as a reStructuredText field list. See 'git grep :Author:' under Documentation for examples. Could even add a
MAINTAINERSentry to improve your chances of being Cc'd on changes.
Thank you for the feedback -- I've submitted a v2 with that change (and a few bugfixes that resulted from md->rst conversion).
I'm not sure one doc file is good enough reason to be put into MAINTAINERS, even if the perk is that I get pre-approved for a kernel.org account. ;)
Best regards,
-K
PATCH v2 1/1 Documentation/process: kernel maintainer PGP guide
In reply to Konstantin RyabitsevThis guide is an adapted version of the more general "Protecting Code Integrity" guide written and maintained by The Linux Foundation IT for use with open-source projects. It provides the oft-lacking guidance on the following topics:
- how to properly protect one's PGP keys to minimize the risks of them being stolen and used maliciously to impersonate a kernel developer
- how to configure Git to properly use GnuPG
- when and how to use PGP with Git
- how to verify fellow Linux Kernel developer identities
I believe this document should live with the rest of the documentation describing proper processes one should follow when participating in kernel development. Placing it in a wiki on some place like kernel.org would be insufficient for a number of reasons -- primarily, because only a relatively small subset of maintainers have accounts on kernel.org, but also because even those who do rarely remember that such wiki exists. Keeping it with the rest of in-kernel docs should hopefully give it more visibility, but also help keep it up-to-date as tools and processes evolve.
---Documentation/process/index.rst | 1 +Documentation/process/maintainer-pgp-guide.rst | 911 +++++++++++++++++++++++++
2 files changed, 912 insertions(+)
create mode 100644 Documentation/process/maintainer-pgp-guide.rst
Documentation/process/index.rst +1 -0
@@ -24,6 +24,7 @@ Below are the essential guides that every developer should read. development-process submitting-patches coding-style + maintainer-pgp-guide email-clients kernel-enforcement-statement kernel-driver-statement
Documentation/process/maintainer-pgp-guide.rst new file +911 -0
911 lines not on this page · raw message
Signature · 1 line
2.13.6
Jonathan Corbet
maintainerQuoted 21 lines · On Thu, 1 Feb 2018 09:42:33 -0500 Konstantin Ryabitsev…
This guide is an adapted version of the more general "Protecting Code Integrity" guide written and maintained by The Linux Foundation IT for use with open-source projects. It provides the oft-lacking guidance on the following topics:
- how to properly protect one's PGP keys to minimize the risks of them being stolen and used maliciously to impersonate a kernel developer
- how to configure Git to properly use GnuPG
- when and how to use PGP with Git
- how to verify fellow Linux Kernel developer identitiesI believe this document should live with the rest of the documentation describing proper processes one should follow when participating in kernel development. Placing it in a wiki on some place like kernel.org would be insufficient for a number of reasons -- primarily, because only a relatively small subset of maintainers have accounts on kernel.org, but also because even those who do rarely remember that such wiki exists. Keeping it with the rest of in-kernel docs should hopefully give it more visibility, but also help keep it up-to-date as tools and processes evolve.
Quoted 1 line
Signed-off-by Konstantin Ryabitsev <[email protected]>
OK, I've been through all of this. Naturally, I have a few quibbles:
- Capitalizing "Kernel" bugs me. Obviously not a big deal.
- The "master keys vs. subkeys" section is nice, but it's missing one thing, IMO: a sentence saying what a subkey *is* in the first place.
- We don't normally endorse commercial products in kernel docs. OTOH, I don't see any other way for people to know which keycards they should get. This section is sure to go obsolete as products come and go, though - you're on the hook for maintaining it :)
- The suggestion to sign individual commits is, as I understand it, controversial (Linus doesn't agree with it) and is 100% contrary to current practice. Are there any signed commits in the kernel repo now? Given that, I'm a bit nervous about putting commit-signing forward as standard practice.
- I'm not quite sure what the "finding paths to Linus" link is supposed to do for the reader.
Anyway, these are all quibbles, and I think the documentation is definitely improved by having this, so I'm going ahead and applying it. It may be worth considering some tweaks for the issues above, though, as time allows.
Thanks,
jon
Quoted 1 line · Jonathan Corbet
- Capitalizing "Kernel" bugs me. Obviously not a big deal.
Noted.
Quoted 2 lines
- The "master keys vs. subkeys" section is nice, but it's missing one thing, IMO: a sentence saying what a subkey *is* in the first place.
I'll work that in for subsequent changes
Quoted 4 lines
- We don't normally endorse commercial products in kernel docs. OTOH, I don't see any other way for people to know which keycards they should get. This section is sure to go obsolete as products come and go, though - you're on the hook for maintaining it :)
If we wanted to avoid this, one way would be to refer people to the "Protecting Code Integrity" guide for smartcard recommendations, though it uses slightly different criteria (Mac users suddenly become important).
Quoted 5 lines
- The suggestion to sign individual commits is, as I understand it, controversial (Linus doesn't agree with it) and is 100% contrary to current practice. Are there any signed commits in the kernel repo now? Given that, I'm a bit nervous about putting commit-signing forward as standard practice.
Linus isn't against it, he just points out that it serves no purpose -- the only thing that needs to be signed is the tip of each branch. Since each commit contains the parent checksum of the previous commit, that provides a backward chain for the rest of the branch, and that is sufficient to give cryptographic assurances for the remainder of all repo objects without needing to separately sign each of the commits leading to the tip.
And, of course, all those PGP signatures are lost when commits are converted to patches, so in his view the whole thing is pretty pointless. All he needs is signatures on tags that he pulls directly from maintainers.
However, there is currently no way to tell git "sign just the tip of the branch" -- I'm not even sure how it would work, because git has no knowledge of your intentions. A tip may only remain a tip for a couple of seconds before you add more commits. And should signatures be removed from previous commit tips, or just left there? And if so, why not just sign every commit anyway, since it doesn't *hurt* anything, especially if gpg-agent is properly configured -- it's just a background operation that doesn't even slow down your work if you use ECC subkeys.
Anyway, I feel it should remain as a weak recommendation just in case someone has to prove at any point their authorship of a specific commit, but I'm happy to change it, remove it, or add more detail explaining the above if you think the section should be expanded. I can talk about it for pages on end, I was just trying to be succinct. ;)
Quoted 2 lines
- I'm not quite sure what the "finding paths to Linus" link is supposed to do for the reader.
The idea is that it's a weak substitute for a web of trust. If someone isn't keeping one going, then using the PGP Pathfinder will give them at least *some* indication about whether the key is trusted or not. I do agree that if you don't already know what you're looking at, the output is fairly opaque. It's long been my desire to put together a kernel.org-specific tool where you can check similar data using pretty graphs (e.g. https://mricon.com/misc/korg-wot-graph.png), but I haven't had a chance yet.
Quoted 4 lines
Anyway, these are all quibbles, and I think the documentation is definitely improved by having this, so I'm going ahead and applying it. It may be worth considering some tweaks for the issues above, though, as time allows.
Will do, thank you for the feedback!
-K
Documentation/process/maintainer-pgp-guide.rst line 885
Quoted 2 lines · Konstantin Ryabitsev
Documentation/process/maintainer-pgp-guide.rst new file +2
-0+ + $ git --list-key [email protected]
Small typo here: you meant 'gpg --list-key' instead of 'git ...'
Regards,
-- Luc Van Oostenryck