doc/rend-spec.txt

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