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