1 Filename: 105-handshake-revision.txt
2 Title: Version negotiation for the Tor protocol.
5 Author: Nick Mathewson, Roger Dingledine
8 Implemented-In: 0.2.0.x
12 This document was extracted from a modified version of tor-spec.txt that we
13 had written before the proposal system went into place. It adds two new
14 cells types to the Tor link connection setup handshake: one used for
15 version negotiation, and another to prevent MITM attacks.
17 This proposal is partially implemented, and partially proceded by
20 Motivation: Tor versions
22 Our *current* approach to versioning the Tor protocol(s) has been as
24 - All changes must be backward compatible.
25 - It's okay to add new cell types, if they would be ignored by previous
27 - It's okay to add new data elements to cells, if they would be
28 ignored by previous versions of Tor.
29 - For forward compatibility, Tor must ignore cell types it doesn't
30 recognize, and ignore data in those cells it doesn't expect.
31 - Clients can inspect the version of Tor declared in the platform line
32 of a router's descriptor, and use that to learn whether a server
33 supports a given feature. Servers, however, aren't assumed to all
34 know about each other, and so don't know the version of who they're
37 This system has these problems:
38 - It's very hard to change fundamental aspects of the protocol, like the
39 cell format, the link protocol, any of the various encryption schemes,
41 - The router-to-router link protocol has remained more-or-less frozen
42 for a long time, since we can't easily have an OR use new features
43 unless it knows the other OR will understand them.
45 We need to resolve these problems because:
46 - Our cipher suite is showing its age: SHA1/AES128/RSA1024/DH1024 will
47 not seem like the best idea for all time.
48 - There are many ideas circulating for multiple cell sizes; while it's
49 not obvious whether these are safe, we can't do them at all without a
50 mechanism to permit them.
51 - There are many ideas circulating for alternative circuit building and
52 cell relay rules: they don't work unless they can coexist in the
54 - If our protocol changes a lot, it's hard to describe any coherent
55 version of it: we need to say "the version that Tor versions W through
56 X use when talking to versions Y through Z". This makes analysis
59 Motivation: Preventing MITM attacks
61 TLS prevents a man-in-the-middle attacker from reading or changing the
62 contents of a communication. It does not, however, prevent such an
63 attacker from observing timing information. Since timing attacks are some
64 of the most effective against low-latency anonymity nets like Tor, we
65 should take more care to make sure that we're not only talking to who
66 we think we're talking to, but that we're using the network path we
69 Motivation: Signed clock information
71 It's very useful for Tor instances to know how skewed they are relative
72 to one another. The only way to find out currently has been to download
73 directory information, and check the Date header--but this is not
74 authenticated, and hence subject to modification on the wire. Using
75 BEGIN_DIR to create an authenticated directory stream through an existing
76 circuit is better, but that's an extra step and it might be nicer to
77 learn the information in the course of the regular protocol.
83 The node-to-node TLS-based "OR connection" protocol and the multi-hop
84 "circuit" protocol are versioned quasi-independently.
86 Of course, some dependencies will continue to exist: Certain versions
87 of the circuit protocol may require a minimum version of the connection
88 protocol to be used. The connection protocol affects:
89 - Initial connection setup, link encryption, transport guarantees,
91 - The allowable set of cell commands
92 - Allowable formats for cells.
94 The circuit protocol determines:
95 - How circuits are established and maintained
96 - How cells are decrypted and relayed
97 - How streams are established and maintained.
99 Version numbers are incremented for backward-incompatible protocol changes
100 only. Backward-compatible changes are generally implemented by adding
101 additional fields to existing structures; implementations MUST ignore
102 fields they do not expect. Unused portions of cells MUST be set to zero.
104 Though versioning the protocol will make it easier to maintain backward
105 compatibility with older versions of Tor, we will nevertheless continue to
106 periodically drop support for older protocols,
107 - to keep the implementation from growing without bound,
108 - to limit the maintenance burden of patching bugs in obsolete Tors,
109 - to limit the testing burden of verifying that many old protocol
110 versions continue to be implemented properly, and
111 - to limit the exposure of the network to protocol versions that are
112 expensive to support.
114 The Tor protocol as implemented through the 0.1.2.x Tor series will be
115 called "version 1" in its link protocol and "version 1" in its relay
116 protocol. Versions of the Tor protocol so old as to be incompatible with
117 Tor 0.1.2.x can be considered to be version 0 of each, and are not
122 When a Tor connection is established, both parties normally send a
123 VERSIONS cell before sending any other cells. (But see below.)
126 Versions [VersionsLen bytes]
128 "Versions" is a sequence of VersionsLen bytes. Each value between 1 and
129 127 inclusive represents a single version; current implementations MUST
130 ignore other bytes. Parties should list all of the versions which they
131 are able and willing to support. Parties can only communicate if they
132 have some connection protocol version in common.
134 Version 0.2.0.x-alpha and earlier don't understand VERSIONS cells,
135 and therefore don't support version negotiation. Thus, waiting until
136 the other side has sent a VERSIONS cell won't work for these servers:
137 if the other side sends no cells back, it is impossible to tell
139 have sent a VERSIONS cell that has been stalled, or whether they have
140 dropped our own VERSIONS cell as unrecognized. Therefore, we'll
141 change the TLS negotiation parameters so that old parties can still
142 negotiate, but new parties can recognize each other. Immediately
143 after a TLS connection has been established, the parties check
144 whether the other side negotiated the connection in an "old" way or a
145 "new" way. If either party negotiated in the "old" way, we assume a
146 v1 connection. Otherwise, both parties send VERSIONS cells listing
147 all their supported versions. Upon receiving the other party's
148 VERSIONS cell, the implementation begins using the highest-valued
149 version common to both cells. If the first cell from the other party
150 has a recognized command, and is _not_ a VERSIONS cell, we assume a
153 (For more detail on the TLS protocol change, see forthcoming draft
154 proposals from Steven Murdoch.)
156 Implementations MUST discard VERSIONS cells that are not the first
157 recognized cells sent on a connection.
159 The VERSIONS cell must be sent as a v1 cell (2 bytes of circuitID, 1
160 byte of command, 509 bytes of payload).
162 [NOTE: The VERSIONS cell is assigned the command number 7.]
164 2.2. MITM-prevention and time checking
166 If we negotiate a v2 connection or higher, the second cell we send SHOULD
167 be a NETINFO cell. Implementations SHOULD NOT send NETINFO cells at other
170 A NETINFO cell contains:
172 Other OR's address [variable]
173 Number of addresses [1 byte]
174 This OR's addresses [variable]
176 Timestamp is the OR's current Unix time, in seconds since the epoch. If
177 an implementation receives time values from many ORs that
178 indicate that its clock is skewed, it SHOULD try to warn the
179 administrator. (We leave the definition of 'many' intentionally vague
182 Before believing the timestamp in a NETINFO cell, implementations
183 SHOULD compare the time at which they received the cell to the time
184 when they sent their VERSIONS cell. If the difference is very large,
185 it is likely that the cell was delayed long enough that its
186 contents are out of date.
188 Each address contains Type/Length/Value as used in Section 6.4 of
189 tor-spec.txt. The first address is the one that the party sending
190 the NETINFO cell believes the other has -- it can be used to learn
191 what your IP address is if you have no other hints.
192 The rest of the addresses are the advertised addresses of the party
193 sending the NETINFO cell -- we include them
194 to block a man-in-the-middle attack on TLS that lets an attacker bounce
195 traffic through his own computers to enable timing and packet-counting
198 A Tor instance should use the other Tor's reported address
199 information as part of logic to decide whether to treat a given
200 connection as suitable for extending circuits to a given address/ID
201 combination. When we get an extend request, we use an
202 existing OR connection if the ID matches, and ANY of the following
204 - The IP matches the requested IP.
205 - We know that the IP we're using is canonical because it was
206 listed in the NETINFO cell.
207 - We know that the IP we're using is canonical because it was
208 listed in the server descriptor.
210 [NOTE: The NETINFO cell is assigned the command number 8.]
212 Discussion: Versions versus feature lists
214 Many protocols negotiate lists of available features instead of (or in
215 addition to) protocol versions. While it's possible that some amount of
216 feature negotiation could be supported in a later Tor, we should prefer to
217 use protocol versions whenever possible, for reasons discussed in
218 the "Anonymity Loves Company" paper.
220 Discussion: Bytes per version, versions per cell
222 This document provides for a one-byte count of how many versions a Tor
223 supports, and allows one byte per version. Thus, it can only support only
224 254 more versions of the protocol beyond the unallocated v0 and the
225 current v1. If we ever need to split the protocol into 255 incompatible
226 versions, we've probably screwed up badly somewhere.
228 Nevertheless, here are two ways we could support more versions:
229 - Change the version count to a two-byte field that counts the number of
230 _bytes_ used, and use a UTF8-style encoding: versions 0 through 127
231 take one byte to encode, versions 128 through 2047 take two bytes to
232 encode, and so on. We wouldn't need to parse any version higher than
233 127 right now, since all bytes used to encode higher versions would
234 have their high bit set.
236 We'd still have a limit of 380 simultaneously versions that could be
237 declared in any version. This is probably okay.
239 - Decide that if we need to support more versions, we can add a
240 MOREVERSIONS cell that gets sent before the VERSIONS cell. The spec
241 above requires Tors to ignore unrecognized cell types that they get
242 before the first VERSIONS cell, and still allows version negotiation
246 [Resolution: Reserve the high bit and the v0 value for later use. If
247 we ever have more live versions than we can fit in a cell, we've made a
248 bad design decision somewhere along the line.]
250 Discussion: Reducing round-trips
252 It might be appealing to see if we can cram more information in the
253 initial VERSIONS cell. For example, the contents of NETINFO will pretty
254 soon be sent by everybody before any more information is exchanged, but
255 decoupling them from the version exchange increases round-trips.
257 Instead, we could speculatively include handshaking information at
258 the end of a VERSIONS cell, wrapped in a marker to indicate, "if we wind
259 up speaking VERSION 2, here's the NETINFO I'll send. Otherwise, ignore
260 this." This could be extended to opportunistically reduce round trips
261 when possible for future versions when we guess the versions right.
263 Of course, we'd need to be careful about using a feature like this:
264 - We don't want to include things that are expensive to compute,
265 like PK signatures or proof-of-work.
266 - We don't want to speculate as a mobile client: it may leak our
267 experience with the server in question.
269 Discussion: Advertising versions in routerdescs and networkstatuses.
273 The networkstatus "v" line now has the format:
274 "v" IMPLEMENTATION IMPL-VERSION "Link" LINK-VERSION-LIST
275 "Circuit" CIRCUIT-VERSION-LIST NL
277 LINK-VERSION-LIST and CIRCUIT-VERSION-LIST are comma-separated lists of
278 supported version numbers. IMPLEMENTATION is the name of the
279 implementation of the Tor protocol (e.g., "Tor"), and IMPL-VERSION is the
280 version of the implementation.
283 v Tor 0.2.5.1-alpha Link 1,2,3 Circuit 2,5
285 v OtherOR 2000+ Link 3 Circuit 5
287 Implementations that release independently of the Tor codebase SHOULD NOT
288 use "Tor" as the value of their IMPLEMENTATION.
290 Additional fields on the "v" line MUST be ignored.
292 In router descriptors:
294 The router descriptor should contain a line of the form,
295 "protocols" "Link" LINK-VERSION-LIST "Circuit" CIRCUIT_VERSION_LIST
297 Additional fields on the "protocols" line MUST be ignored.
299 [Versions of Tor before 0.1.2.5-alpha rejected router descriptors with
300 unrecognized items; the protocols line should be preceded with an "opt"
301 until these Tors are obsolete.]
305 Client partitioning is the big danger when we introduce new versions; if a
306 client supports some very unusual set of protocol versions, it will stand
307 out from others no matter where it goes. If a server supports an unusual
308 version, it will get a disproportionate amount of traffic from clients who
309 prefer that version. We can mitigate this somewhat as follows:
311 - Do not have clients prefer any protocol version by default until that
312 version is widespread. (First introduce the new version to servers,
313 and have clients admit to using it only when configured to do so for
314 testing. Then, once many servers are running the new protocol
315 version, enable its use by default.)
317 - Do not multiply protocol versions needlessly.
319 - Encourage protocol implementors to implement the same protocol version
320 sets as some popular version of Tor.
322 - Disrecommend very old/unpopular versions of Tor via the directory
323 authorities' RecommmendedVersions mechanism, even if it is still
324 technically possible to use them.