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
12 https://svn.torproject.org/svn/projects/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 service. 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, and asks it to tell him about her Rendezvous
27 Point (RP). If Bob chooses to answer, he builds a circuit to her
28 RP, and tells it to connect him to Alice. The RP joins their
29 circuits together, and begins relaying cells. Alice's 'BEGIN'
30 cells are received directly by Bob's OP, which passes data to
31 and from the local server implementing Bob's service.
33 Below we describe a network-level specification of this service,
34 along with interfaces to make this process transparent to Alice
35 (so long as she is using an OP).
37 0.1. Notation, conventions and prerequisites
39 In the specifications below, we use the same notation and terminology
40 as in "tor-spec.txt". The service specified here also requires the
41 existence of an onion routing network as specified in that file.
43 H(x) is a SHA1 digest of x.
44 PKSign(SK,x) is a PKCS.1-padded RSA signature of x with SK.
45 PKEncrypt(SK,x) is a PKCS.1-padded RSA encryption of x with SK.
46 Public keys are all RSA, and encoded in ASN.1.
47 All integers are stored in network (big-endian) order.
48 All symmetric encryption uses AES in counter mode, except where
51 In all discussions, "Alice" will refer to a user connecting to a
52 location-hidden service, and "Bob" will refer to a user running a
53 location-hidden service.
55 An OP is (as defined elsewhere) an "Onion Proxy" or Tor client.
57 An OR is (as defined elsewhere) an "Onion Router" or Tor server.
59 An "Introduction point" is a Tor server chosen to be Bob's medium-term
60 'meeting place'. A "Rendezvous point" is a Tor server chosen by Alice to
61 be a short-term communication relay between her and Bob. All Tor servers
62 potentially act as introduction and rendezvous points.
66 1. Bob->Bob's OP: "Offer IP:Port as public-key-name:Port". [configuration]
67 (We do not specify this step; it is left to the implementor of
70 2. Bob's OP generates a long-term keypair.
72 3. Bob's OP->Introduction point via Tor: [introduction setup]
73 "This public key is (currently) associated to me."
75 4. Bob's OP->directory service via Tor: publishes Bob's service descriptor
77 "Meet public-key X at introduction point A, B, or C." (signed)
79 5. Out of band, Alice receives a z.onion:port address.
80 She opens a SOCKS connection to her OP, and requests z.onion:port.
82 6. Alice's OP retrieves Bob's descriptor via Tor. [descriptor lookup.]
84 7. Alice's OP chooses a rendezvous point, opens a circuit to that
85 rendezvous point, and establishes a rendezvous circuit. [rendezvous
88 8. Alice connects to the Introduction point via Tor, and tells it about
89 her rendezvous point. (Encrypted to Bob.) [Introduction 1]
91 9. The Introduction point passes this on to Bob's OP via Tor, along the
92 introduction circuit. [Introduction 2]
94 10. Bob's OP decides whether to connect to Alice, and if so, creates a
95 circuit to Alice's RP via Tor. Establishes a shared circuit.
98 11. The Rendezvous point forwards Bob's confirmation to Alice's OP.
101 12. Alice's OP sends begin cells to Bob's OP. [Connection]
103 0.3. Constants and new cell types
106 32 -- RELAY_COMMAND_ESTABLISH_INTRO
107 33 -- RELAY_COMMAND_ESTABLISH_RENDEZVOUS
108 34 -- RELAY_COMMAND_INTRODUCE1
109 35 -- RELAY_COMMAND_INTRODUCE2
110 36 -- RELAY_COMMAND_RENDEZVOUS1
111 37 -- RELAY_COMMAND_RENDEZVOUS2
112 38 -- RELAY_COMMAND_INTRO_ESTABLISHED
113 39 -- RELAY_COMMAND_RENDEZVOUS_ESTABLISHED
114 40 -- RELAY_COMMAND_INTRODUCE_ACK
116 0.4. Version overview
118 There are several parts in the hidden service protocol that have
119 changed over time, each of them having its own version number, whereas
120 other parts remained the same. The following list of potentially
121 versioned protocol parts should help reduce some confusion:
123 - Hidden service descriptor: the binary-based v0 was the default for a
124 long time, and an ASCII-based v2 has been added by proposal 114. The
125 v0 descriptor format has been deprecated in 0.2.2.1-alpha. See 1.3.
127 - Hidden service descriptor propagation mechanism: currently related to
128 the hidden service descriptor version -- v0 publishes to the original
129 hs directory authorities, whereas v2 publishes to a rotating subset
130 of relays with the "HSDir" flag; see 1.4 and 1.6.
132 - Introduction protocol for how to generate an introduction cell:
133 v0 specified a nickname for the rendezvous point and assumed the
134 relay would know about it, whereas v2 now specifies IP address,
135 port, and onion key so the relay doesn't need to already recognize
140 1.1. Bob configures his local OP.
142 We do not specify a format for the OP configuration file. However,
143 OPs SHOULD allow Bob to provide more than one advertised service
144 per OP, and MUST allow Bob to specify one or more virtual ports per
145 service. Bob provides a mapping from each of these virtual ports
146 to a local IP:Port pair.
148 1.2. Bob's OP establishes his introduction points.
150 The first time the OP provides an advertised service, it generates
151 a public/private keypair (stored locally).
153 The OP chooses a small number of Tor servers as introduction points.
154 The OP establishes a new introduction circuit to each introduction
155 point. These circuits MUST NOT be used for anything but hidden service
156 introduction. To establish the introduction, Bob sends a
157 RELAY_COMMAND_ESTABLISH_INTRO cell, containing:
159 KL Key length [2 octets]
160 PK Bob's public key or service key [KL octets]
161 HS Hash of session info [20 octets]
162 SIG Signature of above information [variable]
164 KL is the length of PK, in octets.
166 To prevent replay attacks, the HS field contains a SHA-1 hash based on the
167 shared secret KH between Bob's OP and the introduction point, as
169 HS = H(KH | "INTRODUCE")
171 HS = H(KH | [49 4E 54 52 4F 44 55 43 45])
172 (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)
174 Upon receiving such a cell, the OR first checks that the signature is
175 correct with the included public key. If so, it checks whether HS is
176 correct given the shared state between Bob's OP and the OR. If either
177 check fails, the OP discards the cell; otherwise, it associates the
178 circuit with Bob's public key, and dissociates any other circuits
179 currently associated with PK. On success, the OR sends Bob a
180 RELAY_COMMAND_INTRO_ESTABLISHED cell with an empty payload.
182 Bob's OP uses either Bob's public key or a freshly generated, single-use
183 service key in the RELAY_COMMAND_ESTABLISH_INTRO cell, depending on the
184 configured hidden service descriptor version. The public key is used for
185 v0 descriptors, the service key for v2 descriptors. In the latter case, the
186 service keys of all introduction points are included in the v2 hidden
187 service descriptor together with the other introduction point information.
188 The reason is that the introduction point does not need to and therefore
189 should not know for which hidden service it works, so as to prevent it from
190 tracking the hidden service's activity. If the hidden service is configured
191 to publish both v0 and v2 descriptors, two separate sets of introduction
192 points are established.
194 1.3. Bob's OP generates service descriptors.
196 For versions before 0.2.2.1-alpha, Bob's OP periodically generates and
197 publishes a descriptor of type "V0".
199 The "V0" descriptor contains:
201 KL Key length [2 octets]
202 PK Bob's public key [KL octets]
203 TS A timestamp [4 octets]
204 NI Number of introduction points [2 octets]
205 Ipt A list of NUL-terminated ORs [variable]
206 SIG Signature of above fields [variable]
208 TS is the number of seconds elapsed since Jan 1, 1970.
210 The members of Ipt may be either (a) nicknames, or (b) identity key
211 digests, encoded in hex, and prefixed with a '$'. Clients must
212 accept both forms. Services must only generate the second form.
213 Once 0.0.9.x is obsoleted, we can drop the first form.
215 [It's ok for Bob to advertise 0 introduction points. He might want
216 to do that if he previously advertised some introduction points,
217 and now he doesn't have any. -RD]
219 Beginning with 0.2.0.10-alpha, Bob's OP encodes "V2" descriptors in
220 addition to (or instead of) "V0" descriptors. The format of a "V2"
221 descriptor is as follows:
223 "rendezvous-service-descriptor" descriptor-id NL
225 [At start, exactly once]
227 Indicates the beginning of the descriptor. "descriptor-id" is a
228 periodically changing identifier of 160 bits formatted as 32 base32
229 chars that is calculated by the hidden service and its clients. The
230 "descriptor-id" is calculated by performing the following operation:
233 H(permanent-id | H(time-period | descriptor-cookie | replica))
235 "permanent-id" is the permanent identifier of the hidden service,
236 consisting of 80 bits. It can be calculated by computing the hash value
237 of the public hidden service key and truncating after the first 80 bits:
239 permanent-id = H(public-key)[:10]
241 Note: If Bob's OP has "stealth" authorization enabled (see Section 2.2),
242 it uses the client key in place of the public hidden service key.
244 "H(time-period | descriptor-cookie | replica)" is the (possibly
245 secret) id part that is necessary to verify that the hidden service is
246 the true originator of this descriptor and that is therefore contained
247 in the descriptor, too. The descriptor ID can only be created by the
248 hidden service and its clients, but the "signature" below can only be
249 created by the service.
251 "time-period" changes periodically as a function of time and
253 "permanent-id". The current value for "time-period" can be calculated
254 using the following formula:
256 time-period = (current-time + permanent-id-byte * 86400 / 256)
259 "current-time" contains the current system time in seconds since
260 1970-01-01 00:00, e.g. 1188241957. "permanent-id-byte" is the first
261 (unsigned) byte of the permanent identifier (which is in network
262 order), e.g. 143. Adding the product of "permanent-id-byte" and
263 86400 (seconds per day), divided by 256, prevents "time-period" from
264 changing for all descriptors at the same time of the day. The result
265 of the overall operation is a (network-ordered) 32-bit integer, e.g.
266 13753 or 0x000035B9 with the example values given above.
268 "descriptor-cookie" is an optional secret password of 128 bits that
269 is shared between the hidden service provider and its clients. If the
270 descriptor-cookie is left out, the input to the hash function is 128
273 "replica" denotes the number of the replica. A service publishes
274 multiple descriptors with different descriptor IDs in order to
275 distribute them to different places on the ring.
277 "version" version-number NL
281 The version number of this descriptor's format. In this case: 2.
283 "permanent-key" NL a public key in PEM format
287 The public key of the hidden service which is required to verify the
288 "descriptor-id" and the "signature".
290 "secret-id-part" secret-id-part NL
294 The result of the following operation as explained above, formatted as
295 32 base32 chars. Using this secret id part, everyone can verify that
296 the signed descriptor belongs to "descriptor-id".
298 secret-id-part = H(time-period | descriptor-cookie | replica)
300 "publication-time" YYYY-MM-DD HH:MM:SS NL
304 A timestamp when this descriptor has been created.
306 "protocol-versions" version-string NL
310 A comma-separated list of recognized and permitted version numbers
311 for use in INTRODUCE cells; these versions are described in section
314 "introduction-points" NL encrypted-string
318 A list of introduction points. If the optional "descriptor-cookie" is
319 used, this list is encrypted with AES in CTR mode with a random
320 initialization vector of 128 bits that is written to
321 the beginning of the encrypted string, and the "descriptor-cookie" as
322 secret key of 128 bits length.
324 The string containing the introduction point data (either encrypted
325 or not) is encoded in base64, and surrounded with
326 "-----BEGIN MESSAGE-----" and "-----END MESSAGE-----".
328 The unencrypted string may begin with:
330 "service-authentication" auth-type auth-data NL
334 The service-specific authentication data can be used to perform
335 client authentication. This data is independent of the selected
336 introduction point as opposed to "intro-authentication" below. The
337 format of auth-data (base64-encoded or PEM format) depends on
338 auth-type. See section 2 of this document for details on auth
341 Subsequently, an arbitrary number of introduction point entries may
342 follow, each containing the following data:
344 "introduction-point" identifier NL
346 [At start, exactly once]
348 The identifier of this introduction point: the base-32 encoded
349 hash of this introduction point's identity key.
351 "ip-address" ip-address NL
355 The IP address of this introduction point.
361 The TCP port on which the introduction point is listening for
362 incoming onion requests.
364 "onion-key" NL a public key in PEM format
368 The public key that can be used to encrypt messages to this
371 "service-key" NL a public key in PEM format
375 The public key that can be used to encrypt messages to the hidden
378 "intro-authentication" auth-type auth-data NL
382 The introduction-point-specific authentication data can be used
383 to perform client authentication. This data depends on the
384 selected introduction point as opposed to "service-authentication"
385 above. The format of auth-data (base64-encoded or PEM format)
386 depends on auth-type. See section 2 of this document for details
389 (This ends the fields in the encrypted portion of the descriptor.)
391 [It's ok for Bob to advertise 0 introduction points. He might want
392 to do that if he previously advertised some introduction points,
393 and now he doesn't have any. -RD]
395 "signature" NL signature-string
397 [At end, exactly once]
399 A signature of all fields above with the private key of the hidden
402 1.3.1. Other descriptor formats we don't use.
404 Support for the V0 descriptor format was dropped in 0.2.2.0-alpha-dev:
406 KL Key length [2 octets]
407 PK Bob's public key [KL octets]
408 TS A timestamp [4 octets]
409 NI Number of introduction points [2 octets]
410 Ipt A list of NUL-terminated ORs [variable]
411 SIG Signature of above fields [variable]
413 KL is the length of PK, in octets.
414 TS is the number of seconds elapsed since Jan 1, 1970.
416 The members of Ipt may be either (a) nicknames, or (b) identity key
417 digests, encoded in hex, and prefixed with a '$'.
419 The V1 descriptor format was understood and accepted from
420 0.1.1.5-alpha-cvs to 0.2.0.6-alpha-dev, but no Tors generated it and
423 V Format byte: set to 255 [1 octet]
424 V Version byte: set to 1 [1 octet]
425 KL Key length [2 octets]
426 PK Bob's public key [KL octets]
427 TS A timestamp [4 octets]
428 PROTO Protocol versions: bitmask [2 octets]
429 NI Number of introduction points [2 octets]
430 For each introduction point: (as in INTRODUCE2 cells)
431 IP Introduction point's address [4 octets]
432 PORT Introduction point's OR port [2 octets]
433 ID Introduction point identity ID [20 octets]
434 KLEN Length of onion key [2 octets]
435 KEY Introduction point onion key [KLEN octets]
436 SIG Signature of above fields [variable]
438 A hypothetical "V1" descriptor, that has never been used but might
439 be useful for historical reasons, contains:
441 V Format byte: set to 255 [1 octet]
442 V Version byte: set to 1 [1 octet]
443 KL Key length [2 octets]
444 PK Bob's public key [KL octets]
445 TS A timestamp [4 octets]
446 PROTO Rendezvous protocol versions: bitmask [2 octets]
447 NA Number of auth mechanisms accepted [1 octet]
448 For each auth mechanism:
449 AUTHT The auth type that is supported [2 octets]
450 AUTHL Length of auth data [1 octet]
451 AUTHD Auth data [variable]
452 NI Number of introduction points [2 octets]
453 For each introduction point: (as in INTRODUCE2 cells)
454 ATYPE An address type (typically 4) [1 octet]
455 ADDR Introduction point's IP address [4 or 16 octets]
456 PORT Introduction point's OR port [2 octets]
457 AUTHT The auth type that is supported [2 octets]
458 AUTHL Length of auth data [1 octet]
459 AUTHD Auth data [variable]
460 ID Introduction point identity ID [20 octets]
461 KLEN Length of onion key [2 octets]
462 KEY Introduction point onion key [KLEN octets]
463 SIG Signature of above fields [variable]
465 AUTHT specifies which authentication/authorization mechanism is
466 required by the hidden service or the introduction point. AUTHD
467 is arbitrary data that can be associated with an auth approach.
468 Currently only AUTHT of [00 00] is supported, with an AUTHL of 0.
469 See section 2 of this document for details on auth mechanisms.
471 1.4. Bob's OP advertises his service descriptor(s).
473 Bob's OP advertises his service descriptor to a fixed set of v0 hidden
474 service directory servers and/or a changing subset of all v2 hidden service
477 For versions before 0.2.2.1-alpha, Bob's OP opens a stream to each v0
478 directory server's directory port via Tor. (He may re-use old circuits for
479 this.) Over this stream, Bob's OP makes an HTTP 'POST' request, to a URL
480 "/tor/rendezvous/publish" relative to the directory server's root,
481 containing as its body Bob's service descriptor.
483 Upon receiving a descriptor, the directory server checks the signature,
484 and discards the descriptor if the signature does not match the enclosed
485 public key. Next, the directory server checks the timestamp. If the
486 timestamp is more than 24 hours in the past or more than 1 hour in the
487 future, or the directory server already has a newer descriptor with the
488 same public key, the server discards the descriptor. Otherwise, the
489 server discards any older descriptors with the same public key and
490 version format, and associates the new descriptor with the public key.
491 The directory server remembers this descriptor for at least 24 hours
492 after its timestamp. At least every 18 hours, Bob's OP uploads a
495 If Bob's OP is configured to publish v2 descriptors, it does so to a
496 changing subset of all v2 hidden service directories instead of the
497 authoritative directory servers. Therefore, Bob's OP opens a stream via
498 Tor to each responsible hidden service directory. (He may re-use old
499 circuits for this.) Over this stream, Bob's OP makes an HTTP 'POST'
500 request to a URL "/tor/rendezvous2/publish" relative to the hidden service
501 directory's root, containing as its body Bob's service descriptor.
503 [XXX022 Reusing old circuits for HS dir posts is very bad. Do we really
506 At any time, there are 6 hidden service directories responsible for
507 keeping replicas of a descriptor; they consist of 2 sets of 3 hidden
508 service directories with consecutive onion IDs. Bob's OP learns about
509 the complete list of hidden service directories by filtering the
510 consensus status document received from the directory authorities. A
511 hidden service directory is deemed responsible for a descriptor ID if
512 it has the HSDir flag and its identity digest is one of the first three
513 identity digests of HSDir relays following the descriptor ID in a
514 circular list. A hidden service directory will only accept a descriptor
515 whose timestamp is no more than three days before or one day after the
516 current time according to the directory's clock.
518 Bob's OP publishes a new v2 descriptor once an hour or whenever its
519 content changes. V2 descriptors can be found by clients within a given
520 time period of 24 hours, after which they change their ID as described
521 under 1.3. If a published descriptor would be valid for less than 60
522 minutes (= 2 x 30 minutes to allow the server to be 30 minutes behind
523 and the client 30 minutes ahead), Bob's OP publishes the descriptor
524 under the ID of both, the current and the next publication period.
526 1.5. Alice receives a z.onion address.
528 When Alice receives a pointer to a location-hidden service, it is as a
529 hostname of the form "z.onion", where z is a base-32 encoding of a
530 10-octet hash of Bob's service's public key, computed as follows:
533 2. Let H' = the first 80 bits of H, considering each octet from
534 most significant bit to least significant bit.
535 3. Generate a 16-character encoding of H', using base32 as defined
538 (We only use 80 bits instead of the 160 bits from SHA1 because we
539 don't need to worry about arbitrary collisions, and because it will
540 make handling the url's more convenient.)
542 [Yes, numbers are allowed at the beginning. See RFC 1123. -NM]
544 1.6. Alice's OP retrieves a service descriptor.
546 Alice's OP fetches the service descriptor from the fixed set of v0 hidden
547 service directory servers and/or a changing subset of all v2 hidden service
550 For versions before 0.2.2.1-alpha, Alice's OP opens a stream to a directory
551 server via Tor, and makes an HTTP GET request for the document
552 '/tor/rendezvous/<z>', where '<z>' is replaced with the encoding of Bob's
553 public key as described above. (She may re-use old circuits for this.) The
554 directory replies with a 404 HTTP response if it does not recognize <z>,
555 and otherwise returns Bob's most recently uploaded service descriptor.
557 If Alice's OP receives a 404 response, it tries the other directory
558 servers, and only fails the lookup if none recognize the public key hash.
560 Upon receiving a service descriptor, Alice verifies with the same process
561 as the directory server uses, described above in section 1.4.
563 The directory server gives a 400 response if it cannot understand Alice's
566 Alice should cache the descriptor locally, but should not use
567 descriptors that are more than 24 hours older than their timestamp.
568 [Caching may make her partitionable, but she fetched it anonymously,
569 and we can't very well *not* cache it. -RD]
571 If Alice's OP is running 0.2.1.10-alpha or higher, it fetches v2 hidden
572 service descriptors. Versions before 0.2.2.1-alpha are fetching both v0 and
573 v2 descriptors in parallel. Similar to the description in section 1.4,
574 Alice's OP fetches a v2 descriptor from a randomly chosen hidden service
575 directory out of the changing subset of 6 nodes. If the request is
576 unsuccessful, Alice retries the other remaining responsible hidden service
577 directories in a random order. Alice relies on Bob to care about a potential
578 clock skew between the two by possibly storing two sets of descriptors (see
581 Alice's OP opens a stream via Tor to the chosen v2 hidden service
582 directory. (She may re-use old circuits for this.) Over this stream,
583 Alice's OP makes an HTTP 'GET' request for the document
584 "/tor/rendezvous2/<z>", where z is replaced with the encoding of the
585 descriptor ID. The directory replies with a 404 HTTP response if it does
586 not recognize <z>, and otherwise returns Bob's most recently uploaded
589 1.7. Alice's OP establishes a rendezvous point.
591 When Alice requests a connection to a given location-hidden service,
592 and Alice's OP does not have an established circuit to that service,
593 the OP builds a rendezvous circuit. It does this by establishing
594 a circuit to a randomly chosen OR, and sending a
595 RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell to that OR. The body of that cell
598 RC Rendezvous cookie [20 octets]
600 The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by
601 Alice's OP. Alice SHOULD choose a new rendezvous cookie for each new
604 Upon receiving a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell, the OR associates
605 the RC with the circuit that sent it. It replies to Alice with an empty
606 RELAY_COMMAND_RENDEZVOUS_ESTABLISHED cell to indicate success.
608 Alice's OP MUST NOT use the circuit which sent the cell for any purpose
609 other than rendezvous with the given location-hidden service.
611 1.8. Introduction: from Alice's OP to Introduction Point
613 Alice builds a separate circuit to one of Bob's chosen introduction
614 points, and sends it a RELAY_COMMAND_INTRODUCE1 cell containing:
617 PK_ID Identifier for Bob's PK [20 octets]
618 Encrypted to Bob's PK: (in the v0 intro protocol)
619 RP Rendezvous point's nickname [20 octets]
620 RC Rendezvous cookie [20 octets]
621 g^x Diffie-Hellman data, part 1 [128 octets]
622 OR (in the v1 intro protocol)
623 VER Version byte: set to 1. [1 octet]
624 RP Rendezvous point nick or ID [42 octets]
625 RC Rendezvous cookie [20 octets]
626 g^x Diffie-Hellman data, part 1 [128 octets]
627 OR (in the v2 intro protocol)
628 VER Version byte: set to 2. [1 octet]
629 IP Rendezvous point's address [4 octets]
630 PORT Rendezvous point's OR port [2 octets]
631 ID Rendezvous point identity ID [20 octets]
632 KLEN Length of onion key [2 octets]
633 KEY Rendezvous point onion key [KLEN octets]
634 RC Rendezvous cookie [20 octets]
635 g^x Diffie-Hellman data, part 1 [128 octets]
636 OR (in the v3 intro protocol)
637 VER Version byte: set to 3. [1 octet]
638 AUTHT The auth type that is used [1 octet]
640 AUTHL Length of auth data [2 octets]
641 AUTHD Auth data [variable]
642 TS A timestamp [4 octets]
643 IP Rendezvous point's address [4 octets]
644 PORT Rendezvous point's OR port [2 octets]
645 ID Rendezvous point identity ID [20 octets]
646 KLEN Length of onion key [2 octets]
647 KEY Rendezvous point onion key [KLEN octets]
648 RC Rendezvous cookie [20 octets]
649 g^x Diffie-Hellman data, part 1 [128 octets]
651 PK_ID is the hash of Bob's public key or the service key, depending on the
652 hidden service descriptor version. In case of a v0 descriptor, Alice's OP
653 uses Bob's public key. If Alice has downloaded a v2 descriptor, she uses
654 the contained public key ("service-key").
656 RP is NUL-padded and terminated. In version 0 of the intro protocol, RP
657 must contain a nickname. In version 1, it must contain EITHER a nickname or
658 an identity key digest that is encoded in hex and prefixed with a '$'.
660 The hybrid encryption to Bob's PK works just like the hybrid
661 encryption in CREATE cells (see tor-spec). Thus the payload of the
662 version 0 RELAY_COMMAND_INTRODUCE1 cell on the wire will contain
663 20+42+16+20+20+128=246 bytes, and the version 1 and version 2
664 introduction formats have other sizes.
666 Through Tor 0.2.0.6-alpha, clients only generated the v0 introduction
667 format, whereas hidden services have understood and accepted v0,
668 v1, and v2 since 0.1.1.x. As of Tor 0.2.0.7-alpha and 0.1.2.18,
669 clients switched to using the v2 intro format.
671 1.9. Introduction: From the Introduction Point to Bob's OP
673 If the Introduction Point recognizes PK_ID as a public key which has
674 established a circuit for introductions as in 1.2 above, it sends the body
675 of the cell in a new RELAY_COMMAND_INTRODUCE2 cell down the corresponding
676 circuit. (If the PK_ID is unrecognized, the RELAY_COMMAND_INTRODUCE1 cell is
679 After sending the RELAY_COMMAND_INTRODUCE2 cell to Bob, the OR replies to
680 Alice with an empty RELAY_COMMAND_INTRODUCE_ACK cell. If no
681 RELAY_COMMAND_INTRODUCE2 cell can be sent, the OR replies to Alice with a
682 non-empty cell to indicate an error. (The semantics of the cell body may be
683 determined later; the current implementation sends a single '1' byte on
686 When Bob's OP receives the RELAY_COMMAND_INTRODUCE2 cell, it decrypts it
687 with the private key for the corresponding hidden service, and extracts the
688 rendezvous point's nickname, the rendezvous cookie, and the value of g^x
693 Bob's OP builds a new Tor circuit ending at Alice's chosen rendezvous
694 point, and sends a RELAY_COMMAND_RENDEZVOUS1 cell along this circuit,
696 RC Rendezvous cookie [20 octets]
697 g^y Diffie-Hellman [128 octets]
698 KH Handshake digest [20 octets]
700 (Bob's OP MUST NOT use this circuit for any other purpose.)
702 If the RP recognizes RC, it relays the rest of the cell down the
703 corresponding circuit in a RELAY_COMMAND_RENDEZVOUS2 cell, containing:
705 g^y Diffie-Hellman [128 octets]
706 KH Handshake digest [20 octets]
708 (If the RP does not recognize the RC, it discards the cell and
709 tears down the circuit.)
711 When Alice's OP receives a RELAY_COMMAND_RENDEZVOUS2 cell on a circuit which
712 has sent a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell but which has not yet
713 received a reply, it uses g^y and H(g^xy) to complete the handshake as in
714 the Tor circuit extend process: they establish a 60-octet string as
715 K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02])
721 Subsequently, the rendezvous point passes relay cells, unchanged, from
722 each of the two circuits to the other. When Alice's OP sends
723 RELAY cells along the circuit, it first encrypts them with the
724 Kf, then with all of the keys for the ORs in Alice's side of the circuit;
725 and when Alice's OP receives RELAY cells from the circuit, it decrypts
726 them with the keys for the ORs in Alice's side of the circuit, then
727 decrypts them with Kb. Bob's OP does the same, with Kf and Kb
730 1.11. Creating streams
732 To open TCP connections to Bob's location-hidden service, Alice's OP sends
733 a RELAY_COMMAND_BEGIN cell along the established circuit, using the special
734 address "", and a chosen port. Bob's OP chooses a destination IP and
735 port, based on the configuration of the service connected to the circuit,
736 and opens a TCP stream. From then on, Bob's OP treats the stream as an
737 ordinary exit connection.
738 [ Except he doesn't include addr in the connected cell or the end
741 Alice MAY send multiple RELAY_COMMAND_BEGIN cells along the circuit, to open
742 multiple streams to Bob. Alice SHOULD NOT send RELAY_COMMAND_BEGIN cells
743 for any other address along her circuit to Bob; if she does, Bob MUST reject
746 2. Authentication and authorization.
748 The rendezvous protocol as described in Section 1 provides a few options
749 for implementing client-side authorization. There are two steps in the
750 rendezvous protocol that can be used for performing client authorization:
751 when downloading and decrypting parts of the hidden service descriptor and
752 at Bob's Tor client before contacting the rendezvous point. A service
753 provider can restrict access to his service at these two points to
754 authorized clients only.
756 There are currently two authorization protocols specified that are
757 described in more detail below:
759 1. The first protocol allows a service provider to restrict access
760 to clients with a previously received secret key only, but does not
761 attempt to hide service activity from others.
763 2. The second protocol, albeit being feasible for a limited set of about
764 16 clients, performs client authorization and hides service activity
765 from everyone but the authorized clients.
767 2.1. Service with large-scale client authorization
769 The first client authorization protocol aims at performing access control
770 while consuming as few additional resources as possible. This is the "basic"
771 authorization protocol. A service provider should be able to permit access
772 to a large number of clients while denying access for everyone else.
773 However, the price for scalability is that the service won't be able to hide
774 its activity from unauthorized or formerly authorized clients.
776 The main idea of this protocol is to encrypt the introduction-point part
777 in hidden service descriptors to authorized clients using symmetric keys.
778 This ensures that nobody else but authorized clients can learn which
779 introduction points a service currently uses, nor can someone send a
780 valid INTRODUCE1 message without knowing the introduction key. Therefore,
781 a subsequent authorization at the introduction point is not required.
783 A service provider generates symmetric "descriptor cookies" for his
784 clients and distributes them outside of Tor. The suggested key size is
785 128 bits, so that descriptor cookies can be encoded in 22 base64 chars
786 (which can hold up to 22 * 5 = 132 bits, leaving 4 bits to encode the
787 authorization type (here: "0") and allow a client to distinguish this
788 authorization protocol from others like the one proposed below).
789 Typically, the contact information for a hidden service using this
790 authorization protocol looks like this:
792 v2cbb2l4lsnpio4q.onion Ll3X7Xgz9eHGKCCnlFH0uz
794 When generating a hidden service descriptor, the service encrypts the
795 introduction-point part with a single randomly generated symmetric
796 128-bit session key using AES-CTR as described for v2 hidden service
797 descriptors in rend-spec. Afterwards, the service encrypts the session
798 key to all descriptor cookies using AES. Authorized client should be able
799 to efficiently find the session key that is encrypted for him/her, so
800 that 4 octet long client ID are generated consisting of descriptor cookie
801 and initialization vector. Descriptors always contain a number of
802 encrypted session keys that is a multiple of 16 by adding fake entries.
803 Encrypted session keys are ordered by client IDs in order to conceal
804 addition or removal of authorized clients by the service provider.
806 ATYPE Authorization type: set to 1. [1 octet]
807 ALEN Number of clients := 1 + ((clients - 1) div 16) [1 octet]
808 for each symmetric descriptor cookie:
809 ID Client ID: H(descriptor cookie | IV)[:4] [4 octets]
810 SKEY Session key encrypted with descriptor cookie [16 octets]
811 (end of client-specific part)
812 RND Random data [(15 - ((clients - 1) mod 16)) * 20 octets]
813 IV AES initialization vector [16 octets]
814 IPOS Intro points, encrypted with session key [remaining octets]
816 An authorized client needs to configure Tor to use the descriptor cookie
817 when accessing the hidden service. Therefore, a user adds the contact
818 information that she received from the service provider to her torrc
819 file. Upon downloading a hidden service descriptor, Tor finds the
820 encrypted introduction-point part and attempts to decrypt it using the
821 configured descriptor cookie. (In the rare event of two or more client
822 IDs being equal a client tries to decrypt all of them.)
824 Upon sending the introduction, the client includes her descriptor cookie
825 as auth type "1" in the INTRODUCE2 cell that she sends to the service.
826 The hidden service checks whether the included descriptor cookie is
827 authorized to access the service and either responds to the introduction
830 2.2. Authorization for limited number of clients
832 A second, more sophisticated client authorization protocol goes the extra
833 mile of hiding service activity from unauthorized clients. This is the
834 "stealth" authorization protocol. With all else being equal to the preceding
835 authorization protocol, the second protocol publishes hidden service
836 descriptors for each user separately and gets along with encrypting the
837 introduction-point part of descriptors to a single client. This allows the
838 service to stop publishing descriptors for removed clients. As long as a
839 removed client cannot link descriptors issued for other clients to the
840 service, it cannot derive service activity any more. The downside of this
841 approach is limited scalability. Even though the distributed storage of
842 descriptors (cf. proposal 114) tackles the problem of limited scalability to
843 a certain extent, this protocol should not be used for services with more
844 than 16 clients. (In fact, Tor should refuse to advertise services for more
845 than this number of clients.)
847 A hidden service generates an asymmetric "client key" and a symmetric
848 "descriptor cookie" for each client. The client key is used as
849 replacement for the service's permanent key, so that the service uses a
850 different identity for each of his clients. The descriptor cookie is used
851 to store descriptors at changing directory nodes that are unpredictable
852 for anyone but service and client, to encrypt the introduction-point
853 part, and to be included in INTRODUCE2 cells. Once the service has
854 created client key and descriptor cookie, he tells them to the client
855 outside of Tor. The contact information string looks similar to the one
856 used by the preceding authorization protocol (with the only difference
857 that it has "1" encoded as auth-type in the remaining 4 of 132 bits
858 instead of "0" as before).
860 When creating a hidden service descriptor for an authorized client, the
861 hidden service uses the client key and descriptor cookie to compute
862 secret ID part and descriptor ID:
864 secret-id-part = H(time-period | descriptor-cookie | replica)
866 descriptor-id = H(client-key[:10] | secret-id-part)
868 The hidden service also replaces permanent-key in the descriptor with
869 client-key and encrypts introduction-points with the descriptor cookie.
871 ATYPE Authorization type: set to 2. [1 octet]
872 IV AES initialization vector [16 octets]
873 IPOS Intro points, encr. with descriptor cookie [remaining octets]
875 When uploading descriptors, the hidden service needs to make sure that
876 descriptors for different clients are not uploaded at the same time (cf.
877 Section 1.1) which is also a limiting factor for the number of clients.
879 When a client is requested to establish a connection to a hidden service
880 it looks up whether it has any authorization data configured for that
881 service. If the user has configured authorization data for authorization
882 protocol "2", the descriptor ID is determined as described in the last
883 paragraph. Upon receiving a descriptor, the client decrypts the
884 introduction-point part using its descriptor cookie. Further, the client
885 includes its descriptor cookie as auth-type "2" in INTRODUCE2 cells that
886 it sends to the service.
888 2.3. Hidden service configuration
890 A hidden service that is meant to perform client authorization adds a
891 new option HiddenServiceAuthorizeClient to its hidden service
892 configuration. This option contains the authorization type which is
893 either "basic" for the protocol described in 2.1 or "stealth" for the
894 protocol in 2.2 and a comma-separated list of human-readable client
895 names, so that Tor can create authorization data for these clients:
897 HiddenServiceAuthorizeClient auth-type client-name,client-name,...
899 If this option is configured, HiddenServiceVersion is automatically
900 reconfigured to contain only version numbers of 2 or higher. There is
901 a maximum of 512 client names for basic auth and a maximum of 16 for
904 Tor stores all generated authorization data for the authorization
905 protocols described in Sections 2.1 and 2.2 in a new file using the
906 following file format:
908 "client-name" human-readable client identifier NL
909 "descriptor-cookie" 128-bit key ^= 22 base64 chars NL
911 If the authorization protocol of Section 2.2 is used, Tor also generates
912 and stores the following data:
914 "client-key" NL a public key in PEM format
916 2.4. Client configuration
918 Clients need to make their authorization data known to Tor using another
919 configuration option that contains a service name (mainly for the sake of
920 convenience), the service address, and the descriptor cookie that is
921 required to access a hidden service (the authorization protocol number is
922 encoded in the descriptor cookie):
924 HidServAuth service-name service-address descriptor-cookie
926 3. Hidden service directory operation
928 This section has been introduced with the v2 hidden service descriptor
929 format. It describes all operations of the v2 hidden service descriptor
930 fetching and propagation mechanism that are required for the protocol
931 described in section 1 to succeed with v2 hidden service descriptors.
933 3.1. Configuring as hidden service directory
935 Every onion router that has its directory port open can decide whether it
936 wants to store and serve hidden service descriptors. An onion router which
937 is configured as such includes the "hidden-service-dir" flag in its router
938 descriptors that it sends to directory authorities.
940 The directory authorities include a new flag "HSDir" for routers that
941 decided to provide storage for hidden service descriptors and that
942 have been running for at least 24 hours.
944 3.2. Accepting publish requests
946 Hidden service directory nodes accept publish requests for v2 hidden service
947 descriptors and store them to their local memory. (It is not necessary to
948 make descriptors persistent, because after restarting, the onion router
949 would not be accepted as a storing node anyway, because it has not been
950 running for at least 24 hours.) All requests and replies are formatted as
951 HTTP messages. Requests are initiated via BEGIN_DIR cells directed to
952 the router's directory port, and formatted as HTTP POST requests to the URL
953 "/tor/rendezvous2/publish" relative to the hidden service directory's root,
954 containing as its body a v2 service descriptor.
956 A hidden service directory node parses every received descriptor and only
957 stores it when it thinks that it is responsible for storing that descriptor
958 based on its own routing table. See section 1.4 for more information on how
959 to determine responsibility for a certain descriptor ID.
961 3.3. Processing fetch requests
963 Hidden service directory nodes process fetch requests for hidden service
964 descriptors by looking them up in their local memory. (They do not need to
965 determine if they are responsible for the passed ID, because it does no harm
966 if they deliver a descriptor for which they are not (any more) responsible.)
967 All requests and replies are formatted as HTTP messages. Requests are
968 initiated via BEGIN_DIR cells directed to the router's directory port,
969 and formatted as HTTP GET requests for the document "/tor/rendezvous2/<z>",
970 where z is replaced with the encoding of the descriptor ID.