Start a new guard-spec.txt as a copy of prop271.

Remove the old guard section of path-spec, now that guard-spec is
separate.

1 files changed, 6 insertions, 117 deletions

diff --git a/path-spec.txt b/path-spec.txt
index 47dae3b..ceb6c77 100644
--- a/path-spec.txt
+++ b/path-spec.txt
@@ -554,123 +554,12 @@ of their choices.
 
 5. Guard nodes
 
-  We use Guard nodes (also called "helper nodes" in the literature) to
-  prevent certain profiling attacks.  Here's the risk: if we choose entry and
-  exit nodes at random, and an attacker controls C out of N relays
-  (ignoring bandwidth), then the
-  attacker will control the entry and exit node of any given circuit with
-  probability (C/N)^2.  But as we make many different circuits over time,
-  then the probability that the attacker will see a sample of about (C/N)^2
-  of our traffic goes to 1.  Since statistical sampling works, the attacker
-  can be sure of learning a profile of our behavior.
-
-  If, on the other hand, we picked an entry node and held it fixed, we would
-  have probability C/N of choosing a bad entry and being profiled, and
-  probability (N-C)/N of choosing a good entry and not being profiled.
-
-  When guard nodes are enabled, Tor maintains an ordered list of entry nodes
-  as our chosen guards, and stores this list persistently to disk.  If a Guard
-  node becomes unusable, rather than replacing it, Tor adds new guards to the
-  end of the list.  When choosing the first hop of a circuit, Tor
-  chooses at
-  random from among the first NumEntryGuards (default 3) usable guards on the
-  list.  If there are not at least 2 usable guards on the list, Tor adds
-  routers until there are, or until there are no more usable routers to add.
-
-  A guard is unusable if any of the following hold:
-    - it is not marked as a Guard by the networkstatuses,
-    - it is not marked Valid (and the user hasn't set AllowInvalid entry)
-    - it is not marked Running
-    - Tor couldn't reach it the last time it tried to connect
-
-  A guard is unusable for a particular circuit if any of the rules for path
-  selection in 2.2 are not met.  In particular, if the circuit is "fast"
-  and the guard is not Fast, or if the circuit is "stable" and the guard is
-  not Stable, or if the guard has already been chosen as the exit node in
-  that circuit, Tor can't use it as a guard node for that circuit.
-
-  If the guard is excluded because of its status in the networkstatuses for
-  over 30 days, Tor removes it from the list entirely, preserving order.
-
-  If Tor fails to connect to an otherwise usable guard, it retries
-  periodically: every hour for six hours, every 4 hours for 3 days, every
-  18 hours for a week, and every 36 hours thereafter.  Additionally, Tor
-  retries unreachable guards the first time it adds a new guard to the list,
-  since it is possible that the old guards were only marked as unreachable
-  because the network was unreachable or down.
-
-  Tor does not add a guard persistently to the list until the first time we
-  have connected to it successfully.
-
-5.1. Guard selection algorithm
-
-  If configured to use entry guards, and the circuit's purpose is not marked
-  for testing, then a random entry guard from the persisted state (as
-  mentioned earlier in §5) will be chosen (provided there is already some
-  persisted state storing previously chosen guard nodes).
-
-  Otherwise, if any the above conditions are not satisfied, then a new entry
-  guard node will be chosen for that circuit.  The algorithm is as follows:
-
-    - EXCLUDED_NODES is a list of nodes which, for some reason, are not
-      acceptable for use as an entry guard.
-
-    1. If an exit node has been chosen for the circuit:
-
-       1.a. Then that exit is added to EXCLUDED_NODES (and thus will not be
-            used as the entry guard).
-
-    2. If running behind a fascist firewall (e.g. outgoing connections are
-       only permitted to ports 80 and/or 443):
-
-       2.a. For all known routers in the network (as given in the
-            networkstatus document), a router is added to the list of
-            EXCLUDED_NODES iff it does not advertise the ability to be reached
-            via the ports allowed through the fascist firewall.
-
-    3. Add any entry guards currently in volatile storage, as well as all
-       nodes within their families, to EXCLUDED_NODES.
-
-    4. Determine which of the following flags should apply to the selection of
-       an entry guard:
-
-         * CRN_NEED_UPTIME: the router can only be chosen as an entry guard
-           iff has been available for at least some minimum uptime.
-         * CRN_NEED_CAPACITY: potentially suitable routers are weighted by
-           their advertised bandwidth capacity.
-         * CRN_ALLOW_INVALID: also consider using routers which have been
-           marked as invalid.
-         * CRN_NEED_GUARD: only consider routers which have the Guard flag.
-         * CRN_NEED_DESC: only consider routers for which we have enough
-           information to be used to build a circuit.
-
-       Additionally, if configured to allow nodes marked as invalid AND to
-       specifically allow entry guards which have been marked as invalid, then
-       the CRN_ALLOW_INVALID flag will be set.  Lastly, the CRN_NEED_GUARD and
-       CRN_NEED_DESC flags are always applied, regardless of configuration.
-
-    5. If configured to exclude routers which allow single-hop circuits, then
-       the list of known routers is traversed, and all routers which permit
-       single-hop circuits are added to EXCLUDED_NODES.
-
-    6. If we are an OR, add ourselves (and our family) to EXCLUDED_NODES.
-
-    7. The list of potential routers is weighted according to the bandwidth
-       weights from the consensus (cf. §5.1.1), and then a random selection is
-       chosen with respect to those weights.
-
-       7.a. If we've made a choice now, the algorithm finishes.
-       7.b. Otherwise, continue to step #8.
-
-    8. We couldn't find a suitable guard, so now we try much harder by
-       discarding the CRN_NEED_UPTIME, CRN_NEED_CAPACITY, and CRN_NEED_GUARD
-       selection flags.  This effectively means we'll use nearly any router,
-       except for ones already in EXCLUDED_LIST.
-
-       [XXX Does this mean we even include BadExits and other misbehaving
-       nodes?  This sounds bad.  —isis]
-
-5.1.1. How consensus bandwidth weights factor into entry guard selection
+  We use Guard nodes (also called "helper nodes" in the research
+  literature) to prevent certain profiling attacks. For an overview of
+  our Guard selection algorithm -- which has grown rather complex -- see
+  guard-spec.txt.
+
+5.1. How consensus bandwidth weights factor into entry guard selection
 
   When weighting a list of routers for choosing an entry guard, the following
   consensus parameters (from the "bandwidth-weights" line) apply: