Commit | Line | Data |
---|---|---|
b72dde38 KR |
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 | |
78ed7845 | 21 | kernel development community and, to a lesser degree, establish trusted |
b72dde38 KR |
22 | communication channels between developers via PGP-signed email exchange. |
23 | ||
78ed7845 | 24 | The Linux kernel source code is available in two main formats: |
b72dde38 KR |
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 | |
78ed7845 | 56 | establish the integrity of the Linux kernel itself. |
b72dde38 KR |
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 | |
78ed7845 | 142 | kernel development purposes. If you do not yet have one, please see the |
b72dde38 KR |
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 | ||
78ed7845 KR |
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: | |
b72dde38 KR |
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 | ||
1ba2211c | 222 | $ gpg --quick-addkey [fpr] ed25519 sign |
b72dde38 KR |
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 | ||
1ba2211c KR |
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 | ||
b72dde38 KR |
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/ | |
1ba2211c | 464 | .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html |
b72dde38 KR |
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 | |
1ba2211c | 492 | the smartcard). You so rarely need to use the Admin PIN, that you will |
b72dde38 KR |
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 | ||
1ba2211c KR |
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 | ||
b72dde38 KR |
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 | ||
1ba2211c KR |
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 | ||
b72dde38 KR |
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 | |
1ba2211c | 722 | $ git config --global gpgv.program gpgv2 |
b72dde38 KR |
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 | ||
1ba2211c KR |
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 | ||
b72dde38 KR |
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 | |
78ed7845 | 782 | use them in Linux kernel development, since it relies on patches sent to |
b72dde38 | 783 | the mailing list, and this workflow does not preserve PGP commit |
78ed7845 KR |
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. | |
b72dde38 KR |
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 | ||
78ed7845 KR |
822 | .. note:: |
823 | ||
824 | Make sure you configure ``gpg-agent`` before you turn this on. | |
825 | ||
b72dde38 KR |
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 | ||
78ed7845 | 938 | $ gpg --list-key torvalds@kernel.org |
b72dde38 KR |
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 they 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 |