diff options
author | Konstantin Ryabitsev <konstantin@linuxfoundation.org> | 2018-02-06 11:51:19 -0500 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2018-02-06 16:31:56 -0700 |
commit | 78ed78451963d1a4282bcda92059fdf2a7821401 (patch) | |
tree | 5a817e67fcb87bb7944e47912e9f208735a40644 /Documentation/process | |
parent | 54e36a2dc554685463af54b4ac97a5ec022bd09c (diff) | |
download | linux-78ed78451963d1a4282bcda92059fdf2a7821401.tar.gz linux-78ed78451963d1a4282bcda92059fdf2a7821401.tar.bz2 linux-78ed78451963d1a4282bcda92059fdf2a7821401.zip |
Documentation/process: tweak pgp maintainer guide
Based on the feedback provided:
- Uniformly use lowercase k in "Linux kernel"
- Give a one-sentence explanation of what subkeys are
- Explain what signed commits might be useful for even if upstream
developers do not use them for much of anything
- Admonish to set up gpg-agent if signed commits are turned on in
git config
- Fix a typo reported by Luc Van Oostenryck
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/process')
-rw-r--r-- | Documentation/process/maintainer-pgp-guide.rst | 50 |
1 files changed, 34 insertions, 16 deletions
diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 28674eb42b95..b453561a7148 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -18,10 +18,10 @@ The role of PGP in Linux Kernel development =========================================== PGP helps ensure the integrity of the code that is produced by the Linux -Kernel development community and, to a lesser degree, establish trusted +kernel development community and, to a lesser degree, establish trusted communication channels between developers via PGP-signed email exchange. -The Linux Kernel source code is available in two main formats: +The Linux kernel source code is available in two main formats: - Distributed source repositories (git) - Periodic release snapshots (tarballs) @@ -53,7 +53,7 @@ want to make sure that by placing trust into developers we do not simply shift the blame for potential future security incidents to someone else. The goal is to provide a set of guidelines developers can use to create a secure working environment and safeguard the PGP keys used to -establish the integrity of the Linux Kernel itself. +establish the integrity of the Linux kernel itself. .. _pgp_tools: @@ -139,7 +139,7 @@ Protect your master PGP key =========================== This guide assumes that you already have a PGP key that you use for Linux -Kernel development purposes. If you do not yet have one, please see the +kernel development purposes. If you do not yet have one, please see the "`Protecting Code Integrity`_" document mentioned earlier for guidance on how to create a new one. @@ -149,7 +149,9 @@ You should also make a new key if your current one is weaker than 2048 bits Master key vs. Subkeys ---------------------- -It is important to understand the following: +Subkeys are fully independent PGP keypairs that are tied to the "master" +key using certifying key signatures (certificates). It is important to +understand the following: 1. There are no technical differences between the "master key" and "subkeys." 2. At creation time, we assign functional limitations to each key by @@ -742,17 +744,29 @@ How to work with signed commits ------------------------------- It is easy to create signed commits, but it is much more difficult to -use them in Linux Kernel development, since it relies on patches sent to +use them in Linux kernel development, since it relies on patches sent to the mailing list, and this workflow does not preserve PGP commit -signatures. - -If you have your working git tree publicly available at some git hosting -service (kernel.org, infradead.org, ozlabs.org, or others), then the -recommendation is that you sign all your git commits even if upstream -developers do not directly benefit from this practice. Should there ever -be a need to perform code forensics or track code provenance, even -externally maintained trees carrying PGP commit signatures will be -extremely valuable for such purposes. +signatures. Furthermore, when rebasing your repository to match +upstream, even your own PGP commit signatures will end up discarded. For +this reason, most kernel developers don't bother signing their commits +and will ignore signed commits in any external repositories that they +rely upon in their work. + +However, if you have your working git tree publicly available at some +git hosting service (kernel.org, infradead.org, ozlabs.org, or others), +then the recommendation is that you sign all your git commits even if +upstream developers do not directly benefit from this practice. + +We recommend this for the following reasons: + +1. Should there ever be a need to perform code forensics or track code + provenance, even externally maintained trees carrying PGP commit + signatures will be valuable for such purposes. +2. If you ever need to re-clone your local repository (for example, + after a disk failure), this lets you easily verify the repository + integrity before resuming your work. +3. If someone needs to cherry-pick your commits, this allows them to + quickly verify their integrity before applying them. Creating signed commits ~~~~~~~~~~~~~~~~~~~~~~~ @@ -770,6 +784,10 @@ You can tell git to always sign commits:: git config --global commit.gpgSign true +.. note:: + + Make sure you configure ``gpg-agent`` before you turn this on. + .. _verify_identities: How to verify kernel developer identities @@ -882,7 +900,7 @@ Locate the ID of the master key in the output, in our example ``C94035C21B4F2AEB``. Now display the key of Linus Torvalds that you have on your keyring:: - $ git --list-key torvalds@kernel.org + $ gpg --list-key torvalds@kernel.org pub rsa2048 2011-09-20 [SC] ABAF11C65A2970B130ABE3C479BE3E4300411886 uid [ unknown] Linus Torvalds <torvalds@kernel.org> |