Lines Matching +full:key +full:- +full:home
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…
22 communication channels between developers via PGP-signed email exchange.
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 -------------------------------------------
64 ----------------------
70 $ gpg --version | head -n1
76 Configure gpg-agent options
81 of caching the private key passphrase. There are two options you should
84 - ``default-cache-ttl`` (seconds): If you use the same key again before
85 the time-to-live expires, the countdown will reset for another period.
87 - ``max-cache-ttl`` (seconds): Regardless of how recently you've used
88 the key since initial passphrase entry, if the maximum time-to-live
93 edit your ``~/.gnupg/gpg-agent.conf`` file to set your own values::
96 default-cache-ttl 1800
97 max-cache-ttl 7200
101 It is no longer necessary to start gpg-agent manually at the
108 Protect your PGP key
111 This guide assumes that you already have a PGP key that you use for Linux
116 You should also make a new key if your current one is weaker than 2048
120 -------------------------
122 A PGP key rarely consists of a single keypair -- usually it is a
125 PGP defines four capabilities that a key can have:
127 - **[S]** keys can be used for signing
128 - **[E]** keys can be used for encryption
129 - **[A]** keys can be used for authentication
130 - **[C]** keys can be used for certifying other keys
132 The key with the **[C]** capability is often called the "master" key,
134 key can be used in place of any of other subkey on the same chain (like
135 a physical "master key" can be used to open locks made for other keys).
137 key" to avoid any ambiguity.
143 private key on your chain.
144 2. With the exception of the Certify key, there can be multiple subkeys
147 subkey). All subkeys are fully independent -- a message encrypted to
150 3. A single subkey may have multiple capabilities (e.g. your **[C]** key
151 can also be your **[S]** key).
153 The key carrying the **[C]** (certify) capability is the only key that
155 key can be used to:
157 - add or revoke other keys (subkeys) with S/E/A capabilities
158 - add, change or revoke identities (uids) associated with the key
159 - add or change the expiration date on itself or any subkey
160 - sign other people's keys for web of trust purposes
164 - One subkey carrying both Certify and Sign capabilities (**[SC]**)
165 - A separate subkey with the Encryption capability (**[E]**)
167 If you used the default parameters when generating your key, then that
168 is what you will have. You can verify by running ``gpg --list-secret-keys``,
171 sec ed25519 2022-12-20 [SC] [expires: 2024-12-19]
174 ssb cv25519 2022-12-20 [E] [expires: 2024-12-19]
176 The long line under the ``sec`` entry is your key fingerprint --
177 whenever you see ``[fpr]`` in the examples below, that 40-character
181 --------------------------------
191 $ gpg --change-passphrase [fpr]
194 --------------------------------
196 Our goal is to protect your Certify key by moving it to offline media,
197 so if you only have a combined **[SC]** key, then you should create a
200 $ gpg --quick-addkey [fpr] ed25519 sign
209 Back up your Certify key for disaster recovery
210 ----------------------------------------------
212 The more signatures you have on your PGP key from other developers, the
216 The best way to create a printable hardcopy of your private key is by
223 key::
225 $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt
229 strongly recommended** because the key printout is still encrypted with
231 used to be when you had created the backup -- *guaranteed*.
233 Put the resulting printout and the hand-written passphrase into an envelope
234 and store in a secure and well-protected place, preferably away from your
235 home, such as your bank vault.
241 your passphrase, printing out even to "cloud-integrated" modern
245 ----------------------------------
253 disaster-level preparedness we did with ``paperkey``. You will also rely
254 on these external copies whenever you need to use your Certify key --
255 such as when making changes to your own key or signing other people's
260 -- refer to your distro's documentation on how to accomplish this.
263 PGP key.
265 Once the encryption process is over, re-insert the USB drive and make
269 $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup
273 $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr]
277 need to use a random USB drive, and put in a safe place -- but not too
282 Remove the Certify key from your homedir
283 ----------------------------------------
285 The files in our home directory are not as well protected as we like to
288 - by accident when making quick homedir copies to set up a new workstation
289 - by systems administrator negligence or malice
290 - via poorly secured backups
291 - via malware in desktop apps (browsers, pdf viewers, etc)
292 - via coercion when crossing international borders
294 Protecting your key with a good passphrase greatly helps reduce the risk
296 shoulder-surfing, or any number of other means. For this reason, the
297 recommended setup is to remove your Certify key from your home directory
304 render your key useless if you do not have a usable backup!
306 First, identify the keygrip of your Certify key::
308 $ gpg --with-keygrip --list-key [fpr]
312 pub ed25519 2022-12-20 [SC] [expires: 2022-12-19]
316 sub cv25519 2022-12-20 [E] [expires: 2022-12-19]
318 sub ed25519 2022-12-20 [S]
322 Certify key fingerprint). This will correspond directly to a file in your
325 $ cd ~/.gnupg/private-keys-v1.d
327 1111000000000000000000000000000000000000.key
328 2222000000000000000000000000000000000000.key
329 3333000000000000000000000000000000000000.key
331 All you have to do is simply remove the .key file that corresponds to
332 the Certify key keygrip::
334 $ cd ~/.gnupg/private-keys-v1.d
335 $ rm 1111000000000000000000000000000000000000.key
337 Now, if you issue the ``--list-secret-keys`` command, it will show that
338 the Certify key is missing (the ``#`` indicates it is not available)::
340 $ gpg --list-secret-keys
341 sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19]
344 ssb cv25519 2022-12-20 [E] [expires: 2024-12-19]
345 ssb ed25519 2022-12-20 [S]
350 If you don't have the "private-keys-v1.d" directory
353 If you do not have a ``~/.gnupg/private-keys-v1.d`` directory, then your
355 GnuPG v1. Making any changes to your key, such as changing the
357 ``secring.gpg`` format to use ``private-keys-v1.d`` instead.
367 Even though the Certify key is now safe from being leaked or stolen, the
368 subkeys are still in your home directory. Anyone who manages to get
379 --------------------------
383 itself. Because the key contents never leave the smartcard, the
387 backup purposes -- while that USB device is plugged in and mounted, the
388 operating system is able to access the private key contents.
391 smartcard-capable device.
394 ---------------------------
400 - `Nitrokey Start`_: Open hardware and Free Software, based on FSI
403 resistance to tampering or some side-channel attacks).
404 - `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more
405 tamper-resistant and offers more security features. Pro 2 supports ECC
407 - `Yubikey 5`_: proprietary hardware and software, but cheaper than
408 Nitrokey Pro and comes available in the USB-C form that is more useful
422 .. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6
423 .. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3
424 .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/
425 .. _Gnuk: https://www.fsij.org/doc-gnuk/
426 .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-…
429 -------------------------------
434 $ gpg --card-status
443 there are no convenient command-line switches::
445 $ gpg --card-edit
452 Please make sure to record and store these in a safe place -- especially
473 ----------------------------------
476 your subkeys onto the smartcard. You will need both your PGP key
479 $ gpg --edit-key [fpr]
484 created: 2022-12-20 expires: 2024-12-19 usage: SC
487 created: 2022-12-20 expires: never usage: E
489 created: 2017-12-07 expires: never usage: S
494 Using ``--edit-key`` puts us into the menu mode again, and you will
495 notice that the key listing is a little different. From here on, all
498 First, let's select the key we'll be putting onto the card -- you do
499 this by typing ``key 1`` (it's the first one in the listing, the **[E]**
502 gpg> key 1
504 In the output, you should now see ``ssb*`` on the **[E]** key. The ``*``
505 indicates which key is currently "selected." It works as a *toggle*,
506 meaning that if you type ``key 1`` again, the ``*`` will disappear and
507 the key will not be selected any more.
509 Now, let's move that key onto the smartcard::
512 Please select where to store the key:
513 (2) Encryption key
516 Since it's our **[E]** key, it makes sense to put it into the Encryption
518 your PGP key passphrase, and then for the admin PIN. If the command
519 returns without an error, your key has been moved.
521 **Important**: Now type ``key 1`` again to unselect the first key, and
522 ``key 2`` to select the **[S]** key::
524 gpg> key 1
525 gpg> key 2
527 Please select where to store the key:
528 (1) Signature key
529 (3) Authentication key
532 You can use the **[S]** key both for Signature and Authentication, but
541 home directory (but it's okay, because we have them in our backups
547 If you perform ``--list-secret-keys`` now, you will see a subtle
550 $ gpg --list-secret-keys
551 sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19]
554 ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19]
555 ssb> ed25519 2022-12-20 [S]
560 ``.key`` files there have been replaced with stubs::
562 $ cd ~/.gnupg/private-keys-v1.d
563 $ strings *.key | grep 'private-key'
565 The output should contain ``shadowed-private-key`` to indicate that
574 $ echo "Hello world" | gpg --clearsign > /tmp/test.asc
575 $ gpg --verify /tmp/test.asc
578 show "Good signature" after you run ``gpg --verify``.
584 -----------------------------
587 with your PGP key.
592 You will need your Certify key for any of the operations below, so you
596 $ export GNUPGHOME=/media/disk/foo/gnupg-backup
597 $ gpg --list-secret-keys
600 output (the ``#`` means the key is not available and you're still using
601 your regular home directory location).
603 Extending key expiration date
606 The Certify key has the default expiration date of 2 years from the date
610 To extend the expiration on your key by a year from current date, just
613 $ gpg --quick-set-expire [fpr] 1y
618 $ gpg --quick-set-expire [fpr] 2025-07-01
620 Remember to send the updated key back to keyservers::
622 $ gpg --send-key [fpr]
627 After you make any changes to your key using the offline storage, you will
630 $ gpg --export | gpg --homedir ~/.gnupg --import
633 Using gpg-agent over ssh
636 You can forward your gpg-agent over ssh if you need to sign tags or
640 - `Agent Forwarding over SSH`_
652 One of the core features of Git is its decentralized nature -- once a
669 .. _`nothing to do with it`: https://github.com/jayphelps/git-blame-someone-else
671 Configure git to use your PGP key
672 ---------------------------------
674 If you only have one secret key in your keyring, then you don't really
675 need to do anything extra, as it becomes your default key. However, if
676 you happen to have multiple secret keys, you can tell git which key
677 should be used (``[fpr]`` is the fingerprint of your key)::
679 $ git config --global user.signingKey [fpr]
682 ----------------------------
684 To create a signed tag, simply pass the ``-s`` switch to the tag
687 $ git tag -s [tagname]
696 To verify a signed tag, simply use the ``verify-tag`` command::
698 $ git verify-tag [tagname]
716 import their PGP key. Please refer to the
726 $ git config --global tag.forceSignAnnotated true
729 -------------------------------
750 2. If you ever need to re-clone your local repository (for example,
753 3. If someone needs to cherry-pick your commits, this allows them to
759 To create a signed commit, you just need to pass the ``-S`` flag to the
760 ``git commit`` command (it's capital ``-S`` due to collision with
763 $ git commit -S
770 git config --global commit.gpgSign true
774 Make sure you configure ``gpg-agent`` before you turn this on.
780 -------------------------------
782 It is possible to use your PGP key to sign patches sent to kernel
784 (PGP-Mime or PGP-inline) tend to cause problems with regular code
787 headers (a-la DKIM):
789 - `Patatt Patch Attestation`_
799 If you already have your PGP key configured with git (via the
802 the git-send-email hook in the repository you want::
804 patatt install-hook
806 Now any patches you send with ``git send-email`` will be automatically
816 $ b4 am 20220720205013.890942-1-broonie@kernel.org
819 ---
823 ---
839 that the key used to sign something belongs to the actual kernel
842 Configure auto-key-retrieval using WKD and DANE
843 -----------------------------------------------
847 on key auto-discovery and auto-retrieval. GnuPG can piggyback on other
854 auto-key-locate wkd,dane,local
855 auto-key-retrieve
857 DNS-Based Authentication of Named Entities ("DANE") is a method for
859 zones. Web Key Directory ("WKD") is the alternative method that uses
862 respectively, before adding auto-retrieved public keys to your local
867 auto-retrieve the keys for Linus Torvalds and Greg Kroah-Hartman (if you
870 $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org
873 UID to your key`_ to make WKD more useful to other kernel developers.
875 .. _`add the kernel.org UID to your key`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernel…
878 ------------------------------------------------
890 "the SSH-like approach to trust." With SSH, the first time you connect
891 to a remote system, its key fingerprint is recorded and remembered. If
892 the key changes in the future, the SSH client will alert you and refuse
894 trust the changed key or not. Similarly, the first time you import
895 someone's PGP key, it is assumed to be valid. If at any point in the
896 future GnuPG comes across another key with the same identity, both the
897 previously imported key and the new key will be marked as invalid and
902 ``trust-model`` setting in ``~/.gnupg/gpg.conf``::
904 trust-model tofu+pgp
907 --------------------------------------------
914 - `Kernel developer PGP Keyring`_
916 If you are a kernel developer, please consider submitting your key for