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