commit b729833befc66d94ce0510356290586e43402dee Author: Nick Mathewson nickm@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