diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/debugging.texi | 287 |
1 files changed, 287 insertions, 0 deletions
diff --git a/doc/debugging.texi b/doc/debugging.texi new file mode 100644 index 0000000..14056d6 --- /dev/null +++ b/doc/debugging.texi @@ -0,0 +1,287 @@ +@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 |