* configure.ac: Require libksba 0.9.11.
[gnupg.git] / README
1                    The GNU Privacy Guard 2
2                   =========================
3                        Version 1.9.x
4
5
6 GnuPG 1.9 is the future version of GnuPG; it is based on the gnupg-1.3
7 code and the previous newpg package.  It will eventually lead to a
8 GnuPG 2.0 release.  Note that GnuPG 1.3 and 1.9 are not always in sync
9 and thus features and bug fixes done in 1.3 are not necessary
10 available in 1.9.
11
12 You should use this GnuPG version if you want to use the gpg-agent or
13 gpgsm (the S/MIME variant of gpg).  Note that the gpg-agent is also
14 helpful when using the standard gpg versions (1.2.x or 1.3.x).
15
16
17 BUILD INSTRUCTIONS
18 ==================
19
20 GnuPG 1.9 depends on the following packages:
21
22   libgpg-error (ftp://ftp.gnupg.org/gcrypt/libgpg-error/)
23   libgcrypt    (ftp://ftp.gnupg.org/gcrypt/libgcrypt/)
24   libassuan    (ftp://ftp.gnupg.org/gcrypt/alpha/libassuan/)
25   libksba      (ftp://ftp.gnupg.org/gcrypt/alpha/libksba/)
26   
27 If you use the configure option --enable-agent-only, libksba is not
28 required.
29
30 You also need the pinentry package for most function of GnuPG; however
31 it is not a build requirement.  pinentry is available at
32 ftp://ftp.gnupg.org/gcrypt/pinentry/ .
33
34 You should get the latest versions of course, the GnuPG configure
35 script complains if a version is not sufficient.
36
37 After building and installing the above packages in the order as given
38 above, you may now continue with GnuPG installation (you may also just
39 try to build GnuPG to see whether your already installed versions are
40 sufficient).
41
42 As with all packages, you just have to do
43
44  ./configure
45  make
46  make install
47
48 (Before doing install you might need to become root.)
49
50 If everything succeeds, you have a working GnuPG with support for
51 S/MIME and smartcards.  Note that there is no binary gpg but a gpg2 so
52 that this package won't confict with a GnuPG 1.2 or 1.3
53 installation. gpg2 behaves just like gpg; it is however suggested to
54 keep using gpg 1.2.x or 1.3.x.
55
56 In case of problem please ask on gpa-dev@gnupg.org for advise.  Note
57 that this release is only expected to build on GNU and *BSD systems.
58
59 A texinfo manual named `gnupg.info' will get installed.  Some commands
60 and options given below.  See also the section `SMARTCARD INTRO'.
61
62
63 COMMANDS
64 ========
65
66 gpgsm:
67 ------
68
69 --learn-card
70
71    Read information about the private keys from the smartcard and
72    import the certificates from there.
73
74 --export
75
76    Export all certificates stored in the Keybox or those specified on
77    the command line.  When using --armor a few informational lines are
78    prepended before each block.
79
80
81 gpg2: (Note that these card commands are also available with gpg 1.3.x)
82 -----
83
84 --card-status
85
86    Show information pertaining smartcards implementing the OpenPGP
87    application.
88
89 --change-pin
90
91    Offers a menu to change the PIN of OpenPGP smartcards and to reset
92    the retry counters.
93
94 --card-edit
95
96    Offers a menu to change any data object on the card and to generate
97    the keys. 
98
99
100 OPTIONS
101 =======
102
103 gpgsm:
104 ------
105
106 --include-certs <n>
107
108   Using N of -2 includes all certificate except for the Root cert,
109   -1 includes all certs, 0 does not include any certs, 1 includes only
110   the signers cert (this is the default) and all other positives
111   values include up to N certs starting with the signer cert.
112   
113 --policy-file <filename>
114
115   Chnage the deault name of the policy file
116
117 --enable-policy-checks
118 --disable-policy-checks
119
120   By default policy checks are enabled.  These options may be used to
121   change it.
122
123 --enable-crl-checks
124 --disable-crl-checks
125
126   By default the CRL checks are enabled and the DirMngr is used to
127   check for revoked certificates.  The disable option is most useful
128   with a off-line connection to suppres this check.
129
130 --agent-program <path_to_agent_program>
131
132   Specify an agent program to be used for secret key operations.  The
133   default value is "../agent/gpg-agent".  This is only used as a
134   fallback when the envrionment varaibale GPG_AGENT_INFO is not set or
135   a running agent can't be connected.
136   
137 --dirmngr-program <path_to_dirmgr_program>
138
139   Specify a dirmngr program to be used for CRL checks.  The default
140   value is "/usr/sbin/dirmngr".  This is only used as a fallback when
141   the environment varaibale DIRMNGR_INFO is not set or a running
142   dirmngr can't be connected.
143
144 --no-secmem-warning
145
146   Don't print the warning "no secure memory"
147
148 --armor
149
150   Create PEM ecoded output.  Default is binary output. 
151
152 --base64 
153
154   Create Base-64 encoded output; i.e. PEM without the header lines.
155
156 --assume-armor
157
158   Assume the input data is PEM encoded.  Default is to autodetect the
159   encoding but this is may fail.
160
161 --assume-base64
162
163   Assume the input data is plain base-64 encoded.
164
165 --assume-binary
166
167   Assume the input data is binary encoded.
168
169 --server
170
171   Run in server mode.  This is used by GPGME to control gpgsm.  See
172   the assuan specification regarding gpgsm about the used protocol.
173   Some options are ignored in server mode.
174
175 --local-user  <user_id>
176
177   Set the user to be used for signing.  The default is the first
178   secret key found in the database.
179
180 --with-key-data
181
182   Displays extra information with the --list-keys commands.  Especially
183   a line tagged "grp" is printed which tells you the keygrip of a
184   key.  This is string is for example used as the filename of the
185   secret key.
186
187
188
189 gpg-agent:
190 ---------
191
192 --pinentry-program <path_to_pinentry_program>
193
194   Specify the PINentry program.  The default value is
195   "<prefix>/bin/pinentry" so you most likely want to specify it.
196
197 --no-grab
198
199   Tell the pinentry not to grab keybourd and mouse.  You most likely
200   want to give this option during testing and development to avoid
201   lockups in case of bugs.
202
203                      
204 scdaemon:
205 --------
206
207 --ctapi-driver <libraryname>
208
209   The default for Scdaemon is to use the PC/SC API currently provided
210   by libpcsclite.so.  As an alternative the ctAPI can be used by
211   specify this option with the appropriate driver name
212   (e.g. libtowitoko.so).
213
214 --reader-port <portname>
215
216   This specifies the port of the chipcard reader.  For PC/SC this is
217   currently ignored and the first PC/SC reader is used.  For the
218   ctAPI, a number must be specified (the default is 32768 for the
219   first USB port).
220
221 --disable-ccid 
222
223   Disable the integrated support for CCID compliant readers.  This
224   allows to fall back to one of the other drivers even if the internal
225   CCID driver can handle the reader.  Note, that CCID support is only
226   available if libusb was available at build time.
227
228
229 FILES
230 =====
231
232 The default home directory is ~/.gnupg.  It can be changed by
233 either the --homedir option or by seting the environment variable
234 GNUPGHOME.  This is a list of files usually found in this directory:
235
236 gpgsm.conf 
237
238         Options for gpgsm.  Options are the same as the command line
239         options but don't enter the leading dashes and give arguments
240         without an equal sign.  Blank lines and lines starting with a
241         hash mark as the first non whitye space character are ignored.
242
243 gpg-agent.conf
244         
245         Options for gpg-agent
246
247 scdaemon.conf
248
249         Options for scdaemon.
250
251 dirmngr.conf 
252
253         Options for the DirMngr which is not part of this package and
254         the option file wilol most likely be moved to /etc
255
256 gpg.conf
257         
258         Options for gpg.  Note that old versions of gpg use the
259         filename `options' instead of `gpg.conf'.
260
261 gpg.conf-1.9.x
262
263         Options for gpg; tried before gpg.conf
264
265
266 policies.txt
267
268         A list of allowed CA policies.  This file should give the
269         object identifiers of the policies line by line.  Empty lines
270         and lines startung with a hash mark are ignored.
271
272         ++++++++++
273         2.289.9.9  
274         ++++++++++
275
276 trustlist.txt
277
278         A list of trusted certificates. The file will be created
279         automagically with some explaining comments.  By using
280         gpg-agent's option --allow-mark-trusted, gpg-agent may add new
281         entries after user confirmation.
282
283 random_seed
284
285         Used internally for keeping the state of the RNG over
286         invocations.
287
288 pubring.kbx
289
290         The database file with the certificates. 
291
292 pubring.gpg
293
294         The database file with the OpenPGP public keys.  This will
295         eventually be merged with pubring.kbx
296
297 secring.gpg
298
299         The database file with the OpenPGP secret keys.  This will be
300         removed when gpg is changed to make use of the gpg-agent.
301
302
303 private-keys-v1.d/
304
305         Directory holding the private keys maintained by gpg-agent.
306         For detailed info see agent/keyformat.txt. Note that there is
307         a helper tool gpg-protect-tool which may be used to protect or
308         unprotect keys.  This is however nothing a user should care
309         about.
310
311
312 SOURCE FILES
313 ============
314
315 Here is a list of directories with source files:
316
317 jnlib/  utility functions
318 kbx/    keybox library
319 g10/    the gpg program here called gpg2
320 sm/     the gpgsm program
321 agent/  the gpg-agent
322 scd/    the smartcard daemon
323 doc/    documentation
324
325
326
327 HOW TO SPECIFY A USER ID
328 ========================
329
330 Due to the way X.509 certificates are made up we need a few new ways
331 to specify a certificate (aka key in OpenPGP).  In addition to the
332 ways a user ID can be specified with gpg, I have implemented 3 new
333 modes for gpgsm, here is the entire list of ways to specify a key:
334
335  * By keyID.
336
337    This format is deducded from the length of the string and its
338    content or "0x" prefix. For use with OpenPGP a exclamation mark may
339    be appended to force use of the specified (sub)key.
340
341    As with v34 OpenPGP keys, the keyID of an X509 certificate are the
342    low 64 bits of the SHA-1 fingerprint.  The use of keyIDs is just a
343    shortcut, for all automated processing the fingerprint should be
344    used.
345
346    Examples:
347
348        234567C4
349        0F34E556E
350        01347A56A
351        0xAB123456
352
353        234AABBCC34567C4
354        0F323456784E56EAB
355        01AB3FED1347A5612
356        0x234AABBCC34567C4
357
358  * By fingerprint
359
360    This is format is deduced from the length of the string and its
361    content or "0x" prefix.  Note, that only the 20 byte fingerprint is
362    used with GPGSM (SHA-1 hash of the certificate).  For use with
363    OpenPGP a exclamation mark may be appended to force use of the
364    specified (sub)key.
365
366    Examples:
367
368        1234343434343434C434343434343434
369        123434343434343C3434343434343734349A3434
370        0E12343434343434343434EAB3484343434343434
371        0xE12343434343434343434EAB3484343434343434
372
373  * Exact match on OpenPGP user ID
374
375    This is denoted by a leading equal sign. It does not make much
376    sense for X.509.
377
378    Example:
379
380        =Heinrich Heine <heinrichh@uni-duesseldorf.de>
381
382  * Exact match on an email address.
383
384    This is indicated by enclosing the email address in the usual way
385    with left and right angles
386
387    Example:
388
389        <heinrichh@uni-duesseldorf.de>
390
391  * Word match
392
393    All words must match exactly (not case sensitive) but can appear in
394    any order in the user ID or a subjects name.  Words are any
395    sequences of letters, digits, the underscore and all characters
396    with bit 7 set.
397
398    Example:
399
400        +Heinrich Heine duesseldorf
401
402  * Exact match by subject's DN
403
404    This is indicated by a leading slash, directly followed by the
405    rfc2253 encoded DN of the subject.  Note that you can't use the
406    string printed by "gpgsm --list-keys" because that one as been
407    reordered and modified for better readability; use --with-colons to 
408    print the raw (but standard escaped) rfc2253 string 
409
410    Example:
411
412       /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
413
414  * Excact match by issuer's DN
415
416    This is indicated by a leading hash mark, directly followed by a
417    slash and then directly followed by the rfc2253 encoded DN of the
418    issuer.  This should return the Root cert of the issuer.  See note
419    above.
420
421    Example:
422
423       #/CN=Root Cert,O=Poets,L=Paris,C=FR
424
425  * Exact match by serial number and issuer's DN
426
427    This is indicated by a hash mark, followed by the hexadecmal
428    representation of the serial number, the followed by a slash and
429    the RFC2253 encoded DN of the issuer. See note above.
430
431    Example:
432
433       #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
434
435  * Substring match
436
437    By case insensitive substring matching.  This is the default mode
438    but applications may want to explicitly indicate this by putting
439    the asterisk in front.
440
441    Example:
442
443         Heine
444         *Heine
445
446
447 Please note that we have reused the hash mark identifier which was
448 used in old GnuPG versions to indicate the so called local-id.  It is
449 not anymore used and there should be no conflict when used with X.509
450 stuff.
451
452 Using the rfc2253 format of DNs has the drawback that it is not
453 possible to map them back to the original encoding, however we don't
454 have to do this, because our key database stores this encoding as meta
455 data.
456
457 Some of the search modes are not yet implemented ;-)
458
459
460 HOW TO IMPORT A PRIVATE KEY
461 ===========================
462 There is some limited support to import a private key from a PKCS-12
463 file.  
464
465  gpgsm --import  foo.p12
466
467 This requires that the gpg-agent is running.
468
469
470 HOW TO EXPORT A PRIVATE KEY
471 ===========================
472 There is also limited support to export a private key in PKCS-12
473 format. However there is no MAC applied.
474
475  gpgsm --export-secret-key-p12 userID  >foo.p12
476
477
478 SMARTCARD INTRO
479 ===============
480
481 GPG, the OpenPGP part of GnuPG, supports the OpenPGP smartcard
482 (surprise!); see http://g10code.com/p-card.html.
483
484 [Fixme: We need to explain this further]
485
486
487 GPGSM, the CMS (S/MIME) part of GnuPG, supports two kinds of
488 smartcards.  The most flexible way is to use PKCS#15 compliant cards,
489 however you must have build GnuPG with support for the OpenSC library.
490 The build process automagically detects the presence of this library
491 and will include support for these cards.
492
493 The other cards we currently support are the Telesec NetKey card with
494 the NKS 2.0 card application and all generic DINSIG cards.
495
496 Before GPGSM can make use of a new card it must gather some
497 information, like the card's serial number, the public keys and the
498 certificates stored on the card.  Thus for a new card you need to run
499 the command
500
501   gpgsm --learn-card
502
503 once.  This is also a good test to see whether your card reader is
504 properly installed. See below in case of error.  Once this has been
505 done you may use the keys stored on the card in the same way you use
506 keys stored on the disk.  gpgsm automagically knows whether a card is
507 required and will pop up the pinentry to ask you to insert the
508 correct card.
509
510 For selecting the driver, see the options of scdaemon.  A useful
511 debugging flag is "--debug 2048" showing the communication between
512 scdaemon and the reader.
513
514 [fixme: write more stuff]
515
516
517
518
519