[tor-commits] [torspec/master] Explain more about primary guards and about building circuits

[nickm at torproject.org]

commit b729833befc66d94ce0510356290586e43402dee
Author: Nick Mathewson <nickm at torproject.org>
Date:   Wed Feb 1 08:54:07 2017 -0500

    Explain more about primary guards and about building circuits
    
    In path-spec: explain our rules (post-21242) for waiting to build
    circuits.
    
    In guard-spec:
      - explain what to do about missing descriptors
      - explain parallel use of multiple primary guards, based on parameters.
---
 guard-spec.txt | 22 ++++++++++++++++++++--
 path-spec.txt  | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+), 2 deletions(-)

diff --git a/guard-spec.txt b/guard-spec.txt
index 59c66b8..87e16a7 100644
--- a/guard-spec.txt
+++ b/guard-spec.txt
@@ -451,8 +451,10 @@
   When we want to build a circuit, and we need to pick a guard:
 
     * If any entry in PRIMARY_GUARDS has {is_reachable} status of
-      <maybe> or <yes>, return the first such guard. The circuit is
-      <usable_on_completion>.
+      <maybe> or <yes>, return one of the first
+      {NUM_USABLE_PRIMARY_GUARDS} or
+      {NUM_USABLE_PRIMARY_DIRECTORY_GUARDS} such guards, chosen
+      uniformly at random. The circuit is <usable_on_completion>.
 
       [Note: We do not use {is_pending} on primary guards, since we
       are willing to try to build multiple circuits through them
@@ -620,6 +622,18 @@
    circuits are neither built nor in-progress; that <complete>
    circuits are built; and that the other states are in-progress.
 
+4.12. When we are missing descriptors
+   [Section:MISSING_DESCRIPTORS]
+
+   We need either a router descriptor or a microdescriptor in order
+   to build a circuit through a guard.  If we do not have such a
+   descriptor for a guard, we can still use the guard for one-hop
+   directory fetches, but not for longer circuits.
+
+   (Also, when we are missing descriptors for our first
+   {NUM_USABLE_PRIMARY_GUARDS} primary guards, we don't build
+   circuits at all until we have fetched them.)
+
 A. Appendices
 
 A.1.  Parameters with suggested values. [Section:PARAM_VALS]
@@ -663,6 +677,10 @@ A.1.  Parameters with suggested values. [Section:PARAM_VALS]
 
    {param:GUARD_CONFIRMED_MIN_LIFETIME} -- 60 days
 
+   {param:NUM_USABLE_PRIMARY_GUARDS} -- 1
+
+   {param:NUM_USABLE_PRIMARY_DIRECTORY_GUARDS} -- 3
+
 A.2. Random values [Section:RANDOM]
 
    Frequently, we want to randomize the expiration time of something
diff --git a/path-spec.txt b/path-spec.txt
index ceb6c77..6e88cb3 100644
--- a/path-spec.txt
+++ b/path-spec.txt
@@ -112,6 +112,39 @@ of their choices.
 
 2.1. When we build
 
+2.1.0. We don't build circuits until we have enough directory info
+
+   There's a class of possible attacks where our directory servers
+   only give us information about the relays that they would like us
+   to use.  To prevent this attack, we don't build multi-hop
+   circuits for real traffic (like those in 2.1.1, 2.1.2, 2.1.4
+   below) until we have enough directory information to be
+   reasonably confident this attack isn't being done to us.
+
+   Here, "enough" directory information is defined as:
+
+      * Having a consensus that's been valid at some point in the
+        last REASONABLY_LIVE_TIME interval (24 hourts).
+
+      * Having enough descriptors that we could build at least some
+        fraction F of all bandwidth-weighted paths, without taking
+        ExitNodes/EntryNodes/etc into account.
+
+        (F is set by the PathsNeededToBuildCircuits option,
+        defaulting to the 'min_paths_for_circs_pct' consensus
+        parameter, with a final default value of 60%.)
+
+      * Having enough descriptors that we could build at least some
+        fraction F of all bandwidth-weighted paths, _while_ taking
+        ExitNodes/EntryNodes/etc into account.
+
+        (F is as above.)
+
+      * Having a descriptor for every one of the first
+        NUM_GUARDS_TO_USE guards among our primary guards. (see
+        guard-spec.txt)
+
+
 2.1.1. Clients build circuits preemptively
 
    When running as a client, Tor tries to maintain at least a certain