Ready to test version 0.2.0
[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     Batch mode
164     ----------
165     If you use the option "--batch", G10 runs in non-interactive mode and
166     never prompts for input data.  This even does not allow to enter
167     passphrase; until we have a better solution (something like ssh-agent),
168     you can use the option "--passhrase-fd n", which works like PGPs
169     PGPPASSFD.
170
171     Batch mode also causes G10 to terminate as soon as a BAD signature is
172     detected.
173
174
175     Exit status
176     -----------
177     G10 returns with an exit status of 1 if in batch mode and a bad signature
178     has been detected or 2 or higher for all other errors.  You should parse
179     stderr to get detailed informations about the errors.
180
181
182     Esoteric commands
183     -----------------
184
185         g10 --list-packets datafile
186
187     Use this to list the contents of a data file. If the file is encrypted
188     you are asked for the passphrase, so that G10 is able to look at the
189     inner structure of a encrypted packet.
190
191         --quick-random
192
193     Do not use the stroing random generator but a faster one.  This can be
194     used to generate keys for tests; those are marked as insecure.
195
196         --list-trustdb
197
198     List the contents of the trustdb in a human readable format
199
200         --list-trustdb  <usernames>
201
202     List the tree of certificates for the given usernames
203
204         --list-trust-path  depth  username
205
206     List the possible trust paths for the given username, up to the specified
207     depth.  If depth is negative, duplicate introducers are not listed,
208     because those would increase the trust probabilty only minimal.
209     (you must use the special option "--" to stop option parsing when
210      using a negative number). This option may create new entries in the
211     trustdb.
212
213         --print-mds  filenames
214
215     List all available message digest values for the fiven filenames
216
217         --gen-prime n
218
219     Generate and print a simple prime number of size n
220
221         --gen-prime n q
222
223     Generate a prime number suitable for ElGamal signatures of size n with
224     a q as largest primefactor of n-1.
225
226         --gen-prime n q 1
227
228     Ditto, but calculate a generator too.
229
230
231     For more options/commands see the file g10/OPTIONS.
232
233
234     Debug Flags
235     -----------
236     Use the option "--debug n" to output debug informations. This option
237     can be used multiple times, all values are ORed; n maybe prefixed with
238     0x to use hex-values.
239
240          value  used for
241          -----  ----------------------------------------------
242           1     packet reading/writing
243           2     MPI details
244           4     ciphers and primes (may reveal sensitive data)
245           8     iobuf filter functions
246           16    iobuf stuff
247           32    memory allocation stuff
248           64    caching
249           128   show memory statistics at exit
250           256   trust verification stuff
251
252
253     Other Notes
254     -----------
255     This is work in progress, so you may find duplicated code fragments,
256     ugly data structures, weird usage of filenames and other thinks.
257     I will run "indent" over the source when making a real distribution,
258     but for now I stick to my own formatting rules.
259
260     The primary FTP site is "ftp://ftp.guug.de/pub/gcrypt/"
261     The primary WWW page is "http://www.d.shuttle.de/isil/g10.html"
262
263     Please direct bug reports to <g10-bugs@isil.d.shuttle.de> or better
264     post them to the mailing list <g10@net.lut.ac.uk>.
265
266