920 lines · plain
1.. _pgpguide:2 3===========================4Kernel Maintainer PGP guide5===========================6 7:Author: Konstantin Ryabitsev <konstantin@linuxfoundation.org>8 9This document is aimed at Linux kernel developers, and especially at10subsystem maintainers. It contains a subset of information discussed in11the more general "`Protecting Code Integrity`_" guide published by the12Linux Foundation. Please read that document for more in-depth discussion13on some of the topics mentioned in this guide.14 15.. _`Protecting Code Integrity`: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md16 17The role of PGP in Linux Kernel development18===========================================19 20PGP helps ensure the integrity of the code that is produced by the Linux21kernel development community and, to a lesser degree, establish trusted22communication channels between developers via PGP-signed email exchange.23 24The Linux kernel source code is available in two main formats:25 26- Distributed source repositories (git)27- Periodic release snapshots (tarballs)28 29Both git repositories and tarballs carry PGP signatures of the kernel30developers who create official kernel releases. These signatures offer a31cryptographic guarantee that downloadable versions made available via32kernel.org or any other mirrors are identical to what these developers33have on their workstations. To this end:34 35- git repositories provide PGP signatures on all tags36- tarballs provide detached PGP signatures with all downloads37 38.. _devs_not_infra:39 40Trusting the developers, not infrastructure41-------------------------------------------42 43Ever since the 2011 compromise of core kernel.org systems, the main44operating principle of the Kernel Archives project has been to assume45that any part of the infrastructure can be compromised at any time. For46this reason, the administrators have taken deliberate steps to emphasize47that trust must always be placed with developers and never with the code48hosting infrastructure, regardless of how good the security practices49for the latter may be.50 51The above guiding principle is the reason why this guide is needed. We52want to make sure that by placing trust into developers we do not simply53shift the blame for potential future security incidents to someone else.54The goal is to provide a set of guidelines developers can use to create55a secure working environment and safeguard the PGP keys used to56establish the integrity of the Linux kernel itself.57 58.. _pgp_tools:59 60PGP tools61=========62 63Use GnuPG 2.2 or later64----------------------65 66Your distro should already have GnuPG installed by default, you just67need to verify that you are using a reasonably recent version of it.68To check, run::69 70 $ gpg --version | head -n171 72If you have version 2.2 or above, then you are good to go. If you have a73version that is prior than 2.2, then some commands from this guide may74not work.75 76Configure gpg-agent options77~~~~~~~~~~~~~~~~~~~~~~~~~~~78 79The GnuPG agent is a helper tool that will start automatically whenever80you use the ``gpg`` command and run in the background with the purpose81of caching the private key passphrase. There are two options you should82know in order to tweak when the passphrase should be expired from cache:83 84- ``default-cache-ttl`` (seconds): If you use the same key again before85 the time-to-live expires, the countdown will reset for another period.86 The default is 600 (10 minutes).87- ``max-cache-ttl`` (seconds): Regardless of how recently you've used88 the key since initial passphrase entry, if the maximum time-to-live89 countdown expires, you'll have to enter the passphrase again. The90 default is 30 minutes.91 92If you find either of these defaults too short (or too long), you can93edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values::94 95 # set to 30 minutes for regular ttl, and 2 hours for max ttl96 default-cache-ttl 180097 max-cache-ttl 720098 99.. note::100 101 It is no longer necessary to start gpg-agent manually at the102 beginning of your shell session. You may want to check your rc files103 to remove anything you had in place for older versions of GnuPG, as104 it may not be doing the right thing any more.105 106.. _protect_your_key:107 108Protect your PGP key109====================110 111This guide assumes that you already have a PGP key that you use for Linux112kernel development purposes. If you do not yet have one, please see the113"`Protecting Code Integrity`_" document mentioned earlier for guidance114on how to create a new one.115 116You should also make a new key if your current one is weaker than 2048117bits (RSA).118 119Understanding PGP Subkeys120-------------------------121 122A PGP key rarely consists of a single keypair -- usually it is a123collection of independent subkeys that can be used for different124purposes based on their capabilities, assigned at their creation time.125PGP defines four capabilities that a key can have:126 127- **[S]** keys can be used for signing128- **[E]** keys can be used for encryption129- **[A]** keys can be used for authentication130- **[C]** keys can be used for certifying other keys131 132The key with the **[C]** capability is often called the "master" key,133but this terminology is misleading because it implies that the Certify134key can be used in place of any of other subkey on the same chain (like135a physical "master key" can be used to open locks made for other keys).136Since this is not the case, this guide will refer to it as "the Certify137key" to avoid any ambiguity.138 139It is critical to fully understand the following:140 1411. All subkeys are fully independent from each other. If you lose a142 private subkey, it cannot be restored or recreated from any other143 private key on your chain.1442. With the exception of the Certify key, there can be multiple subkeys145 with identical capabilities (e.g. you can have 2 valid encryption146 subkeys, 3 valid signing subkeys, but only one valid certification147 subkey). All subkeys are fully independent -- a message encrypted to148 one **[E]** subkey cannot be decrypted with any other **[E]** subkey149 you may also have.1503. A single subkey may have multiple capabilities (e.g. your **[C]** key151 can also be your **[S]** key).152 153The key carrying the **[C]** (certify) capability is the only key that154can be used to indicate relationship with other keys. Only the **[C]**155key can be used to:156 157- add or revoke other keys (subkeys) with S/E/A capabilities158- add, change or revoke identities (uids) associated with the key159- add or change the expiration date on itself or any subkey160- sign other people's keys for web of trust purposes161 162By default, GnuPG creates the following when generating new keys:163 164- One subkey carrying both Certify and Sign capabilities (**[SC]**)165- A separate subkey with the Encryption capability (**[E]**)166 167If you used the default parameters when generating your key, then that168is what you will have. You can verify by running ``gpg --list-secret-keys``,169for example::170 171 sec ed25519 2022-12-20 [SC] [expires: 2024-12-19]172 000000000000000000000000AAAABBBBCCCCDDDD173 uid [ultimate] Alice Dev <adev@kernel.org>174 ssb cv25519 2022-12-20 [E] [expires: 2024-12-19]175 176The long line under the ``sec`` entry is your key fingerprint --177whenever you see ``[fpr]`` in the examples below, that 40-character178string is what it refers to.179 180Ensure your passphrase is strong181--------------------------------182 183GnuPG uses passphrases to encrypt your private keys before storing them on184disk. This way, even if your ``.gnupg`` directory is leaked or stolen in185its entirety, the attackers cannot use your private keys without first186obtaining the passphrase to decrypt them.187 188It is absolutely essential that your private keys are protected by a189strong passphrase. To set it or change it, use::190 191 $ gpg --change-passphrase [fpr]192 193Create a separate Signing subkey194--------------------------------195 196Our goal is to protect your Certify key by moving it to offline media,197so if you only have a combined **[SC]** key, then you should create a198separate signing subkey::199 200 $ gpg --quick-addkey [fpr] ed25519 sign201 202.. note:: ECC support in GnuPG203 204 Note, that if you intend to use a hardware token that does not205 support ED25519 ECC keys, you should choose "nistp256" instead or206 "ed25519." See the section below on recommended hardware devices.207 208 209Back up your Certify key for disaster recovery210----------------------------------------------211 212The more signatures you have on your PGP key from other developers, the213more reasons you have to create a backup version that lives on something214other than digital media, for disaster recovery reasons.215 216The best way to create a printable hardcopy of your private key is by217using the ``paperkey`` software written for this very purpose. See ``man218paperkey`` for more details on the output format and its benefits over219other solutions. Paperkey should already be packaged for most220distributions.221 222Run the following command to create a hardcopy backup of your private223key::224 225 $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt226 227Print out that file (or pipe the output straight to lpr), then take a228pen and write your passphrase on the margin of the paper. **This is229strongly recommended** because the key printout is still encrypted with230that passphrase, and if you ever change it you will not remember what it231used to be when you had created the backup -- *guaranteed*.232 233Put the resulting printout and the hand-written passphrase into an envelope234and store in a secure and well-protected place, preferably away from your235home, such as your bank vault.236 237.. note::238 239 Your printer is probably no longer a simple dumb device connected to240 your parallel port, but since the output is still encrypted with241 your passphrase, printing out even to "cloud-integrated" modern242 printers should remain a relatively safe operation.243 244Back up your whole GnuPG directory245----------------------------------246 247.. warning::248 249 **!!!Do not skip this step!!!**250 251It is important to have a readily available backup of your PGP keys252should you need to recover them. This is different from the253disaster-level preparedness we did with ``paperkey``. You will also rely254on these external copies whenever you need to use your Certify key --255such as when making changes to your own key or signing other people's256keys after conferences and summits.257 258Start by getting a small USB "thumb" drive (preferably two!) that you259will use for backup purposes. You will need to encrypt them using LUKS260-- refer to your distro's documentation on how to accomplish this.261 262For the encryption passphrase, you can use the same one as on your263PGP key.264 265Once the encryption process is over, re-insert the USB drive and make266sure it gets properly mounted. Copy your entire ``.gnupg`` directory267over to the encrypted storage::268 269 $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup270 271You should now test to make sure everything still works::272 273 $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr]274 275If you don't get any errors, then you should be good to go. Unmount the276USB drive, distinctly label it so you don't blow it away next time you277need to use a random USB drive, and put in a safe place -- but not too278far away, because you'll need to use it every now and again for things279like editing identities, adding or revoking subkeys, or signing other280people's keys.281 282Remove the Certify key from your homedir283----------------------------------------284 285The files in our home directory are not as well protected as we like to286think. They can be leaked or stolen via many different means:287 288- by accident when making quick homedir copies to set up a new workstation289- by systems administrator negligence or malice290- via poorly secured backups291- via malware in desktop apps (browsers, pdf viewers, etc)292- via coercion when crossing international borders293 294Protecting your key with a good passphrase greatly helps reduce the risk295of any of the above, but passphrases can be discovered via keyloggers,296shoulder-surfing, or any number of other means. For this reason, the297recommended setup is to remove your Certify key from your home directory298and store it on offline storage.299 300.. warning::301 302 Please see the previous section and make sure you have backed up303 your GnuPG directory in its entirety. What we are about to do will304 render your key useless if you do not have a usable backup!305 306First, identify the keygrip of your Certify key::307 308 $ gpg --with-keygrip --list-key [fpr]309 310The output will be something like this::311 312 pub ed25519 2022-12-20 [SC] [expires: 2022-12-19]313 000000000000000000000000AAAABBBBCCCCDDDD314 Keygrip = 1111000000000000000000000000000000000000315 uid [ultimate] Alice Dev <adev@kernel.org>316 sub cv25519 2022-12-20 [E] [expires: 2022-12-19]317 Keygrip = 2222000000000000000000000000000000000000318 sub ed25519 2022-12-20 [S]319 Keygrip = 3333000000000000000000000000000000000000320 321Find the keygrip entry that is beneath the ``pub`` line (right under the322Certify key fingerprint). This will correspond directly to a file in your323``~/.gnupg`` directory::324 325 $ cd ~/.gnupg/private-keys-v1.d326 $ ls327 1111000000000000000000000000000000000000.key328 2222000000000000000000000000000000000000.key329 3333000000000000000000000000000000000000.key330 331All you have to do is simply remove the .key file that corresponds to332the Certify key keygrip::333 334 $ cd ~/.gnupg/private-keys-v1.d335 $ rm 1111000000000000000000000000000000000000.key336 337Now, if you issue the ``--list-secret-keys`` command, it will show that338the Certify key is missing (the ``#`` indicates it is not available)::339 340 $ gpg --list-secret-keys341 sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19]342 000000000000000000000000AAAABBBBCCCCDDDD343 uid [ultimate] Alice Dev <adev@kernel.org>344 ssb cv25519 2022-12-20 [E] [expires: 2024-12-19]345 ssb ed25519 2022-12-20 [S]346 347You should also remove any ``secring.gpg`` files in the ``~/.gnupg``348directory, which may be left over from previous versions of GnuPG.349 350If you don't have the "private-keys-v1.d" directory351~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~352 353If you do not have a ``~/.gnupg/private-keys-v1.d`` directory, then your354secret keys are still stored in the legacy ``secring.gpg`` file used by355GnuPG v1. Making any changes to your key, such as changing the356passphrase or adding a subkey, should automatically convert the old357``secring.gpg`` format to use ``private-keys-v1.d`` instead.358 359Once you get that done, make sure to delete the obsolete ``secring.gpg``360file, which still contains your private keys.361 362.. _smartcards:363 364Move the subkeys to a dedicated crypto device365=============================================366 367Even though the Certify key is now safe from being leaked or stolen, the368subkeys are still in your home directory. Anyone who manages to get369their hands on those will be able to decrypt your communication or fake370your signatures (if they know the passphrase). Furthermore, each time a371GnuPG operation is performed, the keys are loaded into system memory and372can be stolen from there by sufficiently advanced malware (think373Meltdown and Spectre).374 375The best way to completely protect your keys is to move them to a376specialized hardware device that is capable of smartcard operations.377 378The benefits of smartcards379--------------------------380 381A smartcard contains a cryptographic chip that is capable of storing382private keys and performing crypto operations directly on the card383itself. Because the key contents never leave the smartcard, the384operating system of the computer into which you plug in the hardware385device is not able to retrieve the private keys themselves. This is very386different from the encrypted USB storage device we used earlier for387backup purposes -- while that USB device is plugged in and mounted, the388operating system is able to access the private key contents.389 390Using external encrypted USB media is not a substitute to having a391smartcard-capable device.392 393Available smartcard devices394---------------------------395 396Unless all your laptops and workstations have smartcard readers, the397easiest is to get a specialized USB device that implements smartcard398functionality. There are several options available:399 400- `Nitrokey Start`_: Open hardware and Free Software, based on FSI401 Japan's `Gnuk`_. One of the few available commercial devices that402 support ED25519 ECC keys, but offer fewest security features (such as403 resistance to tampering or some side-channel attacks).404- `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more405 tamper-resistant and offers more security features. Pro 2 supports ECC406 cryptography (NISTP).407- `Yubikey 5`_: proprietary hardware and software, but cheaper than408 Nitrokey Pro and comes available in the USB-C form that is more useful409 with newer laptops. Offers additional security features such as FIDO410 U2F, among others, and now finally supports NISTP and ED25519 ECC411 keys.412 413Your choice will depend on cost, shipping availability in your414geographical region, and open/proprietary hardware considerations.415 416.. note::417 418 If you are listed in MAINTAINERS or have an account at kernel.org,419 you `qualify for a free Nitrokey Start`_ courtesy of The Linux420 Foundation.421 422.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6423.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3424.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/425.. _Gnuk: https://www.fsij.org/doc-gnuk/426.. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html427 428Configure your smartcard device429-------------------------------430 431Your smartcard device should Just Work (TM) the moment you plug it into432any modern Linux workstation. You can verify it by running::433 434 $ gpg --card-status435 436If you see full smartcard details, then you are good to go.437Unfortunately, troubleshooting all possible reasons why things may not438be working for you is way beyond the scope of this guide. If you are439having trouble getting the card to work with GnuPG, please seek help via440usual support channels.441 442To configure your smartcard, you will need to use the GnuPG menu system, as443there are no convenient command-line switches::444 445 $ gpg --card-edit446 [...omitted...]447 gpg/card> admin448 Admin commands are allowed449 gpg/card> passwd450 451You should set the user PIN (1), Admin PIN (3), and the Reset Code (4).452Please make sure to record and store these in a safe place -- especially453the Admin PIN and the Reset Code (which allows you to completely wipe454the smartcard). You so rarely need to use the Admin PIN, that you will455inevitably forget what it is if you do not record it.456 457Getting back to the main card menu, you can also set other values (such458as name, sex, login data, etc), but it's not necessary and will459additionally leak information about your smartcard should you lose it.460 461.. note::462 463 Despite having the name "PIN", neither the user PIN nor the admin464 PIN on the card need to be numbers.465 466.. warning::467 468 Some devices may require that you move the subkeys onto the device469 before you can change the passphrase. Please check the documentation470 provided by the device manufacturer.471 472Move the subkeys to your smartcard473----------------------------------474 475Exit the card menu (using "q") and save all changes. Next, let's move476your subkeys onto the smartcard. You will need both your PGP key477passphrase and the admin PIN of the card for most operations::478 479 $ gpg --edit-key [fpr]480 481 Secret subkeys are available.482 483 pub ed25519/AAAABBBBCCCCDDDD484 created: 2022-12-20 expires: 2024-12-19 usage: SC485 trust: ultimate validity: ultimate486 ssb cv25519/1111222233334444487 created: 2022-12-20 expires: never usage: E488 ssb ed25519/5555666677778888489 created: 2017-12-07 expires: never usage: S490 [ultimate] (1). Alice Dev <adev@kernel.org>491 492 gpg>493 494Using ``--edit-key`` puts us into the menu mode again, and you will495notice that the key listing is a little different. From here on, all496commands are done from inside this menu mode, as indicated by ``gpg>``.497 498First, let's select the key we'll be putting onto the card -- you do499this by typing ``key 1`` (it's the first one in the listing, the **[E]**500subkey)::501 502 gpg> key 1503 504In the output, you should now see ``ssb*`` on the **[E]** key. The ``*``505indicates which key is currently "selected." It works as a *toggle*,506meaning that if you type ``key 1`` again, the ``*`` will disappear and507the key will not be selected any more.508 509Now, let's move that key onto the smartcard::510 511 gpg> keytocard512 Please select where to store the key:513 (2) Encryption key514 Your selection? 2515 516Since it's our **[E]** key, it makes sense to put it into the Encryption517slot. When you submit your selection, you will be prompted first for518your PGP key passphrase, and then for the admin PIN. If the command519returns without an error, your key has been moved.520 521**Important**: Now type ``key 1`` again to unselect the first key, and522``key 2`` to select the **[S]** key::523 524 gpg> key 1525 gpg> key 2526 gpg> keytocard527 Please select where to store the key:528 (1) Signature key529 (3) Authentication key530 Your selection? 1531 532You can use the **[S]** key both for Signature and Authentication, but533we want to make sure it's in the Signature slot, so choose (1). Once534again, if your command returns without an error, then the operation was535successful::536 537 gpg> q538 Save changes? (y/N) y539 540Saving the changes will delete the keys you moved to the card from your541home directory (but it's okay, because we have them in our backups542should we need to do this again for a replacement smartcard).543 544Verifying that the keys were moved545~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~546 547If you perform ``--list-secret-keys`` now, you will see a subtle548difference in the output::549 550 $ gpg --list-secret-keys551 sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19]552 000000000000000000000000AAAABBBBCCCCDDDD553 uid [ultimate] Alice Dev <adev@kernel.org>554 ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19]555 ssb> ed25519 2022-12-20 [S]556 557The ``>`` in the ``ssb>`` output indicates that the subkey is only558available on the smartcard. If you go back into your secret keys559directory and look at the contents there, you will notice that the560``.key`` files there have been replaced with stubs::561 562 $ cd ~/.gnupg/private-keys-v1.d563 $ strings *.key | grep 'private-key'564 565The output should contain ``shadowed-private-key`` to indicate that566these files are only stubs and the actual content is on the smartcard.567 568Verifying that the smartcard is functioning569~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~570 571To verify that the smartcard is working as intended, you can create a572signature::573 574 $ echo "Hello world" | gpg --clearsign > /tmp/test.asc575 $ gpg --verify /tmp/test.asc576 577This should ask for your smartcard PIN on your first command, and then578show "Good signature" after you run ``gpg --verify``.579 580Congratulations, you have successfully made it extremely difficult to581steal your digital developer identity!582 583Other common GnuPG operations584-----------------------------585 586Here is a quick reference for some common operations you'll need to do587with your PGP key.588 589Mounting your safe offline storage590~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~591 592You will need your Certify key for any of the operations below, so you593will first need to mount your backup offline storage and tell GnuPG to594use it::595 596 $ export GNUPGHOME=/media/disk/foo/gnupg-backup597 $ gpg --list-secret-keys598 599You want to make sure that you see ``sec`` and not ``sec#`` in the600output (the ``#`` means the key is not available and you're still using601your regular home directory location).602 603Extending key expiration date604~~~~~~~~~~~~~~~~~~~~~~~~~~~~~605 606The Certify key has the default expiration date of 2 years from the date607of creation. This is done both for security reasons and to make obsolete608keys eventually disappear from keyservers.609 610To extend the expiration on your key by a year from current date, just611run::612 613 $ gpg --quick-set-expire [fpr] 1y614 615You can also use a specific date if that is easier to remember (e.g.616your birthday, January 1st, or Canada Day)::617 618 $ gpg --quick-set-expire [fpr] 2025-07-01619 620Remember to send the updated key back to keyservers::621 622 $ gpg --send-key [fpr]623 624Updating your work directory after any changes625~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~626 627After you make any changes to your key using the offline storage, you will628want to import these changes back into your regular working directory::629 630 $ gpg --export | gpg --homedir ~/.gnupg --import631 $ unset GNUPGHOME632 633Using gpg-agent over ssh634~~~~~~~~~~~~~~~~~~~~~~~~635 636You can forward your gpg-agent over ssh if you need to sign tags or637commits on a remote system. Please refer to the instructions provided638on the GnuPG wiki:639 640- `Agent Forwarding over SSH`_641 642It works more smoothly if you can modify the sshd server settings on the643remote end.644 645.. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding646 647.. _pgp_with_git:648 649Using PGP with Git650==================651 652One of the core features of Git is its decentralized nature -- once a653repository is cloned to your system, you have full history of the654project, including all of its tags, commits and branches. However, with655hundreds of cloned repositories floating around, how does anyone verify656that their copy of linux.git has not been tampered with by a malicious657third party?658 659Or what happens if a backdoor is discovered in the code and the "Author"660line in the commit says it was done by you, while you're pretty sure you661had `nothing to do with it`_?662 663To address both of these issues, Git introduced PGP integration. Signed664tags prove the repository integrity by assuring that its contents are665exactly the same as on the workstation of the developer who created the666tag, while signed commits make it nearly impossible for someone to667impersonate you without having access to your PGP keys.668 669.. _`nothing to do with it`: https://github.com/jayphelps/git-blame-someone-else670 671Configure git to use your PGP key672---------------------------------673 674If you only have one secret key in your keyring, then you don't really675need to do anything extra, as it becomes your default key. However, if676you happen to have multiple secret keys, you can tell git which key677should be used (``[fpr]`` is the fingerprint of your key)::678 679 $ git config --global user.signingKey [fpr]680 681How to work with signed tags682----------------------------683 684To create a signed tag, simply pass the ``-s`` switch to the tag685command::686 687 $ git tag -s [tagname]688 689Our recommendation is to always sign git tags, as this allows other690developers to ensure that the git repository they are pulling from has691not been maliciously altered.692 693How to verify signed tags694~~~~~~~~~~~~~~~~~~~~~~~~~695 696To verify a signed tag, simply use the ``verify-tag`` command::697 698 $ git verify-tag [tagname]699 700If you are pulling a tag from another fork of the project repository,701git should automatically verify the signature at the tip you're pulling702and show you the results during the merge operation::703 704 $ git pull [url] tags/sometag705 706The merge message will contain something like this::707 708 Merge tag 'sometag' of [url]709 710 [Tag message]711 712 # gpg: Signature made [...]713 # gpg: Good signature from [...]714 715If you are verifying someone else's git tag, then you will need to716import their PGP key. Please refer to the717":ref:`verify_identities`" section below.718 719Configure git to always sign annotated tags720~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~721 722Chances are, if you're creating an annotated tag, you'll want to sign723it. To force git to always sign annotated tags, you can set a global724configuration option::725 726 $ git config --global tag.forceSignAnnotated true727 728How to work with signed commits729-------------------------------730 731It is easy to create signed commits, but it is much more difficult to732use them in Linux kernel development, since it relies on patches sent to733the mailing list, and this workflow does not preserve PGP commit734signatures. Furthermore, when rebasing your repository to match735upstream, even your own PGP commit signatures will end up discarded. For736this reason, most kernel developers don't bother signing their commits737and will ignore signed commits in any external repositories that they738rely upon in their work.739 740However, if you have your working git tree publicly available at some741git hosting service (kernel.org, infradead.org, ozlabs.org, or others),742then the recommendation is that you sign all your git commits even if743upstream developers do not directly benefit from this practice.744 745We recommend this for the following reasons:746 7471. Should there ever be a need to perform code forensics or track code748 provenance, even externally maintained trees carrying PGP commit749 signatures will be valuable for such purposes.7502. If you ever need to re-clone your local repository (for example,751 after a disk failure), this lets you easily verify the repository752 integrity before resuming your work.7533. If someone needs to cherry-pick your commits, this allows them to754 quickly verify their integrity before applying them.755 756Creating signed commits757~~~~~~~~~~~~~~~~~~~~~~~758 759To create a signed commit, you just need to pass the ``-S`` flag to the760``git commit`` command (it's capital ``-S`` due to collision with761another flag)::762 763 $ git commit -S764 765Configure git to always sign commits766~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~767 768You can tell git to always sign commits::769 770 git config --global commit.gpgSign true771 772.. note::773 774 Make sure you configure ``gpg-agent`` before you turn this on.775 776.. _verify_identities:777 778 779How to work with signed patches780-------------------------------781 782It is possible to use your PGP key to sign patches sent to kernel783developer mailing lists. Since existing email signature mechanisms784(PGP-Mime or PGP-inline) tend to cause problems with regular code785review tasks, you should use the tool kernel.org created for this786purpose that puts cryptographic attestation signatures into message787headers (a-la DKIM):788 789- `Patatt Patch Attestation`_790 791.. _`Patatt Patch Attestation`: https://pypi.org/project/patatt/792 793Installing and configuring patatt794~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~795 796Patatt is packaged for many distributions already, so please check there797first. You can also install it from pypi using "``pip install patatt``".798 799If you already have your PGP key configured with git (via the800``user.signingKey`` configuration parameter), then patatt requires no801further configuration. You can start signing your patches by installing802the git-send-email hook in the repository you want::803 804 patatt install-hook805 806Now any patches you send with ``git send-email`` will be automatically807signed with your cryptographic signature.808 809Checking patatt signatures810~~~~~~~~~~~~~~~~~~~~~~~~~~811 812If you are using ``b4`` to retrieve and apply patches, then it will813automatically attempt to verify all DKIM and patatt signatures it814encounters, for example::815 816 $ b4 am 20220720205013.890942-1-broonie@kernel.org817 [...]818 Checking attestation on all messages, may take a moment...819 ---820 ✓ [PATCH v1 1/3] kselftest/arm64: Correct buffer allocation for SVE Z registers821 ✓ [PATCH v1 2/3] arm64/sve: Document our actual ABI for clearing registers on syscall822 ✓ [PATCH v1 3/3] kselftest/arm64: Enforce actual ABI for SVE syscalls823 ---824 ✓ Signed: openpgp/broonie@kernel.org825 ✓ Signed: DKIM/kernel.org826 827.. note::828 829 Patatt and b4 are still in active development and you should check830 the latest documentation for these projects for any new or updated831 features.832 833.. _kernel_identities:834 835How to verify kernel developer identities836=========================================837 838Signing tags and commits is easy, but how does one go about verifying839that the key used to sign something belongs to the actual kernel840developer and not to a malicious imposter?841 842Configure auto-key-retrieval using WKD and DANE843-----------------------------------------------844 845If you are not already someone with an extensive collection of other846developers' public keys, then you can jumpstart your keyring by relying847on key auto-discovery and auto-retrieval. GnuPG can piggyback on other848delegated trust technologies, namely DNSSEC and TLS, to get you going if849the prospect of starting your own Web of Trust from scratch is too850daunting.851 852Add the following to your ``~/.gnupg/gpg.conf``::853 854 auto-key-locate wkd,dane,local855 auto-key-retrieve856 857DNS-Based Authentication of Named Entities ("DANE") is a method for858publishing public keys in DNS and securing them using DNSSEC signed859zones. Web Key Directory ("WKD") is the alternative method that uses860https lookups for the same purpose. When using either DANE or WKD for861looking up public keys, GnuPG will validate DNSSEC or TLS certificates,862respectively, before adding auto-retrieved public keys to your local863keyring.864 865Kernel.org publishes the WKD for all developers who have kernel.org866accounts. Once you have the above changes in your ``gpg.conf``, you can867auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you868don't already have them)::869 870 $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org871 872If you have a kernel.org account, then you should `add the kernel.org873UID to your key`_ to make WKD more useful to other kernel developers.874 875.. _`add the kernel.org UID to your key`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernelorg_uid_to_your_pgp_key876 877Web of Trust (WOT) vs. Trust on First Use (TOFU)878------------------------------------------------879 880PGP incorporates a trust delegation mechanism known as the "Web of881Trust." At its core, this is an attempt to replace the need for882centralized Certification Authorities of the HTTPS/TLS world. Instead of883various software makers dictating who should be your trusted certifying884entity, PGP leaves this responsibility to each user.885 886Unfortunately, very few people understand how the Web of Trust works.887While it remains an important aspect of the OpenPGP specification,888recent versions of GnuPG (2.2 and above) have implemented an alternative889mechanism called "Trust on First Use" (TOFU). You can think of TOFU as890"the SSH-like approach to trust." With SSH, the first time you connect891to a remote system, its key fingerprint is recorded and remembered. If892the key changes in the future, the SSH client will alert you and refuse893to connect, forcing you to make a decision on whether you choose to894trust the changed key or not. Similarly, the first time you import895someone's PGP key, it is assumed to be valid. If at any point in the896future GnuPG comes across another key with the same identity, both the897previously imported key and the new key will be marked as invalid and898you will need to manually figure out which one to keep.899 900We recommend that you use the combined TOFU+PGP trust model (which is901the new default in GnuPG v2). To set it, add (or modify) the902``trust-model`` setting in ``~/.gnupg/gpg.conf``::903 904 trust-model tofu+pgp905 906Using the kernel.org web of trust repository907--------------------------------------------908 909Kernel.org maintains a git repository with developers' public keys as a910replacement for replicating keyserver networks that have gone mostly911dark in the past few years. The full documentation for how to set up912that repository as your source of public keys can be found here:913 914- `Kernel developer PGP Keyring`_915 916If you are a kernel developer, please consider submitting your key for917inclusion into that keyring.918 919.. _`Kernel developer PGP Keyring`: https://korg.docs.kernel.org/pgpkeys.html920