On Tue, Dec 20, 2022 at 02:44:17PM -0500, Konstantin Ryabitsev wrote: > 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). > Shouldn't "Protecting Code Integrity" doc also be updated with recent situation? > 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 > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > LGTM, thanks. Reviewed-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx> -- An old man doll... just what I always wanted! - Clara
Attachment:
signature.asc
Description: PGP signature
