| blob | 2a32f899ca2e90acd0a40ca645c6b75a9481b97b |
2 Tor Rendezvous Specification
4 0. Overview and preliminaries
6 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
7 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
8 "OPTIONAL" in this document are to be interpreted as described in
9 RFC 2119.
11 Read
12 https://www.torproject.org/doc/design-paper/tor-design.html#sec:rendezvous
13 before you read this specification. It will make more sense.
15 Rendezvous points provide location-hidden services (server
16 anonymity) for the onion routing network. With rendezvous points,
17 Bob can offer a TCP service (say, a webserver) via the onion
18 routing network, without revealing the IP of that service.
20 Bob does this by anonymously advertising a public key for his
21 service, along with a list of onion routers to act as "Introduction
22 Points" for his service. He creates forward circuits to those
23 introduction points, and tells them about his public key. To
24 connect to Bob, Alice first builds a circuit to an OR to act as
25 her "Rendezvous Point." She then connects to one of Bob's chosen
26 introduction points, optionally provides authentication or
27 authorization information, and asks it to tell him about her Rendezvous
28 Point (RP). If Bob chooses to answer, he builds a circuit to her
29 RP, and tells it to connect him to Alice. The RP joins their
30 circuits together, and begins relaying cells. Alice's 'BEGIN'
31 cells are received directly by Bob's OP, which passes data to
32 and from the local server implementing Bob's service.
34 Below we describe a network-level specification of this service,
35 along with interfaces to make this process transparent to Alice
36 (so long as she is using an OP).
38 0.1. Notation, conventions and prerequisites
40 In the specifications below, we use the same notation and terminology
41 as in "tor-spec.txt". The service specified here also requires the
42 existence of an onion routing network as specified in that file.
44 H(x) is a SHA1 digest of x.
45 PKSign(SK,x) is a PKCS.1-padded RSA signature of x with SK.
46 PKEncrypt(SK,x) is a PKCS.1-padded RSA encryption of x with SK.
47 Public keys are all RSA, and encoded in ASN.1.
48 All integers are stored in network (big-endian) order.
49 All symmetric encryption uses AES in counter mode, except where
50 otherwise noted.
52 In all discussions, "Alice" will refer to a user connecting to a
53 location-hidden service, and "Bob" will refer to a user running a
54 location-hidden service.
56 An OP is (as defined elsewhere) an "Onion Proxy" or Tor client.
58 An OR is (as defined elsewhere) an "Onion Router" or Tor server.
60 An "Introduction point" is a Tor server chosen to be Bob's medium-term
61 'meeting place'. A "Rendezvous point" is a Tor server chosen by Alice to
62 be a short-term communication relay between her and Bob. All Tor servers
63 potentially act as introduction and rendezvous points.
65 0.2. Protocol outline
67 1. Bob->Bob's OP: "Offer IP:Port as
68 public-key-name:Port". [configuration]
69 (We do not specify this step; it is left to the implementor of
70 Bob's OP.)
72 2. Bob's OP generates keypair and rendezvous service descriptor:
73 "Meet public-key X at introduction point A, B, or C." (signed)
75 3. Bob's OP->Introduction point via Tor: [introduction setup]
76 "This pk is me."
78 4. Bob's OP->directory service via Tor: publishes Bob's service
79 descriptor [advertisement]
81 5. Out of band, Alice receives a [x.y.]z.onion:port address.
82 She opens a SOCKS connection to her OP, and requests
83 x.y.z.onion:port.
85 6. Alice's OP retrieves Bob's descriptor via Tor. [descriptor lookup.]
87 7. Alice's OP chooses a rendezvous point, opens a circuit to that
88 rendezvous point, and establishes a rendezvous circuit. [rendezvous
89 setup.]
91 8. Alice connects to the Introduction point via Tor, and tells it about
92 her rendezvous point and optional authentication/authorization
93 information. (Encrypted to Bob.) [Introduction 1]
95 9. The Introduction point passes this on to Bob's OP via Tor, along the
96 introduction circuit. [Introduction 2]
98 10. Bob's OP decides whether to connect to Alice, and if so, creates a
99 circuit to Alice's RP via Tor. Establishes a shared circuit.
100 [Rendezvous.]
102 11. Alice's OP sends begin cells to Bob's OP. [Connection]
104 0.3. Constants and new cell types
106 Relay cell types
107 32 -- RELAY_COMMAND_ESTABLISH_INTRO
108 33 -- RELAY_COMMAND_ESTABLISH_RENDEZVOUS
109 34 -- RELAY_COMMAND_INTRODUCE1
110 35 -- RELAY_COMMAND_INTRODUCE2
111 36 -- RELAY_COMMAND_RENDEZVOUS1
112 37 -- RELAY_COMMAND_RENDEZVOUS2
113 38 -- RELAY_COMMAND_INTRO_ESTABLISHED
114 39 -- RELAY_COMMAND_RENDEZVOUS_ESTABLISHED
115 40 -- RELAY_COMMAND_INTRODUCE_ACK
117 0.4. Version overview
119 There are several parts in the hidden service protocol that have
120 changed over time, each of them having its own version number, whereas
121 other parts remained the same. The following list of potentially
122 versioned protocol parts should help reduce some confusion:
124 - Hidden service descriptor: the binary-based v0 was the default for
125 a long time, and an ascii-based v2 has been added by proposal
126 114. See 1.3.
128 - Hidden service descriptor propagation mechanism: currently related to
129 the hidden service descriptor version -- v0 publishes to the original
130 hs directory authorities, whereas v2 publishes to a rotating subset
131 of relays with the "hsdir" flag; see 1.4 and 1.6.
133 - Introduction protocol for how to generate an introduction cell:
134 v0 specified a nickname for the rendezvous point and assumed the
135 relay would know about it, whereas v2 now specifies IP address,
136 port, and onion key so the relay doesn't need to already recognize
137 it. See 1.8.
139 1. The Protocol
141 1.1. Bob configures his local OP.
143 We do not specify a format for the OP configuration file. However,
144 OPs SHOULD allow Bob to provide more than one advertised service
145 per OP, and MUST allow Bob to specify one or more virtual ports per
146 service. Bob provides a mapping from each of these virtual ports
147 to a local IP:Port pair.
149 1.2. Bob's OP establishes his introduction points.
151 The OP establishes a new introduction circuit to each introduction
152 point. These circuits MUST NOT be used for anything but hidden service
153 introduction. To establish the introduction, Bob sends a
154 RELAY_COMMAND_ESTABLISH_INTRO cell, containing:
156 KL Key length [2 octets]
157 PK Bob's public key [KL octets]
158 HS Hash of session info [20 octets]
159 SIG Signature of above information [variable]
161 [XXX011, need to add auth information here. -RD]
163 To prevent replay attacks, the HS field contains a SHA-1 hash based on the
164 shared secret KH between Bob's OP and the introduction point, as
165 follows:
166 HS = H(KH | "INTRODUCE")
167 That is:
168 HS = H(KH | [49 4E 54 52 4F 44 55 43 45])
169 (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)
171 Upon receiving such a cell, the OR first checks that the signature is
172 correct with the included public key. If so, it checks whether HS is
173 correct given the shared state between Bob's OP and the OR. If either
174 check fails, the OP discards the cell; otherwise, it associates the
175 circuit with Bob's public key, and dissociates any other circuits
176 currently associated with PK. On success, the OR sends Bob a
177 RELAY_COMMAND_INTRO_ESTABLISHED cell with an empty payload.
179 If a hidden service is configured to publish only v2 hidden service
180 descriptors, Bob's OP does not include its own public key in the
181 RELAY_COMMAND_ESTABLISH_INTRO cell, but the public key of a freshly
182 generated key pair. The OP also includes these fresh public keys in the v2
183 hidden service descriptor together with the other introduction point
184 information. The reason is that the introduction point does not need to
185 and therefore should not know for which hidden service it works, so as
186 to prevent it from tracking the hidden service's activity. If the hidden
187 service is configured to publish both, v0 and v2 descriptors, two
188 separate sets of introduction points are established.
190 1.3. Bob's OP generates service descriptors.
192 The first time the OP provides an advertised service, it generates
193 a public/private keypair (stored locally).
195 Beginning with 0.2.0.10-alpha, Bob's OP encodes "V2" descriptors. The
196 format of a "V2" descriptor is as follows:
198 "rendezvous-service-descriptor" descriptor-id NL
200 [At start, exactly once]
202 Indicates the beginning of the descriptor. "descriptor-id" is a
203 periodically changing identifier of 160 bits formatted as 32 base32
204 chars that is calculated by the hidden service and its clients. If
205 the optional "descriptor-cookie" is used, this "descriptor-id"
206 cannot be computed by anyone else. (Everyone can verify that this
207 "descriptor-id" belongs to the rest of the descriptor, even without
208 knowing the optional "descriptor-cookie", as described below.) The
209 "descriptor-id" is calculated by performing the following operation:
211 descriptor-id =
212 H(permanent-id | H(time-period | descriptor-cookie | replica))
214 "permanent-id" is the permanent identifier of the hidden service,
215 consisting of 80 bits. It can be calculated by computing the hash value
216 of the public hidden service key and truncating after the first 80 bits:
218 permanent-id = H(public-key)[:10]
220 "H(time-period | descriptor-cookie | replica)" is the (possibly
221 secret) id part that is
222 necessary to verify that the hidden service is the true originator
223 of this descriptor. It can only be created by the hidden service
224 and its clients, but the "signature" below can only be created by
225 the service.
227 "descriptor-cookie" is an optional secret password of 128 bits that
228 is shared between the hidden service provider and its clients.
230 "replica" denotes the number of the non-consecutive replica.
232 (Each descriptor is replicated on a number of _consecutive_ nodes
233 in the identifier ring by making every storing node responsible
234 for the identifier intervals starting from its 3rd predecessor's
235 ID to its own ID. In addition to that, every service publishes
236 multiple descriptors with different descriptor IDs in order to
237 distribute them to different places on the ring. Therefore,
238 "replica" chooses one of the _non-consecutive_ replicas. -KL)
240 The "time-period" changes periodically depending on the global time and
241 as a function of "permanent-id". The current value for "time-period" can
242 be calculated using the following formula:
244 time-period = (current-time + permanent-id-byte * 86400 / 256)
245 / 86400
247 "current-time" contains the current system time in seconds since
248 1970-01-01 00:00, e.g. 1188241957. "permanent-id-byte" is the first
249 (unsigned) byte of the permanent identifier (which is in network
250 order), e.g. 143. Adding the product of "permanent-id-byte" and
251 86400 (seconds per day), divided by 256, prevents "time-period" from
252 changing for all descriptors at the same time of the day. The result
253 of the overall operation is a (network-ordered) 32-bit integer, e.g.
254 13753 or 0x000035B9 with the example values given above.
256 "version" version-number NL
258 [Exactly once]
260 The version number of this descriptor's format. In this case: 2.
262 "permanent-key" NL a public key in PEM format
264 [Exactly once]
266 The public key of the hidden service which is required to verify the
267 "descriptor-id" and the "signature".
269 "secret-id-part" secret-id-part NL
271 [Exactly once]
273 The result of the following operation as explained above, formatted as
274 32 base32 chars. Using this secret id part, everyone can verify that
275 the signed descriptor belongs to "descriptor-id".
277 secret-id-part = H(time-period | descriptor-cookie | replica)
279 "publication-time" YYYY-MM-DD HH:MM:SS NL
281 [Exactly once]
283 A timestamp when this descriptor has been created.
285 "protocol-versions" version-string NL
287 [Exactly once]
289 A comma-separated list of recognized and permitted version numbers
290 for use in INTRODUCE cells; these versions are described in section
291 1.8 below.
293 "introduction-points" NL encrypted-string
295 [At most once]
297 A list of introduction points. If the optional "descriptor-cookie" is
298 used, this list is encrypted with AES in CTR mode with a random
299 initialization vector of 128 bits that is written to
300 the beginning of the encrypted string, and the "descriptor-cookie" as
301 secret key of 128 bits length.
303 The string containing the introduction point data (either encrypted
304 or not) is encoded in base64, and surrounded with
305 "-----BEGIN MESSAGE-----" and "-----END MESSAGE-----".
307 The unencrypted string may begin with:
309 ["service-authentication" auth-type NL auth-data ... reserved]
311 [At start, any number]
313 The service-specific authentication data can be used to perform
314 client authentication. This data is independent of the selected
315 introduction point as opposed to "intro-authentication" below.
317 Subsequently, an arbitrary number of introduction point entries may
318 follow, each containing the following data:
320 "introduction-point" identifier NL
322 [At start, exactly once]
324 The identifier of this introduction point: the base-32 encoded
325 hash of this introduction point's identity key.
327 "ip-address" ip-address NL
329 [Exactly once]
331 The IP address of this introduction point.
333 "onion-port" port NL
335 [Exactly once]
337 The TCP port on which the introduction point is listening for
338 incoming onion requests.
340 "onion-key" NL a public key in PEM format
342 [Exactly once]
344 The public key that can be used to encrypt messages to this
345 introduction point.
347 "service-key" NL a public key in PEM format
349 [Exactly once]
351 The public key that can be used to encrypt messages to the hidden
352 service.
354 ["intro-authentication" auth-type NL auth-data ... reserved]
356 [Any number]
358 The introduction-point-specific authentication data can be used
359 to perform client authentication. This data depends on the
360 selected introduction point as opposed to "service-authentication"
361 above.
363 (This ends the fields in the encrypted portion of the descriptor.)
365 [It's ok for Bob to advertise 0 introduction points. He might want
366 to do that if he previously advertised some introduction points,
367 and now he doesn't have any. -RD]
369 "signature" NL signature-string
371 [At end, exactly once]
373 A signature of all fields above with the private key of the hidden
374 service.
376 1.3.1. Other descriptor formats we don't use.
378 Support for the V0 descriptor format was dropped in 0.2.2.0-alpha-dev:
380 KL Key length [2 octets]
381 PK Bob's public key [KL octets]
382 TS A timestamp [4 octets]
383 NI Number of introduction points [2 octets]
384 Ipt A list of NUL-terminated ORs [variable]
385 SIG Signature of above fields [variable]
387 KL is the length of PK, in octets.
388 TS is the number of seconds elapsed since Jan 1, 1970.
390 The members of Ipt may be either (a) nicknames, or (b) identity key
391 digests, encoded in hex, and prefixed with a '$'.
393 The V1 descriptor format was understood and accepted from
394 0.1.1.5-alpha-cvs to 0.2.0.6-alpha-dev, but no Tors generated it and
395 it was removed:
397 V Format byte: set to 255 [1 octet]
398 V Version byte: set to 1 [1 octet]
399 KL Key length [2 octets]
400 PK Bob's public key [KL octets]
401 TS A timestamp [4 octets]
402 PROTO Protocol versions: bitmask [2 octets]
403 NI Number of introduction points [2 octets]
404 For each introduction point: (as in INTRODUCE2 cells)
405 IP Introduction point's address [4 octets]
406 PORT Introduction point's OR port [2 octets]
407 ID Introduction point identity ID [20 octets]
408 KLEN Length of onion key [2 octets]
409 KEY Introduction point onion key [KLEN octets]
410 SIG Signature of above fields [variable]
412 A hypothetical "V1" descriptor, that has never been used but might
413 be useful for historical reasons, contains:
415 V Format byte: set to 255 [1 octet]
416 V Version byte: set to 1 [1 octet]
417 KL Key length [2 octets]
418 PK Bob's public key [KL octets]
419 TS A timestamp [4 octets]
420 PROTO Rendezvous protocol versions: bitmask [2 octets]
421 NA Number of auth mechanisms accepted [1 octet]
422 For each auth mechanism:
423 AUTHT The auth type that is supported [2 octets]
424 AUTHL Length of auth data [1 octet]
425 AUTHD Auth data [variable]
426 NI Number of introduction points [2 octets]
427 For each introduction point: (as in INTRODUCE2 cells)
428 ATYPE An address type (typically 4) [1 octet]
429 ADDR Introduction point's IP address [4 or 16 octets]
430 PORT Introduction point's OR port [2 octets]
431 AUTHT The auth type that is supported [2 octets]
432 AUTHL Length of auth data [1 octet]
433 AUTHD Auth data [variable]
434 ID Introduction point identity ID [20 octets]
435 KLEN Length of onion key [2 octets]
436 KEY Introduction point onion key [KLEN octets]
437 SIG Signature of above fields [variable]
439 AUTHT specifies which authentication/authorization mechanism is
440 required by the hidden service or the introduction point. AUTHD
441 is arbitrary data that can be associated with an auth approach.
442 Currently only AUTHT of [00 00] is supported, with an AUTHL of 0.
443 See section 2 of this document for details on auth mechanisms.
445 1.4. Bob's OP advertises his service descriptor(s).
447 Bob's OP opens a stream to each directory server's directory port via Tor.
448 (He may re-use old circuits for this.) Over this stream, Bob's OP makes
449 an HTTP 'POST' request, to a URL "/tor/rendezvous/publish" relative to the
450 directory server's root, containing as its body Bob's service descriptor.
452 Bob should upload a service descriptor for each version format that
453 is supported in the current Tor network.
455 Upon receiving a descriptor, the directory server checks the signature,
456 and discards the descriptor if the signature does not match the enclosed
457 public key. Next, the directory server checks the timestamp. If the
458 timestamp is more than 24 hours in the past or more than 1 hour in the
459 future, or the directory server already has a newer descriptor with the
460 same public key, the server discards the descriptor. Otherwise, the
461 server discards any older descriptors with the same public key and
462 version format, and associates the new descriptor with the public key.
463 The directory server remembers this descriptor for at least 24 hours
464 after its timestamp. At least every 18 hours, Bob's OP uploads a
465 fresh descriptor.
467 Bob's OP publishes v2 descriptors to a changing subset of all v2 hidden
468 service directories. Therefore, Bob's OP opens a stream via Tor to each
469 responsible hidden service directory. (He may re-use old circuits
470 for this.) Over this stream, Bob's OP makes an HTTP 'POST' request to a
471 URL "/tor/rendezvous2/publish" relative to the hidden service
472 directory's root, containing as its body Bob's service descriptor.
474 At any time, there are 6 hidden service directories responsible for
475 keeping replicas of a descriptor; they consist of 2 sets of 3 hidden
476 service directories with consecutive onion IDs. Bob's OP learns about
477 the complete list of hidden service directories by filtering the
478 consensus status document received from the directory authorities. A
479 hidden service directory is deemed responsible for all descriptor IDs in
480 the interval from its direct predecessor, exclusive, to its own ID,
481 inclusive; it further holds replicas for its 2 predecessors. A
482 participant only trusts its own routing list and never learns about
483 routing information from other parties.
485 Bob's OP publishes a new v2 descriptor once an hour or whenever its
486 content changes. V2 descriptors can be found by clients within a given
487 time period of 24 hours, after which they change their ID as described
488 under 1.3. If a published descriptor would be valid for less than 60
489 minutes (= 2 x 30 minutes to allow the server to be 30 minutes behind
490 and the client 30 minutes ahead), Bob's OP publishes the descriptor
491 under the ID of both, the current and the next publication period.
493 1.5. Alice receives a x.y.z.onion address.
495 When Alice receives a pointer to a location-hidden service, it is as a
496 hostname of the form "z.onion" or "y.z.onion" or "x.y.z.onion", where
497 z is a base-32 encoding of a 10-octet hash of Bob's service's public
498 key, computed as follows:
500 1. Let H = H(PK).
501 2. Let H' = the first 80 bits of H, considering each octet from
502 most significant bit to least significant bit.
503 2. Generate a 16-character encoding of H', using base32 as defined
504 in RFC 3548.
506 (We only use 80 bits instead of the 160 bits from SHA1 because we
507 don't need to worry about arbitrary collisions, and because it will
508 make handling the url's more convenient.)
510 The string "x", if present, is the base-32 encoding of the
511 authentication/authorization required by the introduction point.
512 The string "y", if present, is the base-32 encoding of the
513 authentication/authorization required by the hidden service.
514 Omitting a string is taken to mean auth type [00 00].
515 See section 2 of this document for details on auth mechanisms.
517 [Yes, numbers are allowed at the beginning. See RFC 1123. -NM]
519 1.6. Alice's OP retrieves a service descriptor.
521 Similarly to the description in section 1.4, Alice's OP fetches a v2
522 descriptor from a randomly chosen hidden service directory out of the
523 changing subset of 6 nodes. If the request is unsuccessful, Alice retries
524 the other remaining responsible hidden service directories in a random
525 order. Alice relies on Bob to care about a potential clock skew between
526 the two by possibly storing two sets of descriptors (see end of section
527 1.4).
529 Alice's OP opens a stream via Tor to the chosen v2 hidden service
530 directory. (She may re-use old circuits for this.) Over this stream,
531 Alice's OP makes an HTTP 'GET' request for the document
532 "/tor/rendezvous2/<z>", where z is replaced with the encoding of the
533 descriptor ID. The directory replies with a 404 HTTP response if it does
534 not recognize <z>, and otherwise returns Bob's most recently uploaded
535 service descriptor.
537 If Alice's OP receives a 404 response, it tries the other directory
538 servers, and only fails the lookup if none recognize the public key hash.
540 Upon receiving a service descriptor, Alice verifies with the same process
541 as the directory server uses, described above in section 1.4.
543 The directory server gives a 400 response if it cannot understand Alice's
544 request.
546 Alice should cache the descriptor locally, but should not use
547 descriptors that are more than 24 hours older than their timestamp.
548 [Caching may make her partitionable, but she fetched it anonymously,
549 and we can't very well *not* cache it. -RD]
551 1.7. Alice's OP establishes a rendezvous point.
553 When Alice requests a connection to a given location-hidden service,
554 and Alice's OP does not have an established circuit to that service,
555 the OP builds a rendezvous circuit. It does this by establishing
556 a circuit to a randomly chosen OR, and sending a
557 RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell to that OR. The body of that cell
558 contains:
560 RC Rendezvous cookie [20 octets]
562 [XXX011 this looks like an auth mechanism. should we generalize here? -RD]
564 The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by
565 Alice's OP.
567 Upon receiving a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell, the OR associates
568 the RC with the circuit that sent it. It replies to Alice with an empty
569 RELAY_COMMAND_RENDEZVOUS_ESTABLISHED cell to indicate success.
571 Alice's OP MUST NOT use the circuit which sent the cell for any purpose
572 other than rendezvous with the given location-hidden service.
574 1.8. Introduction: from Alice's OP to Introduction Point
576 Alice builds a separate circuit to one of Bob's chosen introduction
577 points, and sends it a RELAY_COMMAND_INTRODUCE1 cell containing:
579 Cleartext
580 PK_ID Identifier for Bob's PK [20 octets]
581 Encrypted to Bob's PK: (in the v0 intro protocol)
582 RP Rendezvous point's nickname [20 octets]
583 RC Rendezvous cookie [20 octets]
584 g^x Diffie-Hellman data, part 1 [128 octets]
585 OR (in the v1 intro protocol)
586 VER Version byte: set to 1. [1 octet]
587 RP Rendezvous point nick or ID [42 octets]
588 RC Rendezvous cookie [20 octets]
589 g^x Diffie-Hellman data, part 1 [128 octets]
590 OR (in the v2 intro protocol)
591 VER Version byte: set to 2. [1 octet]
592 IP Rendezvous point's address [4 octets]
593 PORT Rendezvous point's OR port [2 octets]
594 ID Rendezvous point identity ID [20 octets]
595 KLEN Length of onion key [2 octets]
596 KEY Rendezvous point onion key [KLEN octets]
597 RC Rendezvous cookie [20 octets]
598 g^x Diffie-Hellman data, part 1 [128 octets]
600 PK_ID is the hash of Bob's public key. RP is NUL-padded and
601 terminated. In version 0, it must contain a nickname. In version 1,
602 it must contain EITHER a nickname or an identity key digest that is
603 encoded in hex and prefixed with a '$'.
605 The hybrid encryption to Bob's PK works just like the hybrid
606 encryption in CREATE cells (see tor-spec). Thus the payload of the
607 version 0 RELAY_COMMAND_INTRODUCE1 cell on the wire will contain
608 20+42+16+20+20+128=246 bytes, and the version 1 and version 2
609 introduction formats have other sizes.
611 Through Tor 0.2.0.6-alpha, clients only generated the v0 introduction
612 format, whereas hidden services have understood and accepted v0,
613 v1, and v2 since 0.1.1.x. As of Tor 0.2.0.7-alpha and 0.1.2.18,
614 clients switched to using the v2 intro format.
616 If Alice has downloaded a v2 descriptor, she uses the contained public
617 key ("service-key") instead of Bob's public key to create the
618 RELAY_COMMAND_INTRODUCE1 cell as described above.
620 1.8.1. Other introduction formats we don't use.
622 We briefly speculated about using the following format for the
623 "encrypted to Bob's PK" part of the introduction, but no Tors have
624 ever generated these.
626 VER Version byte: set to 3. [1 octet]
627 ATYPE An address type (typically 4) [1 octet]
628 ADDR Rendezvous point's IP address [4 or 16 octets]
629 PORT Rendezvous point's OR port [2 octets]
630 AUTHT The auth type that is supported [2 octets]
631 AUTHL Length of auth data [1 octet]
632 AUTHD Auth data [variable]
633 ID Rendezvous point identity ID [20 octets]
634 KLEN Length of onion key [2 octets]
635 KEY Rendezvous point onion key [KLEN octets]
636 RC Rendezvous cookie [20 octets]
637 g^x Diffie-Hellman data, part 1 [128 octets]
639 1.9. Introduction: From the Introduction Point to Bob's OP
641 If the Introduction Point recognizes PK_ID as a public key which has
642 established a circuit for introductions as in 1.2 above, it sends the body
643 of the cell in a new RELAY_COMMAND_INTRODUCE2 cell down the corresponding
644 circuit. (If the PK_ID is unrecognized, the RELAY_COMMAND_INTRODUCE1 cell is
645 discarded.)
647 After sending the RELAY_COMMAND_INTRODUCE2 cell, the OR replies to Alice
648 with an empty RELAY_COMMAND_INTRODUCE_ACK cell. If no
649 RELAY_COMMAND_INTRODUCE2 cell can be sent, the OR replies to Alice with a
650 non-empty cell to indicate an error. (The semantics of the cell body may be
651 determined later; the current implementation sends a single '1' byte on
652 failure.)
654 When Bob's OP receives the RELAY_COMMAND_INTRODUCE2 cell, it decrypts it
655 with the private key for the corresponding hidden service, and extracts the
656 rendezvous point's nickname, the rendezvous cookie, and the value of g^x
657 chosen by Alice.
659 1.10. Rendezvous
661 Bob's OP builds a new Tor circuit ending at Alice's chosen rendezvous
662 point, and sends a RELAY_COMMAND_RENDEZVOUS1 cell along this circuit,
663 containing:
664 RC Rendezvous cookie [20 octets]
665 g^y Diffie-Hellman [128 octets]
666 KH Handshake digest [20 octets]
668 (Bob's OP MUST NOT use this circuit for any other purpose.)
670 If the RP recognizes RC, it relays the rest of the cell down the
671 corresponding circuit in a RELAY_COMMAND_RENDEZVOUS2 cell, containing:
673 g^y Diffie-Hellman [128 octets]
674 KH Handshake digest [20 octets]
676 (If the RP does not recognize the RC, it discards the cell and
677 tears down the circuit.)
679 When Alice's OP receives a RELAY_COMMAND_RENDEZVOUS2 cell on a circuit which
680 has sent a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell but which has not yet
681 received a reply, it uses g^y and H(g^xy) to complete the handshake as in
682 the Tor circuit extend process: they establish a 60-octet string as
683 K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02])
684 and generate
685 KH = K[0..15]
686 Kf = K[16..31]
687 Kb = K[32..47]
689 Subsequently, the rendezvous point passes relay cells, unchanged, from
690 each of the two circuits to the other. When Alice's OP sends
691 RELAY cells along the circuit, it first encrypts them with the
692 Kf, then with all of the keys for the ORs in Alice's side of the circuit;
693 and when Alice's OP receives RELAY cells from the circuit, it decrypts
694 them with the keys for the ORs in Alice's side of the circuit, then
695 decrypts them with Kb. Bob's OP does the same, with Kf and Kb
696 interchanged.
698 1.11. Creating streams
700 To open TCP connections to Bob's location-hidden service, Alice's OP sends
701 a RELAY_COMMAND_BEGIN cell along the established circuit, using the special
702 address "", and a chosen port. Bob's OP chooses a destination IP and
703 port, based on the configuration of the service connected to the circuit,
704 and opens a TCP stream. From then on, Bob's OP treats the stream as an
705 ordinary exit connection.
706 [ Except he doesn't include addr in the connected cell or the end
707 cell. -RD]
709 Alice MAY send multiple RELAY_COMMAND_BEGIN cells along the circuit, to open
710 multiple streams to Bob. Alice SHOULD NOT send RELAY_COMMAND_BEGIN cells
711 for any other address along her circuit to Bob; if she does, Bob MUST reject
712 them.
714 2. Authentication and authorization.
716 Foo.
718 3. Hidden service directory operation
720 This section has been introduced with the v2 hidden service descriptor
721 format. It describes all operations of the v2 hidden service descriptor
722 fetching and propagation mechanism that are required for the protocol
723 described in section 1 to succeed with v2 hidden service descriptors.
725 3.1. Configuring as hidden service directory
727 Every onion router that has its directory port open can decide whether it
728 wants to store and serve hidden service descriptors. An onion router which
729 is configured as such includes the "hidden-service-dir" flag in its router
730 descriptors that it sends to directory authorities.
732 The directory authorities include a new flag "HSDir" for routers that
733 decided to provide storage for hidden service descriptors and that
734 have been running for at least 24 hours.
736 3.2. Accepting publish requests
738 Hidden service directory nodes accept publish requests for v2 hidden service
739 descriptors and store them to their local memory. (It is not necessary to
740 make descriptors persistent, because after restarting, the onion router
741 would not be accepted as a storing node anyway, because it has not been
742 running for at least 24 hours.) All requests and replies are formatted as
743 HTTP messages. Requests are initiated via BEGIN_DIR cells directed to
744 the router's directory port, and formatted as HTTP POST requests to the URL
745 "/tor/rendezvous2/publish" relative to the hidden service directory's root,
746 containing as its body a v2 service descriptor.
748 A hidden service directory node parses every received descriptor and only
749 stores it when it thinks that it is responsible for storing that descriptor
750 based on its own routing table. See section 1.4 for more information on how
751 to determine responsibility for a certain descriptor ID.
753 3.3. Processing fetch requests
755 Hidden service directory nodes process fetch requests for hidden service
756 descriptors by looking them up in their local memory. (They do not need to
757 determine if they are responsible for the passed ID, because it does no harm
758 if they deliver a descriptor for which they are not (any more) responsible.)
759 All requests and replies are formatted as HTTP messages. Requests are
760 initiated via BEGIN_DIR cells directed to the router's directory port,
761 and formatted as HTTP GET requests for the document "/tor/rendezvous2/<z>",
762 where z is replaced with the encoding of the descriptor ID.