textual changes
[gnupg.git] / README
1
2                   GNUPG - The GNU Privacy Guard
3                  -------------------------------
4                           Version 0.3
5
6
7     As you can see from the version number, the program may have some
8     bugs and some features may not work at all - please report this to
9     the mailing list.
10
11     On a Linux box (version 2.x.x, alpha or x86 CPU) it should
12     work reliably.  You may create your key on such a machine and
13     use it.  Please verify the tar file; there is a PGP and a GNUPG
14     signature available. My PGP key is well known and published in
15     the "Global Trust Register for 1998", ISBN 0-9532397-0-5.
16
17     I have included my pubring as "g10/pubring.asc", which contains
18     the key used to make GNUPG signatures:
19     "pub  1312G/FF3EAA0B 1998-02-09 Werner Koch <wk@isil.d.shuttle.de>"
20     "Key fingerprint = 8489 6CD0 1851 0E33 45DA  CD67 036F 11B8 FF3E AA0B"
21
22     You may add it to your GNUPG pubring and use it in the future to
23     verify new releases.  Because you verified the tar file containing
24     this file here, you can be sure that the above fingerprint is correct.
25
26     Please subscribe to g10@net.lut.ac.uk by sending a mail with
27     the word "subscribe" in the body to "g10-request@net.lut.ac.uk".
28     This mailing is closed (only subscribers can post) to avoid spam.
29
30     See the file COPYING for copyright and warranty information.
31
32     Due to the fact that GNUPG does not use use any patented algorithm,
33     it cannot be compatible with old PGP versions, because those use
34     IDEA (which is patented worldwide) and RSA (which is patented in
35     the United States until Sep 20, 2000).
36
37     GNUPG is in most aspects compatible with other OpenPGP implementations.
38
39     The default algorithms are now DSA and ELGamal.  ELGamal for signing
40     is still available, but due to the larger size of such signatures it
41     is depreciated (Please note that the GNUPG implementation of ElGamal
42     signatures is *not* insecure).  Symmetric algorithms are: Blowfish
43     and CAST5,  Digest algorithms are MD5, RIPEMD160, SHA1 and TIGER/192.
44
45
46
47     Installation
48     ------------
49
50     See the file INSTALL.  Here is a quick summary:
51
52     1)  "./configure"
53
54     2) "make"
55
56     3) "make install"
57
58     4) You end up with a binary "gpg" in /usr/local/bin
59
60     5) Optional, but suggested: install the program "gpg" as suid root.
61
62
63
64     Key Generation
65     --------------
66
67         gpg --gen-key
68
69     This asks some questions and then starts key generation. To create
70     good random numbers for prime number generation, it uses a /dev/random
71     which will only emit bytes if the kernel can gather enough entropy.
72     If you see no progress, you should start some other activities such
73     as mouse moves, "find /" or using the keyboard (in another window).
74     Because we have no hardware device to generate randomness we have to
75     use this method.
76
77     You should make a revocation certificate in case someone gets
78     knowledge of your secret key or you forgot your passphrase:
79
80         gpg --gen-revoke your_user_id
81
82     Run this command and store it away; output is always ASCII armored,
83     so that you can print it and (hopefully never) re-create it if
84     your electronic media fails.
85
86     If you decided to create a DSA key, you should add an ElGamal
87     for encryption:
88
89         gpg --add-key user_id_of_your_key
90
91     and follow the displayed instructions (select "ElGamal using v4 packets").
92
93
94     You can sign a key with this command:
95
96         gpg --sign-key Donald
97
98     This let you sign the key of "Donald" with your default userid.
99
100         gpg --sign-key -u Karl -u Joe Donald
101
102     This let you sign the key of of "Donald" with the userids of "Karl"
103     and "Joe".
104     All existing signatures are checked; if some are invalid, a menu is
105     offered to delete some of them, and then you are asked for every user
106     whether you want to sign this key.
107
108     You may remove a signature at any time using the option "--edit-sig",
109     which asks for the sigs to remove.  Self-signatures are not removable.
110
111
112
113
114     Sign
115     ----
116
117         gpg -s file
118
119     This creates a file file.gpg which is compressed and has a signature
120     attached.
121
122         gpg -sa file
123
124     Same as above, but file.gpg is ascii armored.
125
126         gpg -s -o out file
127
128     Creates a signature of file, but writes the output to the file "out".
129
130
131     Encrypt
132     -------
133
134         gpg -e -r heine file
135
136     This encrypts files with the public key of "heine" and writes it
137     to "file.gpg"
138
139         echo "hallo" | gpg -ea -r heine | mail heine
140
141     Ditto, but encrypts "hallo\n" and mails it as ascii armored message.
142
143
144     Sign and Encrypt
145     ----------------
146
147         gpg -se -r heine file
148
149     This encrypts files with the public key of "heine" and writes it
150     to "file.gpg" after signing it with the default user id.
151
152
153         gpg -se -r heine -u Suttner file
154
155     Ditto, but sign the file with the user id "Suttner"
156
157
158     Keyring Management
159     ------------------
160     To export your complete keyring(s) do this:
161
162         gpg --export
163
164     To export only some user ids do this:
165
166         gpg --export userids
167
168     Use "-a" or "--armor" to create ASCII armored output.
169
170     Importing keys is done with the option, you guessed it, "--import":
171
172         gpg --import [filenames]
173
174     New keys are appended to the default keyring and already existing
175     keys are merged.  Keys without a self-signature are ignored.
176
177
178     How to Specify a UserID
179     -----------------------
180     There are several ways to specify a userID, here are some examples:
181
182     * Only by the short keyid (prepend a zero if it begins with A..F):
183
184         "234567C4"
185         "0F34E556E"
186         "01347A56A"
187         "0xAB123456
188
189     * By a complete keyid:
190
191         "234AABBCC34567C4"
192         "0F323456784E56EAB"
193         "01AB3FED1347A5612"
194         "0x234AABBCC34567C4"
195
196     * By a fingerprint:
197
198         "1234343434343434C434343434343434"
199         "123434343434343C3434343434343734349A3434"
200         "0E12343434343434343434EAB3484343434343434"
201
202       The first one is MD5 the others are ripemd160 or sha1.
203
204     * By an exact string (not yet implemented):
205
206         "=Heinrich Heine <heinrichh@uni-duesseldorf.de>"
207
208     * By an email address:
209
210         "<heinrichh@uni-duesseldorf.de>"
211
212       This can be used by a keyserver instead of a substring to
213       find this key faster.
214
215     * By the Local ID (from the trustdb):
216
217         "#34"
218
219       This can be used by a MUA to specify an exact key after selecting
220       a key from GNUPG (by the use of a special option or an extra utility)
221
222
223     * Or by the usual substring:
224
225         "Heine"
226         "*Heine"
227
228       The '*' indicates substring search explicitly.
229
230
231
232
233     Batch mode
234     ----------
235     If you use the option "--batch", GNUPG runs in non-interactive mode and
236     never prompts for input data.  This does not even allow entering the
237     passphrase; until we have a better solution (something like ssh-agent),
238     you can use the option "--passhrase-fd n", which works like PGPs
239     PGPPASSFD.
240
241     Batch mode also causes GNUPG to terminate as soon as a BAD signature is
242     detected.
243
244
245     Exit status
246     -----------
247     GNUPG returns with an exit status of 1 if in batch mode and a bad signature
248     has been detected or 2 or higher for all other errors.  You should parse
249     stderr or the output of the fd specified with --status-fd to get detailed
250     information about the errors.
251
252
253     Esoteric commands
254     -----------------
255
256         gpg --list-packets datafile
257
258     Use this to list the contents of a data file. If the file is encrypted
259     you are asked for the passphrase, so that GNUPG is able to look at the
260     inner structure of a encrypted packet.
261
262         gpgm --list-trustdb
263
264     List the contents of the trustdb in a human readable format
265
266         gpgm --list-trustdb  <usernames>
267
268     List the tree of certificates for the given usernames
269
270         gpgm --list-trust-path  depth  username
271
272     List the possible trust paths for the given username, up to the specified
273     depth.  If depth is negative, duplicate introducers are not listed,
274     because those would increase the trust probability only minimally.
275     (you must use the special option "--" to stop option parsing when
276      using a negative number). This option may create new entries in the
277     trustdb.
278
279         gpgm --print-mds  filenames
280
281     List all available message digest values for the fiven filenames
282
283         gpgm --gen-prime n
284
285     Generate and print a simple prime number of size n
286
287         gpgm --gen-prime n q
288
289     Generate a prime number suitable for ElGamal signatures of size n with
290     a q as largest prime factor of n-1.
291
292         gpgm --gen-prime n q 1
293
294     Ditto, but calculate a generator too.
295
296
297     For more options/commands see the file g10/OPTIONS, or use "gpg --help"
298
299
300     Debug Flags
301     -----------
302     Use the option "--debug n" to output debug information. This option
303     can be used multiple times, all values are ORed; n maybe prefixed with
304     0x to use hex-values.
305
306          value  used for
307          -----  ----------------------------------------------
308           1     packet reading/writing
309           2     MPI details
310           4     ciphers and primes (may reveal sensitive data)
311           8     iobuf filter functions
312           16    iobuf stuff
313           32    memory allocation stuff
314           64    caching
315           128   show memory statistics at exit
316           256   trust verification stuff
317
318
319     Other Notes
320     -----------
321     This is work in progress, so you may find duplicated code fragments,
322     ugly data structures, weird usage of filenames and other things.
323
324     The primary FTP site is "ftp://ftp.guug.de/pub/gcrypt/"
325     The primary WWW page is "http://www.d.shuttle.de/isil/crypt/gnupg.html"
326
327     If you like, send your keys to <gnupg-keys@isil.d.shuttle.de>; use
328     "gpg --export --armor | mail gnupg-keys@isil.d.shuttle.de" to do this.
329
330     Please direct bug reports to <gnupg-bugs@gnu.org> or better
331     post them to the mailing list <g10@net.lut.ac.uk> (this is a closed list,
332     please subscribe before posting).
333
334