See ChangeLog: Thu Sep 2 16:40:55 CEST 1999 Werner Koch
[gnupg.git] / README
1 -----BEGIN PGP SIGNED MESSAGE-----
2
3                     GnuPG - The GNU Privacy Guard
4                    -------------------------------
5                            Version 0.9.11
6
7     GnuPG is a tool for secure communication and data storage.  It
8     can be used to encrypt data and to create digital signatures.
9     It includes an advanced key management facility and is compliant
10     to the proposed OpenPGP Internet standard as described in RFC2440.
11
12     GnuPG is now in Beta test and you should report all bugs to the
13     mailing list (see below).  The 0.9.x versions are released mainly
14     to fix all remaining serious bugs.  As soon as version 1.0 is out,
15     development will continue with a 1.1 series and bug fixes for the
16     1.0 version as needed.
17
18     GnuPG works best on GNU/Linux or *BSD.  Other Unices are
19     also supported but are not as well tested as the Free Unices.
20
21     See the file COPYING for copyright and warranty information.
22
23     Because GnuPG does not use use any patented algorithm it cannot be
24     compatible with PGP2 versions.  PGP 2.x uses only IDEA (which is
25     patented worldwide) and RSA (which is patented in the United States
26     until Sep 20, 2000).
27
28     The default algorithms are DSA and ElGamal.  ElGamal for signing
29     is still available, but because of the larger size of such
30     signatures it is deprecated (Please note that the GnuPG
31     implementation of ElGamal signatures is *not* insecure).  Symmetric
32     algorithms are: 3DES, Blowfish, CAST5 and Twofish (GnuPG does not
33     yet create Twofish encrypted messages because there is no agreement
34     in the OpenPGP WG on how to use it together with a MDC algorithm)
35     Digest algorithms available are MD5, RIPEMD160, SHA1, and TIGER/192.
36
37
38     Installation
39     ------------
40
41     Please read the file INSTALL!
42
43     Here is a quick summary:
44
45     1) Check that you have unmodified sources.  The below on how to do this.
46        Don't skip it - this is an important step!
47
48     2)  Unpack the TAR.  With GNU tar you can do it this way:
49         "tar xzvf gnupg-x.y.z.tar.gz"
50
51     3) "cd gnupg-x.y.z"
52
53     4)  "./configure"
54
55     5) "make"
56
57     6) "make install"
58
59     7) You end up with a "gpg" binary in /usr/local/bin.
60        Note: Because some old programs rely on the existence of a
61        binary named "gpgm"; you should install a symbolic link
62        from gpgm to gpg:
63         "cd /usr/local/bin; ln -s gpg gpgm"
64
65     8) To avoid swapping out of sensitive data, you can install "gpg" as
66        suid root.  If you don't do so, you may want to add the option
67        "no-secmem-warning" to ~/.gnupg/options
68
69
70     How to Verify the Source
71     ------------------------
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 g10/pubring.asc (use "gpg --import g10/pubring.gpg" to
90        add it to the keyring) or from any keyserver.  You have to make
91        sure that this is really the key and not a faked one. You can do
92        this by comparing the output of:
93
94                 $ gpg --fingerprint 0x57548DCD
95
96        with the elsewhere published fingerprint, or - if you are able to
97        _positively_ verify the signature of this README file - with
98        this fingerprint: "6BD9 050F D8FC 941B 4341  2DCC 68B7 AB89 5754 8DCD"
99
100        Please note, that you have to use an old version of GnuPG to
101        do all this stuff.  *Never* use the version which you are going
102        to check!
103
104
105     b) If you have a trusted Version of PGP 2 or 5 installed, you
106        can check the supplied PGP 2 signature:
107
108         $ pgp gnupg-x.y.z.tar.gz.sig gnupg-x.y.z.tar.gz
109
110        This checks that the detached signature gnupg-x.y.z.tar.gz.sig
111        is indeed a a signature of gnupg-x.y.z.tar.gz.  Please note,
112        that this signature has been created with a RSA signature and
113        you probably can't use this method (due to legal reasons) when
114        you are in the U.S.  The key used to create this signature is
115        the same as the one used to sign this README file.  It should be
116        available at the keyservers and is also included in the source
117        of GnuPG in g10/pubring.asc.
118
119        "pub   768R/0C9857A5 1995-09-30 Werner Koch <werner.koch@guug.de>"
120
121        The fingerprint of this key is published in printed form in the
122           "Global Trust Register for 1998", ISBN 0-9532397-0-5.
123
124
125     c) If you don't have any of the above programs, you have to verify
126        the MD5 checksum:
127
128         $ md5sum gnupg-x.y.z.tar.gz.sig
129
130        This should yield an output similar to this:
131
132         fd9351b26b3189c1d577f0970f9dcadc  gnupg-x.y.z.tar.gz
133
134        Now check that this checksum is _exactly_ the same as the one
135        published via the announcement list and probably via Usenet.
136
137
138     Introduction
139     ------------
140
141     A draft version of the manual is included in the subdirectory doc
142     and some HOWTO documents are available online; dor a listing see:
143
144         http://www.gnupg.org/docs.html#howtos
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 results require that YOU
149     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     * By the Local ID (from the trust DB):
428
429         "#34"
430
431       This may be used by a MUA to specify an exact key after selecting
432       a key from GnuPG (by using a special option or an extra utility)
433
434     * Or by the usual substring:
435
436         "Heine"
437         "*Heine"
438
439       The '*' indicates substring search explicitly.
440
441
442     Batch mode
443     ----------
444     If you use the option "--batch", GnuPG runs in non-interactive mode and
445     never prompts for input data.  This does not even allow entering the
446     passphrase.  Until we have a better solution (something like ssh-agent),
447     you can use the option "--passphrase-fd n", which works like PGP's
448     PGPPASSFD.
449
450     Batch mode also causes GnuPG to terminate as soon as a BAD signature is
451     detected.
452
453
454     Exit status
455     -----------
456     GnuPG returns with an exit status of 1 if in batch mode and a bad signature
457     has been detected or 2 or higher for all other errors.  You should parse
458     stderr or, better, the output of the fd specified with --status-fd to get
459     detailed information about the errors.
460
461
462     Esoteric commands
463     -----------------
464
465         gpg --list-packets datafile
466
467     Use this to list the contents of a data file. If the file is encrypted
468     you are asked for the passphrase, so that GnuPG is able to look at the
469     inner structure of a encrypted packet.  This command should list all
470     kinds of rfc2440 messages.
471
472         gpg --list-trustdb
473
474     List the contents of the trust DB in a human readable format
475
476         gpg --list-trustdb  <usernames>
477
478     List the tree of certificates for the given usernames
479
480         gpg --list-trust-path  username
481
482     List the possible trust paths for the given username. The length
483     of such a trust path is limited by the option --max-cert-depth
484     which defaults to 5.
485
486     For more options/commands see the man page or use "gpg --help".
487
488
489     Other Notes
490     -----------
491
492     The primary FTP site is "ftp://ftp.gnupg.org/pub/gcrypt/"
493     The primary WWW page is "http://www.gnupg.org"
494
495     See http://www.gnupg.org/mirrors.html for a list of FTP mirrors
496     and use them if possible.
497
498     We have some mailing lists dedicated to GnuPG:
499
500         gnupg-announce@gnupg.org    For important announcements like
501                                     new versions and  such stuff.
502                                     This is a moderated list and has
503                                     very low traffic.
504         gnupg-users@gnupg.org       For general user discussion and
505                                     help.
506         gnupg-devel@gnupg.org       GnuPG developers main forum.
507
508     You subscribe to one of the list by sending mail with a subject
509     of "subscribe" to x-request@gnupg.org, where x is the name of the
510     mailing list (gnupg-announce, gnupg-users, etc.).  An archive of
511     the mailing lists is available at http://lists.gnupg.org .
512
513     The gnupg.org domain is hosted in Germany to avoid possible legal
514     problems (technical advices may count as a violation of ITAR).
515
516     Please direct bug reports to <gnupg-bugs@gnu.org> or post
517     them direct to the mailing list <gnupg-devel@gnupg.org>.
518     Please direct questions about GnuPG to the users mailing list or
519     one of the pgp newsgroups to give me more time to improve
520     GnuPG.  Commercial support for GnuPG is also available; please
521     see the GNU service directory or search other resources.
522
523     Have fun and remember: Echelon is looking at you kid.
524
525 -----BEGIN PGP SIGNATURE-----
526 Version: GnuPG v0.9.10 (GNU/Linux)
527 Comment: For info see http://www.gnupg.org
528
529 iQB1AwUBN86L1h0Z9MEMmFelAQFQlQL/S5jDPpDFI3wDG/soA/qMTR79YX1IXDz9
530 Izin49GkPHElRCoNbT3r3+T6V+lNtrZpah6JBR30//yo1OGUyoJ88yn3KC0JdtUq
531 NgJzX3yYUXD+Ojer+WHEL+O8D8qkZrAX
532 =wiUu
533 -----END PGP SIGNATURE-----