diff options
Diffstat (limited to 'Documentation/process/maintainer-pgp-guide.rst')
| -rw-r--r-- | Documentation/process/maintainer-pgp-guide.rst | 502 |
1 files changed, 225 insertions, 277 deletions
diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 29e7d7b1cd44..b6919bf606c3 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -49,7 +49,7 @@ hosting infrastructure, regardless of how good the security practices for the latter may be. The above guiding principle is the reason why this guide is needed. We -want to make sure that by placing trust into developers we do not simply +want to make sure that by placing trust into developers we do not merely 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 @@ -60,36 +60,18 @@ establish the integrity of the Linux kernel itself. PGP tools ========= -Use GnuPG v2 ------------- +Use GnuPG 2.4 or later +---------------------- Your distro should already have GnuPG installed by default, you just -need to verify that you are using version 2.x and not the legacy 1.4 -release -- many distributions still package both, with the default -``gpg`` command invoking GnuPG v.1. To check, run:: +need to verify that you are using a reasonably recent version of it. +To check, run:: $ gpg --version | head -n1 -If you see ``gpg (GnuPG) 1.4.x``, then you are using GnuPG v.1. Try the -``gpg2`` command (if you don't have it, you may need to install the -gnupg2 package):: - - $ gpg2 --version | head -n1 - -If you see ``gpg (GnuPG) 2.x.x``, then you are good to go. This guide -will assume you have the version 2.2 of GnuPG (or later). If you are -using version 2.0 of GnuPG, then some of the commands in this guide will -not work, and you should consider installing the latest 2.2 version of -GnuPG. Versions of gnupg-2.1.11 and later should be compatible for the -purposes of this guide as well. - -If you have both ``gpg`` and ``gpg2`` commands, you should make sure you -are always using GnuPG v2, not the legacy version. You can enforce this -by setting the appropriate alias:: - - $ alias gpg=gpg2 - -You can put that in your ``.bashrc`` to make sure it's always the case. +If you have version 2.4 or above, then you are good to go. If you have +an earlier version, then you are using a release of GnuPG that is no +longer maintained and some commands from this guide may not work. Configure gpg-agent options ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -121,57 +103,56 @@ edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values:: to remove anything you had in place for older versions of GnuPG, as it may not be doing the right thing any more. -Set up a refresh cronjob -~~~~~~~~~~~~~~~~~~~~~~~~ - -You will need to regularly refresh your keyring in order to get the -latest changes on other people's public keys, which is best done with a -daily cronjob:: +.. _protect_your_key: - @daily /usr/bin/gpg2 --refresh >/dev/null 2>&1 - -Check the full path to your ``gpg`` or ``gpg2`` command and use the -``gpg2`` command if regular ``gpg`` for you is the legacy GnuPG v.1. - -.. _master_key: - -Protect your master PGP key -=========================== +Protect your 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 "`Protecting Code Integrity`_" document mentioned earlier for guidance on how to create a new one. -You should also make a new key if your current one is weaker than 2048 bits -(RSA). - -Master key vs. Subkeys ----------------------- - -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 - giving it specific capabilities. -3. A PGP key can have 4 capabilities: - - - **[S]** key can be used for signing - - **[E]** key can be used for encryption - - **[A]** key can be used for authentication - - **[C]** key can be used for certifying other keys - -4. A single key may have multiple capabilities. -5. A subkey is fully independent from the master key. A message - encrypted to a subkey cannot be decrypted with the master key. If you - lose your private subkey, it cannot be recreated from the master key - in any way. - -The key carrying the **[C]** (certify) capability is considered the -"master" key because it is the only key that can be used to indicate -relationship with other keys. Only the **[C]** key can be used to: +You should also make a new key if your current one is weaker than 2048 +bits (RSA). + +Understanding PGP Subkeys +------------------------- + +A PGP key rarely consists of a single keypair -- usually it is a +collection of independent subkeys that can be used for different +purposes based on their capabilities, assigned at their creation time. +PGP defines four capabilities that a key can have: + +- **[S]** keys can be used for signing +- **[E]** keys can be used for encryption +- **[A]** keys can be used for authentication +- **[C]** keys can be used for certifying other keys + +The key with the **[C]** capability is often called the "master" key, +but this terminology is misleading because it implies that the Certify +key can be used in place of any of other subkey on the same chain (like +a physical "master key" can be used to open locks made for other keys). +Since this is not the case, this guide will refer to it as "the Certify +key" to avoid any ambiguity. + +It is critical to fully understand the following: + +1. All subkeys are fully independent from each other. If you lose a + private subkey, it cannot be restored or recreated from any other + private key on your chain. +2. With the exception of the Certify key, there can be multiple subkeys + with identical capabilities (e.g. you can have 2 valid encryption + subkeys, 3 valid signing subkeys, but only one valid certification + subkey). All subkeys are fully independent -- a message encrypted to + one **[E]** subkey cannot be decrypted with any other **[E]** subkey + you may also have. +3. A single subkey may have multiple capabilities (e.g. your **[C]** key + can also be your **[S]** key). + +The key carrying the **[C]** (certify) capability is the only key that +can be used to indicate relationship with other keys. Only the **[C]** +key can be used to: - add or revoke other keys (subkeys) with S/E/A capabilities - add, change or revoke identities (uids) associated with the key @@ -180,20 +161,17 @@ relationship with other keys. Only the **[C]** key can be used to: By default, GnuPG creates the following when generating new keys: -- A master key carrying both Certify and Sign capabilities (**[SC]**) +- One subkey carrying both Certify and Sign capabilities (**[SC]**) - A separate subkey with the Encryption capability (**[E]**) If you used the default parameters when generating your key, then that is what you will have. You can verify by running ``gpg --list-secret-keys``, for example:: - sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23] + sec ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23] - -Any key carrying the **[C]** capability is your master key, regardless -of any other capabilities it may have assigned to it. + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] The long line under the ``sec`` entry is your key fingerprint -- whenever you see ``[fpr]`` in the examples below, that 40-character @@ -215,43 +193,20 @@ strong passphrase. To set it or change it, use:: Create a separate Signing subkey -------------------------------- -Our goal is to protect your master key by moving it to offline media, so -if you only have a combined **[SC]** key, then you should create a separate -signing subkey:: +Our goal is to protect your Certify key by moving it to offline media, +so if you only have a combined **[SC]** key, then you should create a +separate signing subkey:: $ gpg --quick-addkey [fpr] ed25519 sign -Remember to tell the keyservers about this change, so others can pull down -your new subkey:: - - $ gpg --send-key [fpr] - -.. note:: ECC support in GnuPG - - GnuPG 2.1 and later has full support for Elliptic Curve - Cryptography, with ability to combine ECC subkeys with traditional - RSA master keys. The main upside of ECC cryptography is that it is - much faster computationally and creates much smaller signatures when - compared byte for byte with 2048+ bit RSA keys. Unless you plan on - using a smartcard device that does not support ECC operations, we - recommend that you create an ECC signing subkey for your kernel - work. - - If for some reason you prefer to stay with RSA subkeys, just replace - "ed25519" with "rsa2048" in the above command. Additionally, if you - plan to use a hardware device that does not support ED25519 ECC - keys, like Nitrokey Pro or a Yubikey, then you should use - "nistp256" instead or "ed25519." - - -Back up your master key for disaster recovery ---------------------------------------------- +Back up your Certify key for disaster recovery +---------------------------------------------- The more signatures you have on your PGP key from other developers, the more reasons you have to create a backup version that lives on something other than digital media, for disaster recovery reasons. -The best way to create a printable hardcopy of your private key is by +A good way to create a printable hardcopy of your private key is by using the ``paperkey`` software written for this very purpose. See ``man paperkey`` for more details on the output format and its benefits over other solutions. Paperkey should already be packaged for most @@ -262,11 +217,11 @@ key:: $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt -Print out that file (or pipe the output straight to lpr), then take a -pen and write your passphrase on the margin of the paper. **This is -strongly recommended** because the key printout is still encrypted with -that passphrase, and if you ever change it you will not remember what it -used to be when you had created the backup -- *guaranteed*. +Print out that file, then take a pen and write your passphrase on the +margin of the paper. **This is strongly recommended** because the key +printout is still encrypted with that passphrase, and if you ever change +it you will not remember what it used to be when you had created the +backup -- *guaranteed*. Put the resulting printout and the hand-written passphrase into an envelope and store in a secure and well-protected place, preferably away from your @@ -274,12 +229,9 @@ home, such as your bank vault. .. note:: - Your printer is probably no longer a simple dumb device connected to - your parallel port, but since the output is still encrypted with - your passphrase, printing out even to "cloud-integrated" modern - printers should remain a relatively safe operation. One option is to - change the passphrase on your master key immediately after you are - done with paperkey. + The key is still encrypted with your passphrase, so printing out + even to "cloud-integrated" modern printers should remain a + relatively safe operation. Back up your whole GnuPG directory ---------------------------------- @@ -295,16 +247,17 @@ on these external copies whenever you need to use your Certify key -- such as when making changes to your own key or signing other people's keys after conferences and summits. -Start by getting a small USB "thumb" drive (preferably two!) that you -will use for backup purposes. You will need to encrypt them using LUKS --- refer to your distro's documentation on how to accomplish this. +Start by getting an external media card (preferably two!) that you will +use for backup purposes. You will need to create an encrypted partition +on this device using LUKS -- refer to your distro's documentation on how +to accomplish this. For the encryption passphrase, you can use the same one as on your -master key. +PGP key. -Once the encryption process is over, re-insert the USB drive and make -sure it gets properly mounted. Copy your entire ``.gnupg`` directory -over to the encrypted storage:: +Once the encryption process is over, re-insert your device and make sure +it gets properly mounted. Copy your entire ``.gnupg`` directory over to +the encrypted storage:: $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup @@ -313,13 +266,12 @@ You should now test to make sure everything still works:: $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr] If you don't get any errors, then you should be good to go. Unmount the -USB drive, distinctly label it so you don't blow it away next time you -need to use a random USB drive, and put in a safe place -- but not too -far away, because you'll need to use it every now and again for things -like editing identities, adding or revoking subkeys, or signing other -people's keys. +device, distinctly label it so you don't overwrite it by accident, and +put in a safe place -- but not too far away, because you'll need to use +it every now and again for things like editing identities, adding or +revoking subkeys, or signing other people's keys. -Remove the master key from your homedir +Remove the Certify key from your homedir ---------------------------------------- The files in our home directory are not as well protected as we like to @@ -334,7 +286,7 @@ think. They can be leaked or stolen via many different means: Protecting your key with a good passphrase greatly helps reduce the risk of any of the above, but passphrases can be discovered via keyloggers, shoulder-surfing, or any number of other means. For this reason, the -recommended setup is to remove your master key from your home directory +recommended setup is to remove your Certify key from your home directory and store it on offline storage. .. warning:: @@ -343,23 +295,23 @@ and store it on offline storage. your GnuPG directory in its entirety. What we are about to do will render your key useless if you do not have a usable backup! -First, identify the keygrip of your master key:: +First, identify the "keygrip" of your Certify key:: $ gpg --with-keygrip --list-key [fpr] The output will be something like this:: - pub rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + pub ed25519 2022-12-20 [SC] [expires: 2022-12-19] 000000000000000000000000AAAABBBBCCCCDDDD Keygrip = 1111000000000000000000000000000000000000 uid [ultimate] Alice Dev <adev@kernel.org> - sub rsa2048 2018-01-24 [E] [expires: 2020-01-24] + sub cv25519 2022-12-20 [E] [expires: 2022-12-19] Keygrip = 2222000000000000000000000000000000000000 - sub ed25519 2018-01-24 [S] + sub ed25519 2022-12-20 [S] Keygrip = 3333000000000000000000000000000000000000 Find the keygrip entry that is beneath the ``pub`` line (right under the -master key fingerprint). This will correspond directly to a file in your +Certify key fingerprint). This will correspond directly to a file in your ``~/.gnupg`` directory:: $ cd ~/.gnupg/private-keys-v1.d @@ -368,24 +320,24 @@ master key fingerprint). This will correspond directly to a file in your 2222000000000000000000000000000000000000.key 3333000000000000000000000000000000000000.key -All you have to do is simply remove the .key file that corresponds to -the master keygrip:: +It is sufficient to remove the .key file that corresponds to the Certify +key keygrip:: $ cd ~/.gnupg/private-keys-v1.d $ rm 1111000000000000000000000000000000000000.key Now, if you issue the ``--list-secret-keys`` command, it will show that -the master key is missing (the ``#`` indicates it is not available):: +the Certify key is missing (the ``#`` indicates it is not available):: $ gpg --list-secret-keys - sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb rsa2048 2018-01-24 [E] [expires: 2020-01-24] - ssb ed25519 2018-01-24 [S] + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb ed25519 2022-12-20 [S] You should also remove any ``secring.gpg`` files in the ``~/.gnupg`` -directory, which are left over from earlier versions of GnuPG. +directory, which may be left over from previous versions of GnuPG. If you don't have the "private-keys-v1.d" directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -404,7 +356,7 @@ file, which still contains your private keys. Move the subkeys to a dedicated crypto device ============================================= -Even though the master key is now safe from being leaked or stolen, the +Even though the Certify key is now safe from being leaked or stolen, the subkeys are still in your home directory. Anyone who manages to get their hands on those will be able to decrypt your communication or fake your signatures (if they know the passphrase). Furthermore, each time a @@ -412,7 +364,7 @@ GnuPG operation is performed, the keys are loaded into system memory and can be stolen from there by sufficiently advanced malware (think Meltdown and Spectre). -The best way to completely protect your keys is to move them to a +A good way to completely protect your keys is to move them to a specialized hardware device that is capable of smartcard operations. The benefits of smartcards @@ -423,11 +375,11 @@ private keys and performing crypto operations directly on the card itself. Because the key contents never leave the smartcard, the operating system of the computer into which you plug in the hardware device is not able to retrieve the private keys themselves. This is very -different from the encrypted USB storage device we used earlier for -backup purposes -- while that USB device is plugged in and mounted, the +different from the encrypted media storage device we used earlier for +backup purposes -- while that device is plugged in and mounted, the operating system is able to access the private key contents. -Using external encrypted USB media is not a substitute to having a +Using external encrypted media is not a substitute to having a smartcard-capable device. Available smartcard devices @@ -438,19 +390,17 @@ easiest is to get a specialized USB device that implements smartcard functionality. There are several options available: - `Nitrokey Start`_: Open hardware and Free Software, based on FSI - Japan's `Gnuk`_. One of the few available commercial devices that - support ED25519 ECC keys, but offer fewest security features (such as - resistance to tampering or some side-channel attacks). -- `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more - tamper-resistant and offers more security features. Pro 2 supports ECC - cryptography (NISTP). + Japan's `Gnuk`_. One of the cheapest options, but offers fewest + security features (such as resistance to tampering or some + side-channel attacks). +- `Nitrokey 3`_: Similar to the Nitrokey Start, but more + tamper-resistant and offers more security features and USB + form-factors. Supports ECC cryptography (ED25519 and NISTP). - `Yubikey 5`_: proprietary hardware and software, but cheaper than - Nitrokey Pro and comes available in the USB-C form that is more useful - with newer laptops. Offers additional security features such as FIDO - U2F, among others, and now finally supports ECC keys (NISTP). + Nitrokey with a similar set of features. Supports ECC cryptography + (ED25519 and NISTP). -`LWN has a good review`_ of some of the above models, as well as several -others. Your choice will depend on cost, shipping availability in your +Your choice will depend on cost, shipping availability in your geographical region, and open/proprietary hardware considerations. .. note:: @@ -459,11 +409,10 @@ geographical region, and open/proprietary hardware considerations. you `qualify for a free Nitrokey Start`_ courtesy of The Linux Foundation. -.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 -.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3 +.. _`Nitrokey Start`: https://www.nitrokey.com/products/nitrokeys +.. _`Nitrokey 3`: https://www.nitrokey.com/products/nitrokeys .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ .. _Gnuk: https://www.fsij.org/doc-gnuk/ -.. _`LWN has a good review`: https://lwn.net/Articles/736231/ .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html Configure your smartcard device @@ -496,7 +445,7 @@ the smartcard). You so rarely need to use the Admin PIN, that you will inevitably forget what it is if you do not record it. Getting back to the main card menu, you can also set other values (such -as name, sex, login data, etc), but it's not necessary and will +as name, gender, login data, etc), but it's not necessary and will additionally leak information about your smartcard should you lose it. .. note:: @@ -521,11 +470,11 @@ passphrase and the admin PIN of the card for most operations:: Secret subkeys are available. - pub rsa2048/AAAABBBBCCCCDDDD - created: 2018-01-23 expires: 2020-01-23 usage: SC + pub ed25519/AAAABBBBCCCCDDDD + created: 2022-12-20 expires: 2024-12-19 usage: SC trust: ultimate validity: ultimate - ssb rsa2048/1111222233334444 - created: 2018-01-23 expires: never usage: E + ssb cv25519/1111222233334444 + created: 2022-12-20 expires: never usage: E ssb ed25519/5555666677778888 created: 2017-12-07 expires: never usage: S [ultimate] (1). Alice Dev <adev@kernel.org> @@ -589,11 +538,11 @@ If you perform ``--list-secret-keys`` now, you will see a subtle difference in the output:: $ gpg --list-secret-keys - sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb> rsa2048 2018-01-24 [E] [expires: 2020-01-24] - ssb> ed25519 2018-01-24 [S] + ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb> ed25519 2022-12-20 [S] The ``>`` in the ``ssb>`` output indicates that the subkey is only available on the smartcard. If you go back into your secret keys @@ -627,10 +576,10 @@ Other common GnuPG operations Here is a quick reference for some common operations you'll need to do with your PGP key. -Mounting your master key offline storage -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Mounting your safe offline storage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You will need your master key for any of the operations below, so you +You will need your Certify key for any of the operations below, so you will first need to mount your backup offline storage and tell GnuPG to use it:: @@ -644,7 +593,7 @@ your regular home directory location). Extending key expiration date ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The master key has the default expiration date of 2 years from the date +The Certify key has the default expiration date of 2 years from the date of creation. This is done both for security reasons and to make obsolete keys eventually disappear from keyservers. @@ -656,7 +605,7 @@ run:: You can also use a specific date if that is easier to remember (e.g. your birthday, January 1st, or Canada Day):: - $ gpg --quick-set-expire [fpr] 2020-07-01 + $ gpg --quick-set-expire [fpr] 2038-07-01 Remember to send the updated key back to keyservers:: @@ -685,6 +634,7 @@ remote end. .. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding +.. _pgp_with_git: Using PGP with Git ================== @@ -696,9 +646,9 @@ hundreds of cloned repositories floating around, how does anyone verify that their copy of linux.git has not been tampered with by a malicious third party? -Or what happens if a backdoor is discovered in the code and the "Author" -line in the commit says it was done by you, while you're pretty sure you -had `nothing to do with it`_? +Or what happens if malicious code is discovered in the kernel and the +"Author" line in the commit says it was done by you, while you're pretty +sure you had `nothing to do with it`_? To address both of these issues, Git introduced PGP integration. Signed tags prove the repository integrity by assuring that its contents are @@ -718,17 +668,10 @@ should be used (``[fpr]`` is the fingerprint of your key):: $ git config --global user.signingKey [fpr] -**IMPORTANT**: If you have a distinct ``gpg2`` command, then you should -tell git to always use it instead of the legacy ``gpg`` from version 1:: - - $ git config --global gpg.program gpg2 - $ git config --global gpgv.program gpgv2 - How to work with signed tags ---------------------------- -To create a signed tag, simply pass the ``-s`` switch to the tag -command:: +To create a signed tag, pass the ``-s`` switch to the tag command:: $ git tag -s [tagname] @@ -739,7 +682,7 @@ not been maliciously altered. How to verify signed tags ~~~~~~~~~~~~~~~~~~~~~~~~~ -To verify a signed tag, simply use the ``verify-tag`` command:: +To verify a signed tag, use the ``verify-tag`` command:: $ git verify-tag [tagname] @@ -758,16 +701,9 @@ The merge message will contain something like this:: # gpg: Signature made [...] # gpg: Good signature from [...] -If you are verifying someone else's git tag, then you will need to -import their PGP key. Please refer to the -":ref:`verify_identities`" section below. - -.. note:: - - If you get "``gpg: Can't check signature: unknown pubkey - algorithm``" error, you need to tell git to use gpgv2 for - verification, so it properly processes signatures made by ECC keys. - See instructions at the start of this section. +If you are verifying someone else's git tag, you will first need to +import their PGP key. Please refer to the ":ref:`verify_identities`" +section below. Configure git to always sign annotated tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -781,16 +717,16 @@ configuration option:: 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 -the mailing list, and this workflow does not preserve PGP commit -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. +It is also possible to create signed commits, but they have limited +usefulness in Linux kernel development. The kernel contribution workflow +relies on sending in patches, and converting commits to patches does not +preserve git commit signatures. Furthermore, when rebasing your own +repository on a newer upstream, 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 +That said, 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. @@ -801,7 +737,7 @@ We recommend this for the following reasons: 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 + after reinstalling your system), this lets you 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. @@ -809,9 +745,8 @@ We recommend this for the following reasons: Creating signed commits ~~~~~~~~~~~~~~~~~~~~~~~ -To create a signed commit, you just need to pass the ``-S`` flag to the -``git commit`` command (it's capital ``-S`` due to collision with -another flag):: +To create a signed commit, pass the ``-S`` flag to the ``git commit`` +command (it's capital ``-S`` due to collision with another flag):: $ git commit -S @@ -828,12 +763,73 @@ You can tell git to always sign commits:: .. _verify_identities: +How to work with signed patches +------------------------------- + +It is possible to use your PGP key to sign patches sent to kernel +developer mailing lists. Since existing email signature mechanisms +(PGP-Mime or PGP-inline) tend to cause problems with regular code +review tasks, you should use the tool kernel.org created for this +purpose that puts cryptographic attestation signatures into message +headers (a-la DKIM): + +- `Patatt Patch Attestation`_ + +.. _`Patatt Patch Attestation`: https://pypi.org/project/patatt/ + +Installing and configuring patatt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + If you use B4 to send in your patches, patatt is already installed + and integrated into your workflow. + +Patatt is packaged for many distributions already, so please check there +first. You can also install it from pypi using "``pip install patatt``". + +If you already have your PGP key configured with git (via the +``user.signingKey`` configuration parameter), then patatt requires no +further configuration. You can start signing your patches by installing +the git-send-email hook in the repository you want:: + + patatt install-hook + +Now any patches you send with ``git send-email`` will be automatically +signed with your cryptographic signature. + +Checking patatt signatures +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using ``b4`` to retrieve and apply patches, then it will +automatically attempt to verify all DKIM and patatt signatures it +encounters, for example:: + + $ b4 am 20220720205013.890942-1-broonie@kernel.org + [...] + Checking attestation on all messages, may take a moment... + --- + ✓ [PATCH v1 1/3] kselftest/arm64: Correct buffer allocation for SVE Z registers + ✓ [PATCH v1 2/3] arm64/sve: Document our actual ABI for clearing registers on syscall + ✓ [PATCH v1 3/3] kselftest/arm64: Enforce actual ABI for SVE syscalls + --- + ✓ Signed: openpgp/broonie@kernel.org + ✓ Signed: DKIM/kernel.org + +.. note:: + + Patatt and b4 are still in active development and you should check + the latest documentation for these projects for any new or updated + features. + +.. _kernel_identities: + How to verify kernel developer identities ========================================= -Signing tags and commits is easy, but how does one go about verifying -that the key used to sign something belongs to the actual kernel -developer and not to a malicious imposter? +Signing tags and commits is straightforward, but how does one go about +verifying that the key used to sign something belongs to the actual +kernel developer and not to a malicious imposter? Configure auto-key-retrieval using WKD and DANE ----------------------------------------------- @@ -880,7 +876,7 @@ various software makers dictating who should be your trusted certifying entity, PGP leaves this responsibility to each user. Unfortunately, very few people understand how the Web of Trust works. -While it remains an important aspect of the OpenPGP specification, +While it is still an important part of the OpenPGP specification, recent versions of GnuPG (2.2 and above) have implemented an alternative mechanism called "Trust on First Use" (TOFU). You can think of TOFU as "the SSH-like approach to trust." With SSH, the first time you connect @@ -890,8 +886,8 @@ to connect, forcing you to make a decision on whether you choose to trust the changed key or not. Similarly, the first time you import someone's PGP key, it is assumed to be valid. If at any point in the future GnuPG comes across another key with the same identity, both the -previously imported key and the new key will be marked as invalid and -you will need to manually figure out which one to keep. +previously imported key and the new key will be marked for verification +and you will need to manually figure out which one to keep. We recommend that you use the combined TOFU+PGP trust model (which is the new default in GnuPG v2). To set it, add (or modify) the @@ -899,65 +895,17 @@ the new default in GnuPG v2). To set it, add (or modify) the trust-model tofu+pgp -How to use keyservers (more) safely ------------------------------------ - -If you get a "No public key" error when trying to validate someone's -tag, then you should attempt to lookup that key using a keyserver. It is -important to keep in mind that there is absolutely no guarantee that the -key you retrieve from PGP keyservers belongs to the actual person -- -that much is by design. You are supposed to use the Web of Trust to -establish key validity. - -How to properly maintain the Web of Trust is beyond the scope of this -document, simply because doing it properly requires both effort and -dedication that tends to be beyond the caring threshold of most human -beings. Here are some shortcuts that will help you reduce the risk of -importing a malicious key. - -First, let's say you've tried to run ``git verify-tag`` but it returned -an error saying the key is not found:: - - $ git verify-tag sunxi-fixes-for-4.15-2 - gpg: Signature made Sun 07 Jan 2018 10:51:55 PM EST - gpg: using RSA key DA73759BF8619E484E5A3B47389A54219C0F2430 - gpg: issuer "wens@...org" - gpg: Can't check signature: No public key - -Let's query the keyserver for more info about that key fingerprint (the -fingerprint probably belongs to a subkey, so we can't use it directly -without finding out the ID of the master key it is associated with):: - - $ gpg --search DA73759BF8619E484E5A3B47389A54219C0F2430 - gpg: data source: hkp://keys.gnupg.net - (1) Chen-Yu Tsai <wens@...org> - 4096 bit RSA key C94035C21B4F2AEB, created: 2017-03-14, expires: 2019-03-15 - Keys 1-1 of 1 for "DA73759BF8619E484E5A3B47389A54219C0F2430". Enter number(s), N)ext, or Q)uit > q - -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:: - - $ gpg --list-key torvalds@kernel.org - pub rsa2048 2011-09-20 [SC] - ABAF11C65A2970B130ABE3C479BE3E4300411886 - uid [ unknown] Linus Torvalds <torvalds@kernel.org> - sub rsa2048 2011-09-20 [E] - -Next, find a trust path from Linus Torvalds to the key-id you found via ``gpg ---search`` of the unknown key. For this, you can use several tools including -https://github.com/mricon/wotmate, -https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git/tree/graphs, and -https://the.earth.li/~noodles/pathfind.html. - -If you get a few decent trust paths, then it's a pretty good indication -that it is a valid key. You can add it to your keyring from the -keyserver now:: - - $ gpg --recv-key C94035C21B4F2AEB - -This process is not perfect, and you are obviously trusting the -administrators of the PGP Pathfinder service to not be malicious (in -fact, this goes against :ref:`devs_not_infra`). However, if you -do not carefully maintain your own web of trust, then it is a marked -improvement over blindly trusting keyservers. +Using the kernel.org web of trust repository +-------------------------------------------- + +Kernel.org maintains a git repository with developers' public keys as a +replacement for replicating keyserver networks that have gone mostly +dark in the past few years. The full documentation for how to set up +that repository as your source of public keys can be found here: + +- `Kernel developer PGP Keyring`_ + +If you are a kernel developer, please consider submitting your key for +inclusion into that keyring. + +.. _`Kernel developer PGP Keyring`: https://korg.docs.kernel.org/pgpkeys.html |