rend-spec.txt 35 KB

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