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