Give hints on files to backup.
[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 there are the most annoying ones and reponsible 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 fomat 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 cerificates and a total of 17 keys or certificates
76 are flagges 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 certifcates 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
107 @end itemize
108
109
110 @node Common Problems
111 @section Commonly Seen Problems
112
113
114 @itemize @bullet
115 @item Error code @samp{Not supported} from Dirmngr
116
117 Most likely the option @option{enable-ocsp} is active for gpgsm
118 but Dirmngr's OCSP feature has not been enabled using
119 @option{allow-ocsp} in @file{dirmngr.conf}.
120
121 @item The Curses based Pinentry does not work
122
123 The far most common reason for this is that the environment variable
124 @code{GPG_TTY} has not been set correctly.  Make sure that it has been
125 set to a real tty devce and not just to @samp{/dev/tty};
126 i.e. @samp{GPG_TTY=tty} is plainly wrong; what you want is
127 @samp{GPG_TTY=`tty`} --- note the back ticks.  Also make sure that
128 this environment variable gets exported, that is you should follow up
129 the setting with an @samp{export GPG_TTY} (assuming a Bourne style
130 shell). Even for GUI based Pinentries; you should have set
131 @code{GPG_TTY}. See the section on installing the @command{gpg-agent}
132 on how to do it.
133
134
135 @item SSH hangs while a popping up pinentry was expected
136
137 SSH has no way to tell the gpg-agent what terminal or X display it is
138 running on.  So when remotely logging into a box where a gpg-agent with
139 SSH support is running, the pinentry will get popped up on whatever
140 display t he gpg-agent has been started.  To solve this problem you may
141 issue the command
142
143 @smallexample
144 echo UPDATESTARTUPTTY | gpg-connect-agent
145 @end smallexample
146
147 and the next pinentry will pop up on your display or screen. However,
148 you need to kill the running pinentry first because only one pinentry
149 may be running at once.  If you plan to use ssh on a new display you
150 should issue the above command before invoking ssh or any other service
151 making use of ssh.
152
153
154 @item Exporting a secret key without a certificate
155
156 I may happen that you have created a certificate request using
157 @command{gpgsm} but not yet received and imported the certificate from
158 the CA.  However, you want to export the secret key to another machine
159 right now to import the certificate over there then.  You can do this
160 with a little trick but it requires that you know the approximate time
161 you created the signing request.  By running the command
162
163 @smallexample
164   ls -ltr ~/.gnupg/private-keys-v1.d
165 @end smallexample
166
167 you get a listing of all private keys under control of @command{gpg-agent}.
168 Pick the key which best matches the creation time and run the command
169  
170 @smallexample
171   /usr/local/libexec/gpg-protect-tool --p12-export ~/.gnupg/private-keys-v1.d/@var{foo} >@var{foo}.p12
172 @end smallexample
173
174 (Please adjust the path to @command{gpg-protect-tool} to the approriate
175 location). @var{foo} is the name of the key file you picked (it should
176 have the suffix @file{.key}).  A Pinentry box will pop up and ask you
177 for the current passphrase of the key and a new passphrase to protect it
178 in the pkcs#12 file.
179
180 To import the created file on the machine you use this command:  
181
182 @smallexample
183   /usr/local/libexec/gpg-protect-tool --p12-import --store  @var{foo}.p12
184 @end smallexample
185
186 You will be asked for the pkcs#12 passphrase and a new passphrase to
187 protect the imported private key at its new location.
188
189 Note that there is no easy way to match existing certificates with
190 stored private keys because some private keys are used for Secure Shell
191 or other purposes and don't have a corresponding certificate.
192
193
194 @item A root certificate does not verify
195
196 A common problem is that the root certificate misses the required
197 basicConstrains attribute and thus @command{gpgsm} rejects this
198 certificate.  An error message indicating ``no value'' is a sign for
199 such a certificate.  You may use the @code{relax} flag in
200 @file{trustlist.txt} to accept the certificate anyway.  Note that the
201 fingerprint and this flag may only be added manually to
202 @file{trustlist.txt}.
203
204 @item Error message: ``digest algorithm N has not been enabled''
205
206 The signature is broken.  You may try the option
207 @option{--extra-digest-algo SHA256} to workaround the problem.  The
208 number N is the internal algorighm indentifier; for example 8 refers to
209 SHA-256.
210
211
212 @item The Windows version does not work under Wine
213
214 When running the W32 version of @command{gpg} under Wine you may get
215 an error messages like:
216
217 @smallexample
218 gpg: fatal: WriteConsole failed: Access denied
219 @end smallexample
220
221 @noindent
222 The solution is to use the command @command{wineconsole}. 
223
224 Some operations like gen-key really want to talk to the console directly
225 for increased security (for example to prevent the passphrase from
226 appearing on the screen).  So, you should use @command{wineconsole}
227 instead of @command{wine}, which will launch a windows console that
228 implements those additional features.
229
230
231 @item Why does GPG's --search-key list weird keys?
232
233 For performance reasons the keyservers do not check the keys the same
234 way @command{gpg} does.  It may happen that the listing of keys
235 available on the keyservers shows keys with wrong user IDs or with user
236 Ids from other keys.  If you try to import this key, the bad keys or bad
237 user ids won't get imported, though.  This is a bit unfortunate but we
238 can't do anything about it without actually downloading the keys.
239
240 @end itemize
241
242
243 @c ********************************************
244 @c ***  Architecture Details  *****************
245 @c ********************************************
246 @node Architecture Details
247 @section How the whole thing works internally.
248
249
250 @menu
251 * GnuPG-1 and GnuPG-2::   Relationship between the two branches.
252 @end menu
253
254 @node GnuPG-1 and GnuPG-2
255 @subsection  Relationship between the two branches.
256
257 Here is a little picture showing how the components work together:
258
259 @image{gnupg-card-architecture, 10cm}
260
261 @noindent
262 Lets try to explain it:
263
264 TO BE DONE.
265
266