From c4c97c074699123e6e7880c54a1ba0cb9385e4f2 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Sun, 28 Mar 2004 08:46:38 +0000 Subject: Initial rendezvous spec version. Needs another review and revision; but first I must sleep svn:r1355 --- doc/rend-spec.txt | 310 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 310 insertions(+) create mode 100644 doc/rend-spec.txt (limited to 'doc') diff --git a/doc/rend-spec.txt b/doc/rend-spec.txt new file mode 100644 index 000000000..afe7d8718 --- /dev/null +++ b/doc/rend-spec.txt @@ -0,0 +1,310 @@ +$Id$ + +Tor Rendezvous Spec + +0. Overview and preliminaries + + Rendezvous points provide location-hidden services (server + anonymity) for the onion routing network. With rendezvous points, + Bob can offer a TCP service (say, a webserver) via the onion + routing network, without revealing the IP of that service. + + Bob does this by anonymously advertising a public key for his + service, along with a list of onion routers to act as "Introduction + Points" for his service. He creates forward OR circuits to those + introduction points, and tells them about his public key. To + connect to Bob, Alice first builds an OR circuit to an OR to act as + her "Rendezvous Point", then connects to one of Bob's chosen + introduction points, and asks it to tell him about her Rendezvous + Point (RP). If Bob chooses to answer, he builds an OR circuit to her + RP, and tells it to connect him to Alice. The RP joints their + circuits together, and begins relaying cells. Alice's 'BEGIN' + cells are received directly by Bob's OP, which responds by + communication with the local server implementing Bob's service. + + Below, we describe a network-level specification of this service, + along with interfaces to make this process transparent to Alice + (so long as she is using an OP). + +0.1. Notation, conventions and prerequisites + + In the specifications below, we use the same notation as in + "tor-spec.txt". The service specified here also requires the existence of + an onion routing network as specified in "tor-spec.txt". + + H(x) is a SHA1 digest of x. + PKSign(SK,x) is a PKCS.1-padded RSA signature of x with SK. + PKEncrypt(SK,x) is a PKCS.1-padded RSA encryption of x with SK. + Public keys are all RSA, and encoded in ASN.1. + All integers are stored in network (big-endian) order. + All symmetric encryption uses AES in counter mode, except where + otherwise noted. + + In all discussions, "Alice" will refer to a user connecting to a + location-hidden service, and "Bob" will refer to a user running a + location-hidden service. + +0.2. Protocol outline + + 1. Bob->Bob's OP: "Offer IP:Port as public-key-name:Port". [configuration] + (We do not specify this step; it is left to the implementor of + Bob's OP.) + + 2. Bob's OP generates keypair and rendezvous service descriptor: + "Meet public-key X at introduction point A, B, or C." (signed) + + 3. Bob's OP->Introduction point via Tor: [introduction setup] + "This pk is me." + + 4. Bob's OP->directory service via Tor: publishes Bob's service descriptor + [advertisement] + + 5. Out of band, Alice receives a y.onion:port address. She opens a + SOCKS connection to her OP, and requests y.onion:port. + + 6. Alice's OP retrieves Bob's descriptor via Tor: [descriptor lookup.] + + 7. Alice's OP chooses a rendezvous point, opens a circuit to that + rendezvous point, and establishes a rendezvous circuit. [rendezvous + setup.] + + 8. Alice connects to the Introduction point via Tor, and tells it about + her rendezvous point. (Encrypted to Bob.) [Introduction 1] + + 9. The Introduction point passes this on to Bob's OP via Tor, along the + introduction circuit. [Introduction 2] + + 10. Bob's OP decides whether to connect to Alice, and if so, creates a + circuit to Alice's RP via Tor. Establishes a shared circuit. + [Rendezvous.] + + 11. Alice's OP sends begin cells to Bob's OP. [Connection] + +0.3. Constants and new cell types + + Relay cell types + 32 -- RELAY_ESTABLISH_INTRO + 33 -- RELAY_ESTABLISH_RENDEZVOUS + 34 -- RELAY_INTRODUCE1 + 35 -- RELAY_INTRODUCE2 + 36 -- RELAY_RENDEZVOUS1 + 37 -- RELAY_RENDEZVOUS2 + +1. The Protocol + +1.1. Bob configures his local OP. + + We do not specify a format for the OP configuration file. However, + OPs SHOULD allow Bob to provide more than one advertised service + per OP, and MUST allow Bob to specify one or more virtual ports per + service. Bob provides a mapping from each of these virtual ports + to a local IP:Port pair. + +1.2. Bob's OP generates service descriptors. + + The first time the OP provides an advertised service, it generates + a public/private keypair (stored locally). Periodically, the OP + generates service descriptor, containing: + + KL Key length [2 octets] + PK Bob's public key [KL octets] + TS A timestamp [8 octets] + NI Number of introduction points [2 octets] + Ipt A list of NUL-terminated OR nicknames [variable] + SIG Signature of above fields [KL octets] + + KL is the length of PK, in octets. (Currently, KL must be 128.) + TS is the number of milliseconds elapsed since Jan 1, 1970. + + [Shouldn't the nicknames be hostname:port's instead? That way, Alice's + directory servers don't need to know Bob's chosen introduction points. + Not important now, but essential if we ever have a non-total-knowledge + design. -NM] + +1.3. Bob's OP establishes his introduction points. + + The OP establishes a new introduction circuit to each introduction + point. These circuits MUST NOT be used for anything but rendezvous + introduction. To establish the introduction, Bob sends a + RELAY_ESTABLISH_INTRO cell, containing: + + KL Key length [2 octets + PK Bob's public key [KL octets] + HS Hash of session info [20 octets] + SIG Signature of above information [KL octets] + + To prevent replay attacks, the HS field contains a SHA-1 hash based on the + shared secret g^xy between Bob's OP and the introduction point, as + follows: + HS = H(g^xy | "INTRODUCE") + That is: + HS = H(g^xy | [49 4E 54 52 4F 44 55 43 45]) + + Upon receiving such a cell, the OR first checks that the signature is + correct with the included public key. If so, it checks whether HS is + correct given the shared state between Bob's OP and the OR. If either + check fails, the OP discards the cell; otherwise, it associates the + circuit with Bob's public key, and dissociates any other circuits + currently associated with PK. + +1.4. Bob's OP advertises his server descriptor + + Bob's OP opens a stream to each directory server's directory port via Tor. + Over this stream, Bob's OP makes an HTTP 'POST' request, to the URL + '/rendezvous/publish' (relative to the directory server's root), + containing as its body Bob's service descriptor. Upon receiving a + descriptor, the director server checks the signature, and discards the + descriptor if the signature does not match the enclosed public key. Next, + the directory server checks the timestamp. If the timestamp is more than + 24 hours in the past or more than 1 hour in the future, or the directory + server already has a newer descriptor with the same public key, the server + discards the descriptor. Otherwise, the server discards any older + descriptors with the same public key, and associates the new descriptor + with the public key. The directory server remembers this descriptor for + at least 24 hours after its timestamp. At least every 24 hours, Bob's OP + uploads a fresh descriptor. + +1.5. Alice receives a y.onion address + + When Alice receives a pointer to a location-hidden service, it is as a + hostname of the form "y.onion", where y is a base-32 encoding of a + ~16-octet hash of Bob's service's public key, computed as follows: + + 1. Let H = H(PK). + 2. Let H' = the first 130 bits of H, considering each octet from + most significant bit to least significant big. + 2. Generate a 26-character encoding of H', taking H' 5 bits at + a time, and mapping each 5-bit value to a character as follows: + 0..25 map to the characters 'a'...'z', respectively. + 26..31 map to the characters '0'...'5', respectively. + + (We only use 130 bits instead of the 160 bits from SHA1 because we don't + need to worry about man-in-the-middle attacks. We use 130 instead of 128 + in order to have an even multiple of 5.) + + [Yes, numbers are allowed at the beginning. See RFC1123. -NM] + +1.6. Alice's OP retrieves a service descriptor + + Alice opens a stream to a directory server via Tor, and makes an HTTP GET + request for the document '/rendevous/', where ' is replaced with the + encoding of Bob's public key as described above. The directory replies + with a 404 HTTP response if it does not recognize , and otherwise + returns Bob's most recently uploaded service descriptor. + + If Alice's OP receives a 404 response, it tries the other directory + servers, and only fails the lookup if none recognizes the public key hash. + + Upon receiving a service descriptor, Alice verifies with the same process + as the directory server uses, described above in section 1.4. + + [XXXX can Alice cache the descriptor? It may make her + partitionable. -NM] + +1.7. Alice's OP establishes a rendezvous point. + + When Alice requests a connection to a given location-hidden service, + and Alice's OP has not already established a circuit to that circuit, + the OP establishes a rendezvous service. It does this by establishing + a circuit to a randomly chosen OR, and sending a + RELAY_ESTABLISH_RENDEZVOUS cell to that OR. The body of that cell + contains: + + RC Rendezvous cookie [20 octets] + + The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by + Alice's OP. + + Upon receiving a RELAY_ESTABLISH_RENDEZVOUS cell, the OP associates the + RC with the circuit that sent it. + + Alice's OP MUST NOT use the circuit which sent the cell for any purpose + other than rendezvous with the given location-hidden service. + +1.8. Introduction: from Alice's OP to Introduction Point + + Via another circuit, Alice sends a RELAY_INTRODUCE1 cell to once of Bob's + chosen introduction points. This cell contains: + + Cleartext + PK_ID Identifier for Bob's PK [16 octets] + + Encrypted to Bob's PK: + RP Rendezvous point's nickname [variable] + RC Rendezvous cookie [20 octets] + g^x Diffie-Hellman data, part 1 [128 octetes] + + PK_ID is the first 16 octets of the hash of Bob's public key. RP is + NUL-terminated. + + The data is encrypted to Bob's PK as follows: Suppose Bob's PK is L octets + long. If the data to be encrypted is shorter than L, then it is encrypted + directly (with no padding). If the data is at least as long as L, then a + randomly generated 16-byte symmetric key is prepended to the data, after + which the first L-1 bytes of the data are encrypted with Bob's PK; and the + rest of the data is encrypted with the symmetric key. + +1.9. Introduction: From the Introduction Point to Bob's OP + + If the Introduction Point recognizes PK_ID as a public key which has + established a circuit for introductions as in 1.3 above, it sends the + encrypted portion of the cell in a new RELAY_INTRODUCE2 cell down the + corresponding circuit. (If the PK_ID is unrecognized, the + RELAY_INTRODUCE1 cell is discarded.) + + When Bob's OP receives the RELAY_INTRODUCE2 cell, it decrypts it with + the private key for the corresponding hidden service, and extracts the + rendezvous point's nickname, the rendezvous cookie, and the value of g^x + chosen by Alice. + +1.10. Rendezvous + + Bob's OP build a new Tor circuit ending at Alice's chosen rendezvous + point, and sends a RELAY_RENDEZVOUS1 cell along this circuit, containing: + RC Rendezvous cookie [20 octets] + g^y Diffie-Hellman [128 octets] + H(KH) Handshake digest [20 octets] + + (Bob's OP MUST NOT use this circuit for any other purpose.) + + If the RP recognizes RC, it relays the rest of the cell down the + corresponding circuit in a RELAY_RENDEZVOUS2 cell, containing: + + g^y Diffie-Hellman [128 octets] + H(KH) Handshake digest [20 octets] + + (If the RP does not recognize the RC, it discards the cell and + tears down the circuit.) + + When Alice's OP receives a RELAY_RENDEZVOUS2 cell on a circuit which + has sent a RELAY_ESTABLISH_RENDEZVOUS cell but which has not yet received + a reply, it uses g^y and H(g^xy) to complete the handshake as in the Tor + circuit extend process: they establish a 60-octet string as + K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02]) + and generate + KH = K[0..15] + Kf = K[16..31] + Kb = K[32..47] + + Subsequently, the rendezvous point passes relay cells, unchained, from + each of the two circuits to the other. When Alice's OP sends + sends RELAY cells along the circuit, it first encrypts them with the + Kf, then with all of the keys for the ORs in Alice's side of the circuit; + and when Alice's OP receives RELAY cells from the circuit, it decrypts + them with the keys for the ORs in Alice's side of the circuit, then + decrypts them with Kb. Bob's OP does the same, with Kf and Kb + interchanged. + +1.11. Creating streams + + To open TCP connections to Bob's location-hidden service, Alice's OP sends + a RELAY_BEGIN cell along the established circuit, using the special + address "", and a chosen port. Bob's OP chooses a destination IP and + port, based on the configuration of the service connected to the circuit, + and opens a TCP stream. From then on, Bob's OP treats the stream as an + ordinary exit connection. + + Alice MAY send multiple RELAY_BEGIN cells along the circuit, to open + multiple streams to Bob. Alice SHOULD NOT send RELAY_BEGIN cells for any + other address along her circuit to Bob; if she does, Bob MUST reject them. + -- cgit v1.2.3