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 GNU PG (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).
GNU PG is part of every Linux distribution, for Debian/Ubuntu simply run
apt-get install gnupg2. For Fedora or RedHat based distributions, run
dnf install gnupg2.
Mac OS X download links can be found at https://gnupg.org/download/index.html
Now we need to generate a key pair:
- 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 etc.!
- 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.
- NOTE: In RedHat/Centos, gpg 1.x is the default. If you get
gpg: Invalid option "--full-generate-key", you will want likely want to replace
gpg2command or update gnupg. Tested with gnupg 2.2.8.
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 # Fedora/RedHat/Centos gpg2 --full-generate-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. firstname.lastname@example.org – in addition to the standard – email@example.com – you can edit your key to add the extra details:
gpg --edit-key firstname.lastname@example.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
Your private key will be stored in ~/.gnupg/secring.gpg, so make sure to add it to a (secure) backup.
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 the SKS keyserver network.
Preferrably keys should be retrieved using HKPS (TLS-secured key retrieval) via separate pool. The use is documented on the SKS website.
For the less secure non-transport encrypted just select one of the pools by adding the following option to ~/.gnupg/gpg.conf:
Now push your key to the keyserver network. First identify the key ID of your key by running
gpg --list-key email@example.com
You will receive a entry which starts with "pub 4096R/" and ends with the key creation date. The 32-bit (8-character) hex value in between is your key ID, e.g. ED64ABED. Now send your key to the keyserver network:
gpg --send-key ED64ABED
That's all, your key will be synchronised to the other keyservers automatically.
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.
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:
Now you have a copy of your renewed key; follow the steps under Publishing your key to make the renewed key available to others.
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:
- Thunderbird: The enigmail extension integrates PGP: https://www.enigmail.net/home/index.php
- Apple mail: https://ssd.eff.org/en/module/how-use-pgp-mac-os-x
- KMail: https://userbase.kde.org/KMail/PGP_MIME
- (add your client)