This document is aimed at Linux kernel developers, and especially at subsystem maintainers. It contains a subset of information discussed in the more general “Protecting Code Integrity” guide published by the Linux Foundation. Please read that document for more in-depth discussion on some of the topics mentioned in this guide.

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 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 establish the integrity of the Linux kernel itself.

Ever since the 2011 compromise of core kernel.org systems, the main operating principle of the Kernel Archives project has been to assume that any part of the infrastructure can be compromised at any time. For this reason, the administrators have taken deliberate steps to emphasize that trust must always be placed with developers and never with the code hosting infrastructure, regardless of how good the security practices for the latter may be.

Both git repositories and tarballs carry PGP signatures of the kernel developers who create official kernel releases. These signatures offer a cryptographic guarantee that downloadable versions made available via kernel.org or any other mirrors are identical to what these developers have on their workstations. To this end:

PGP helps ensure the integrity of the code that is produced by the Linux kernel development community and, to a lesser degree, establish trusted communication channels between developers via PGP-signed email exchange.

Protect your master PGP key¶

This guide assumes that you already have a PGP key that you use for Linux kernel development purposes. If you do not yet have one, please see the “Protecting Code Integrity” document mentioned earlier for guidance on how to create a new one.

You should also make a new key if your current one is weaker than 2048 bits (RSA).

Master key vs. Subkeys¶ Subkeys are fully independent PGP keypairs that are tied to the “master” key using certifying key signatures (certificates). It is important to understand the following: There are no technical differences between the “master key” and “subkeys.” At creation time, we assign functional limitations to each key by giving it specific capabilities. A PGP key can have 4 capabilities: [S] key can be used for signing

key can be used for signing [E] key can be used for encryption

key can be used for encryption [A] key can be used for authentication

key can be used for authentication [C] key can be used for certifying other keys A single key may have multiple capabilities. A subkey is fully independent from the master key. A message encrypted to a subkey cannot be decrypted with the master key. If you lose your private subkey, it cannot be recreated from the master key in any way. The key carrying the [C] (certify) capability is considered the “master” key because it is the only key that can be used to indicate relationship with other keys. Only the [C] key can be used to: add or revoke other keys (subkeys) with S/E/A capabilities

add, change or revoke identities (uids) associated with the key

add or change the expiration date on itself or any subkey

sign other people’s keys for web of trust purposes By default, GnuPG creates the following when generating new keys: A master key carrying both Certify and Sign capabilities ( [SC] )

) A separate subkey with the Encryption capability ([E]) 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] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23] Any key carrying the [C] capability is your master key, regardless of any other capabilities it may have assigned to it. The long line under the sec entry is your key fingerprint – whenever you see [fpr] in the examples below, that 40-character string is what it refers to.

Ensure your passphrase is strong¶ GnuPG uses passphrases to encrypt your private keys before storing them on disk. This way, even if your .gnupg directory is leaked or stolen in its entirety, the attackers cannot use your private keys without first obtaining the passphrase to decrypt them. It is absolutely essential that your private keys are protected by a strong passphrase. To set it or change it, use: $ gpg --change-passphrase [fpr]

Create a separate Signing subkey¶ Our goal is to protect your master key by moving it to offline media, so if you only have a combined [SC] key, then you should create a separate signing subkey: $ gpg --quick-addkey [fpr] ed25519 sign Remember to tell the keyservers about this change, so others can pull down your new subkey: $ gpg --send-key [fpr] 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 master 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. If for some reason you prefer to stay with RSA subkeys, just replace “ed25519” with “rsa2048” in the above command. Additionally, if you plan to use a hardware device that does not support ED25519 ECC keys, like Nitrokey Pro or a Yubikey, then you should use “nistp256” instead or “ed25519.”

Back up your master key for disaster recovery¶ 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 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 distributions. Run the following command to create a hardcopy backup of your private 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. 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 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. One option is to change the passphrase on your master key immediately after you are done with paperkey.

Back up your whole GnuPG directory¶ Warning !!!Do not skip this step!!! It is important to have a readily available backup of your PGP keys should you need to recover them. This is different from the disaster-level preparedness we did with paperkey . You will also rely 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. For the encryption passphrase, you can use the same one as on your master 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: $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup 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.