gnupg/doc/debugging.texi

@c Copyright (C) 2004 Free Software Foundation, Inc.
@c This is part of the GnuPG manual.
@c For copying conditions, see the file gnupg.texi.

@node Debugging
@chapter 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.


@menu
* Debugging Tools::       Description of some useful tools.
* Debugging Hints::       Various hints on debugging.
* Common Problems::       Commonly seen problems.
* Architecture Details::  How the whole thing works internally.
@end menu


@node Debugging Tools
@section Debugging Tools

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

@menu
* kbxutil::        Scrutinizing a keybox file.
@end menu

@node kbxutil
@subsection 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
@file{pubring.kbx} in the @file{.gnupg} directory. It contains all
X.509 certificates as well as OpenPGP keys.

@noindent
When called the standard way, e.g.:

@samp{kbxutil ~/.gnupg/pubring.kbx}

@noindent
it lists all records (called @acronym{blobs}) with there meta-information
in a human readable format.

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

@samp{kbxutil --stats ~/.gnupg/pubring.kbx}

@noindent
and you get an output like:

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

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 @command{gpgsm} or @command{gpg}. 81 certificates are stored
in a standard way and directly available from @command{gpgsm}.

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

@samp{kbxutil --find-dups ~/.gnupg/pubring.kbx}


@node Debugging Hints
@section Various hints on debugging

@itemize @bullet

@item 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

@smallexample
 gpg --keyserver-options debug=1 -v --refresh-key 1E42B367
@end smallexample

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

@item Logging on WindowsCE

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

@end itemize


@node Common Problems
@section Commonly Seen Problems


@itemize @bullet
@item Error code @samp{Not supported} from Dirmngr

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

@item The Curses based Pinentry does not work

The far most common reason for this is that the environment variable
@code{GPG_TTY} has not been set correctly.  Make sure that it has been
set to a real tty device and not just to @samp{/dev/tty};
i.e. @samp{GPG_TTY=tty} is plainly wrong; what you want is
@samp{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 @samp{export GPG_TTY} (assuming a Bourne style
shell). Even for GUI based Pinentries; you should have set
@code{GPG_TTY}. See the section on installing the @command{gpg-agent}
on how to do it.


@item 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

@smallexample
echo UPDATESTARTUPTTY | gpg-connect-agent
@end smallexample

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.


@item Exporting a secret key without a certificate

It may happen that you have created a certificate request using
@command{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

@smallexample
  ls -ltr ~/.gnupg/private-keys-v1.d
@end smallexample

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

@cartouche
@smallexample
  @value{LIBEXECDIR}/gpg-protect-tool --p12-export \
     ~/.gnupg/private-keys-v1.d/@var{foo} >@var{foo}.p12
@end smallexample
@end cartouche

(Please adjust the path to @command{gpg-protect-tool} to the appropriate
location). @var{foo} is the name of the key file you picked (it should
have the suffix @file{.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:

@cartouche
@smallexample
  @value{LIBEXECDIR}/gpg-protect-tool --p12-import --store  @var{foo}.p12
@end smallexample
@end cartouche

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.


@item A root certificate does not verify

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

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

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


@item The Windows version does not work under Wine

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

@smallexample
gpg: fatal: WriteConsole failed: Access denied
@end smallexample

@noindent
The solution is to use the command @command{wineconsole}.

Some operations like @option{--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 @command{wineconsole}
instead of @command{wine}, which will launch a windows console that
implements those additional features.


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

For performance reasons the keyservers do not check the keys the same
way @command{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.

@end itemize


@c ********************************************
@c ***  Architecture Details  *****************
@c ********************************************
@node Architecture Details
@section How the whole thing works internally


@menu
* Component interaction:: How the components work together.
* GnuPG-1 and GnuPG-2::   Relationship between GnuPG 1.4 and 2.x.
@end menu

@node Component interaction
@subsection How the components work together


@float Figure,fig:moduleoverview
@caption{GnuPG module overview}
@center @image{gnupg-module-overview, 150mm,,GnuPG modules}
@end float


@node GnuPG-1 and GnuPG-2
@subsection  Relationship between GnuPG 1.4 and 2.x

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

@float Figure,fig:cardarchitecture
@caption{GnuPG card architecture}
@center @image{gnupg-card-architecture, 150mm,, GnuPG card architecture}
@end float