fixed severe exploit
[gnupg.git] / doc / DETAILS
1
2
3     * For packet version 3 we calculate the keyids this way:
4         RSA     := low 64 bits of n
5         ELGAMAL := build a v3 pubkey packet (with CTB 0x99) and calculate
6                    a rmd160 hash value from it. This is used as the
7                    fingerprint and the low 64 bits are the keyid.
8
9     * Revocation certificates consist only of the signature packet;
10       "import" knows how to handle this.  The rationale behind it is
11       to keep them small.
12
13
14     Key generation shows progress by printing different characters to
15     stderr:
16              "."  Last 10 Miller-Rabin tests failed
17              "+"  Miller-Rabin test succeeded
18              "!"  Reloading the pool with fresh prime numbers
19              "^"  Checking a new value for the generator
20              "<"  Size of one factor decreased
21              ">"  Size of one factor increased
22
23     The prime number for ElGamal is generated this way:
24
25     1) Make a prime number q of 160, 200, 240 bits (depending on the keysize)
26     2) Select the length of the other prime factors to be at least the size
27        of q and calculate the number of prime factors needed
28     3) Make a pool of prime numbers, each of the length determined in step 2
29     4) Get a new permutation out of the pool or continue with step 3
30        if we have tested all permutations.
31     5) Calculate a candidate prime p = 2 * q * p[1] * ... * p[n] + 1
32     6) Check that this prime has the correct length (this may change q if
33        it seems not to be possible to make a prime of the desired length)
34     7) Check whether this is a prime using trial divisions and the
35        Miller-Rabin test.
36     8) Continue with step 4 if we did not find a prime in step 7.
37     9) Find a generator for that prime.
38
39
40
41
42 Layout of the TrustDB
43 =====================
44 FIXME: use a directory record as top node instead of the pubkey record
45
46 The TrustDB is built from fixed length records, where the first byte
47 describes the record type.  All numeric values are stored in network
48 byte order. The length of each record is 40 bytes. The first record of
49 the DB is always of type 1 and this is the only record of this type.
50
51 Record type 0:
52 --------------
53     Unused record, can be reused for any purpose.
54
55 Record type 1:
56 --------------
57     Version information for this TrustDB.  This is always the first
58     record of the DB and the only one with type 1.
59      1 byte value 1
60      3 bytes 'gpg'  magic value
61      1 byte Version of the TrustDB
62      3 byte reserved
63      1 u32  locked by (pid) 0 = not locked.
64      1 u32  timestamp of trustdb creation
65      1 u32  timestamp of last modification
66      1 u32  timestamp of last validation
67             (Used to keep track of the time, when this TrustDB was checked
68              against the pubring)
69      1 u32  reserved
70      1 byte marginals needed
71      1 byte completes needed
72      1 byte max. cert depth
73             If any of this 3 values are changed, all cache records
74             must be invalidated.
75      9 bytes reserved
76
77
78 Record type 2: (directory record)
79 --------------
80     Informations about a public key certificate.
81     These are static values which are never changed without user interaction.
82
83      1 byte value 2
84      1 byte   reserved
85      8 bytes keyid (We keep it here to speed up searching by keyid)
86      1 u32   Local-Id.  This is simply the record number of this record.
87      1 u32   primary public key (record number of it)
88      1 u32   cache record
89      1 u32   sigrecord
90      1 byte  No signatures flag  (used to avoid duplicate building).
91      3 byte  reserved
92      1 u32   userid record
93      6 byte reserved
94
95
96 Record type 3:
97 --------------
98     Informations about a primary public key.
99     These are static values which are never changed without user interaction.
100
101      1 byte value 3
102      1 byte   reserved
103      1 u32   owner  This is used to bind all records for
104              a given certificate together. It is valid only in this TrustDB
105              and useful if we have duplicate keyids
106              It points back to the directory node.
107      1 byte pubkey algorithm
108      1 byte length of the fingerprint (in bytes)
109      20 bytes fingerprint of the public key
110      1 byte ownertrust if there is no trust defined for the userid:
111      3 byte reserved
112
113
114 Record type 4:  (cache record)
115 --------------
116     Used to bind the trustDB to the concrete instance of keyblock in
117     a pubring. This is used to cache information.
118
119      1 byte   value 4
120      1 byte   reserved
121      1 u32    Local-Id.
122      8 bytes  keyid of the primary key (needed?)
123      1 byte   cache-is-valid the following stuff is only
124               valid if this is set.
125      1 byte   reserved
126      20 bytes rmd160 hash value over the complete keyblock
127               This is used to detect any changes of the keyblock with all
128               CTBs and lengths headers. Calculation is easy if the keyblock
129               is optained from a keyserver: simply create the hash from all
130               received data bytes.
131
132      1 byte   number of untrusted signatures.
133      1 byte   number of marginal trusted signatures.
134      1 byte   number of fully trusted signatures.
135               (255 is stored for all values greater than 254)
136      1 byte   Trustlevel
137                 0 = undefined (not calculated)
138                 1 = unknown
139                 2 = not trusted
140                 3 = marginally trusted
141                 4 = fully trusted
142                 5 = ultimately trusted (have secret key too).
143
144 Record type 5  (sigrec)
145 -------------
146     Used to keep track of valid key signatures. Self-signatures are not
147     stored.
148
149      1 byte   value 5
150      1 byte   reserved
151      1 u32    For Local-Id (points back to the directory record)
152      1 u32    chain: next sigrec of this owner or 0 to indicate the
153               last sigrec.
154      6 times
155         1 u32  Local_id of signators pubkey record
156         1 byte reserved
157
158
159 Record Type 6 (hash table)
160 -------------
161     Due to the fact that we use the keyid to lookup keys, we can
162     implement quick access by some simple hash methods, and avoid
163     the overhead of gdbm.  A property of keyids is that they can be
164     used directly as hash values.  (They can be considered as strong
165     random numbers.)
166       What we use is a dynamic multilevel architecture, which combines
167     hashtables, record lists, and linked lists.
168
169     This record is a hashtable of 256 entries; a special property
170     is that all these records are stored consecutively to make one
171     big table. The hash value is simple the 1st, 2nd, ... byte of
172     the keyid (depending on the indirection level).
173
174      1 byte value 5
175      1 byte reserved
176      n u32  recnum; n depends on th record length:
177             n = (reclen-2)/4  which yields 9 for the current record length
178             of 40 bytes.
179
180     the total number of surch record which makes up the table is:
181          m = (256+n-1) / n
182     which is 29 for a record length of 40.
183
184     To look up a key we use its lsb to get the recnum from this
185     hashtable and look up the addressed record:
186        - If this record is another hashtable, we use 2nd lsb
187          to index this hast table and so on.
188        - if this record is a hashlist, we walk thru the
189          reclist records until we found one whose hash field
190          matches the MSB of our keyid, and lookup this record
191        - if this record is a dir record, we compare the
192          keyid and if this is correct, we get the keyrecod and compare
193          the fingerprint to decide whether it is the requested key;
194          if this is not the correct dir record, we look at the next
195          dir record which is linked by the link field.
196
197 Record type 7  (hash list)
198 -------------
199     see hash table for an explanation.
200
201     1 byte value 6
202     1 byte reserved
203     1 u32  chain         next hash list record
204     n times              n = (reclen-6)/5
205         1 byte hash
206         1 u32  recnum
207
208     For the current record length of 40, n is 6
209
210 Record type 8: (userid)
211 --------------
212     Informations about a userid
213     We do not store the userid but the hash value of the userid because that
214     is sufficient.
215
216      1 byte value 8
217      1 byte   reserved
218      1 u32  owner; points to the directory record.
219      1 u32  next userid
220      1 byte subtype: 0 = a real user id
221                      1 = not a real userid, but a "dummy" user of length 0
222                          which is used to represent stuff that is directly
223                          bound to the key.
224      20 bytes ripemd160 hash of the username.
225      1 u32  pointer to preference record
226      1 byte ownertrust
227      4 byte reserved
228
229
230
231 Packet Headers
232 ===============
233
234 GNUPG uses PGP 2 packet headers and also understands OpenPGP packet header.
235 There is one enhancement used with the old style packet headers:
236
237    CTB bits 10, the "packet-length length bits", have values listed in
238    the following table:
239
240       00 - 1-byte packet-length field
241       01 - 2-byte packet-length field
242       10 - 4-byte packet-length field
243       11 - no packet length supplied, unknown packet length
244
245    As indicated in this table, depending on the packet-length length
246    bits, the remaining 1, 2, 4, or 0 bytes of the packet structure field
247    are a "packet-length field".  The packet-length field is a whole
248    number field.  The value of the packet-length field is defined to be
249    the value of the whole number field.
250
251    A value of 11 is currently used in one place: on compressed data.
252    That is, a compressed data block currently looks like <A3 01 . .  .>,
253    where <A3>, binary 10 1000 11, is an indefinite-length packet. The
254    proper interpretation is "until the end of the enclosing structure",
255    although it should never appear outermost (where the enclosing
256    structure is a file).
257
258 +  This will be changed with another version, where the new meaning of
259 +  the value 11 (see below) will also take place.
260 +
261 +  A value of 11 for other packets enables a special length encoding,
262 +  which is used in case, where the length of the following packet can
263 +  not be determined prior to writing the packet; especially this will
264 +  be used if large amounts of data are processed in filter mode.
265 +
266 +  It works like this: After the CTB (with a length field of 11) a
267 +  marker field is used, which gives the length of the following datablock.
268 +  This is a simple 2 byte field (MSB first) containig the amount of data
269 +  following this field, not including this length field. After this datablock
270 +  another length field follows, which gives the size of the next datablock.
271 +  A value of 0 indicates the end of the packet. The maximum size of a
272 +  data block is limited to 65534, thereby reserving a value of 0xffff for
273 +  future extensions. These length markers must be insereted into the data
274 +  stream just before writing the data out.
275 +
276 +  This 2 byte filed is large enough, because the application must buffer
277 +  this amount of data to prepend the length marker before writing it out.
278 +  Data block sizes larger than about 32k doesn't make any sense. Note
279 +  that this may also be used for compressed data streams, but we must use
280 +  another packet version to tell the application that it can not assume,
281 +  that this is the last packet.
282
283
284
285
286
287
288
289 Keyserver Message Format
290 -------------------------
291
292 The keyserver may be contacted by a Unix Domain socket or via TCP.
293
294 The format of a request is:
295
296 ----
297 command-tag
298 "Content-length:" digits
299 CRLF
300 ------
301
302 Where command-tag is
303
304 NOOP
305 GET <user-name>
306 PUT
307 DELETE <user-name>
308
309
310 The format of a response is:
311
312 ------
313 "GNUPG/1.0" status-code status-text
314 "Content-length:" digits
315 CRLF
316 ------------
317 followed by <digits> bytes of data
318
319
320 Status codes are:
321
322      o  1xx: Informational - Request received, continuing process
323
324      o  2xx: Success - The action was successfully received, understood,
325         and accepted
326
327      o  4xx: Client Error - The request contains bad syntax or cannot be
328         fulfilled
329
330      o  5xx: Server Error - The server failed to fulfill an apparently
331         valid request
332
333
334
335 Ich werde jetzt doch das HKP Protokoll implementieren:
336
337 Naja, die Doku ist so gut wie nichtexistent, da gebe ich Dir recht.
338 In kurzen Worten:
339
340 (Minimal-)HTTP-Server auf Port 11371, versteht ein GET auf /pks/lookup,
341 wobei die Query-Parameter (Key-Value-Paare mit = zwischen Key und
342 Value; die Paare sind hinter ? und durch & getrennt). Gültige
343 Operationen sind:
344
345 - - op (Operation) mit den Möglichkeiten index (gleich wie -kv bei
346   PGP), vindex (-kvv) und get (-kxa)
347 - - search: Liste der Worte, die im Key vorkommen müssen. Worte sind
348   mit Worttrennzeichen wie Space, Punkt, @, ... getrennt, Worttrennzeichen
349   werden nicht betrachtet, die Reihenfolge der Worte ist egal.
350 - - exact: (on=aktiv, alles andere inaktiv) Nur die Schlüssel
351   zurückgeben, die auch den "search"-String beinhalten (d.h.
352   Wortreihenfolge und Sonderzeichen sind wichtig)
353 - - fingerprint (Bei [v]index auch den Fingerprint ausgeben), "on"
354   für aktiv, alles andere inaktiv
355
356 Neu (wird von GNUPG benutzt):
357    /pks/lookup/<gnupg_formatierte_user_id>?op=<operation>
358
359 Zusätzlich versteht der Keyserver auch ein POST auf /pks/add, womit
360 man Keys hochladen kann.
361