3 Tor Rendezvous Specification
5 0. Overview and preliminaries
7 Read http://tor.eff.org/doc/design-paper/tor-design.html#sec:rendezvous
8 before you read this specification. It will make more sense.
10 Rendezvous points provide location-hidden services (server
11 anonymity) for the onion routing network. With rendezvous points,
12 Bob can offer a TCP service (say, a webserver) via the onion
13 routing network, without revealing the IP of that service.
15 Bob does this by anonymously advertising a public key for his
16 service, along with a list of onion routers to act as "Introduction
17 Points" for his service. He creates forward circuits to those
18 introduction points, and tells them about his public key. To
19 connect to Bob, Alice first builds a circuit to an OR to act as
20 her "Rendezvous Point." She then connects to one of Bob's chosen
21 introduction points, optionally provides authentication or
22 authorization information, and asks it to tell him about her Rendezvous
23 Point (RP). If Bob chooses to answer, he builds a circuit to her
24 RP, and tells it to connect him to Alice. The RP joins their
25 circuits together, and begins relaying cells. Alice's 'BEGIN'
26 cells are received directly by Bob's OP, which passes data to
27 and from the local server implementing Bob's service.
29 Below we describe a network-level specification of this service,
30 along with interfaces to make this process transparent to Alice
31 (so long as she is using an OP).
33 0.1. Notation, conventions and prerequisites
35 In the specifications below, we use the same notation and terminology
36 as in "tor-spec.txt". The service specified here also requires the
37 existence of an onion routing network as specified in that file.
39 H(x) is a SHA1 digest of x.
40 PKSign(SK,x) is a PKCS.1-padded RSA signature of x with SK.
41 PKEncrypt(SK,x) is a PKCS.1-padded RSA encryption of x with SK.
42 Public keys are all RSA, and encoded in ASN.1.
43 All integers are stored in network (big-endian) order.
44 All symmetric encryption uses AES in counter mode, except where
47 In all discussions, "Alice" will refer to a user connecting to a
48 location-hidden service, and "Bob" will refer to a user running a
49 location-hidden service.
51 An OP is (as defined elsewhere) an "Onion Proxy" or Tor client.
53 An OR is (as defined elsewhere) an "Onion Router" or Tor server.
55 An "Introduction point" is a Tor server chosen to be Bob's medium-term
56 'meeting place'. A "Rendezvous point" is a Tor server chosen by Alice to
57 be a short-term communication relay between her and Bob. All Tor servers
58 potentially act as introduction and rendezvous points.
62 1. Bob->Bob's OP: "Offer IP:Port as
63 public-key-name:Port". [configuration]
64 (We do not specify this step; it is left to the implementor of
67 2. Bob's OP generates keypair and rendezvous service descriptor:
68 "Meet public-key X at introduction point A, B, or C." (signed)
70 3. Bob's OP->Introduction point via Tor: [introduction setup]
73 4. Bob's OP->directory service via Tor: publishes Bob's service
74 descriptor [advertisement]
76 5. Out of band, Alice receives a [x.y.]z.onion:port address.
77 She opens a SOCKS connection to her OP, and requests
80 6. Alice's OP retrieves Bob's descriptor via Tor. [descriptor lookup.]
82 7. Alice's OP chooses a rendezvous point, opens a circuit to that
83 rendezvous point, and establishes a rendezvous circuit. [rendezvous
86 8. Alice connects to the Introduction point via Tor, and tells it about
87 her rendezvous point and optional authentication/authorization
88 information. (Encrypted to Bob.) [Introduction 1]
90 9. The Introduction point passes this on to Bob's OP via Tor, along the
91 introduction circuit. [Introduction 2]
93 10. Bob's OP decides whether to connect to Alice, and if so, creates a
94 circuit to Alice's RP via Tor. Establishes a shared circuit.
97 11. Alice's OP sends begin cells to Bob's OP. [Connection]
99 0.3. Constants and new cell types
102 32 -- RELAY_ESTABLISH_INTRO
103 33 -- RELAY_ESTABLISH_RENDEZVOUS
104 34 -- RELAY_INTRODUCE1
105 35 -- RELAY_INTRODUCE2
106 36 -- RELAY_RENDEZVOUS1
107 37 -- RELAY_RENDEZVOUS2
108 38 -- RELAY_INTRO_ESTABLISHED
109 39 -- RELAY_RENDEZVOUS_ESTABLISHED
110 40 -- RELAY_COMMAND_INTRODUCE_ACK
114 1.1. Bob configures his local OP.
116 We do not specify a format for the OP configuration file. However,
117 OPs SHOULD allow Bob to provide more than one advertised service
118 per OP, and MUST allow Bob to specify one or more virtual ports per
119 service. Bob provides a mapping from each of these virtual ports
120 to a local IP:Port pair.
122 1.2. Bob's OP generates service descriptors.
124 The first time the OP provides an advertised service, it generates
125 a public/private keypair (stored locally). Periodically, the OP
126 generates and publishes a descriptor of type "V0". The V1 descriptor
127 format in 0.1.1.5-alpha-cvs is understood and accepted, but currently
128 no Tors generate them. The more complex V1 descriptor format below
129 is just speculation and has never been used.
131 A hypothetical "V1" descriptor contains:
133 V Format byte: set to 255 [1 octet]
134 V Version byte: set to 1 [1 octet]
135 KL Key length [2 octets]
136 PK Bob's public key [KL octets]
137 TS A timestamp [4 octets]
138 PROTO Rendezvous protocol versions: bitmask [2 octets]
139 NA Number of auth mechanisms accepted [1 octet]
140 For each auth mechanism:
141 AUTHT The auth type that is supported [2 octets]
142 AUTHL Length of auth data [1 octet]
143 AUTHD Auth data [variable]
144 NI Number of introduction points [2 octets]
145 For each introduction point: (as in INTRODUCE2 cells)
146 ATYPE An address type (typically 4) [1 octet]
147 ADDR Introduction point's IP address [4 or 16 octets]
148 PORT Introduction point's OR port [2 octets]
149 AUTHT The auth type that is supported [2 octets]
150 AUTHL Length of auth data [1 octet]
151 AUTHD Auth data [variable]
152 ID Introduction point identity ID [20 octets]
153 KLEN Length of onion key [2 octets]
154 KEY Introduction point onion key [KLEN octets]
155 SIG Signature of above fields [variable]
157 The "V1" descriptor in 0.1.1.5-alpha-cvs contains:
159 V Format byte: set to 255 [1 octet]
160 V Version byte: set to 1 [1 octet]
161 KL Key length [2 octets]
162 PK Bob's public key [KL octets]
163 TS A timestamp [4 octets]
164 PROTO Protocol versions: bitmask [2 octets]
165 NI Number of introduction points [2 octets]
166 For each introduction point: (as in INTRODUCE2 cells)
167 IP Introduction point's address [4 octets]
168 PORT Introduction point's OR port [2 octets]
169 ID Introduction point identity ID [20 octets]
170 KLEN Length of onion key [2 octets]
171 KEY Introduction point onion key [KLEN octets]
172 SIG Signature of above fields [variable]
174 The "V0" descriptor contains:
176 KL Key length [2 octets]
177 PK Bob's public key [KL octets]
178 TS A timestamp [4 octets]
179 NI Number of introduction points [2 octets]
180 Ipt A list of NUL-terminated ORs [variable]
181 SIG Signature of above fields [variable]
183 KL is the length of PK, in octets.
184 TS is the number of seconds elapsed since Jan 1, 1970.
186 AUTHT specifies which authentication/authorization mechanism is
187 required by the hidden service or the introduction point. AUTHD
188 is arbitrary data that can be associated with an auth approach.
189 Currently only AUTHT of [00 00] is supported, with an AUTHL of 0.
190 See section 2 of this document for details on auth mechanisms.
192 The members of Ipt may be either (a) nicknames, or (b) identity key
193 digests, encoded in hex, and prefixed with a '$'. Clients must
194 accept both forms. Services must only generate the second form.
195 Once 0.0.9.x is obsoleted, we can drop the first form.
197 [It's ok for Bob to advertise 0 introduction points. He might want
198 to do that if he previously advertised some introduction points,
199 and now he doesn't have any. -RD]
201 [Once Tor 0.1.0.x is obsolete, we can stop generating or using V0
204 1.3. Bob's OP establishes his introduction points.
206 The OP establishes a new introduction circuit to each introduction
207 point. These circuits MUST NOT be used for anything but rendezvous
208 introduction. To establish the introduction, Bob sends a
209 RELAY_ESTABLISH_INTRO cell, containing:
211 KL Key length [2 octets]
212 PK Bob's public key [KL octets]
213 HS Hash of session info [20 octets]
214 SIG Signature of above information [variable]
216 [XXX011, need to add auth information here. -RD]
218 To prevent replay attacks, the HS field contains a SHA-1 hash based on the
219 shared secret KH between Bob's OP and the introduction point, as
221 HS = H(KH | "INTRODUCE")
223 HS = H(KH | [49 4E 54 52 4F 44 55 43 45])
224 (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)
226 Upon receiving such a cell, the OR first checks that the signature is
227 correct with the included public key. If so, it checks whether HS is
228 correct given the shared state between Bob's OP and the OR. If either
229 check fails, the OP discards the cell; otherwise, it associates the
230 circuit with Bob's public key, and dissociates any other circuits
231 currently associated with PK. On success, the OR sends Bob a
232 RELAY_INTRO_ESTABLISHED cell with an empty payload.
234 1.4. Bob's OP advertises his service descriptor(s).
236 Bob's OP opens a stream to each directory server's directory port via Tor.
237 (He may re-use old circuits for this.) Over this stream, Bob's OP makes
238 an HTTP 'POST' request, to a URL "/tor/rendezvous/publish" relative to the
239 directory server's root, containing as its body Bob's service descriptor.
241 Bob should upload a service descriptor for each version format that
242 is supported in the current Tor network.
244 Upon receiving a descriptor, the directory server checks the signature,
245 and discards the descriptor if the signature does not match the enclosed
246 public key. Next, the directory server checks the timestamp. If the
247 timestamp is more than 24 hours in the past or more than 1 hour in the
248 future, or the directory server already has a newer descriptor with the
249 same public key, the server discards the descriptor. Otherwise, the
250 server discards any older descriptors with the same public key and
251 version format, and associates the new descriptor with the public key.
252 The directory server remembers this descriptor for at least 24 hours
253 after its timestamp. At least every 18 hours, Bob's OP uploads a
256 1.5. Alice receives a x.y.z.onion address.
258 When Alice receives a pointer to a location-hidden service, it is as a
259 hostname of the form "z.onion" or "y.z.onion" or "x.y.z.onion", where
260 z is a base-32 encoding of a 10-octet hash of Bob's service's public
261 key, computed as follows:
264 2. Let H' = the first 80 bits of H, considering each octet from
265 most significant bit to least significant bit.
266 2. Generate a 16-character encoding of H', using base32 as defined
269 (We only use 80 bits instead of the 160 bits from SHA1 because we
270 don't need to worry about arbitrary collisions, and because it will
271 make handling the url's more convenient.)
273 The string "x", if present, is the base-32 encoding of the
274 authentication/authorization required by the introduction point.
275 The string "y", if present, is the base-32 encoding of the
276 authentication/authorization required by the hidden service.
277 Omitting a string is taken to mean auth type [00 00].
278 See section 2 of this document for details on auth mechanisms.
280 [Yes, numbers are allowed at the beginning. See RFC 1123. -NM]
282 1.6. Alice's OP retrieves a service descriptor.
284 Alice opens a stream to a directory server via Tor, and makes an HTTP GET
285 request for the document '/tor/rendezvous/<z>' or '/tor/rendezvous1/<z>',
286 where '<z>' is replaced with the encoding of Bob's public key as described
287 above. (She may re-use old circuits for this.) The directory replies with
288 a 404 HTTP response if it does not recognize <z>, and otherwise returns
289 Bob's most recently uploaded service descriptor. (If Alice requests
290 'rendezvous1', the directory server provides a V1 descriptor or a V0
291 descriptor if no V1 descriptor is available. If Alice requests
292 'rendezvous', the directory server returns a V0 descriptor.)
294 If Alice's OP receives a 404 response, it tries the other directory
295 servers, and only fails the lookup if none recognize the public key hash.
297 Upon receiving a service descriptor, Alice verifies with the same process
298 as the directory server uses, described above in section 1.4.
300 The directory server gives a 400 response if it cannot understand Alice's
303 Alice should cache the descriptor locally, but should not use
304 descriptors that are more than 24 hours older than their timestamp.
305 [Caching may make her partitionable, but she fetched it anonymously,
306 and we can't very well *not* cache it. -RD]
308 1.7. Alice's OP establishes a rendezvous point.
310 When Alice requests a connection to a given location-hidden service,
311 and Alice's OP does not have an established circuit to that service,
312 the OP builds a rendezvous circuit. It does this by establishing
313 a circuit to a randomly chosen OR, and sending a
314 RELAY_ESTABLISH_RENDEZVOUS cell to that OR. The body of that cell
317 RC Rendezvous cookie [20 octets]
319 [XXX011 this looks like an auth mechanism. should we generalize here? -RD]
321 The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by
324 Upon receiving a RELAY_ESTABLISH_RENDEZVOUS cell, the OR associates the
325 RC with the circuit that sent it. It replies to Alice with an empty
326 RELAY_RENDEZVOUS_ESTABLISHED cell to indicate success.
328 Alice's OP MUST NOT use the circuit which sent the cell for any purpose
329 other than rendezvous with the given location-hidden service.
331 1.8. Introduction: from Alice's OP to Introduction Point
333 Alice builds a separate circuit to one of Bob's chosen introduction
334 points, and sends it a RELAY_INTRODUCE1 cell containing:
337 PK_ID Identifier for Bob's PK [20 octets]
338 [XXX011 want to put intro-level auth info here, but no version. crap. -RD]
340 Encrypted to Bob's PK:
341 RP Rendezvous point's nickname [20 octets]
342 RC Rendezvous cookie [20 octets]
343 g^x Diffie-Hellman data, part 1 [128 octets]
345 VER Version byte: set to 1. [1 octet]
346 RP Rendezvous point nick or ID [42 octets]
347 RC Rendezvous cookie [20 octets]
348 g^x Diffie-Hellman data, part 1 [128 octets]
350 VER Version byte: set to 2. [1 octet]
351 IP Rendezvous point's address [4 octets]
352 PORT Rendezvous point's OR port [2 octets]
353 ID Rendezvous point identity ID [20 octets]
354 KLEN Length of onion key [2 octets]
355 KEY Rendezvous point onion key [KLEN octets]
356 RC Rendezvous cookie [20 octets]
357 g^x Diffie-Hellman data, part 1 [128 octets]
359 VER Version byte: set to 3. [1 octet]
360 ATYPE An address type (typically 4) [1 octet]
361 ADDR Rendezvous point's IP address [4 or 16 octets]
362 PORT Rendezvous point's OR port [2 octets]
363 AUTHT The auth type that is supported [2 octets]
364 AUTHL Length of auth data [1 octet]
365 AUTHD Auth data [variable]
366 ID Rendezvous point identity ID [20 octets]
367 KLEN Length of onion key [2 octets]
368 KEY Rendezvous point onion key [KLEN octets]
369 RC Rendezvous cookie [20 octets]
370 g^x Diffie-Hellman data, part 1 [128 octets]
372 PK_ID is the hash of Bob's public key. RP is NUL-padded and terminated,
373 and must contain EITHER a nickname, or an identity key digest, encoded in
374 hex, and prefixed with a '$'.
376 Implementations SHOULD accept all variants, and list the variants they
377 accept in their V1 descriptor. Implementations should only generate the
378 variants listed in the service's V1 descriptor; if no V1 descriptor is
379 available, only the first variant should be generated. No version should
380 generate the second variant (version byte=1).
382 The hybrid encryption to Bob's PK works just like the hybrid
383 encryption in CREATE cells (see main spec). Thus the payload of the
384 RELAY_INTRODUCE1 cell on the wire will contain 20+42+16+20+20+128=246
385 bytes. [XXXX not really]
387 1.9. Introduction: From the Introduction Point to Bob's OP
389 If the Introduction Point recognizes PK_ID as a public key which has
390 established a circuit for introductions as in 1.3 above, it sends the body
391 of the cell in a new RELAY_INTRODUCE2 cell down the corresponding circuit.
392 (If the PK_ID is unrecognized, the RELAY_INTRODUCE1 cell is discarded.)
394 After sending the RELAY_INTRODUCE2 cell, the OR replies to Alice with an
395 empty RELAY_COMMAND_INTRODUCE_ACK cell. If no RELAY_INTRODUCE2 cell can
396 be sent, the OR replies to Alice with a non-empty cell to indicate an
397 error. (The semantics of the cell body may be determined later; the
398 current implementation sends a single '1' byte on failure.)
400 When Bob's OP receives the RELAY_INTRODUCE2 cell, it decrypts it with
401 the private key for the corresponding hidden service, and extracts the
402 rendezvous point's nickname, the rendezvous cookie, and the value of g^x
407 Bob's OP builds a new Tor circuit ending at Alice's chosen rendezvous
408 point, and sends a RELAY_RENDEZVOUS1 cell along this circuit, containing:
409 RC Rendezvous cookie [20 octets]
410 g^y Diffie-Hellman [128 octets]
411 KH Handshake digest [20 octets]
413 (Bob's OP MUST NOT use this circuit for any other purpose.)
415 If the RP recognizes RC, it relays the rest of the cell down the
416 corresponding circuit in a RELAY_RENDEZVOUS2 cell, containing:
418 g^y Diffie-Hellman [128 octets]
419 KH Handshake digest [20 octets]
421 (If the RP does not recognize the RC, it discards the cell and
422 tears down the circuit.)
424 When Alice's OP receives a RELAY_RENDEZVOUS2 cell on a circuit which
425 has sent a RELAY_ESTABLISH_RENDEZVOUS cell but which has not yet received
426 a reply, it uses g^y and H(g^xy) to complete the handshake as in the Tor
427 circuit extend process: they establish a 60-octet string as
428 K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02])
434 Subsequently, the rendezvous point passes relay cells, unchanged, from
435 each of the two circuits to the other. When Alice's OP sends
436 RELAY cells along the circuit, it first encrypts them with the
437 Kf, then with all of the keys for the ORs in Alice's side of the circuit;
438 and when Alice's OP receives RELAY cells from the circuit, it decrypts
439 them with the keys for the ORs in Alice's side of the circuit, then
440 decrypts them with Kb. Bob's OP does the same, with Kf and Kb
443 1.11. Creating streams
445 To open TCP connections to Bob's location-hidden service, Alice's OP sends
446 a RELAY_BEGIN cell along the established circuit, using the special
447 address "", and a chosen port. Bob's OP chooses a destination IP and
448 port, based on the configuration of the service connected to the circuit,
449 and opens a TCP stream. From then on, Bob's OP treats the stream as an
450 ordinary exit connection.
451 [ Except he doesn't include addr in the connected cell or the end
454 Alice MAY send multiple RELAY_BEGIN cells along the circuit, to open
455 multiple streams to Bob. Alice SHOULD NOT send RELAY_BEGIN cells for any
456 other address along her circuit to Bob; if she does, Bob MUST reject them.
458 2. Authentication and authorization.