See ChangeLog: Fri Apr 9 12:26:25 CEST 1999 Werner Koch
[libgcrypt.git] / README
1 Please note that this is only a bug fix release and some things
2 do not yet work - see TODO for parts which are problematic
3
4
5
6 -----BEGIN PGP SIGNED MESSAGE-----
7
8                     GnuPG - The GNU Privacy Guard
9                    -------------------------------
10                             Version 0.9
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     Please verify the tar file with the PGP2 or GnuPG/PGP5
21     signatures provided.  My PGP2 key is well known and published in
22     the "Global Trust Register for 1998", ISBN 0-9532397-0-5.
23
24     I have included my pubring as "g10/pubring.asc", which contains
25     the key used to make GnuPG signatures:
26     "pub  1024D/57548DCD 1998-07-07 Werner Koch (gnupg sig) <dd9jn@gnu.org>"
27     "Key fingerprint = 6BD9 050F D8FC 941B 4341  2DCC 68B7 AB89 5754 8DCD"
28
29     My new DSA key is:
30     "pub  1024D/621CC013 1998-07-07 Werner Koch <werner.koch@guug.de>"
31     "Key fingerprint = ECAF 7590 EB34 43B5 C7CF  3ACB 6C7E E1B8 621C C013"
32
33     You may want add my new DSA key to your GnuPG pubring and use it in
34     the future to verify new releases.  Because you verified this README
35     file and _checked_that_it_is_really_my PGP2 key 0C9857A5, you can be
36     sure that the above fingerprints are correct.
37
38     Please subscribe to g10@net.lut.ac.uk by sending a mail with
39     the word "subscribe" in the body to "g10-request@net.lut.ac.uk".
40     This mailing list is closed (only subscribers are allowed to post)
41     to avoid misuse by folks who don't know the Netiquette and trash
42     your mailspool with commercial junk.
43
44     See the file COPYING for copyright and warranty information.
45
46     GnuPG is in compliance with RFC2440 (OpenPGP), see doc/OpenPGP for
47     details.
48
49     Because GnuPG does not use use any patented algorithm it cannot be
50     compatible with PGP2 versions.  PGP 2.x uses only IDEA (which is
51     patented worldwide) and RSA (which is patented in the United States
52     until Sep 20, 2000).
53
54     The default algorithms are now DSA and ElGamal.  ElGamal for signing
55     is still available, but because of the larger size of such
56     signatures it is deprecated (Please note that the GnuPG
57     implementation of ElGamal signatures is *not* insecure).  Symmetric
58     algorithms are: 3DES, Blowfish, and CAST5 (Twofish will come soon).
59     Digest algorithms available are MD5, RIPEMD160, SHA1, and TIGER/192.
60
61
62     Installation
63     ------------
64
65     Please read the file INSTALL!
66
67     Here is a quick summary:
68
69     1)  "./configure"
70
71     2) "make"
72
73     3) "make install"
74
75     4) You end up with the binaries "gpg" and "gpgm" in /usr/local/bin.
76
77     5) Optional, but suggested, install the binary "gpg" as suid root.
78
79
80
81     Introduction
82     ------------
83
84     This is a brief overview how to use GnuPG - it is strongly suggested
85     that you read the manual^H^H^H more information about the use of
86     cryptography.  GnuPG is only a tool, secure results require that YOU
87     KNOW WHAT YOU ARE DOING.
88
89     If you already have a DSA key from PGP 5 (they call them DH/ElGamal)
90     you can simply copy the pgp keyrings over the GnuPG keyrings after
91     running gpg once to create the correct directory.
92
93     The normal way to create a key is
94
95         gpg --gen-key
96
97     This asks some questions and then starts key generation. To create
98     good random numbers for the key parameters, GnuPG needs to gather
99     enough noise (entropy) from your system.  If you see no progress
100     during key generation you should start some other activities such
101     as mouse moves or hitting on the CTRL and SHIFT keys.
102
103     Generate a key ONLY on a machine where you have direct physical
104     access - don't do it over the network or on a machine used also
105     by others - especially if you have no access to the root account.
106
107     When you are asked for a passphrase use a good one which you can
108     easy remember.  Don't make the passphrase too long because you have
109     to type it for every decryption or signing; but, - AND THIS IS VERY
110     IMPORTANT - use a good one that is not easily to guess because the
111     security of the whole system relies on your secret key and the
112     passphrase that protects it when someone gains access to your secret
113     keyring.  A good way to select a passphrase is to figure out a short
114     nonsense sentence which makes some sense for you and modify it by
115     inserting extra spaces, non-letters and changing the case of some
116     characters - this is really easy to remember especially if you
117     associate some pictures with it.
118
119     Next, you should create a revocation certificate in case someone
120     gets knowledge of your secret key or you forgot your passphrase
121
122         gpg --gen-revoke your_user_id
123
124     Run this command and store the revocation certificate away.  The output
125     is always ASCII armored, so that you can print it and (hopefully
126     never) re-create it if your electronic media fails.
127
128     Now you can use your key to create digital signatures
129
130         gpg -s file
131
132     This creates a file "file.gpg" which is compressed and has a
133     signature attached.
134
135         gpg -sa file
136
137     Same as above, but creates a file "file.asc" which is ASCII armored
138     and and ready for sending by mail.  It is better to use your
139     mailers features to create signatures (The mailer uses GnuPG to do
140     this) because the mailer has the ability to MIME encode such
141     signatures - but this is not a security issue.
142
143         gpg -s -o out file
144
145     Creates a signature of "file", but writes the output to the file
146     "out".
147
148     Everyone who knows your public key (you can and should publish
149     your key by putting it on a key server, a web page or in your .plan
150     file) is now able to check whether you really signed this text
151
152         gpg --verify file
153
154     GnuPG now checks whether the signature is valid and prints an
155     appropriate message.  If the signature is good, you know at least
156     that the person (or machine) has access to the secret key which
157     corresponds to the published public key.
158
159     If you run gpg without an option it will verify the signature and
160     create a new file that is identical to the original.  gpg can also
161     run as a filter, so that you can pipe data to verify trough it
162
163         cat signed-file | gpg | wc -l
164
165     which will check the signature of signed-file and then display the
166     number of lines in the original file.
167
168     To send a message encrypted to someone you can use
169
170         gpg -e -r heine file
171
172     This encrypts "file" with the public key of the user "heine" and
173     writes it to "file.gpg"
174
175         echo "hello" | gpg -ea -r heine | mail heine
176
177     Ditto, but encrypts "hello\n" and mails it as ASCII armored message
178     to the user with the mail address heine.
179
180         gpg -se -r heine file
181
182     This encrypts "file" with the public key of "heine" and writes it
183     to "file.gpg" after signing it with your user id.
184
185         gpg -se -r heine -u Suttner file
186
187     Ditto, but sign the file with your alternative user id "Suttner"
188
189
190     GnuPG has some options to help you publish public keys.  This is
191     called "exporting" a key, thus
192
193         gpg --export >all-my-keys
194
195     exports all the keys in the keyring and writes them (in a binary
196     format) to "all-my-keys".  You may then mail "all-my-keys" as an
197     MIME attachment to someone else or put it on an FTP server. To
198     export only some user IDs, you give them as arguments on the command
199     line.
200
201     To mail a public key or put it on a web page you have to create
202     the key in ASCII armored format
203
204         gpg --export --armor | mail panther@tiger.int
205
206     This will send all your public keys to your friend panther.
207
208     If you have received a key from someone else you can put it
209     into your public keyring.  This is called "importing"
210
211         gpg --import [filenames]
212
213     New keys are appended to your keyring and already existing
214     keys are updated. Note that GnuPG does not import keys that
215     are not self-signed.
216
217     Because anyone can claim that a public key belongs to her
218     we must have some way to check that a public key really belongs
219     to the owner.  This can be achieved by comparing the key during
220     a phone call.  Sure, it is not very easy to compare a binary file
221     by reading the complete hex dump of the file - GnuPG (and nearly
222     every other program used for management of cryptographic keys)
223     provides other solutions.
224
225         gpg --fingerprint <username>
226
227     prints the so called "fingerprint" of the given username which
228     is a sequence of hex bytes (which you may have noticed in mail
229     sigs or on business cards) that uniquely identifies the public
230     key - different keys will always have different fingerprints.
231     It is easy to compare fingerprints by phone and I suggest
232     that you print your fingerprint on the back of your business
233     card.
234
235     If you don't know the owner of the public key you are in trouble.
236     Suppose however that friend of yours knows someone who knows someone
237     who has met the owner of the public key at some computer conference.
238     Suppose that all the people between you and the public key holder
239     may now act as introducers to you.  Introducers signing keys thereby
240     certify that they know the owner of the keys they sign.  If you then
241     trust all the introducers to have correctly signed other keys, you
242     can be be sure that the other key really belongs to the one who
243     claims to own it..
244
245     There are 2 steps to validate a key:
246         1. First check that there is a complete chain
247            of signed keys from the public key you want to use
248            and your key and verify each signature.
249         2. Make sure that you have full trust in the certificates
250            of all the introduces between the public key holder and
251            you.
252     Step 2 is the more complicated part because there is no easy way
253     for a computer to decide who is trustworthy and who is not.  GnuPG
254     leaves this decision to you and will ask you for a trust value
255     (here also referenced as the owner-trust of a key) for every key
256     needed to check the chain of certificates.  You may choose from:
257       a) "I don't know" - then it is not possible to use any
258          of the chains of certificates, in which this key is used
259          as an introducer, to validate the target key.  Use this if
260          you don't know the introducer.
261       b) "I do not trust" - Use this if you know that the introducer
262          does not do a good job in certifying other keys.  The effect
263          is the same as with a) but for a) you may later want to
264          change the value because you got new information about this
265          introducer.
266       c) "I trust marginally" - Use this if you assume that the
267          introducer knows what he is doing.  Together with some
268          other marginally trusted keys, GnuPG validates the target
269          key then as good.
270       d) "I fully trust" - Use this if you really know that this
271          introducer does a good job when certifying other keys.
272          If all the introducer are of this trust value, GnuPG
273          normally needs only one chain of signatures to validate
274          a target key okay. (But this may be adjusted with the help
275          of some options).
276     This information is confidential because it gives your personal
277     opinion on the trustworthiness of someone else.  Therefore this data
278     is not stored in the keyring but in the "trustdb"
279     (~/.gnupg/trustdb.gpg).  Do not assign a high trust value just
280     because the introducer is a friend of yours - decide how well she
281     understands the implications of key signatures and you may want to
282     tell her more about public key cryptography so you can later change
283     the trust value you assigned.
284
285     Okay, here is how GnuPG helps you with key management.  Most stuff
286     is done with the --edit-key command
287
288         gpg --edit-key <keyid or username>
289
290     GnuPG displays some information about the key and then prompts
291     for a command (enter "help" to see a list of commands and see
292     the man page for a more detailed explanation).  To sign a key
293     you select the user ID you want to sign by entering the number
294     that is displayed in the leftmost column (or do nothing if the
295     key has only one user ID) and then enter the command "sign" and
296     follow all the prompts.  When you are ready, give the command
297     "save" (or use "quit" to cancel your actions).
298
299     If you want to sign the key with another of your user IDs, you
300     must give an "-u" option on the command line together with the
301     "--edit-key".
302
303     Normally you want to sign only one user ID because GnuPG
304     uses only one and this keeps the public key certificate
305     small.  Because such key signatures are very important you
306     should make sure that the signatories of your key sign a user ID
307     which is very likely to stay for a long time - choose one with an
308     email address you have full control of or do not enter an email
309     address at all.  In future GnuPG will have a way to tell which
310     user ID is the one with an email address you prefer - because
311     you have no signatures on this email address it is easy to change
312     this address.  Remember, your signatories sign your public key (the
313     primary one) together with one of your user IDs - so it is not possible
314     to change the user ID later without voiding all the signatures.
315
316     Tip: If you hear about a key signing party on a computer conference
317     join it because this is a very convenient way to get your key
318     certified (But remember that signatures have nothing to to with the
319     trust you assign to a key).
320
321
322     8 Ways to Specify a User ID
323     --------------------------
324     There are several ways to specify a user ID, here are some examples.
325
326     * Only by the short keyid (prepend a zero if it begins with A..F):
327
328         "234567C4"
329         "0F34E556E"
330         "01347A56A"
331         "0xAB123456
332
333     * By a complete keyid:
334
335         "234AABBCC34567C4"
336         "0F323456784E56EAB"
337         "01AB3FED1347A5612"
338         "0x234AABBCC34567C4"
339
340     * By a fingerprint:
341
342         "1234343434343434C434343434343434"
343         "123434343434343C3434343434343734349A3434"
344         "0E12343434343434343434EAB3484343434343434"
345
346       The first one is MD5 the others are ripemd160 or sha1.
347
348     * By an exact string:
349
350         "=Heinrich Heine <heinrichh@uni-duesseldorf.de>"
351
352     * By an email address:
353
354         "<heinrichh@uni-duesseldorf.de>"
355
356     * By word match
357
358         "+Heinrich Heine duesseldorf"
359
360       All words must match excatly (not case sensitive) and appear in
361       any order in the user ID.  Words are any sequences of letters,
362       digits, the underscore and characters with bit 7 set.
363
364     * By the Local ID (from the trust DB):
365
366         "#34"
367
368       This may be used by a MUA to specify an exact key after selecting
369       a key from GnuPG (by using a special option or an extra utility)
370
371     * Or by the usual substring:
372
373         "Heine"
374         "*Heine"
375
376       The '*' indicates substring search explicitly.
377
378
379     Batch mode
380     ----------
381     If you use the option "--batch", GnuPG runs in non-interactive mode and
382     never prompts for input data.  This does not even allow entering the
383     passphrase.  Until we have a better solution (something like ssh-agent),
384     you can use the option "--passphrase-fd n", which works like PGPs
385     PGPPASSFD.
386
387     Batch mode also causes GnuPG to terminate as soon as a BAD signature is
388     detected.
389
390
391     Exit status
392     -----------
393     GnuPG returns with an exit status of 1 if in batch mode and a bad signature
394     has been detected or 2 or higher for all other errors.  You should parse
395     stderr or, better, the output of the fd specified with --status-fd to get
396     detailed information about the errors.
397
398
399     Esoteric commands
400     -----------------
401
402         gpg --list-packets datafile
403
404     Use this to list the contents of a data file. If the file is encrypted
405     you are asked for the passphrase, so that GnuPG is able to look at the
406     inner structure of a encrypted packet.  This command should list all
407     kinds of rfc2440 messages.
408
409         gpgm --list-trustdb
410
411     List the contents of the trust DB in a human readable format
412
413         gpgm --list-trustdb  <usernames>
414
415     List the tree of certificates for the given usernames
416
417         gpgm --list-trust-path  username
418
419     List the possible trust paths for the given username. The length
420     of such a trust path is limited by the option --max-cert-depth
421     which defaults to 5.
422
423     For more options/commands see the man page or use "gpg --help".
424
425
426     Other Notes
427     -----------
428
429     The primary FTP site is "ftp://ftp.gnupg.org/pub/gcrypt/"
430     The primary WWW page is "http://www.gnupg.org"
431
432     See http://www.gnupg.org/mirrors.html for a list of FTP mirrors
433     and use them if possible.
434
435     Please direct bug reports to <gnupg-bugs@gnu.org> or, better,
436     post them to the mailing list <g10@net.lut.ac.uk> (this is a
437     closed list - subscribe before posting, see above (~line 33)).
438     Please direct questions about GnuPG to the mailing list or
439     one of the pgp newsgroups and give me more time to improve
440     GnuPG.  Commercial support for GnuPG will be available soon.
441
442     Have fun and remember: Echelon is looking at you kid.
443
444 -----BEGIN PGP SIGNATURE-----
445 Version: GnuPG v0.9.2 (GNU/Linux)
446 Comment: For info see http://www.gnupg.org
447
448 iQB1AwUBNr2fPh0Z9MEMmFelAQHqNAL/e7pApR0CGUJ/zuIsjaVhNGPEgKAglcEd
449 YuVdB+RCN0wq7ZfI0AHU2FdVISRACmSN3xituTTgeiOUsczM40EZ4l1XNfyRF768
450 fglui6XxEeYHFY7mSQMgzzFWDG0Squx0
451 =enRo
452 -----END PGP SIGNATURE-----