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