MIRRORS/linux-yocto
1
0
Fork 0
mirror of git://git.yoctoproject.org/linux-yocto.git synced 2026-01-27 12:47:24 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation: update maintainer-pgp-guide for latest best practices

Browse Source 
Freshen up the maintainer PGP guide:

- Bump minimum GnuPG version requirement from 2.2 to 2.4, since 2.2 is
  no longer maintained
- All major hardware tokens now support Curve25519, so remove outdated
  ECC support callouts
- Update hardware device recommendations (Nitrokey Pro 2 -> Nitrokey 3)
- Broaden backup media terminology (USB thumb drive -> external media)
- Update wording to follow vale's linter recommendations
- Various minor wording improvements for clarity

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Reviewed-by: Paul Barker <paul@pbarker.dev>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250902-pgp-guide-updates-v1-1-62ac7312d3f9@linuxfoundation.org>
This commit is contained in:
Konstantin Ryabitsev 2025-09-02 11:44:19 -04:00 committed by Jonathan Corbet
parent dc896f853e
commit f44a29784f
1 changed files with 75 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -49,7 +49,7 @@ hosting infrastructure, regardless of how good the security practices
for the latter may be.
The above guiding principle is the reason why this guide is needed. We
want to make sure that by placing trust into developers we do not simply
want to make sure that by placing trust into developers we do not merely
shift the blame for potential future security incidents to someone else.
The goal is to provide a set of guidelines developers can use to create
a secure working environment and safeguard the PGP keys used to
@ -60,7 +60,7 @@ establish the integrity of the Linux kernel itself.
PGP tools
=========
Use GnuPG 2.2 or later
Use GnuPG 2.4 or later
----------------------
Your distro should already have GnuPG installed by default, you just
@ -69,9 +69,9 @@ To check, run::
$ gpg --version | head -n1
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.
If you have version 2.4 or above, then you are good to go. If you have
an earlier version, then you are using a release of GnuPG that is no
longer maintained and some commands from this guide may not work.
Configure gpg-agent options
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -199,13 +199,6 @@ separate signing subkey::
$ gpg --quick-addkey [fpr] ed25519 sign
.. note:: ECC support in GnuPG
Note, that if you intend to use a hardware token that does not
support ED25519 ECC keys, you should choose "nistp256" instead or
"ed25519." See the section below on recommended hardware devices.
Back up your Certify key for disaster recovery
----------------------------------------------
@ -213,7 +206,7 @@ The more signatures you have on your PGP key from other developers, the
more reasons you have to create a backup version that lives on something
other than digital media, for disaster recovery reasons.
The best way to create a printable hardcopy of your private key is by
A good way to create a printable hardcopy of your private key is by
using the ``paperkey`` software written for this very purpose. See ``man
paperkey`` for more details on the output format and its benefits over
other solutions. Paperkey should already be packaged for most
@ -224,11 +217,11 @@ key::
$ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt
Print out that file (or pipe the output straight to lpr), then take a
pen and write your passphrase on the margin of the paper. **This is
strongly recommended** because the key printout is still encrypted with
that passphrase, and if you ever change it you will not remember what it
used to be when you had created the backup -- *guaranteed*.
Print out that file, then take a pen and write your passphrase on the
margin of the paper. **This is strongly recommended** because the key
printout is still encrypted with that passphrase, and if you ever change
it you will not remember what it used to be when you had created the
backup -- *guaranteed*.
Put the resulting printout and the hand-written passphrase into an envelope
and store in a secure and well-protected place, preferably away from your
@ -236,10 +229,9 @@ home, such as your bank vault.
.. note::
Your printer is probably no longer a simple dumb device connected to
your parallel port, but since the output is still encrypted with
your passphrase, printing out even to "cloud-integrated" modern
printers should remain a relatively safe operation.
The key is still encrypted with your passphrase, so printing out
even to "cloud-integrated" modern printers should remain a
relatively safe operation.
Back up your whole GnuPG directory
----------------------------------
@ -255,16 +247,17 @@ on these external copies whenever you need to use your Certify key --
such as when making changes to your own key or signing other people's
keys after conferences and summits.
Start by getting a small USB "thumb" drive (preferably two!) that you
will use for backup purposes. You will need to encrypt them using LUKS
-- refer to your distro's documentation on how to accomplish this.
Start by getting an external media card (preferably two!) that you will
use for backup purposes. You will need to create an encrypted partition
on this device using LUKS -- refer to your distro's documentation on how
to accomplish this.
For the encryption passphrase, you can use the same one as on your
PGP key.
Once the encryption process is over, re-insert the USB drive and make
sure it gets properly mounted. Copy your entire ``.gnupg`` directory
over to the encrypted storage::
Once the encryption process is over, re-insert your device and make sure
it gets properly mounted. Copy your entire ``.gnupg`` directory over to
the encrypted storage::
$ cp -a ~/.gnupg /media/disk/foo/gnupg-backup
@ -273,11 +266,10 @@ You should now test to make sure everything still works::
$ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr]
If you don't get any errors, then you should be good to go. Unmount the
USB drive, distinctly label it so you don't blow it away next time you
need to use a random USB drive, and put in a safe place -- but not too
far away, because you'll need to use it every now and again for things
like editing identities, adding or revoking subkeys, or signing other
people's keys.
device, distinctly label it so you don't overwrite it by accident, and
put in a safe place -- but not too far away, because you'll need to use
it every now and again for things like editing identities, adding or
revoking subkeys, or signing other people's keys.
Remove the Certify key from your homedir
----------------------------------------
@ -303,7 +295,7 @@ and store it on offline storage.
your GnuPG directory in its entirety. What we are about to do will
render your key useless if you do not have a usable backup!
First, identify the keygrip of your Certify key::
First, identify the "keygrip" of your Certify key::
$ gpg --with-keygrip --list-key [fpr]
@ -328,8 +320,8 @@ Certify key fingerprint). This will correspond directly to a file in your
2222000000000000000000000000000000000000.key
3333000000000000000000000000000000000000.key
All you have to do is simply remove the .key file that corresponds to
the Certify key keygrip::
It is sufficient to remove the .key file that corresponds to the Certify
key keygrip::
$ cd ~/.gnupg/private-keys-v1.d
$ rm 1111000000000000000000000000000000000000.key
@ -372,7 +364,7 @@ GnuPG operation is performed, the keys are loaded into system memory and
can be stolen from there by sufficiently advanced malware (think
Meltdown and Spectre).
The best way to completely protect your keys is to move them to a
A good way to completely protect your keys is to move them to a
specialized hardware device that is capable of smartcard operations.
The benefits of smartcards
@ -383,11 +375,11 @@ private keys and performing crypto operations directly on the card
itself. Because the key contents never leave the smartcard, the
operating system of the computer into which you plug in the hardware
device is not able to retrieve the private keys themselves. This is very
different from the encrypted USB storage device we used earlier for
backup purposes -- while that USB device is plugged in and mounted, the
different from the encrypted media storage device we used earlier for
backup purposes -- while that device is plugged in and mounted, the
operating system is able to access the private key contents.
Using external encrypted USB media is not a substitute to having a
Using external encrypted media is not a substitute to having a
smartcard-capable device.
Available smartcard devices
@ -398,17 +390,15 @@ easiest is to get a specialized USB device that implements smartcard
functionality. There are several options available:
- `Nitrokey Start`_: Open hardware and Free Software, based on FSI
Japan's `Gnuk`_. One of the few available commercial devices that
support ED25519 ECC keys, but offer fewest security features (such as
resistance to tampering or some side-channel attacks).
- `Nitrokey Pro 2`_: Similar to the Nitrokey Start, but more
tamper-resistant and offers more security features. Pro 2 supports ECC
cryptography (NISTP).
Japan's `Gnuk`_. One of the cheapest options, but offers fewest
security features (such as resistance to tampering or some
side-channel attacks).
- `Nitrokey 3`_: Similar to the Nitrokey Start, but more
tamper-resistant and offers more security features and USB
form-factors. Supports ECC cryptography (ED25519 and NISTP).
- `Yubikey 5`_: proprietary hardware and software, but cheaper than
Nitrokey Pro and comes available in the USB-C form that is more useful
with newer laptops. Offers additional security features such as FIDO
U2F, among others, and now finally supports NISTP and ED25519 ECC
keys.
Nitrokey with a similar set of features. Supports ECC cryptography
(ED25519 and NISTP).
Your choice will depend on cost, shipping availability in your
geographical region, and open/proprietary hardware considerations.
@ -419,8 +409,8 @@ geographical region, and open/proprietary hardware considerations.
you `qualify for a free Nitrokey Start`_ courtesy of The Linux
Foundation.
.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6
.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3
.. _`Nitrokey Start`: https://www.nitrokey.com/products/nitrokeys
.. _`Nitrokey 3`: https://www.nitrokey.com/products/nitrokeys
.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/
.. _Gnuk: https://www.fsij.org/doc-gnuk/
.. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html
@ -455,7 +445,7 @@ the smartcard). You so rarely need to use the Admin PIN, that you will
inevitably forget what it is if you do not record it.
Getting back to the main card menu, you can also set other values (such
as name, sex, login data, etc), but it's not necessary and will
as name, gender, login data, etc), but it's not necessary and will
additionally leak information about your smartcard should you lose it.
.. note::
@ -615,7 +605,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] 2025-07-01
$ gpg --quick-set-expire [fpr] 2038-07-01
Remember to send the updated key back to keyservers::
@ -656,9 +646,9 @@ hundreds of cloned repositories floating around, how does anyone verify
that their copy of linux.git has not been tampered with by a malicious
third party?
Or what happens if a backdoor is discovered in the code and the "Author"
line in the commit says it was done by you, while you're pretty sure you
had `nothing to do with it`_?
Or what happens if malicious code is discovered in the kernel and the
"Author" line in the commit says it was done by you, while you're pretty
sure you had `nothing to do with it`_?
To address both of these issues, Git introduced PGP integration. Signed
tags prove the repository integrity by assuring that its contents are
@ -681,8 +671,7 @@ should be used (``[fpr]`` is the fingerprint of your key)::
How to work with signed tags
----------------------------
To create a signed tag, simply pass the ``-s`` switch to the tag
command::
To create a signed tag, pass the ``-s`` switch to the tag command::
$ git tag -s [tagname]
@ -693,7 +682,7 @@ not been maliciously altered.
How to verify signed tags
~~~~~~~~~~~~~~~~~~~~~~~~~
To verify a signed tag, simply use the ``verify-tag`` command::
To verify a signed tag, use the ``verify-tag`` command::
$ git verify-tag [tagname]
@ -712,9 +701,9 @@ The merge message will contain something like this::
# gpg: Signature made [...]
# gpg: Good signature from [...]
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.
If you are verifying someone else's git tag, you will first need to
import their PGP key. Please refer to the ":ref:`verify_identities`"
section below.
Configure git to always sign annotated tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -728,16 +717,16 @@ configuration option::
How to work with signed commits
-------------------------------
It is easy to create signed commits, but it is much more difficult to
use them in Linux kernel development, since it relies on patches sent to
the mailing list, and this workflow does not preserve PGP commit
signatures. Furthermore, when rebasing your repository to match
upstream, even your own PGP commit signatures will end up discarded. For
this reason, most kernel developers don't bother signing their commits
and will ignore signed commits in any external repositories that they
rely upon in their work.
It is also possible to create signed commits, but they have limited
usefulness in Linux kernel development. The kernel contribution workflow
relies on sending in patches, and converting commits to patches does not
preserve git commit signatures. Furthermore, when rebasing your own
repository on a newer upstream, PGP commit signatures will end up
discarded. For this reason, most kernel developers don't bother signing
their commits and will ignore signed commits in any external
repositories that they rely upon in their work.
However, if you have your working git tree publicly available at some
That said, if you have your working git tree publicly available at some
git hosting service (kernel.org, infradead.org, ozlabs.org, or others),
then the recommendation is that you sign all your git commits even if
upstream developers do not directly benefit from this practice.
@ -748,7 +737,7 @@ We recommend this for the following reasons:
provenance, even externally maintained trees carrying PGP commit
signatures will be valuable for such purposes.
2. If you ever need to re-clone your local repository (for example,
after a disk failure), this lets you easily verify the repository
after reinstalling your system), this lets you verify the repository
integrity before resuming your work.
3. If someone needs to cherry-pick your commits, this allows them to
quickly verify their integrity before applying them.
@ -756,9 +745,8 @@ We recommend this for the following reasons:
Creating signed commits
~~~~~~~~~~~~~~~~~~~~~~~
To create a signed commit, you just need to pass the ``-S`` flag to the
``git commit`` command (it's capital ``-S`` due to collision with
another flag)::
To create a signed commit, pass the ``-S`` flag to the ``git commit``
command (it's capital ``-S`` due to collision with another flag)::
$ git commit -S
@ -775,7 +763,6 @@ You can tell git to always sign commits::
.. _verify_identities:
How to work with signed patches
-------------------------------
@ -793,6 +780,11 @@ headers (a-la DKIM):
Installing and configuring patatt
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note::
If you use B4 to send in your patches, patatt is already installed
and integrated into your workflow.
Patatt is packaged for many distributions already, so please check there
first. You can also install it from pypi using "``pip install patatt``".
@ -835,9 +827,9 @@ encounters, for example::
How to verify kernel developer identities
=========================================
Signing tags and commits is easy, but how does one go about verifying
that the key used to sign something belongs to the actual kernel
developer and not to a malicious imposter?
Signing tags and commits is straightforward, but how does one go about
verifying that the key used to sign something belongs to the actual
kernel developer and not to a malicious imposter?
Configure auto-key-retrieval using WKD and DANE
-----------------------------------------------
@ -884,7 +876,7 @@ various software makers dictating who should be your trusted certifying
entity, PGP leaves this responsibility to each user.
Unfortunately, very few people understand how the Web of Trust works.
While it remains an important aspect of the OpenPGP specification,
While it is still an important part of the OpenPGP specification,
recent versions of GnuPG (2.2 and above) have implemented an alternative
mechanism called "Trust on First Use" (TOFU). You can think of TOFU as
"the SSH-like approach to trust." With SSH, the first time you connect
@ -894,8 +886,8 @@ to connect, forcing you to make a decision on whether you choose to
trust the changed key or not. Similarly, the first time you import
someone's PGP key, it is assumed to be valid. If at any point in the
future GnuPG comes across another key with the same identity, both the
previously imported key and the new key will be marked as invalid and
you will need to manually figure out which one to keep.
previously imported key and the new key will be marked for verification
and you will need to manually figure out which one to keep.
We recommend that you use the combined TOFU+PGP trust model (which is
the new default in GnuPG v2). To set it, add (or modify) the