[tor-commits] [torspec/master] In specs, do not say "server" when we mean "relay" or "node"

commit 56a66372d492afd964d4c92537f79020e213b5cb Author: Nick Mathewson nickm@torproject.org Date: Mon May 9 10:36:59 2011 -0400

In specs, do not say "server" when we mean "relay" or "node"

Fixes bug 2936. --- control-spec.txt | 10 +++++----- dir-spec.txt | 44 ++++++++++++++++++++++---------------------- path-spec.txt | 20 ++++++++++---------- tor-spec.txt | 52 ++++++++++++++++++++++++++-------------------------- 4 files changed, 63 insertions(+), 63 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt index 5878d75..c0a0a0e 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -25,7 +25,7 @@ TC is a bidirectional message-based protocol. It assumes an underlying stream for communication between a controlling process (the "client" or "controller") and a Tor process (or "server"). The stream may be - implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on, + implemented via TCP, TLS-over-TCP, a Unix-doma2in socket, or so on, but it must provide reliable in-order delivery. For security, the stream should not be accessible by untrusted parties.

@@ -467,7 +467,7 @@ have no guess, return a 551 error. (Added in 0.1.2.2-alpha)

"fingerprint" -- the contents of the fingerprint file that Tor - writes as a server, or a 551 if we're not a server currently. + writes as a relay, or a 551 if we're not a relay currently. (Added in 0.1.2.3-alpha)

"circuit-status" @@ -509,7 +509,7 @@ [From 0.1.1.4-alpha to 0.1.1.10-alpha, entry-guards was called "helper-nodes". Tor still supports calling "helper-nodes", but it is deprecated and should not be used.] - + [Older versions of Tor (before 0.1.2.x-final) generated 'down' instead of unlisted/unusable. Current Tors never generate 'down'.]

@@ -1609,8 +1609,8 @@ Our DNS provider is giving a hijacked address instead of well-known websites; Tor will not try to be an exit node.

- {Controllers could warn the admin if the server is running as an - exit server: the admin needs to configure a good DNS server. + {Controllers could warn the admin if the relay is running as an + exit node: the admin needs to configure a good DNS server. Alternatively, this happens a lot in some restrictive environments (hotels, universities, coffeeshops) when the user hasn't registered.}

diff --git a/dir-spec.txt b/dir-spec.txt index 589b0e9..0e17e6e 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -178,8 +178,8 @@ any missing router descriptors. Clients download missing descriptors from caches; caches and authorities download from authorities. Descriptors are downloaded by the hash of the descriptor, not by the - server's identity key: this prevents servers from attacking clients by - giving them descriptors nobody else uses. + relay's identity key: this prevents directory servers from attacking + clients by giving them descriptors nobody else uses.

All directory information is uploaded and downloaded with HTTP.

@@ -402,8 +402,8 @@ "average" bandwidth is the volume per second that the OR is willing to sustain over long periods; the "burst" bandwidth is the volume that the OR is willing to sustain in very short intervals. The "observed" - value is an estimate of the capacity this server can handle. The - server remembers the max bandwidth sustained output over any ten + value is an estimate of the capacity this relay can handle. The + relay remembers the max bandwidth sustained output over any ten second period in the past day, and another sustained input. The "observed" value is the lesser of these two numbers.

@@ -438,7 +438,7 @@

[At most once]

- If the value is 1, then the Tor server was hibernating when the + If the value is 1, then the Tor relay was hibernating when the descriptor was published, and shouldn't be used to build circuits.

[We didn't start parsing this line until Tor 0.1.0.6-rc; it should be @@ -490,14 +490,14 @@

[At most once]

- Describes a way to contact the server's administrator, preferably + Describes a way to contact the relay's administrator, preferably including an email address and a PGP key fingerprint.

"family" names NL

[At most once]

- 'Names' is a space-separated list of server nicknames or + 'Names' is a space-separated list of relay nicknames or hexdigests. If two ORs list one another in their "family" entries, then OPs should treat them as a single OR for the purpose of path selection. @@ -530,7 +530,7 @@ dns logic. Versions of Tor with this field set to false SHOULD NOT be used for reverse hostname lookups.

- [This option is obsolete. All Tor current servers should be presumed + [This option is obsolete. All Tor current relays should be presumed to have the evdns backend.]

"caches-extra-info" NL @@ -591,7 +591,7 @@ [At most once.]

Present only if the router allows single-hop circuits to make exit - connections. Most Tor servers do not support this: this is + connections. Most Tor relays do not support this: this is included for specialized controllers designed to support perspective access and such.

@@ -913,7 +913,7 @@ nickname ::= between 1 and 19 alphanumeric characters ([A-Za-z0-9]), case-insensitive. hexdigest ::= a '$', followed by 40 hexadecimal characters - ([A-Fa-f0-9]). [Represents a server by the digest of its identity + ([A-Fa-f0-9]). [Represents a relay by the digest of its identity key.]

exitpattern ::= addrspec ":" portspec @@ -1138,7 +1138,7 @@

[At most once.]

- A comma-separated list of recommended Tor versions for server + A comma-separated list of recommended Tor versions for relay usage, in ascending order. The versions are given as defined by version-spec.txt. If absent, no opinion is held about server versions. @@ -1319,7 +1319,7 @@

[At most once.]

- The version of the Tor protocol that this server is running. If + The version of the Tor protocol that this relay is running. If the value begins with "Tor" SP, the rest of the string is a Tor version number, and the protocol is "The Tor protocol as supported by the given version of Tor." Otherwise, if the value begins with @@ -1335,7 +1335,7 @@

[At most once.]

- An estimate of the bandwidth of this server, in an arbitrary + An estimate of the bandwidth of this relay, in an arbitrary unit (currently kilobytes per second). Used to weight router selection.

@@ -1446,7 +1446,7 @@ believes the given name should be bound to the given key.

Two strategies exist on the current network for deciding on - values for the Named flag. In the original version, server + values for the Named flag. In the original version, relay operators were asked to send nickname-identity pairs to a mailing list of Naming directory authorities operators. The operators were then supposed to add the pairs to their @@ -1515,13 +1515,13 @@ serves v2 hidden service descriptors and the authority managed to connect to it successfully within the last 24 hours.

- Directory server administrators may label some servers or IPs as + Directory server administrators may label some relays or IPs as blacklisted, and elect not to include them in their network-status lists.

- Authorities SHOULD 'disable' any servers in excess of 3 on any single IP. + Authorities SHOULD 'disable' any relays in excess of 3 on any single IP. When there are more than 3 to choose from, authorities should first prefer authorities to non-authorities, then prefer Running to non-Running, and - then prefer high-bandwidth to low-bandwidth. To 'disable' a server, the + then prefer high-bandwidth to low-bandwidth. To 'disable' a relay, the authority *should* advertise it without the Running or Valid flag.

Thus, the network-status vote includes all non-blacklisted, @@ -2270,17 +2270,17 @@ 6. Using directory information

Everyone besides directory authorities uses the approaches in this section - to decide which servers to use and what their keys are likely to be. + to decide which relays to use and what their keys are likely to be. (Directory authorities just believe their own opinions, as in 3.1 above.)

6.1. Choosing routers for circuits.

Circuits SHOULD NOT be built until the client has enough directory information: a live consensus network status [XXXX fallback?] and - descriptors for at least 1/4 of the servers believed to be running. + descriptors for at least 1/4 of the relays believed to be running.

- A server is "listed" if it is included by the consensus network-status - document. Clients SHOULD NOT use unlisted servers. + A relay is "listed" if it is included by the consensus network-status + document. Clients SHOULD NOT use unlisted relays.

These flags are used as follows:

@@ -2304,7 +2304,7 @@

6.2. Managing naming

- In order to provide human-memorable names for individual server + In order to provide human-memorable names for individual router identities, some directory servers bind names to IDs. Clients handle names in two ways:

diff --git a/path-spec.txt b/path-spec.txt index 7c313f8..90e3160 100644 --- a/path-spec.txt +++ b/path-spec.txt @@ -76,16 +76,16 @@ of their choices. is unknown (usually its target IP), but we believe the path probably supports the request according to the rules given below.

-1.1. A server's bandwidth +1.1. A relay's bandwidth

Old versions of Tor did not report bandwidths in network status documents, so clients had to learn them from the routers' advertised - server descriptors. + relay descriptors.

For versions of Tor prior to 0.2.1.17-rc, everywhere below where we - refer to a server's "bandwidth", we mean its clipped advertised + refer to a relay's "bandwidth", we mean its clipped advertised bandwidth, computed by taking the smaller of the 'rate' and - 'observed' arguments to the "bandwidth" element in the server's + 'observed' arguments to the "bandwidth" element in the relay's descriptor. If a router's advertised bandwidth is greater than MAX_BELIEVABLE_BANDWIDTH (currently 10 MB/s), we clipped to that value. @@ -144,13 +144,13 @@ of their choices. In some cases we can reuse an already established circuit if it's clean; see Section 2.3 (cannibalizing circuits) for details.

-2.1.3. Servers build circuits for testing reachability and bandwidth +2.1.3. Relays build circuits for testing reachability and bandwidth

- Tor servers test reachability of their ORPort once they have + Tor relays test reachability of their ORPort once they have successfully built a circuit (on start and whenever their IP address changes). They build an ordinary fast internal circuit with themselves as the last hop. As soon as any testing circuit succeeds, the Tor - server decides it's reachable and is willing to publish a descriptor. + relay decides it's reachable and is willing to publish a descriptor.

We launch multiple testing circuits (one at a time), until we have NUM_PARALLEL_TESTING_CIRC (4) such circuits open. Then we @@ -161,7 +161,7 @@ of their choices. incoming bandwidth, and helps to jumpstart the observed bandwidth (see dir-spec.txt).

- Tor servers also test reachability of their DirPort once they have + Tor relays also test reachability of their DirPort once they have established a circuit, but they use an ordinary exit circuit for this purpose.

@@ -266,7 +266,7 @@ of their choices. such a connection if any clause that accepts any connections to that port precedes all clauses (if any) that reject all connections to that port.

- Unless requested to do so by the user, we never choose an exit server + Unless requested to do so by the user, we never choose an exit node flagged as "BadExit" by more than half of the authorities who advertise themselves as listing bad exits.

@@ -539,7 +539,7 @@ of their choices.

We use Guard nodes (also called "helper nodes" in the literature) to prevent certain profiling attacks. Here's the risk: if we choose entry and - exit nodes at random, and an attacker controls C out of N servers + exit nodes at random, and an attacker controls C out of N relays (ignoring bandwidth), then the attacker will control the entry and exit node of any given circuit with probability (C/N)^2. But as we make many different circuits over time, diff --git a/tor-spec.txt b/tor-spec.txt index 9c45a36..7d84dc9 100644 --- a/tor-spec.txt +++ b/tor-spec.txt @@ -130,31 +130,31 @@ see tor-design.pdf.

1.1. Keys and names

- Every Tor server has multiple public/private keypairs: + Every Tor relay has multiple public/private keypairs:

- A long-term signing-only "Identity key" used to sign documents and - certificates, and used to establish server identity. + certificates, and used to establish relay identity. - A medium-term "Onion key" used to decrypt onion skins when accepting circuit extend attempts. (See 5.1.) Old keys MUST be accepted for at least one week after they are no longer advertised. Because of this, - servers MUST retain old keys for a while after they're rotated. + relays MUST retain old keys for a while after they're rotated. - A short-term "Connection key" used to negotiate TLS connections. Tor implementations MAY rotate this key as often as they like, and SHOULD rotate this key at least once a day.

- Tor servers are also identified by "nicknames"; these are specified in + Tor relays are also identified by "nicknames"; these are specified in dir-spec.txt.

2. Connections

- Connections between two Tor servers, or between a client and a server, + Connections between two Tor relays, or between a client and a relay, use TLS/SSLv3 for link authentication and encryption. All implementations MUST support the SSLv3 ciphersuite "SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA", and SHOULD support the TLS ciphersuite "TLS_DHE_RSA_WITH_AES_128_CBC_SHA" if it is available.

There are three acceptable ways to perform a TLS handshake when - connecting to a Tor server: "certificates up-front", "renegotiation", and + connecting to a Tor relay: "certificates up-front", "renegotiation", and "backwards-compatible renegotiation". ("Backwards-compatible renegotiation" is, as the name implies, compatible with both other handshake types.) @@ -197,7 +197,7 @@ see tor-design.pdf. certificates have been sent, it proceeds as in "certificates up-front"; otherwise, it proceeds as in "renegotiation".

- All new implementations of the Tor server protocol MUST support + All new relay implementations of the Tor protocol MUST support "backwards-compatible renegotiation"; clients SHOULD do this too. If this is not possible, new client implementations MUST support both "renegotiation" and "certificates up-front" and use the router's @@ -205,7 +205,7 @@ see tor-design.pdf. to decide which to use.

In all of the above handshake variants, certificates sent in the clear - SHOULD NOT include any strings to identify the host as a Tor server. In + SHOULD NOT include any strings to identify the host as a Tor relay. In the "renegotiation" and "backwards-compatible renegotiation" steps, the initiator SHOULD choose a list of ciphersuites and TLS extensions to mimic one used by a popular web browser. @@ -255,7 +255,7 @@ see tor-design.pdf. (As an exception, directory servers may try to stay connected to all of the ORs -- though this will be phased out for the Tor 0.1.2.x release.)

- To avoid being trivially distinguished from servers, client-only Tor + To avoid being trivially distinguished from relays, client-only Tor instances are encouraged but not required to use a two-certificate chain as well. Clients SHOULD NOT keep using the same certificates when their IP address changes. Clients MAY send no certificates at all. @@ -332,8 +332,8 @@ see tor-design.pdf. version is 2 or higher.

To determine the version, in any connection where the "renegotiation" - handshake was used (that is, where the server sent only one certificate - at first and where the client did not send any certificates until + handshake was used (that is, where the responder sent only one certificate + at first and where the initiator did not send any certificates until renegotiation), both parties MUST send a VERSIONS cell immediately after the renegotiation is finished, before any other cells are sent. Parties MUST NOT send any other cells on a connection until they have received a @@ -458,24 +458,24 @@ see tor-design.pdf. 5.2. Setting circuit keys

Once the handshake between the OP and an OR is completed, both can - now calculate g^xy with ordinary DH. Before computing g^xy, both client - and server MUST verify that the received g^x or g^y value is not degenerate; + now calculate g^xy with ordinary DH. Before computing g^xy, both parties + MUST verify that the received g^x or g^y value is not degenerate; that is, it must be strictly greater than 1 and strictly less than p-1 where p is the DH modulus. Implementations MUST NOT complete a handshake with degenerate keys. Implementations MUST NOT discard other "weak" g^x values.

(Discarding degenerate keys is critical for security; if bad keys - are not discarded, an attacker can substitute the server's CREATED + are not discarded, an attacker can substitute the OR's CREATED cell's g^y with 0 or 1, thus creating a known g^xy and impersonating - the server. Discarding other keys may allow attacks to learn bits of + the OR. Discarding other keys may allow attacks to learn bits of the private key.)

- If CREATE or EXTEND is used to extend a circuit, the client and server + If CREATE or EXTEND is used to extend a circuit, both parties base their key material on K0=g^xy, represented as a big-endian unsigned integer.

- If CREATE_FAST is used, the client and server base their key material on + If CREATE_FAST is used, both parties base their key material on K0=X|Y.

From the base key material K0, they compute KEY_LEN*2+HASH_LEN*3 bytes of @@ -624,8 +624,8 @@ see tor-design.pdf. 3 -- REQUESTED (A client sent a TRUNCATE command.) 4 -- HIBERNATING (Not currently operating; trying to save bandwidth.) 5 -- RESOURCELIMIT (Out of memory, sockets, or circuit IDs.) - 6 -- CONNECTFAILED (Unable to reach server.) - 7 -- OR_IDENTITY (Connected to server, but its OR identity was not + 6 -- CONNECTFAILED (Unable to reach relay.) + 7 -- OR_IDENTITY (Connected to relay, but its OR identity was not as expected.) 8 -- OR_CONN_CLOSED (The OR connection that was carrying this circuit died.) @@ -684,7 +684,7 @@ see tor-design.pdf. RELAY cells that are not targeted at the first hop of any circuit as RELAY_EARLY cells too, in order to partially conceal the circuit length.

- [In a future version of Tor, servers will reject any EXTEND cell not + [In a future version of Tor, relays will reject any EXTEND cell not received in a RELAY_EARLY cell. See proposal 110.]

6. Application connections and stream management @@ -792,7 +792,7 @@ see tor-design.pdf. A number of seconds (TTL) for which the address may be cached [4 octets] [XXXX No version of Tor currently generates the IPv6 format.]

- [Tor servers before 0.1.2.0 set the TTL field to a fixed value. Later + [Tor exit nodes before 0.1.2.0 set the TTL field to a fixed value. Later versions set the TTL to the last value seen from a DNS server, and expire their own cached entries after a fixed interval. This prevents certain attacks.] @@ -822,16 +822,16 @@ see tor-design.pdf.

6.2.1. Opening a directory stream

- If a Tor server is a directory server, it should respond to a + If a Tor relay is a directory server, it should respond to a RELAY_BEGIN_DIR cell as if it had received a BEGIN cell requesting a connection to its directory port. RELAY_BEGIN_DIR cells ignore exit policy, since the stream is local to the Tor process.

- If the Tor server is not running a directory service, it should respond + If the Tor relay is not running a directory service, it should respond with a REASON_NOTDIRECTORY RELAY_END cell.

Clients MUST generate an all-zero payload for RELAY_BEGIN_DIR cells, - and servers MUST ignore the payload. + and relays MUST ignore the payload.

[RELAY_BEGIN_DIR was not supported before Tor 0.1.2.2-alpha; clients SHOULD NOT send it to routers running earlier versions of Tor.] @@ -866,7 +866,7 @@ see tor-design.pdf. 13 -- REASON_TORPROTOCOL (Sent when closing connection because of Tor protocol violations.) 14 -- REASON_NOTDIRECTORY (Client sent RELAY_BEGIN_DIR to a - non-directory server.) + non-directory relay.)

(With REASON_EXITPOLICY, the 4-byte IPv4 address or 16-byte IPv6 address forms the optional data, along with a 4-byte TTL; no other reason @@ -1014,7 +1014,7 @@ see tor-design.pdf. A.1. Differences between spec and implementation

- The current specification requires all ORs to have IPv4 addresses, but - allows servers to exit and resolve to IPv6 addresses, and to declare IPv6 + allows relays to exit and resolve to IPv6 addresses, and to declare IPv6 addresses in their exit policies. The current codebase has no IPv6 support at all.