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