Lines Matching +full:master +full:- +full:kernel
4 Kernel Maintainer PGP guide
9 This document is aimed at Linux kernel developers, and especially at
12 Linux Foundation. Please read that document for more in-depth discussion
15 .. _`Protecting Code Integrity`: https://github.com/lfit/itpol/blob/master/protecting-code-integrit…
17 The role of PGP in Linux Kernel development
21 kernel development community and, to a lesser degree, establish trusted
22 communication channels between developers via PGP-signed email exchange.
24 The Linux kernel source code is available in two main formats:
26 - Distributed source repositories (git)
27 - Periodic release snapshots (tarballs)
29 Both git repositories and tarballs carry PGP signatures of the kernel
30 developers who create official kernel releases. These signatures offer a
32 kernel.org or any other mirrors are identical to what these developers
35 - git repositories provide PGP signatures on all tags
36 - tarballs provide detached PGP signatures with all downloads
41 -------------------------------------------
43 Ever since the 2011 compromise of core kernel.org systems, the main
44 operating principle of the Kernel Archives project has been to assume
56 establish the integrity of the Linux kernel itself.
64 ------------
68 release -- many distributions still package both, with the default
71 $ gpg --version | head -n1
77 $ gpg2 --version | head -n1
83 GnuPG. Versions of gnupg-2.1.11 and later should be compatible for the
94 Configure gpg-agent options
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.
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
111 edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values::
114 default-cache-ttl 1800
115 max-cache-ttl 7200
119 It is no longer necessary to start gpg-agent manually at the
131 @daily /usr/bin/gpg2 --refresh >/dev/null 2>&1
138 Protect your master PGP key
142 kernel development purposes. If you do not yet have one, please see the
149 Master key vs. Subkeys
150 ----------------------
152 Subkeys are fully independent PGP keypairs that are tied to the "master"
156 1. There are no technical differences between the "master key" and "subkeys."
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
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
173 "master" key because it is the only key that can be used to indicate
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
183 - A master key carrying both Certify and Sign capabilities (**[SC]**)
184 - A separate subkey with the Encryption capability (**[E]**)
187 is what you will have. You can verify by running ``gpg --list-secret-keys``,
190 sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23]
192 uid [ultimate] Alice Dev <adev@kernel.org>
193 ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23]
195 Any key carrying the **[C]** capability is your master key, regardless
198 The long line under the ``sec`` entry is your key fingerprint --
199 whenever you see ``[fpr]`` in the examples below, that 40-character
203 --------------------------------
213 $ gpg --change-passphrase [fpr]
216 --------------------------------
218 Our goal is to protect your master key by moving it to offline media, so
222 $ gpg --quick-addkey [fpr] ed25519 sign
227 $ gpg --send-key [fpr]
233 RSA master keys. The main upside of ECC cryptography is that it is
237 recommend that you create an ECC signing subkey for your kernel
247 Back up your master key for disaster recovery
248 ---------------------------------------------
263 $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt
269 used to be when you had created the backup -- *guaranteed*.
271 Put the resulting printout and the hand-written passphrase into an envelope
272 and store in a secure and well-protected place, preferably away from your
279 your passphrase, printing out even to "cloud-integrated" modern
281 change the passphrase on your master key immediately after you are
285 ----------------------------------
293 disaster-level preparedness we did with ``paperkey``. You will also rely
294 on these external copies whenever you need to use your Certify key --
300 -- refer to your distro's documentation on how to accomplish this.
303 master key.
305 Once the encryption process is over, re-insert the USB drive and make
309 $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup
313 $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr]
317 need to use a random USB drive, and put in a safe place -- but not too
322 Remove the master key from your homedir
323 ----------------------------------------
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
336 shoulder-surfing, or any number of other means. For this reason, the
337 recommended setup is to remove your master key from your home directory
346 First, identify the keygrip of your master key::
348 $ gpg --with-keygrip --list-key [fpr]
352 pub rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
355 uid [ultimate] Alice Dev <adev@kernel.org>
356 sub rsa2048 2018-01-24 [E] [expires: 2020-01-24]
358 sub ed25519 2018-01-24 [S]
362 master key fingerprint). This will correspond directly to a file in your
365 $ cd ~/.gnupg/private-keys-v1.d
372 the master keygrip::
374 $ cd ~/.gnupg/private-keys-v1.d
377 Now, if you issue the ``--list-secret-keys`` command, it will show that
378 the master key is missing (the ``#`` indicates it is not available)::
380 $ gpg --list-secret-keys
381 sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
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]
390 If you don't have the "private-keys-v1.d" directory
393 If you do not have a ``~/.gnupg/private-keys-v1.d`` directory, then your
397 ``secring.gpg`` format to use ``private-keys-v1.d`` instead.
407 Even though the master key is now safe from being leaked or stolen, the
419 --------------------------
427 backup purposes -- while that USB device is plugged in and mounted, the
431 smartcard-capable device.
434 ---------------------------
440 - `Nitrokey Start`_: Open hardware and Free Software, based on FSI
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
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
458 If you are listed in MAINTAINERS or have an account at kernel.org,
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: https://www.fsij.org/doc-gnuk/
467 .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-…
470 -------------------------------
475 $ gpg --card-status
484 there are no convenient command-line switches::
486 $ gpg --card-edit
493 Please make sure to record and store these in a safe place -- especially
514 ----------------------------------
520 $ gpg --edit-key [fpr]
525 created: 2018-01-23 expires: 2020-01-23 usage: SC
528 created: 2018-01-23 expires: never usage: E
530 created: 2017-12-07 expires: never usage: S
531 [ultimate] (1). Alice Dev <adev@kernel.org>
535 Using ``--edit-key`` puts us into the menu mode again, and you will
539 First, let's select the key we'll be putting onto the card -- you do
588 If you perform ``--list-secret-keys`` now, you will see a subtle
591 $ gpg --list-secret-keys
592 sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
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]
603 $ cd ~/.gnupg/private-keys-v1.d
604 $ strings *.key | grep 'private-key'
606 The output should contain ``shadowed-private-key`` to indicate that
615 $ echo "Hello world" | gpg --clearsign > /tmp/test.asc
616 $ gpg --verify /tmp/test.asc
619 show "Good signature" after you run ``gpg --verify``.
625 -----------------------------
630 Mounting your master key offline storage
633 You will need your master key for any of the operations below, so you
637 $ export GNUPGHOME=/media/disk/foo/gnupg-backup
638 $ gpg --list-secret-keys
647 The master key has the default expiration date of 2 years from the date
654 $ gpg --quick-set-expire [fpr] 1y
659 $ gpg --quick-set-expire [fpr] 2020-07-01
663 $ gpg --send-key [fpr]
671 $ gpg --export | gpg --homedir ~/.gnupg --import
674 Using gpg-agent over ssh
677 You can forward your gpg-agent over ssh if you need to sign tags or
681 - `Agent Forwarding over SSH`_
692 One of the core features of Git is its decentralized nature -- once a
709 .. _`nothing to do with it`: https://github.com/jayphelps/git-blame-someone-else
712 ---------------------------------
719 $ git config --global user.signingKey [fpr]
724 $ git config --global gpg.program gpg2
725 $ git config --global gpgv.program gpgv2
728 ----------------------------
730 To create a signed tag, simply pass the ``-s`` switch to the tag
733 $ git tag -s [tagname]
742 To verify a signed tag, simply use the ``verify-tag`` command::
744 $ git verify-tag [tagname]
779 $ git config --global tag.forceSignAnnotated true
782 -------------------------------
785 use them in Linux kernel development, since it relies on patches sent to
789 this reason, most kernel developers don't bother signing their commits
794 git hosting service (kernel.org, infradead.org, ozlabs.org, or others),
803 2. If you ever need to re-clone your local repository (for example,
806 3. If someone needs to cherry-pick your commits, this allows them to
812 To 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
816 $ git commit -S
823 git config --global commit.gpgSign true
827 Make sure you configure ``gpg-agent`` before you turn this on.
831 How to verify kernel developer identities
835 that the key used to sign something belongs to the actual kernel
838 Configure auto-key-retrieval using WKD and DANE
839 -----------------------------------------------
843 on key auto-discovery and auto-retrieval. GnuPG can piggyback on other
850 auto-key-locate wkd,dane,local
851 auto-key-retrieve
853 DNS-Based Authentication of Named Entities ("DANE") is a method for
858 respectively, before adding auto-retrieved public keys to your local
861 Kernel.org publishes the WKD for all developers who have kernel.org
863 auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you
866 $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org
868 If you have a kernel.org account, then you should `add the kernel.org
869 UID to your key`_ to make WKD more useful to other kernel developers.
871 .. _`add the kernel.org UID to your key`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernel…
874 ------------------------------------------------
886 "the SSH-like approach to trust." With SSH, the first time you connect
898 ``trust-model`` setting in ``~/.gnupg/gpg.conf``::
900 trust-model tofu+pgp
903 -----------------------------------
908 key you retrieve from PGP keyservers belongs to the actual person --
918 First, let's say you've tried to run ``git verify-tag`` but it returned
921 $ git verify-tag sunxi-fixes-for-4.15-2
929 without finding out the ID of the master key it is associated with)::
931 $ gpg --search DA73759BF8619E484E5A3B47389A54219C0F2430
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
937 Locate the ID of the master key in the output, in our example
941 $ gpg --list-key torvalds@kernel.org
942 pub rsa2048 2011-09-20 [SC]
944 uid [ unknown] Linus Torvalds <torvalds@kernel.org>
945 sub rsa2048 2011-09-20 [E]
949 paste the key-id you found via ``gpg --search`` of the unknown key, and
952 - `Finding paths to Linus`_
958 $ gpg --recv-key C94035C21B4F2AEB