Jump to content

PGP Keys

From Wikitech

This article provides a brief summary/introduction on use of PGP encryption in the wikimedia.org infrastructure. For more details on PGP in general, please see the the Wikipedia article on PGP.


PGP is an encryption standard and GnuPG (commonly referred to as GPG) is the most-used implementation. It comes in two flavours (GPG1 and GPG2, with the former being in maintenance mode; if you don't use it yet, start with GPG2).

GnuPG is traditionally a core component of every Linux distribution and is highly likely to be available in the repositories:

Distribution Package name
Debian/Ubuntu gnupg2
Fedora/RedHat gnupg2
Arch Linux gnupg

macOS download links can be found at the official GnuPG website.

Key creation

Now we need to generate a key pair. The public key will be send to the "key server network". If anyone wants to send you a PGP-encrypted email, she fetches your public key from the keyservers and encrypts the mail with it. Only the person in possession of the private key (i.e. you) is able to decrypt what she sent you.

There are front end tools, but the process is simple and may just as well be done in a terminal:

# Debian/Ubuntu:
gpg --gen-key # for full dialog: gpg --full-generate-key

# Fedora/RedHat/Centos:
gpg2 --full-generate-key

# Arch Linux:
gpg --full-gen-key

Please select the following options:

  • When asked for the key type, use "RSA and RSA"
  • When asked for the key size, select 4096. In some special cases 2048 might be the more appropriate selection (e.g. some PGP smartcards only support 2048 bit RSA)
  • The key validity can either be set to a specific timeframe (e.g. in five years from today onwards) or to unlimited validity. If you opt for a limited key validity, people will need to resign/refetch your new key after expiry. Going with an unlimited key still allows you to react on key changes; a key can be marked as "revoked" at any time. When in doubt limit the expiry to a year,
  • gpg will also ask for your name and your email address (see below to add additional email addresses). The comment entry can usually be left blank unless you're well-known by a nickname, e.g. Jimbo.

Now you'll need to enter a passphrase. The passphrase secures access to your key, so that even if someone manages to steal your private key file, the attacker will not be able to use the key unless they also know the passphrase. As such, a strong passphrase is very important; if it's too short or a common word, an attacker will be able to brute-force it. Micah Lee of The Intercept has written a great article on strong passphrases. More background information can be found in Wikipedia.

Following that, the key is created. You'll most likely see a message "We need to generate a lot of random bytes". That's totally harmless – simply do something else for a few minutes and your computer will have generated enough randomness based on your keyboard typing or mouse movements. If it complains that "Not enough random bytes available." try playing a video at the same time.

If you use an alias email address @wikimedia – e.g. nickname@wikimedia.org – in addition to the standard – first_letter_of_firstname_surname@wikimedia.org – you can edit your key to add the extra details:

gpg --edit-key name@wikimedia.org

A command prompt will appear. Now type adduid and reenter your name and add the new email address. After entering your passphrase you'll get back to the command prompt, now type save.

Your private key will be stored in ~/.gnupg/secring.gpg, so make sure to add it to a (secure) backup.

The private key should only be stored on a computer under your control, preferably using hard disk encryption.
Don't copy the key to your EC2 server, Google Drive or anything else potentially untrustworthy!

Publishing your key

Now that your key has been created, we need to send it to the keyserver(s). Most key servers synchronise between each other. A good choice is https://keys.openpgp.org/. Note: if openpgp keyservers are down, alternatively hkp://keyserver.ubuntu.com could be used.

Step-by-step instructions on how to publish your key are available here: https://keys.openpgp.org/about/usage

Signing keys

Your PGP key is now on the keyserver network, but there's no way for others to tell whether it's your key or someone who pretends to be you. On the one hand you can make your key known by adding it e.g. to your email signature. Aside from the 32-bit hex value mentioned above, every key has a fingerprint. The fingerprint is shown by running the command

gpg --fingerprint KEYID

If you advertise your key, you should always do that based on your fingerprint, not the 32-bit key ID. Using the short form is insecure!.

But the more important factor is the web of trust. Once you have validated that a given key belongs to a given person, you can sign their key. This allows others who trust your identity to also trust a person you trust.

There are many ways to confirm the identity (which are often subject to discussions, since some people have strong opinions on that matter). Some people only verify based on government-issued passports, but in most cases verifying people you know in a video session like Hangout is sufficient. You know these people based on their appearance, their dialects and their jokes, which is much more difficult to forge than a passport:

  • Make sure every participant creates their keys and sends them to the keyserver network
  • Fetch the keys of all people participating in the video session, select their fingerprints in a text file and collect all public keys in a keyring file (both files are sent to all attendees)
  • During the video session every participant reads out the fingerprint of her key
  • If the fingerprint read out matches the one you fetched from the keyserver you mark the fingerprint as validated
  • After the video session is over, import the keyring file using gpg --import KEYRINGFILE, sign their keys and send them to keyserver network:
gpg --sign-key VALIDATEDKEY
gpg --send-key VALIDATEDKEY
  • The keyserver network will detect the new signatures and whenever someone fetches the person's key, it's now marked as trusted by you

(There are some tools to automate the key signing processes (e.g. caff), but in most cases using the commands above will be simpler).

If you have a private PGP key already, you should sign your wikimedia.org key with your personal key. An alternative is to add your wikimedia.org address to your existing key, but generally it's more secure to keep both apart and only store your private key on your personal notebook and only store your wikimedia.org key on your work machine.

Renewing keys

When your key expires, it's no longer valid. Before anyone can use it again (e.g. to verify your signature, or to re-encrypt the pwstore database) you'll need to renew it, which you can do either before or after the expiration. You can do this by editing the key to change the expiration date.

$gpg --edit-key NAME@wikimedia.org
gpg> expire
Changing expiration time for the primary key. [...]

GPG will prompt you for a new expiration date for the primary key; you can enter e.g. "5y" to set an expiration date five years in the future. Then you'll get a warning:

gpg: WARNING: Your encryption subkey expires soon.
gpg: You may want to change its expiration date too.

First select the subkey to update, then set its expiration date the same way:

gpg> key 1
gpg> expire
Changing expiration time for a subkey. [...]

Enter the same length of time as you chose for the primary key. Finally, save the key:

gpg> save

Now you have a copy of your renewed key; follow the steps under Publishing your key to make the renewed key available to others.

Revoking Keys

In the event you need to notify others to not use a key you have published, you can issue a revocation.

gpg --armor --output revoke.asc --gen-revoke KEYID
gpg --import revoke.asc
gpg --send-keys REVOKEKEYID  # The revocation key id

Using PGP in your mail client

Documentation for integrating PGP into mail clients: