Merge branch 'master' into key-storage-work
[gnupg.git] / 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