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