gpg: New card function agent_scd_keypairinfo.
[gnupg.git] / doc / debugging.texi
index c83ab1e..42a1a15 100644 (file)
@@ -10,7 +10,7 @@ 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
+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.
 
@@ -41,7 +41,7 @@ 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}.
+@file{pubring.gpg}.}.
 
 @noindent
 When called the standard way, e.g.:
@@ -86,7 +86,7 @@ should not occur but sometimes things go wrong), run it using
 
 
 @node Debugging Hints
-@section Various hints on debugging.
+@section Various hints on debugging
 
 @itemize @bullet
 
@@ -103,17 +103,15 @@ used.  Using the keyserver debug option as in
 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
+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
+a log file name of @file{GPG2:} (@pxref{option --log-file}).
 
 @end itemize
 
@@ -133,7 +131,7 @@ but Dirmngr's OCSP feature has not been enabled using
 
 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};
+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
@@ -164,7 +162,7 @@ making use of ssh.
 
 @item Exporting a secret key without a certificate
 
-I may happen that you have created a certificate request using
+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
@@ -177,10 +175,13 @@ 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 appropriate
 location). @var{foo} is the name of the key file you picked (it should
@@ -188,11 +189,13 @@ 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.
@@ -230,9 +233,10 @@ gpg: fatal: WriteConsole failed: Access denied
 @end smallexample
 
 @noindent
-The solution is to use the command @command{wineconsole}. 
+The solution is to use the command @command{wineconsole}.
 
-Some operations like gen-key really want to talk to the console directly
+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
@@ -255,23 +259,33 @@ can't do anything about it without actually downloading the keys.
 @c ***  Architecture Details  *****************
 @c ********************************************
 @node Architecture Details
-@section How the whole thing works internally.
+@section How the whole thing works internally
 
 
 @menu
-* GnuPG-1 and GnuPG-2::   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
 
-@node GnuPG-1 and GnuPG-2
-@subsection  Relationship between the two branches.
+@node Component interaction
+@subsection How the components work together
 
-Here is a little picture showing how the components work together:
 
-@image{gnupg-card-architecture, 10cm}
+@float Figure,fig:moduleoverview
+@caption{GnuPG module overview}
+@center @image{gnupg-module-overview, 150mm,,GnuPG modules}
+@end float
 
-@noindent
-Lets try to explain it:
 
-TO BE DONE.
+@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