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