backup

3 files changed, 127 insertions, 28 deletions

diff --git a/doc/DETAILS b/doc/DETAILS
index efd412ca7..dca87afff 100644
--- a/doc/DETAILS
+++ b/doc/DETAILS
@@ -1,16 +1,44 @@
 
-
-    * For packet version 3 we calculate the keyids this way:
-	RSA	:= low 64 bits of n
-	ELGAMAL := build a v3 pubkey packet (with CTB 0x99) and calculate
-		   a rmd160 hash value from it. This is used as the
-		   fingerprint and the low 64 bits are the keyid.
-
-    * Revocation certificates consist only of the signature packet;
-      "import" knows how to handle this.  The rationale behind it is
-      to keep them small.
-
-
+Format of "---with-colons" listings
+===================================
+
+sec::1024:17:6C7EE1B8621CC013:1998-07-07:0:::Werner Koch <werner.koch@guug.de>:
+ssb::1536:20:5CE086B5B5A18FF4:1998-07-07:0:::
+
+ 1. Field:  Type of record
+	    pub = public key
+	    sub = subkey (secondary key)
+	    sec = secret key
+	    ssb = secret subkey (secondary key)
+	    uid = user id (only field 10 is used).
+	    fpr = fingerprint: (fingerprint is in field 10)
+
+ 2. Field:  A letter describing the calculated trust, see doc/FAQ
+	    (not used for secret keys)
+ 3. Field:  length of key in bits.
+ 4. Field:  Algorithm:	1 = RSA
+		       16 = ElGamal (encrypt only)
+		       17 = DSA (sometimes called DH, sign only)
+		       20 = ElGamal (sign and encrypt)
+ 5. Field:  KeyID
+ 6. Field:  Creation Date (in UTC)
+ 7. Field:  key expieres n days after creation.
+	    (I will change this to a key exiration date)
+ 8. Field:  Local ID: record number of the dir record in the trustdb
+	    this value is only valid as long as the trustdb is not
+	    deleted.  May be later used to lookup the key: You will be
+	    able to use "#<local-id> as the user id.  This is needed
+	    because keyids may not be unique - a program may use this
+	    number to access keys later.
+ 9. Field:  Ownertrust (primary public keys only)
+10. Field:  User-ID.  The value is quoted like a C string to avoid
+	    control characters (the colon is quoted "\x3a").
+
+More fields may be added later.
+
+
+Key generation
+==============
     Key generation shows progress by printing different characters to
     stderr:
 	     "."  Last 10 Miller-Rabin tests failed
@@ -38,7 +66,6 @@
 
 
 
-
 Layout of the TrustDB
 =====================
 The TrustDB is built from fixed length records, where the first byte
@@ -66,7 +93,10 @@ Record type 1:
 	     against the pubring)
      1 u32  record number of keyhashtable
      1 u32  first free record
-     8 bytes reserved
+     1 u32  record number of shadow directory hash table
+	    It does not make sense to combine this table with the key table
+	    becuase the keyid is not in every case a part of the fingerprint.
+     4 bytes reserved for version extension record
 
 
 Record type 2: (directory record)
@@ -131,17 +161,46 @@ Record type 5: (pref record)
 
 Record type 6  (sigrec)
 -------------
-    Used to keep track of valid key signatures. Self-signatures are not
-    stored.
+    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 owner or 0 to indicate the
+     1 u32    next   next sigrec of this uid or 0 to indicate the
 		     last sigrec.
      6 times
-	1 u32  Local_id of signators dir record
-	1 byte reserved
+	1 u32  Local_id of signators 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 my be revoked)
+
+
+
+Record type 8: (shadow directory record)
+--------------
+    This record is used to reserved 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
 
 
 
@@ -191,6 +250,9 @@ Record Type 10 (hash table)
     big table. The hash value is simple the 1st, 2nd, ... byte of
     the fingerprint (depending on the indirection level).
 
+    When used to hash shadow directory records, a different table is used
+    and indexed by the keyid.
+
      1 byte value 10
      1 byte reserved
      n u32  recnum; n depends on the record length:
@@ -214,6 +276,7 @@ Record Type 10 (hash table)
 Record type 11 (hash list)
 --------------
     see hash table for an explanation.
+    This is also used for other purposes.
 
     1 byte value 11
     1 byte reserved
@@ -223,7 +286,11 @@ Record type 11 (hash list)
 
     For the current record length of 40, n is 7
 
-Record type 254: (free record)
+
+
+Record type 254 (free record)
+---------------
+    All these records form a linked list of unused records.
      1 byte  value 254
      1 byte  reserved (0)
      1 u32   next_free
@@ -285,6 +352,20 @@ There is one enhancement used with the old style packet headers:
 
 
 
+Other Notes
+===========
+    * For packet version 3 we calculate the keyids this way:
+	RSA	:= low 64 bits of n
+	ELGAMAL := build a v3 pubkey packet (with CTB 0x99) and calculate
+		   a rmd160 hash value from it. This is used as the
+		   fingerprint and the low 64 bits are the keyid.
+
+    * Revocation certificates consist only of the signature packet;
+      "import" knows how to handle this.  The rationale behind it is
+      to keep them small.
+
+
+
 
 
 
diff --git a/doc/FAQ b/doc/FAQ
index 62003e2ec..ee7f8107b 100644
--- a/doc/FAQ
+++ b/doc/FAQ
@@ -171,7 +171,7 @@
   (ownertrust) to a key.  I have plans to use a cache for calculated
   trust values to speed up calcualtion.
 
-  You can see the calculated trust value using this command:
+  You can see the validity (calculated trust value) using this command:
 
       gpgm --list-keys --with-colons
 
@@ -187,8 +187,8 @@
 	 is only used for keys for which
 	 the secret key is also available.
 
-  You can get a list of the assigned ownertrust values (how far you trust
-  the owner to correctly sign another another ones key)
+  You can get a list of the assigned trust values (how far you trust
+  the owner to correctly sign another one's key)
 
       gpgm --list-ownertrust
 
@@ -259,5 +259,23 @@
    gpg [--options] --sign --encrypt foo.txt
 
 
+  Q: What kind of output is this: "key C26EE891.298, uid 09FB: ...."?
+  A: This is the internal representaion of a user id in the trustdb.
+     "C26EE891" is the keyid, "298" is the local id (a record number
+     in the trustdb) and "09FB" are the last two bytes of a ripe-md-160
+     hash of the user id for this key.
+
+
+  Q: What is trust, validity and ownertrust?
+  A: "ownertrust" is used instead of "trust" to make clear that
+     this is the value you have assigned to key to express, how far you
+     trust the owner of this key to correctly sign (and so introduce)
+     other keys.  "validity" or calculated trust is a value which
+     says, how far the gnupg thinks a key is valid (that it really belongs
+     to the one who claims to be the owner of the key).
+     For more see the chapter "The Web of Trust" in the
+     Manual [gpg: Oops: Internal error: manual not found - sorry]
+
+
+
 
-[That's it for now.)]
diff --git a/doc/gpg.1pod b/doc/gpg.1pod
index 5a2172205..2f76e80a3 100644
--- a/doc/gpg.1pod
+++ b/doc/gpg.1pod
@@ -12,7 +12,7 @@ B<gpgm> [--homedir name] [--options file] [options] command [args]
 
 B<gpg> is the main program for the GNUPG system. B<gpgm> is a maintenance
 tool which has some commands B<gpgm> does not have; it is there because
-it does not handle sensitive data ans therefore has no need to allocate
+it does not handle sensitive data and therefore has no need to allocate
 secure memory.
 
 =head1 COMMANDS
@@ -315,13 +315,13 @@ B<--marginals-needed> I<n>
 
 B<--cipher-algo> I<name>
     Use I<name> as cipher algorithm. Running the program
-    with the option B<--verbose> yields a list of supported
+    with the command B<--version> yields a list of supported
     algorithms. If this is not used the cipher algorithm is
     selected from the preferences stored with the key.
 
 B<--digest-algo> I<name>
     Use I<name> as message digest algorithm. Running the
-    program with the option B<--verbose> yields a list of
+    program with the command B<--version> yields a list of
     supported algorithms.  Please note that using this
     option may violate the OpenPGP requirement, that a
     160 bit hash is to be used for DSA.
@@ -357,7 +357,7 @@ B<--compress-algo> I<number>
 
 B<--digest-algo> I<name>
     Use I<name> as message digest algorithm. Running the
-    program with the option B<--verbose> yields a list of
+    program with the command B<--version> yields a list of
     supported algorithms.