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