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