3 ===========================
4 Kernel Maintainer PGP guide
5 ===========================
7 :Author: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
9 This document is aimed at Linux kernel developers, and especially at
10 subsystem maintainers. It contains a subset of information discussed in
11 the more general "`Protecting Code Integrity`_" guide published by the
12 Linux Foundation. Please read that document for more in-depth discussion
13 on some of the topics mentioned in this guide.
15 .. _`Protecting Code Integrity`: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md
17 The role of PGP in Linux Kernel development
18 ===========================================
20 PGP helps ensure the integrity of the code that is produced by the Linux
21 kernel development community and, to a lesser degree, establish trusted
22 communication channels between developers via PGP-signed email exchange.
24 The Linux kernel source code is available in two main formats:
26 - Distributed source repositories (git)
27 - Periodic release snapshots (tarballs)
29 Both git repositories and tarballs carry PGP signatures of the kernel
30 developers who create official kernel releases. These signatures offer a
31 cryptographic guarantee that downloadable versions made available via
32 kernel.org or any other mirrors are identical to what these developers
33 have on their workstations. To this end:
35 - git repositories provide PGP signatures on all tags
36 - tarballs provide detached PGP signatures with all downloads
40 Trusting the developers, not infrastructure
41 -------------------------------------------
43 Ever since the 2011 compromise of core kernel.org systems, the main
44 operating principle of the Kernel Archives project has been to assume
45 that any part of the infrastructure can be compromised at any time. For
46 this reason, the administrators have taken deliberate steps to emphasize
47 that trust must always be placed with developers and never with the code
48 hosting infrastructure, regardless of how good the security practices
49 for the latter may be.
51 The above guiding principle is the reason why this guide is needed. We
52 want to make sure that by placing trust into developers we do not simply
53 shift the blame for potential future security incidents to someone else.
54 The goal is to provide a set of guidelines developers can use to create
55 a secure working environment and safeguard the PGP keys used to
56 establish the integrity of the Linux kernel itself.
63 Use GnuPG 2.2 or later
64 ----------------------
66 Your distro should already have GnuPG installed by default, you just
67 need to verify that you are using a reasonably recent version of it.
70 $ gpg --version | head -n1
72 If you have version 2.2 or above, then you are good to go. If you have a
73 version that is prior than 2.2, then some commands from this guide may
76 Configure gpg-agent options
77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
79 The GnuPG agent is a helper tool that will start automatically whenever
80 you use the ``gpg`` command and run in the background with the purpose
81 of caching the private key passphrase. There are two options you should
82 know in order to tweak when the passphrase should be expired from cache:
84 - ``default-cache-ttl`` (seconds): If you use the same key again before
85 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 used
88 the key since initial passphrase entry, if the maximum time-to-live
89 countdown expires, you'll have to enter the passphrase again. The
90 default is 30 minutes.
92 If you find either of these defaults too short (or too long), you can
93 edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values::
95 # set to 30 minutes for regular ttl, and 2 hours for max ttl
96 default-cache-ttl 1800
101 It is no longer necessary to start gpg-agent manually at the
102 beginning of your shell session. You may want to check your rc files
103 to remove anything you had in place for older versions of GnuPG, as
104 it may not be doing the right thing any more.
106 .. _protect_your_key:
111 This guide assumes that you already have a PGP key that you use for Linux
112 kernel development purposes. If you do not yet have one, please see the
113 "`Protecting Code Integrity`_" document mentioned earlier for guidance
114 on how to create a new one.
116 You should also make a new key if your current one is weaker than 2048
119 Understanding PGP Subkeys
120 -------------------------
122 A PGP key rarely consists of a single keypair -- usually it is a
123 collection of independent subkeys that can be used for different
124 purposes based on their capabilities, assigned at their creation time.
125 PGP defines four capabilities that a key can have:
127 - **[S]** keys can be used for signing
128 - **[E]** keys can be used for encryption
129 - **[A]** keys can be used for authentication
130 - **[C]** keys can be used for certifying other keys
132 The key with the **[C]** capability is often called the "master" key,
133 but this terminology is misleading because it implies that the Certify
134 key can be used in place of any of other subkey on the same chain (like
135 a physical "master key" can be used to open locks made for other keys).
136 Since this is not the case, this guide will refer to it as "the Certify
137 key" to avoid any ambiguity.
139 It is critical to fully understand the following:
141 1. All subkeys are fully independent from each other. If you lose a
142 private subkey, it cannot be restored or recreated from any other
143 private key on your chain.
144 2. With the exception of the Certify key, there can be multiple subkeys
145 with identical capabilities (e.g. you can have 2 valid encryption
146 subkeys, 3 valid signing subkeys, but only one valid certification
147 subkey). All subkeys are fully independent -- a message encrypted to
148 one **[E]** subkey cannot be decrypted with any other **[E]** subkey
150 3. A single subkey may have multiple capabilities (e.g. your **[C]** key
151 can also be your **[S]** key).
153 The key carrying the **[C]** (certify) capability is the only key that
154 can be used to indicate relationship with other keys. Only the **[C]**
157 - add or revoke other keys (subkeys) with S/E/A capabilities
158 - add, change or revoke identities (uids) associated with the key
159 - add or change the expiration date on itself or any subkey
160 - sign other people's keys for web of trust purposes
162 By default, GnuPG creates the following when generating new keys:
164 - One subkey carrying both Certify and Sign capabilities (**[SC]**)
165 - A separate subkey with the Encryption capability (**[E]**)
167 If you used the default parameters when generating your key, then that
168 is what you will have. You can verify by running ``gpg --list-secret-keys``,
171 sec ed25519 2022-12-20 [SC] [expires: 2024-12-19]
172 000000000000000000000000AAAABBBBCCCCDDDD
173 uid [ultimate] Alice Dev <adev@kernel.org>
174 ssb cv25519 2022-12-20 [E] [expires: 2024-12-19]
176 The long line under the ``sec`` entry is your key fingerprint --
177 whenever you see ``[fpr]`` in the examples below, that 40-character
178 string is what it refers to.
180 Ensure your passphrase is strong
181 --------------------------------
183 GnuPG uses passphrases to encrypt your private keys before storing them on
184 disk. This way, even if your ``.gnupg`` directory is leaked or stolen in
185 its entirety, the attackers cannot use your private keys without first
186 obtaining the passphrase to decrypt them.
188 It is absolutely essential that your private keys are protected by a
189 strong passphrase. To set it or change it, use::
191 $ gpg --change-passphrase [fpr]
193 Create a separate Signing subkey
194 --------------------------------
196 Our goal is to protect your Certify key by moving it to offline media,
197 so if you only have a combined **[SC]** key, then you should create a
198 separate signing subkey::
200 $ gpg --quick-addkey [fpr] ed25519 sign
202 .. note:: ECC support in GnuPG
204 Note, that if you intend to use a hardware token that does not
205 support ED25519 ECC keys, you should choose "nistp256" instead or
206 "ed25519." See the section below on recommended hardware devices.
209 Back up your Certify key for disaster recovery
210 ----------------------------------------------
212 The more signatures you have on your PGP key from other developers, the
213 more reasons you have to create a backup version that lives on something
214 other than digital media, for disaster recovery reasons.
216 The best way to create a printable hardcopy of your private key is by
217 using the ``paperkey`` software written for this very purpose. See ``man
218 paperkey`` for more details on the output format and its benefits over
219 other solutions. Paperkey should already be packaged for most
222 Run the following command to create a hardcopy backup of your private
225 $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt
227 Print out that file (or pipe the output straight to lpr), then take a
228 pen and write your passphrase on the margin of the paper. **This is
229 strongly recommended** because the key printout is still encrypted with
230 that passphrase, and if you ever change it you will not remember what it
231 used to be when you had created the backup -- *guaranteed*.
233 Put the resulting printout and the hand-written passphrase into an envelope
234 and store in a secure and well-protected place, preferably away from your
235 home, such as your bank vault.
239 Your printer is probably no longer a simple dumb device connected to
240 your parallel port, but since the output is still encrypted with
241 your passphrase, printing out even to "cloud-integrated" modern
242 printers should remain a relatively safe operation.
244 Back up your whole GnuPG directory
245 ----------------------------------
249 **!!!Do not skip this step!!!**
251 It is important to have a readily available backup of your PGP keys
252 should you need to recover them. This is different from the
253 disaster-level preparedness we did with ``paperkey``. You will also rely
254 on these external copies whenever you need to use your Certify key --
255 such as when making changes to your own key or signing other people's
256 keys after conferences and summits.
258 Start by getting a small USB "thumb" drive (preferably two!) that you
259 will use for backup purposes. You will need to encrypt them using LUKS
260 -- refer to your distro's documentation on how to accomplish this.
262 For the encryption passphrase, you can use the same one as on your
265 Once the encryption process is over, re-insert the USB drive and make
266 sure it gets properly mounted. Copy your entire ``.gnupg`` directory
267 over to the encrypted storage::
269 $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup
271 You should now test to make sure everything still works::
273 $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr]
275 If you don't get any errors, then you should be good to go. Unmount the
276 USB drive, distinctly label it so you don't blow it away next time you
277 need to use a random USB drive, and put in a safe place -- but not too
278 far away, because you'll need to use it every now and again for things
279 like editing identities, adding or revoking subkeys, or signing other
282 Remove the Certify key from your homedir
283 ----------------------------------------
285 The files in our home directory are not as well protected as we like to
286 think. They can be leaked or stolen via many different means:
288 - by accident when making quick homedir copies to set up a new workstation
289 - by systems administrator negligence or malice
290 - via poorly secured backups
291 - via malware in desktop apps (browsers, pdf viewers, etc)
292 - via coercion when crossing international borders
294 Protecting your key with a good passphrase greatly helps reduce the risk
295 of any of the above, but passphrases can be discovered via keyloggers,
296 shoulder-surfing, or any number of other means. For this reason, the
297 recommended setup is to remove your Certify key from your home directory
298 and store it on offline storage.
302 Please see the previous section and make sure you have backed up
303 your GnuPG directory in its entirety. What we are about to do will
304 render your key useless if you do not have a usable backup!
306 First, identify the keygrip of your Certify key::
308 $ gpg --with-keygrip --list-key [fpr]
310 The output will be something like this::
312 pub ed25519 2022-12-20 [SC] [expires: 2022-12-19]
313 000000000000000000000000AAAABBBBCCCCDDDD
314 Keygrip = 1111000000000000000000000000000000000000
315 uid [ultimate] Alice Dev <adev@kernel.org>
316 sub cv25519 2022-12-20 [E] [expires: 2022-12-19]
317 Keygrip = 2222000000000000000000000000000000000000
318 sub ed25519 2022-12-20 [S]
319 Keygrip = 3333000000000000000000000000000000000000
321 Find the keygrip entry that is beneath the ``pub`` line (right under the
322 Certify key fingerprint). This will correspond directly to a file in your
323 ``~/.gnupg`` directory::
325 $ cd ~/.gnupg/private-keys-v1.d
327 1111000000000000000000000000000000000000.key
328 2222000000000000000000000000000000000000.key
329 3333000000000000000000000000000000000000.key
331 All you have to do is simply remove the .key file that corresponds to
332 the Certify key keygrip::
334 $ cd ~/.gnupg/private-keys-v1.d
335 $ rm 1111000000000000000000000000000000000000.key
337 Now, if you issue the ``--list-secret-keys`` command, it will show that
338 the Certify key is missing (the ``#`` indicates it is not available)::
340 $ gpg --list-secret-keys
341 sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19]
342 000000000000000000000000AAAABBBBCCCCDDDD
343 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]
347 You should also remove any ``secring.gpg`` files in the ``~/.gnupg``
348 directory, which may be left over from previous versions of GnuPG.
350 If you don't have the "private-keys-v1.d" directory
351 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
353 If you do not have a ``~/.gnupg/private-keys-v1.d`` directory, then your
354 secret keys are still stored in the legacy ``secring.gpg`` file used by
355 GnuPG v1. Making any changes to your key, such as changing the
356 passphrase or adding a subkey, should automatically convert the old
357 ``secring.gpg`` format to use ``private-keys-v1.d`` instead.
359 Once you get that done, make sure to delete the obsolete ``secring.gpg``
360 file, which still contains your private keys.
364 Move the subkeys to a dedicated crypto device
365 =============================================
367 Even though the Certify key is now safe from being leaked or stolen, the
368 subkeys are still in your home directory. Anyone who manages to get
369 their hands on those will be able to decrypt your communication or fake
370 your signatures (if they know the passphrase). Furthermore, each time a
371 GnuPG operation is performed, the keys are loaded into system memory and
372 can be stolen from there by sufficiently advanced malware (think
373 Meltdown and Spectre).
375 The best way to completely protect your keys is to move them to a
376 specialized hardware device that is capable of smartcard operations.
378 The benefits of smartcards
379 --------------------------
381 A smartcard contains a cryptographic chip that is capable of storing
382 private keys and performing crypto operations directly on the card
383 itself. Because the key contents never leave the smartcard, the
384 operating system of the computer into which you plug in the hardware
385 device is not able to retrieve the private keys themselves. This is very
386 different from the encrypted USB storage device we used earlier for
387 backup purposes -- while that USB device is plugged in and mounted, the
388 operating system is able to access the private key contents.
390 Using external encrypted USB media is not a substitute to having a
391 smartcard-capable device.
393 Available smartcard devices
394 ---------------------------
396 Unless all your laptops and workstations have smartcard readers, the
397 easiest is to get a specialized USB device that implements smartcard
398 functionality. There are several options available:
400 - `Nitrokey Start`_: Open hardware and Free Software, based on FSI
401 Japan's `Gnuk`_. One of the few available commercial devices that
402 support ED25519 ECC keys, but offer fewest security features (such as
403 resistance to tampering or some side-channel attacks).
404 - `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more
405 tamper-resistant and offers more security features. Pro 2 supports ECC
406 cryptography (NISTP).
407 - `Yubikey 5`_: proprietary hardware and software, but cheaper than
408 Nitrokey Pro and comes available in the USB-C form that is more useful
409 with newer laptops. Offers additional security features such as FIDO
410 U2F, among others, and now finally supports NISTP and ED25519 ECC
413 Your choice will depend on cost, shipping availability in your
414 geographical region, and open/proprietary hardware considerations.
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 Linux
422 .. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6
423 .. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3
424 .. _`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.html
428 Configure your smartcard device
429 -------------------------------
431 Your smartcard device should Just Work (TM) the moment you plug it into
432 any modern Linux workstation. You can verify it by running::
436 If you see full smartcard details, then you are good to go.
437 Unfortunately, troubleshooting all possible reasons why things may not
438 be working for you is way beyond the scope of this guide. If you are
439 having trouble getting the card to work with GnuPG, please seek help via
440 usual support channels.
442 To configure your smartcard, you will need to use the GnuPG menu system, as
443 there are no convenient command-line switches::
448 Admin commands are allowed
451 You should set the user PIN (1), Admin PIN (3), and the Reset Code (4).
452 Please make sure to record and store these in a safe place -- especially
453 the Admin PIN and the Reset Code (which allows you to completely wipe
454 the smartcard). You so rarely need to use the Admin PIN, that you will
455 inevitably forget what it is if you do not record it.
457 Getting back to the main card menu, you can also set other values (such
458 as name, sex, login data, etc), but it's not necessary and will
459 additionally leak information about your smartcard should you lose it.
463 Despite having the name "PIN", neither the user PIN nor the admin
464 PIN on the card need to be numbers.
468 Some devices may require that you move the subkeys onto the device
469 before you can change the passphrase. Please check the documentation
470 provided by the device manufacturer.
472 Move the subkeys to your smartcard
473 ----------------------------------
475 Exit the card menu (using "q") and save all changes. Next, let's move
476 your subkeys onto the smartcard. You will need both your PGP key
477 passphrase and the admin PIN of the card for most operations::
479 $ gpg --edit-key [fpr]
481 Secret subkeys are available.
483 pub ed25519/AAAABBBBCCCCDDDD
484 created: 2022-12-20 expires: 2024-12-19 usage: SC
485 trust: ultimate validity: ultimate
486 ssb cv25519/1111222233334444
487 created: 2022-12-20 expires: never usage: E
488 ssb ed25519/5555666677778888
489 created: 2017-12-07 expires: never usage: S
490 [ultimate] (1). Alice Dev <adev@kernel.org>
494 Using ``--edit-key`` puts us into the menu mode again, and you will
495 notice that the key listing is a little different. From here on, all
496 commands are done from inside this menu mode, as indicated by ``gpg>``.
498 First, let's select the key we'll be putting onto the card -- you do
499 this by typing ``key 1`` (it's the first one in the listing, the **[E]**
504 In the output, you should now see ``ssb*`` on the **[E]** key. The ``*``
505 indicates which key is currently "selected." It works as a *toggle*,
506 meaning that if you type ``key 1`` again, the ``*`` will disappear and
507 the key will not be selected any more.
509 Now, let's move that key onto the smartcard::
512 Please select where to store the key:
516 Since it's our **[E]** key, it makes sense to put it into the Encryption
517 slot. When you submit your selection, you will be prompted first for
518 your PGP key passphrase, and then for the admin PIN. If the command
519 returns without an error, your key has been moved.
521 **Important**: Now type ``key 1`` again to unselect the first key, and
522 ``key 2`` to select the **[S]** key::
527 Please select where to store the key:
529 (3) Authentication key
532 You can use the **[S]** key both for Signature and Authentication, but
533 we want to make sure it's in the Signature slot, so choose (1). Once
534 again, if your command returns without an error, then the operation was
538 Save changes? (y/N) y
540 Saving the changes will delete the keys you moved to the card from your
541 home directory (but it's okay, because we have them in our backups
542 should we need to do this again for a replacement smartcard).
544 Verifying that the keys were moved
545 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
547 If you perform ``--list-secret-keys`` now, you will see a subtle
548 difference in the output::
550 $ gpg --list-secret-keys
551 sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19]
552 000000000000000000000000AAAABBBBCCCCDDDD
553 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]
557 The ``>`` in the ``ssb>`` output indicates that the subkey is only
558 available on the smartcard. If you go back into your secret keys
559 directory and look at the contents there, you will notice that the
560 ``.key`` files there have been replaced with stubs::
562 $ cd ~/.gnupg/private-keys-v1.d
563 $ strings *.key | grep 'private-key'
565 The output should contain ``shadowed-private-key`` to indicate that
566 these files are only stubs and the actual content is on the smartcard.
568 Verifying that the smartcard is functioning
569 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
571 To verify that the smartcard is working as intended, you can create a
574 $ echo "Hello world" | gpg --clearsign > /tmp/test.asc
575 $ gpg --verify /tmp/test.asc
577 This should ask for your smartcard PIN on your first command, and then
578 show "Good signature" after you run ``gpg --verify``.
580 Congratulations, you have successfully made it extremely difficult to
581 steal your digital developer identity!
583 Other common GnuPG operations
584 -----------------------------
586 Here is a quick reference for some common operations you'll need to do
589 Mounting your safe offline storage
590 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
592 You will need your Certify key for any of the operations below, so you
593 will first need to mount your backup offline storage and tell GnuPG to
596 $ export GNUPGHOME=/media/disk/foo/gnupg-backup
597 $ gpg --list-secret-keys
599 You want to make sure that you see ``sec`` and not ``sec#`` in the
600 output (the ``#`` means the key is not available and you're still using
601 your regular home directory location).
603 Extending key expiration date
604 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
606 The Certify key has the default expiration date of 2 years from the date
607 of creation. This is done both for security reasons and to make obsolete
608 keys eventually disappear from keyservers.
610 To extend the expiration on your key by a year from current date, just
613 $ gpg --quick-set-expire [fpr] 1y
615 You can also use a specific date if that is easier to remember (e.g.
616 your birthday, January 1st, or Canada Day)::
618 $ gpg --quick-set-expire [fpr] 2025-07-01
620 Remember to send the updated key back to keyservers::
622 $ gpg --send-key [fpr]
624 Updating your work directory after any changes
625 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
627 After you make any changes to your key using the offline storage, you will
628 want to import these changes back into your regular working directory::
630 $ gpg --export | gpg --homedir ~/.gnupg --import
633 Using gpg-agent over ssh
634 ~~~~~~~~~~~~~~~~~~~~~~~~
636 You can forward your gpg-agent over ssh if you need to sign tags or
637 commits on a remote system. Please refer to the instructions provided
640 - `Agent Forwarding over SSH`_
642 It works more smoothly if you can modify the sshd server settings on the
645 .. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding
652 One of the core features of Git is its decentralized nature -- once a
653 repository is cloned to your system, you have full history of the
654 project, including all of its tags, commits and branches. However, with
655 hundreds of cloned repositories floating around, how does anyone verify
656 that their copy of linux.git has not been tampered with by a malicious
659 Or what happens if a backdoor is discovered in the code and the "Author"
660 line in the commit says it was done by you, while you're pretty sure you
661 had `nothing to do with it`_?
663 To address both of these issues, Git introduced PGP integration. Signed
664 tags prove the repository integrity by assuring that its contents are
665 exactly the same as on the workstation of the developer who created the
666 tag, while signed commits make it nearly impossible for someone to
667 impersonate you without having access to your PGP keys.
669 .. _`nothing to do with it`: https://github.com/jayphelps/git-blame-someone-else
671 Configure git to use your PGP key
672 ---------------------------------
674 If you only have one secret key in your keyring, then you don't really
675 need to do anything extra, as it becomes your default key. However, if
676 you happen to have multiple secret keys, you can tell git which key
677 should be used (``[fpr]`` is the fingerprint of your key)::
679 $ git config --global user.signingKey [fpr]
681 How to work with signed tags
682 ----------------------------
684 To create a signed tag, simply pass the ``-s`` switch to the tag
687 $ git tag -s [tagname]
689 Our recommendation is to always sign git tags, as this allows other
690 developers to ensure that the git repository they are pulling from has
691 not been maliciously altered.
693 How to verify signed tags
694 ~~~~~~~~~~~~~~~~~~~~~~~~~
696 To verify a signed tag, simply use the ``verify-tag`` command::
698 $ git verify-tag [tagname]
700 If you are pulling a tag from another fork of the project repository,
701 git should automatically verify the signature at the tip you're pulling
702 and show you the results during the merge operation::
704 $ git pull [url] tags/sometag
706 The merge message will contain something like this::
708 Merge tag 'sometag' of [url]
712 # gpg: Signature made [...]
713 # gpg: Good signature from [...]
715 If you are verifying someone else's git tag, then you will need to
716 import their PGP key. Please refer to the
717 ":ref:`verify_identities`" section below.
719 Configure git to always sign annotated tags
720 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
722 Chances are, if you're creating an annotated tag, you'll want to sign
723 it. To force git to always sign annotated tags, you can set a global
724 configuration option::
726 $ git config --global tag.forceSignAnnotated true
728 How to work with signed commits
729 -------------------------------
731 It is easy to create signed commits, but it is much more difficult to
732 use them in Linux kernel development, since it relies on patches sent to
733 the mailing list, and this workflow does not preserve PGP commit
734 signatures. Furthermore, when rebasing your repository to match
735 upstream, even your own PGP commit signatures will end up discarded. For
736 this reason, most kernel developers don't bother signing their commits
737 and will ignore signed commits in any external repositories that they
738 rely upon in their work.
740 However, if you have your working git tree publicly available at some
741 git hosting service (kernel.org, infradead.org, ozlabs.org, or others),
742 then the recommendation is that you sign all your git commits even if
743 upstream developers do not directly benefit from this practice.
745 We recommend this for the following reasons:
747 1. Should there ever be a need to perform code forensics or track code
748 provenance, even externally maintained trees carrying PGP commit
749 signatures will be valuable for such purposes.
750 2. If you ever need to re-clone your local repository (for example,
751 after a disk failure), this lets you easily verify the repository
752 integrity before resuming your work.
753 3. If someone needs to cherry-pick your commits, this allows them to
754 quickly verify their integrity before applying them.
756 Creating signed commits
757 ~~~~~~~~~~~~~~~~~~~~~~~
759 To create a signed commit, you just need to pass the ``-S`` flag to the
760 ``git commit`` command (it's capital ``-S`` due to collision with
765 Configure git to always sign commits
766 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
768 You can tell git to always sign commits::
770 git config --global commit.gpgSign true
774 Make sure you configure ``gpg-agent`` before you turn this on.
776 .. _verify_identities:
779 How to work with signed patches
780 -------------------------------
782 It is possible to use your PGP key to sign patches sent to kernel
783 developer mailing lists. Since existing email signature mechanisms
784 (PGP-Mime or PGP-inline) tend to cause problems with regular code
785 review tasks, you should use the tool kernel.org created for this
786 purpose that puts cryptographic attestation signatures into message
789 - `Patatt Patch Attestation`_
791 .. _`Patatt Patch Attestation`: https://pypi.org/project/patatt/
793 Installing and configuring patatt
794 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
796 Patatt is packaged for many distributions already, so please check there
797 first. You can also install it from pypi using "``pip install patatt``".
799 If you already have your PGP key configured with git (via the
800 ``user.signingKey`` configuration parameter), then patatt requires no
801 further configuration. You can start signing your patches by installing
802 the git-send-email hook in the repository you want::
806 Now any patches you send with ``git send-email`` will be automatically
807 signed with your cryptographic signature.
809 Checking patatt signatures
810 ~~~~~~~~~~~~~~~~~~~~~~~~~~
812 If you are using ``b4`` to retrieve and apply patches, then it will
813 automatically attempt to verify all DKIM and patatt signatures it
814 encounters, for example::
816 $ b4 am 20220720205013.890942-1-broonie@kernel.org
818 Checking attestation on all messages, may take a moment...
820 ✓ [PATCH v1 1/3] kselftest/arm64: Correct buffer allocation for SVE Z registers
821 ✓ [PATCH v1 2/3] arm64/sve: Document our actual ABI for clearing registers on syscall
822 ✓ [PATCH v1 3/3] kselftest/arm64: Enforce actual ABI for SVE syscalls
824 ✓ Signed: openpgp/broonie@kernel.org
825 ✓ Signed: DKIM/kernel.org
829 Patatt and b4 are still in active development and you should check
830 the latest documentation for these projects for any new or updated
833 .. _kernel_identities:
835 How to verify kernel developer identities
836 =========================================
838 Signing tags and commits is easy, but how does one go about verifying
839 that the key used to sign something belongs to the actual kernel
840 developer and not to a malicious imposter?
842 Configure auto-key-retrieval using WKD and DANE
843 -----------------------------------------------
845 If you are not already someone with an extensive collection of other
846 developers' public keys, then you can jumpstart your keyring by relying
847 on key auto-discovery and auto-retrieval. GnuPG can piggyback on other
848 delegated trust technologies, namely DNSSEC and TLS, to get you going if
849 the prospect of starting your own Web of Trust from scratch is too
852 Add the following to your ``~/.gnupg/gpg.conf``::
854 auto-key-locate wkd,dane,local
857 DNS-Based Authentication of Named Entities ("DANE") is a method for
858 publishing public keys in DNS and securing them using DNSSEC signed
859 zones. Web Key Directory ("WKD") is the alternative method that uses
860 https lookups for the same purpose. When using either DANE or WKD for
861 looking up public keys, GnuPG will validate DNSSEC or TLS certificates,
862 respectively, before adding auto-retrieved public keys to your local
865 Kernel.org publishes the WKD for all developers who have kernel.org
866 accounts. Once you have the above changes in your ``gpg.conf``, you can
867 auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you
868 don't already have them)::
870 $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org
872 If you have a kernel.org account, then you should `add the kernel.org
873 UID to your key`_ to make WKD more useful to other kernel developers.
875 .. _`add the kernel.org UID to your key`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernelorg_uid_to_your_pgp_key
877 Web of Trust (WOT) vs. Trust on First Use (TOFU)
878 ------------------------------------------------
880 PGP incorporates a trust delegation mechanism known as the "Web of
881 Trust." At its core, this is an attempt to replace the need for
882 centralized Certification Authorities of the HTTPS/TLS world. Instead of
883 various software makers dictating who should be your trusted certifying
884 entity, PGP leaves this responsibility to each user.
886 Unfortunately, very few people understand how the Web of Trust works.
887 While it remains an important aspect of the OpenPGP specification,
888 recent versions of GnuPG (2.2 and above) have implemented an alternative
889 mechanism called "Trust on First Use" (TOFU). You can think of TOFU as
890 "the SSH-like approach to trust." With SSH, the first time you connect
891 to a remote system, its key fingerprint is recorded and remembered. If
892 the key changes in the future, the SSH client will alert you and refuse
893 to connect, forcing you to make a decision on whether you choose to
894 trust the changed key or not. Similarly, the first time you import
895 someone's PGP key, it is assumed to be valid. If at any point in the
896 future GnuPG comes across another key with the same identity, both the
897 previously imported key and the new key will be marked as invalid and
898 you will need to manually figure out which one to keep.
900 We recommend that you use the combined TOFU+PGP trust model (which is
901 the new default in GnuPG v2). To set it, add (or modify) the
902 ``trust-model`` setting in ``~/.gnupg/gpg.conf``::
906 Using the kernel.org web of trust repository
907 --------------------------------------------
909 Kernel.org maintains a git repository with developers' public keys as a
910 replacement for replicating keyserver networks that have gone mostly
911 dark in the past few years. The full documentation for how to set up
912 that repository as your source of public keys can be found here:
914 - `Kernel developer PGP Keyring`_
916 If you are a kernel developer, please consider submitting your key for
917 inclusion into that keyring.
919 .. _`Kernel developer PGP Keyring`: https://korg.docs.kernel.org/pgpkeys.html