[tor-commits] [metrics-web/master] Link to new Tor bridge descriptors specification.

Sat Aug 5 20:54:34 UTC 2017

commit 8e15643cbcce09add914fe98905ec2117cf58b7d
Author: Karsten Loesing <karsten.loesing at gmx.net>
Date:   Sat Aug 5 22:23:04 2017 +0200

    Link to new Tor bridge descriptors specification.
---
 .../src/main/resources/web/WEB-INF/collector.jsp   | 83 +---------------------
 website/src/main/resources/web/WEB-INF/sources.jsp | 11 +++
 2 files changed, 13 insertions(+), 81 deletions(-)

diff --git a/website/src/main/resources/web/WEB-INF/collector.jsp b/website/src/main/resources/web/WEB-INF/collector.jsp
index 4b37e5e..f57ccb8 100644
--- a/website/src/main/resources/web/WEB-INF/collector.jsp
+++ b/website/src/main/resources/web/WEB-INF/collector.jsp
@@ -366,89 +366,10 @@ descriptors, because that would defeat the purpose of making bridges hard
 to enumerate for censors.
 We therefore sanitize bridge descriptors by removing all potentially
 identifying information and publish sanitized versions here.
-The sanitizing steps are as follows:
+The sanitizing steps are specified in detail on a separate
+<a href="bridge-descriptors.html">page</a>.
 </p>
 
-<ol>
-<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'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 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 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 <code>10.x.x.x</code> with
-<code>x.x.x</code> being the 3 byte output of
-<code>H(IP address | bridge identity | secret)[:3]</code>.
-The input <code>IP address</code> is the 4-byte long binary representation of
-the bridge's current IP address.
-The <code>bridge identity</code> is the 20-byte long binary representation of
-the bridge's long-term identity fingerprint.
-The <code>secret</code> is a 31-byte long secure random string that changes
-once per month for all descriptors and statuses published in that month.
-<code>H()</code> is SHA-256.
-The <code>[:3]</code> operator means that we pick the 3 most significant bytes
-of the result.</li>
-<li>IPv6 addresses are replaced with <code>[fd9f:2e19:3bcf::xx:xxxx]</code>
-with <code>xx:xxxx</code> being the hex-formatted 3 byte output of a similar
-hash function as described for IPv4 addresses.
-The only differences are that the input <code>IP address</code> is 16 bytes
-long and the <code>secret</code> is only 19 bytes long.</li></ul></li>
-<li><b>Replace TCP port with TCP port hash:</b> It may be less obvious
-that TCP ports need to be sanitized, but an unusual TCP port used by a
-high-value bridge might still stand out and provide yet another way to
-locate and block the bridge.
-Therefore, each non-zero TCP port is replaced with a number in the range
-from 49152 to 65535 that is the result of
-<code>H(port | bridge identity | secret)[:2] / 2^2 + 2^15 + 2^14</code>
-written as decimal number.
-The input <code>port</code> is the 2-byte long binary representation of the
-TCP port.
-The <code>bridge identity</code> is the 20-byte long binary representation of
-the bridge's long-term identity fingerprint.
-The <code>secret</code> is a 33-byte long secure random string that changes
-once per month for all descriptors and statuses published in that month.
-<code>H()</code> is SHA-256.
-The <code>[:2]</code> operator means that we pick the 2 most significant bytes
-of the result.
-The subsequent integer division and additions make sure that sanitized
-ports are in the range from 49152 to 65535 which is reserved for private
-services.
-All operations assume inputs to be in network byte order.
-TCP ports that are 0 in the original descriptor are left unchanged.</li>
-<li><b>Replace contact information:</b> If there is contact information in
-a descriptor, the contact line is changed to
-<code>somebody</code>.</li>
-<li><b>Remove pluggable transport addresses and arguments:</b> Bridges may
-provide transports in addition to the onion-routing protocol and include
-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 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 contain a new line
-<code>router-digest</code> with the hex representation of the SHA-1 of the
-original descriptor digest excluding RSA signature and—if the bridge
-uses an Ed25519 identity—a new line <code>router-digest-sha256</code>
-with the base64-encoded SHA-256 of the SHA-256 digest of the original
-descriptor including all signatures.</li>
-</ol>
-
 <h3 id="type-bridge-network-status" class="hover">Bridge Network Statuses
 <small><code>@type bridge-network-status 1.2</code></small>
 <a href="https://collector.torproject.org/recent/bridge-descriptors/statuses/" target="_blank" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a>
diff --git a/website/src/main/resources/web/WEB-INF/sources.jsp b/website/src/main/resources/web/WEB-INF/sources.jsp
index 43a926b..a0f5460 100644
--- a/website/src/main/resources/web/WEB-INF/sources.jsp
+++ b/website/src/main/resources/web/WEB-INF/sources.jsp
@@ -41,5 +41,16 @@
       </ul>
     </div>
 
+    <div class="container">
+      <h2>Specifications <a href="#specifications" name="specifications" class="anchor">#</a></h2>
+      <p>The following specification documents are available for Tor network data.</p>
+      <ul>
+        <li><a href="https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt" target="_blank">Tor directory protocol, version 3</a></li>
+        <li><a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v2.txt" target="_blank">Tor directory protocol, version 2</a></li>
+        <li><a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v1.txt" target="_blank">Tor directory protocol, version 1</a></li>
+        <li><a href="bridge-descriptors.html">Tor bridge descriptors</a></li>
+      </ul>
+    </div>
+
 <jsp:include page="bottom.jsp"/>
 

