diff options
Diffstat (limited to 'doc/spec')
| -rw-r--r-- | doc/spec/dir-spec.txt | 18 | ||||
| -rw-r--r-- | doc/spec/proposals/000-index.txt | 8 | ||||
| -rw-r--r-- | doc/spec/proposals/105-handshake-revision.txt | 2 | ||||
| -rw-r--r-- | doc/spec/proposals/130-v2-conn-protocol.txt | 2 | ||||
| -rw-r--r-- | doc/spec/tor-spec.txt | 172 |
5 files changed, 173 insertions, 29 deletions
diff --git a/doc/spec/dir-spec.txt b/doc/spec/dir-spec.txt index 4e482bae0..cd47eb029 100644 --- a/doc/spec/dir-spec.txt +++ b/doc/spec/dir-spec.txt @@ -573,6 +573,24 @@ $Id$ supports those descriptor versions. If none are specified, it defaults to version 2 descriptors. + [Versions of Tor before 0.1.2.5-alpha rejected router descriptors + with unrecognized items; the protocols line should be preceded with + an "opt" until these Tors are obsolete.] + + "protocols" SP "Link" SP LINK-VERSION-LIST SP "Circuit" SP + CIRCUIT-VERSION-LIST NL + + [At most once.] + + Both lists are space-separated sequences of numbers, to indicate which + protocols the server supports. As of 30 Mar 2008, specified + protocols are "Link 1 2 Circuit 1". See section 4.1 of tor-spec.txt + for more information about link protocol versions. + + [Versions of Tor before 0.1.2.5-alpha rejected router descriptors + with unrecognized items; the protocols line should be preceded with + an "opt" until these Tors are obsolete.] + 2.2. Extra-info documents Extra-info documents consist of the following items: diff --git a/doc/spec/proposals/000-index.txt b/doc/spec/proposals/000-index.txt index c5a31536d..d96841b64 100644 --- a/doc/spec/proposals/000-index.txt +++ b/doc/spec/proposals/000-index.txt @@ -27,7 +27,7 @@ Proposals by number: 102 Dropping "opt" from the directory format [CLOSED] 103 Splitting identity key from regularly used signing key [CLOSED] 104 Long and Short Router Descriptors [CLOSED] -105 Version negotiation for the Tor protocol [FINISHED] +105 Version negotiation for the Tor protocol [CLOSED] 106 Checking fewer things during TLS handshakes [CLOSED] 107 Uptime Sanity Checking [CLOSED] 108 Base "Stable" Flag on Mean Time Between Failures [CLOSED] @@ -52,7 +52,7 @@ Proposals by number: 127 Relaying dirport requests to Tor download site / website [DRAFT] 128 Families of private bridges [DRAFT] 129 Block Insecure Protocols by Default [CLOSED] -130 Version 2 Tor connection protocol [FINISHED] +130 Version 2 Tor connection protocol [CLOSED] 131 Help users to verify they are using Tor [NEEDS-REVISION] 132 A Tor Web Service For Verifying Correct Browser Configuration [DRAFT] 133 Incorporate Unreachable ORs into the Tor Network [DRAFT] @@ -79,15 +79,14 @@ Proposals by status: 098 Proposals that should be written 099 Miscellaneous proposals FINISHED: - 105 Version negotiation for the Tor protocol 111 Prioritizing local traffic over relayed traffic 125 Behavior for bridge users, bridge relays, and bridge authorities - 130 Version 2 Tor connection protocol CLOSED: 101 Voting on the Tor Directory System 102 Dropping "opt" from the directory format 103 Splitting identity key from regularly used signing key 104 Long and Short Router Descriptors + 105 Version negotiation for the Tor protocol 106 Checking fewer things during TLS handshakes 107 Uptime Sanity Checking 108 Base "Stable" Flag on Mean Time Between Failures @@ -98,6 +97,7 @@ Proposals by status: 123 Naming authorities automatically create bindings 126 Getting GeoIP data and publishing usage summaries 129 Block Insecure Protocols by Default + 130 Version 2 Tor connection protocol SUPERSEDED: 112 Bring Back Pathlen Coin Weight 124 Blocking resistant TLS certificate usage diff --git a/doc/spec/proposals/105-handshake-revision.txt b/doc/spec/proposals/105-handshake-revision.txt index 8a4d7ac43..f4288c5f6 100644 --- a/doc/spec/proposals/105-handshake-revision.txt +++ b/doc/spec/proposals/105-handshake-revision.txt @@ -4,7 +4,7 @@ Version: $Revision$ Last-Modified: $Date$ Author: Nick Mathewson, Roger Dingledine Created: -Status: Finished +Status: Closed Overview: diff --git a/doc/spec/proposals/130-v2-conn-protocol.txt b/doc/spec/proposals/130-v2-conn-protocol.txt index 3913e57ec..1a4b80580 100644 --- a/doc/spec/proposals/130-v2-conn-protocol.txt +++ b/doc/spec/proposals/130-v2-conn-protocol.txt @@ -4,7 +4,7 @@ Version: $Revision$ Last-Modified: $Date$ Author: Nick Mathewson Created: 2007-10-25 -Status: Finished +Status: Closed Overview: diff --git a/doc/spec/tor-spec.txt b/doc/spec/tor-spec.txt index b31e7bf62..b55e088e8 100644 --- a/doc/spec/tor-spec.txt +++ b/doc/spec/tor-spec.txt @@ -143,14 +143,70 @@ see tor-design.pdf. 2. Connections - Tor uses TLS/SSLv3 for link authentication and encryption. All + Connections between two Tor servers, or between a client and a server, + 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. - Implementations MAY support other TLS ciphersuites, but MUST NOT - support any suite that lacks ephemeral keys, or whose symmetric keys are - less then KEY_LEN bits, or whose digests are less than HASH_LEN bits. - Implementations SHOULD NOT allow other SSLv3 ciphersuites. + + There are three acceptable ways to perform a TLS handshake when + connecting to a Tor server: "certificates up-front", "renegotiation", and + "backwards-compatible renegotiation". ("Backwards-compatible + renegotiation" is, as the name implies, compatible with both other + handshake types.) + + Before Tor 0.2.0.21, only "certificates up-front" was supported. In Tor + 0.2.0.21 or later, "backwards-compatible renegotiation" is used. + + In "certificates up-front", the connection initiator always sends a + two-certificate chain, consisting of an X.509 certificate using a + short-term connection public key and a second, self- signed X.509 + certificate containing its identity key. The other party sends a similar + certificate chain. The initiator's ClientHello MUST NOT include any + ciphersuites other than: + TLS_DHE_RSA_WITH_AES_256_CBC_SHA + TLS_DHE_RSA_WITH_AES_128_CBC_SHA + SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA + SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA + + In "renegotiation", the connection initiator sends no certificates, and + the responder sends a single connection certificate. Once the TLS + handshake is complete, the initiator renegotiates the handshake, with each + parties sending a two-certificate chain as in "certificates up-front". + The initiator's ClientHello MUST include at least once ciphersuite not in + the list above. + + In "backwards-compatible renegotiation", the connection initiator's + ClientHello MUST include at least one ciphersuite other than those listed + above. The connection responder examines the initiator's ciphersuite list + to see whether it includes any ciphers other than those included in the + list above. If extra ciphers are included, the responder proceeds as in + "renegotiation": it sends a single certificate and does not request + client certificates. Otherwise (in the case that no extra ciphersuites + are included in the ClientHello) the responder proceeds as in + "certificates up-front": it requests client certificates, and sends a + two-certificate chain. In either case, once the responder has sent its + certificate or certificates, the initiator counts them. If two + 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 + "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 + published link protocols list (see dir-spec.txt on the "protocols" entry) + 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 + the "renegotation" and "backwards-compatible renegotiation", the + initiator SHOULD chose a list of ciphersuites and TLS extensions chosen + to mimic one used by a popular web browser. + + Responders MUST NOT select any TLS ciphersuite that lacks ephemeral keys, + or whose symmetric keys are less then KEY_LEN bits, or whose digests are + less than HASH_LEN bits. Responders SHOULD NOT select any SSLv3 + ciphersuite other than those listed above. Even though the connection protocol is identical, we will think of the initiator as either an onion router (OR) if it is willing to relay @@ -158,21 +214,9 @@ see tor-design.pdf. local requests. Onion proxies SHOULD NOT provide long-term-trackable identifiers in their handshakes. - During the TLS handshake, the connection initiator always sends a - two-certificate chain, consisting of an X.509 certificate using a - short-term connection public key and a second, self- signed X.509 - certificate containing its identity key. The commonName of the first - certificate is the OR's nickname, and the commonName of the second - certificate is the OR's nickname, followed by a space and the string - "<identity>". The other party sends a similar certificate chain. - - Implementations running Protocol 1 and earlier use an - organizationName of "Tor" or "TOR". Future implementations (which - support the version negotiation protocol in section 4.1) MUST NOT - have either of these values for their organizationName. - - All parties receiving certificates must confirm that the identity key is - as expected. (When initiating a connection, the expected identity key is + In all handshake variants, once all certificates are exchanged, all + parties receiving certificates must confirm that the identity key is as + expected. (When initiating a connection, the expected identity key is the one given in the directory; when creating a connection because of an EXTEND cell, the expected identity key is the one given in the cell.) If the key is not as expected, the party must close the connection. @@ -216,6 +260,14 @@ see tor-design.pdf. Command [1 byte] Payload (padded with 0 bytes) [PAYLOAD_LEN bytes] + On a version 2 connection, all cells are as in version 1 connections, + except for the initial VERSIONS cell, whose format is: + + Circuit [2 octets; set to 0] + Command [1 octet; set to 7 for VERSIONS] + Length [2 octets; big-endian integer] + Payload [Length bytes] + The CircID field determines which circuit, if any, the cell is associated with. @@ -227,6 +279,8 @@ see tor-design.pdf. 4 -- DESTROY (Stop using a circuit) (See Sec 5.4) 5 -- CREATE_FAST (Create a circuit, no PK) (See Sec 5.1) 6 -- CREATED_FAST (Circuit created, no PK) (See Sec 5.1) + 7 -- VERSIONS (Negotiate proto version) (See Sec 4) + 8 -- NETINFO (Time and address info) (See Sec 4) The interpretation of 'Payload' depends on the type of the cell. PADDING: Payload is unused. @@ -246,12 +300,64 @@ see tor-design.pdf. cell every few minutes. CREATE, CREATED, and DESTROY cells are used to manage circuits; - see section 4 below. + see section 5 below. RELAY cells are used to send commands and data along a circuit; see - section 5 below. + section 6 below. + + VERSIONS and NETINFO cells are used to set up connections. See section 4 + below. + +4. Negotiating and initializing connections + +4.1. Negotiating versions with VERSIONS cells + + There are multiple instances of the Tor link connection protocol. Any + connection negotiated using the "certificates up front" handshake (see + section 2 above) is "version 1". In any connection where both parties + have behaved as in the "renegotiation" handshake, the link protocol + 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 + 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 + VERSIONS cell. + + The payload in a VERSIONS cell is a series of big-endian two-byte + integers. Both parties MUST select as the link protocol version the + highest number contained both in the VERSIONS cell they sent and in the + versions cell they received. If they have no such version in common, + they cannot communicate and MUST close the connection. + + Since the version 1 link protocol does not use the "renegotiation" + handshake, implementations MUST NOT list version 1 in their VERSIONS + cell. + +4.2. NETINFO cells + + If version 2 or higher is negotiated, each party sends the other a + NETINFO cell. The cell's payload is: + + Timestamp [4 bytes] + Other OR's address [variable] + Number of addresses [1 byte] + This OR's addresses [variable] + + The address format is a type/length/value sequence as given in section + 6.4 below. The timestamp is a big-endian unsigned integer number of + seconds since the unix epoch. + + Implementations MAY use the timestamp value to help decide if their + clocks are skewed. Initiators MAY use "other OR's address" to help + learn which address their connections are originating from, if they do + not know it. Initiators SHOULD use "this OR's address" to make sure + that they have connected to another OR at its canonical address. + + [As of 0.2.0.23-rc, implementations use none of the above values.] -4. [This section deliberately left blank.] 5. Circuit management @@ -443,6 +549,26 @@ see tor-design.pdf. until a break in traffic allows time to do so without harming network latency too greatly.) +5.3.1. Canonical connections + + It is possible for an attacker to launch a man-in-the-middle attack + against a connection by telling OR Alice to extend to OR Bob at some + address X controlled by the attacker. The attacker cannot read the + encrypted traffic, but the attacker is now in a position to count all + bytes sent between Alice and Bob (assuming Alice was not already + connected to Bob.) + + To prevent this, when an OR we gets an extend request, it SHOULD use an + existing OR connection if the ID matches, and ANY of the following + conditions hold: + - The IP matches the requested IP. + - The OR knows that the IP of the connection it's using is canonical + because it was listed in the NETINFO cell. + - The OR knows that the IP of the connection it's using is canonical + because it was listed in the server descriptor. + + [This is not implemented in Tor 0.2.0.23-rc.] + 5.4. Tearing down circuits Circuits are torn down when an unrecoverable error occurs along |