It is finally becoming increasingly rare to find a distribution that
still ships with gnupg-1.x, so remove the last vestiges of "gpg" vs
"gpg2" from documentation.
Similarly, starting with GnuPG 2.2 and above, the default --gen-key
operation creates ed25519/cv25519 keypairs, so update all example
command outputs to use that combination instead of rsa2048.
Lastly, add a few wording tweaks and remove links that lead to stale
information (e.g. hardware tokens overview from 2017).
Signed-off-by: Konstantin Ryabitsev <konstantin@xxxxxxxxxxxxxxxxxxx>
---
Documentation/process/maintainer-pgp-guide.rst | 102 ++++++++-----------------
1 file changed, 30 insertions(+), 72 deletions(-)
diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst
index 40bfbd3b7648..f5277993b195 100644
--- a/Documentation/process/maintainer-pgp-guide.rst
+++ b/Documentation/process/maintainer-pgp-guide.rst
@@ -60,36 +60,18 @@ establish the integrity of the Linux kernel itself.
PGP tools
=========
-Use GnuPG v2
-------------
+Use GnuPG 2.2 or later
+----------------------
Your distro should already have GnuPG installed by default, you just
-need to verify that you are using version 2.x and not the legacy 1.4
-release -- many distributions still package both, with the default
-``gpg`` command invoking GnuPG v.1. To check, run::
+need to verify that you are using a reasonably recent version of it.
+To check, run::
$ gpg --version | head -n1
-If you see ``gpg (GnuPG) 1.4.x``, then you are using GnuPG v.1. Try the
-``gpg2`` command (if you don't have it, you may need to install the
-gnupg2 package)::
-
- $ gpg2 --version | head -n1
-
-If you see ``gpg (GnuPG) 2.x.x``, then you are good to go. This guide
-will assume you have the version 2.2 of GnuPG (or later). If you are
-using version 2.0 of GnuPG, then some of the commands in this guide will
-not work, and you should consider installing the latest 2.2 version of
-GnuPG. Versions of gnupg-2.1.11 and later should be compatible for the
-purposes of this guide as well.
-
-If you have both ``gpg`` and ``gpg2`` commands, you should make sure you
-are always using GnuPG v2, not the legacy version. You can enforce this
-by setting the appropriate alias::
-
- $ alias gpg=gpg2
-
-You can put that in your ``.bashrc`` to make sure it's always the case.
+If you have version 2.2 or above, then you are good to go. If you have a
+version that is prior than 2.2, then some commands from this guide may
+not work.
Configure gpg-agent options
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -150,9 +132,9 @@ PGP defines four capabilities that a key can have:
The key with the **[C]** capability is often called the "master" key,
but this terminology is misleading because it implies that the Certify
key can be used in place of any of other subkey on the same chain (like
-a physical "master key" can be used to open the locks made for other
-keys). Since this is not the case, this guide will refer to it as "the
-Certify key" to avoid any ambiguity.
+a physical "master key" can be used to open locks made for other keys).
+Since this is not the case, this guide will refer to it as "the Certify
+key" to avoid any ambiguity.
It is critical to fully understand the following:
@@ -186,10 +168,10 @@ If you used the default parameters when generating your key, then that
is what you will have. You can verify by running ``gpg --list-secret-keys``,
for example::
- sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23]
+ sec ed25519 2022-12-20 [SC] [expires: 2024-12-19]
000000000000000000000000AAAABBBBCCCCDDDD
uid [ultimate] Alice Dev <adev@xxxxxxxxxx>
- ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23]
+ ssb cv25519 2022-12-20 [E] [expires: 2024-12-19]
The long line under the ``sec`` entry is your key fingerprint --
whenever you see ``[fpr]`` in the examples below, that 40-character
@@ -219,18 +201,9 @@ separate signing subkey::
.. note:: ECC support in GnuPG
- GnuPG 2.1 and later has full support for Elliptic Curve
- Cryptography, with ability to combine ECC subkeys with traditional
- RSA keys. The main upside of ECC cryptography is that it is much
- faster computationally and creates much smaller signatures when
- compared byte for byte with 2048+ bit RSA keys. Unless you plan on
- using a smartcard device that does not support ECC operations, we
- recommend that you create an ECC signing subkey for your kernel
- work.
-
- Note, that if you plan to use a hardware device that does not
+ Note, that if you intend to use a hardware token that does not
support ED25519 ECC keys, you should choose "nistp256" instead or
- "ed25519."
+ "ed25519." See the section below on recommended hardware devices.
Back up your Certify key for disaster recovery
@@ -336,13 +309,13 @@ First, identify the keygrip of your Certify key::
The output will be something like this::
- pub rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
+ pub ed25519 2022-12-20 [SC] [expires: 2022-12-19]
000000000000000000000000AAAABBBBCCCCDDDD
Keygrip = 1111000000000000000000000000000000000000
uid [ultimate] Alice Dev <adev@xxxxxxxxxx>
- sub rsa2048 2018-01-24 [E] [expires: 2020-01-24]
+ sub cv25519 2022-12-20 [E] [expires: 2022-12-19]
Keygrip = 2222000000000000000000000000000000000000
- sub ed25519 2018-01-24 [S]
+ sub ed25519 2022-12-20 [S]
Keygrip = 3333000000000000000000000000000000000000
Find the keygrip entry that is beneath the ``pub`` line (right under the
@@ -365,14 +338,14 @@ Now, if you issue the ``--list-secret-keys`` command, it will show that
the Certify key is missing (the ``#`` indicates it is not available)::
$ gpg --list-secret-keys
- sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
+ sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19]
000000000000000000000000AAAABBBBCCCCDDDD
uid [ultimate] Alice Dev <adev@xxxxxxxxxx>
- ssb rsa2048 2018-01-24 [E] [expires: 2020-01-24]
- ssb ed25519 2018-01-24 [S]
+ ssb cv25519 2022-12-20 [E] [expires: 2024-12-19]
+ ssb ed25519 2022-12-20 [S]
You should also remove any ``secring.gpg`` files in the ``~/.gnupg``
-directory, which are left over from earlier versions of GnuPG.
+directory, which may be left over from previous versions of GnuPG.
If you don't have the "private-keys-v1.d" directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -437,8 +410,7 @@ functionality. There are several options available:
U2F, among others, and now finally supports NISTP and ED25519 ECC
keys.
-`LWN has a good review`_ of some of the above models, as well as several
-others. Your choice will depend on cost, shipping availability in your
+Your choice will depend on cost, shipping availability in your
geographical region, and open/proprietary hardware considerations.
.. note::
@@ -451,7 +423,6 @@ geographical region, and open/proprietary hardware considerations.
.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3
.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/
.. _Gnuk: https://www.fsij.org/doc-gnuk/
-.. _`LWN has a good review`: https://lwn.net/Articles/736231/
.. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html
Configure your smartcard device
@@ -509,11 +480,11 @@ passphrase and the admin PIN of the card for most operations::
Secret subkeys are available.
- pub rsa2048/AAAABBBBCCCCDDDD
- created: 2018-01-23 expires: 2020-01-23 usage: SC
+ pub ed25519/AAAABBBBCCCCDDDD
+ created: 2022-12-20 expires: 2024-12-19 usage: SC
trust: ultimate validity: ultimate
- ssb rsa2048/1111222233334444
- created: 2018-01-23 expires: never usage: E
+ ssb cv25519/1111222233334444
+ created: 2022-12-20 expires: never usage: E
ssb ed25519/5555666677778888
created: 2017-12-07 expires: never usage: S
[ultimate] (1). Alice Dev <adev@xxxxxxxxxx>
@@ -577,11 +548,11 @@ If you perform ``--list-secret-keys`` now, you will see a subtle
difference in the output::
$ gpg --list-secret-keys
- sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24]
+ sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19]
000000000000000000000000AAAABBBBCCCCDDDD
uid [ultimate] Alice Dev <adev@xxxxxxxxxx>
- ssb> rsa2048 2018-01-24 [E] [expires: 2020-01-24]
- ssb> ed25519 2018-01-24 [S]
+ ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19]
+ ssb> ed25519 2022-12-20 [S]
The ``>`` in the ``ssb>`` output indicates that the subkey is only
available on the smartcard. If you go back into your secret keys
@@ -644,7 +615,7 @@ run::
You can also use a specific date if that is easier to remember (e.g.
your birthday, January 1st, or Canada Day)::
- $ gpg --quick-set-expire [fpr] 2020-07-01
+ $ gpg --quick-set-expire [fpr] 2025-07-01
Remember to send the updated key back to keyservers::
@@ -707,12 +678,6 @@ should be used (``[fpr]`` is the fingerprint of your key)::
$ git config --global user.signingKey [fpr]
-**IMPORTANT**: If you have a distinct ``gpg2`` command, then you should
-tell git to always use it instead of the legacy ``gpg`` from version 1::
-
- $ git config --global gpg.program gpg2
- $ git config --global gpgv.program gpgv2
-
How to work with signed tags
----------------------------
@@ -751,13 +716,6 @@ If you are verifying someone else's git tag, then you will need to
import their PGP key. Please refer to the
":ref:`verify_identities`" section below.
-.. note::
-
- If you get "``gpg: Can't check signature: unknown pubkey
- algorithm``" error, you need to tell git to use gpgv2 for
- verification, so it properly processes signatures made by ECC keys.
- See instructions at the start of this section.
-
Configure git to always sign annotated tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---
base-commit: 830b3c68c1fb1e9176028d02ef86f3cf76aa2476
change-id: 20221220-docs-pgp-guide-ad94042ad062
Best regards,
--
Konstantin Ryabitsev <konstantin@xxxxxxxxxxxxxxxxxxx>
