1.. _pgpguide:
2
3===========================
4Kernel Maintainer PGP guide
5===========================
6
7:Author: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
8
9This document is aimed at Linux kernel developers, and especially at
10subsystem maintainers. It contains a subset of information discussed in
11the more general "`Protecting Code Integrity`_" guide published by the
12Linux Foundation. Please read that document for more in-depth discussion
13on some of the topics mentioned in this guide.
14
15.. _`Protecting Code Integrity`: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md
16
17The role of PGP in Linux Kernel development
18===========================================
19
20PGP helps ensure the integrity of the code that is produced by the Linux
21kernel development community and, to a lesser degree, establish trusted
22communication 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 kernel
30developers who create official kernel releases. These signatures offer a
31cryptographic guarantee that downloadable versions made available via
32kernel.org or any other mirrors are identical to what these developers
33have on their workstations. To this end:
34
35- git repositories provide PGP signatures on all tags
36- tarballs provide detached PGP signatures with all downloads
37
38.. _devs_not_infra:
39
40Trusting the developers, not infrastructure
41-------------------------------------------
42
43Ever since the 2011 compromise of core kernel.org systems, the main
44operating principle of the Kernel Archives project has been to assume
45that any part of the infrastructure can be compromised at any time. For
46this reason, the administrators have taken deliberate steps to emphasize
47that trust must always be placed with developers and never with the code
48hosting infrastructure, regardless of how good the security practices
49for the latter may be.
50
51The above guiding principle is the reason why this guide is needed. We
52want to make sure that by placing trust into developers we do not simply
53shift the blame for potential future security incidents to someone else.
54The goal is to provide a set of guidelines developers can use to create
55a secure working environment and safeguard the PGP keys used to
56establish the integrity of the Linux kernel itself.
57
58.. _pgp_tools:
59
60PGP tools
61=========
62
63Use GnuPG 2.2 or later
64----------------------
65
66Your distro should already have GnuPG installed by default, you just
67need to verify that you are using a reasonably recent version of it.
68To check, run::
69
70    $ gpg --version | head -n1
71
72If you have version 2.2 or above, then you are good to go. If you have a
73version that is prior than 2.2, then some commands from this guide may
74not work.
75
76Configure gpg-agent options
77~~~~~~~~~~~~~~~~~~~~~~~~~~~
78
79The GnuPG agent is a helper tool that will start automatically whenever
80you use the ``gpg`` command and run in the background with the purpose
81of caching the private key passphrase. There are two options you should
82know 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 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.
91
92If you find either of these defaults too short (or too long), you can
93edit 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 ttl
96    default-cache-ttl 1800
97    max-cache-ttl 7200
98
99.. note::
100
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.
105
106.. _protect_your_key:
107
108Protect your PGP key
109====================
110
111This guide assumes that you already have a PGP key that you use for Linux
112kernel development purposes. If you do not yet have one, please see the
113"`Protecting Code Integrity`_" document mentioned earlier for guidance
114on how to create a new one.
115
116You should also make a new key if your current one is weaker than 2048
117bits (RSA).
118
119Understanding PGP Subkeys
120-------------------------
121
122A PGP key rarely consists of a single keypair -- usually it is a
123collection of independent subkeys that can be used for different
124purposes 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 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
131
132The key with the **[C]** capability is often called the "master" key,
133but this terminology is misleading because it implies that the Certify
134key can be used in place of any of other subkey on the same chain (like
135a 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 Certify
137key" 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 a
142   private subkey, it cannot be restored or recreated from any other
143   private key on your chain.
1442. 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
149   you may also have.
1503. A single subkey may have multiple capabilities (e.g. your **[C]** key
151   can also be your **[S]** key).
152
153The key carrying the **[C]** (certify) capability is the only key that
154can 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 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
161
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 that
168is 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          000000000000000000000000AAAABBBBCCCCDDDD
173    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-character
178string is what it refers to.
179
180Ensure your passphrase is strong
181--------------------------------
182
183GnuPG uses passphrases to encrypt your private keys before storing them on
184disk. This way, even if your ``.gnupg`` directory is leaked or stolen in
185its entirety, the attackers cannot use your private keys without first
186obtaining the passphrase to decrypt them.
187
188It is absolutely essential that your private keys are protected by a
189strong passphrase. To set it or change it, use::
190
191    $ gpg --change-passphrase [fpr]
192
193Create a separate Signing subkey
194--------------------------------
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 a
198separate signing subkey::
199
200    $ gpg --quick-addkey [fpr] ed25519 sign
201
202.. note:: ECC support in GnuPG
203
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.
207
208
209Back up your Certify key for disaster recovery
210----------------------------------------------
211
212The more signatures you have on your PGP key from other developers, the
213more reasons you have to create a backup version that lives on something
214other than digital media, for disaster recovery reasons.
215
216The best way to create a printable hardcopy of your private key is by
217using the ``paperkey`` software written for this very purpose. See ``man
218paperkey`` for more details on the output format and its benefits over
219other solutions. Paperkey should already be packaged for most
220distributions.
221
222Run the following command to create a hardcopy backup of your private
223key::
224
225    $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt
226
227Print out that file (or pipe the output straight to lpr), then take a
228pen and write your passphrase on the margin of the paper. **This is
229strongly recommended** because the key printout is still encrypted with
230that passphrase, and if you ever change it you will not remember what it
231used to be when you had created the backup -- *guaranteed*.
232
233Put the resulting printout and the hand-written passphrase into an envelope
234and store in a secure and well-protected place, preferably away from your
235home, such as your bank vault.
236
237.. note::
238
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.
243
244Back up your whole GnuPG directory
245----------------------------------
246
247.. warning::
248
249    **!!!Do not skip this step!!!**
250
251It is important to have a readily available backup of your PGP keys
252should you need to recover them. This is different from the
253disaster-level preparedness we did with ``paperkey``. You will also rely
254on these external copies whenever you need to use your Certify key --
255such as when making changes to your own key or signing other people's
256keys after conferences and summits.
257
258Start by getting a small USB "thumb" drive (preferably two!) that you
259will use for backup purposes. You will need to encrypt them using LUKS
260-- refer to your distro's documentation on how to accomplish this.
261
262For the encryption passphrase, you can use the same one as on your
263PGP key.
264
265Once the encryption process is over, re-insert the USB drive and make
266sure it gets properly mounted. Copy your entire ``.gnupg`` directory
267over to the encrypted storage::
268
269    $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup
270
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 the
276USB drive, distinctly label it so you don't blow it away next time you
277need to use a random USB drive, and put in a safe place -- but not too
278far away, because you'll need to use it every now and again for things
279like editing identities, adding or revoking subkeys, or signing other
280people's keys.
281
282Remove the Certify key from your homedir
283----------------------------------------
284
285The files in our home directory are not as well protected as we like to
286think.  They can be leaked or stolen via many different means:
287
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
293
294Protecting your key with a good passphrase greatly helps reduce the risk
295of any of the above, but passphrases can be discovered via keyloggers,
296shoulder-surfing, or any number of other means. For this reason, the
297recommended setup is to remove your Certify key from your home directory
298and store it on offline storage.
299
300.. warning::
301
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!
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          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
320
321Find the keygrip entry that is beneath the ``pub`` line (right under the
322Certify key fingerprint). This will correspond directly to a file in your
323``~/.gnupg`` directory::
324
325    $ cd ~/.gnupg/private-keys-v1.d
326    $ ls
327    1111000000000000000000000000000000000000.key
328    2222000000000000000000000000000000000000.key
329    3333000000000000000000000000000000000000.key
330
331All you have to do is simply remove the .key file that corresponds to
332the Certify key keygrip::
333
334    $ cd ~/.gnupg/private-keys-v1.d
335    $ rm 1111000000000000000000000000000000000000.key
336
337Now, if you issue the ``--list-secret-keys`` command, it will show that
338the Certify key is missing (the ``#`` indicates it is not available)::
339
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]
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" directory
351~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
352
353If you do not have a ``~/.gnupg/private-keys-v1.d`` directory, then your
354secret keys are still stored in the legacy ``secring.gpg`` file used by
355GnuPG v1. Making any changes to your key, such as changing the
356passphrase or adding a subkey, should automatically convert the old
357``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 device
365=============================================
366
367Even though the Certify key is now safe from being leaked or stolen, the
368subkeys are still in your home directory. Anyone who manages to get
369their hands on those will be able to decrypt your communication or fake
370your signatures (if they know the passphrase). Furthermore, each time a
371GnuPG operation is performed, the keys are loaded into system memory and
372can be stolen from there by sufficiently advanced malware (think
373Meltdown and Spectre).
374
375The best way to completely protect your keys is to move them to a
376specialized hardware device that is capable of smartcard operations.
377
378The benefits of smartcards
379--------------------------
380
381A smartcard contains a cryptographic chip that is capable of storing
382private keys and performing crypto operations directly on the card
383itself. Because the key contents never leave the smartcard, the
384operating system of the computer into which you plug in the hardware
385device is not able to retrieve the private keys themselves. This is very
386different from the encrypted USB storage device we used earlier for
387backup purposes -- while that USB device is plugged in and mounted, the
388operating system is able to access the private key contents.
389
390Using external encrypted USB media is not a substitute to having a
391smartcard-capable device.
392
393Available smartcard devices
394---------------------------
395
396Unless all your laptops and workstations have smartcard readers, the
397easiest is to get a specialized USB device that implements smartcard
398functionality. There are several options available:
399
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
411  keys.
412
413Your choice will depend on cost, shipping availability in your
414geographical 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 Linux
420    Foundation.
421
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
427
428Configure your smartcard device
429-------------------------------
430
431Your smartcard device should Just Work (TM) the moment you plug it into
432any modern Linux workstation. You can verify it by running::
433
434    $ gpg --card-status
435
436If you see full smartcard details, then you are good to go.
437Unfortunately, troubleshooting all possible reasons why things may not
438be working for you is way beyond the scope of this guide. If you are
439having trouble getting the card to work with GnuPG, please seek help via
440usual support channels.
441
442To configure your smartcard, you will need to use the GnuPG menu system, as
443there are no convenient command-line switches::
444
445    $ gpg --card-edit
446    [...omitted...]
447    gpg/card> admin
448    Admin commands are allowed
449    gpg/card> passwd
450
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 -- especially
453the Admin PIN and the Reset Code (which allows you to completely wipe
454the smartcard). You so rarely need to use the Admin PIN, that you will
455inevitably forget what it is if you do not record it.
456
457Getting back to the main card menu, you can also set other values (such
458as name, sex, login data, etc), but it's not necessary and will
459additionally 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 admin
464    PIN on the card need to be numbers.
465
466.. warning::
467
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.
471
472Move the subkeys to your smartcard
473----------------------------------
474
475Exit the card menu (using "q") and save all changes. Next, let's move
476your subkeys onto the smartcard. You will need both your PGP key
477passphrase 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/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>
491
492    gpg>
493
494Using ``--edit-key`` puts us into the menu mode again, and you will
495notice that the key listing is a little different. From here on, all
496commands 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 do
499this by typing ``key 1`` (it's the first one in the listing, the **[E]**
500subkey)::
501
502    gpg> key 1
503
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 and
507the key will not be selected any more.
508
509Now, let's move that key onto the smartcard::
510
511    gpg> keytocard
512    Please select where to store the key:
513       (2) Encryption key
514    Your selection? 2
515
516Since it's our **[E]** key, it makes sense to put it into the Encryption
517slot.  When you submit your selection, you will be prompted first for
518your PGP key passphrase, and then for the admin PIN. If the command
519returns without an error, your key has been moved.
520
521**Important**: Now type ``key 1`` again to unselect the first key, and
522``key 2`` to select the **[S]** key::
523
524    gpg> key 1
525    gpg> key 2
526    gpg> keytocard
527    Please select where to store the key:
528       (1) Signature key
529       (3) Authentication key
530    Your selection? 1
531
532You can use the **[S]** key both for Signature and Authentication, but
533we want to make sure it's in the Signature slot, so choose (1). Once
534again, if your command returns without an error, then the operation was
535successful::
536
537    gpg> q
538    Save changes? (y/N) y
539
540Saving the changes will delete the keys you moved to the card from your
541home directory (but it's okay, because we have them in our backups
542should we need to do this again for a replacement smartcard).
543
544Verifying that the keys were moved
545~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
546
547If you perform ``--list-secret-keys`` now, you will see a subtle
548difference in the output::
549
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]
556
557The ``>`` in the ``ssb>`` output indicates that the subkey is only
558available on the smartcard. If you go back into your secret keys
559directory and look at the contents there, you will notice that the
560``.key`` files there have been replaced with stubs::
561
562    $ cd ~/.gnupg/private-keys-v1.d
563    $ strings *.key | grep 'private-key'
564
565The output should contain ``shadowed-private-key`` to indicate that
566these files are only stubs and the actual content is on the smartcard.
567
568Verifying that the smartcard is functioning
569~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
570
571To verify that the smartcard is working as intended, you can create a
572signature::
573
574    $ echo "Hello world" | gpg --clearsign > /tmp/test.asc
575    $ gpg --verify /tmp/test.asc
576
577This should ask for your smartcard PIN on your first command, and then
578show "Good signature" after you run ``gpg --verify``.
579
580Congratulations, you have successfully made it extremely difficult to
581steal your digital developer identity!
582
583Other common GnuPG operations
584-----------------------------
585
586Here is a quick reference for some common operations you'll need to do
587with your PGP key.
588
589Mounting your safe offline storage
590~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
591
592You will need your Certify key for any of the operations below, so you
593will first need to mount your backup offline storage and tell GnuPG to
594use it::
595
596    $ export GNUPGHOME=/media/disk/foo/gnupg-backup
597    $ gpg --list-secret-keys
598
599You want to make sure that you see ``sec`` and not ``sec#`` in the
600output (the ``#`` means the key is not available and you're still using
601your regular home directory location).
602
603Extending key expiration date
604~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
605
606The Certify key has the default expiration date of 2 years from the date
607of creation. This is done both for security reasons and to make obsolete
608keys eventually disappear from keyservers.
609
610To extend the expiration on your key by a year from current date, just
611run::
612
613    $ gpg --quick-set-expire [fpr] 1y
614
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-01
619
620Remember to send the updated key back to keyservers::
621
622    $ gpg --send-key [fpr]
623
624Updating your work directory after any changes
625~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
626
627After you make any changes to your key using the offline storage, you will
628want to import these changes back into your regular working directory::
629
630    $ gpg --export | gpg --homedir ~/.gnupg --import
631    $ unset GNUPGHOME
632
633Using gpg-agent over ssh
634~~~~~~~~~~~~~~~~~~~~~~~~
635
636You can forward your gpg-agent over ssh if you need to sign tags or
637commits on a remote system. Please refer to the instructions provided
638on the GnuPG wiki:
639
640- `Agent Forwarding over SSH`_
641
642It works more smoothly if you can modify the sshd server settings on the
643remote end.
644
645.. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding
646
647.. _pgp_with_git:
648
649Using PGP with Git
650==================
651
652One of the core features of Git is its decentralized nature -- once a
653repository is cloned to your system, you have full history of the
654project, including all of its tags, commits and branches. However, with
655hundreds of cloned repositories floating around, how does anyone verify
656that their copy of linux.git has not been tampered with by a malicious
657third 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 you
661had `nothing to do with it`_?
662
663To address both of these issues, Git introduced PGP integration. Signed
664tags prove the repository integrity by assuring that its contents are
665exactly the same as on the workstation of the developer who created the
666tag, while signed commits make it nearly impossible for someone to
667impersonate you without having access to your PGP keys.
668
669.. _`nothing to do with it`: https://github.com/jayphelps/git-blame-someone-else
670
671Configure git to use your PGP key
672---------------------------------
673
674If you only have one secret key in your keyring, then you don't really
675need to do anything extra, as it becomes your default key.  However, if
676you happen to have multiple secret keys, you can tell git which key
677should be used (``[fpr]`` is the fingerprint of your key)::
678
679    $ git config --global user.signingKey [fpr]
680
681How to work with signed tags
682----------------------------
683
684To create a signed tag, simply pass the ``-s`` switch to the tag
685command::
686
687    $ git tag -s [tagname]
688
689Our recommendation is to always sign git tags, as this allows other
690developers to ensure that the git repository they are pulling from has
691not been maliciously altered.
692
693How to verify signed tags
694~~~~~~~~~~~~~~~~~~~~~~~~~
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 pulling
702and show you the results during the merge operation::
703
704    $ git pull [url] tags/sometag
705
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 to
716import their PGP key. Please refer to the
717":ref:`verify_identities`" section below.
718
719Configure git to always sign annotated tags
720~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
721
722Chances are, if you're creating an annotated tag, you'll want to sign
723it. To force git to always sign annotated tags, you can set a global
724configuration option::
725
726    $ git config --global tag.forceSignAnnotated true
727
728How to work with signed commits
729-------------------------------
730
731It is easy to create signed commits, but it is much more difficult to
732use them in Linux kernel development, since it relies on patches sent to
733the mailing list, and this workflow does not preserve PGP commit
734signatures. Furthermore, when rebasing your repository to match
735upstream, even your own PGP commit signatures will end up discarded. For
736this reason, most kernel developers don't bother signing their commits
737and will ignore signed commits in any external repositories that they
738rely upon in their work.
739
740However, if you have your working git tree publicly available at some
741git hosting service (kernel.org, infradead.org, ozlabs.org, or others),
742then the recommendation is that you sign all your git commits even if
743upstream 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 code
748   provenance, even externally maintained trees carrying PGP commit
749   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 repository
752   integrity before resuming your work.
7533. If someone needs to cherry-pick your commits, this allows them to
754   quickly verify their integrity before applying them.
755
756Creating signed commits
757~~~~~~~~~~~~~~~~~~~~~~~
758
759To 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
761another flag)::
762
763    $ git commit -S
764
765Configure git to always sign commits
766~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
767
768You can tell git to always sign commits::
769
770    git config --global commit.gpgSign true
771
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 patches
780-------------------------------
781
782It is possible to use your PGP key to sign patches sent to kernel
783developer mailing lists. Since existing email signature mechanisms
784(PGP-Mime or PGP-inline) tend to cause problems with regular code
785review tasks, you should use the tool kernel.org created for this
786purpose that puts cryptographic attestation signatures into message
787headers (a-la DKIM):
788
789- `Patatt Patch Attestation`_
790
791.. _`Patatt Patch Attestation`: https://pypi.org/project/patatt/
792
793Installing and configuring patatt
794~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
795
796Patatt is packaged for many distributions already, so please check there
797first. You can also install it from pypi using "``pip install patatt``".
798
799If you already have your PGP key configured with git (via the
800``user.signingKey`` configuration parameter), then patatt requires no
801further configuration. You can start signing your patches by installing
802the git-send-email hook in the repository you want::
803
804    patatt install-hook
805
806Now any patches you send with ``git send-email`` will be automatically
807signed with your cryptographic signature.
808
809Checking patatt signatures
810~~~~~~~~~~~~~~~~~~~~~~~~~~
811
812If you are using ``b4`` to retrieve and apply patches, then it will
813automatically attempt to verify all DKIM and patatt signatures it
814encounters, for example::
815
816    $ b4 am 20220720205013.890942-1-broonie@kernel.org
817    [...]
818    Checking attestation on all messages, may take a moment...
819    ---
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
823      ---
824      ✓ Signed: openpgp/broonie@kernel.org
825      ✓ Signed: DKIM/kernel.org
826
827.. note::
828
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
831    features.
832
833.. _kernel_identities:
834
835How to verify kernel developer identities
836=========================================
837
838Signing tags and commits is easy, but how does one go about verifying
839that the key used to sign something belongs to the actual kernel
840developer and not to a malicious imposter?
841
842Configure auto-key-retrieval using WKD and DANE
843-----------------------------------------------
844
845If you are not already someone with an extensive collection of other
846developers' public keys, then you can jumpstart your keyring by relying
847on key auto-discovery and auto-retrieval. GnuPG can piggyback on other
848delegated trust technologies, namely DNSSEC and TLS, to get you going if
849the prospect of starting your own Web of Trust from scratch is too
850daunting.
851
852Add the following to your ``~/.gnupg/gpg.conf``::
853
854    auto-key-locate wkd,dane,local
855    auto-key-retrieve
856
857DNS-Based Authentication of Named Entities ("DANE") is a method for
858publishing public keys in DNS and securing them using DNSSEC signed
859zones. Web Key Directory ("WKD") is the alternative method that uses
860https lookups for the same purpose. When using either DANE or WKD for
861looking up public keys, GnuPG will validate DNSSEC or TLS certificates,
862respectively, before adding auto-retrieved public keys to your local
863keyring.
864
865Kernel.org publishes the WKD for all developers who have kernel.org
866accounts. Once you have the above changes in your ``gpg.conf``, you can
867auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you
868don't already have them)::
869
870    $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org
871
872If you have a kernel.org account, then you should `add the kernel.org
873UID 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_key
876
877Web of Trust (WOT) vs. Trust on First Use (TOFU)
878------------------------------------------------
879
880PGP incorporates a trust delegation mechanism known as the "Web of
881Trust." At its core, this is an attempt to replace the need for
882centralized Certification Authorities of the HTTPS/TLS world. Instead of
883various software makers dictating who should be your trusted certifying
884entity, 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 alternative
889mechanism 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
891to a remote system, its key fingerprint is recorded and remembered. If
892the key changes in the future, the SSH client will alert you and refuse
893to connect, forcing you to make a decision on whether you choose to
894trust the changed key or not. Similarly, the first time you import
895someone's PGP key, it is assumed to be valid. If at any point in the
896future GnuPG comes across another key with the same identity, both the
897previously imported key and the new key will be marked as invalid and
898you will need to manually figure out which one to keep.
899
900We recommend that you use the combined TOFU+PGP trust model (which is
901the new default in GnuPG v2). To set it, add (or modify) the
902``trust-model`` setting in ``~/.gnupg/gpg.conf``::
903
904    trust-model tofu+pgp
905
906Using the kernel.org web of trust repository
907--------------------------------------------
908
909Kernel.org maintains a git repository with developers' public keys as a
910replacement for replicating keyserver networks that have gone mostly
911dark in the past few years. The full documentation for how to set up
912that 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 for
917inclusion into that keyring.
918
919.. _`Kernel developer PGP Keyring`: https://korg.docs.kernel.org/pgpkeys.html
920