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