Project:Infrastructure/Generating GLEP 63 based OpenPGP keys

This guide [[Article description::provides Gentoo developers with best practice details on creating a GLEP 63 compliant [[wikipedia:Pretty_Good_Privacy#OpenPGP|OpenPGP]] key.]]

OpenPGP
OpenPGP is one of the most widely used cryptographic standards in the world. The OpenPGP standard was originally derived from PGP (Pretty Good Privacy), first created by Phil Zimmermann in 1991, and is now maintained by the OpenPGP Working Group of the Internet Engineering Task Force. One of the most used open source implementations of the OpenPGP standard is the GNU Privacy Guard (GnuPG).

The OpenPGP standard is a hybrid scheme utilizing both asymmetrical and symmetrical cryptography to establish the cryptosystem. The asymmetrical components are used to establish a nPKI (Public Key Infrastructure) ad when mentioning keys in this document, it is a reference to the asymmetrical components. It is a hybrid system when used for data encryption, as the data itself is encrypted symmetrically using a random session key, which is afterwards encrypted individually using the asymmetrical encryption keys of each recipient.

OpenPGP keys (i.e. asymmetrical) normally consists of a primary key used for certification and signing and a subkey capable of Encryption. This is often extended to using a primary key for certification purposes only, and separate subkeys for Signing and Encryption. Such a scheme allows for the primary key to be stored offline, while the subkeys are used for day-to-day use.

When generating a new User ID, a new subkey, creating a certification (signature) of another key, or performing revocation procedures, the primary key will have to be used, and as such these operations are normally conducted on a more secure system. As certifications by other users are tied to the primary key, as components structured below the User ID and User Attribute, this allows for key-rotation without losing existing certificates of the key, e.g. in the event of a key compromise due to loss of a device.

GLEP 63
GLEP 63 is a proposal accepted by the Gentoo Council which provides both a minimum requirement and a recommended set of OpenPGP key management policies for the use of GnuPG  by Gentoo Linux developers. It is intended to provide a basis for future improvements such as consistent ebuild or package signing and the possibility of verification of integrity by end users.

Generating a GLEP 63-compliant OpenPGP key
In the next few steps we will show you how to generate a GLEP 63-compliant OpenPGP key. This key should last for next 10 years and be flexible enough to support as many setups as possible (e.g. various hardware token). In the end this key should allow you to become part of the Web of Trust while helping to keep Gentoo secure.

Step 1: Install the tools you will need
We will need the normal GnuPG 2.x CLI client. If it is not installed yet, you can install it with

Step 2: Backup an existing GnuPG setup
First, backup an existing GnuPG configuration, including the private keyring. The location of the current GnuPG configuration and keyrings can be displayed with:

Now that GnuPG's current homedir has been discovered ( in this example), create a backup of the current GnuPG configuration, including the keyrings:

is used to restrict access to the backup file. Note the parenthesis - the command is running in a subshell to avoid resetting } afterwards. It is safe to ignore the warnings regarding ignored sockets above.

Step 3: Update gpg.conf
This step is optional but recommended: Make sure the file (usually located in ) contains the following settings:

Step 4: Create a new master key
With the configuration from above in place, a new master key can be created. The master key will only have the capability "Certify" and is only needed when the key is modified or when you sign someone else's key. Separating capabilities will allow you to split master key from subkeys so that you can keep master key in a secure, air-gapped, environment for example.

Step 5: Create subkeys
To be able to sign commits or push signed to any Gentoo repository, we will need a subkey with "Sign" capability. Therefore we will create a RSA key with keysize of 2048-bits and a validity of 1 year (note that we will use the previous shown fingerprint when we specify which key we want to edit):

Now it is also recommended that you will create a subkey you can use for encryption. This will allow you to encrypt files against your OpenPGP key and allow others to send you encrypted messages for example:

Step 6: Add a subkey for authentication
This step is optional. If you want to use your OpenPGP key for SSH authentication as well, it is recommended to add a dedicated subkey just for authentication:

Summary
The creation of a new, GLEP 63-compliant OpenPGP key is now completed. Let's view the new key:

Submit the new key to the keyserver
After the newly generated key has been configured, the key should be published to the Gentoo keyserver.

The Gentoo keyserver is restricted to accepting uploads from authorized Gentoo hosts. A convenience key upload script is provided on the developer machine:

It is recommended to also upload the new key to a public keyserver. This will allow others to easily discover it and send encrypted mails. A privacy-friendly and stable keyserver is keys.openpgp.org:

Updating LDAP
The next step is to update the LDAP entry on woodpecker, so that the new key will be recognized and is allowed to push to Gentoo repositories. See this FAQ entry for more details.

Split key
TODO: Add information how to split key so that you can keep master key on an air-gapped system for example and/or use keycard, YubiKey...

Fix an existing key
If you already have an existing OpenPGP key and maybe want to keep the received signatures (i.e. Web of Trust status), it maybe possible to adjust the existing key to become GLEP 63-compliant. The following guide provides some examples non-compliant keys and how they can be fixed:

Assume the key looks like the following:

What's wrong with this key? Let's assume today's date is 2019-08-27:


 * This key violates 2. Signing subkey that is different from the primary key, and does not have any other capabilities enabled because the subkey (0x5AD7FB3114AA19AD) has both, "Sign" and "Authenticate" capability enabled.
 * This key violates 3. Primary key and the signing subkey are both of type EITHER:\na) RSA, >=2048 bits (OpenPGP v4 key format or later only), because the signing subkey has a keysize <2048 bits.
 * This key violates 4. Expiration date on key and all subkeys set to no more than 900 days into the future. because the master key doesn't expire within next 900 days and the encryption subkey (0x594CA20866E92013) has no expiration date set at all.
 * This key violates 6. UID using your @gentoo.org e-mail included in the key. because Larry the Cow hasn't added his Gentoo UID (@gentoo.org address).

Replace an invalid subkey
To fix a violation of requirement #2 and #3, the violating subkey must be replaced with a new subkey. Because a subkey cannot be removed, the offending subkey must be marked as expired, and a new subkey added.

The violating key will expire tomorrow.

Next add the new, valid signing subkey:

Invalid expiration date
An OpenPGP key can have an expiration date for the master key itself and a unique/Independent expiration date for each subkey. In the example above, we have to fix two expiration dates:


 * For the master key (currently set to 2026-01-25 which violates the maximum expiration date of 900 days)
 * For the encryption key (doesn't have an expiration date at the moment but GLEP 63 requires that every key has an expiration date set)

To fix this, edit key and set a new expiration date:

Changing the expiration date for the encryption subkey (0x594CA20866E92013) works the same; just be sure to select the correct subkey:

It is possible to change the expiration date for both keys in one step. This guide used two steps to demonstrate how to switch/select keys separately.

Adding missing Gentoo UID
GLEP 63 requires that the UID of the key is your Gentoo e-mail address. Let's add one to our key:

Summary
Now that we have fixed all issues, our now GLEP 63-compliant key looks like

Don't forget to submit the updated key to the keyserver(s) so that the Gentoo project infrastructure can discover the changes.