Table of Contents:

About this document


This document was first published at – updated versions will go there, too. Please ensure that you have the latest copy of this document by checking the version list.

This document is basically a rewrite of Daniel Kahn Gillmor’s excellent May 2009 article “HOWTO prepare for migration off of SHA-1 in OpenPGP” at – but much simplified and rephrased for a less technical audience which just “wants it to work”. Note that there is no such thing as “just works” in security, since understanding how things work (and how not, and where its limits are exactly) is an essential component of security. However, people are often scared off by too technical documentation, so this one will be kept simple, and you still have the option of (and are encouraged to) reading up on everything on dkg’s weblog and elsewhere.

Normally, as Daniel describes in his weblog, you should prepare and roll over your keys along a period of a few months. However, if you are reading this document, which was only first published more than a year after it was about time to start rolling over your keys, then you are already late, and you will likely want to roll over your keys as soon as possible. As such, the preparatory process is omitted in this document.

I have tried to describe the process as simple as possible while trying to be roughly factually correct and not completely imprecise. I am, like any human, prone to error and may thus have gotten something wrong which could be equally well explained with correct facts. If you find this is the case, please contact me by email at alster at tachanka D0T org. If you would like to encrypt your email, please use the 0x778E467839A8722D key as found in the SKS keyserver pool (

You are welcome to share and remix this document under the terms of the CreativeCommons Attribution-NonCommercial-ShareAlike 3.0 Unported license.



This section is going to be a little technical, so if you’re already convinced you need to roll your key(s) over then just skip this.

Encryption usually relies on so-called hash functions, a method to create, for a given text, an almost unique alternative representation, a so-called digest. This method should, however, only work in one direction, so you can create the digest from the text but can not recover the original text from the digest, even though each digest just stands for very few original texts. If you were able to do this, this hash function would be considered broken and could be no longer used for encryption.

GPG also makes use of such hash functions during message signing. Traditionally GPG would create so-called DSA keys, which were limited to 1024 bit key length and to using 160-bit sized hashes, traditionally using the SHA-1 hash function. Most people will have generated such keys during the past decade. The issue with these keys is two-fold: with new developments in cryptanalysis (“hacking encryption”) in recent years, 1024 bit keys need to be considered short now. What’s worse, the SHA-1 hash function has immanent design issues which show that you can create the same hash using two different original texts considerably easier than you should be able to. That’s a bad omen and a good reason to replace one hash function by another.

So you need both longer (>= 2048 bit) keys and an encryption mechanism which works with a hash function which is not weak. DSA fails on both fronts. The other common encryption scheme named RSA has been supported by most encryption software since a long time and perfectly meets the requirements, too. Therefore, this document will discuss how to create new RSA keys.


Everyone who is currently using DSA keys with 1024 bit length, which have been the default key type in GPG for quite a while, should roll over (i.e. replace) their keys. Actually everyone using DSA OR RSA primary keys shorter than 2048 bit should do it.

To determine which keys you have open a terminal window and enter:

gpg --list-secret-keys

All lines starting ‘sec 1024D’ indicate keys which need to be replaced (unless you already did, but you will be aware of it if you already did it).

This command lists the key IDs of those of your keys you need to replace, including expired or revoked keys:

gpg --list-secret-keys --with-colons | awk -F : '{ if ( $1=="sec" && $3=="1024" && $4=="17" ) print $5 }'

To inspect these in detail, use:

gpg --fingerprint --list-keys `gpg --list-secret-keys --with-colons | awk -F : '{ if ( $1=="sec" && $3=="1024" && $4=="17" ) print $5 }'`

If it does not work for you, just look up the keys to be replaced as explained in the first command above. Take a note of the ‘sec’ key IDs (the 8 or 16 character code), you will need them later.

What’s required?

This document is mostly targeted at Linux users. The commands provided were tested on Ubuntu 10.04 (Lucid Lynx), but may apply to other operating systems just as well. Being somewhat comfortable with typing commands into a terminal window / working with a command line is a requirement, too.

This document requires you to use a GPG 1.x version higher than or equal to 1.4.10 (It may also work with GPG 1.4.9, but you may need to create your RSA key pair in two separate steps using the GPG command line interface then), or a GPG 2.x version higher than or equal to 2.0.16. To determine your GPG version, use:

gpg --version

It is also required that you use Thunderbird 3.0 or higher and Enigmail 1.0.1 or higher (but Thunderbird 2.0 and Enigmail 0.96.0 are assumed to work, too). You should be able to determine which versions you have installed using the Thunderbird menu options “Help” → “About Thunderbird” and “OpenPGP” → “About OpenPGP” respectively.

If any of your versions are too low, please consult the documentation your operating system provides for installing updated versions.

How to do it?

Update your GPG preferences

Run a text editor such as Vim, Nano, Jed, Pico, GEdit, Kate, Wordpad, Notepad++ (but not Notepad!). Open the GPG configuration file which is located in your home directory in a hidden subdirectory called .gnupg, in a file called gpg.conf. For example:

nano /home/alster/.gnupg/gpg.conf

Go to the end of this file, add a blank new line, then paste this:

personal-digest-preferences SHA256
cert-digest-algo SHA256
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed

Save the file and exit the text editor.

Create new key

Back to the list of keys you are going to phase out (see above on how to determine which keys to replace). For each of these keys you want to replace (i.e. those you still need), you should now create new ones, using the RSA encryption scheme and at least 2048 bit length. This can be done with either Enigmail or GPG directly (using the command line interface).

Using Enigmail:

Using GPG on the command line:

Sign your new key using your old key

You should let other people know that you (who was using your old key so far when communicating with them) fully trust that other key (the one you just created). If you would not do this, your new key would look just like any other key to them. Sure, it does have your email address on it and this new keys’ user (you) would claim that this is ‘my new key, replacing the old one’. But for the other people this would just be someone claiming this, who could just as well be imposing you. However, if you sign your new key with your old key and make this signature visible/available to others this is at least some indication that this new key can actually be somewhat trusted. It does not yet explain that this is the replacement key for the old one, but we will get to this later.

Using Enigmail:

Using GPG:

Publish your new key

To allow other people easy access to your new key as part of the transition and whenever they need it later, you should publish it on a keyserver.

Using Enigmail:

Using GPG:

Write and publish transition statement

Now you need to let everyone know that you’re rolling your keys over. And in a way they can actually know it is you telling them this, and that you are actually in possession of this new key you created. Open up a text editor and write up a transition statement (here’s an example from Daniels’ earlier key transition – be sure to replace his GPG key IDs by your own old and new key IDs), then save it to a file, say, “openpgp-transition-2010.txt”.

Now sign this file with both your old and new keys:

gpg -u <Legacy key ID> -u <New key ID> --armor --clearsign openpgp-transition-2010.txt

You will be asked for the two keys’ passphrases, then GPG will create a file openpgp-transition-2010.txt.asc which is your signed transition document. You no longer need the original document “openpgp-transition-2010.txt” now and can delete it.
You should now make this document generally available by placing it on a public website. Since not everyone has access to a web server, a good enough option is to publish the document (just copy and paste from “openpgp-transition-2010.txt.asc”) on or a similar service (optionally using an anonymization service such as Tor). If you decide to use, once you have submitted it, click on the ‘RAW’ link on the top right of your transition statement. You should then end up with a page showing nothing but the raw transition statement exactly as it looks in the file you just created. Copy the URL of this web page from your web browsers’ location bar, it should look something like You will need this Internet address later.

Revoke old key

You should now revoke every of your old DSA keys. Revoking them ensures that other people having a copy of your public key will no longer be able to encrypt to it, and will realize that email signed by this key is no longer trusted. You will, however, still be able to read all email others have sent to you (and encrypted to your old key) during the past years.

Using Enigmail:

Using GPG:


Extra hint: Refresh your copy of peoples’ keys regularly

You should regularly update your local copy of keys from a key server. How to do this depends on your operating system.

Using (ana)cron on Linux

On Linux you would probably want to create a per user (i.e. not system-wide) cron job. To do so, you edit your users’ crontab:

crontab -e

An editor will spawn, now add this to the end of this file:

@daily /usr/bin/gpg --refresh-keys > /dev/null 2>&1

This will ensure that your GPG keys get updated from your default keyserver (as configured in ~/.gnupg/gpg.conf – I recommend using or a keyserver which supports the transport encrypted HKPS protocol) once a day.

If you prefer it to happen by a fixed time you could use this instead (or additionally):

0 1 * * * /usr/bin/gpg --refresh-keys > /dev/null 2>&1

This would run it every night at 01:00 AM. Note, however, that the latter cron job will not be executed if your computer is not running by this exact time. If you would like to run it at a different time, run man 5 crontab to read the manual for the crontab command which also explains the format of this file. Note also that the special ‘@daily’ format may not work on all Unix derivates (it depends on anacron).

You can optionally add a second line to ensure you start with up to date GPG keys whenever your computer boots up:

@reboot /usr/bin/gpg --refresh-keys > /dev/null 2>&1

Using scheduled tasks on Windows

On Windows, you would define ‘scheduled tasks’ to achieve the same thing. How to do this exactly is out of the scope of this document. You should be able to find several documentations on the Internet, though.

Related resources