Browse Source

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.
Nick Mathewson 2 years ago
parent
commit
b729833bef
2 changed files with 53 additions and 2 deletions
  1. 20 2
      guard-spec.txt
  2. 33 0
      path-spec.txt

+ 20 - 2
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

+ 33 - 0
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