wks: Let the client only export the requested UID.
[gnupg.git] / doc / debugging.texi
index 6c696ab..debdd40 100644 (file)
@@ -9,14 +9,15 @@ 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.
 
 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 probelsm a merely configuration and user problems but
-nevertheless there are the most annoying ones and reposnible for may
+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
 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 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
 * Common Problems::       Commonly seen problems.
 * Architecture Details::  How the whole thing works internally.
 @end menu
@@ -35,7 +36,7 @@ and solving problems.
 @node kbxutil
 @subsection Scrutinizing a keybox file
 
 @node kbxutil
 @subsection Scrutinizing a keybox file
 
-A keybox is a file fomat used to store public keys along with meta
+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
 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
@@ -71,14 +72,48 @@ Total number of blobs:       99
 @end example
 
 In this example you see that the keybox does not have any OpenPGP keys
 @end example
 
 In this example you see that the keybox does not have any OpenPGP keys
-but contains 98 X.509 cerificates and a total of 17 keys or certificates
-are flagges as ephemeral, meaning that they are only temporary stored
+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
 (cached) in the keybox and won't get listed using the usual commands
-provided by @command{gpgsm} or @command{gpg}. 81 certifcates are stored
+provided by @command{gpgsm} or @command{gpg}. 81 certificates are stored
 in a standard way and directly available from @command{gpgsm}.
 
 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
 
 
 @node Common Problems
@@ -111,7 +146,7 @@ on how to do it.
 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
 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 t he gpg-agent has been started.  To solve this problem you may
+display the gpg-agent has been started.  To solve this problem you may
 issue the command
 
 @smallexample
 issue the command
 
 @smallexample
@@ -125,6 +160,97 @@ should issue the above command before invoking ssh or any other service
 making use of ssh.
 
 
 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
+
+@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 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
 
 
 @end itemize
 
 
@@ -136,19 +262,30 @@ making use of ssh.
 
 
 @menu
 
 
 @menu
-* gpg 1.4 vs. 1.9::   Relationship between the two branches.
+* Component interaction:: How the components work together.
+* GnuPG-1 and GnuPG-2::   Relationship between GnuPG 1.4 and 2.x.
 @end menu
 
 @end menu
 
-@node gpg 1.4 vs. 1.9
-@subsection  Relationship between the two branches.
 
 
-Here is a little picture showing how the components work together:
+@node Component interaction
+@subsection How the components work together.
 
 
-@image{gnupg-card-architecture, 10cm}
 
 
-@noindent
-Lets try to explain it:
+@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:
 
 
-TO BE DONE.
+@float Figure,fig:cardarchitecture
+@caption{GnuPG card architecture}
+@center @image{gnupg-card-architecture, 150mm,, GnuPG card architecture}
+@end float