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.
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
when sending messages:
- Send operation aborted. Error - encryption command failed
- Send operation aborted. Key 0x....... not found or not valid. The (sub-)key might have expired
How to Analyze
How to Fix it
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.:
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.
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:
killall gpg-agent gpg-agent --debug-level expert --use-standard-socket --daemon /bin/sh
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: 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:
gpg-agent: starting a new PIN Entry gpg-agent: chan_19 <- ERR 67109133 can't exec `/usr/bin/pinentry': No such file or directory gpg-agent: chan_19 -> BYE gpg-agent: can't connect to the PIN entry module: IPC connect call failed gpg-agent: command get_passphrase failed: No pinentry
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.
If you have to enter your passphrase every time you select an encrypted mail, or try to write a signed mail, then you need to adjust the configuration of gpg-agent.
If you are on Linux, Mac OS X, or any other Unix-like system:
Add the following line to $HOME/.gnupg/gpg-agent.conf:
Then reboot your computer.
If you are on Windows:
Add the following line to C:\Users\<your login>\AppData\Roaming\gnupg:
Then reboot your computer.
gpg-agent is a mandatory component of GnuPG 2.x. That's a design decision taken by the GnuPG developers, which cannot be influenced by Enigmail. It is not possible to use GnuPG 2.x without gpg-agent.