wks: Allow reading of --install-key arguments from stdin.
[gnupg.git] / doc / debugging.texi
1 @c Copyright (C) 2004 Free Software Foundation, Inc.
2 @c This is part of the GnuPG manual.
3 @c For copying conditions, see the file gnupg.texi.
4
5 @node Debugging
6 @chapter How to solve problems
7
8 Everyone knows that software often does not do what it should do and thus
9 there is a need to track down problems.  We call this debugging in a
10 reminiscent to the moth jamming a relay in a Mark II box back in 1947.
11
12 Most of the problems a merely configuration and user problems but
13 nevertheless they are the most annoying ones and responsible for many
14 gray hairs.  We try to give some guidelines here on how to identify and
15 solve the problem at hand.
16
17
18 @menu
19 * Debugging Tools::       Description of some useful tools.
20 * Debugging Hints::       Various hints on debugging.
21 * Common Problems::       Commonly seen problems.
22 * Architecture Details::  How the whole thing works internally.
23 @end menu
24
25
26 @node Debugging Tools
27 @section Debugging Tools
28
29 The GnuPG distribution comes with a couple of tools, useful to help find
30 and solving problems.
31
32 @menu
33 * kbxutil::        Scrutinizing a keybox file.
34 @end menu
35
36 @node kbxutil
37 @subsection Scrutinizing a keybox file
38
39 A keybox is a file format used to store public keys along with meta
40 information and indices.  The commonly used one is the file
41 @file{pubring.kbx} in the @file{.gnupg} directory. It contains all
42 X.509 certificates as well as OpenPGP keys@footnote{Well, OpenPGP keys
43 are not implemented, @command{gpg} still used the keyring file
44 @file{pubring.gpg}.}.
45
46 @noindent
47 When called the standard way, e.g.:
48
49 @samp{kbxutil ~/.gnupg/pubring.kbx}
50
51 @noindent
52 it lists all records (called @acronym{blobs}) with there meta-information
53 in a human readable format.
54
55 @noindent
56 To see statistics on the keybox in question, run it using
57
58 @samp{kbxutil --stats ~/.gnupg/pubring.kbx}
59
60 @noindent
61 and you get an output like:
62
63 @example
64 Total number of blobs:       99
65                header:        1
66                 empty:        0
67               openpgp:        0
68                  x509:       98
69           non flagged:       81
70        secret flagged:        0
71     ephemeral flagged:       17
72 @end example
73
74 In this example you see that the keybox does not have any OpenPGP keys
75 but contains 98 X.509 certificates and a total of 17 keys or certificates
76 are flagged as ephemeral, meaning that they are only temporary stored
77 (cached) in the keybox and won't get listed using the usual commands
78 provided by @command{gpgsm} or @command{gpg}. 81 certificates are stored
79 in a standard way and directly available from @command{gpgsm}.
80
81 @noindent
82 To find duplicated certificates and keyblocks in a keybox file (this
83 should not occur but sometimes things go wrong), run it using
84
85 @samp{kbxutil --find-dups ~/.gnupg/pubring.kbx}
86
87
88 @node Debugging Hints
89 @section Various hints on debugging
90
91 @itemize @bullet
92
93 @item How to find the IP address of a keyserver
94
95 If a round robin URL of is used for a keyserver
96 (e.g. subkeys.gnupg.org); it is not easy to see what server is actually
97 used.  Using the keyserver debug option as in
98
99 @smallexample
100  gpg --keyserver-options debug=1 -v --refresh-key 1E42B367
101 @end smallexample
102
103 is thus often helpful.  Note that the actual output depends on the
104 backend and may change from release to release.
105
106 @item Logging on WindowsCE
107
108 For development, the best logging method on WindowsCE is the use of
109 remote debugging using a log file name of @file{tcp://<ip-addr>:<port>}.
110 The command @command{watchgnupg} may be used on the remote host to listen
111 on the given port (@pxref{option watchgnupg --tcp}).  For in the field
112 tests it is better to make use of the logging facility provided by the
113 @command{gpgcedev} driver (part of libassuan); this is enabled by using
114 a log file name of @file{GPG2:} (@pxref{option --log-file}).
115
116 @end itemize
117
118
119 @node Common Problems
120 @section Commonly Seen Problems
121
122
123 @itemize @bullet
124 @item Error code @samp{Not supported} from Dirmngr
125
126 Most likely the option @option{enable-ocsp} is active for gpgsm
127 but Dirmngr's OCSP feature has not been enabled using
128 @option{allow-ocsp} in @file{dirmngr.conf}.
129
130 @item The Curses based Pinentry does not work
131
132 The far most common reason for this is that the environment variable
133 @code{GPG_TTY} has not been set correctly.  Make sure that it has been
134 set to a real tty device and not just to @samp{/dev/tty};
135 i.e. @samp{GPG_TTY=tty} is plainly wrong; what you want is
136 @samp{GPG_TTY=`tty`} --- note the back ticks.  Also make sure that
137 this environment variable gets exported, that is you should follow up
138 the setting with an @samp{export GPG_TTY} (assuming a Bourne style
139 shell). Even for GUI based Pinentries; you should have set
140 @code{GPG_TTY}. See the section on installing the @command{gpg-agent}
141 on how to do it.
142
143
144 @item SSH hangs while a popping up pinentry was expected
145
146 SSH has no way to tell the gpg-agent what terminal or X display it is
147 running on.  So when remotely logging into a box where a gpg-agent with
148 SSH support is running, the pinentry will get popped up on whatever
149 display the gpg-agent has been started.  To solve this problem you may
150 issue the command
151
152 @smallexample
153 echo UPDATESTARTUPTTY | gpg-connect-agent
154 @end smallexample
155
156 and the next pinentry will pop up on your display or screen. However,
157 you need to kill the running pinentry first because only one pinentry
158 may be running at once.  If you plan to use ssh on a new display you
159 should issue the above command before invoking ssh or any other service
160 making use of ssh.
161
162
163 @item Exporting a secret key without a certificate
164
165 It may happen that you have created a certificate request using
166 @command{gpgsm} but not yet received and imported the certificate from
167 the CA.  However, you want to export the secret key to another machine
168 right now to import the certificate over there then.  You can do this
169 with a little trick but it requires that you know the approximate time
170 you created the signing request.  By running the command
171
172 @smallexample
173   ls -ltr ~/.gnupg/private-keys-v1.d
174 @end smallexample
175
176 you get a listing of all private keys under control of @command{gpg-agent}.
177 Pick the key which best matches the creation time and run the command
178
179 @cartouche
180 @smallexample
181   @value{LIBEXECDIR}/gpg-protect-tool --p12-export \
182      ~/.gnupg/private-keys-v1.d/@var{foo} >@var{foo}.p12
183 @end smallexample
184 @end cartouche
185
186 (Please adjust the path to @command{gpg-protect-tool} to the appropriate
187 location). @var{foo} is the name of the key file you picked (it should
188 have the suffix @file{.key}).  A Pinentry box will pop up and ask you
189 for the current passphrase of the key and a new passphrase to protect it
190 in the pkcs#12 file.
191
192 To import the created file on the machine you use this command:
193
194 @cartouche
195 @smallexample
196   @value{LIBEXECDIR}/gpg-protect-tool --p12-import --store  @var{foo}.p12
197 @end smallexample
198 @end cartouche
199
200 You will be asked for the pkcs#12 passphrase and a new passphrase to
201 protect the imported private key at its new location.
202
203 Note that there is no easy way to match existing certificates with
204 stored private keys because some private keys are used for Secure Shell
205 or other purposes and don't have a corresponding certificate.
206
207
208 @item A root certificate does not verify
209
210 A common problem is that the root certificate misses the required
211 basicConstraints attribute and thus @command{gpgsm} rejects this
212 certificate.  An error message indicating ``no value'' is a sign for
213 such a certificate.  You may use the @code{relax} flag in
214 @file{trustlist.txt} to accept the certificate anyway.  Note that the
215 fingerprint and this flag may only be added manually to
216 @file{trustlist.txt}.
217
218 @item Error message: ``digest algorithm N has not been enabled''
219
220 The signature is broken.  You may try the option
221 @option{--extra-digest-algo SHA256} to workaround the problem.  The
222 number N is the internal algorithm identifier; for example 8 refers to
223 SHA-256.
224
225
226 @item The Windows version does not work under Wine
227
228 When running the W32 version of @command{gpg} under Wine you may get
229 an error messages like:
230
231 @smallexample
232 gpg: fatal: WriteConsole failed: Access denied
233 @end smallexample
234
235 @noindent
236 The solution is to use the command @command{wineconsole}.
237
238 Some operations like @option{--generate-key} really want to talk to
239 the console directly
240 for increased security (for example to prevent the passphrase from
241 appearing on the screen).  So, you should use @command{wineconsole}
242 instead of @command{wine}, which will launch a windows console that
243 implements those additional features.
244
245
246 @item Why does GPG's --search-key list weird keys?
247
248 For performance reasons the keyservers do not check the keys the same
249 way @command{gpg} does.  It may happen that the listing of keys
250 available on the keyservers shows keys with wrong user IDs or with user
251 Ids from other keys.  If you try to import this key, the bad keys or bad
252 user ids won't get imported, though.  This is a bit unfortunate but we
253 can't do anything about it without actually downloading the keys.
254
255 @end itemize
256
257
258 @c ********************************************
259 @c ***  Architecture Details  *****************
260 @c ********************************************
261 @node Architecture Details
262 @section How the whole thing works internally
263
264
265 @menu
266 * Component interaction:: How the components work together.
267 * GnuPG-1 and GnuPG-2::   Relationship between GnuPG 1.4 and 2.x.
268 @end menu
269
270 @node Component interaction
271 @subsection How the components work together
272
273
274 @float Figure,fig:moduleoverview
275 @caption{GnuPG module overview}
276 @center @image{gnupg-module-overview, 150mm,,GnuPG modules}
277 @end float
278
279
280 @node GnuPG-1 and GnuPG-2
281 @subsection  Relationship between GnuPG 1.4 and 2.x
282
283 Here is a little picture showing how the different GnuPG versions make
284 use of a smartcard:
285
286 @float Figure,fig:cardarchitecture
287 @caption{GnuPG card architecture}
288 @center @image{gnupg-card-architecture, 150mm,, GnuPG card architecture}
289 @end float
290
291