commit 4daf3db96ce162ca25d05e77a849e774579898c4 Author: Roger Dingledine arma@torproject.org Date: Fri May 19 00:24:48 2017 -0400

easy and hopefully uncontroversial fixes to guard-spec

please do feel free to look through and make sure i didn't break anything though :) --- guard-spec.txt | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-)

diff --git a/guard-spec.txt b/guard-spec.txt index dc9f865..267edab 100644 --- a/guard-spec.txt +++ b/guard-spec.txt @@ -18,11 +18,11 @@ sample of every user's traffic with probability 1.

To prevent this from happening, Tor clients choose a small number - of guard nodes (currently 3). These guard nodes are the only + of guard nodes (e.g. 3). These guard nodes are the only nodes that the client will connect to directly. If they are not compromised, the user's paths are not compromised.

- This proposal outlines Tor's current guard selection algorithm, + This specification outlines Tor's guard selection algorithm, which tries to meet the following goals:

- Heuristics and algorithms for determining how and which guards @@ -35,7 +35,7 @@ usability.

- Tor should make a best attempt at discovering the most - appropriate behaviour, with as little user input and + appropriate behavior, with as little user input and configuration as possible.

- Tor clients should discover usable guards without too much @@ -109,7 +109,7 @@ required. An exit node is required if traffic will exit the Tor network. Depending on its configuration, a relay listed in a consensus could be used for any of these roles. However, this - proposal defines how entry guards specifically should be selected and + specification defines how entry guards specifically should be selected and managed, as opposed to middle or exit nodes.

3.1.1 Entry guard selection @@ -144,7 +144,8 @@

Middle nodes are selected at random from relays listed in the latest consensus, weighted by bandwidth. Exit nodes are chosen - similarly but restricted to relays with an exit policy. + similarly but restricted to relays with a sufficiently permissive + exit policy.

3.2 Circuit Building

@@ -222,7 +223,7 @@ We require that {SAMPLED_GUARDS} contain at least {MIN_FILTERED_SAMPLE} guards from the consensus (if possible), but not more than {MAX_SAMPLE_THRESHOLD} of the number of guards - in the consensus, and not more then {MAX_SAMPLE_SIZE} in total. + in the consensus, and not more than {MAX_SAMPLE_SIZE} in total. (But if the maximum would be smaller than {MIN_FILTERED_SAMPLE}, we set the maximum at {MIN_FILTERED_SAMPLE}.)

@@ -274,7 +275,7 @@ - It is a member of {SAMPLED_GUARDS}, with {IS_LISTED} set to true. - It is not disabled because of path bias issues. - - It is not disabled because of ReachableAddress police, + - It is not disabled because of ReachableAddresses policy, the ClientUseIPv4 setting, the ClientUseIPv6 setting, the FascistFirewall setting, or some other option that prevents using some addresses. @@ -316,7 +317,7 @@ order of using them. It is a subset of {SAMPLED_GUARDS}. For each guard in this list, we store persistently:

- - {pvar:IDENTITY} Its fingerprint + - {pvar:IDENTITY} Its fingerprint.

- {pvar:CONFIRMED_ON_DATE} When we added this guard to {CONFIRMED_GUARDS}. @@ -346,7 +347,7 @@ {is_pending}==true guards have higher priority.

* Among those, the guard with earlier {last_tried_connect} time - have higher priority. + has higher priority.

* Finally, among guards that do not appear in {CONFIRMED_GUARDS} with {is_pending==false}, all have equal @@ -509,10 +510,10 @@ When a circuit fails in a way that makes us conclude that a guard is not reachable, we take the following steps:

- * We set the guard's {is_reachable} status to <no>. If it had + * Set the guard's {is_reachable} status to <no>. If it had {is_pending} set to true, we make it non-pending.

- * We close the circuit, of course. (This removes it from + * Close the circuit, of course. (This removes it from consideration by the algorithm in [UPDATE_WAITING].)

* Update the list of waiting circuits. (See [UPDATE_WAITING] @@ -580,7 +581,7 @@

We run this procedure periodically:

- * If any circuit stays is <waiting_for_better_guard> + * If any circuit stays in <waiting_for_better_guard> for more than {NONPRIMARY_GUARD_IDLE_TIMEOUT} seconds, time it out.

@@ -597,7 +598,7 @@ them after all if the <complete> circuit goes down before {NONPRIMARY_GUARD_IDLE_TIMEOUT} seconds.

-4.10. Whenever we get a new consensus. [Section:ON_CONSENSUS] +4.10. Whenever we get a new consensus. [Section:ON_CONSENSUS]

We update {GUARDS}.

@@ -619,7 +620,7 @@ 4.11. Deciding whether to generate a new circuit. [Section:NEW_CIRCUIT_NEEDED]

- In current Tor, we generate a new circuit when we don't have + We generate a new circuit when we don't have enough circuits either built or in-progress to handle a given stream, or an expected stream.

@@ -627,7 +628,7 @@ 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 +4.12. When we are missing descriptors. [Section:MISSING_DESCRIPTORS]

We need either a router descriptor or a microdescriptor in order @@ -757,7 +758,7 @@ A.3. Controller changes A.4. Persistent state format

The persistent state format doesn't need to be part of this - proposal, since different implementations can do it + specification, since different implementations can do it differently. Nonetheless, here's the one Tor uses:

The "state" file contains one Guard entry for each sampled guard @@ -767,7 +768,7 @@ A.4. Persistent state format any nonspace characters.

Implementations must retain any unrecognized K=V entries for a - sampled guard when the regenerate the state file. + sampled guard when they regenerate the state file.

The order of K=V entries is not allowed to matter.

@@ -794,7 +795,7 @@ A.4. Persistent state format "unlisted_since" -- the date since which the guard has been unlisted. Optional.

- "listed" -- 0 if the guard is not listed ; 1 if it is. Required. + "listed" -- 0 if the guard is not listed; 1 if it is. Required.

"confirmed_on" -- date when the guard was confirmed. Optional. @@ -834,7 +835,7 @@ TODO. Still non-addressed issues [Section:TODO] We don't need to worry about directory guards for relays, since we aren't trying to prevent relay enumeration.

- IP version preferenes via ClientPreferIPv6ORPort + IP version preferences via ClientPreferIPv6ORPort

Suggestion: Treat it as a preference when adding to {CONFIRMED_GUARDS}, but not otherwise.