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