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