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