* configure.ac: Big warning that TIGER/192 is being removed from the
[gnupg.git] / README
1
2                     GnuPG - The GNU Privacy Guard
3                    -------------------------------
4                             Version 1.3.2
5
6              Copyright 1998, 1999, 2000, 2001, 2002, 2003
7                     Free Software Foundation, Inc.
8
9     This file is free software; as a special exception the author gives
10     unlimited permission to copy and/or distribute it, with or without
11     modifications, as long as this notice is preserved.
12
13     This file is distributed in the hope that it will be useful, but
14     WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
15     implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16
17
18     Intro
19     -----
20
21     GnuPG is GNU's tool for secure communication and data storage.
22     It can be used to encrypt data and to create digital signatures.
23     It includes an advanced key management facility and is compliant
24     with the proposed OpenPGP Internet standard as described in RFC2440.
25
26     GnuPG works best on GNU/Linux or *BSD systems.  Most other Unices
27     are also supported but are not as well tested as the Free Unices.
28     See http://www.gnupg.org/gnupg.html#supsys for a list of systems
29     which are known to work.
30
31     See the file COPYING for copyright and warranty information.
32
33     Because GnuPG does not use use any patented algorithm it cannot be
34     compatible with PGP2 versions.  PGP 2.x uses IDEA (which is patented
35     worldwide).
36
37     The default algorithms are DSA and ElGamal, but RSA is also
38     supported.  ElGamal for signing is available, but because of the
39     larger size of such signatures it is deprecated (Please note that
40     the GnuPG implementation of ElGamal signatures is *not* insecure).
41     Symmetric algorithms are: AES, 3DES, Blowfish, CAST5 and Twofish.
42     Digest algorithms available are MD5, RIPEMD160 and SHA1.
43
44
45     Installation
46     ------------
47     Please read the file INSTALL and the sections in this file
48     related to the installation.  Here is a quick summary:
49
50     1) Check that you have unmodified sources.  See below on how to do
51        this.  Don't skip it - this is an important step!
52
53     2)  Unpack the TAR.  With GNU tar you can do it this way:
54         "tar xzvf gnupg-x.y.z.tar.gz"
55
56     3) "cd gnupg-x.y.z"
57
58     4)  "./configure"
59
60     5) "make"
61
62     6) "make install"
63
64     7) You end up with a "gpg" binary in /usr/local/bin.
65
66     8) To avoid swapping out of sensitive data, you can install "gpg" as
67        suid root.  If you don't do so, you may want to add the option
68        "no-secmem-warning" to ~/.gnupg/gpg.conf
69
70
71     How to Verify the Source
72     ------------------------
73     In order to check that the version of GnuPG which you are going to
74     install is an original and unmodified one, you can do it in one of
75     the following ways:
76
77     a) If you already have a trusted Version of GnuPG installed, you
78        can simply check the supplied signature:
79
80         $ gpg --verify gnupg-x.y.z.tar.gz.asc
81
82        This checks that the detached signature gnupg-x.y.z.tar.gz.asc
83        is indeed a a signature of gnupg-x.y.z.tar.gz.  The key used to
84        create this signature is:
85
86        "pub  1024D/57548DCD 1998-07-07 Werner Koch (gnupg sig) <dd9jn@gnu.org>"
87
88        If you do not have this key, you can get it from the source in
89        the file doc/samplekeys.asc (use "gpg --import  doc/samplekeys.asc"
90        to add it to the keyring) or from any keyserver.  You have to
91        make sure that this is really the key and not a faked one. You
92        can do this by comparing the output of:
93
94                 $ gpg --fingerprint 0x57548DCD
95
96        with the fingerprint published elsewhere.
97
98        Please note, that you have to use an old version of GnuPG to
99        do all this stuff.  *Never* use the version which you are going
100        to check!
101
102
103     b) If you don't have any of the above programs, you have to verify
104        the MD5 checksum:
105
106         $ md5sum gnupg-x.y.z.tar.gz
107
108        This should yield an output _similar_ to this:
109
110         fd9351b26b3189c1d577f0970f9dcadc  gnupg-x.y.z.tar.gz
111
112        Now check that this checksum is _exactly_ the same as the one
113        published via the announcement list and probably via Usenet.
114
115
116
117     Documentation
118     -------------
119     The manual will be distributed separate under the name "gph".
120     An online version of the latest manual draft is available at the
121     GnuPG web pages:
122
123         http://www.gnupg.org/gph/
124
125     A list of frequently asked questions is available in GnuPG's
126     distibution in the file doc/FAQ and online as:
127
128         http://www.gnupg.org/faq.html
129
130     A couple of HOWTO documents are available online; for a listing see:
131
132         http://www.gnupg.org/docs.html#howtos
133
134     A man page with a description of all commands and options gets installed
135     along with the program. 
136
137
138     Introduction
139     ------------
140     Here is a brief overview on how to use GnuPG - it is strongly suggested
141     that you read the manual and other information about the use of
142     cryptography.  GnuPG is only a tool, secure usage requires that
143     YOU KNOW WHAT YOU ARE DOING.
144
145     If you already have a DSA key from PGP 5 (they call them DH/ElGamal)
146     you can simply copy the pgp keyrings over the GnuPG keyrings after
147     running gpg once to create the correct directory.
148
149     The normal way to create a key is
150
151         gpg --gen-key
152
153     This asks some questions and then starts key generation. To create
154     good random numbers for the key parameters, GnuPG needs to gather
155     enough noise (entropy) from your system.  If you see no progress
156     during key generation you should start some other activities such
157     as mouse moves or hitting on the CTRL and SHIFT keys.
158
159     Generate a key ONLY on a machine where you have direct physical
160     access - don't do it over the network or on a machine used also
161     by others - especially if you have no access to the root account.
162
163     When you are asked for a passphrase use a good one which you can
164     easy remember.  Don't make the passphrase too long because you have
165     to type it for every decryption or signing; but, - AND THIS IS VERY
166     IMPORTANT - use a good one that is not easily to guess because the
167     security of the whole system relies on your secret key and the
168     passphrase that protects it when someone gains access to your secret
169     keyring.  A good way to select a passphrase is to figure out a short
170     nonsense sentence which makes some sense for you and modify it by
171     inserting extra spaces, non-letters and changing the case of some
172     characters - this is really easy to remember especially if you
173     associate some pictures with it.
174
175     Next, you should create a revocation certificate in case someone
176     gets knowledge of your secret key or you forgot your passphrase
177
178         gpg --gen-revoke your_user_id
179
180     Run this command and store the revocation certificate away.  The output
181     is always ASCII armored, so that you can print it and (hopefully
182     never) re-create it if your electronic media fails.
183
184     Now you can use your key to create digital signatures
185
186         gpg -s file
187
188     This creates a file "file.gpg" which is compressed and has a
189     signature attached.
190
191         gpg -sa file
192
193     Same as above, but creates a file "file.asc" which is ASCII armored
194     and and ready for sending by mail.  It is better to use your
195     mailers features to create signatures (The mailer uses GnuPG to do
196     this) because the mailer has the ability to MIME encode such
197     signatures - but this is not a security issue.
198
199         gpg -s -o out file
200
201     Creates a signature of "file", but writes the output to the file
202     "out".
203
204     Everyone who knows your public key (you can and should publish
205     your key by putting it on a key server, a web page or in your .plan
206     file) is now able to check whether you really signed this text
207
208         gpg --verify file
209
210     GnuPG now checks whether the signature is valid and prints an
211     appropriate message.  If the signature is good, you know at least
212     that the person (or machine) has access to the secret key which
213     corresponds to the published public key.
214
215     If you run gpg without an option it will verify the signature and
216     create a new file that is identical to the original.  gpg can also
217     run as a filter, so that you can pipe data to verify trough it
218
219         cat signed-file | gpg | wc -l
220
221     which will check the signature of signed-file and then display the
222     number of lines in the original file.
223
224     To send a message encrypted to someone you can use
225
226         gpg -e -r heine file
227
228     This encrypts "file" with the public key of the user "heine" and
229     writes it to "file.gpg"
230
231         echo "hello" | gpg -ea -r heine | mail heine
232
233     Ditto, but encrypts "hello\n" and mails it as ASCII armored message
234     to the user with the mail address heine.
235
236         gpg -se -r heine file
237
238     This encrypts "file" with the public key of "heine" and writes it
239     to "file.gpg" after signing it with your user id.
240
241         gpg -se -r heine -u Suttner file
242
243     Ditto, but sign the file with your alternative user id "Suttner"
244
245
246     GnuPG has some options to help you publish public keys.  This is
247     called "exporting" a key, thus
248
249         gpg --export >all-my-keys
250
251     exports all the keys in the keyring and writes them (in a binary
252     format) to "all-my-keys".  You may then mail "all-my-keys" as an
253     MIME attachment to someone else or put it on an FTP server. To
254     export only some user IDs, you give them as arguments on the command
255     line.
256
257     To mail a public key or put it on a web page you have to create
258     the key in ASCII armored format
259
260         gpg --export --armor | mail panther@tiger.int
261
262     This will send all your public keys to your friend panther.
263
264     If you have received a key from someone else you can put it
265     into your public keyring.  This is called "importing"
266
267         gpg --import [filenames]
268
269     New keys are appended to your keyring and already existing
270     keys are updated. Note that GnuPG does not import keys that
271     are not self-signed.
272
273     Because anyone can claim that a public key belongs to her
274     we must have some way to check that a public key really belongs
275     to the owner.  This can be achieved by comparing the key during
276     a phone call.  Sure, it is not very easy to compare a binary file
277     by reading the complete hex dump of the file - GnuPG (and nearly
278     every other program used for management of cryptographic keys)
279     provides other solutions.
280
281         gpg --fingerprint <username>
282
283     prints the so called "fingerprint" of the given username which
284     is a sequence of hex bytes (which you may have noticed in mail
285     sigs or on business cards) that uniquely identifies the public
286     key - different keys will always have different fingerprints.
287     It is easy to compare fingerprints by phone and I suggest
288     that you print your fingerprint on the back of your business
289     card.  To see the fingerprints of the secondary keys, you can
290     give the command twice; but this is normally not needed.
291
292     If you don't know the owner of the public key you are in trouble.
293     Suppose however that friend of yours knows someone who knows someone
294     who has met the owner of the public key at some computer conference.
295     Suppose that all the people between you and the public key holder
296     may now act as introducers to you.  Introducers signing keys thereby
297     certify that they know the owner of the keys they sign.  If you then
298     trust all the introducers to have correctly signed other keys, you
299     can be be sure that the other key really belongs to the one who
300     claims to own it..
301
302     There are 2 steps to validate a key:
303         1. First check that there is a complete chain
304            of signed keys from the public key you want to use
305            and your key and verify each signature.
306         2. Make sure that you have full trust in the certificates
307            of all the introduces between the public key holder and
308            you.
309     Step 2 is the more complicated part because there is no easy way
310     for a computer to decide who is trustworthy and who is not.  GnuPG
311     leaves this decision to you and will ask you for a trust value
312     (here also referenced as the owner-trust of a key) for every key
313     needed to check the chain of certificates.  You may choose from:
314       a) "I don't know" - then it is not possible to use any
315          of the chains of certificates, in which this key is used
316          as an introducer, to validate the target key.  Use this if
317          you don't know the introducer.
318       b) "I do not trust" - Use this if you know that the introducer
319          does not do a good job in certifying other keys.  The effect
320          is the same as with a) but for a) you may later want to
321          change the value because you got new information about this
322          introducer.
323       c) "I trust marginally" - Use this if you assume that the
324          introducer knows what he is doing.  Together with some
325          other marginally trusted keys, GnuPG validates the target
326          key then as good.
327       d) "I fully trust" - Use this if you really know that this
328          introducer does a good job when certifying other keys.
329          If all the introducer are of this trust value, GnuPG
330          normally needs only one chain of signatures to validate
331          a target key okay. (But this may be adjusted with the help
332          of some options).
333     This information is confidential because it gives your personal
334     opinion on the trustworthiness of someone else.  Therefore this data
335     is not stored in the keyring but in the "trustdb"
336     (~/.gnupg/trustdb.gpg).  Do not assign a high trust value just
337     because the introducer is a friend of yours - decide how well she
338     understands the implications of key signatures and you may want to
339     tell her more about public key cryptography so you can later change
340     the trust value you assigned.
341
342     Okay, here is how GnuPG helps you with key management.  Most stuff
343     is done with the --edit-key command
344
345         gpg --edit-key <keyid or username>
346
347     GnuPG displays some information about the key and then prompts
348     for a command (enter "help" to see a list of commands and see
349     the man page for a more detailed explanation).  To sign a key
350     you select the user ID you want to sign by entering the number
351     that is displayed in the leftmost column (or do nothing if the
352     key has only one user ID) and then enter the command "sign" and
353     follow all the prompts.  When you are ready, give the command
354     "save" (or use "quit" to cancel your actions).
355
356     If you want to sign the key with another of your user IDs, you
357     must give an "-u" option on the command line together with the
358     "--edit-key".
359
360     Normally you want to sign only one user ID because GnuPG
361     uses only one and this keeps the public key certificate
362     small.  Because such key signatures are very important you
363     should make sure that the signatories of your key sign a user ID
364     which is very likely to stay for a long time - choose one with an
365     email address you have full control of or do not enter an email
366     address at all.  In future GnuPG will have a way to tell which
367     user ID is the one with an email address you prefer - because
368     you have no signatures on this email address it is easy to change
369     this address.  Remember, your signatories sign your public key (the
370     primary one) together with one of your user IDs - so it is not possible
371     to change the user ID later without voiding all the signatures.
372
373     Tip: If you hear about a key signing party on a computer conference
374     join it because this is a very convenient way to get your key
375     certified (But remember that signatures have nothing to to with the
376     trust you assign to a key).
377
378
379     8 Ways to Specify a User ID
380     --------------------------
381     There are several ways to specify a user ID, here are some examples.
382
383     * Only by the short keyid (prepend a zero if it begins with A..F):
384
385         "234567C4"
386         "0F34E556E"
387         "01347A56A"
388         "0xAB123456
389
390     * By a complete keyid:
391
392         "234AABBCC34567C4"
393         "0F323456784E56EAB"
394         "01AB3FED1347A5612"
395         "0x234AABBCC34567C4"
396
397     * By a fingerprint:
398
399         "1234343434343434C434343434343434"
400         "123434343434343C3434343434343734349A3434"
401         "0E12343434343434343434EAB3484343434343434"
402
403       The first one is MD5 the others are ripemd160 or sha1.
404
405     * By an exact string:
406
407         "=Heinrich Heine <heinrichh@uni-duesseldorf.de>"
408
409     * By an email address:
410
411         "<heinrichh@uni-duesseldorf.de>"
412
413     * By word match
414
415         "+Heinrich Heine duesseldorf"
416
417       All words must match exactly (not case sensitive) and appear in
418       any order in the user ID.  Words are any sequences of letters,
419       digits, the underscore and characters with bit 7 set.
420
421     * Or by the usual substring:
422
423         "Heine"
424         "*Heine"
425
426       The '*' indicates substring search explicitly.
427
428
429     Batch mode
430     ----------
431     If you use the option "--batch", GnuPG runs in non-interactive mode and
432     never prompts for input data.  This does not even allow entering the
433     passphrase.  Until we have a better solution (something like ssh-agent),
434     you can use the option "--passphrase-fd n", which works like PGP's
435     PGPPASSFD.
436
437     Batch mode also causes GnuPG to terminate as soon as a BAD signature is
438     detected.
439
440
441     Exit status
442     -----------
443     GnuPG returns with an exit status of 1 if in batch mode and a bad signature
444     has been detected or 2 or higher for all other errors.  You should parse
445     stderr or, better, the output of the fd specified with --status-fd to get
446     detailed information about the errors.
447
448
449     Configure options 
450     -----------------
451     Here is a list of configure options which are sometime useful 
452     for installation.
453
454     --enable-static-rnd=<name> 
455                      Force the use of the random byte gathering
456                      module <name>.  Default is either to use /dev/random
457                      or the auto mode.  Value for name:
458                        egd - Use the module which accesses the
459                              Entropy Gathering Daemon. See the webpages
460                              for more information about it.
461                       unix - Use the standard Unix module which does not
462                              have a very good performance.
463                      linux - Use the module which accesses /dev/random.
464                              This is the first choice and the default one
465                              for GNU/Linux or *BSD.
466                       auto - Compile linux, egd and unix in and 
467                              automagically select at runtime.
468   
469     --with-egd-socket=<name>
470                      This is only used when EGD is used as random
471                      gatherer. GnuPG uses by default "~/.gnupg/entropy"
472                      as the socket to connect EGD.  Using this option the
473                      socket name can be changed.  You may use any filename
474                      here with 2 exceptions:  a filename starting with
475                      "~/" uses the socket in the homedirectory of the user
476                      and one starting with a "=" uses a socket in the
477                      GnuPG homedirectory which is bye default "~/.gnupg".
478    
479      --with-included-zlib
480                      Forces usage of the local zlib sources. Default is
481                      to use the (shared) library of the system.
482
483      --with-included-gettext
484                      Forces usage of the local gettext sources instead of
485                      the one provided by your system.
486
487      --disable-nls
488                      Disable NLS support (See the file ABOUT-NLS)
489
490      --enable-m-guard
491                      Enable the integrated malloc checking code. Please
492                      note that this feature does not work on all CPUs
493                      (e.g. SunOS 5.7 on UltraSparc-2) and might give
494                      you a bus error.
495
496      --disable-dynload 
497                     If you have problems with dynamic loading, this
498                     option disables all dynamic loading stuff.  Note
499                     that the use of dynamic linking is very limited.
500
501      --disable-asm
502                     Do not use assembler modules.  It is not possible 
503                     to use this on some CPU types.
504                     
505      --disable-exec
506                     Disable all remote program execution.  This
507                     disables photo ID viewing as well as all keyserver
508                     types aside from HKP.
509
510      --disable-photo-viewers
511                     Disable only photo ID viewing.
512
513      --disable-keyserver-helpers
514                     Disable only keyserver helpers (not including
515                     HKP).
516
517      --disable-keyserver-path
518                     Disables the user's ability to use the exec-path
519                     feature to add additional search directories when
520                     executing a keyserver helper.
521
522      --with-photo-viewer=FIXED_VIEWER
523                     Force the photo viewer to be FIXED_VIEWER and
524                     disable any ability for the user to change it in
525                     their options file.
526
527      --disable-idea
528      --disable-cast5
529      --disable-blowfish
530      --disable-aes
531      --disable-twofish
532      --disable-sha256
533      --disable-sha512
534                     Removes support for the selected algorithm.  This
535                     can give a smaller gpg binary for places where
536                     space is tight.
537
538                     *** Note, that if there are existing keys that
539                     have one of these algorithms as a preference,
540                     messages may be received that use one of these
541                     algorithms and you will not be able to decrypt the
542                     message! ***
543
544                     A public key preference list can be updated to
545                     match the list of available algorithms by using
546                     'gpg --edit (thekey)', and running the "updpref"
547                     command.
548
549
550     Installation Problems
551     ---------------------
552     If you get unresolved externals "gettext" you should run configure
553     again with the option "--with-included-gettext"; this is version
554     0.10.35 which is available at alpha.gnu.org.
555
556     If you have other compile problems, try the configure options
557     "--with-included-zlib" or "--disable-nls" (See ABOUT-NLS) or
558     --disable-dynload.
559
560     We can't check all assembler files, so if you have problems
561     assembling them (or the program crashes) use --disable-asm with
562     ./configure.  The configure scripts may consider several
563     subdirectories to get all available assembler files; be sure to
564     delete the correct ones. The assembler replacements are in C and
565     in mpi/generic; never delete udiv-qrnnd.S in any CPU directory,
566     because there may be no C substitute.  Don't forget to delete
567     "config.cache" and run "./config.status --recheck".
568
569     Some make tools are broken - the best solution is to use GNU's
570     make.  Try gmake or grab the sources from a GNU archive and
571     install them.
572
573     On some OSF systems you may get unresolved externals.  This is a
574     libtool problem and the workaround is to manually remove all the
575     "-lc -lz" but the last one from the linker line and execute them
576     manually.
577
578     On some architectures you see warnings like:
579       longlong.h:175: warning: function declaration isn't a prototype
580     or
581       http.c:647: warning: cast increases required alignment of target type
582     This doesn't matter and we know about it (actually it is due to
583     some warning options which we have enabled for gcc)
584
585
586     Specific problems on some machines
587     ----------------------------------
588
589     * Apple Darwin 6.1:
590
591         ./configure --with-libiconv-prefix=/sw
592
593     * Compaq C V6.2 for alpha:
594
595         You may want to use the option "-msg-disable ptrmismatch1"
596         to get rid of the sign/unsigned char mismatch warnings.
597
598     * IBM RS/6000 running AIX:
599
600         Due to a change in gcc (since version 2.8) the MPI stuff may
601         not build. In this case try to run configure using:
602             CFLAGS="-g -O2 -mcpu=powerpc" ./configure
603
604     * SVR4.2 (ESIX V4.2 cc)
605
606         Due to problems with the ESIX as, you probably want to do
607             CFLAGS="-O -K pentium" ./configure --disable-asm
608
609
610     The Random Device
611     -----------------
612
613     Random devices are available in Linux, FreeBSD and OpenBSD.
614     Operating systems without a random devices must use another
615     entropy collector. 
616
617     This collector works by running a lot of commands that yield more
618     or less unpredictable output and feds this as entropy into the
619     random generator - It should work reliably but you should check
620     whether it produces good output for your version of Unix. There
621     are some debug options to help you (see cipher/rndunix.c).
622
623
624     Creating an RPM package
625     -----------------------
626     The file scripts/gnupg.spec is used to build a RPM package (both
627     binary and src):
628       1. copy the spec file into /usr/src/redhat/SPECS
629       2. copy the tar file into /usr/src/redhat/SOURCES
630       3. type: rpm -ba SPECS/gnupg.spec
631
632     Or use the -t (--tarbuild) option of rpm:
633       1. rpm -ta gnupg-x.x.x.tar.gz
634
635     The binary rpm file can now be found in /usr/src/redhat/RPMS, source
636     rpm in /usr/src/redhat/SRPMS
637
638
639     How to Get More Information
640     ---------------------------
641
642     The primary WWW page is "http://www.gnupg.org"
643     The primary FTP site is "ftp://ftp.gnupg.org/gcrypt/"
644
645     See http://www.gnupg.org/mirrors.html for a list of mirrors
646     and use them if possible.  You may also find GnuPG mirrored on
647     some of the regular GNU mirrors.
648
649     We have some mailing lists dedicated to GnuPG:
650
651         gnupg-announce@gnupg.org    For important announcements like
652                                     new versions and such stuff.
653                                     This is a moderated list and has
654                                     very low traffic.
655
656         gnupg-users@gnupg.org       For general user discussion and
657                                     help.
658
659         gnupg-devel@gnupg.org       GnuPG developers main forum.
660
661     You subscribe to one of the list by sending mail with a subject
662     of "subscribe" to x-request@gnupg.org, where x is the name of the
663     mailing list (gnupg-announce, gnupg-users, etc.).  An archive of
664     the mailing lists is available at http://lists.gnupg.org .
665
666     Please direct bug reports to <bug-gnupg@gnu.org> or post
667     them direct to the mailing list <gnupg-devel@gnupg.org>.
668
669     Please direct questions about GnuPG to the users mailing list or
670     one of the pgp newsgroups; please do not direct questions to one
671     of the authors directly as we are busy working on improvements
672     and bug fixes.  Both mailing lists are watched by the authors
673     and we try to answer questions when time allows us to do so.
674
675     Commercial grade support for GnuPG is available; please see
676     the GNU service directory or search other resources.
677