commit da1b248e2ef9f6b07b089ad95d05adf2f91ce3d9 Author: teor teor@torproject.org Date: Wed Feb 5 12:51:46 2020 +1000

Prop 312: Add State Management

Document tor's current address detection state management, and our new state management for IPv4 and IPv6 address detection.

As suggested by Nick Mathewson.

Part of 33073. --- proposals/312-relay-auto-ipv6-addr.txt | 114 +++++++++++++++++++++++++++++++-- 1 file changed, 108 insertions(+), 6 deletions(-)

diff --git a/proposals/312-relay-auto-ipv6-addr.txt b/proposals/312-relay-auto-ipv6-addr.txt index ed5ebac..c407dc1 100644 --- a/proposals/312-relay-auto-ipv6-addr.txt +++ b/proposals/312-relay-auto-ipv6-addr.txt @@ -98,7 +98,7 @@ Ticket: #33073 directory authorities only use addresses that are explicitly configured in their torrc.)

-3.1. Current Relay IPv4 Address Implementation +3.1. Current Relay IPv4 Address Discovery

Currently, all relays (and bridges) must have an IPv4 address. IPv6 addresses are optional for relays. @@ -124,6 +124,66 @@ Ticket: #33073 * the latest address(es) returned by a directory server, DNS, or the local interface API.

+3.1.1. Current Relay IPv4 and IPv6 Address State Management + + Currently, relays (and bridges) manage their IPv4 address discovery state, + as described in the following table: + + a b c d e f + 1. Address literal . . . . . . + 1. Address hostname S N . . . T + 2. auto hostname S N . . F T + 3. auto interface ? ? . . F ? + 3. auto socket ? ? . . F ? + 4. auto dir header D N D D F A + + IPv6 address discovery only uses the first IPv6 ORPort address: + + a b c d e f + 1. ORPort listener . . C . F . + 1. ORPort literal . . C C F . + 1. ORPort hostname S N C C F T + + The tables are structured as follows: + * rows are address resolution stage variants + * each address resolution stage has a number, and a description + * the description includes any variants + (for example: IP address literal, or hostname) + * columns describe each variant's state management. + + The state management key is: + a. What kind of API is used to perform the address resolution? + * . a CPU-bound API + * S a synchronous query API + * ? an API that is probably CPU-bound, but may be synchronous on some + platforms + * D tor automatically updates the stored directory address, whenever a + directory document is received + b. What does the API depend on? + * . a CPU-bound API + * N a network-bound API + * ? an API that is probably CPU-bound, but may be network-bound on some + platforms + c. How are any discovered addresses stored? + * . addresses are not stored + (but they may be cached by some higher-level tor modules) + * D addresses are stored in the directory address suggestion variable + * C addresses are stored in the port config listener list + d. What event makes the address resolution happen? + * . when tor wants to know its own address + * D when a directory document is received + * C when tor parses its config at startup, and during reconfiguration + e. What conditions make tor attempt this address resolution method? + * . this method is always attempted + * F this method is only attempted when all other higher-priority + methods fail to return an address + f. Can this method timeout? + * . can't time out + * T might time out + * ? probably doesn't time out, but might time out on some platforms + * A can't time out, because it is asynchronous. If a stored address + is available, it is returned immediately. + 3.2. Finding Relay IPv6 Addresses

We propose that relays (and bridges) try to find their IPv6 address. For @@ -251,8 +311,8 @@ Ticket: #33073 The ORPort address may be a hostname. If it is, tor should try to use it to resolve an IPv4 and IPv6 address, and open ORPorts on the first available IPv4 and IPv6 address. Tor should respect the IPv4Only and IPv6Only port - flags, if specified. (Tor currently resolves IPv4 addresses in ORPort - lines. It might not look for an IPv6 address.) + flags, if specified. (Tor currently resolves IPv4 and IPv6 addresses from + hostnames in ORPort lines.)

Relays (and bridges) currently use the first advertised ORPort IPv6 address as their IPv6 address. We propose to use the first advertised IPv4 ORPort @@ -265,6 +325,18 @@ Ticket: #33073 In rare cases, relays may have been using non-advertised ORPorts for their addresses. This change may also change their addresses.

+ Tor currently uses its listener port list to look up its IPv6 ORPort for + its descriptor. We propose that tor's address discovery uses the listener + port list for both IPv4 and IPv6. (And does not attempt to independently + parse or resolve ORPort configs.) + + This design decouples ORPort option parsing, ORPort listener opening, and + address discovery. It also implements a form of caching: IPv4 and IPv6 + addresses resolved from hostnames are stored in the listener port list, + then used to open listeners. Therefore, tor should continue to use the same + address, while the listener remains open. (See also sections 3.2.7 and + 3.2.8.) + For security reasons, directory authorities only use addresses that are explicitly configured in their torrc. Therefore, we propose that directory authorities only accept IPv4 or IPv6 address literals in the address part @@ -460,15 +532,18 @@ Ticket: #33073 3.2.7. Automatically Enabling an IPv6 ORPort

We propose that relays (and bridges) that discover their IPv6 address, - should open an ORPort on that address, and test its reachability (see + should open an IPv6 ORPort, and test its reachability (see [Proposal 311: Relay IPv6 Reachability], particularly section 4.3.1).

The ORPort should be opened on the port configured in the relay's ORPort torrc option. Relay operators can use the IPv4Only and IPv6Only options to configure different ports for IPv4 and IPv6.

- If an ORPort is configured, but there is no specific bind address, relays - may attempt to bind to all IPv4 and IPv6 addresses (or all interfaces). + If the ORPort is auto-detected, there will not be any specific bind + address. (And the detected address may actually be on a NAT box, rather + than the local machine.) Therefore, relays should attempt to bind to all + IPv4 and IPv6 addresses (or all interfaces). + Some operating systems expect applications to bind to IPv4 and IPv6 addresses using separate API calls. Others don't support binding only to IPv4 or IPv6, and will bind to all addresses whenever there is no specified @@ -484,6 +559,33 @@ Ticket: #33073 * stop publishing their IPv6 ORPort in their descriptor, and * log a notice about the failed IPv6 ORPort reachability check.

+3.2.8. Proposed Relay IPv4 and IPv6 Address State Management + + We propose that relays (and bridges) manage their IPv4 and IPv6 address + discovery state, as described in the following table: + + a b c d e f + 1. Address literal . . . . . . + 1. Address hostname S N . . . T + 2. ORPort listener . . C . F . + 2. ORPort literal . . C C F . + 2. ORPort hostname S N C C F T + 3. auto interface ? ? . . F ? + 3. auto socket ? ? . . F ? + 4. auto hostname S N . . F T + 5. auto dir header D N D D F A + + See section 3.1.1 for a description and key for this table. See the rest of + section 3.2 for a detailed description of each method and variant. + + For security reasons, directory authorities only use addresses that are + explicitly configured in their torrc. Therefore, they stop after step 2. + (And don't use the "hostname" variants in steps 1 and 2.) + + For anonymity reasons, bridges are unable to fetch directory documents over + IPv6, until clients start to do so. (See + [Proposal 306: Client Auto IPv6 Connections].) + 3.3. Consequential Tor Client Changes

We do not propose any required client address resolution changes at this