The Web of Trust .wot file format, version 0.2


1. Overview

To stimulate statistics and analyzes of the OpenPGP Web of Trust, a
file format is proposed to carry information about key IDs, names and
signatures, in files small enough to be easily downloaded by anyone.

Because the OpenPGP Web of Trust is supposed to grow a lot, the file
format is designed with compressed size as first priority. Key IDs and
names are specified only once. The signatures are specified using
sorted lists of indices into the key list. Similar data is close
together. The result is a format which can store the current (November
2004) strongly connected set in less than 0.9 MiB.

The first system to use this file format is Wotsap,
http://www.lysator.liu.se/~jc/wotsap/.

The latest version of this file is available at
http://www.lysator.liu.se/~jc/wotsap/wotfileformat.txt
with detached signature at
http://www.lysator.liu.se/~jc/wotsap/wotfileformat.txt.sig

2. File format

A wot file consists of the data chunks with names and content listed
below. The chunks are stored, in the same order as below, in a
bzip2-compressed ar-archive. All texts are coded using UTF-8, and all
integers are in network byte order.

"README":

  A short text describing what kind of file this is, and where and
  when it was generated.

"WOTVERSION":

  The version of this specification, followed by a newline. Currently
  "0.2\n".

"names"

  One string specifying the name of the primary user ID of each key. 
  Each name is followed by a newline. The inclusion of a key here
  implies that it is a valid key which is part of the web of trust. 
  The order of the keys is random and has no meaning, except that the
  same order is used in all lists in a specific wot file. The orders
  in two different wot files are generally not the same.

"keys"

  Four bytes specifying the key ID of each key. The keys are in the
  same order as in the "names" chunk.

"signatures"

  For each key, in the same order as the above lists, a 4-byte integer
  specifying the number of signatures on that key, followed by a list
  of that number of 4-byte signature descriptions. The 4 most
  significant bits indicates the signature type and the 28 least
  significant bits indicate the signing key as an index, starting from
  zero, for the above lists.

  The 4-bit signature type is interpreted as:

    If the signing key has signed the primary user ID and one or more
    other IDs, all signatures except the one on the primary user ID
    are ignored.

    If and only if the signing key has signed the primary user ID, bit
    2 is set and the two least significant bits are set to the cert
    check level (0-3) of that signature.

    If the primary user ID is not signed, one or more other user IDs
    are. Bit 2 is not set, but the two least significant bits are set
    to the highest cert check level of those signatures.

    Bit 3 is reserved and might be given a meaning in future 0.2.x
    versions. Set to zero when writing and ignore when reading.

"debug" (optional)

  Optional debug text, which should be of no interest to anyone not
  developing/debugging/tuning the .wot generation program.

4. Future extensions

Future versions will, if possible, only add new chunks to the archive. 
Such versions will have version numbers 0.2.x. Current implementations
must be able to read these files, by ignoring the extra chunks. If
incompatible changes are introduced, the version number will change to
0.3.

5. Version history

Version 0.2 - 2004-11-07
  * Some clarifications
  * Easier parsing of signatures chunk
     signatures chunk in 0.1 contained:
        "For each key, a list specifying the keys that has signed this
        key. The list elements are 4-byte indices into the above
        lists. The lists are in the same order as in the above chunks. 
        The lists are separated by 0xFFFFFFFF."
  * Specify if primary UID is signed
  * Specify cert check level
  * New (optional) debug file
  * Renamed internal files as "chunks" to avoid confusion
  Available at
  http://www.lysator.liu.se/~jc/wotsap/wotfileformat-0.2.txt
  with detached signature at
  http://www.lysator.liu.se/~jc/wotsap/wotfileformat-0.2.txt.sig

Version 0.1 - 2003-03-26
  Initial version, available at
  http://www.lysator.liu.se/~jc/wotsap/wotfileformat-0.1.txt
  with detached signature at
  http://www.lysator.liu.se/~jc/wotsap/wotfileformat-0.1.txt.sig

6. Author and date

Jörgen Cederlöf <jc@lysator.liu.se>, 2004-11-07