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.
6 @chapter How to solve problems
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.
12 Most of the problems a merely configuration and user problems but
13 nevertheless there 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.
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.
27 @section Debugging Tools
29 The GnuPG distribution comes with a couple of tools, useful to help find
33 * kbxutil:: Scrutinizing a keybox file.
37 @subsection Scrutinizing a keybox file
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
47 When called the standard way, e.g.:
49 @samp{kbxutil ~/.gnupg/pubring.kbx}
52 it lists all records (called @acronym{blobs}) with there meta-information
53 in a human readable format.
56 To see statistics on the keybox in question, run it using
58 @samp{kbxutil --stats ~/.gnupg/pubring.kbx}
61 and you get an output like:
64 Total number of blobs: 99
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}.
82 To find duplicated certificates and keyblocks in a keybox file (this
83 should not occur but sometimes things go wrong), run it using
85 @samp{kbxutil --find-dups ~/.gnupg/pubring.kbx}
89 @section Various hints on debugging.
93 @item How to find the IP address of a keyserver
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
100 gpg --keyserver-options debug=1 -v --refresh-key 1E42B367
103 is thus often helpful. Note that the actual output depends on the
104 backend and may change from release to release.
107 @item Logging on WindowsCE
109 For development, the best logging method on WindowsCE is the use of
110 remote debugging using a log file name of @file{tcp://<ip-addr>:<port>}.
111 The command @command{watchgnupg} may be used on the remote host to listen
112 on the given port. (@pxref{option watchgnupg --tcp}). For in the field
113 tests it is better to make use of the logging facility provided by the
114 @command{gpgcedev} driver (part of libassuan); this is enabled by using
115 a log file name of @file{GPG2:}. (@pxref{option --log-file}).
121 @node Common Problems
122 @section Commonly Seen Problems
126 @item Error code @samp{Not supported} from Dirmngr
128 Most likely the option @option{enable-ocsp} is active for gpgsm
129 but Dirmngr's OCSP feature has not been enabled using
130 @option{allow-ocsp} in @file{dirmngr.conf}.
132 @item The Curses based Pinentry does not work
134 The far most common reason for this is that the environment variable
135 @code{GPG_TTY} has not been set correctly. Make sure that it has been
136 set to a real tty devce and not just to @samp{/dev/tty};
137 i.e. @samp{GPG_TTY=tty} is plainly wrong; what you want is
138 @samp{GPG_TTY=`tty`} --- note the back ticks. Also make sure that
139 this environment variable gets exported, that is you should follow up
140 the setting with an @samp{export GPG_TTY} (assuming a Bourne style
141 shell). Even for GUI based Pinentries; you should have set
142 @code{GPG_TTY}. See the section on installing the @command{gpg-agent}
146 @item SSH hangs while a popping up pinentry was expected
148 SSH has no way to tell the gpg-agent what terminal or X display it is
149 running on. So when remotely logging into a box where a gpg-agent with
150 SSH support is running, the pinentry will get popped up on whatever
151 display the gpg-agent has been started. To solve this problem you may
155 echo UPDATESTARTUPTTY | gpg-connect-agent
158 and the next pinentry will pop up on your display or screen. However,
159 you need to kill the running pinentry first because only one pinentry
160 may be running at once. If you plan to use ssh on a new display you
161 should issue the above command before invoking ssh or any other service
165 @item Exporting a secret key without a certificate
167 I may happen that you have created a certificate request using
168 @command{gpgsm} but not yet received and imported the certificate from
169 the CA. However, you want to export the secret key to another machine
170 right now to import the certificate over there then. You can do this
171 with a little trick but it requires that you know the approximate time
172 you created the signing request. By running the command
175 ls -ltr ~/.gnupg/private-keys-v1.d
178 you get a listing of all private keys under control of @command{gpg-agent}.
179 Pick the key which best matches the creation time and run the command
183 /usr/local/libexec/gpg-protect-tool --p12-export \
184 ~/.gnupg/private-keys-v1.d/@var{foo} >@var{foo}.p12
188 (Please adjust the path to @command{gpg-protect-tool} to the appropriate
189 location). @var{foo} is the name of the key file you picked (it should
190 have the suffix @file{.key}). A Pinentry box will pop up and ask you
191 for the current passphrase of the key and a new passphrase to protect it
194 To import the created file on the machine you use this command:
198 /usr/local/libexec/gpg-protect-tool --p12-import --store @var{foo}.p12
202 You will be asked for the pkcs#12 passphrase and a new passphrase to
203 protect the imported private key at its new location.
205 Note that there is no easy way to match existing certificates with
206 stored private keys because some private keys are used for Secure Shell
207 or other purposes and don't have a corresponding certificate.
210 @item A root certificate does not verify
212 A common problem is that the root certificate misses the required
213 basicConstraints attribute and thus @command{gpgsm} rejects this
214 certificate. An error message indicating ``no value'' is a sign for
215 such a certificate. You may use the @code{relax} flag in
216 @file{trustlist.txt} to accept the certificate anyway. Note that the
217 fingerprint and this flag may only be added manually to
218 @file{trustlist.txt}.
220 @item Error message: ``digest algorithm N has not been enabled''
222 The signature is broken. You may try the option
223 @option{--extra-digest-algo SHA256} to workaround the problem. The
224 number N is the internal algorithm identifier; for example 8 refers to
228 @item The Windows version does not work under Wine
230 When running the W32 version of @command{gpg} under Wine you may get
231 an error messages like:
234 gpg: fatal: WriteConsole failed: Access denied
238 The solution is to use the command @command{wineconsole}.
240 Some operations like gen-key really want to talk to the console directly
241 for increased security (for example to prevent the passphrase from
242 appearing on the screen). So, you should use @command{wineconsole}
243 instead of @command{wine}, which will launch a windows console that
244 implements those additional features.
247 @item Why does GPG's --search-key list weird keys?
249 For performance reasons the keyservers do not check the keys the same
250 way @command{gpg} does. It may happen that the listing of keys
251 available on the keyservers shows keys with wrong user IDs or with user
252 Ids from other keys. If you try to import this key, the bad keys or bad
253 user ids won't get imported, though. This is a bit unfortunate but we
254 can't do anything about it without actually downloading the keys.
259 @c ********************************************
260 @c *** Architecture Details *****************
261 @c ********************************************
262 @node Architecture Details
263 @section How the whole thing works internally.
267 * GnuPG-1 and GnuPG-2:: Relationship between the two branches.
270 @node GnuPG-1 and GnuPG-2
271 @subsection Relationship between the two branches.
273 Here is a little picture showing how the components work together:
275 @image{gnupg-card-architecture, 10cm}
278 Lets try to explain it: