commit 11179b2eb314a740b0e893bc9a0f8a9e8663fae6 Author: Karsten Loesing karsten.loesing@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>