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