How to solve problems
*********************

Everyone knows that software often does not do what it should do and thus there is a need to track down problems.  We call this debugging in a reminiscent to the moth jamming a relay in a Mark II box back in 1947.

Most of the problems a merely configuration and user problems but nevertheless they are the most annoying ones and responsible for many gray hairs.  We try to give some guidelines here on how to identify and solve the problem at hand.

Debugging Tools
===============

The GnuPG distribution comes with a couple of tools, useful to help find and solving problems.

Scrutinizing a keybox file
--------------------------

A keybox is a file format used to store public keys along with meta information and indices.  The commonly used one is the file pubring.kbx in the .gnupg directory.  It contains all X.509 certificates as well as OpenPGP keys.

When called the standard way, e.g.:

kbxutil ~/.gnupg/pubring.kbx

it lists all records (called blobs) with there meta-information in a human readable format.

To see statistics on the keybox in question, run it using

kbxutil --stats ~/.gnupg/pubring.kbx

and you get an output like:

     Total number of blobs:       99
                    header:        1
                     empty:        0
                   openpgp:        0
                      x509:       98
               non flagged:       81
            secret flagged:        0
         ephemeral flagged:       17

In this example you see that the keybox does not have any OpenPGP keys but contains 98 X.509 certificates and a total of 17 keys or certificates are flagged as ephemeral, meaning that they are only temporary stored (cached) in the keybox and won't get listed using the usual commands provided by gpgsm or gpg. 81 certificates are stored in a standard way and directly available from gpgsm.

To find duplicated certificates and keyblocks in a keybox file (this should not occur but sometimes things go wrong), run it using

kbxutil --find-dups ~/.gnupg/pubring.kbx

Various hints on debugging
==========================

  * How to find the IP address of a keyserver

     If a round robin URL of is used for a keyserver (e.g. subkeys.gnupg.org); it is not easy to see what server is actually used.  Using the keyserver debug option as in

           gpg --keyserver-options debug=1 -v --refresh-key 1E42B367

     is thus often helpful.  Note that the actual output depends on the backend and may change from release to release.

  * Logging on WindowsCE

     For development, the best logging method on WindowsCE is the use of remote debugging using a log file name of tcp://<ip-addr>:<port>. The command watchgnupg may be used on the remote host to listen on the given port (see option watchgnupg --tcp).  For in the field tests it is better to make use of the logging facility provided by the gpgcedev driver (part of libassuan); this is enabled by using a log file name of GPG2: (see option --log-file).

Commonly Seen Problems
======================

  * Error code Not supported from Dirmngr

     Most likely the option enable-ocsp is active for gpgsm but Dirmngr's OCSP feature has not been enabled using allow-ocsp in dirmngr.conf.

  * The Curses based Pinentry does not work

     The far most common reason for this is that the environment variable GPG_TTY has not been set correctly.  Make sure that it has been set to a real tty device and not just to /dev/tty; i.e. GPG_TTY=tty is plainly wrong; what you want is GPG_TTY=`tty` --- note the back ticks.  Also make sure that this environment variable gets exported, that is you should follow up the setting with an export GPG_TTY (assuming a Bourne style shell). Even for GUI based Pinentries; you should have set GPG_TTY. See the section on installing the gpg-agent on how to do it.

  * SSH hangs while a popping up pinentry was expected

     SSH has no way to tell the gpg-agent what terminal or X display it is running on.  So when remotely logging into a box where a gpg-agent with SSH support is running, the pinentry will get popped up on whatever display the gpg-agent has been started.  To solve this problem you may issue the command

          echo UPDATESTARTUPTTY | gpg-connect-agent

     and the next pinentry will pop up on your display or screen. However, you need to kill the running pinentry first because only one pinentry may be running at once.  If you plan to use ssh on a new display you should issue the above command before invoking ssh or any other service making use of ssh.

  * Exporting a secret key without a certificate

     It may happen that you have created a certificate request using gpgsm but not yet received and imported the certificate from the CA.  However, you want to export the secret key to another machine right now to import the certificate over there then.  You can do this with a little trick but it requires that you know the approximate time you created the signing request.  By running the command

            ls -ltr ~/.gnupg/private-keys-v1.d

     you get a listing of all private keys under control of gpg-agent. Pick the key which best matches the creation time and run the command

            LIBEXECDIR/gpg-protect-tool --p12-export \
               ~/.gnupg/private-keys-v1.d/FOO >FOO.p12

     (Please adjust the path to gpg-protect-tool to the appropriate location). FOO is the name of the key file you picked (it should have the suffix .key).  A Pinentry box will pop up and ask you for the current passphrase of the key and a new passphrase to protect it in the pkcs#12 file.

     To import the created file on the machine you use this command:

            LIBEXECDIR/gpg-protect-tool --p12-import --store  FOO.p12

     You will be asked for the pkcs#12 passphrase and a new passphrase to protect the imported private key at its new location.

     Note that there is no easy way to match existing certificates with stored private keys because some private keys are used for Secure Shell or other purposes and don't have a corresponding certificate.

  * A root certificate does not verify

     A common problem is that the root certificate misses the required basicConstraints attribute and thus gpgsm rejects this certificate.  An error message indicating ``no value'' is a sign for such a certificate.  You may use the relax flag in trustlist.txt to accept the certificate anyway.  Note that the fingerprint and this flag may only be added manually to trustlist.txt.

  * Error message: ``digest algorithm N has not been enabled''

     The signature is broken.  You may try the option --extra-digest-algo SHA256 to workaround the problem.  The number N is the internal algorithm identifier; for example 8 refers to SHA-256.

  * The Windows version does not work under Wine

     When running the W32 version of gpg under Wine you may get an error messages like:

          gpg: fatal: WriteConsole failed: Access denied

     The solution is to use the command wineconsole.

     Some operations like --generate-key really want to talk to the console directly for increased security (for example to prevent the passphrase from appearing on the screen).  So, you should use wineconsole instead of wine, which will launch a windows console that implements those additional features.

  * Why does GPG's --search-key list weird keys?

     For performance reasons the keyservers do not check the keys the same way gpg does.  It may happen that the listing of keys available on the keyservers shows keys with wrong user IDs or with user Ids from other keys.  If you try to import this key, the bad keys or bad user ids won't get imported, though.  This is a bit unfortunate but we can't do anything about it without actually downloading the keys.

How the whole thing works internally
====================================

How the components work together
--------------------------------

Figure: GnuPG module overview
GnuPG modules

Relationship between GnuPG 1.4 and 2.x
--------------------------------------

Here is a little picture showing how the different GnuPG versions make use of a smartcard:

Figure: GnuPG card architecture
GnuPG card architecture