[tor-commits] [torspec/master] Prop 306: Minor fixes and tidying up
teor at torproject.org
teor at torproject.org
Wed Jan 15 12:50:37 UTC 2020
commit a78e23a053415a2aa498ff611e4131762a264d53
Author: teor <teor at torproject.org>
Date: Mon Jan 13 20:21:40 2020 +1000
Prop 306: Minor fixes and tidying up
* modify design to match Tor's typical design patterns
* add some missing info and special cases
* improve formatting and consistency
* fix some typos
Part of 29801.
---
proposals/306-ipv6-happy-eyeballs.txt | 109 ++++++++++++++++++++--------------
1 file changed, 66 insertions(+), 43 deletions(-)
diff --git a/proposals/306-ipv6-happy-eyeballs.txt b/proposals/306-ipv6-happy-eyeballs.txt
index 5055cc6..25381ad 100644
--- a/proposals/306-ipv6-happy-eyeballs.txt
+++ b/proposals/306-ipv6-happy-eyeballs.txt
@@ -71,28 +71,35 @@ Ticket: https://trac.torproject.org/projects/tor/ticket/29801
This will allow us to try IPv4 and the IPv6 addresses should both be
available on a relay and the client is dual-stack.
- When parsing relay descriptors and filling in the extend info data
- structure, we need to fill in both the IPv4 and IPv6 address if both are
- available. If only one family is available for a relay (IPv4 or IPv6), we
- should fill in the address for preferred family and leave the alternate
- family null.
+ When processing:
+ * relay descriptors,
+ * hard-coded authority and fallback directory lists,
+ * onion service descriptors, or
+ * onion service introduce cells,
+ and filling in the extend info data structure, we need to fill in both the
+ IPv4 and IPv6 address if both are available. If only one family is
+ available for a relay (IPv4 or IPv6), we should leave the other family null.
2.2. Guard Selection Changes
- In Proposal 283, we have allowed microdescriptor consensus documents
- to contain IPv6 addresses. As most clients download microdescriptor
- consensuses, Prop283 makes it possible to implement Prop306.
- When we select candidates for the entry node, we should have an option
- for the number of entry guards. The parameter is as follows:
+ When we select guard candidates, we should have an option for the number of
+ primary IPv6 entry guards. The parameter is as follows:
* NumIPv6Guards NUM
- If UseEntryGuards is set to 1, we will try to pick NUM routers that support
- IPv6 for our primary guard list, which is the set of routers we strongly
- prefer when connecting to the Tor network. If NUM is 0, we try to learn the
- number from the guard-n-primary-guards-ipv6 consensus parameter, and default
- to 1 if the consensus parameter isn’t set.
+ If UseEntryGuards is set to 1, we will try to pick NUM relays that support
+ IPv6 for our primary guard list, which is the set of relays we strongly
+ prefer when connecting to the Tor network. (This number should also apply
+ to all of Tor's other guard lists, scaled up based on the relative size of
+ the list.)
+
+ If NUM is -1, we try to learn the number from the NumIPv6Guards
+ consensus parameter. If the consensus parameter isn't set, we should
+ default to 1.
+
+ The default value for NumIPv6Guards should be -1. (Use the consensus
+ parameter, or the default value.)
The default value for NumIPv6Guards should be 0.
@@ -101,9 +108,10 @@ Ticket: https://trac.torproject.org/projects/tor/ticket/29801
If there is an existing authenticated connection, we must use it similar
to how we used it pre-Prop306.
- If there is no existing authenticated connection for an entry node, we
- must attempt to connect using the first available, allowed, and preferred
- address.
+ If there is no existing authenticated connection for an entry node, tor
+ currently attempts to connect using the first available, allowed, and
+ preferred address. (Determined using the existing Client IPv4 and IPv6
+ options.)
We should also allow falling back to the alternate address. For this,
a design will be given in Section 3.1.
@@ -111,7 +119,7 @@ Ticket: https://trac.torproject.org/projects/tor/ticket/29801
3.1. TCP Connection to Preferred Address On First TCP Success
In this design, we will connect via TCP to the first preferred address.
- On a failure or after a 250 ms delay, we attempt to connect via TCP to
+ On a failure or after a 250 msec delay, we attempt to connect via TCP to
the alternate address. On a success, Tor attempts to authenticate and
closes the other connection.
@@ -134,7 +142,7 @@ Ticket: https://trac.torproject.org/projects/tor/ticket/29801
As mentioned in [TEOR-P306-REP], initially, clients should prefer IPv4
by default. The Connection Attempt Delay, or delay between IPv4 and IPv6
- connections should be 250 ms. This is to avoid the overhead from tunneled
+ connections should be 250 msec. This is to avoid the overhead from tunneled
IPv6 connections.
The Minimum Connection Attempt Delay should not be dynamically adjusted
@@ -151,8 +159,8 @@ Ticket: https://trac.torproject.org/projects/tor/ticket/29801
recommendation of 2 seconds. For Tor, we should make this timeout value 30
seconds to match Tor's existing timeout.
- We should also make it possible for users to set the Maximum Connection
- Attempt value higher for slower and higher-latency networks such as dial-up
+ We need to make it possible for users to set the Maximum Connection Attempt
+ Delay value higher for slower and higher-latency networks such as dial-up
and satellite.
4. Option Changes
@@ -163,11 +171,11 @@ Ticket: https://trac.torproject.org/projects/tor/ticket/29801
The new default options should be:
- * ClientUseIPv4 as 1 (to enable IPv4)
+ * ClientUseIPv4 1 (to enable IPv4)
- * ClientUseIPv6 as 1 (to enable IPv6)
+ * ClientUseIPv6 1 (to enable IPv6)
- * ClientPreferIPv6ORPort as 0 (for load-balancing reasons so we don't
+ * ClientPreferIPv6ORPort 0 (for load-balancing reasons so we don't
overload IPv6-only guards)
* ConnectionAttemptDelay 10 (for 10 msec, the minimum delay between
@@ -175,30 +183,30 @@ Ticket: https://trac.torproject.org/projects/tor/ticket/29801
One thing to note is that clients should be able to connect with the above
options on IPv4-only, dual-stack, and IPv6-only networks, and they should
- also work if ClientPreferIPv6ORPort is 1. This means we shouldn't expect
- IPv4 or IPv6 to work if ClientUseIPv4 or ClientUseIPv6 is set.
+ also work if ClientPreferIPv6ORPort is 1. But we shouldn't expect
+ IPv4 or IPv6 to work if ClientUseIPv4 or ClientUseIPv6 is set to 0.
- When the majority of clients are IPv6-capable, we could set the default
- value of ClientPreferIPv6ORPort to 1 in order to take advantage of IPv6.
+ When the majority of clients and relay are IPv6-capable, we could set the
+ default value of ClientPreferIPv6ORPort to 1, in order to take advantage
+ of IPv6.
5. Relay Statistics
- Entry nodes could measure the following statistics from clients for both
- IPv4 and IPv6:
+ Entry nodes could measure the following statistics for both IPv4 and IPv6:
- * Number of successful connections
+ * Number of successful connections
- * Number of failed connections
-
- * Number of timed out connections
+ * Number of unsuccessful or cancelled connections
+ * Client closes the connection before completing TLS
+ * Client closes the connection before sending any circuit or data cells
Should we implement Section 5:
- * We could send this information to directory authorities
-
- * We should consider the privacy implications of these statistics
+ * We can send this information to the directory authorities using relay
+ extra-info descriptors
- * If submitted to dirauths, whether these should be public or not
+ * We should consider the privacy implications of these statistics, and
+ how much noise we need to add to them
6. Initial Feasibility Testing
@@ -220,8 +228,11 @@ Ticket: https://trac.torproject.org/projects/tor/ticket/29801
* Implementation of the algorithm in Section 3.1 along with the changes
described in Sections 2.1 and 2.2
- * The Connection Success/Failure mechanism in Section 3.2 and Connection
- Delay mechanism in Section 3.3 (the consensus parameter is optional)
+ * The Connection Success/Failure mechanism in Section 3.2.
+
+ * The Connection Delay mechanism in Section 3.3. (The
+ ConnectionAttemptDelay torrc option and consensus parameter are
+ optional.)
* A default setup capable of both IPv4 and IPv6 connections with the
options described in Section 4.1
@@ -230,12 +241,24 @@ Ticket: https://trac.torproject.org/projects/tor/ticket/29801
Some features which are optional include:
+ * Single Onion services: extend info address changes for onion service
+ descriptors and introduce cells. (Section 2.1.)
+
+ * Bridge clients are out of scope: they would require bridge line format
+ changes, internal bridge data structure changes, and extend info address
+ changes. (Section 2.1.)
+
+ * NumIPv6Guards torrc option and consensus parameter. We may need this
+ option if the proposed default doesn't work for some clients.
+ (Section 2.3.)
+
* Consensus Parameter ConnectionAttemptDelay (Section 3.3) - We will need
this if the Minimum Connection Attempt Delay needs to be dynamically
adjusted, for instance, if clients often fail IPv6 connections
- * Prop306 Statistics (Section 5) - While optional, this may be useful
- for debugging and reliability testing, and metrics on IPv4 vs IPv6
+ * IPv4, IPv6, and Prop306 connection Statistics. While optional, this may
+ be useful for debugging and reliability testing, and metrics on IPv4 vs
+ IPv6. (Section 5.)
9. Acknowledgments
More information about the tor-commits
mailing list