mirror of
git://git.gnupg.org/gnupg.git
synced 2024-09-06 12:46:22 +02:00
278 lines
9.2 KiB
Plaintext
278 lines
9.2 KiB
Plaintext
@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 there 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@footnote{Well, OpenPGP keys
|
|
are not implemented, @command{gpg} still used the keyring file
|
|
@file{pubring.gpg}} .
|
|
|
|
@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.
|
|
|
|
@ifset gpgtwoone
|
|
@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 ifset
|
|
|
|
@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 devce 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
|
|
|
|
I 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
|
|
|
|
@smallexample
|
|
/usr/local/libexec/gpg-protect-tool --p12-export ~/.gnupg/private-keys-v1.d/@var{foo} >@var{foo}.p12
|
|
@end smallexample
|
|
|
|
(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:
|
|
|
|
@smallexample
|
|
/usr/local/libexec/gpg-protect-tool --p12-import --store @var{foo}.p12
|
|
@end smallexample
|
|
|
|
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 gen-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
|
|
* GnuPG-1 and GnuPG-2:: Relationship between the two branches.
|
|
@end menu
|
|
|
|
@node GnuPG-1 and GnuPG-2
|
|
@subsection Relationship between the two branches.
|
|
|
|
Here is a little picture showing how the components work together:
|
|
|
|
@image{gnupg-card-architecture, 10cm}
|
|
|
|
@noindent
|
|
Lets try to explain it:
|
|
|
|
TO BE DONE.
|
|
|
|
|