How to use this guide.
We have gathered here a lot of information about configuring GnuPG. There are detailed explanations for each configuration suggestion. Many of these changes require you to make changes to the GnuPG configuration file on your machine located at
~/.gnupg/gpg.conf
. For your convenience, all the suggested changes to the
gpg.conf
file are gathered in one place
near the bottom of this page. We strongly encourage you to not blindly copy the file, but read the document and understand what the settings do.
Use free software, and keep it updated.
Information security is too important to leave to proprietary software. You should use a free OpenPGP implementation, and keep it up-to-date. The canonical free OpenPGP implementation is
GnuPG, and it is available for every major modern operating system. It is not enough to install GnuPG and forget about it, though. You
must keep it up to date so that critical security flaws are fixed. All software has bugs, and GnuPG is no exception. If you are running:
- GNU/Linux (Debian, Ubuntu, Mint, Fedora, etc)
- your operating system will install GnuPG automatically and keep it up to date for you.
- Windows
- you can install Gpg4win and subscribe to gpg4win-announce to know when to update.
- Mac OS
- you can install GPG suite from GPGTools (how do you know when you need to update?).
- Building from source for any other operating system
- you should subscribe to gnupg-announce to know when you should update.
Selecting a keyserver and configuring your machine to refresh your keyring.
If you do not regularly refresh your public keys, you do not get timely expirations or revocations, both of which are very important to be aware of! There are two components to receiving key updates. Many users send their key updates to keyservers. In order to receive these updates, you must first ensure that you are using a keyserver that is functioning properly. Then, you have to configure your machine to receive key updates in a regular fashion.
Use the sks keyserver pool, instead of one specific server, with secure connections.
Most OpenPGP clients come configured with a single, specific keyserver. This is not ideal because if the keyserver fails, or even worse, if it appears to work but is not functioning properly, you may not receive critical key updates. Not only is this a single point of failure, it is also a prime source of leaks of relationship information between OpenPGP users, and thus an attack target.
Therefore, we recommend using the
sks keyservers pool. The machines in this pool have regular health checks to ensure that they are functioning properly. If a server is not working well, it will be removed automatically from the pool.
You should also ensure that you are communicating with the keyserver pool over an encrypted channel, using a protocol called hkps. In order to use hkps, you will first need to install gnupg-curl:
sudo apt-get install gnupg-curl
Then, to use this keyserver pool, you will need to
download the sks-keyservers.net CA, and save it somewhere on your machine. Please remember the path that you save the file to! Next, you should
verify the certificate’s finger print.
Now, you will need to use the following parameters in
~/.gnupg/gpg.conf
, and specify the full path where you saved the .pem file above:
keyserver hkps://hkps.pool.sks-keyservers.net
keyserver-options ca-cert-file=/path/to/CA/sks-keyservers.netCA.pem
Now your interactions with the keyserver will be encrypted via hkps, which will obscure your social relationship map from anyone who may be snooping on your traffic. For example, if you do a
gpg --refresh-keys
on a keyserver that is hkp only, then someone snooping your traffic will see every single key you have in your key ring as you request any updates to them. That is pretty interesting information.
Note: hkps://keys.indymedia.org, hkps://keys.mayfirst.org and hkps://keys.riseup.net all offer this (although it is recommended that you use a pool instead).
Ensure that all keys are refreshed through the keyserver you have selected.
When creating a key, individuals may designate a specific keyserver to use to pull their keys from. It is recommended that you use the following option to
~/.gnupg/gpg.conf
, which will ignore such designations:
keyserver-options no-honor-keyserver-url
This is useful because (1) it prevents someone from designating an insecure method for pulling their key and (2) if the server designated uses hkps, the refresh will fail because the ca-cert will not match, so the keys will never be refreshed. Note also that an attacker could designate a keyserver that they control to monitor when or from where you refresh their key.
Refresh your keys slowly and one at a time.
Now that you have configured a good keyserver, you need to make sure that you are regularly refreshing your keys. The best way to do this on Debian and Ubuntu is to use parcimonie:
sudo apt-get install parcimonie
Parcimonie is a daemon that slowly refreshes your keyring from a keyserver over
Tor -. It uses a randomized sleep, and fresh Tor circuits for each key. The purpose is to make it hard for an attacker to correlate the key updates with your keyring.
You should
not use
gpg --refresh-keys
or the refresh keys menu item on your email client because you disclose to anyone listening, and the keyserver operator, the whole set of keys that you are interested in refreshing.
Do not blindly trust keys from keyservers.
Anyone can upload keys to keyservers and there is no reason that you should trust that any key you download actually belongs to the individual listed in the key. You should therefore verify with the individual owner the full key fingerprint of their key. You should do this verification in real life or over the phone.
Once you have verified the key fingerprint that you need, you may download the key from the keyserver pool:
gpg --recv-key ''
The next step is to confirm that you actually got the correct key from the keyserver. The keyserver might have given you a different key than the one you just asked for. If you have gpg with version less than 2.1, then you must manually confirm the fingerprint after you have downloaded the key (versions 2.1 and later will refuse to accept incorrect keys from the keyserver).
You can confirm the key fingerprint in one of two ways:
Option 1. Check the fingerprint is now in your keyring:
gpg --fingerprint ''
Option 2. Attempt to (locally) sign a key with that fingerprint:
gpg --lsign-key ''
If you are confident you have the right fingerprint from the owner of the key, the preferred method is to locally sign the key. If you want to publicly advertise your connection to the person who owns the key, you can do a publicly exportable
--sign-key
instead.
Note the single quote marks above (’), which should surround your full fingerprint and are necessary to make this command work. Double-quotes (") also work.
Don’t rely on the Key ID.
Short OpenPGP Key IDs, for example 0×2861A790, are 32 bits long. They have been
shown to be easily spoofed by another key with the same Key ID. Long OpenPGP Key IDs (for example 0xA1E6148633874A3D) are 64 bits long. They are
trivially collidable, which is
also a potentially serious problem.
If you want to deal with a cryptographically-strong identifier for a key, you should use the full fingerprint. You should
never rely on the short, or even long, Key ID.
You should probably at least set
keyid-format 0xlong
and
with-fingerprint
gpg options (put them in
~/.gnupg/gpg.conf
) to increase the Key ID display size to 64-bit under regular use, and to always display the fingerprint.
Note that there was a
bug in enigmail, which is fixed in version 1.7.0: If you add the option ‘with-fingerprint’ to display full fingerprints when listing keys, the fingerprint that is displayed in the enigmail key management window will be that of a subkey rather than the fingerprint of the primary key. You can always find your primary key’s fingerprint (for example, if you want to give your fingerprint to someone to verify at a keysigning party), you can display the fingerprints of all of your secret keys by running this:
gpg --with-fingerprint --list-secret-key
Check key fingerprints before importing.
If you received or downloaded a key in a
, you can and should display its fingerprint before importing it into your keyring, in that way you can verify the fingerprint without possibly spoiling your keyring and adding a compromised key:
gpg --with-fingerprint
Key configuration.
Now that you know how to receive regular key updates from a well-maintained keyserver, you should make sure that your OpenPGP key is optimally configured. Many of these changes may require you to generate a new key.
Use a strong primary key.
Some people still have 1024-bit
DSA keys. You really should transition to a stronger bit-length and hashing algo. In 2011, the US government instution
NIST has
deprecated DSA-1024, since 2013 it is even
disallowed.
It is recommend to make a 4096bit
RSA key, with the sha512 hashing algo, making a
transition statement that is signed by both keys, and then letting people know. Also have a look at this
good document that details
exactly the steps that you need to create such a key, making sure that you are getting the right hashing algo (it can be slightly complicated if you are using GnuPG versions less than 1.4.10).
Transitioning can be painful, but it is worth it, and a good opportunity to practice with the tools!
Use an expiration date less than two years.
People think that they don’t want their keys to expire, but you actually
do. Why? Because
you can always extend your expiration date, even after it has expired! This “expiration” is actually more of a safety valve or “dead-man switch” that will automatically trigger at some point. If you have access to the secret key material, you can untrigger it. The point is to setup something to disable your key in case you lose access to it (and have no revocation certificate).
Setting an expiration date means that you will need to extend that expiration date sometime in the future. That is a small task that you will need to remember to do (see next item about setting a reminder).
You may think that is annoying and you don’t want to deal with it, but it is actually good to be doing this on a regular basis so you keep your OpenPGP skills fresh. It indicates to users that they key is still active, and that the keyholder is using it, and gives you an opportunity to review the current state of your tools, and best practices. Also, many people will not sign a key that has no expiration date!
If you have already generated a key without an expiration date, you can set an expiration date on your key by doing the following:
gpg --edit-key ''
Now select the subkey for which you want to set an expiration date (e.g. the first one), or none to set the expiration on your primary key and then issue the ‘expire’ command:
gpg> key 1
gpg> expire
Then set the date to a reasonable one, and save the key and exit (e.g. 2 years):
Key is valid for? (0) 2y
gpg> save
Then you may send your key to the keyservers to publish this change:
gpg --send-key ''
Set a calendar event to remind you about your expiration date
You won’t remember, so its best to ask something to remind you. Set your reminder a month or more before the date so you can do the change with some time. You do not want to be rushed when you are dealing with your keys.
Remember: you can always extend your expiration date (even after it has expired!), so you do not need to make a brand new key, you just need to extend your expiration to a later time. Doing this on a regular basis is good to exercise your OpenPGP muscles, otherwise you will forget things.
Generate a revocation certificate.
If you forget your passphrase or if your private key is compromised or lost, the only hope you have is to wait for the key to expire (this is not a good solution), or to activate your revocation certificate by publishing it to the keyservers. Doing this will notify others that this key has been revoked.
A revoked key can still be used to verify old signatures, or decrypt data (if you still have access to the private key), but it cannot be used to encrypt new messages to you.
gpg --output revoke.asc --gen-revoke ''
This will create a file called revoke.asc. You may wish to print a hardcopy of the certificate to store somewhere safe (give it to your mom, or put it in your offsite backups). If someone gets access to this, they can revoke your key, which is very inconvenient, but if they also have access to your private key, then this is exactly what you want to happen.
Only use your primary key for certification (and possibly signing). Have a separate subkey for encryption.
(bonus) Have a separate subkey for signing, and keep your primary key entirely offline.
In this scenario, your primary key is used only for certifications, which happen infrequently.
OpenPGP key checks.
There is a handy tool that will perform the key checks below for you. You can get it
from the source, or if you are running Debian or Ubuntu, you can install the package directly by doing:
sudo apt-get install hopenpgp-tools
To run these tests with the tool, you can do the following:
hkt export-pubkeys '' | hokey lint
The output will display any problems with your key in red text. If everything is green, your key passes each of the tests below. If it is red, your key fails one of the tests listed below and you should fix it or generate a new key after ensuring that your
gpg.conf
is set up as recommended.
Make sure your key is OpenPGPv4
According to
RFC4880: “V3 keys are deprecated. They contain three weaknesses. First, it is relatively easy to construct a V3 key that has the same Key ID as any other key because the Key ID is simply the low 64 bits of the public modulus. Secondly, because the fingerprint of a V3 key hashes the key material, but not its length, there is an increased opportunity for fingerprint collisions. Third, there are weaknesses in the MD5 hash algorithm that make developers prefer other algorithms. See below for a fuller discussion of Key IDs and fingerprints”
To determine if your key is a V3 key you can do the following:
gpg --export-options export-minimal --export '' | gpg --list-packets |grep version
primary keys should be DSA-2 or RSA (RSA preferred), ideally 4096 bits or more.
To check if you are using
DSA-2 or
RSA, you can do this:
gpg --export-options export-minimal --export '' | gpg --list-packets | grep -A2 '^:public key packet:$' | grep algo
If the reported algorithm is 1, you are using
RSA. If it is 17, then it is
DSA and you will need to confirm that the size reported in the next check reports a bit-length key size greater than 1024, otherwise you aren’t using
DSA-2.
If the reported algorithm is 19, you are using
ECDSA, if it is 18 you are using
ECC, and the key bit-length determination check below is not an appropriate criteria for these types of keys as as the key sizes will drop significantly.
To check the bit-length of the primary key you can do this:
gpg --export-options export-minimal --export '' | gpg --list-packets | grep -A2 'public key' | grep 'pkey\[0\]:'
self-signatures should not use MD5 exclusively
You can check this by doing:
gpg --export-options export-minimal --export '' | gpg --list-packets | grep -A 2 signature | grep 'digest algo'
If you see any ‘digest algo 1’ results printed, then you have some self-signatures that are using MD5, as digest algo 1 is MD5. See the
OpenPGP RFC 4880, section 9.4 for a table that maps hash algorithms to numbers.
To fix this, first, you should set the following in your
~/.gnupg/gpg.conf
:
cert-digest-algo SHA512
Second, you should generate a new self-signature on your key (e.g.
by changing the key’s expiration date).
self-signatures should not use SHA1
You can check this by doing:
gpg --export-options export-minimal --export '' | gpg --list-packets | grep -A 2 signature | grep 'digest algo 2,'
If you see any ‘digest algo 2’ results printed, then you have some self-signatures that are using SHA1, as digest algo 2 is SHA1. See the
OpenPGP RFC 4880, section 9.4 for a table that maps hash algorithms to numbers.
To fix this, you can generate a new self-signature on your key (e.g.
by changing its expiration date) after setting the following in your
~/.gnupg/gpg.conf
:
cert-digest-algo SHA512
stated digest algorithm preferences must include at least one member of the SHA-2 family at a higher priority than both MD5 and SHA1
You can check this by doing:
gpg --export-options export-minimal --export '' | gpg --list-packets | grep 'pref-hash-algos'
and then inspect the results. The preference order is based on which number comes first from left to right. If you see the number ‘3’, ‘2’, or ‘1’ before you see ‘11’, ‘10’, ‘9’ or ‘8’, then you have specified your preferences to favor a weakened digest algorithm
To fix this, first set the following in your
~/.gnupg/gpg.conf
:
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
then set the preferences on your key like this:
$ gpg --edit-key ''
gpg> setpref
...
gpg> save
primary keys should have a reasonable expiration date (no more than 2 years in the future)
You can check what your expiration dates are by doing this:
gpg --export-options export-minimal --export '' | gpg --list-packets | grep 'key expires after'
Then visually inspect what the results are to confirm this — the date listed will be relative to key creation, though, which can be difficult to interpret.
Another way to check expiration is just to do:
gpg --list-keys ''
which should show the creation and expiration dates of the primary key and each associated subkey. If you don’t see anything that says “expires” in this output, then you have not set an expiration date properly.
To fix this, you can do:
$ gpg --edit-key ''
gpg> expire
...
gpg> save
Putting it all together.
All the recommended settings discussed on this guide have been combined into one configuration file at Jacob Appelbaum’s
duraconf “collection of hardened configuration files.” You may
right-click on this link and save the gpg.conf in your
~/.gnupg/gpg.conf
(linux and MacOS). For windows users, the gpg.conf file should be saved to
AppData\GnuPG\
.
You will need to uncomment and/or adjust the following settings to your local preferences:
default-key
,
keyserver-options ca-cert-file
and
keyserver-options http-proxy
.
Additional suggestions.
Do you have an encrypted backup of your secret key material?
Double check on it.
Do not include a “Comment” in your User ID.
If you think you need a “Comment” field in your OpenPGP User ID
please think long and hard before deciding that is really the case. You probably don’t need or want it, and having a comment field makes it harder for people to know what they’re certifying.
https://help.riseup.net/en/security/message-security/openpgp/best-practices