mirrors
/
linux-stable
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
1
0
Fork 0
Code Issues Releases Wiki Activity

docs: maintainer-pgp-guide: update for latest gnupg defaults 

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@linuxfoundation.org>
Link: https://lore.kernel.org/r/20221220-docs-pgp-guide-v1-1-9b0c0bf974fb@linuxfoundation.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Konstantin Ryabitsev 2022-12-20 14:44:17 -05:00 committed by Jonathan Corbet
parent 71240f94f1
commit 041d432913
1 changed files with 30 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
Documentation/process/maintainer-pgp-guide.rst
View File

@ -60,36 +60,18 @@ establish the integrity of the Linux kernel itself.
PGP tools PGP tools
========= =========
Use GnuPG v2 Use GnuPG 2.2 or later
------------ ----------------------
Your distro should already have GnuPG installed by default, you just 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 need to verify that you are using a reasonably recent version of it.
release -- many distributions still package both, with the default To check, run::
``gpg`` command invoking GnuPG v.1. To check, run::
$ gpg --version | head -n1 $ gpg --version | head -n1
If you see ``gpg (GnuPG) 1.4.x``, then you are using GnuPG v.1. Try the If you have version 2.2 or above, then you are good to go. If you have a
``gpg2`` command (if you don't have it, you may need to install the version that is prior than 2.2, then some commands from this guide may
gnupg2 package):: not work.
$ 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.
Configure gpg-agent options 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, The key with the **[C]** capability is often called the "master" key,
but this terminology is misleading because it implies that the Certify 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 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 a physical "master key" can be used to open locks made for other keys).
keys). Since this is not the case, this guide will refer to it as "the Since this is not the case, this guide will refer to it as "the Certify
Certify key" to avoid any ambiguity. key" to avoid any ambiguity.
It is critical to fully understand the following: 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``, is what you will have. You can verify by running ``gpg --list-secret-keys``,
for example:: for example::
sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23] sec ed25519 2022-12-20 [SC] [expires: 2024-12-19]
000000000000000000000000AAAABBBBCCCCDDDD 000000000000000000000000AAAABBBBCCCCDDDD
uid [ultimate] Alice Dev <adev@kernel.org> uid [ultimate] Alice Dev <adev@kernel.org>
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 -- The long line under the ``sec`` entry is your key fingerprint --
whenever you see ``[fpr]`` in the examples below, that 40-character whenever you see ``[fpr]`` in the examples below, that 40-character
@ -219,18 +201,9 @@ separate signing subkey::
.. note:: ECC support in GnuPG .. note:: ECC support in GnuPG
GnuPG 2.1 and later has full support for Elliptic Curve Note, that if you intend to use a hardware token that does not
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
support ED25519 ECC keys, you should choose "nistp256" instead or 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 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:: 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 000000000000000000000000AAAABBBBCCCCDDDD
Keygrip = 1111000000000000000000000000000000000000 Keygrip = 1111000000000000000000000000000000000000
uid [ultimate] Alice Dev <adev@kernel.org> uid [ultimate] Alice Dev <adev@kernel.org>
sub rsa2048 2018-01-24 [E] [expires: 2020-01-24] sub cv25519 2022-12-20 [E] [expires: 2022-12-19]
Keygrip = 2222000000000000000000000000000000000000 Keygrip = 2222000000000000000000000000000000000000
sub ed25519 2018-01-24 [S] sub ed25519 2022-12-20 [S]
Keygrip = 3333000000000000000000000000000000000000 Keygrip = 3333000000000000000000000000000000000000
Find the keygrip entry that is beneath the ``pub`` line (right under the 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):: the Certify key is missing (the ``#`` indicates it is not available)::
$ gpg --list-secret-keys $ 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 000000000000000000000000AAAABBBBCCCCDDDD
uid [ultimate] Alice Dev <adev@kernel.org> uid [ultimate] Alice Dev <adev@kernel.org>
ssb rsa2048 2018-01-24 [E] [expires: 2020-01-24] ssb cv25519 2022-12-20 [E] [expires: 2024-12-19]
ssb ed25519 2018-01-24 [S] ssb ed25519 2022-12-20 [S]
You should also remove any ``secring.gpg`` files in the ``~/.gnupg`` 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 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 U2F, among others, and now finally supports NISTP and ED25519 ECC
keys. keys.
`LWN has a good review`_ of some of the above models, as well as several Your choice will depend on cost, shipping availability in your
others. Your choice will depend on cost, shipping availability in your
geographical region, and open/proprietary hardware considerations. geographical region, and open/proprietary hardware considerations.
.. note:: .. 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 .. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3
.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/
.. _Gnuk: https://www.fsij.org/doc-gnuk/ .. _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 .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html
Configure your smartcard device Configure your smartcard device
@ -509,11 +480,11 @@ passphrase and the admin PIN of the card for most operations::
Secret subkeys are available. Secret subkeys are available.
pub rsa2048/AAAABBBBCCCCDDDD pub ed25519/AAAABBBBCCCCDDDD
created: 2018-01-23 expires: 2020-01-23 usage: SC created: 2022-12-20 expires: 2024-12-19 usage: SC
trust: ultimate validity: ultimate trust: ultimate validity: ultimate
ssb rsa2048/1111222233334444 ssb cv25519/1111222233334444
created: 2018-01-23 expires: never usage: E created: 2022-12-20 expires: never usage: E
ssb ed25519/5555666677778888 ssb ed25519/5555666677778888
created: 2017-12-07 expires: never usage: S created: 2017-12-07 expires: never usage: S
[ultimate] (1). Alice Dev <adev@kernel.org> [ultimate] (1). Alice Dev <adev@kernel.org>
@ -577,11 +548,11 @@ If you perform ``--list-secret-keys`` now, you will see a subtle
difference in the output:: difference in the output::
$ gpg --list-secret-keys $ 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 000000000000000000000000AAAABBBBCCCCDDDD
uid [ultimate] Alice Dev <adev@kernel.org> uid [ultimate] Alice Dev <adev@kernel.org>
ssb> rsa2048 2018-01-24 [E] [expires: 2020-01-24] ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19]
ssb> ed25519 2018-01-24 [S] ssb> ed25519 2022-12-20 [S]
The ``>`` in the ``ssb>`` output indicates that the subkey is only The ``>`` in the ``ssb>`` output indicates that the subkey is only
available on the smartcard. If you go back into your secret keys 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. You can also use a specific date if that is easier to remember (e.g.
your birthday, January 1st, or Canada Day):: 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:: 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] $ 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 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 import their PGP key. Please refer to the
":ref:`verify_identities`" section below. ":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 Configure git to always sign annotated tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~