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 @item Error message: ``digest algorithm N has not been enabled''
 186
 187 The signature is broken.  You may try the option
 188 @option{--extra-digest-algo SHA256} to workaround the problem.  The
 189 number N is the internal algorighm indentifier; for example 8 refers to
 190 SHA-256.
 191
 192 @end itemize
 193
 194
 195 @c ********************************************
 196 @c ***  Architecture Details  *****************
 197 @c ********************************************
 198 @node Architecture Details
 199 @section How the whole thing works internally.
 200
 201
 202 @menu
 203 * GnuPG-1 and GnuPG-2::   Relationship between the two branches.
 204 @end menu
 205
 206 @node GnuPG-1 and GnuPG-2
 207 @subsection  Relationship between the two branches.
 208
 209 Here is a little picture showing how the components work together:
 210
 211 @image{gnupg-card-architecture, 10cm}
 212
 213 @noindent
 214 Lets try to explain it:
 215
 216 TO BE DONE.
 217
 218