Lines Matching +full:key +full:- +full:code
11 the more general "`Protecting Code Integrity`_" guide published by the
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…
20 PGP helps ensure the integrity of the code that is produced by the Linux
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)
35 - git repositories provide PGP signatures on all tags
36 - tarballs provide detached PGP signatures with all downloads
41 -------------------------------------------
47 that trust must always be placed with developers and never with the code
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
99 of caching the private key passphrase. There are two options you should
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
141 This guide assumes that you already have a PGP key that you use for Linux
143 "`Protecting Code Integrity`_" document mentioned earlier for guidance
146 You should also make a new key if your current one is weaker than 2048 bits
149 Master key vs. Subkeys
150 ----------------------
153 key using certifying key signatures (certificates). It is important to
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
159 3. A PGP key can have 4 capabilities:
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
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
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:
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]**)
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``,
190 sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23]
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
219 if you only have a combined **[SC]** key, then you should create a separate
222 $ gpg --quick-addkey [fpr] ed25519 sign
227 $ gpg --send-key [fpr]
247 Back up your master key for disaster recovery
248 ---------------------------------------------
250 The more signatures you have on your PGP key from other developers, the
254 The best way to create a printable hardcopy of your private key is by
261 key::
263 $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt
267 strongly recommended** because the key printout is still encrypted with
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 --
295 such as when making changes to your own key or signing other people's
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
334 Protecting your key with a good passphrase greatly helps reduce the risk
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
344 render your key useless if you do not have a usable backup!
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]
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
367 1111000000000000000000000000000000000000.key
368 2222000000000000000000000000000000000000.key
369 3333000000000000000000000000000000000000.key
371 All you have to do is simply remove the .key file that corresponds to
374 $ cd ~/.gnupg/private-keys-v1.d
375 $ rm 1111000000000000000000000000000000000000.key
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]
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
395 GnuPG v1. Making any changes to your key, such as changing the
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 --------------------------
423 itself. Because the key contents never leave the smartcard, the
427 backup purposes -- while that USB device is plugged in and mounted, the
428 operating system is able to access the private key contents.
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
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
492 You should set the user PIN (1), Admin PIN (3), and the Reset Code (4).
493 Please make sure to record and store these in a safe place -- especially
494 the Admin PIN and the Reset Code (which allows you to completely wipe
514 ----------------------------------
517 your subkeys onto the smartcard. You will need both your PGP key
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
535 Using ``--edit-key`` puts us into the menu mode again, and you will
536 notice that the key listing is a little different. From here on, all
539 First, let's select the key we'll be putting onto the card -- you do
540 this by typing ``key 1`` (it's the first one in the listing, the **[E]**
543 gpg> key 1
545 In the output, you should now see ``ssb*`` on the **[E]** key. The ``*``
546 indicates which key is currently "selected." It works as a *toggle*,
547 meaning that if you type ``key 1`` again, the ``*`` will disappear and
548 the key will not be selected any more.
550 Now, let's move that key onto the smartcard::
553 Please select where to store the key:
554 (2) Encryption key
557 Since it's our **[E]** key, it makes sense to put it into the Encryption
559 your PGP key passphrase, and then for the admin PIN. If the command
560 returns without an error, your key has been moved.
562 **Important**: Now type ``key 1`` again to unselect the first key, and
563 ``key 2`` to select the **[S]** key::
565 gpg> key 1
566 gpg> key 2
568 Please select where to store the key:
569 (1) Signature key
570 (3) Authentication key
573 You can use the **[S]** key both for Signature and Authentication, but
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]
595 ssb> rsa2048 2018-01-24 [E] [expires: 2020-01-24]
596 ssb> ed25519 2018-01-24 [S]
601 ``.key`` files there have been replaced with stubs::
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 -----------------------------
628 with your PGP key.
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
641 output (the ``#`` means the key is not available and you're still using
644 Extending key expiration date
647 The master key has the default expiration date of 2 years from the date
651 To extend the expiration on your key by a year from current date, just
654 $ gpg --quick-set-expire [fpr] 1y
659 $ gpg --quick-set-expire [fpr] 2020-07-01
661 Remember to send the updated key back to keyservers::
663 $ gpg --send-key [fpr]
668 After you make any changes to your key using the offline storage, you will
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
699 Or what happens if a backdoor is discovered in the code and the "Author"
709 .. _`nothing to do with it`: https://github.com/jayphelps/git-blame-someone-else
711 Configure git to use your PGP key
712 ---------------------------------
714 If you only have one secret key in your keyring, then you don't really
715 need to do anything extra, as it becomes your default key. However, if
716 you happen to have multiple secret keys, you can tell git which key
717 should be used (``[fpr]`` is the fingerprint of your key)::
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]
762 import their PGP key. Please refer to the
779 $ git config --global tag.forceSignAnnotated true
782 -------------------------------
800 1. Should there ever be a need to perform code forensics or track code
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.
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
855 zones. Web Key Directory ("WKD") is the alternative method that uses
858 respectively, before adding auto-retrieved public keys to your local
863 auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you
866 $ gpg --locate-keys torvalds@kernel.org gregkh@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
887 to a remote system, its key fingerprint is recorded and remembered. If
888 the key changes in the future, the SSH client will alert you and refuse
890 trust the changed key or not. Similarly, the first time you import
891 someone's PGP key, it is assumed to be valid. If at any point in the
892 future GnuPG comes across another key with the same identity, both the
893 previously imported key and the new key will be marked as invalid and
898 ``trust-model`` setting in ``~/.gnupg/gpg.conf``::
900 trust-model tofu+pgp
903 -----------------------------------
905 If you get a "No public key" error when trying to validate someone's
906 tag, then you should attempt to lookup that key using a keyserver. It is
908 key you retrieve from PGP keyservers belongs to the actual person --
910 establish key validity.
916 importing a malicious key.
918 First, let's say you've tried to run ``git verify-tag`` but it returned
919 an error saying the key is not found::
921 $ git verify-tag sunxi-fixes-for-4.15-2
923 gpg: using RSA key DA73759BF8619E484E5A3B47389A54219C0F2430
925 gpg: Can't check signature: No public key
927 Let's query the keyserver for more info about that key fingerprint (the
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
938 ``C94035C21B4F2AEB``. Now display the key of Linus Torvalds that you
941 $ gpg --list-key torvalds@kernel.org
942 pub rsa2048 2011-09-20 [SC]
945 sub rsa2048 2011-09-20 [E]
947 Next, open the `PGP pathfinder`_. In the "From" field, paste the key
949 paste the key-id you found via ``gpg --search`` of the unknown key, and
952 - `Finding paths to Linus`_
955 that it is a valid key. You can add it to your keyring from the
958 $ gpg --recv-key C94035C21B4F2AEB