[tor-commits] [metrics-db/master] Document new ed25519-related lines.

[karsten at torproject.org]

commit 11179b2eb314a740b0e893bc9a0f8a9e8663fae6
Author: Karsten Loesing <karsten.loesing at gmx.net>
Date:   Fri Jun 19 11:27:36 2015 +0200

    Document new ed25519-related lines.
---
 web/formats.html |   58 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 37 insertions(+), 21 deletions(-)

diff --git a/web/formats.html b/web/formats.html
index d8abf65..3d6c2ba 100644
--- a/web/formats.html
+++ b/web/formats.html
@@ -223,22 +223,24 @@ The sanitizing steps are as follows:
 </p>
 
 <ol>
-<li><b>Replace the bridge identity with its SHA1 value:</b> Clients
+<li><b>Replace bridge identities with their digests:</b> Clients
 can request a bridge's current descriptor by sending its identity string
 to the bridge authority.
 This is a feature to make bridges on dynamic IP addresses useful.
 Therefore, the original identities (and anything that could be used to
 derive them) need to be removed from the descriptors.
-The bridge identity is replaced with its SHA1 hash value.
+The bridge's RSA-based identity fingerprint is replaced with its SHA-1
+hash value, and the bridge's optional base64-encoded Ed25519 master key is
+replaced with its SHA-256 digest.
 The idea is to have a consistent replacement that remains stable over
 months or even years (without keeping a secret for a keyed hash
 function).</li>
-<li><b>Remove all cryptographic keys and signatures:</b> It would be
+<li><b>Remove most cryptographic keys and signatures:</b> It would be
 straightforward to learn about the bridge identity from the bridge's
 public key.
 Replacing keys by newly generated ones seemed to be unnecessary (and would
-involve keeping a state over months/years), so that all cryptographic
-objects have simply been removed.</li>
+involve keeping a state over months/years), so that most cryptographic
+keys and signatures have simply been removed.</li>
 <li><b>Replace IP address with IP address hash:</b> Of course, IP
 addresses need to be sanitized, too.
 <ul><li>IPv4 addresses are replaced with <tt>10.x.x.x</tt> with
@@ -267,12 +269,15 @@ information about these transports in their extra-info descriptors for
 BridgeDB.
 In that case, any IP addresses, TCP ports, or additional arguments are
 removed, only leaving in the supported transport names.</li>
-<li><b>Append descriptor digest:</b> Descriptors are often referenced by
-their digest, but that is not possible anymore once their content is
+<li><b>Append descriptor digests:</b> Descriptors are often referenced by
+their digest, but that is not possible anymore once their content has
 changed.
-As a workaround, sanitized descriptors may contain a new line
+As a workaround, sanitized descriptors contain a new line
 <tt>router-digest</tt> with the hex representation of the SHA-1 of the
-original descriptor digest.
+original descriptor digest excluding RSA signature and—if the bridge
+uses an Ed25519 identity—a new line <tt>router-digest-sha256</tt>
+with the base64-encoded SHA-256 of the SHA-256 digest of the original
+descriptor including all signatures.</li>
 </ol>
 
 <h3>Network statuses
@@ -295,7 +300,7 @@ descriptors of a given month, not just network statuses.
 (<a href="archive/bridge-descriptors/">archive</a>,
 <a href="recent/bridge-descriptors/server-descriptors/">recent</a>)
 <span class="type-annotation"><tt>@type bridge-server-descriptor
-1.0</tt></span>
+1.1</tt></span>
 </h3>
 
 <p>
@@ -309,20 +314,28 @@ files in
 <a href="recent/bridge-descriptors/server-descriptors/">recent</a>
 contain all descriptors collected in an hour concatenated into a single
 file to reduce the number of files.
+The format has changed over time to accomodate changes to the sanitizing
+process, with earlier versions being:
 </p>
 
-<p>
-There was supposed to be a newer version of this document that indicates
+<ul>
+<li><font color="#666"><tt>@type bridge-server-descriptor 1.0</tt> was the
+first version.</font></li>
+<li><font color="#666">There was supposed to be a newer version indicating
 added <tt>ntor-onion-key</tt> lines, but due to a mistake only the version
 number of sanitized bridge extra-info descriptors was raised.
-As a result, there may be sanitized bridge server descriptors with and
-without those lines.
-</p>
+As a result, there may be sanitized bridge server descriptors with version
+<tt>@type bridge-server-descriptor 1.0</tt> with and without those
+lines.</font></li>
+<li><tt>@type bridge-server-descriptor 1.1</tt> added
+<tt>master-key-ed25519</tt> lines and <tt>router-digest-sha256</tt> to
+server descriptors published by bridges using an Ed25519 master key.</li>
+</ul>
 
 <h3>Extra-info descriptors
 (<a href="archive/bridge-descriptors/">archive</a>,
 <a href="recent/bridge-descriptors/extra-infos/">recent</a>)
-<span class="type-annotation"><tt>@type bridge-extra-info 1.2</tt></span>
+<span class="type-annotation"><tt>@type bridge-extra-info 1.3</tt></span>
 </h3>
 
 <p>
@@ -336,11 +349,14 @@ process, with earlier versions being:
 <li><font color="#666"><tt>@type bridge-extra-info 1.0</tt> was the first
 version.</font></li>
 <li><font color="#666"><tt>@type bridge-extra-info 1.1</tt> added
-sanitized <tt>transport</tt> lines</font>.</li>
-<li><tt>@type bridge-extra-info 1.2</tt> was supposed to indicate added
-<tt>ntor-onion-key</tt> lines, but those changes only affect bridge server
-descriptors, not extra-info descriptors.
-So, nothing has changed as compared to version 1.1.</li>
+sanitized <tt>transport</tt> lines.</font></li>
+<li><font color="#666"><tt>@type bridge-extra-info 1.2</tt> was supposed
+to indicate added <tt>ntor-onion-key</tt> lines, but those changes only
+affect bridge server descriptors, not extra-info descriptors.
+So, nothing has changed as compared to version 1.1.</font></li>
+<li><tt>@type bridge-extra-info 1.3</tt> added <tt>master-key-ed25519</tt>
+lines and <tt>router-digest-sha256</tt> to extra-info descriptors
+published by bridges using an Ed25519 master key.</li>
 </ul>
 
 <p>