security-and-privacy/gnupg
security-and-privacy/gnupg
1
0
Fork 0
mirror of git://git.gnupg.org/gnupg.git synced 2025-01-20 14:37:08 +01:00
Code Activity

doc: Update the record description of the trustdb.

Browse Source 
--

This now reflects the used version of the trustdb.  However, it still
missed a detailed description on how it works.
This commit is contained in:
Werner Koch 2015-06-15 15:37:30 +02:00
parent b89a592a2e
commit 0b3e8342fa
No known key found for this signature in database
GPG Key ID: E3FDFF218E45B72B
1 changed files with 109 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

293
doc/DETAILS
View File

@ -924,212 +924,131 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
The TrustDB is built from fixed length records, where the first byte The TrustDB is built from fixed length records, where the first byte
describes the record type. All numeric values are stored in network describes the record type. All numeric values are stored in network
byte order. The length of each record is 40 bytes. The first record byte order. The length of each record is 40 bytes. The first
of the DB is always of type 1 and this is the only record of this record of the DB is always of type 1 and this is the only record of
type. this type.
FIXME: The layout changed, document it here. The record types: directory(2), key(3), uid(4), pref(5), sigrec(6),
#+begin_example and shadow directory(8) are not anymore used by version 2 of the
Record type 0: TrustDB.
--------------
Unused record, can be reused for any purpose. ** Record type 0
Unused record or deleted, can be reused for any purpose. Such
records should in general not exist because deleted records are of
type 254 and kept in a linked list.
** Version info (RECTYPE_VER, 1)
Record type 1:
--------------
Version information for this TrustDB. This is always the first Version information for this TrustDB. This is always the first
record of the DB and the only one with type 1. record of the DB and the only one of this type.
1 byte value 1
3 bytes 'gpg' magic value - 1 u8 :: Record type (value: 1).
1 byte Version of the TrustDB (2) - 3 byte :: Magic value ("gpg")
1 byte marginals needed - 1 u8 :: TrustDB version (value: 2).
1 byte completes needed - 1 u8 :: =marginals=. How many marginal trusted keys are required.
1 byte max_cert_depth - 1 u8 :: =completes=. How many completely trusted keys are
The three items are used to check whether the cached required.
validity value from the dir record can be used. - 1 u8 :: =max_cert_depth=. How deep is the WoT evaluated. Along
1 u32 locked flags [not used] with =marginals= and =completes=, this value is used to
1 u32 timestamp of trustdb creation check whether the cached validity value from a [FIXME
1 u32 timestamp of last modification which may affect the validity dir] record can be used.
of keys in the trustdb. This value is checked against the - 1 u8 :: =trust_model=
validity timestamp in the dir records. - 1 u8 :: =min_cert_level=
1 u32 timestamp of last validation [currently not used] - 2 byte :: Not used
(Used to keep track of the time, when this TrustDB was checked - 1 u32 :: =created=. Timestamp of trustdb creation.
against the pubring) - 1 u32 :: =nextcheck=. Timestamp of last modification which may
1 u32 record number of keyhashtable [currently not used] affect the validity of keys in the trustdb. This value
1 u32 first free record is checked against the validity timestamp in the dir
1 u32 record number of shadow directory hash table [currently not used] records.
It does not make sense to combine this table with the key table - 1 u32 :: =reserved=. Not used.
because the keyid is not in every case a part of the fingerprint. - 1 u32 :: =reserved2=. Not used.
1 u32 record number of the trusthashtbale - 1 u32 :: =firstfree=. Number of the record with the head record
of the RECTYPE_FREE linked list.
- 1 u32 :: =reserved3=. Not used.
- 1 u32 :: =trusthashtbl=. Record number of the trusthashtable.
Record type 2: (directory record) ** Hash table (RECTYPE_HTBL, 10)
--------------
Informations about a public key certificate.
These are static values which are never changed without user interaction.
1 byte value 2
1 byte reserved
1 u32 LID . (This is simply the record number of this record.)
1 u32 List of key-records (the first one is the primary key)
1 u32 List of uid-records
1 u32 cache record
1 byte ownertrust
1 byte dirflag
1 byte maximum validity of all the user ids
1 u32 time of last validity check.
1 u32 Must check when this time has been reached.
(0 = no check required)
Record type 3: (key record)
--------------
Informations about a primary public key.
(This is mainly used to lookup a trust record)
1 byte value 3
1 byte reserved
1 u32 LID
1 u32 next - next key record
7 bytes reserved
1 byte keyflags
1 byte pubkey algorithm
1 byte length of the fingerprint (in bytes)
20 bytes fingerprint of the public key
(This is the value we use to identify a key)
Record type 4: (uid record)
--------------
Informations about a userid
We do not store the userid but the hash value of the userid because that
is sufficient.
1 byte value 4
1 byte reserved
1 u32 LID points to the directory record.
1 u32 next next userid
1 u32 pointer to preference record
1 u32 siglist list of valid signatures
1 byte uidflags
1 byte validity of the key calculated over this user id
20 bytes ripemd160 hash of the username.
Record type 5: (pref record)
--------------
This record type is not anymore used.
1 byte value 5
1 byte reserved
1 u32 LID; points to the directory record (and not to the uid record!).
(or 0 for standard preference record)
1 u32 next
30 byte preference data
Record type 6 (sigrec)
-------------
Used to keep track of key signatures. Self-signatures are not
stored. If a public key is not in the DB, the signature points to
a shadow dir record, which in turn has a list of records which
might be interested in this key (and the signature record here
is one).
1 byte value 6
1 byte reserved
1 u32 LID points back to the dir record
1 u32 next next sigrec of this uid or 0 to indicate the
last sigrec.
6 times
1 u32 Local_id of signatures dir or shadow dir record
1 byte Flag: Bit 0 = checked: Bit 1 is valid (we have a real
directory record for this)
1 = valid is set (but may be revoked)
Record type 8: (shadow directory record)
--------------
This record is used to reserve a LID for a public key. We
need this to create the sig records of other keys, even if we
do not yet have the public key of the signature.
This record (the record number to be more precise) will be reused
as the dir record when we import the real public key.
1 byte value 8
1 byte reserved
1 u32 LID (This is simply the record number of this record.)
2 u32 keyid
1 byte pubkey algorithm
3 byte reserved
1 u32 hintlist A list of records which have references to
this key. This is used for fast access to
signature records which are not yet checked.
Note, that this is only a hint and the actual records
may not anymore hold signature records for that key
but that the code cares about this.
18 byte reserved
Record Type 10 (hash table)
--------------
Due to the fact that we use fingerprints to lookup keys, we can Due to the fact that we use fingerprints to lookup keys, we can
implement quick access by some simple hash methods, and avoid implement quick access by some simple hash methods, and avoid the
the overhead of gdbm. A property of fingerprints is that they can be overhead of gdbm. A property of fingerprints is that they can be
used directly as hash values. (They can be considered as strong used directly as hash values. What we use is a dynamic multilevel
random numbers.) architecture, which combines hash tables, record lists, and linked
What we use is a dynamic multilevel architecture, which combines lists.
hashtables, record lists, and linked lists.
This record is a hashtable of 256 entries; a special property This record is a hash table of 256 entries with the property that
is that all these records are stored consecutively to make one all these records are stored consecutively to make one big
big table. The hash value is simple the 1st, 2nd, ... byte of table. The hash value is simple the 1st, 2nd, ... byte of the
the fingerprint (depending on the indirection level). fingerprint (depending on the indirection level).
When used to hash shadow directory records, a different table is used - 1 u8 :: Record type (value: 10).
and indexed by the keyid. - 1 u8 :: Reserved
- n u32 :: =recnum=. A table with the hash table items fitting into
this record. =n= depends on the record length:
$n=(reclen-2)/4$ which yields 9 for oure current record
length of 40 bytes.
1 byte value 10 The total number of hash table records to form the table is:
1 byte reserved $m=(256+n-1)/n$. This is 29 for our record length of 40.
n u32 recnum; n depends on the record length:
n = (reclen-2)/4 which yields 9 for the current record length
of 40 bytes.
the total number of such record which makes up the table is:
m = (256+n-1) / n
which is 29 for a record length of 40.
To look up a key we use the first byte of the fingerprint to get To look up a key we use the first byte of the fingerprint to get
the recnum from this hashtable and look up the addressed record: the recnum from this hash table and then look up the addressed
- If this record is another hashtable, we use 2nd byte record:
to index this hash table and so on.
- if this record is a hashlist, we walk all entries - If that record is another hash table, we use 2nd byte to index
until we found one a matching one. that hash table and so on;
- if this record is a key record, we compare the - if that record is a hash list, we walk all entries until we find
fingerprint and to decide whether it is the requested key; a matching one; or
- if that record is a key record, we compare the fingerprint to
decide whether it is the requested key;
Record type 11 (hash list) ** Hash list (RECTYPE_HLST, 11)
--------------
see hash table for an explanation.
This is also used for other purposes.
1 byte value 11 See hash table above on how it is used. It may also be used for
1 byte reserved other purposes.
1 u32 next next hash list record
n times n = (reclen-5)/5
1 u32 recnum
For the current record length of 40, n is 7 - 1 u8 :: Record type (value: 11).
- 1 u8 :: Reserved.
- 1 u32 :: =next=. Record number of the next hash list record or 0
if none.
- n u32 :: =rnum=. Array with record numbers to values. With
$n=(reclen-5)/5$ and our record length of 40, n is 7.
** Trust record (RECTYPE_TRUST, 12)
- 1 u8 :: Record type (value: 12).
- 1 u8 :: Reserved.
- 20 byte :: =fingerprint=.
- 1 u8 :: =ownertrust=.
- 1 u8 :: =depth=.
- 1 u8 :: =min_ownertrust=.
- 1 byte :: Not used.
- 1 u32 :: =validlist=.
- 10 byte :: Not used.
Record type 254 (free record) ** Validity record (RECTYPE_VALID, 13)
---------------
All these records form a linked list of unused records. - 1 u8 :: Record type (value: 13).
1 byte value 254 - 1 u8 :: Reserved.
1 byte reserved (0) - 20 byte :: =namehash=.
1 u32 next_free - 1 u8 :: =validity=
#+end_example - 1 u32 :: =next=.
- 1 u8 :: =full_count=.
- 1 u8 :: =marginal_count=.
- 11 byte :: Not used.
** Free record (RECTYPE_FREE, 254)
All these records form a linked list of unused records in the TrustDB.
- 1 u8 :: Record type (value: 254)
- 1 u8 :: Reserved.
- 1 u32 :: =next=. Record number of the next rcord of this type.
The record number to the head of this linked list is
stored in the version info record.
* GNU extensions to the S2K algorithm * GNU extensions to the S2K algorithm