Adding upstream version 2.2.27.upstream/2.2.27upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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