Change capitalization of TOR to Tor.
[gnupg.git] / doc / debugging.texi
index 242d601..7965dbc 100644 (file)
@@ -10,13 +10,14 @@ 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 reponsible for many
+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 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
@@ -35,7 +36,7 @@ and solving problems.
 @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
@@ -71,10 +72,10 @@ Total number of blobs:       99
 @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
-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}.
 
 @noindent
@@ -84,8 +85,35 @@ 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
@@ -118,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
-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
@@ -147,22 +175,27 @@ you created the signing request.  By running the command
 
 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
-  /usr/local/libexec/gpg-protect-tool --p12-export ~/.gnupg/private-keys-v1.d/@var{foo} >@var{foo}.p12
+  @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 approriate
+(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:  
+To import the created file on the machine you use this command:
 
+@cartouche
 @smallexample
-  /usr/local/libexec/gpg-protect-tool --p12-import --store  @var{foo}.p12
+  @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.
@@ -175,7 +208,7 @@ 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
-basicConstrains attribute and thus @command{gpgsm} rejects this
+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
@@ -186,9 +219,38 @@ fingerprint and this flag may only be added manually to
 
 The signature is broken.  You may try the option
 @option{--extra-digest-algo SHA256} to workaround the problem.  The
-number N is the internal algorighm indentifier; for example 8 refers to
+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