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