doc/Notes

   1
   2 Add an infor page for watchgnupg.
   3
   4 > * How to mark a CA certificate as trusted.
   5
   6 There are two ways:
   7
   8   1. Let gpg-agent do this for you.  Since version 1.9.9 you need to
   9      add the option --allow-mark-trusted  gpg-agent.conf or when
  10      invoking gpg-agent.  Everytime gpgsm notices an untrusted root
  11      certificate gpg-agent will pop up a dialog to ask whether this
  12      certificate should be trusted.  This is similar to whatmost
  13      browsers do.
  14
  15      The disadvantage of this method and the reason why
  16      --allow-mark-trusted is required is that the list of trusted root
  17      certificates will grow, because almost all user will just hit
  18      "yes, I trust" and "yes, I verified the fingerprint" without
  19      understanding that this is a very serious decision.
  20
  21   2. Use your editor.  Edit the file ~/.gnupg/trustlist.txt and add
  22      the fingerprints of the trusted root certificates. There are
  23      comments on the top explaining the simple format.  The current
  24      CVS version allows for colons in the fingerprint, so you can
  25      easily cut and paste it from whereever you know that this is the
  26      correct fingerprint.
  27
  28 An example for an entry in the trustlist.txt is:
  29
  30   # CN=PCA-1-Verwaltung,O=PKI-1-Verwaltung,C=de
  31   3EEE3D8BB7F0FE5C9F5804A3A7E51BCE98209DF9 S
  32
  33 This is in fact one that probably made its way into the file using the
  34 first method.  As usual a # indicates a comment.  The trailing S means
  35 that this is to be used for (X.509).
  36
  37 It is not possible to trust intermediate CA certificates; gpgsm always
  38 checks the entire chain of certificates.
  39
  40 > * How to import a key and bind it to some certificate already
  41 >   imported.  Alternatively, import key and certificate together, from
  42 >   a pkcs12 blob, or pkcs8 + certificate blobs, or whatever.
  43 >   Alternatively, don't import the key at all, but specify location of
  44 >   key using a parameter when signing.
  45
  46 You always need to import the key; there is something similar to a
  47 keyring (here called a keybox: ~/.gnupg/pubring.kbx).
  48
  49 Importing a key either from a binary or ascii armored (PEM) certificate
  50 file or from a cert-only signature file is done using
  51
  52   gpg --import FILE
  53
  54 or
  55
  56   gpg --import < FILE
  57
  58 In general you should first import the root certificates and then down
  59 to the end user certificate.  You may put all into one file and gpgsm
  60 will do the right thing in this case independend of the order.
  61
  62 While verifying a signature, all included certificates are
  63 automagically imported.
  64
  65 To import from a pkcs#12 file you may use the same command; if a
  66 private key is contained in that file, you will be asked for the
  67 transport passphrases as well as for the new passphrase used to
  68 protect it in gpg-agent's private key storage
  69 (~/.gnupg/private-keys-v1.d/). Note that the pkcs#12 support is very
  70 basic but sufficient for certificates exported from Mozilla, OpenSSL
  71 and MS Outlook.
  72
  73 Background info on private keys:
  74
  75 If you want to look at the private key you first need to know the name
  76 of the keyfile.  Run the command "gpgsm -K --with-key-data [KEYID]" and
  77 you get an output like:
  78
  79   crs::1024:1:CF8[..]6D:20040105T184908:2006[...]:09::CN=ZS[....]::esES:
  80   fpr:::::::::3B50BF2BDAF2[...]1AE6796D:::2812[...]508F21F065E65E44:
  81   grp:::::::::C92DB9CFD588ADE846BE3AC4E7A2E1B11A4A2ADB:
  82   uid:::::::::CN=Werner Koch,OU=test,O=g10 Code,C=de::
  83   uid:::::::::<wk@g10code.de>::
  84
  85 This should be familar to advanced gpg-users; see doc/DETAILS in gpg
  86 1.3 (CVS HEAD) for a description of the records.  The value in the
  87 "grp" tagged record is the so called keygrip and you should find a
  88 file ~/.gnupg/private-keys-v1.d/C92DB9CFD588ADE846BE3AC4E7A2E1B11A4A2ADB.key
  89 with the private and public key in an S-expression like format.  The
  90 gpg-protect-tool may be used to display it in a human readable format:
  91
  92   $ gpgsm --call-protect-tool ~/.gnupg/private-keys-v1.d/C9[...]B.key
  93   (protected-private-key
  94    (rsa
  95     (n #00C16B6E807C47BB[...]10487#)
  96     (e #010001#)
  97     (protected openpgp-s2k3-sha1-aes-cbc
  98      (
  99       (sha1 "Hvü9Qt^Ç" "96")
 100       #2B17DC766AEA2568EE0C688E18F9757E#)
 101      #65A4FF9F30750A1300[...]7#)
 102     )
 103    )
 104
 105 The current CVS version of gpgsm has a command --dump-keys which lists
 106 more details of a key including the keygrip so you don't need to use
 107 the colon format if you want to manually debug things.
 108
 109   $ gpgsm --dump-keys
 110   Serial number: 01
 111          Issuer: CN=Trust Anchor,O=Test Certificates,C=US
 112         Subject: CN=Trust Anchor,O=Test Certificates,C=US
 113        sha1_fpr: 66:8A:47:56:A2:DC:88:FF:DA:B8:95:E1:3C:63:37:55:5F:0A:F7:BF
 114         md5_fpr: 03:01:3B:BB:EC:6C:5D:48:88:4C:95:63:99:84:ED:C0
 115         keygrip: 6A082B3063F6DA6D68B2994AB11B4328FD6206D2
 116       notBefore: 2001-04-19 14:57:20
 117        notAfter: 2011-04-19 14:57:20
 118        hashAlgo: 1.2.840.113549.1.1.5 (sha1WithRSAEncryption)
 119         keyType: 1024 bit RSA
 120       authKeyId: [none]
 121        keyUsage: certSign crlSign
 122     extKeyUsage: [none]
 123        policies: [none]
 124     chainLength: unlimited
 125           crlDP: [none]
 126        authInfo: [none]
 127        subjInfo: [none]
 128            extn: 2.5.29.14 (subjectKeyIdentifier)  [22 octets]
 129
 130 > * How to import a CRL
 131
 132 CRLs are managed by the dirmngr which is a separate package.  The idea
 133 is to eventaully turn it into a system daemon, so that on a multi-user
 134 machine CRLs are handled more efficiently.  As of now the dirmngr
 135 needs service from gpgsm thus it is best to call it through gpgsm:
 136
 137   gpgsm --call-dirmngr LOAD /absolute/filename/to/a/CRL/file
 138
 139 See the dirmngr README and manual for further details.
 140
 141 If you don't want to check CRLs, use the option --diable-crl-checks
 142 with gpgsm.
 143
 144 > I'm trying to replace the S/MIME support in OpenSSL with gpgsm for the
 145 > MUA Gnus.
 146
 147 Great; I'd love it.
 148
 149 > Perhaps I shouldn't be using gpgsm directly?  gpgme didn't seem to
 150 > have a command line front end.
 151
 152 For Gnus it makes sense to use gpgsm directly.  Enhancing pgg to
 153 support gpgsm should not be that hard.  Things you need to take care
 154 off are: Warn if GPG_AGENT_INFO has not been set, because this will
 155 call gpg-agent for each operation and obviously does not cache the
 156 passphrase them. If GPG_AGENT_INFO has been set, also disable the
 157 passphrase code for gpg and pass --use-agent to gpg - this way gpg
 158 benefits from the passphrase caching and the pinentry.
 159
 160 You may want to look at gpgconf (tools/README.gpgconf) to provide a
 161 customization interface for gpgsm, gpg-agent and dirmngr.
 162
 163 \f
 164 Module Overview
 165 ================
 166
 167 gpgsm
 168         libgpg-error
 169         libgcrypt
 170         libksba
 171         libassuan [statically linked]
 172         [Standard system libraries]
 173
 174 gpg-agent
 175         libgpg-error
 176         libgcrypt
 177         libassuan [statically linked]
 178         libpth    [system library]
 179         [Standard system libraries]
 180
 181 scdaemon
 182         libgpg-error
 183         libgcrypt
 184         libksba
 185         libassuan [statically linked]
 186         libusb    [system library, optional]
 187         libopensc [system library, optional]
 188         [For reader access libpcsclite or a CT-API library may be
 189          linked at runtime (controllable by scdaemon.conf)]
 190         [Standard system libraries]
 191
 192 gpg-protect-tool
 193         libgpg-error
 194         libgcrypt
 195         [Standard system libraries]
 196
 197 dirmngr
 198         libgpg-error
 199         libgcrypt
 200         libksba
 201         libassuan [statically linked]
 202         libldap [system libary]
 203         liblber [system libary]
 204         libsasl [system libary, required by libldap]
 205         libdb2  [system libary, required by libsasl]
 206         libcrypt [system libary, required by libsasl - OOPS]
 207         libpam  [system libary, required by libsasl]
 208         [Standard system libraries]
 209
 210 pinentry-curses
 211         libncurses
 212         [Standard system libraries]
 213         [Independent Assuan code is source included]
 214
 215 pinentry-gtk
 216         libncurses
 217         [GTK+ and X libraries]
 218         [Standard system libraries]
 219         [Independent Assuan code is source included]
 220
 221 pinentry-qt
 222         libncurses
 223         [QT and X libraries]
 224         [Standard system libraries]
 225         [Independent Assuan code is source included]
 226
 227 gpgme
 228         [Standard system libraries]
 229         [gpgsm is required at runtime]
 230         [Independent Assuan code is source included]
 231
 232 libgpg-error
 233         [none]
 234
 235 libgcrypt
 236         libgpg-error
 237
 238 libksba
 239         libgpg-error
 240
 241 libassuan
 242         [none]
 243
 244
 245