Make gpgconf --list-components also print the name of the executable program.
[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 * Common Problems::       Commonly seen problems.
21 * Architecture Details::  How the whole thing works internally.
22 @end menu
23
24
25 @node Debugging Tools
26 @section Debugging Tools
27
28 The GnuPG distribution comes with a couple of tools, useful to help find
29 and solving problems.
30
31 @menu
32 * kbxutil::        Scrutinizing a keybox file.
33 @end menu
34
35 @node kbxutil
36 @subsection Scrutinizing a keybox file
37
38 A keybox is a file fomat used to store public keys along with meta
39 information and indices.  The commonly used one is the file
40 @file{pubring.kbx} in the @file{.gnupg} directory. It contains all
41 X.509 certificates as well as OpenPGP keys@footnote{Well, OpenPGP keys
42 are not implemented, @command{gpg} still used the keyring file
43 @file{pubring.gpg}} .
44
45 @noindent
46 When called the standard way, e.g.:
47
48 @samp{kbxutil ~/.gnupg/pubring.kbx}
49
50 @noindent
51 it lists all records (called @acronym{blobs}) with there meta-information
52 in a human readable format.
53
54 @noindent
55 To see statistics on the keybox in question, run it using
56
57 @samp{kbxutil --stats ~/.gnupg/pubring.kbx}
58
59 @noindent
60 and you get an output like:
61
62 @example
63 Total number of blobs:       99
64                header:        1
65                 empty:        0
66               openpgp:        0
67                  x509:       98
68           non flagged:       81
69        secret flagged:        0
70     ephemeral flagged:       17
71 @end example
72
73 In this example you see that the keybox does not have any OpenPGP keys
74 but contains 98 X.509 cerificates and a total of 17 keys or certificates
75 are flagges as ephemeral, meaning that they are only temporary stored
76 (cached) in the keybox and won't get listed using the usual commands
77 provided by @command{gpgsm} or @command{gpg}. 81 certifcates are stored
78 in a standard way and directly available from @command{gpgsm}.
79
80 @noindent
81 To find duplicated certificates and keyblocks in a keybox file (this
82 should not occur but sometimes things go wrong), run it using
83
84 @samp{kbxutil --find-dups ~/.gnupg/pubring.kbx}
85
86
87
88
89
90
91 @node Common Problems
92 @section Commonly Seen Problems
93
94
95 @itemize @bullet
96 @item Error code @samp{Not supported} from Dirmngr
97
98 Most likely the option @option{enable-ocsp} is active for gpgsm
99 but Dirmngr's OCSP feature has not been enabled using
100 @option{allow-ocsp} in @file{dirmngr.conf}.
101
102 @item The Curses based Pinentry does not work
103
104 The far most common reason for this is that the environment variable
105 @code{GPG_TTY} has not been set correctly.  Make sure that it has been
106 set to a real tty devce and not just to @samp{/dev/tty};
107 i.e. @samp{GPG_TTY=tty} is plainly wrong; what you want is
108 @samp{GPG_TTY=`tty`} --- note the back ticks.  Also make sure that
109 this environment variable gets exported, that is you should follow up
110 the setting with an @samp{export GPG_TTY} (assuming a Bourne style
111 shell). Even for GUI based Pinentries; you should have set
112 @code{GPG_TTY}. See the section on installing the @command{gpg-agent}
113 on how to do it.
114
115
116 @item SSH hangs while a popping up pinentry was expected
117
118 SSH has no way to tell the gpg-agent what terminal or X display it is
119 running on.  So when remotely logging into a box where a gpg-agent with
120 SSH support is running, the pinentry will get popped up on whatever
121 display t he gpg-agent has been started.  To solve this problem you may
122 issue the command
123
124 @smallexample
125 echo UPDATESTARTUPTTY | gpg-connect-agent
126 @end smallexample
127
128 and the next pinentry will pop up on your display or screen. However,
129 you need to kill the running pinentry first because only one pinentry
130 may be running at once.  If you plan to use ssh on a new display you
131 should issue the above command before invoking ssh or any other service
132 making use of ssh.
133
134
135 @item Exporting a secret key without a certificate
136
137 I may happen that you have created a certificate request using
138 @command{gpgsm} but not yet received and imported the certificate from
139 the CA.  However, you want to export the secret key to another machine
140 right now to import the certificate over there then.  You can do this
141 with a little trick but it requires that you know the approximate time
142 you created the signing request.  By running the command
143
144 @smallexample
145   ls -ltr ~/.gnupg/private-keys-v1.d
146 @end smallexample
147
148 you get a listing of all private keys under control of @command{gpg-agent}.
149 Pick the key which best matches the creation time and run the command
150  
151 @smallexample
152   /usr/local/libexec/gpg-protect-tool --p12-export ~/.gnupg/private-keys-v1.d/@var{foo} >@var{foo}.p12
153 @end smallexample
154
155 (Please adjust the path to @command{gpg-protect-tool} to the approriate
156 location). @var{foo} is the name of the key file you picked (it should
157 have the suffix @file{.key}).  A Pinentry box will pop up and ask you
158 for the current passphrase of the key and a new passphrase to protect it
159 in the pkcs#12 file.
160
161 To import the created file on the machine you use this command:  
162
163 @smallexample
164   /usr/local/libexec/gpg-protect-tool --p12-import --store  @var{foo}.p12
165 @end smallexample
166
167 You will be asked for the pkcs#12 passphrase and a new passphrase to
168 protect the imported private key at its new location.
169
170 Note that there is no easy way to match existing certificates with
171 stored private keys because some private keys are used for Secure Shell
172 or other purposes and don't have a corresponding certificate.
173
174
175 @item A root certificate does not verify
176
177 A common problem is that the root certificate misses the required
178 basicConstrains attribute and thus @command{gpgsm} rejects this
179 certificate.  An error message indicating ``no value'' is a sign for
180 such a certificate.  You may use the @code{relax} flag in
181 @file{trustlist.txt} to accept the certificate anyway.  Note that the
182 fingerprint and this flag may only be added manually to
183 @file{trustlist.txt}.
184
185
186
187 @end itemize
188
189
190 @c ********************************************
191 @c ***  Architecture Details  *****************
192 @c ********************************************
193 @node Architecture Details
194 @section How the whole thing works internally.
195
196
197 @menu
198 * GnuPG-1 and GnuPG-2::   Relationship between the two branches.
199 @end menu
200
201 @node GnuPG-1 and GnuPG-2
202 @subsection  Relationship between the two branches.
203
204 Here is a little picture showing how the components work together:
205
206 @image{gnupg-card-architecture, 10cm}
207
208 @noindent
209 Lets try to explain it:
210
211 TO BE DONE.
212
213