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