rend-spec.txt 50 KB

  1. Tor Rendezvous Specification
  2. 0. Overview and preliminaries
  3. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  5. "OPTIONAL" in this document are to be interpreted as described in
  6. RFC 2119.
  7. Read
  9. 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.
  14. Bob does this by anonymously advertising a public key for his
  15. service, along with a list of onion routers to act as "Introduction
  16. Points" for his service. He creates forward circuits to those
  17. introduction points, and tells them about his service. To
  18. connect to Bob, Alice first builds a circuit to an OR to act as
  19. her "Rendezvous Point." She then connects to one of Bob's chosen
  20. introduction points, and asks it to tell him about her Rendezvous
  21. Point (RP). If Bob chooses to answer, he builds a circuit to her
  22. RP, and tells it to connect him to Alice. The RP joins their
  23. circuits together, and begins relaying cells. Alice's 'BEGIN'
  24. cells are received directly by Bob's OP, which passes data to
  25. and from the local server implementing Bob's service.
  26. Below we describe a network-level specification of this service,
  27. along with interfaces to make this process transparent to Alice
  28. (so long as she is using an OP).
  29. 0.1. Notation, conventions and prerequisites
  30. In the specifications below, we use the same notation and terminology
  31. as in "tor-spec.txt". The service specified here also requires the
  32. existence of an onion routing network as specified in that file.
  33. H(x) is a SHA1 digest of x.
  34. PKSign(SK,x) is a PKCS.1-padded RSA signature of x with SK.
  35. PKEncrypt(SK,x) is a PKCS.1-padded RSA encryption of x with SK.
  36. Public keys are all RSA, and encoded in ASN.1.
  37. All integers are stored in network (big-endian) order.
  38. All symmetric encryption uses AES in counter mode, except where
  39. otherwise noted.
  40. In all discussions, "Alice" will refer to a user connecting to a
  41. location-hidden service, and "Bob" will refer to a user running a
  42. location-hidden service.
  43. An OP is (as defined elsewhere) an "Onion Proxy" or Tor client.
  44. An OR is (as defined elsewhere) an "Onion Router" or Tor server.
  45. An "Introduction point" is a Tor server chosen to be Bob's medium-term
  46. 'meeting place'. A "Rendezvous point" is a Tor server chosen by Alice to
  47. be a short-term communication relay between her and Bob. All Tor servers
  48. potentially act as introduction and rendezvous points.
  49. 0.2. Protocol outline
  50. 1. Bob->Bob's OP: "Offer IP:Port as public-key-name:Port". [configuration]
  51. (We do not specify this step; it is left to the implementor of
  52. Bob's OP.)
  53. 2. Bob's OP generates a long-term keypair.
  54. 3. Bob's OP->Introduction point via Tor: [introduction setup]
  55. "This public key is (currently) associated to me."
  56. 4. Bob's OP->directory service via Tor: publishes Bob's service descriptor
  57. [advertisement]
  58. "Meet public-key X at introduction point A, B, or C." (signed)
  59. 5. Out of band, Alice receives a z.onion:port address.
  60. She opens a SOCKS connection to her OP, and requests z.onion:port.
  61. 6. Alice's OP retrieves Bob's descriptor via Tor. [descriptor lookup.]
  62. 7. Alice's OP chooses a rendezvous point, opens a circuit to that
  63. rendezvous point, and establishes a rendezvous circuit. [rendezvous
  64. setup.]
  65. 8. Alice connects to the Introduction point via Tor, and tells it about
  66. her rendezvous point. (Encrypted to Bob.) [Introduction 1]
  67. 9. The Introduction point passes this on to Bob's OP via Tor, along the
  68. introduction circuit. [Introduction 2]
  69. 10. Bob's OP decides whether to connect to Alice, and if so, creates a
  70. circuit to Alice's RP via Tor. Establishes a shared circuit.
  71. [Rendezvous 1]
  72. 11. The Rendezvous point forwards Bob's confirmation to Alice's OP.
  73. [Rendezvous 2]
  74. 12. Alice's OP sends begin cells to Bob's OP. [Connection]
  75. 0.3. Constants and new cell types
  76. Relay cell types
  86. 0.4. Version overview
  87. There are several parts in the hidden service protocol that have
  88. changed over time, each of them having its own version number, whereas
  89. other parts remained the same. The following list of potentially
  90. versioned protocol parts should help reduce some confusion:
  91. - Hidden service descriptor: the binary-based v0 was the default for a
  92. long time, and an ASCII-based v2 has been added by proposal 114. The
  93. v0 descriptor format has been deprecated in See 1.3.
  94. - Hidden service descriptor propagation mechanism: currently related to
  95. the hidden service descriptor version -- v0 publishes to the original
  96. hs directory authorities, whereas v2 publishes to a rotating subset
  97. of relays with the "HSDir" flag; see 1.4 and 1.6.
  98. - Introduction protocol for how to generate an introduction cell:
  99. v0 specified a nickname for the rendezvous point and assumed the
  100. relay would know about it, whereas v2 now specifies IP address,
  101. port, and onion key so the relay doesn't need to already recognize
  102. it. See 1.8.
  103. 1. The Protocol
  104. 1.1. Bob configures his local OP.
  105. We do not specify a format for the OP configuration file. However,
  106. OPs SHOULD allow Bob to provide more than one advertised service
  107. per OP, and MUST allow Bob to specify one or more virtual ports per
  108. service. Bob provides a mapping from each of these virtual ports
  109. to a local IP:Port pair.
  110. 1.2. Bob's OP establishes his introduction points.
  111. The first time the OP provides an advertised service, it generates
  112. a public/private keypair (stored locally).
  113. The OP chooses a small number of Tor servers as introduction points.
  114. The OP establishes a new introduction circuit to each introduction
  115. point. These circuits MUST NOT be used for anything but hidden service
  116. introduction. To establish the introduction, Bob sends a
  117. RELAY_COMMAND_ESTABLISH_INTRO cell, containing:
  118. KL Key length [2 octets]
  119. PK Bob's public key or service key [KL octets]
  120. HS Hash of session info [20 octets]
  121. SIG Signature of above information [variable]
  122. KL is the length of PK, in octets.
  123. To prevent replay attacks, the HS field contains a SHA-1 hash based on the
  124. shared secret KH between Bob's OP and the introduction point, as
  125. follows:
  126. HS = H(KH | "INTRODUCE")
  127. That is:
  128. HS = H(KH | [49 4E 54 52 4F 44 55 43 45])
  129. (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)
  130. Upon receiving such a cell, the OR first checks that the signature is
  131. correct with the included public key. If so, it checks whether HS is
  132. correct given the shared state between Bob's OP and the OR. If either
  133. check fails, the OP discards the cell; otherwise, it associates the
  134. circuit with Bob's public key, and dissociates any other circuits
  135. currently associated with PK. On success, the OR sends Bob a
  136. RELAY_COMMAND_INTRO_ESTABLISHED cell with an empty payload.
  137. Bob's OP uses either Bob's public key or a freshly generated, single-use
  138. service key in the RELAY_COMMAND_ESTABLISH_INTRO cell, depending on the
  139. configured hidden service descriptor version. The public key is used for
  140. v0 descriptors, the service key for v2 descriptors. In the latter case, the
  141. service keys of all introduction points are included in the v2 hidden
  142. service descriptor together with the other introduction point information.
  143. The reason is that the introduction point does not need to and therefore
  144. should not know for which hidden service it works, so as to prevent it from
  145. tracking the hidden service's activity. If the hidden service is configured
  146. to publish both v0 and v2 descriptors, two separate sets of introduction
  147. points are established.
  148. 1.3. Bob's OP generates service descriptors.
  149. For versions before, Bob's OP periodically generates and
  150. publishes a descriptor of type "V0".
  151. The "V0" descriptor contains:
  152. KL Key length [2 octets]
  153. PK Bob's public key [KL octets]
  154. TS A timestamp [4 octets]
  155. NI Number of introduction points [2 octets]
  156. Ipt A list of NUL-terminated ORs [variable]
  157. SIG Signature of above fields [variable]
  158. TS is the number of seconds elapsed since Jan 1, 1970.
  159. The members of Ipt may be either (a) nicknames, or (b) identity key
  160. digests, encoded in hex, and prefixed with a '$'. Clients must
  161. accept both forms. Services must only generate the second form.
  162. Once 0.0.9.x is obsoleted, we can drop the first form.
  163. [It's ok for Bob to advertise 0 introduction points. He might want
  164. to do that if he previously advertised some introduction points,
  165. and now he doesn't have any. -RD]
  166. Beginning with, Bob's OP encodes "V2" descriptors in
  167. addition to (or instead of) "V0" descriptors. The format of a "V2"
  168. descriptor is as follows:
  169. "rendezvous-service-descriptor" SP descriptor-id NL
  170. [At start, exactly once]
  171. [No extra arguments]
  172. Indicates the beginning of the descriptor. "descriptor-id" is a
  173. periodically changing identifier of 160 bits formatted as 32 base32
  174. chars that is calculated by the hidden service and its clients. The
  175. "descriptor-id" is calculated by performing the following operation:
  176. descriptor-id =
  177. H(permanent-id | H(time-period | descriptor-cookie | replica))
  178. "permanent-id" is the permanent identifier of the hidden service,
  179. consisting of 80 bits. It can be calculated by computing the hash value
  180. of the public hidden service key and truncating after the first 80 bits:
  181. permanent-id = H(public-key)[:10]
  182. Note: If Bob's OP has "stealth" authorization enabled (see Section 2.2),
  183. it uses the client key in place of the public hidden service key.
  184. "H(time-period | descriptor-cookie | replica)" is the (possibly
  185. secret) id part that is necessary to verify that the hidden service is
  186. the true originator of this descriptor and that is therefore contained
  187. in the descriptor, too. The descriptor ID can only be created by the
  188. hidden service and its clients, but the "signature" below can only be
  189. created by the service.
  190. "time-period" changes periodically as a function of time and
  191. "permanent-id". The current value for "time-period" can be calculated
  192. using the following formula:
  193. time-period = (current-time + permanent-id-byte * 86400 / 256)
  194. / 86400
  195. "current-time" contains the current system time in seconds since
  196. 1970-01-01 00:00, e.g. 1188241957. "permanent-id-byte" is the first
  197. (unsigned) byte of the permanent identifier (which is in network
  198. order), e.g. 143. Adding the product of "permanent-id-byte" and
  199. 86400 (seconds per day), divided by 256, prevents "time-period" from
  200. changing for all descriptors at the same time of the day. The result
  201. of the overall operation is a (network-ordered) 32-bit integer, e.g.
  202. 13753 or 0x000035B9 with the example values given above.
  203. "descriptor-cookie" is an optional secret password of 128 bits that
  204. is shared between the hidden service provider and its clients. If the
  205. descriptor-cookie is left out, the input to the hash function is 128
  206. bits shorter. [No extra arguments]
  207. "replica" denotes the number of the replica. A service publishes
  208. multiple descriptors with different descriptor IDs in order to
  209. distribute them to different places on the ring.
  210. "version" SP version-number NL
  211. [Exactly once]
  212. [No extra arguments]
  213. The version number of this descriptor's format. Version numbers are a
  214. positive integer.
  215. "permanent-key" NL a public key in PEM format
  216. [Exactly once]
  217. [No extra arguments]
  218. The public key of the hidden service which is required to verify the
  219. "descriptor-id" and the "signature".
  220. "secret-id-part" SP secret-id-part NL
  221. [Exactly once]
  222. [No extra arguments]
  223. The result of the following operation as explained above, formatted as
  224. 32 base32 chars. Using this secret id part, everyone can verify that
  225. the signed descriptor belongs to "descriptor-id".
  226. secret-id-part = H(time-period | descriptor-cookie | replica)
  227. "publication-time" SP YYYY-MM-DD HH:MM:SS NL
  228. [Exactly once]
  229. A timestamp when this descriptor has been created. It should be
  230. rounded down to the nearest hour.
  231. "protocol-versions" SP version-string NL
  232. [Exactly once]
  233. [No extra arguments]
  234. A comma-separated list of recognized and permitted version numbers
  235. for use in INTRODUCE cells; these versions are described in section
  236. 1.8 below. Version numbers are positive integers.
  237. "introduction-points" NL encrypted-string
  238. [At most once]
  239. [No extra arguments]
  240. A list of introduction points. If the optional "descriptor-cookie" is
  241. used, this list is encrypted with AES in CTR mode with a random
  242. initialization vector of 128 bits that is written to
  243. the beginning of the encrypted string, and the "descriptor-cookie" as
  244. secret key of 128 bits length.
  245. The string containing the introduction point data (either encrypted
  246. or not) is encoded in base64, and surrounded with
  247. "-----BEGIN MESSAGE-----" and "-----END MESSAGE-----".
  248. A maximum of 10 introduction point entries may follow, each containing
  249. the following data:
  250. "introduction-point" SP identifier NL
  251. [At start, exactly once]
  252. [No extra arguments]
  253. The identifier of this introduction point: the base32 encoded
  254. hash of this introduction point's identity key.
  255. "ip-address" SP ip4 NL
  256. [Exactly once]
  257. [No extra arguments]
  258. The IP address of this introduction point.
  259. "onion-port" SP port NL
  260. [Exactly once]
  261. [No extra arguments]
  262. The TCP port on which the introduction point is listening for
  263. incoming onion requests.
  264. "onion-key" NL a public key in PEM format
  265. [Exactly once]
  266. [No extra arguments]
  267. The public key that can be used to encrypt messages to this
  268. introduction point.
  269. "service-key" NL a public key in PEM format
  270. [Exactly once]
  271. [No extra arguments]
  272. The public key that can be used to encrypt messages to the hidden
  273. service.
  274. "intro-authentication" auth-type auth-data NL
  275. [Any number]
  276. The introduction-point-specific authentication data can be used
  277. to perform client authentication. This data depends on the
  278. selected introduction point as opposed to "service-authentication"
  279. above. The format of auth-data (base64-encoded or PEM format)
  280. depends on auth-type. See section 2 of this document for details
  281. on auth mechanisms.
  282. (This ends the fields in the encrypted portion of the descriptor.)
  283. [It's ok for Bob to advertise 0 introduction points. He might want
  284. to do that if he previously advertised some introduction points,
  285. and now he doesn't have any. -RD]
  286. "signature" NL signature-string
  287. [At end, exactly once]
  288. [No extra arguments]
  289. A signature of all fields above including '"signature" NL' with
  290. the private key of the hidden service.
  291. 1.3.1. Other descriptor formats we don't use.
  292. Support for the V0 descriptor format was dropped in
  293. KL Key length [2 octets]
  294. PK Bob's public key [KL octets]
  295. TS A timestamp [4 octets]
  296. NI Number of introduction points [2 octets]
  297. Ipt A list of NUL-terminated ORs [variable]
  298. SIG Signature of above fields [variable]
  299. KL is the length of PK, in octets.
  300. TS is the number of seconds elapsed since Jan 1, 1970.
  301. The members of Ipt may be either (a) nicknames, or (b) identity key
  302. digests, encoded in hex, and prefixed with a '$'.
  303. The V1 descriptor format was understood and accepted from
  304. to, but no Tors generated it and
  305. it was removed:
  306. V Format byte: set to 255 [1 octet]
  307. V Version byte: set to 1 [1 octet]
  308. KL Key length [2 octets]
  309. PK Bob's public key [KL octets]
  310. TS A timestamp [4 octets]
  311. PROTO Protocol versions: bitmask [2 octets]
  312. NI Number of introduction points [2 octets]
  313. For each introduction point: (as in INTRODUCE2 cells)
  314. IP Introduction point's address [4 octets]
  315. PORT Introduction point's OR port [2 octets]
  316. ID Introduction point identity ID [20 octets]
  317. KLEN Length of onion key [2 octets]
  318. KEY Introduction point onion key [KLEN octets]
  319. SIG Signature of above fields [variable]
  320. A hypothetical "V1" descriptor, that has never been used but might
  321. be useful for historical reasons, contains:
  322. V Format byte: set to 255 [1 octet]
  323. V Version byte: set to 1 [1 octet]
  324. KL Key length [2 octets]
  325. PK Bob's public key [KL octets]
  326. TS A timestamp [4 octets]
  327. PROTO Rendezvous protocol versions: bitmask [2 octets]
  328. NA Number of auth mechanisms accepted [1 octet]
  329. For each auth mechanism:
  330. AUTHT The auth type that is supported [2 octets]
  331. AUTHL Length of auth data [1 octet]
  332. AUTHD Auth data [variable]
  333. NI Number of introduction points [2 octets]
  334. For each introduction point: (as in INTRODUCE2 cells)
  335. ATYPE An address type (typically 4) [1 octet]
  336. ADDR Introduction point's IP address [4 or 16 octets]
  337. PORT Introduction point's OR port [2 octets]
  338. AUTHT The auth type that is supported [2 octets]
  339. AUTHL Length of auth data [1 octet]
  340. AUTHD Auth data [variable]
  341. ID Introduction point identity ID [20 octets]
  342. KLEN Length of onion key [2 octets]
  343. KEY Introduction point onion key [KLEN octets]
  344. SIG Signature of above fields [variable]
  345. AUTHT specifies which authentication/authorization mechanism is
  346. required by the hidden service or the introduction point. AUTHD
  347. is arbitrary data that can be associated with an auth approach.
  348. Currently only AUTHT of [00 00] is supported, with an AUTHL of 0.
  349. See section 2 of this document for details on auth mechanisms.
  350. 1.4. Bob's OP advertises his service descriptor(s).
  351. Bob's OP advertises his service descriptor to a fixed set of v0 hidden
  352. service directory servers and/or a changing subset of all v2 hidden service
  353. directories.
  354. For versions before, Bob's OP opens a stream to each v0
  355. directory server's directory port via Tor. (He may re-use old circuits for
  356. this.) Over this stream, Bob's OP makes an HTTP 'POST' request, to a URL
  357. "/tor/rendezvous/publish" relative to the directory server's root,
  358. containing as its body Bob's service descriptor.
  359. Upon receiving a descriptor, the directory server checks the signature,
  360. and discards the descriptor if the signature does not match the enclosed
  361. public key. Next, the directory server checks the timestamp. If the
  362. timestamp is more than 24 hours in the past or more than 1 hour in the
  363. future, or the directory server already has a newer descriptor with the
  364. same public key, the server discards the descriptor. Otherwise, the
  365. server discards any older descriptors with the same public key and
  366. version format, and associates the new descriptor with the public key.
  367. The directory server remembers this descriptor for at least 24 hours
  368. after its timestamp. At least every 18 hours, Bob's OP uploads a
  369. fresh descriptor.
  370. If Bob's OP is configured to publish v2 descriptors, it does so to a
  371. changing subset of all v2 hidden service directories instead of the
  372. authoritative directory servers. Therefore, Bob's OP opens a stream via
  373. Tor to each responsible hidden service directory. (He may re-use old
  374. circuits for this.) Over this stream, Bob's OP makes an HTTP 'POST'
  375. request to a URL "/tor/rendezvous2/publish" relative to the hidden service
  376. directory's root, containing as its body Bob's service descriptor.
  377. [XXX022 Reusing old circuits for HS dir posts is very bad. Do we really
  378. do that? --RR]
  379. At any time, there are 6 hidden service directories responsible for
  380. keeping replicas of a descriptor; they consist of 2 sets of 3 hidden
  381. service directories with consecutive onion IDs. Bob's OP learns about
  382. the complete list of hidden service directories by filtering the
  383. consensus status document received from the directory authorities. A
  384. hidden service directory is deemed responsible for a descriptor ID if
  385. it has the HSDir flag and its identity digest is one of the first three
  386. identity digests of HSDir relays following the descriptor ID in a
  387. circular list. A hidden service directory will only accept a descriptor
  388. whose timestamp is no more than three days before or one day after the
  389. current time according to the directory's clock.
  390. Bob's OP publishes a new v2 descriptor once an hour or whenever its
  391. content changes. V2 descriptors can be found by clients within a given
  392. time period of 24 hours, after which they change their ID as described
  393. under 1.3. If a published descriptor would be valid for less than 60
  394. minutes (= 2 x 30 minutes to allow the server to be 30 minutes behind
  395. and the client 30 minutes ahead), Bob's OP publishes the descriptor
  396. under the ID of both, the current and the next publication period.
  397. 1.5. Alice receives a z.onion address.
  398. When Alice receives a pointer to a location-hidden service, it is as a
  399. hostname of the form "z.onion", where z is a base32 encoding of a
  400. 10-octet hash of Bob's service's public key, computed as follows:
  401. 1. Let H = H(PK).
  402. 2. Let H' = the first 80 bits of H, considering each octet from
  403. most significant bit to least significant bit.
  404. 3. Generate a 16-character encoding of H', using base32 as defined
  405. in RFC 4648.
  406. (We only use 80 bits instead of the 160 bits from SHA1 because we
  407. don't need to worry about arbitrary collisions, and because it will
  408. make handling the url's more convenient.)
  409. [Yes, numbers are allowed at the beginning. See RFC 1123. -NM]
  410. 1.6. Alice's OP retrieves a service descriptor.
  411. Alice's OP fetches the service descriptor from the fixed set of v0 hidden
  412. service directory servers and/or a changing subset of all v2 hidden service
  413. directories.
  414. For versions before, Alice's OP opens a stream to a directory
  415. server via Tor, and makes an HTTP GET request for the document
  416. '/tor/rendezvous/<z>', where '<z>' is replaced with the encoding of Bob's
  417. public key as described above. (She may re-use old circuits for this.) The
  418. directory replies with a 404 HTTP response if it does not recognize <z>,
  419. and otherwise returns Bob's most recently uploaded service descriptor.
  420. If Alice's OP receives a 404 response, it tries the other directory
  421. servers, and only fails the lookup if none recognize the public key hash.
  422. Upon receiving a service descriptor, Alice verifies with the same process
  423. as the directory server uses, described above in section 1.4.
  424. The directory server gives a 400 response if it cannot understand Alice's
  425. request.
  426. Alice should cache the descriptor locally, but should not use
  427. descriptors that are more than 24 hours older than their timestamp.
  428. [Caching may make her partitionable, but she fetched it anonymously,
  429. and we can't very well *not* cache it. -RD]
  430. If Alice's OP is running or higher, it fetches v2 hidden
  431. service descriptors. Versions before are fetching both v0 and
  432. v2 descriptors in parallel. Similar to the description in section 1.4,
  433. Alice's OP fetches a v2 descriptor from a randomly chosen hidden service
  434. directory out of the changing subset of 6 nodes. If the request is
  435. unsuccessful, Alice retries the other remaining responsible hidden service
  436. directories in a random order. Alice relies on Bob to care about a potential
  437. clock skew between the two by possibly storing two sets of descriptors (see
  438. end of section 1.4).
  439. Alice's OP opens a stream via Tor to the chosen v2 hidden service
  440. directory. (She may re-use old circuits for this.) Over this stream,
  441. Alice's OP makes an HTTP 'GET' request for the document
  442. "/tor/rendezvous2/<z>", where z is replaced with the encoding of the
  443. descriptor ID. The directory replies with a 404 HTTP response if it does
  444. not recognize <z>, and otherwise returns Bob's most recently uploaded
  445. service descriptor.
  446. 1.7. Alice's OP establishes a rendezvous point.
  447. When Alice requests a connection to a given location-hidden service,
  448. and Alice's OP does not have an established circuit to that service,
  449. the OP builds a rendezvous circuit. It does this by establishing
  450. a circuit to a randomly chosen OR, and sending a
  451. RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell to that OR. The body of that cell
  452. contains:
  453. RC Rendezvous cookie [20 octets]
  454. The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by
  455. Alice's OP. Alice SHOULD choose a new rendezvous cookie for each new
  456. connection attempt.
  457. Upon receiving a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell, the OR associates
  458. the RC with the circuit that sent it. It replies to Alice with an empty
  459. RELAY_COMMAND_RENDEZVOUS_ESTABLISHED cell to indicate success.
  460. Alice's OP MUST NOT use the circuit which sent the cell for any purpose
  461. other than rendezvous with the given location-hidden service.
  462. 1.8. Introduction: from Alice's OP to Introduction Point
  463. Alice builds a separate circuit to one of Bob's chosen introduction
  464. points, and sends it a RELAY_COMMAND_INTRODUCE1 cell containing:
  465. Cleartext
  466. PK_ID Identifier for Bob's PK [20 octets]
  467. Encrypted to Bob's PK: (in the v0 intro protocol)
  468. RP Rendezvous point's nickname [20 octets]
  469. RC Rendezvous cookie [20 octets]
  470. g^x Diffie-Hellman data, part 1 [128 octets]
  471. OR (in the v1 intro protocol)
  472. VER Version byte: set to 1. [1 octet]
  473. RP Rendezvous point nick or ID [42 octets]
  474. RC Rendezvous cookie [20 octets]
  475. g^x Diffie-Hellman data, part 1 [128 octets]
  476. OR (in the v2 intro protocol)
  477. VER Version byte: set to 2. [1 octet]
  478. IP Rendezvous point's address [4 octets]
  479. PORT Rendezvous point's OR port [2 octets]
  480. ID Rendezvous point identity ID [20 octets]
  481. KLEN Length of onion key [2 octets]
  482. KEY Rendezvous point onion key [KLEN octets]
  483. RC Rendezvous cookie [20 octets]
  484. g^x Diffie-Hellman data, part 1 [128 octets]
  485. OR (in the v3 intro protocol)
  486. VER Version byte: set to 3. [1 octet]
  487. AUTHT The auth type that is used [1 octet]
  488. If AUTHT != [00]:
  489. AUTHL Length of auth data [2 octets]
  490. AUTHD Auth data [variable]
  491. TS A timestamp [4 octets]
  492. IP Rendezvous point's address [4 octets]
  493. PORT Rendezvous point's OR port [2 octets]
  494. ID Rendezvous point identity ID [20 octets]
  495. KLEN Length of onion key [2 octets]
  496. KEY Rendezvous point onion key [KLEN octets]
  497. RC Rendezvous cookie [20 octets]
  498. g^x Diffie-Hellman data, part 1 [128 octets]
  499. PK_ID is the hash of Bob's public key or the service key, depending on the
  500. hidden service descriptor version. In case of a v0 descriptor, Alice's OP
  501. uses Bob's public key. If Alice has downloaded a v2 descriptor, she uses
  502. the contained public key ("service-key").
  503. RP is NUL-padded and terminated. In version 0 of the intro protocol, RP
  504. must contain a nickname. In version 1, it must contain EITHER a nickname or
  505. an identity key digest that is encoded in hex and prefixed with a '$'.
  506. The hybrid encryption to Bob's PK works just like the hybrid
  507. encryption in CREATE cells (see tor-spec). Thus the payload of the
  508. version 0 RELAY_COMMAND_INTRODUCE1 cell on the wire will contain
  509. 20+42+16+20+20+128=246 bytes, and the version 1 and version 2
  510. introduction formats have other sizes.
  511. Through Tor, clients only generated the v0 introduction
  512. format, whereas hidden services have understood and accepted v0,
  513. v1, and v2 since 0.1.1.x. As of Tor and,
  514. clients switched to using the v2 intro format.
  515. The Timestampe (TS) field is no longer used in Tor and
  516. later. Clients MAY refrain from sending it; see the
  517. "Support022HiddenServices" parameter in dir-spec.txt. Clients SHOULD
  518. NOT send a precise timestamp, and should instead round to the nearest
  519. 10 minutes.
  520. 1.9. Introduction: From the Introduction Point to Bob's OP
  521. If the Introduction Point recognizes PK_ID as a public key which has
  522. established a circuit for introductions as in 1.2 above, it sends the body
  523. of the cell in a new RELAY_COMMAND_INTRODUCE2 cell down the corresponding
  524. circuit. (If the PK_ID is unrecognized, the RELAY_COMMAND_INTRODUCE1 cell is
  525. discarded.)
  526. After sending the RELAY_COMMAND_INTRODUCE2 cell to Bob, the OR replies to
  527. Alice with an empty RELAY_COMMAND_INTRODUCE_ACK cell. If no
  528. RELAY_COMMAND_INTRODUCE2 cell can be sent, the OR replies to Alice with a
  529. non-empty cell to indicate an error. (The semantics of the cell body may be
  530. determined later; the current implementation sends a single '1' byte on
  531. failure.)
  532. When Bob's OP receives the RELAY_COMMAND_INTRODUCE2 cell, it first checks
  533. for a replay. Because of the (undesirable!) malleability of the hybrid
  534. encryption, Bob's OP should only check whether the RSA-encrypted part is
  535. replayed. It does this by keeping, for each introduction key, a list of
  536. cryptographic digests of all the RSA-encrypted parts of the INTRODUCE2
  537. cells that it's seen, and dropping any INTRODUCE2 cell whose RSA-encrypted
  538. part it has seen before. When Bob's OP stops using a given introduction
  539. key, it drops the replay cache corresponding to that key.
  540. (Versions of Tor before used the timestamp in the INTRODUCE2
  541. cell to limit the lifetime of entries in the replay cache. This proved to
  542. be fragile, due to insufficiently synchronized clients.)
  543. Assuming that the cell has not been replayed, Bob's server decrypts it
  544. with the private key for the corresponding hidden service, and extracts the
  545. rendezvous point's nickname, the rendezvous cookie, and the value of g^x
  546. chosen by Alice.
  547. 1.10. Rendezvous
  548. Bob's OP builds a new Tor circuit ending at Alice's chosen rendezvous
  549. point, and sends a RELAY_COMMAND_RENDEZVOUS1 cell along this circuit,
  550. containing:
  551. RC Rendezvous cookie [20 octets]
  552. g^y Diffie-Hellman [128 octets]
  553. KH Handshake digest [20 octets]
  554. (Bob's OP MUST NOT use this circuit for any other purpose.)
  555. (By default, Bob builds a circuit of at least three hops, *not including*
  556. Alice's chosen rendezvous point.)
  557. If the RP recognizes RC, it relays the rest of the cell down the
  558. corresponding circuit in a RELAY_COMMAND_RENDEZVOUS2 cell, containing:
  559. g^y Diffie-Hellman [128 octets]
  560. KH Handshake digest [20 octets]
  561. (If the RP does not recognize the RC, it discards the cell and
  562. tears down the circuit.)
  563. Rendezvous points running Tor version and later are
  564. willing to pass on RENDEZVOUS2 cells so long as they contain at least
  565. the 20 bytes of cookie. Prior to, the RP refused the
  566. cell if it had a payload length different from 20+128+20.
  567. When Alice's OP receives a RELAY_COMMAND_RENDEZVOUS2 cell on a circuit which
  568. has sent a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell but which has not yet
  569. received a reply, it uses g^y and H(g^xy) to complete the handshake as in
  570. the Tor circuit extend process: they establish a 60-octet string as
  571. K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02])
  572. and generate KH, Df, Db, Kf, and Kb as in the KDF-TOR key derivation
  573. approach documented in tor-spec.txt.
  574. As in the TAP handshake, if the KH value derived from KDF-Tor does not
  575. match the value in the RENDEZVOUS2 cell, the client must close the
  576. circuit.
  577. Subsequently, the rendezvous point passes RELAY cells, unchanged, from
  578. each of the two circuits to the other. When Alice's OP sends RELAY cells
  579. along the circuit, it authenticates with Df, and encrypts them with the
  580. Kf, then with all of the keys for the ORs in Alice's side of the circuit;
  581. and when Alice's OP receives RELAY cells from the circuit, it decrypts
  582. them with the keys for the ORs in Alice's side of the circuit, then
  583. decrypts them with Kb, and checks integrity with Db. Bob's OP does the
  584. same, with Kf and Kb interchanged.
  585. 1.11. Creating streams
  586. To open TCP connections to Bob's location-hidden service, Alice's OP sends
  587. a RELAY_COMMAND_BEGIN cell along the established circuit, using the special
  588. address "", and a chosen port. Bob's OP chooses a destination IP and
  589. port, based on the configuration of the service connected to the circuit,
  590. and opens a TCP stream. From then on, Bob's OP treats the stream as an
  591. ordinary exit connection.
  592. [ Except he doesn't include addr in the connected cell or the end
  593. cell. -RD]
  594. Alice MAY send multiple RELAY_COMMAND_BEGIN cells along the circuit, to open
  595. multiple streams to Bob. Alice SHOULD NOT send RELAY_COMMAND_BEGIN cells
  596. for any other address along her circuit to Bob; if she does, Bob MUST reject
  597. them.
  598. 1.12. Closing streams
  599. The payload of a RELAY_END cell begins with a single 'reason' byte to
  600. describe why the stream is closing, plus optional data (depending on the
  601. reason.) These can be found in section 6.3 of tor-spec. The following
  602. describes some of the hidden service related reasons.
  603. 1 -- REASON_MISC
  604. Catch-all for unlisted reasons. Shouldn't happen much in practice.
  606. Tor tried to fetch the hidden service descriptor from the hsdirs but
  607. none of them had it. This implies that the hidden service has not
  608. been running in the past 24 hours.
  610. Every step of the rendezvous worked great, and that the hidden
  611. service is indeed up and running and configured to use the virtual
  612. port you asked for, but there was nothing listening on the other end
  613. of that virtual port. For example, the HS's Tor client is running
  614. fine but its apache service is down.
  616. The destination port that you tried is not configured on the hidden
  617. service side. That is, the hidden service was up and reachable, but
  618. it isn't listening on this port. Since Tor and later
  619. hidden service don't send this error code; instead they send back an
  620. END cell with reason DONE reason then close the circuit on you. This
  621. behavior can be controlled by a config option.
  622. 5 -- REASON_DESTROY
  623. The circuit closed before you could get a response back -- transient
  624. failure, e.g. a relay went down unexpectedly. Trying again might
  625. work.
  626. 6 -- REASON_DONE
  627. Anonymized TCP connection was closed. If you get an END cell with
  628. reason DONE, *before* you've gotten your CONNECTED cell, that
  629. indicates a similar situation to EXITPOLICY, but the hidden service
  630. is running or later, and it has now closed the circuit
  631. on you.
  632. 7 -- REASON_TIMEOUT
  633. Either like CONNECTREFUSED above but connect() got the ETIMEDOUT
  634. errno, or the client-side timeout of 120 seconds kicked in and we
  635. gave up.
  636. 8 -- REASON_NOROUTE
  637. Like CONNECTREFUSED except the errno at the hidden service when
  638. trying to connect() to the service was ENETUNREACH, EHOSTUNREACH,
  639. EACCES, or EPERM.
  640. 10 -- REASON_INTERNAL
  641. Internal error inside the Tor client -- hopefully you will not see
  642. this much. Please report if you do!
  644. Like CONNECTREFUSED except the errno at the hidden service when
  645. trying to connect() to the service was ECONNRESET.
  646. 2. Authentication and authorization.
  647. The rendezvous protocol as described in Section 1 provides a few options
  648. for implementing client-side authorization. There are two steps in the
  649. rendezvous protocol that can be used for performing client authorization:
  650. when downloading and decrypting parts of the hidden service descriptor and
  651. at Bob's Tor client before contacting the rendezvous point. A service
  652. provider can restrict access to his service at these two points to
  653. authorized clients only.
  654. There are currently two authorization protocols specified that are
  655. described in more detail below:
  656. 1. The first protocol allows a service provider to restrict access
  657. to clients with a previously received secret key only, but does not
  658. attempt to hide service activity from others.
  659. 2. The second protocol, albeit being feasible for a limited set of about
  660. 16 clients, performs client authorization and hides service activity
  661. from everyone but the authorized clients.
  662. 2.1. Service with large-scale client authorization
  663. The first client authorization protocol aims at performing access control
  664. while consuming as few additional resources as possible. This is the "basic"
  665. authorization protocol. A service provider should be able to permit access
  666. to a large number of clients while denying access for everyone else.
  667. However, the price for scalability is that the service won't be able to hide
  668. its activity from unauthorized or formerly authorized clients.
  669. The main idea of this protocol is to encrypt the introduction-point part
  670. in hidden service descriptors to authorized clients using symmetric keys.
  671. This ensures that nobody else but authorized clients can learn which
  672. introduction points a service currently uses, nor can someone send a
  673. valid INTRODUCE1 message without knowing the introduction key. Therefore,
  674. a subsequent authorization at the introduction point is not required.
  675. A service provider generates symmetric "descriptor cookies" for his
  676. clients and distributes them outside of Tor. The suggested key size is
  677. 128 bits, so that descriptor cookies can be encoded in 22 base64 chars
  678. (which can hold up to 22 * 6 = 132 bits, leaving 4 bits to encode the
  679. authorization type (here: "0") and allow a client to distinguish this
  680. authorization protocol from others like the one proposed below).
  681. Typically, the contact information for a hidden service using this
  682. authorization protocol looks like this:
  683. v2cbb2l4lsnpio4q.onion Ll3X7Xgz9eHGKCCnlFH0uz
  684. When generating a hidden service descriptor, the service encrypts the
  685. introduction-point part with a single randomly generated symmetric
  686. 128-bit session key using AES-CTR as described for v2 hidden service
  687. descriptors in rend-spec. Afterwards, the service encrypts the session
  688. key to all descriptor cookies using AES. Authorized client should be able
  689. to efficiently find the session key that is encrypted for him/her, so
  690. that 4 octet long client ID are generated consisting of descriptor cookie
  691. and initialization vector. Descriptors always contain a number of
  692. encrypted session keys that is a multiple of 16 by adding fake entries.
  693. Encrypted session keys are ordered by client IDs in order to conceal
  694. addition or removal of authorized clients by the service provider.
  695. ATYPE Authorization type: set to 1. [1 octet]
  696. ALEN Number of clients := 1 + ((clients - 1) div 16) [1 octet]
  697. for each symmetric descriptor cookie:
  698. ID Client ID: H(descriptor cookie | IV)[:4] [4 octets]
  699. SKEY Session key encrypted with descriptor cookie [16 octets]
  700. (end of client-specific part)
  701. RND Random data [(15 - ((clients - 1) mod 16)) * 20 octets]
  702. IV AES initialization vector [16 octets]
  703. IPOS Intro points, encrypted with session key [remaining octets]
  704. An authorized client needs to configure Tor to use the descriptor cookie
  705. when accessing the hidden service. Therefore, a user adds the contact
  706. information that she received from the service provider to her torrc
  707. file. Upon downloading a hidden service descriptor, Tor finds the
  708. encrypted introduction-point part and attempts to decrypt it using the
  709. configured descriptor cookie. (In the rare event of two or more client
  710. IDs being equal a client tries to decrypt all of them.)
  711. Upon sending the introduction, the client includes her descriptor cookie
  712. as auth type "1" in the INTRODUCE2 cell that she sends to the service.
  713. The hidden service checks whether the included descriptor cookie is
  714. authorized to access the service and either responds to the introduction
  715. request, or not.
  716. 2.2. Authorization for limited number of clients
  717. A second, more sophisticated client authorization protocol goes the extra
  718. mile of hiding service activity from unauthorized clients. This is the
  719. "stealth" authorization protocol. With all else being equal to the preceding
  720. authorization protocol, the second protocol publishes hidden service
  721. descriptors for each user separately and gets along with encrypting the
  722. introduction-point part of descriptors to a single client. This allows the
  723. service to stop publishing descriptors for removed clients. As long as a
  724. removed client cannot link descriptors issued for other clients to the
  725. service, it cannot derive service activity any more. The downside of this
  726. approach is limited scalability. Even though the distributed storage of
  727. descriptors (cf. proposal 114) tackles the problem of limited scalability to
  728. a certain extent, this protocol should not be used for services with more
  729. than 16 clients. (In fact, Tor should refuse to advertise services for more
  730. than this number of clients.)
  731. A hidden service generates an asymmetric "client key" and a symmetric
  732. "descriptor cookie" for each client. The client key is used as
  733. replacement for the service's permanent key, so that the service uses a
  734. different identity for each of his clients. The descriptor cookie is used
  735. to store descriptors at changing directory nodes that are unpredictable
  736. for anyone but service and client, to encrypt the introduction-point
  737. part, and to be included in INTRODUCE2 cells. Once the service has
  738. created client key and descriptor cookie, he tells them to the client
  739. outside of Tor. The contact information string looks similar to the one
  740. used by the preceding authorization protocol (with the only difference
  741. that it has "1" encoded as auth-type in the remaining 4 of 132 bits
  742. instead of "0" as before).
  743. When creating a hidden service descriptor for an authorized client, the
  744. hidden service uses the client key and descriptor cookie to compute
  745. secret ID part and descriptor ID:
  746. secret-id-part = H(time-period | descriptor-cookie | replica)
  747. descriptor-id = H(client-key[:10] | secret-id-part)
  748. The hidden service also replaces permanent-key in the descriptor with
  749. client-key and encrypts introduction-points with the descriptor cookie.
  750. ATYPE Authorization type: set to 2. [1 octet]
  751. IV AES initialization vector [16 octets]
  752. IPOS Intro points, encr. with descriptor cookie [remaining octets]
  753. When uploading descriptors, the hidden service needs to make sure that
  754. descriptors for different clients are not uploaded at the same time (cf.
  755. Section 1.1) which is also a limiting factor for the number of clients.
  756. When a client is requested to establish a connection to a hidden service
  757. it looks up whether it has any authorization data configured for that
  758. service. If the user has configured authorization data for authorization
  759. protocol "2", the descriptor ID is determined as described in the last
  760. paragraph. Upon receiving a descriptor, the client decrypts the
  761. introduction-point part using its descriptor cookie. Further, the client
  762. includes its descriptor cookie as auth-type "2" in INTRODUCE2 cells that
  763. it sends to the service.
  764. 2.3. Hidden service configuration
  765. A hidden service that is meant to perform client authorization adds a
  766. new option HiddenServiceAuthorizeClient to its hidden service
  767. configuration. This option contains the authorization type which is
  768. either "basic" for the protocol described in 2.1 or "stealth" for the
  769. protocol in 2.2 and a comma-separated list of human-readable client
  770. names, so that Tor can create authorization data for these clients:
  771. HiddenServiceAuthorizeClient auth-type client-name,client-name,...
  772. If this option is configured, HiddenServiceVersion is automatically
  773. reconfigured to contain only version numbers of 2 or higher. There is
  774. a maximum of 512 client names for basic auth and a maximum of 16 for
  775. stealth auth.
  776. Tor stores all generated authorization data for the authorization
  777. protocols described in Sections 2.1 and 2.2 in a new file using the
  778. following file format:
  779. "client-name" human-readable client identifier NL
  780. "descriptor-cookie" 128-bit key ^= 22 base64 chars NL
  781. If the authorization protocol of Section 2.2 is used, Tor also generates
  782. and stores the following data:
  783. "client-key" NL a private key in PEM format
  784. [No extra arguments]
  785. 2.4. Client configuration
  786. To specify the cookie to use to access a given hidden service,
  787. clients use the following syntax:
  788. HidServAuth onion-address auth-cookie [service-name]:
  789. Valid onion addresses contain 16 characters in a-z2-7 plus
  790. ".onion", and valid auth cookies contain 22 characters in
  791. A-Za-z0-9+/. The service name is only used for internal purposes,
  792. e.g., for Tor controllers; nothing in Tor itself requires or uses
  793. it.
  794. 3. Hidden service directory operation
  795. This section has been introduced with the v2 hidden service descriptor
  796. format. It describes all operations of the v2 hidden service descriptor
  797. fetching and propagation mechanism that are required for the protocol
  798. described in section 1 to succeed with v2 hidden service descriptors.
  799. 3.1. Configuring as hidden service directory
  800. Every onion router that has its directory port open can decide whether it
  801. wants to store and serve hidden service descriptors. An onion router which
  802. is configured as such includes the "hidden-service-dir" flag in its router
  803. descriptors that it sends to directory authorities.
  804. The directory authorities include a new flag "HSDir" for routers that
  805. decided to provide storage for hidden service descriptors and that
  806. have been running for at least 96 hours.
  807. 3.2. Accepting publish requests
  808. Hidden service directory nodes accept publish requests for v2 hidden service
  809. descriptors and store them to their local memory. (It is not necessary to
  810. make descriptors persistent, because after restarting, the onion router
  811. would not be accepted as a storing node anyway, because it has not been
  812. running for at least 24 hours.) All requests and replies are formatted as
  813. HTTP messages. Requests are initiated via BEGIN_DIR cells directed to
  814. the router's directory port, and formatted as HTTP POST requests to the URL
  815. "/tor/rendezvous2/publish" relative to the hidden service directory's root,
  816. containing as its body a v2 service descriptor.
  817. A hidden service directory node parses every received descriptor and only
  818. stores it when it thinks that it is responsible for storing that descriptor
  819. based on its own routing table. See section 1.4 for more information on how
  820. to determine responsibility for a certain descriptor ID.
  821. 3.3. Processing fetch requests
  822. Hidden service directory nodes process fetch requests for hidden service
  823. descriptors by looking them up in their local memory. (They do not need to
  824. determine if they are responsible for the passed ID, because it does no harm
  825. if they deliver a descriptor for which they are not (any more) responsible.)
  826. All requests and replies are formatted as HTTP messages. Requests are
  827. initiated via BEGIN_DIR cells directed to the router's directory port,
  828. and formatted as HTTP GET requests for the document "/tor/rendezvous2/<z>",
  829. where z is replaced with the encoding of the descriptor ID.