rend-spec.txt 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344
  1. $Id$
  2. [XXX We need to make nicknames in intro* cells padded to 20
  3. bytes, and maybe have a fixed length for nicknames in the
  4. descriptor too -RD]
  5. Tor Rendezvous Spec
  6. 0. Overview and preliminaries
  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 OR circuits to those
  14. introduction points, and tells them about his public key. To
  15. connect to Bob, Alice first builds an OR circuit to an OR to act as
  16. her "Rendezvous Point", then connects to one of Bob's chosen
  17. introduction points, and asks it to tell him about her Rendezvous
  18. Point (RP). If Bob chooses to answer, he builds an OR circuit to her
  19. RP, and tells it to connect him to Alice. The RP joints their
  20. circuits together, and begins relaying cells. Alice's 'BEGIN'
  21. cells are received directly by Bob's OP, which responds by
  22. communication with the local server implementing Bob's service.
  23. Below, we describe a network-level specification of this service,
  24. along with interfaces to make this process transparent to Alice
  25. (so long as she is using an OP).
  26. 0.1. Notation, conventions and prerequisites
  27. In the specifications below, we use the same notation as in
  28. "tor-spec.txt". The service specified here also requires the existence of
  29. an onion routing network as specified in "tor-spec.txt".
  30. H(x) is a SHA1 digest of x.
  31. PKSign(SK,x) is a PKCS.1-padded RSA signature of x with SK.
  32. PKEncrypt(SK,x) is a PKCS.1-padded RSA encryption of x with SK.
  33. Public keys are all RSA, and encoded in ASN.1.
  34. All integers are stored in network (big-endian) order.
  35. All symmetric encryption uses AES in counter mode, except where
  36. otherwise noted.
  37. In all discussions, "Alice" will refer to a user connecting to a
  38. location-hidden service, and "Bob" will refer to a user running a
  39. location-hidden service.
  40. 0.2. Protocol outline
  41. 1. Bob->Bob's OP: "Offer IP:Port as public-key-name:Port". [configuration]
  42. (We do not specify this step; it is left to the implementor of
  43. Bob's OP.)
  44. 2. Bob's OP generates keypair and rendezvous service descriptor:
  45. "Meet public-key X at introduction point A, B, or C." (signed)
  46. 3. Bob's OP->Introduction point via Tor: [introduction setup]
  47. "This pk is me."
  48. 4. Bob's OP->directory service via Tor: publishes Bob's service descriptor
  49. [advertisement]
  50. 5. Out of band, Alice receives a y.onion:port address. She opens a
  51. SOCKS connection to her OP, and requests y.onion:port.
  52. 6. Alice's OP retrieves Bob's descriptor via Tor: [descriptor lookup.]
  53. 7. Alice's OP chooses a rendezvous point, opens a circuit to that
  54. rendezvous point, and establishes a rendezvous circuit. [rendezvous
  55. setup.]
  56. 8. Alice connects to the Introduction point via Tor, and tells it about
  57. her rendezvous point. (Encrypted to Bob.) [Introduction 1]
  58. 9. The Introduction point passes this on to Bob's OP via Tor, along the
  59. introduction circuit. [Introduction 2]
  60. 10. Bob's OP decides whether to connect to Alice, and if so, creates a
  61. circuit to Alice's RP via Tor. Establishes a shared circuit.
  62. [Rendezvous.]
  63. 11. Alice's OP sends begin cells to Bob's OP. [Connection]
  64. 0.3. Constants and new cell types
  65. Relay cell types
  66. 32 -- RELAY_ESTABLISH_INTRO
  67. 33 -- RELAY_ESTABLISH_RENDEZVOUS
  68. 34 -- RELAY_INTRODUCE1
  69. 35 -- RELAY_INTRODUCE2
  70. 36 -- RELAY_RENDEZVOUS1
  71. 37 -- RELAY_RENDEZVOUS2
  72. 38 -- RELAY_INTRO_ESTABLISHED
  73. 39 -- RELAY_RENDEZVOUS_ESTABLISHED
  74. 40 -- RELAY_COMMAND_INTRODUCE_ACK
  75. 1. The Protocol
  76. 1.1. Bob configures his local OP.
  77. We do not specify a format for the OP configuration file. However,
  78. OPs SHOULD allow Bob to provide more than one advertised service
  79. per OP, and MUST allow Bob to specify one or more virtual ports per
  80. service. Bob provides a mapping from each of these virtual ports
  81. to a local IP:Port pair.
  82. 1.2. Bob's OP generates service descriptors.
  83. The first time the OP provides an advertised service, it generates
  84. a public/private keypair (stored locally). Periodically, the OP
  85. generates a service descriptor, containing:
  86. KL Key length [2 octets]
  87. PK Bob's public key [KL octets]
  88. TS A timestamp [4 octets]
  89. NI Number of introduction points [2 octets]
  90. Ipt A list of NUL-terminated ORs [variable]
  91. SIG Signature of above fields [variable]
  92. KL is the length of PK, in octets. (Currently, KL must be 128.)
  93. TS is the number of seconds elapsed since Jan 1, 1970.
  94. The members of Ipt may be either (a) nicknames, or (b) identity key
  95. digests, encoded in hex, and prefixed with a '$'. Clients must
  96. accept both forms. Services must only generate the second form.
  97. Once 0.0.8.1 and 0.0.9pre3-4 are obsoleted, we can drop the first
  98. form.
  99. [It's ok for Bob to advertise 0 introduction points. He might want
  100. to do that if he previously advertised some introduction points,
  101. and now he doesn't have any. -RD]
  102. 1.3. Bob's OP establishes his introduction points.
  103. The OP establishes a new introduction circuit to each introduction
  104. point. These circuits MUST NOT be used for anything but rendezvous
  105. introduction. To establish the introduction, Bob sends a
  106. RELAY_ESTABLISH_INTRO cell, containing:
  107. KL Key length [2 octets]
  108. PK Bob's public key [KL octets]
  109. HS Hash of session info [20 octets]
  110. SIG Signature of above information [variable]
  111. To prevent replay attacks, the HS field contains a SHA-1 hash based on the
  112. shared secret KH between Bob's OP and the introduction point, as
  113. follows:
  114. HS = H(KH | "INTRODUCE")
  115. That is:
  116. HS = H(KH | [49 4E 54 52 4F 44 55 43 45])
  117. (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)
  118. Upon receiving such a cell, the OR first checks that the signature is
  119. correct with the included public key. If so, it checks whether HS is
  120. correct given the shared state between Bob's OP and the OR. If either
  121. check fails, the OP discards the cell; otherwise, it associates the
  122. circuit with Bob's public key, and dissociates any other circuits
  123. currently associated with PK. On success, the OR sends Bob a
  124. RELAY_INTRO_ESTABLISHED cell with an empty payload.
  125. 1.4. Bob's OP advertises his service descriptor
  126. Bob's OP opens a stream to each directory server's directory port via Tor.
  127. (He may re-use old circuits for this.)
  128. Over this stream, Bob's OP makes an HTTP 'POST' request, to the URL
  129. '/rendezvous/publish' (relative to the directory server's root),
  130. containing as its body Bob's service descriptor. Upon receiving a
  131. descriptor, the directory server checks the signature, and discards the
  132. descriptor if the signature does not match the enclosed public key. Next,
  133. the directory server checks the timestamp. If the timestamp is more than
  134. 24 hours in the past or more than 1 hour in the future, or the directory
  135. server already has a newer descriptor with the same public key, the server
  136. discards the descriptor. Otherwise, the server discards any older
  137. descriptors with the same public key, and associates the new descriptor
  138. with the public key. The directory server remembers this descriptor for
  139. at least 24 hours after its timestamp. At least every 24 hours, Bob's OP
  140. uploads a fresh descriptor.
  141. 1.5. Alice receives a y.onion address
  142. When Alice receives a pointer to a location-hidden service, it is as a
  143. hostname of the form "y.onion", where y is a base-32 encoding of a
  144. 10-octet hash of Bob's service's public key, computed as follows:
  145. 1. Let H = H(PK).
  146. 2. Let H' = the first 80 bits of H, considering each octet from
  147. most significant bit to least significant bit.
  148. 2. Generate a 16-character encoding of H', using base32 as defined
  149. in RFC 3548.
  150. (We only use 80 bits instead of the 160 bits from SHA1 because we don't
  151. need to worry about man-in-the-middle attacks, and because it will make
  152. handling the url's more convenient.)
  153. [Yes, numbers are allowed at the beginning. See RFC1123. -NM]
  154. 1.6. Alice's OP retrieves a service descriptor
  155. Alice opens a stream to a directory server via Tor, and makes an HTTP GET
  156. request for the document '/rendezvous/<y>', where '<y> is replaced with the
  157. encoding of Bob's public key as described above. (She may re-use old
  158. circuits for this.) The directory replies with a 404 HTTP response if
  159. it does not recognize <y>, and otherwise returns Bob's most recently
  160. uploaded service descriptor.
  161. If Alice's OP receives a 404 response, it tries the other directory
  162. servers, and only fails the lookup if none recognizes the public key hash.
  163. Upon receiving a service descriptor, Alice verifies with the same process
  164. as the directory server uses, described above in section 1.4.
  165. The directory server gives a 400 response if it cannot understand Alice's
  166. request.
  167. Alice should cache the descriptor locally, but should not use
  168. descriptors that are more than 24 hours older than their timestamp.
  169. [Caching may make her partitionable, but she fetched it anonymously,
  170. and we can't very well *not* cache it. -RD]
  171. 1.7. Alice's OP establishes a rendezvous point.
  172. When Alice requests a connection to a given location-hidden service,
  173. and Alice's OP does not have an established circuit to that service,
  174. the OP builds a rendezvous circuit. It does this by establishing
  175. a circuit to a randomly chosen OR, and sending a
  176. RELAY_ESTABLISH_RENDEZVOUS cell to that OR. The body of that cell
  177. contains:
  178. RC Rendezvous cookie [20 octets]
  179. The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by
  180. Alice's OP.
  181. Upon receiving a RELAY_ESTABLISH_RENDEZVOUS cell, the OR associates the
  182. RC with the circuit that sent it. It replies to Alice with an empty
  183. RELAY_RENDEZVOUS_ESTABLISHED cell to indicate success.
  184. Alice's OP MUST NOT use the circuit which sent the cell for any purpose
  185. other than rendezvous with the given location-hidden service.
  186. 1.8. Introduction: from Alice's OP to Introduction Point
  187. Alice builds a separate circuit to one of Bob's chosen introduction
  188. points, and sends it a RELAY_INTRODUCE1 cell containing:
  189. Cleartext
  190. PK_ID Identifier for Bob's PK [20 octets]
  191. Encrypted to Bob's PK:
  192. RP Rendezvous point's nickname [20 octets]
  193. RC Rendezvous cookie [20 octets]
  194. g^x Diffie-Hellman data, part 1 [128 octets]
  195. OR
  196. VER Version byte: set to 1. [1 octet]
  197. RP [42 octets]
  198. RC Rendezvous cookie [20 octets]
  199. g^x Diffie-Hellman data, part 1 [128 octets]
  200. PK_ID is the hash of Bob's public key. RP is NUL-padded and terminated,
  201. and must contain EITHER a nickname, or an identity key digest, encoded in
  202. hex, and prefixed with a '$'.
  203. Implementations must accept both variants, but should only generate the
  204. first so long as Tor 0.0.7 is in use.
  205. The hybrid encryption to Bob's PK works just like the hybrid
  206. encryption in CREATE cells (see main spec). Thus the payload of the
  207. RELAY_INTRODUCE1 cell on the wire will contain 20+42+16+20+20+128=246
  208. bytes.
  209. 1.9. Introduction: From the Introduction Point to Bob's OP
  210. If the Introduction Point recognizes PK_ID as a public key which has
  211. established a circuit for introductions as in 1.3 above, it sends the body
  212. of the cell in a new RELAY_INTRODUCE2 cell down the corresponding circuit.
  213. (If the PK_ID is unrecognized, the RELAY_INTRODUCE1 cell is discarded.)
  214. After sending the RELAY_INTRODUCE2 cell, the OR replies to Alice with an
  215. empty RELAY_COMMAND_INTRODUCE_ACK cell. If no RELAY_INTRODUCE2 cell can
  216. be sent, the OR replies to Alice with a non-empty cell to indicate an
  217. error. (The semantics of the cell body may be determined later; the
  218. current implementation sends a single '1' byte on failure.)
  219. When Bob's OP receives the RELAY_INTRODUCE2 cell, it decrypts it with
  220. the private key for the corresponding hidden service, and extracts the
  221. rendezvous point's nickname, the rendezvous cookie, and the value of g^x
  222. chosen by Alice.
  223. 1.10. Rendezvous
  224. Bob's OP build a new Tor circuit ending at Alice's chosen rendezvous
  225. point, and sends a RELAY_RENDEZVOUS1 cell along this circuit, containing:
  226. RC Rendezvous cookie [20 octets]
  227. g^y Diffie-Hellman [128 octets]
  228. KH Handshake digest [20 octets]
  229. (Bob's OP MUST NOT use this circuit for any other purpose.)
  230. If the RP recognizes RC, it relays the rest of the cell down the
  231. corresponding circuit in a RELAY_RENDEZVOUS2 cell, containing:
  232. g^y Diffie-Hellman [128 octets]
  233. KH Handshake digest [20 octets]
  234. (If the RP does not recognize the RC, it discards the cell and
  235. tears down the circuit.)
  236. When Alice's OP receives a RELAY_RENDEZVOUS2 cell on a circuit which
  237. has sent a RELAY_ESTABLISH_RENDEZVOUS cell but which has not yet received
  238. a reply, it uses g^y and H(g^xy) to complete the handshake as in the Tor
  239. circuit extend process: they establish a 60-octet string as
  240. K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02])
  241. and generate
  242. KH = K[0..15]
  243. Kf = K[16..31]
  244. Kb = K[32..47]
  245. Subsequently, the rendezvous point passes relay cells, unchanged, from
  246. each of the two circuits to the other. When Alice's OP sends
  247. RELAY cells along the circuit, it first encrypts them with the
  248. Kf, then with all of the keys for the ORs in Alice's side of the circuit;
  249. and when Alice's OP receives RELAY cells from the circuit, it decrypts
  250. them with the keys for the ORs in Alice's side of the circuit, then
  251. decrypts them with Kb. Bob's OP does the same, with Kf and Kb
  252. interchanged.
  253. 1.11. Creating streams
  254. To open TCP connections to Bob's location-hidden service, Alice's OP sends
  255. a RELAY_BEGIN cell along the established circuit, using the special
  256. address "", and a chosen port. Bob's OP chooses a destination IP and
  257. port, based on the configuration of the service connected to the circuit,
  258. and opens a TCP stream. From then on, Bob's OP treats the stream as an
  259. ordinary exit connection.
  260. [ Except he doesn't include addr in the connected cell or the end
  261. cell. -RD]
  262. Alice MAY send multiple RELAY_BEGIN cells along the circuit, to open
  263. multiple streams to Bob. Alice SHOULD NOT send RELAY_BEGIN cells for any
  264. other address along her circuit to Bob; if she does, Bob MUST reject them.