6ff7cb656bade403d9687ea47cf10783b6a5f478
[gnupg.git] / doc / DETAILS
1
2 Format of "---with-colons" listings
3 ===================================
4
5 sec::1024:17:6C7EE1B8621CC013:1998-07-07:0:::Werner Koch <werner.koch@guug.de>:
6 ssb::1536:20:5CE086B5B5A18FF4:1998-07-07:0:::
7
8  1. Field:  Type of record
9             pub = public key
10             sub = subkey (secondary key)
11             sec = secret key
12             ssb = secret subkey (secondary key)
13             uid = user id (only field 10 is used).
14             fpr = fingerprint: (fingerprint is in field 10)
15             pkd = public key data (special field format, see below)
16
17  2. Field:  A letter describing the calculated trust, see doc/FAQ
18             This is a single letter, but be prepared that additional
19             information may follow in some future versions.
20             (not used for secret keys)
21  3. Field:  length of key in bits.
22  4. Field:  Algorithm:  1 = RSA
23                        16 = ElGamal (encrypt only)
24                        17 = DSA (sometimes called DH, sign only)
25                        20 = ElGamal (sign and encrypt)
26  5. Field:  KeyID
27  6. Field:  Creation Date (in UTC)
28  7. Field:  Key expiration date or empty if none.
29  8. Field:  Local ID: record number of the dir record in the trustdb
30             this value is only valid as long as the trustdb is not
31             deleted.  May be later used to lookup the key: You will be
32             able to use "#<local-id> as the user id.  This is needed
33             because keyids may not be unique - a program may use this
34             number to access keys later.
35  9. Field:  Ownertrust (primary public keys only)
36             This is a single letter, but be prepared that additional
37             information may follow in some future versions.
38 10. Field:  User-ID.  The value is quoted like a C string to avoid
39             control characters (the colon is quoted "\x3a").
40
41 More fields may be added later.
42
43 If field 1 has the tag "pkd", a listing looks like this:
44 pkd:0:1024:B665B1435F4C2 .... FF26ABB:
45     !  !   !-- the value
46     !  !------ for infomation number of bits in the value
47     !--------- index (eg. DSA goes from 0 to 3: p,q,g,y)
48
49
50
51 Format of the "--status-fd" output
52 ==================================
53 Every line is prefixed with "[GNUPG:] ", followed by a keyword with
54 the type of the status line and a some arguments depending on the
55 type (maybe none); an application should always be prepared to see
56 more arguments in future versions.
57
58
59     GOODSIG     <long keyid>  <username>
60         The signature with the keyid is good.
61
62     BADSIG      <long keyid>  <username>
63         The signature with the keyid has not been verified okay.
64
65     ERRSIG  <long keyid>  <pubkey_algo> <hash_algo> \
66             <sig_class> <timestamp> <rc>
67         It was not possible to check the signature.  This may be
68         caused by a missing public key or an unsupported algorithm.
69         A RC of 4 indicates unknown algorithm, a 9 indicates a missing
70         public key. The other fields give more information about
71         this signature.  sig_class is a 2 byte hex-value.
72
73     VALIDSIG    <fingerprint in hex> <sig_creation_date> <sig-timestamp>
74         The signature with the keyid is good. This is the same
75         as GOODSIG but has the fingerprint as the argument. Both
76         status lines ere emitted for a good signature.
77         sig-timestamp is the signature creation time in seconds after
78         the epoch.
79
80     SIG_ID  <radix64_string>  <sig_creation_date>  <sig-timestamp>
81         This is emitted only for signatures of class 0 or 1 which
82         have been verified okay.  The string is a signature id
83         and may be used in applications to detect replay attacks
84         of signed messages.  Note that only DLP algorithms give
85         unique ids - others may yield duplicated ones when they
86         have been created in the same second.
87
88     ENC_TO  <long keyid>  <keytype>  <keylength>
89         The message is encrypted to this keyid.
90         keytype is the numerical value of the public key algorithm,
91         kenlength is the length of the key or 0 if it is not known
92         (which is currently always the case).
93
94     NODATA  <what>
95         No data has been found. Codes for what are:
96             1 - No armored data.
97             2 - Expected a packet but did not found one.
98             3 - Invalid packet found, this may indicate a non OpenPGP message.
99         You may see more than one of these status lines.
100
101     TRUST_UNDEFINED
102     TRUST_NEVER
103     TRUST_MARGINAL
104     TRUST_FULLY
105     TRUST_ULTIMATE
106         For good signatures one of these status lines are emitted
107         to indicate how trustworthy the signature is.  No arguments yet.
108
109     SIGEXPIRED
110         The signature key has expired.  No arguments yet.
111
112     KEYREVOKED
113         The used key has been revoked by his owner.  No arguments yet.
114
115     BADARMOR
116         The ASCII armor is corrupted.  No arguments yet.
117
118     RSA_OR_IDEA
119         The RSA or IDEA algorithms has been used in the data.  A
120         program might want to fallback to another program to handle
121         the data if GnuPG failed.
122
123     SHM_INFO
124     SHM_GET
125     SHM_GET_BOOL
126     SHM_GET_HIDDEN
127
128     NEED_PASSPHRASE <long keyid>  <keytype>  <keylength>
129         Issued whenever a passphrase is needed.
130         keytype is the numerical value of the public key algorithm
131         or 0 if this is not applicable, keylength is the length
132         of the key or 0 if it is not known (this is currently always the case).
133
134     NEED_PASSPHRASE_SYM <cipher_algo> <s2k_mode> <s2k_hash>
135         Issued whenever a passphrase for symmetric encryption is needed.
136
137     MISSING_PASSPHRASE
138
139     BAD_PASSPHRASE <long keyid>
140         The supplied passphrase was wrong
141
142     GOOD_PASSPHRASE
143         The supplied passphrase was good and the secret key material
144         is therefore usuable.
145
146     DECRYPTION_FAILED
147         The symmetric decryption failed - one reason could be a wrong
148         passphrase for a symmetrical encrypted message.
149
150     DECRYPTION_OKAY
151         The decryption process succeeded.  This means, that either the
152         correct secret key has been used or the correct passphrase
153         for a conventional encrypted message was given.  The program
154         itself may return an errorcode becuase it may not be possible to
155         verify a signature for some reasons.
156
157     NO_PUBKEY  <long keyid>
158     NO_SECKEY  <long keyid>
159         The key is not available
160
161
162 Key generation
163 ==============
164     Key generation shows progress by printing different characters to
165     stderr:
166              "."  Last 10 Miller-Rabin tests failed
167              "+"  Miller-Rabin test succeeded
168              "!"  Reloading the pool with fresh prime numbers
169              "^"  Checking a new value for the generator
170              "<"  Size of one factor decreased
171              ">"  Size of one factor increased
172
173     The prime number for ElGamal is generated this way:
174
175     1) Make a prime number q of 160, 200, 240 bits (depending on the keysize)
176     2) Select the length of the other prime factors to be at least the size
177        of q and calculate the number of prime factors needed
178     3) Make a pool of prime numbers, each of the length determined in step 2
179     4) Get a new permutation out of the pool or continue with step 3
180        if we have tested all permutations.
181     5) Calculate a candidate prime p = 2 * q * p[1] * ... * p[n] + 1
182     6) Check that this prime has the correct length (this may change q if
183        it seems not to be possible to make a prime of the desired length)
184     7) Check whether this is a prime using trial divisions and the
185        Miller-Rabin test.
186     8) Continue with step 4 if we did not find a prime in step 7.
187     9) Find a generator for that prime.
188
189     This algorithm is based on Lim and Lee's suggestion from the
190     Crypto '97 proceedings p. 260.
191
192
193
194 Layout of the TrustDB
195 =====================
196 The TrustDB is built from fixed length records, where the first byte
197 describes the record type.  All numeric values are stored in network
198 byte order. The length of each record is 40 bytes. The first record of
199 the DB is always of type 2 and this is the only record of this type.
200
201   Record type 0:
202   --------------
203     Unused record, can be reused for any purpose.
204
205   Record type 1:
206   --------------
207     Version information for this TrustDB.  This is always the first
208     record of the DB and the only one with type 1.
209      1 byte value 1
210      3 bytes 'gpg'  magic value
211      1 byte Version of the TrustDB (2)
212      1 byte marginals needed
213      1 byte completes needed
214      1 byte max_cert_depth
215             The three items are used to check whether the cached
216             validity value from the dir record can be used.
217      1 u32  locked flags
218      1 u32  timestamp of trustdb creation
219      1 u32  timestamp of last modification which may affect the validity
220             of keys in the trustdb.  This value is checked against the
221             validity timestamp in the dir records.
222      1 u32  timestamp of last validation
223             (Used to keep track of the time, when this TrustDB was checked
224              against the pubring)
225      1 u32  record number of keyhashtable
226      1 u32  first free record
227      1 u32  record number of shadow directory hash table
228             It does not make sense to combine this table with the key table
229             because the keyid is not in every case a part of the fingerprint.
230      4 bytes reserved for version extension record
231
232
233   Record type 2: (directory record)
234   --------------
235     Informations about a public key certificate.
236     These are static values which are never changed without user interaction.
237
238      1 byte value 2
239      1 byte  reserved
240      1 u32   LID     .  (This is simply the record number of this record.)
241      1 u32   List of key-records (the first one is the primary key)
242      1 u32   List of uid-records
243      1 u32   cache record
244      1 byte  ownertrust
245      1 byte  dirflag
246      1 byte  maximum validity of all the user ids
247      1 u32   time of last validity check.
248      1 u32   Must check when this time has been reached.
249              (0 = no check required)
250
251
252   Record type 3:  (key record)
253   --------------
254     Informations about a primary public key.
255     (This is mainly used to lookup a trust record)
256
257      1 byte value 3
258      1 byte  reserved
259      1 u32   LID
260      1 u32   next   - next key record
261      7 bytes reserved
262      1 byte  keyflags
263      1 byte  pubkey algorithm
264      1 byte  length of the fingerprint (in bytes)
265      20 bytes fingerprint of the public key
266               (This is the value we use to identify a key)
267
268   Record type 4: (uid record)
269   --------------
270     Informations about a userid
271     We do not store the userid but the hash value of the userid because that
272     is sufficient.
273
274      1 byte value 4
275      1 byte reserved
276      1 u32  LID  points to the directory record.
277      1 u32  next   next userid
278      1 u32  pointer to preference record
279      1 u32  siglist  list of valid signatures
280      1 byte uidflags
281      1 byte validity of the key calculated over this user id
282      20 bytes ripemd160 hash of the username.
283
284
285   Record type 5: (pref record)
286   --------------
287     Informations about preferences
288
289      1 byte value 5
290      1 byte   reserved
291      1 u32  LID; points to the directory record (and not to the uid record!).
292             (or 0 for standard preference record)
293      1 u32  next
294      30 byte preference data
295
296   Record type 6  (sigrec)
297   -------------
298     Used to keep track of key signatures. Self-signatures are not
299     stored.  If a public key is not in the DB, the signature points to
300     a shadow dir record, which in turn has a list of records which
301     might be interested in this key (and the signature record here
302     is one).
303
304      1 byte   value 6
305      1 byte   reserved
306      1 u32    LID           points back to the dir record
307      1 u32    next   next sigrec of this uid or 0 to indicate the
308                      last sigrec.
309      6 times
310         1 u32  Local_id of signators dir or shadow dir record
311         1 byte Flag: Bit 0 = checked: Bit 1 is valid (we have a real
312                              directory record for this)
313                          1 = valid is set (but my be revoked)
314
315
316
317   Record type 8: (shadow directory record)
318   --------------
319     This record is used to reserved a LID for a public key.  We
320     need this to create the sig records of other keys, even if we
321     do not yet have the public key of the signature.
322     This record (the record number to be more precise) will be reused
323     as the dir record when we import the real public key.
324
325      1 byte value 8
326      1 byte  reserved
327      1 u32   LID      (This is simply the record number of this record.)
328      2 u32   keyid
329      1 byte  pubkey algorithm
330      3 byte reserved
331      1 u32   hintlist   A list of records which have references to
332                         this key.  This is used for fast access to
333                         signature records which are not yet checked.
334                         Note, that this is only a hint and the actual records
335                         may not anymore hold signature records for that key
336                         but that the code cares about this.
337     18 byte reserved
338
339
340
341   Record Type 10 (hash table)
342   --------------
343     Due to the fact that we use fingerprints to lookup keys, we can
344     implement quick access by some simple hash methods, and avoid
345     the overhead of gdbm.  A property of fingerprints is that they can be
346     used directly as hash values.  (They can be considered as strong
347     random numbers.)
348       What we use is a dynamic multilevel architecture, which combines
349     hashtables, record lists, and linked lists.
350
351     This record is a hashtable of 256 entries; a special property
352     is that all these records are stored consecutively to make one
353     big table. The hash value is simple the 1st, 2nd, ... byte of
354     the fingerprint (depending on the indirection level).
355
356     When used to hash shadow directory records, a different table is used
357     and indexed by the keyid.
358
359      1 byte value 10
360      1 byte reserved
361      n u32  recnum; n depends on the record length:
362             n = (reclen-2)/4  which yields 9 for the current record length
363             of 40 bytes.
364
365     the total number of such record which makes up the table is:
366          m = (256+n-1) / n
367     which is 29 for a record length of 40.
368
369     To look up a key we use the first byte of the fingerprint to get
370     the recnum from this hashtable and look up the addressed record:
371        - If this record is another hashtable, we use 2nd byte
372          to index this hash table and so on.
373        - if this record is a hashlist, we walk all entries
374          until we found one a matching one.
375        - if this record is a key record, we compare the
376          fingerprint and to decide whether it is the requested key;
377
378
379   Record type 11 (hash list)
380   --------------
381     see hash table for an explanation.
382     This is also used for other purposes.
383
384     1 byte value 11
385     1 byte reserved
386     1 u32  next          next hash list record
387     n times              n = (reclen-5)/5
388         1 u32  recnum
389
390     For the current record length of 40, n is 7
391
392
393
394   Record type 254 (free record)
395   ---------------
396     All these records form a linked list of unused records.
397      1 byte  value 254
398      1 byte  reserved (0)
399      1 u32   next_free
400
401
402
403 Packet Headers
404 ===============
405
406 GNUPG uses PGP 2 packet headers and also understands OpenPGP packet header.
407 There is one enhancement used with the old style packet headers:
408
409    CTB bits 10, the "packet-length length bits", have values listed in
410    the following table:
411
412       00 - 1-byte packet-length field
413       01 - 2-byte packet-length field
414       10 - 4-byte packet-length field
415       11 - no packet length supplied, unknown packet length
416
417    As indicated in this table, depending on the packet-length length
418    bits, the remaining 1, 2, 4, or 0 bytes of the packet structure field
419    are a "packet-length field".  The packet-length field is a whole
420    number field.  The value of the packet-length field is defined to be
421    the value of the whole number field.
422
423    A value of 11 is currently used in one place: on compressed data.
424    That is, a compressed data block currently looks like <A3 01 . .  .>,
425    where <A3>, binary 10 1000 11, is an indefinite-length packet. The
426    proper interpretation is "until the end of the enclosing structure",
427    although it should never appear outermost (where the enclosing
428    structure is a file).
429
430 +  This will be changed with another version, where the new meaning of
431 +  the value 11 (see below) will also take place.
432 +
433 +  A value of 11 for other packets enables a special length encoding,
434 +  which is used in case, where the length of the following packet can
435 +  not be determined prior to writing the packet; especially this will
436 +  be used if large amounts of data are processed in filter mode.
437 +
438 +  It works like this: After the CTB (with a length field of 11) a
439 +  marker field is used, which gives the length of the following datablock.
440 +  This is a simple 2 byte field (MSB first) containing the amount of data
441 +  following this field, not including this length field. After this datablock
442 +  another length field follows, which gives the size of the next datablock.
443 +  A value of 0 indicates the end of the packet. The maximum size of a
444 +  data block is limited to 65534, thereby reserving a value of 0xffff for
445 +  future extensions. These length markers must be inserted into the data
446 +  stream just before writing the data out.
447 +
448 +  This 2 byte filed is large enough, because the application must buffer
449 +  this amount of data to prepend the length marker before writing it out.
450 +  Data block sizes larger than about 32k doesn't make any sense. Note
451 +  that this may also be used for compressed data streams, but we must use
452 +  another packet version to tell the application that it can not assume,
453 +  that this is the last packet.
454
455
456 Usage of gdbm files for keyrings
457 ================================
458     The key to store the keyblock is it's fingerprint, other records
459     are used for secondary keys.  fingerprints are always 20 bytes
460     where 16 bit fingerprints are appended with zero.
461     The first byte of the key gives some information on the type of the
462     key.
463       1 = key is a 20 bit fingerprint (16 bytes fpr are padded with zeroes)
464           data is the keyblock
465       2 = key is the complete 8 byte keyid
466           data is a list of 20 byte fingerprints
467       3 = key is the short 4 byte keyid
468           data is a list of 20 byte fingerprints
469       4 = key is the email address
470           data is a list of 20 byte fingerprints
471
472     Data is prepended with a type byte:
473       1 = keyblock
474       2 = list of 20 byte padded fingerprints
475       3 = list of list fingerprints (but how to we key them?)
476
477
478
479
480 Other Notes
481 ===========
482     * For packet version 3 we calculate the keyids this way:
483         RSA     := low 64 bits of n
484         ELGAMAL := build a v3 pubkey packet (with CTB 0x99) and calculate
485                    a rmd160 hash value from it. This is used as the
486                    fingerprint and the low 64 bits are the keyid.
487
488     * Revocation certificates consist only of the signature packet;
489       "import" knows how to handle this.  The rationale behind it is
490       to keep them small.
491
492
493
494
495
496
497
498 Keyserver Message Format
499 =========================
500
501 The keyserver may be contacted by a Unix Domain socket or via TCP.
502
503 The format of a request is:
504
505 ====
506 command-tag
507 "Content-length:" digits
508 CRLF
509 =======
510
511 Where command-tag is
512
513 NOOP
514 GET <user-name>
515 PUT
516 DELETE <user-name>
517
518
519 The format of a response is:
520
521 ======
522 "GNUPG/1.0" status-code status-text
523 "Content-length:" digits
524 CRLF
525 ============
526 followed by <digits> bytes of data
527
528
529 Status codes are:
530
531      o  1xx: Informational - Request received, continuing process
532
533      o  2xx: Success - The action was successfully received, understood,
534         and accepted
535
536      o  4xx: Client Error - The request contains bad syntax or cannot be
537         fulfilled
538
539      o  5xx: Server Error - The server failed to fulfill an apparently
540         valid request
541
542
543
544 Ich werde jetzt doch das HKP Protokoll implementieren:
545
546 Naja, die Doku ist so gut wie nichtexistent, da gebe ich Dir recht.
547 In kurzen Worten:
548
549 (Minimal-)HTTP-Server auf Port 11371, versteht ein GET auf /pks/lookup,
550 wobei die Query-Parameter (Key-Value-Paare mit = zwischen Key und
551 Value; die Paare sind hinter ? und durch & getrennt). Gültige
552 Operationen sind:
553
554 - - op (Operation) mit den Möglichkeiten index (gleich wie -kv bei
555   PGP), vindex (-kvv) und get (-kxa)
556 - - search: Liste der Worte, die im Key vorkommen müssen. Worte sind
557   mit Worttrennzeichen wie Space, Punkt, @, ... getrennt, Worttrennzeichen
558   werden nicht betrachtet, die Reihenfolge der Worte ist egal.
559 - - exact: (on=aktiv, alles andere inaktiv) Nur die Schlüssel
560   zurückgeben, die auch den "search"-String beinhalten (d.h.
561   Wortreihenfolge und Sonderzeichen sind wichtig)
562 - - fingerprint (Bei [v]index auch den Fingerprint ausgeben), "on"
563   für aktiv, alles andere inaktiv
564
565 Neu (wird von GNUPG benutzt):
566    /pks/lookup/<gnupg_formatierte_user_id>?op=<operation>
567
568 Zusätzlich versteht der Keyserver auch ein POST auf /pks/add, womit
569 man Keys hochladen kann.
570