Project:Infrastructure/Generating GLEP 63 based OpenPGP keys

General info
In this guide we are going to show you how to create a GLEP 63 based OpenPGP Key following best practice.

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.

How to generate the 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 your existing GnuPG setup
First, backup your existing GnuPG configuration, including your private keyring. You can display the location of your current GnuPG configuration and keyrings with:

Now that you know your GnuPG's current homedir ( in this example), you can create a backup of your current GnuPG configuration, including your keyrings:

(we use umask to restrict access to the backup file; Please note the parenthesis -- we are running the command in a subshell to avoid resetting umask afterwards; It is safe to ignore the warnings regarding ignored sockets above)

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

Step 4: Create your new master key
With the configuration from above in place, your 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-gaped, 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 your new, GLEP 63-compliant OpenPGP key is now completed. Let's view your new key:

Submit your new key to the keyserver
Once you're satisfied with the newly generated key is configured as you want it, the key should be published to both the Gentoo keyserver AND the public SKS keyserver pool.

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

SKS pool is publicly accessible, so you can upload to it directly:

The SKS keyserver pool can take much longer to replicate over the keyserver network, while the Gentoo developer tooling explicitly checks the Gentoo keyserver pool with a much higher frequency.

Non-developers can't upload their keys to the Gentoo keyserver.

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

Split key
Add information how to split key so that you can keep master key on an air-gaped 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 your received signatures (i.e. Web of Trust status), it maybe possible to just fix your existing key to become GLEP 63-compliant. The following guide will show you some examples and how you fix them.

Let's assume your key looks like

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 we have to replace violating subkey with new subkey. Because you cannot really remove a subkey, we will expire the offending subkey first and add a new afterwards.

The violating key will expire tomorrow.

Now we can add our 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, we edit key and set a new expiration date:

Changing the expiration date for the encryption subkey (0x594CA20866E92013) works the same, we just have to make sure we selected the right subkey:

Of course, you could have changed expiration date for both keys in one step. This guide used two steps to demonstrate how to switch/select key you are working on.

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 your updated key to the keyservers so that Gentoo can pick up the changes.