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