3 [XXX We need to make nicknames in intro* cells padded to 20
4 bytes, and maybe have a fixed length for nicknames in the
7 Tor Rendezvous Specification
9 0. Overview and preliminaries
11 Rendezvous points provide location-hidden services (server
12 anonymity) for the onion routing network. With rendezvous points,
13 Bob can offer a TCP service (say, a webserver) via the onion
14 routing network, without revealing the IP of that service.
16 Bob does this by anonymously advertising a public key for his
17 service, along with a list of onion routers to act as "Introduction
18 Points" for his service. He creates forward OR circuits to those
19 introduction points, and tells them about his public key. To
20 connect to Bob, Alice first builds an OR circuit to an OR to act as
21 her "Rendezvous Point", then connects to one of Bob's chosen
22 introduction points, and asks it to tell him about her Rendezvous
23 Point (RP). If Bob chooses to answer, he builds an OR circuit to her
24 RP, and tells it to connect him to Alice. The RP joints their
25 circuits together, and begins relaying cells. Alice's 'BEGIN'
26 cells are received directly by Bob's OP, which responds by
27 communication with 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 as in
36 "tor-spec.txt". The service specified here also requires the existence of
37 an onion routing network as specified in "tor-spec.txt".
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.
53 1. Bob->Bob's OP: "Offer IP:Port as public-key-name:Port". [configuration]
54 (We do not specify this step; it is left to the implementor of
57 2. Bob's OP generates keypair and rendezvous service descriptor:
58 "Meet public-key X at introduction point A, B, or C." (signed)
60 3. Bob's OP->Introduction point via Tor: [introduction setup]
63 4. Bob's OP->directory service via Tor: publishes Bob's service descriptor
66 5. Out of band, Alice receives a y.onion:port address. She opens a
67 SOCKS connection to her OP, and requests y.onion:port.
69 6. Alice's OP retrieves Bob's descriptor via Tor: [descriptor lookup.]
71 7. Alice's OP chooses a rendezvous point, opens a circuit to that
72 rendezvous point, and establishes a rendezvous circuit. [rendezvous
75 8. Alice connects to the Introduction point via Tor, and tells it about
76 her rendezvous point. (Encrypted to Bob.) [Introduction 1]
78 9. The Introduction point passes this on to Bob's OP via Tor, along the
79 introduction circuit. [Introduction 2]
81 10. Bob's OP decides whether to connect to Alice, and if so, creates a
82 circuit to Alice's RP via Tor. Establishes a shared circuit.
85 11. Alice's OP sends begin cells to Bob's OP. [Connection]
87 0.3. Constants and new cell types
90 32 -- RELAY_ESTABLISH_INTRO
91 33 -- RELAY_ESTABLISH_RENDEZVOUS
92 34 -- RELAY_INTRODUCE1
93 35 -- RELAY_INTRODUCE2
94 36 -- RELAY_RENDEZVOUS1
95 37 -- RELAY_RENDEZVOUS2
96 38 -- RELAY_INTRO_ESTABLISHED
97 39 -- RELAY_RENDEZVOUS_ESTABLISHED
98 40 -- RELAY_COMMAND_INTRODUCE_ACK
102 1.1. Bob configures his local OP.
104 We do not specify a format for the OP configuration file. However,
105 OPs SHOULD allow Bob to provide more than one advertised service
106 per OP, and MUST allow Bob to specify one or more virtual ports per
107 service. Bob provides a mapping from each of these virtual ports
108 to a local IP:Port pair.
110 1.2. Bob's OP generates service descriptors.
112 The first time the OP provides an advertised service, it generates
113 a public/private keypair (stored locally). Periodically, the OP
114 generates a service descriptor, containing:
116 KL Key length [2 octets]
117 PK Bob's public key [KL octets]
118 TS A timestamp [4 octets]
119 NI Number of introduction points [2 octets]
120 Ipt A list of NUL-terminated ORs [variable]
121 SIG Signature of above fields [variable]
123 KL is the length of PK, in octets. (Currently, KL must be 128.)
124 TS is the number of seconds elapsed since Jan 1, 1970.
126 The members of Ipt may be either (a) nicknames, or (b) identity key
127 digests, encoded in hex, and prefixed with a '$'. Clients must
128 accept both forms. Services must only generate the second form.
129 Once 0.0.8.1 and 0.0.9pre3-4 are obsoleted, we can drop the first
132 [It's ok for Bob to advertise 0 introduction points. He might want
133 to do that if he previously advertised some introduction points,
134 and now he doesn't have any. -RD]
136 1.3. Bob's OP establishes his introduction points.
138 The OP establishes a new introduction circuit to each introduction
139 point. These circuits MUST NOT be used for anything but rendezvous
140 introduction. To establish the introduction, Bob sends a
141 RELAY_ESTABLISH_INTRO cell, containing:
143 KL Key length [2 octets]
144 PK Bob's public key [KL octets]
145 HS Hash of session info [20 octets]
146 SIG Signature of above information [variable]
148 To prevent replay attacks, the HS field contains a SHA-1 hash based on the
149 shared secret KH between Bob's OP and the introduction point, as
151 HS = H(KH | "INTRODUCE")
153 HS = H(KH | [49 4E 54 52 4F 44 55 43 45])
154 (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)
156 Upon receiving such a cell, the OR first checks that the signature is
157 correct with the included public key. If so, it checks whether HS is
158 correct given the shared state between Bob's OP and the OR. If either
159 check fails, the OP discards the cell; otherwise, it associates the
160 circuit with Bob's public key, and dissociates any other circuits
161 currently associated with PK. On success, the OR sends Bob a
162 RELAY_INTRO_ESTABLISHED cell with an empty payload.
164 1.4. Bob's OP advertises his service descriptor
166 Bob's OP opens a stream to each directory server's directory port via Tor.
167 (He may re-use old circuits for this.)
168 Over this stream, Bob's OP makes an HTTP 'POST' request, to the URL
169 '/tor/rendezvous/publish' (relative to the directory server's root),
170 containing as its body Bob's service descriptor. Upon receiving a
171 descriptor, the directory server checks the signature, and discards the
172 descriptor if the signature does not match the enclosed public key. Next,
173 the directory server checks the timestamp. If the timestamp is more than
174 24 hours in the past or more than 1 hour in the future, or the directory
175 server already has a newer descriptor with the same public key, the server
176 discards the descriptor. Otherwise, the server discards any older
177 descriptors with the same public key, and associates the new descriptor
178 with the public key. The directory server remembers this descriptor for
179 at least 24 hours after its timestamp. At least every 24 hours, Bob's OP
180 uploads a fresh descriptor.
182 1.5. Alice receives a y.onion address
184 When Alice receives a pointer to a location-hidden service, it is as a
185 hostname of the form "y.onion", where y is a base-32 encoding of a
186 10-octet hash of Bob's service's public key, computed as follows:
189 2. Let H' = the first 80 bits of H, considering each octet from
190 most significant bit to least significant bit.
191 2. Generate a 16-character encoding of H', using base32 as defined
194 (We only use 80 bits instead of the 160 bits from SHA1 because we don't
195 need to worry about man-in-the-middle attacks, and because it will make
196 handling the url's more convenient.)
198 [Yes, numbers are allowed at the beginning. See RFC1123. -NM]
200 1.6. Alice's OP retrieves a service descriptor
202 Alice opens a stream to a directory server via Tor, and makes an
203 HTTP GET request for the document '/tor/rendezvous/<y>', where
204 '<y> is replaced with the encoding of Bob's public key as described
205 above. (She may re-use old circuits for this.) The directory replies
206 with a 404 HTTP response if it does not recognize <y>, and otherwise
207 returns Bob's most recently uploaded service descriptor.
209 If Alice's OP receives a 404 response, it tries the other directory
210 servers, and only fails the lookup if none recognizes the public key hash.
212 Upon receiving a service descriptor, Alice verifies with the same process
213 as the directory server uses, described above in section 1.4.
215 The directory server gives a 400 response if it cannot understand Alice's
218 Alice should cache the descriptor locally, but should not use
219 descriptors that are more than 24 hours older than their timestamp.
220 [Caching may make her partitionable, but she fetched it anonymously,
221 and we can't very well *not* cache it. -RD]
223 1.7. Alice's OP establishes a rendezvous point.
225 When Alice requests a connection to a given location-hidden service,
226 and Alice's OP does not have an established circuit to that service,
227 the OP builds a rendezvous circuit. It does this by establishing
228 a circuit to a randomly chosen OR, and sending a
229 RELAY_ESTABLISH_RENDEZVOUS cell to that OR. The body of that cell
232 RC Rendezvous cookie [20 octets]
234 The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by
237 Upon receiving a RELAY_ESTABLISH_RENDEZVOUS cell, the OR associates the
238 RC with the circuit that sent it. It replies to Alice with an empty
239 RELAY_RENDEZVOUS_ESTABLISHED cell to indicate success.
241 Alice's OP MUST NOT use the circuit which sent the cell for any purpose
242 other than rendezvous with the given location-hidden service.
244 1.8. Introduction: from Alice's OP to Introduction Point
246 Alice builds a separate circuit to one of Bob's chosen introduction
247 points, and sends it a RELAY_INTRODUCE1 cell containing:
250 PK_ID Identifier for Bob's PK [20 octets]
252 Encrypted to Bob's PK:
253 RP Rendezvous point's nickname [20 octets]
254 RC Rendezvous cookie [20 octets]
255 g^x Diffie-Hellman data, part 1 [128 octets]
257 VER Version byte: set to 1. [1 octet]
259 RC Rendezvous cookie [20 octets]
260 g^x Diffie-Hellman data, part 1 [128 octets]
262 PK_ID is the hash of Bob's public key. RP is NUL-padded and terminated,
263 and must contain EITHER a nickname, or an identity key digest, encoded in
264 hex, and prefixed with a '$'.
266 Implementations must accept both variants, but should only generate the
267 first so long as Tor 0.0.7 is in use.
269 The hybrid encryption to Bob's PK works just like the hybrid
270 encryption in CREATE cells (see main spec). Thus the payload of the
271 RELAY_INTRODUCE1 cell on the wire will contain 20+42+16+20+20+128=246
274 1.9. Introduction: From the Introduction Point to Bob's OP
276 If the Introduction Point recognizes PK_ID as a public key which has
277 established a circuit for introductions as in 1.3 above, it sends the body
278 of the cell in a new RELAY_INTRODUCE2 cell down the corresponding circuit.
279 (If the PK_ID is unrecognized, the RELAY_INTRODUCE1 cell is discarded.)
281 After sending the RELAY_INTRODUCE2 cell, the OR replies to Alice with an
282 empty RELAY_COMMAND_INTRODUCE_ACK cell. If no RELAY_INTRODUCE2 cell can
283 be sent, the OR replies to Alice with a non-empty cell to indicate an
284 error. (The semantics of the cell body may be determined later; the
285 current implementation sends a single '1' byte on failure.)
287 When Bob's OP receives the RELAY_INTRODUCE2 cell, it decrypts it with
288 the private key for the corresponding hidden service, and extracts the
289 rendezvous point's nickname, the rendezvous cookie, and the value of g^x
294 Bob's OP build a new Tor circuit ending at Alice's chosen rendezvous
295 point, and sends a RELAY_RENDEZVOUS1 cell along this circuit, containing:
296 RC Rendezvous cookie [20 octets]
297 g^y Diffie-Hellman [128 octets]
298 KH Handshake digest [20 octets]
300 (Bob's OP MUST NOT use this circuit for any other purpose.)
302 If the RP recognizes RC, it relays the rest of the cell down the
303 corresponding circuit in a RELAY_RENDEZVOUS2 cell, containing:
305 g^y Diffie-Hellman [128 octets]
306 KH Handshake digest [20 octets]
308 (If the RP does not recognize the RC, it discards the cell and
309 tears down the circuit.)
311 When Alice's OP receives a RELAY_RENDEZVOUS2 cell on a circuit which
312 has sent a RELAY_ESTABLISH_RENDEZVOUS cell but which has not yet received
313 a reply, it uses g^y and H(g^xy) to complete the handshake as in the Tor
314 circuit extend process: they establish a 60-octet string as
315 K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02])
321 Subsequently, the rendezvous point passes relay cells, unchanged, from
322 each of the two circuits to the other. When Alice's OP sends
323 RELAY cells along the circuit, it first encrypts them with the
324 Kf, then with all of the keys for the ORs in Alice's side of the circuit;
325 and when Alice's OP receives RELAY cells from the circuit, it decrypts
326 them with the keys for the ORs in Alice's side of the circuit, then
327 decrypts them with Kb. Bob's OP does the same, with Kf and Kb
330 1.11. Creating streams
332 To open TCP connections to Bob's location-hidden service, Alice's OP sends
333 a RELAY_BEGIN cell along the established circuit, using the special
334 address "", and a chosen port. Bob's OP chooses a destination IP and
335 port, based on the configuration of the service connected to the circuit,
336 and opens a TCP stream. From then on, Bob's OP treats the stream as an
337 ordinary exit connection.
338 [ Except he doesn't include addr in the connected cell or the end
341 Alice MAY send multiple RELAY_BEGIN cells along the circuit, to open
342 multiple streams to Bob. Alice SHOULD NOT send RELAY_BEGIN cells for any
343 other address along her circuit to Bob; if she does, Bob MUST reject them.