Project:Gentoo-keys/Generating GLEP 63 based OpenPGP keys

From Gentoo Wiki
Jump to: navigation, search

General info

In this guide we are going to show you how to create a GLEP 63 based OpenPGP Key using app-crypt/gkeys-gen tool which is the official way of managing OpenPGP keys in the Gentoo Infrastructure.


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 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.

Gentoo Keys

Gentoo Keys is a Python based project that aims to manage the OpenPGP keys used for validation on users and Gentoo’s infrastructure servers.


The tool that is used to generate a GLEP 63 compliant OpenPGP key is app-crypt/gkeys-gen.

To install it run:

root #emerge --ask app-crypt/gkeys-gen

Then run the gkeys-gen command and follow the steps:

user $gkeys-gen gen-key

If you don't have an existing GnuPG setup you can just move the generated key to become the new GPG directory:

user $mv ~/gkeys-user/gpghome ~/.gnupg

When using an existing setup with GnuPG versions 1.4 or 2.0, it is possible to import the keys from the new keyring using:

user $gpg --import ~/gkeys-user/gpghome/{pubring,secring}.gpg

For GnuPG 2.1 the secret key store has changed, to import the keys use the following command instead:

user $gpg --import ~/gkeys-user/gpghome/pubring.{gpg,kbx}
user $cp ~/gkeys-user/gpghome/private-keys-v1.d/* ~/.gnupg/private-keys-v1.d/

Post generation phase

After the new key is created, for GnuPG < 2.1 the next thing you should do is to generate a revocation certificate. If your lose access to your primary key (either because it gets lost or you lose your passphrase) the revocation certificate will be your only way to mark this key as no longer being valid. Similarly if you have reason to believe your primary key in any way has been compromised it should be revoked. GnuPG 2.1 automatically generates revocation certificates, so for this you should copy the certificate from ~/gkeys-user/gpghome/openpgp-revocs.d/

Create revocation certificate

user $gpg --output \<\>.gpg-revocation-certificate --gen-revoke 0xDEADBEEF
Where 0xDEADBEEF is substituted with the KeyID or fingerprint of the newly generated key as output by gkeygen.

Generating an encryption subkey (Optional)

The default Gentoo Keys template generates a Certification-only primary key with a dedicated Signature subkey. If you want to use this key for Encryption purposes you will have to generate an Encryption capable subkey at this stage using the following interactive command:

user $ gpg --edit-key 0xDEADBEEF

which brings up a shell to work in. Additional subkeys are added using the addkey command and following the instructions.

Updating LDAP

For information on how to update the LDAP entry on woodpecker, see this FAQ entry


You should back up your primary key in a safe location, and want to consider also printing a copy and store in a bank vault or similar that can later be typed in manually or recovered using an OCR scanner. In order to minimize the overhead of such a recovery David Shaw’s utility paperkey (available in the main Portage tree as app-crypt/paperkey) can be used.

Export the secret subkeys

After the key is generated, we need to back it up somewhere safe, but first we need to export the secret subkeys that are to be used on a regular basis.

user $gpg --export-secret-keys --armor 0xDEADBEEF >

Publishing the public key

To export the public key to a file use the command

user $gpg --export --armor >

Once you’re satisfied with the newly generated key is configured as you want it, the key should be published to an operational keyserver pool using:

user $gpg --keyserver --send-keys 0xDEADBEEF
The keyserver network operates over the HKP protocol and defaults to port 11371. If you are behind a port-constrained network, use --keyserver hkp:// instead to use a more firewall friendly port.