GnuPG 2.x requires an "agent" to handle passphrases. By default this is done by gpg-agent, but there are other tools implementing a subset of its functionality. These instructions are for gpg-agent only. If you use an agent like gnome-keyring, seahorse-agent or the KDE Wallet Manager, then these instructions don't apply.

Most common Problem

Symptoms

The most common issue is that gpg-agent (a part of GnuPG) cannot launch pinentry (the tool used to query your passphrase). Enigmail would display messages like:

when reading messages:Error - no matching private/secret key found to decrypt message; click on 'Details' button for more information

If the message says something like "no pinentry", "problem with the agent", "Invalid IPC response", "problem with gpg-agent" then there is something wrong with your gpg-agent and/or pinentry setup. Follow the guide below.

How to Fix it

Execute the following script from a terminal to find out if a graphical version of pinentry is used:

pinentry <<EOT
SETDESC Hello World
CONFIRM
EOT

You should get a graphical window with a confirmation message "Hello World". If a "window" is opened within your terminal window then pinentry is text-based, which does not work with Enigmail. To fix this, ensure that a graphical version of pinentry is installed. On Linux/Unix systems, these would typically be pinentry-qt/pinentry-qt4 or pinentry-gtk/pinentry-gtk2, and on Mac OS X pinentry-mac. Rename the existing pinentry file to "pinentry-text" or similar, and create a symlink from pinentry-qt, pinentry-qt4, pinentry-gtk, pinentry-gtk2 or pinentry-mac to pinentry. Then restart your PC.

If the above does not help, check the contents of $HOME/.gnupg/gpg-agent.conf. Make sure that there is a configuration entry pinentry-program containing the full path to a graphical version of pinentry as above. E.g.:

pinentry-program /usr/local/bin/pinentry-gtk

Then save the file and restart your PC.

If you still can't access your key, then execute the following script from a terminal:

gpg-connect-agent <<EOT
GETINFO version
EOT

The output should be something like the text below, where 2.0.26 represents the agent version number. The version number should match your gpg version number:

D 2.0.26
OK

If you get an error message like "ERR 280 not implemented" then you don't use gpg-agent, but one of the alternatives like gnome-keyring. We recommend you switch to gpg-agent by disabling your current agent by disabling the invalid agent. See e.g. the GnuPG wiki for how to disable gnome-keyring or how to disable KDE wallet. Then restart you PC and check if the script now produces a correct result.

If the previous step was not successful, and you are using an Ubuntu or similar Linux distribution (e.g. Linux Mint), then you should add the following line to your $HOME/.gnupg/gpg.conf file:

use-agent

Then restart your PC and repeat the test from step 4.

If steps 4/5 are successful, then execute the following script from a terminal:

gpg-connect-agent <<EOT
GET_CONFIRMATION Hello
EOT

Pinentry should now open as a graphical window (just like above), with the difference to the step above that this instance of pinentry was launched from gpg-agent. If this is successful, then GnuPG 2 should work correctly in Enigmail.

If gpg-agent still cannot launch pinentry from Enigmail, then you need to start debugging gpg-agent. Execute the following commands from a terminal:

This will start gpg-agent from the command line, open a new shell and print the debug output to that shell. If the command succeeded, you will see somehting like:gpg-agent[76979]: gpg-agent 2.0.26 started Leave the terminal window untouched, start Thunderbird and try to use Enigmail. As you'll try to access gpg-agent, you will see the output in your terminal window. If gpg-agent cannot start pinentry successfully, you will see something like this:

Press Ctrl+D in the terminal to end the debugging session. The bold line should tell you the reason for the error (in the example above, pinentry cannot be found). Try to fix the error and repeat the test.