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