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