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 v2
64------------
65
66Your distro should already have GnuPG installed by default, you just
67need to verify that you are using version 2.x and not the legacy 1.4
68release -- many distributions still package both, with the default
69``gpg`` command invoking GnuPG v.1. To check, run::
70
71    $ gpg --version | head -n1
72
73If you see ``gpg (GnuPG) 1.4.x``, then you are using GnuPG v.1. Try the
74``gpg2`` command (if you don't have it, you may need to install the
75gnupg2 package)::
76
77    $ gpg2 --version | head -n1
78
79If you see ``gpg (GnuPG) 2.x.x``, then you are good to go. This guide
80will assume you have the version 2.2 of GnuPG (or later). If you are
81using version 2.0 of GnuPG, then some of the commands in this guide will
82not work, and you should consider installing the latest 2.2 version of
83GnuPG. Versions of gnupg-2.1.11 and later should be compatible for the
84purposes of this guide as well.
85
86If you have both ``gpg`` and ``gpg2`` commands, you should make sure you
87are always using GnuPG v2, not the legacy version. You can enforce this
88by setting the appropriate alias::
89
90    $ alias gpg=gpg2
91
92You can put that in your ``.bashrc`` to make sure it's always the case.
93
94Configure gpg-agent options
95~~~~~~~~~~~~~~~~~~~~~~~~~~~
96
97The GnuPG agent is a helper tool that will start automatically whenever
98you use the ``gpg`` command and run in the background with the purpose
99of caching the private key passphrase. There are two options you should
100know in order to tweak when the passphrase should be expired from cache:
101
102- ``default-cache-ttl`` (seconds): If you use the same key again before
103  the time-to-live expires, the countdown will reset for another period.
104  The default is 600 (10 minutes).
105- ``max-cache-ttl`` (seconds): Regardless of how recently you've used
106  the key since initial passphrase entry, if the maximum time-to-live
107  countdown expires, you'll have to enter the passphrase again. The
108  default is 30 minutes.
109
110If you find either of these defaults too short (or too long), you can
111edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values::
112
113    # set to 30 minutes for regular ttl, and 2 hours for max ttl
114    default-cache-ttl 1800
115    max-cache-ttl 7200
116
117.. note::
118
119    It is no longer necessary to start gpg-agent manually at the
120    beginning of your shell session. You may want to check your rc files
121    to remove anything you had in place for older versions of GnuPG, as
122    it may not be doing the right thing any more.
123
124Set up a refresh cronjob
125~~~~~~~~~~~~~~~~~~~~~~~~
126
127You will need to regularly refresh your keyring in order to get the
128latest changes on other people's public keys, which is best done with a
129daily cronjob::
130
131    @daily /usr/bin/gpg2 --refresh >/dev/null 2>&1
132
133Check the full path to your ``gpg`` or ``gpg2`` command and use the
134``gpg2`` command if regular ``gpg`` for you is the legacy GnuPG v.1.
135
136.. _master_key:
137
138Protect your master PGP key
139===========================
140
141This guide assumes that you already have a PGP key that you use for Linux
142kernel development purposes. If you do not yet have one, please see the
143"`Protecting Code Integrity`_" document mentioned earlier for guidance
144on how to create a new one.
145
146You should also make a new key if your current one is weaker than 2048 bits
147(RSA).
148
149Master key vs. Subkeys
150----------------------
151
152Subkeys are fully independent PGP keypairs that are tied to the "master"
153key using certifying key signatures (certificates). It is important to
154understand the following:
155
1561. There are no technical differences between the "master key" and "subkeys."
1572. At creation time, we assign functional limitations to each key by
158   giving it specific capabilities.
1593. A PGP key can have 4 capabilities:
160
161   - **[S]** key can be used for signing
162   - **[E]** key can be used for encryption
163   - **[A]** key can be used for authentication
164   - **[C]** key can be used for certifying other keys
165
1664. A single key may have multiple capabilities.
1675. A subkey is fully independent from the master key. A message
168   encrypted to a subkey cannot be decrypted with the master key. If you
169   lose your private subkey, it cannot be recreated from the master key
170   in any way.
171
172The key carrying the **[C]** (certify) capability is considered the
173"master" key because it is the only key that can be used to indicate
174relationship with other keys. Only the **[C]** key can be used to:
175
176- add or revoke other keys (subkeys) with S/E/A capabilities
177- add, change or revoke identities (uids) associated with the key
178- add or change the expiration date on itself or any subkey
179- sign other people's keys for web of trust purposes
180
181By default, GnuPG creates the following when generating new keys:
182
183- A master key carrying both Certify and Sign capabilities (**[SC]**)
184- A separate subkey with the Encryption capability (**[E]**)
185
186If you used the default parameters when generating your key, then that
187is what you will have. You can verify by running ``gpg --list-secret-keys``,
188for example::
189
190    sec   rsa2048 2018-01-23 [SC] [expires: 2020-01-23]
191          000000000000000000000000AAAABBBBCCCCDDDD
192    uid           [ultimate] Alice Dev <adev@kernel.org>
193    ssb   rsa2048 2018-01-23 [E] [expires: 2020-01-23]
194
195Any key carrying the **[C]** capability is your master key, regardless
196of any other capabilities it may have assigned to it.
197
198The long line under the ``sec`` entry is your key fingerprint --
199whenever you see ``[fpr]`` in the examples below, that 40-character
200string is what it refers to.
201
202Ensure your passphrase is strong
203--------------------------------
204
205GnuPG uses passphrases to encrypt your private keys before storing them on
206disk. This way, even if your ``.gnupg`` directory is leaked or stolen in
207its entirety, the attackers cannot use your private keys without first
208obtaining the passphrase to decrypt them.
209
210It is absolutely essential that your private keys are protected by a
211strong passphrase. To set it or change it, use::
212
213    $ gpg --change-passphrase [fpr]
214
215Create a separate Signing subkey
216--------------------------------
217
218Our goal is to protect your master key by moving it to offline media, so
219if you only have a combined **[SC]** key, then you should create a separate
220signing subkey::
221
222    $ gpg --quick-addkey [fpr] ed25519 sign
223
224Remember to tell the keyservers about this change, so others can pull down
225your new subkey::
226
227    $ gpg --send-key [fpr]
228
229.. note:: ECC support in GnuPG
230
231    GnuPG 2.1 and later has full support for Elliptic Curve
232    Cryptography, with ability to combine ECC subkeys with traditional
233    RSA master keys. The main upside of ECC cryptography is that it is
234    much faster computationally and creates much smaller signatures when
235    compared byte for byte with 2048+ bit RSA keys. Unless you plan on
236    using a smartcard device that does not support ECC operations, we
237    recommend that you create an ECC signing subkey for your kernel
238    work.
239
240    If for some reason you prefer to stay with RSA subkeys, just replace
241    "ed25519" with "rsa2048" in the above command. Additionally, if you
242    plan to use a hardware device that does not support ED25519 ECC
243    keys, like Nitrokey Pro or a Yubikey, then you should use
244    "nistp256" instead or "ed25519."
245
246
247Back up your master key for disaster recovery
248---------------------------------------------
249
250The more signatures you have on your PGP key from other developers, the
251more reasons you have to create a backup version that lives on something
252other than digital media, for disaster recovery reasons.
253
254The best way to create a printable hardcopy of your private key is by
255using the ``paperkey`` software written for this very purpose. See ``man
256paperkey`` for more details on the output format and its benefits over
257other solutions. Paperkey should already be packaged for most
258distributions.
259
260Run the following command to create a hardcopy backup of your private
261key::
262
263    $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt
264
265Print out that file (or pipe the output straight to lpr), then take a
266pen and write your passphrase on the margin of the paper. **This is
267strongly recommended** because the key printout is still encrypted with
268that passphrase, and if you ever change it you will not remember what it
269used to be when you had created the backup -- *guaranteed*.
270
271Put the resulting printout and the hand-written passphrase into an envelope
272and store in a secure and well-protected place, preferably away from your
273home, such as your bank vault.
274
275.. note::
276
277    Your printer is probably no longer a simple dumb device connected to
278    your parallel port, but since the output is still encrypted with
279    your passphrase, printing out even to "cloud-integrated" modern
280    printers should remain a relatively safe operation. One option is to
281    change the passphrase on your master key immediately after you are
282    done with paperkey.
283
284Back up your whole GnuPG directory
285----------------------------------
286
287.. warning::
288
289    **!!!Do not skip this step!!!**
290
291It is important to have a readily available backup of your PGP keys
292should you need to recover them. This is different from the
293disaster-level preparedness we did with ``paperkey``. You will also rely
294on these external copies whenever you need to use your Certify key --
295such as when making changes to your own key or signing other people's
296keys after conferences and summits.
297
298Start by getting a small USB "thumb" drive (preferably two!) that you
299will use for backup purposes. You will need to encrypt them using LUKS
300-- refer to your distro's documentation on how to accomplish this.
301
302For the encryption passphrase, you can use the same one as on your
303master key.
304
305Once the encryption process is over, re-insert the USB drive and make
306sure it gets properly mounted. Copy your entire ``.gnupg`` directory
307over to the encrypted storage::
308
309    $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup
310
311You should now test to make sure everything still works::
312
313    $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr]
314
315If you don't get any errors, then you should be good to go. Unmount the
316USB drive, distinctly label it so you don't blow it away next time you
317need to use a random USB drive, and put in a safe place -- but not too
318far away, because you'll need to use it every now and again for things
319like editing identities, adding or revoking subkeys, or signing other
320people's keys.
321
322Remove the master key from  your homedir
323----------------------------------------
324
325The files in our home directory are not as well protected as we like to
326think.  They can be leaked or stolen via many different means:
327
328- by accident when making quick homedir copies to set up a new workstation
329- by systems administrator negligence or malice
330- via poorly secured backups
331- via malware in desktop apps (browsers, pdf viewers, etc)
332- via coercion when crossing international borders
333
334Protecting your key with a good passphrase greatly helps reduce the risk
335of any of the above, but passphrases can be discovered via keyloggers,
336shoulder-surfing, or any number of other means. For this reason, the
337recommended setup is to remove your master key from your home directory
338and store it on offline storage.
339
340.. warning::
341
342    Please see the previous section and make sure you have backed up
343    your GnuPG directory in its entirety. What we are about to do will
344    render your key useless if you do not have a usable backup!
345
346First, identify the keygrip of your master key::
347
348    $ gpg --with-keygrip --list-key [fpr]
349
350The output will be something like this::
351
352    pub   rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
353          000000000000000000000000AAAABBBBCCCCDDDD
354          Keygrip = 1111000000000000000000000000000000000000
355    uid           [ultimate] Alice Dev <adev@kernel.org>
356    sub   rsa2048 2018-01-24 [E] [expires: 2020-01-24]
357          Keygrip = 2222000000000000000000000000000000000000
358    sub   ed25519 2018-01-24 [S]
359          Keygrip = 3333000000000000000000000000000000000000
360
361Find the keygrip entry that is beneath the ``pub`` line (right under the
362master key fingerprint). This will correspond directly to a file in your
363``~/.gnupg`` directory::
364
365    $ cd ~/.gnupg/private-keys-v1.d
366    $ ls
367    1111000000000000000000000000000000000000.key
368    2222000000000000000000000000000000000000.key
369    3333000000000000000000000000000000000000.key
370
371All you have to do is simply remove the .key file that corresponds to
372the master keygrip::
373
374    $ cd ~/.gnupg/private-keys-v1.d
375    $ rm 1111000000000000000000000000000000000000.key
376
377Now, if you issue the ``--list-secret-keys`` command, it will show that
378the master key is missing (the ``#`` indicates it is not available)::
379
380    $ gpg --list-secret-keys
381    sec#  rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
382          000000000000000000000000AAAABBBBCCCCDDDD
383    uid           [ultimate] Alice Dev <adev@kernel.org>
384    ssb   rsa2048 2018-01-24 [E] [expires: 2020-01-24]
385    ssb   ed25519 2018-01-24 [S]
386
387You should also remove any ``secring.gpg`` files in the ``~/.gnupg``
388directory, which are left over from earlier versions of GnuPG.
389
390If you don't have the "private-keys-v1.d" directory
391~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
392
393If you do not have a ``~/.gnupg/private-keys-v1.d`` directory, then your
394secret keys are still stored in the legacy ``secring.gpg`` file used by
395GnuPG v1. Making any changes to your key, such as changing the
396passphrase or adding a subkey, should automatically convert the old
397``secring.gpg`` format to use ``private-keys-v1.d`` instead.
398
399Once you get that done, make sure to delete the obsolete ``secring.gpg``
400file, which still contains your private keys.
401
402.. _smartcards:
403
404Move the subkeys to a dedicated crypto device
405=============================================
406
407Even though the master key is now safe from being leaked or stolen, the
408subkeys are still in your home directory. Anyone who manages to get
409their hands on those will be able to decrypt your communication or fake
410your signatures (if they know the passphrase). Furthermore, each time a
411GnuPG operation is performed, the keys are loaded into system memory and
412can be stolen from there by sufficiently advanced malware (think
413Meltdown and Spectre).
414
415The best way to completely protect your keys is to move them to a
416specialized hardware device that is capable of smartcard operations.
417
418The benefits of smartcards
419--------------------------
420
421A smartcard contains a cryptographic chip that is capable of storing
422private keys and performing crypto operations directly on the card
423itself. Because the key contents never leave the smartcard, the
424operating system of the computer into which you plug in the hardware
425device is not able to retrieve the private keys themselves. This is very
426different from the encrypted USB storage device we used earlier for
427backup purposes -- while that USB device is plugged in and mounted, the
428operating system is able to access the private key contents.
429
430Using external encrypted USB media is not a substitute to having a
431smartcard-capable device.
432
433Available smartcard devices
434---------------------------
435
436Unless all your laptops and workstations have smartcard readers, the
437easiest is to get a specialized USB device that implements smartcard
438functionality. There are several options available:
439
440- `Nitrokey Start`_: Open hardware and Free Software, based on FSI
441  Japan's `Gnuk`_. One of the few available commercial devices that
442  support ED25519 ECC keys, but offer fewest security features (such as
443  resistance to tampering or some side-channel attacks).
444- `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more
445  tamper-resistant and offers more security features. Pro 2 supports ECC
446  cryptography (NISTP).
447- `Yubikey 5`_: proprietary hardware and software, but cheaper than
448  Nitrokey Pro and comes available in the USB-C form that is more useful
449  with newer laptops. Offers additional security features such as FIDO
450  U2F, among others, and now finally supports ECC keys (NISTP).
451
452`LWN has a good review`_ of some of the above models, as well as several
453others. Your choice will depend on cost, shipping availability in your
454geographical region, and open/proprietary hardware considerations.
455
456.. note::
457
458    If you are listed in MAINTAINERS or have an account at kernel.org,
459    you `qualify for a free Nitrokey Start`_ courtesy of The Linux
460    Foundation.
461
462.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6
463.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3
464.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/
465.. _Gnuk: http://www.fsij.org/doc-gnuk/
466.. _`LWN has a good review`: https://lwn.net/Articles/736231/
467.. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html
468
469Configure your smartcard device
470-------------------------------
471
472Your smartcard device should Just Work (TM) the moment you plug it into
473any modern Linux workstation. You can verify it by running::
474
475    $ gpg --card-status
476
477If you see full smartcard details, then you are good to go.
478Unfortunately, troubleshooting all possible reasons why things may not
479be working for you is way beyond the scope of this guide. If you are
480having trouble getting the card to work with GnuPG, please seek help via
481usual support channels.
482
483To configure your smartcard, you will need to use the GnuPG menu system, as
484there are no convenient command-line switches::
485
486    $ gpg --card-edit
487    [...omitted...]
488    gpg/card> admin
489    Admin commands are allowed
490    gpg/card> passwd
491
492You should set the user PIN (1), Admin PIN (3), and the Reset Code (4).
493Please make sure to record and store these in a safe place -- especially
494the Admin PIN and the Reset Code (which allows you to completely wipe
495the smartcard). You so rarely need to use the Admin PIN, that you will
496inevitably forget what it is if you do not record it.
497
498Getting back to the main card menu, you can also set other values (such
499as name, sex, login data, etc), but it's not necessary and will
500additionally leak information about your smartcard should you lose it.
501
502.. note::
503
504    Despite having the name "PIN", neither the user PIN nor the admin
505    PIN on the card need to be numbers.
506
507.. warning::
508
509    Some devices may require that you move the subkeys onto the device
510    before you can change the passphrase. Please check the documentation
511    provided by the device manufacturer.
512
513Move the subkeys to your smartcard
514----------------------------------
515
516Exit the card menu (using "q") and save all changes. Next, let's move
517your subkeys onto the smartcard. You will need both your PGP key
518passphrase and the admin PIN of the card for most operations::
519
520    $ gpg --edit-key [fpr]
521
522    Secret subkeys are available.
523
524    pub  rsa2048/AAAABBBBCCCCDDDD
525         created: 2018-01-23  expires: 2020-01-23  usage: SC
526         trust: ultimate      validity: ultimate
527    ssb  rsa2048/1111222233334444
528         created: 2018-01-23  expires: never       usage: E
529    ssb  ed25519/5555666677778888
530         created: 2017-12-07  expires: never       usage: S
531    [ultimate] (1). Alice Dev <adev@kernel.org>
532
533    gpg>
534
535Using ``--edit-key`` puts us into the menu mode again, and you will
536notice that the key listing is a little different. From here on, all
537commands are done from inside this menu mode, as indicated by ``gpg>``.
538
539First, let's select the key we'll be putting onto the card -- you do
540this by typing ``key 1`` (it's the first one in the listing, the **[E]**
541subkey)::
542
543    gpg> key 1
544
545In the output, you should now see ``ssb*`` on the **[E]** key. The ``*``
546indicates which key is currently "selected." It works as a *toggle*,
547meaning that if you type ``key 1`` again, the ``*`` will disappear and
548the key will not be selected any more.
549
550Now, let's move that key onto the smartcard::
551
552    gpg> keytocard
553    Please select where to store the key:
554       (2) Encryption key
555    Your selection? 2
556
557Since it's our **[E]** key, it makes sense to put it into the Encryption
558slot.  When you submit your selection, you will be prompted first for
559your PGP key passphrase, and then for the admin PIN. If the command
560returns without an error, your key has been moved.
561
562**Important**: Now type ``key 1`` again to unselect the first key, and
563``key 2`` to select the **[S]** key::
564
565    gpg> key 1
566    gpg> key 2
567    gpg> keytocard
568    Please select where to store the key:
569       (1) Signature key
570       (3) Authentication key
571    Your selection? 1
572
573You can use the **[S]** key both for Signature and Authentication, but
574we want to make sure it's in the Signature slot, so choose (1). Once
575again, if your command returns without an error, then the operation was
576successful::
577
578    gpg> q
579    Save changes? (y/N) y
580
581Saving the changes will delete the keys you moved to the card from your
582home directory (but it's okay, because we have them in our backups
583should we need to do this again for a replacement smartcard).
584
585Verifying that the keys were moved
586~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
587
588If you perform ``--list-secret-keys`` now, you will see a subtle
589difference in the output::
590
591    $ gpg --list-secret-keys
592    sec#  rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
593          000000000000000000000000AAAABBBBCCCCDDDD
594    uid           [ultimate] Alice Dev <adev@kernel.org>
595    ssb>  rsa2048 2018-01-24 [E] [expires: 2020-01-24]
596    ssb>  ed25519 2018-01-24 [S]
597
598The ``>`` in the ``ssb>`` output indicates that the subkey is only
599available on the smartcard. If you go back into your secret keys
600directory and look at the contents there, you will notice that the
601``.key`` files there have been replaced with stubs::
602
603    $ cd ~/.gnupg/private-keys-v1.d
604    $ strings *.key | grep 'private-key'
605
606The output should contain ``shadowed-private-key`` to indicate that
607these files are only stubs and the actual content is on the smartcard.
608
609Verifying that the smartcard is functioning
610~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
611
612To verify that the smartcard is working as intended, you can create a
613signature::
614
615    $ echo "Hello world" | gpg --clearsign > /tmp/test.asc
616    $ gpg --verify /tmp/test.asc
617
618This should ask for your smartcard PIN on your first command, and then
619show "Good signature" after you run ``gpg --verify``.
620
621Congratulations, you have successfully made it extremely difficult to
622steal your digital developer identity!
623
624Other common GnuPG operations
625-----------------------------
626
627Here is a quick reference for some common operations you'll need to do
628with your PGP key.
629
630Mounting your master key offline storage
631~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
632
633You will need your master key for any of the operations below, so you
634will first need to mount your backup offline storage and tell GnuPG to
635use it::
636
637    $ export GNUPGHOME=/media/disk/foo/gnupg-backup
638    $ gpg --list-secret-keys
639
640You want to make sure that you see ``sec`` and not ``sec#`` in the
641output (the ``#`` means the key is not available and you're still using
642your regular home directory location).
643
644Extending key expiration date
645~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
646
647The master key has the default expiration date of 2 years from the date
648of creation. This is done both for security reasons and to make obsolete
649keys eventually disappear from keyservers.
650
651To extend the expiration on your key by a year from current date, just
652run::
653
654    $ gpg --quick-set-expire [fpr] 1y
655
656You can also use a specific date if that is easier to remember (e.g.
657your birthday, January 1st, or Canada Day)::
658
659    $ gpg --quick-set-expire [fpr] 2020-07-01
660
661Remember to send the updated key back to keyservers::
662
663    $ gpg --send-key [fpr]
664
665Updating your work directory after any changes
666~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
667
668After you make any changes to your key using the offline storage, you will
669want to import these changes back into your regular working directory::
670
671    $ gpg --export | gpg --homedir ~/.gnupg --import
672    $ unset GNUPGHOME
673
674Using gpg-agent over ssh
675~~~~~~~~~~~~~~~~~~~~~~~~
676
677You can forward your gpg-agent over ssh if you need to sign tags or
678commits on a remote system. Please refer to the instructions provided
679on the GnuPG wiki:
680
681- `Agent Forwarding over SSH`_
682
683It works more smoothly if you can modify the sshd server settings on the
684remote end.
685
686.. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding
687
688
689Using PGP with Git
690==================
691
692One of the core features of Git is its decentralized nature -- once a
693repository is cloned to your system, you have full history of the
694project, including all of its tags, commits and branches. However, with
695hundreds of cloned repositories floating around, how does anyone verify
696that their copy of linux.git has not been tampered with by a malicious
697third party?
698
699Or what happens if a backdoor is discovered in the code and the "Author"
700line in the commit says it was done by you, while you're pretty sure you
701had `nothing to do with it`_?
702
703To address both of these issues, Git introduced PGP integration. Signed
704tags prove the repository integrity by assuring that its contents are
705exactly the same as on the workstation of the developer who created the
706tag, while signed commits make it nearly impossible for someone to
707impersonate you without having access to your PGP keys.
708
709.. _`nothing to do with it`: https://github.com/jayphelps/git-blame-someone-else
710
711Configure git to use your PGP key
712---------------------------------
713
714If you only have one secret key in your keyring, then you don't really
715need to do anything extra, as it becomes your default key.  However, if
716you happen to have multiple secret keys, you can tell git which key
717should be used (``[fpr]`` is the fingerprint of your key)::
718
719    $ git config --global user.signingKey [fpr]
720
721**IMPORTANT**: If you have a distinct ``gpg2`` command, then you should
722tell git to always use it instead of the legacy ``gpg`` from version 1::
723
724    $ git config --global gpg.program gpg2
725    $ git config --global gpgv.program gpgv2
726
727How to work with signed tags
728----------------------------
729
730To create a signed tag, simply pass the ``-s`` switch to the tag
731command::
732
733    $ git tag -s [tagname]
734
735Our recommendation is to always sign git tags, as this allows other
736developers to ensure that the git repository they are pulling from has
737not been maliciously altered.
738
739How to verify signed tags
740~~~~~~~~~~~~~~~~~~~~~~~~~
741
742To verify a signed tag, simply use the ``verify-tag`` command::
743
744    $ git verify-tag [tagname]
745
746If you are pulling a tag from another fork of the project repository,
747git should automatically verify the signature at the tip you're pulling
748and show you the results during the merge operation::
749
750    $ git pull [url] tags/sometag
751
752The merge message will contain something like this::
753
754    Merge tag 'sometag' of [url]
755
756    [Tag message]
757
758    # gpg: Signature made [...]
759    # gpg: Good signature from [...]
760
761If you are verifying someone else's git tag, then you will need to
762import their PGP key. Please refer to the
763":ref:`verify_identities`" section below.
764
765.. note::
766
767    If you get "``gpg: Can't check signature: unknown pubkey
768    algorithm``" error, you need to tell git to use gpgv2 for
769    verification, so it properly processes signatures made by ECC keys.
770    See instructions at the start of this section.
771
772Configure git to always sign annotated tags
773~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
774
775Chances are, if you're creating an annotated tag, you'll want to sign
776it. To force git to always sign annotated tags, you can set a global
777configuration option::
778
779    $ git config --global tag.forceSignAnnotated true
780
781How to work with signed commits
782-------------------------------
783
784It is easy to create signed commits, but it is much more difficult to
785use them in Linux kernel development, since it relies on patches sent to
786the mailing list, and this workflow does not preserve PGP commit
787signatures. Furthermore, when rebasing your repository to match
788upstream, even your own PGP commit signatures will end up discarded. For
789this reason, most kernel developers don't bother signing their commits
790and will ignore signed commits in any external repositories that they
791rely upon in their work.
792
793However, if you have your working git tree publicly available at some
794git hosting service (kernel.org, infradead.org, ozlabs.org, or others),
795then the recommendation is that you sign all your git commits even if
796upstream developers do not directly benefit from this practice.
797
798We recommend this for the following reasons:
799
8001. Should there ever be a need to perform code forensics or track code
801   provenance, even externally maintained trees carrying PGP commit
802   signatures will be valuable for such purposes.
8032. If you ever need to re-clone your local repository (for example,
804   after a disk failure), this lets you easily verify the repository
805   integrity before resuming your work.
8063. If someone needs to cherry-pick your commits, this allows them to
807   quickly verify their integrity before applying them.
808
809Creating signed commits
810~~~~~~~~~~~~~~~~~~~~~~~
811
812To create a signed commit, you just need to pass the ``-S`` flag to the
813``git commit`` command (it's capital ``-S`` due to collision with
814another flag)::
815
816    $ git commit -S
817
818Configure git to always sign commits
819~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
820
821You can tell git to always sign commits::
822
823    git config --global commit.gpgSign true
824
825.. note::
826
827    Make sure you configure ``gpg-agent`` before you turn this on.
828
829.. _verify_identities:
830
831How to verify kernel developer identities
832=========================================
833
834Signing tags and commits is easy, but how does one go about verifying
835that the key used to sign something belongs to the actual kernel
836developer and not to a malicious imposter?
837
838Configure auto-key-retrieval using WKD and DANE
839-----------------------------------------------
840
841If you are not already someone with an extensive collection of other
842developers' public keys, then you can jumpstart your keyring by relying
843on key auto-discovery and auto-retrieval. GnuPG can piggyback on other
844delegated trust technologies, namely DNSSEC and TLS, to get you going if
845the prospect of starting your own Web of Trust from scratch is too
846daunting.
847
848Add the following to your ``~/.gnupg/gpg.conf``::
849
850    auto-key-locate wkd,dane,local
851    auto-key-retrieve
852
853DNS-Based Authentication of Named Entities ("DANE") is a method for
854publishing public keys in DNS and securing them using DNSSEC signed
855zones. Web Key Directory ("WKD") is the alternative method that uses
856https lookups for the same purpose. When using either DANE or WKD for
857looking up public keys, GnuPG will validate DNSSEC or TLS certificates,
858respectively, before adding auto-retrieved public keys to your local
859keyring.
860
861Kernel.org publishes the WKD for all developers who have kernel.org
862accounts. Once you have the above changes in your ``gpg.conf``, you can
863auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you
864don't already have them)::
865
866    $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org
867
868If you have a kernel.org account, then you should `add the kernel.org
869UID to your key`_ to make WKD more useful to other kernel developers.
870
871.. _`add the kernel.org UID to your key`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernelorg_uid_to_your_pgp_key
872
873Web of Trust (WOT) vs. Trust on First Use (TOFU)
874------------------------------------------------
875
876PGP incorporates a trust delegation mechanism known as the "Web of
877Trust." At its core, this is an attempt to replace the need for
878centralized Certification Authorities of the HTTPS/TLS world. Instead of
879various software makers dictating who should be your trusted certifying
880entity, PGP leaves this responsibility to each user.
881
882Unfortunately, very few people understand how the Web of Trust works.
883While it remains an important aspect of the OpenPGP specification,
884recent versions of GnuPG (2.2 and above) have implemented an alternative
885mechanism called "Trust on First Use" (TOFU). You can think of TOFU as
886"the SSH-like approach to trust." With SSH, the first time you connect
887to a remote system, its key fingerprint is recorded and remembered. If
888the key changes in the future, the SSH client will alert you and refuse
889to connect, forcing you to make a decision on whether you choose to
890trust the changed key or not. Similarly, the first time you import
891someone's PGP key, it is assumed to be valid. If at any point in the
892future GnuPG comes across another key with the same identity, both the
893previously imported key and the new key will be marked as invalid and
894you will need to manually figure out which one to keep.
895
896We recommend that you use the combined TOFU+PGP trust model (which is
897the new default in GnuPG v2). To set it, add (or modify) the
898``trust-model`` setting in ``~/.gnupg/gpg.conf``::
899
900    trust-model tofu+pgp
901
902How to use keyservers (more) safely
903-----------------------------------
904
905If you get a "No public key" error when trying to validate someone's
906tag, then you should attempt to lookup that key using a keyserver. It is
907important to keep in mind that there is absolutely no guarantee that the
908key you retrieve from PGP keyservers belongs to the actual person --
909that much is by design. You are supposed to use the Web of Trust to
910establish key validity.
911
912How to properly maintain the Web of Trust is beyond the scope of this
913document, simply because doing it properly requires both effort and
914dedication that tends to be beyond the caring threshold of most human
915beings. Here are some shortcuts that will help you reduce the risk of
916importing a malicious key.
917
918First, let's say you've tried to run ``git verify-tag`` but it returned
919an error saying the key is not found::
920
921    $ git verify-tag sunxi-fixes-for-4.15-2
922    gpg: Signature made Sun 07 Jan 2018 10:51:55 PM EST
923    gpg:                using RSA key DA73759BF8619E484E5A3B47389A54219C0F2430
924    gpg:                issuer "wens@...org"
925    gpg: Can't check signature: No public key
926
927Let's query the keyserver for more info about that key fingerprint (the
928fingerprint probably belongs to a subkey, so we can't use it directly
929without finding out the ID of the master key it is associated with)::
930
931    $ gpg --search DA73759BF8619E484E5A3B47389A54219C0F2430
932    gpg: data source: hkp://keys.gnupg.net
933    (1) Chen-Yu Tsai <wens@...org>
934          4096 bit RSA key C94035C21B4F2AEB, created: 2017-03-14, expires: 2019-03-15
935    Keys 1-1 of 1 for "DA73759BF8619E484E5A3B47389A54219C0F2430".  Enter number(s), N)ext, or Q)uit > q
936
937Locate the ID of the master key in the output, in our example
938``C94035C21B4F2AEB``. Now display the key of Linus Torvalds that you
939have on your keyring::
940
941    $ gpg --list-key torvalds@kernel.org
942    pub   rsa2048 2011-09-20 [SC]
943          ABAF11C65A2970B130ABE3C479BE3E4300411886
944    uid           [ unknown] Linus Torvalds <torvalds@kernel.org>
945    sub   rsa2048 2011-09-20 [E]
946
947Next, open the `PGP pathfinder`_. In the "From" field, paste the key
948fingerprint of Linus Torvalds from the output above. In the "To" field,
949paste the key-id you found via ``gpg --search`` of the unknown key, and
950check the results:
951
952- `Finding paths to Linus`_
953
954If you get a few decent trust paths, then it's a pretty good indication
955that it is a valid key. You can add it to your keyring from the
956keyserver now::
957
958    $ gpg --recv-key C94035C21B4F2AEB
959
960This process is not perfect, and you are obviously trusting the
961administrators of the PGP Pathfinder service to not be malicious (in
962fact, this goes against :ref:`devs_not_infra`). However, if you
963do not carefully maintain your own web of trust, then it is a marked
964improvement over blindly trusting keyservers.
965
966.. _`PGP pathfinder`: https://pgp.cs.uu.nl/
967.. _`Finding paths to Linus`: https://pgp.cs.uu.nl/paths/79BE3E4300411886/to/C94035C21B4F2AEB.html
968