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