7aea069b35ed6a5ffea8a33c4af2cd37a298613a
[gnupg.git] / README
1 GnuPG 1.9 is a temporary protect to work on GnuPG extensions.  It will
2 eventually lead to a GnuPG 2.0 release.
3
4 jnlib/  utility functions
5 kbx/    keybox library
6 sm/     the gpgsm program
7 agent/  the gpg-agent
8 scd/    the smartcard daemon
9
10 You need the libgpg-error package.  Libassuan, Libksba and Libgcrypt
11 are also required to build it.
12
13 Keybox is designed to be source include-able.
14
15 A texinfo manual `gnupg.info' will get installed.  Some commands and
16 options given below.
17
18
19 COMMANDS
20 ========
21
22 gpgsm:
23 ------
24
25 --learn-card
26
27    Read tinformation about the private keys from the smartcard and
28    import the certificates from there.
29
30 --export
31
32     Export all certificates storein the Keybox or those specified on
33     the commandline.  When using --armor a few informational lines are
34     prepended before each block.
35
36
37 OPTIONS
38 =======
39
40 gpgsm:
41 ------
42
43 --include-certs <n>
44
45   Using N of -2 includes all certificate except for the Root cert,
46   -1 includes all certs, 0 does not include any certs, 1 includes only
47   the signers cert (this is the default) and all other positives
48   values include up to N certs starting with the signer cert.
49   
50 --policy-file <filename>
51
52   Chnage the deault name of the policy file
53
54 --enable-policy-checks
55 --disable-policy-checks
56
57   By default policy checks are enabled.  These options may be used to
58   change it.
59
60 --enable-crl-checks
61 --disable-crl-checks
62
63   By default the CRL checks are enabled and the DirMngr is used to
64   check for revoked certificates.  The disable option is most useful
65   with a off-line connection to suppres this check.
66
67 --agent-program <path_to_agent_program>
68
69   Specify an agent program to be used for secret key operations.  The
70   default value is "../agent/gpg-agent".  This is only used as a
71   fallback when the envrionment varaibale GPG_AGENT_INFO is not set or
72   a running agent can't be connected.
73   
74 --dirmngr-program <path_to_dirmgr_program>
75
76   Specify a dirmngr program to be used for CRL checks.  The default
77   value is "/usr/sbin/dirmngr".  This is only used as a fallback when
78   the envrionment varaibale DIRMNGR_INFO is not set or a running
79   dirmngr can't be connected.
80
81 --no-secmem-warning
82
83   Don't print the warning "no secure memory"
84
85 --armor
86
87   Create PEM ecoded output.  Default is binary output. 
88
89 --base64 
90
91   Create Base-64 encoded output; i.e. PEM without the header lines.
92
93 --assume-armor
94
95   Assume the input data is PEM encoded.  Default is to autodetect the
96   encoding but this is may fail.
97
98 --assume-base64
99
100   Assume the input data is plain base-64 encoded.
101
102 --assume-binary
103
104   Assume the input data is binary encoded.
105
106 --server
107
108   Run in server mode.  This is used by GPGME to control gpgsm.  See
109   the assuan specification regarding gpgsm about the used protocol.
110   Some options are ignored in server mode.
111
112 --local-user  <user_id>
113
114   Set the user to be used for signing.  The default is the first
115   secret key found in the database.
116
117 --with-key-data
118
119   Displays extra information with the --list-keys commands.  Especiall
120   a line tagged "grp" si printed which tells you the keygrip of a
121   key.  This is string is for example used as the filename of the
122   secret key.
123
124
125
126 gpg-agent:
127 ---------
128
129 --pinentry-program <path_to_pinentry_program>
130
131   Specify the PINentry program.  The default value is
132   "../../pinentry/kpinentry/kpinentry" so you most likely want to
133   specify it. 
134
135 --no-grab
136
137   Tel the pinentry not to grab keybourd and mouse.  You most likely
138   want to give this option during testing and development to avoid
139   lockups in case of bugs.
140
141                      
142
143
144
145 FILES
146 =====
147
148 The default home directory is ~/.gnupg.  It can be changed by
149 either the --homedir option or by seting the environment variable
150 GNUPGHOME.  This is a list of files usually found in this directory:
151
152 gpgsm.conf 
153
154         Options for gpgsm.  Options are the same as the command line
155         options but don't enter the leading dashes and give arguments
156         without an equal sign.  Blank lines and lines starting with a
157         hash mark as the first non whitye space character are ignored.
158
159 gpg-agent.conf
160         
161         Options for gpg-agent
162
163 scdaemon.conf
164
165         Options for scdaemon.
166
167 dirmngr.conf 
168
169         Options for the DirMngr which is not part of this package and
170         the option file wilol most likely be moved to /etc
171
172 gpg.conf
173         
174         Options for gpg.  Note that old versions of gpg use the
175         filename `options' instead of `gpg.conf'.
176
177 policies.txt
178
179         A list of allowed CA policies.  This file should give the
180         object identifiers of the policies line by line.  emptry lines
181         and lines startung with a hash mark are ignored.
182
183         ++++++++++
184         2.289.9.9  
185         ++++++++++
186
187 trustlist.txt
188
189         A list of trusted certificates usually maintained by
190         gpg-agent.  It can however be edited manually.  The file will
191         be created automagically with some explaining comments.
192
193 random_seed
194
195         Used internally for keeping the state of the RNG over
196         invocations.
197
198 pubring.kbx
199
200         The database file with the certificates. 
201
202 pubring.gpg
203
204         The database file with the OpenPGP public keys.  This will
205         eventually be merged with pubring.kbx
206
207 secring.gpg
208
209         The database file with the OpenPGP secret keys.  This will be
210         removed when gpg is changed to make use of the gpg-agent.
211
212
213 private-keys-v1.d/
214
215         Directory holding the private keys maintained by gpg-agent.
216         For detailed info see agent/keyformat.txt. Note that there is
217         a helper tool gpg-protect-tool which may be used to protect or
218         unprotect keys.  This is however nothing a user should care
219         about.
220
221
222 How to specify a user ID
223 ========================
224
225 Due to the way X.509 certificates are made up we need a few new ways
226 to specify a certificate (aka key in OpenPGP).  In addition to the
227 ways a user ID can be specified with gpg, I have implemented 3 new
228 modes for gpgsm, here is the entire list of ways to specify a key:
229
230  * By keyID.
231
232    This format is deducded from the length of the string and its
233    content or "0x" prefix. For use with OpenPGP a exclamation mark may
234    be appended to force use of the specified (sub)key.
235
236    As with v34 OpenPGP keys, the keyID of an X509 certificate are the
237    low 64 bits of the SHA-1 fingerprint.  The use of keyIDs is just a
238    shortcut, for all automated processing the fingerprint should be
239    used.
240
241    Examples:
242
243        234567C4
244        0F34E556E
245        01347A56A
246        0xAB123456
247
248        234AABBCC34567C4
249        0F323456784E56EAB
250        01AB3FED1347A5612
251        0x234AABBCC34567C4
252
253  * By fingerprint
254
255    This is format is deduced from the length of the string and its
256    content or "0x" prefix.  Note, that only the 20 byte fingerprint is
257    used with GPGSM (SHA-1 hash of the certificate).  For use with
258    OpenPGP a exclamation mark may be appended to force use of the
259    specified (sub)key.
260
261    Examples:
262
263        1234343434343434C434343434343434
264        123434343434343C3434343434343734349A3434
265        0E12343434343434343434EAB3484343434343434
266        0xE12343434343434343434EAB3484343434343434
267
268  * Exact match on OpenPGP user ID
269
270    This is denoted by a leading equal sign. It does not make much
271    sense for X.509.
272
273    Example:
274
275        =Heinrich Heine <heinrichh@uni-duesseldorf.de>
276
277  * Exact match on an email address.
278
279    This is indicated by enclosing the email address in the usual way
280    with left and right angles
281
282    Example:
283
284        <heinrichh@uni-duesseldorf.de>
285
286  * Word match
287
288    All words must match exactly (not case sensitive) but can appear in
289    any order in the user ID or a subjects name.  Words are any
290    sequences of letters, digits, the underscore and all characters
291    with bit 7 set.
292
293    Example:
294
295        +Heinrich Heine duesseldorf
296
297  * [NEW] Exact match by subject's DN
298
299    This is indicated by a leading slash, directly followed by the
300    rfc2253 encoded DN of the subject.
301
302    Example:
303
304       /CN=Henrich Heine,O=Poets,L=Paris,C=FR
305
306  * [NEW] Excact match by issuer's DN
307
308    This is indicated by a leading hash mark, directly followed by a
309    slash and then directly followed by the rfc2253 encoded DN of the
310    issuer.  This should return the Root cert of the issuer
311
312    Example:
313
314       #/CN=Root Cert,O=Poets,L=Paris,C=FR
315
316  * [NEW] Exact match by serial number and subject's DN
317
318    This is indicated by a hash mark, followed by the hexadecmal
319    representation of the serial number, the followed by a slahs and
320    the RFC2253 encoded DN of the issuer.
321
322    Example:
323
324       #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
325
326  * Substring match
327
328    By case insensitive substring matching.  This is the default mode
329    but applications may want to explicitly indicate this by putting
330    the asterisk in front.
331
332    Example:
333
334         Heine
335         *Heine
336
337
338 Please note that we have reused the hash mark indentifier which was
339 used in old GnuPG versions to indicate the so called local-id.  It is
340 not anymore used and there should be no conflict when used with X.509
341 stuff.
342
343 Using the rfc2253 format of DNs has the drawback that it is not
344 possible to map them back to the original encoding, however we don't
345 have to do this, because our key database stores this encoding as meta
346 data.
347
348 Some of the search modes are not yet implemented ;-)
349
350
351 How to import a private key
352 ===========================
353 There is some limited support to import a private key from a PKCS-12
354 file.  Note, that this does only import the private key and not any
355 certificates available in that file. 
356
357  gpgsm --call-protect-tool --p12-import --store  foo.p12
358
359 This require that the gpg-agent is running, alternative you may give
360 the passphrase on the commandline using the option "-P <passphrase>" -
361 however this is in general not a good idea.  If that key already
362 exists, the protect-tool refuses to store it unless you use the option
363 "--force". 
364
365 How to export a private key
366 ===========================
367 There is also limited support to export a private key in PKCS-12
368 format. However the certificate is not stored and there is no MAC applied.
369
370  gpgsm --call-protect-tool --p12-export  foo.key  >foo.p12
371
372