[tor-commits] [torspec/master] easy and hopefully uncontroversial fixes to guard-spec

Fri May 19 04:25:18 UTC 2017

commit 4daf3db96ce162ca25d05e77a849e774579898c4
Author: Roger Dingledine <arma at 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.

