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