Merge commit 'nickm/fix_security_bug_022' into maint-0.2.2
[tor.git] / doc / spec / rend-spec.txt
blob3c14ebc662ed0724df99201a9e403b771ff5c74e
2                     Tor Rendezvous Specification
4 0. Overview and preliminaries
6       The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
7       NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
8       "OPTIONAL" in this document are to be interpreted as described in
9       RFC 2119.
11    Read
12    https://svn.torproject.org/svn/projects/design-paper/tor-design.html#sec:rendezvous
13    before you read this specification. It will make more sense.
15    Rendezvous points provide location-hidden services (server
16    anonymity) for the onion routing network. With rendezvous points,
17    Bob can offer a TCP service (say, a webserver) via the onion
18    routing network, without revealing the IP of that service.
20    Bob does this by anonymously advertising a public key for his
21    service, along with a list of onion routers to act as "Introduction
22    Points" for his service.  He creates forward circuits to those
23    introduction points, and tells them about his service.  To
24    connect to Bob, Alice first builds a circuit to an OR to act as
25    her "Rendezvous Point." She then connects to one of Bob's chosen
26    introduction points, and asks it to tell him about her Rendezvous
27    Point (RP).  If Bob chooses to answer, he builds a circuit to her
28    RP, and tells it to connect him to Alice.  The RP joins their
29    circuits together, and begins relaying cells.  Alice's 'BEGIN'
30    cells are received directly by Bob's OP, which passes data to
31    and from the local server implementing Bob's service.
33    Below we describe a network-level specification of this service,
34    along with interfaces to make this process transparent to Alice
35    (so long as she is using an OP).
37 0.1. Notation, conventions and prerequisites
39    In the specifications below, we use the same notation and terminology
40    as in "tor-spec.txt".  The service specified here also requires the
41    existence of an onion routing network as specified in that file.
43         H(x) is a SHA1 digest of x.
44         PKSign(SK,x) is a PKCS.1-padded RSA signature of x with SK.
45         PKEncrypt(SK,x) is a PKCS.1-padded RSA encryption of x with SK.
46         Public keys are all RSA, and encoded in ASN.1.
47         All integers are stored in network (big-endian) order.
48         All symmetric encryption uses AES in counter mode, except where
49             otherwise noted.
51    In all discussions, "Alice" will refer to a user connecting to a
52    location-hidden service, and "Bob" will refer to a user running a
53    location-hidden service.
55    An OP is (as defined elsewhere) an "Onion Proxy" or Tor client.
57    An OR is (as defined elsewhere) an "Onion Router" or Tor server.
59    An "Introduction point" is a Tor server chosen to be Bob's medium-term
60    'meeting place'.  A "Rendezvous point" is a Tor server chosen by Alice to
61    be a short-term communication relay between her and Bob.  All Tor servers
62    potentially act as introduction and rendezvous points.
64 0.2. Protocol outline
66    1. Bob->Bob's OP: "Offer IP:Port as public-key-name:Port". [configuration]
67       (We do not specify this step; it is left to the implementor of
68       Bob's OP.)
70    2. Bob's OP generates a long-term keypair.
72    3. Bob's OP->Introduction point via Tor: [introduction setup]
73         "This public key is (currently) associated to me."
75    4. Bob's OP->directory service via Tor: publishes Bob's service descriptor
76       [advertisement]
77         "Meet public-key X at introduction point A, B, or C." (signed)
79    5. Out of band, Alice receives a z.onion:port address.
80       She opens a SOCKS connection to her OP, and requests z.onion:port.
82    6. Alice's OP retrieves Bob's descriptor via Tor. [descriptor lookup.]
84    7. Alice's OP chooses a rendezvous point, opens a circuit to that
85       rendezvous point, and establishes a rendezvous circuit. [rendezvous
86       setup.]
88    8. Alice connects to the Introduction point via Tor, and tells it about
89       her rendezvous point.  (Encrypted to Bob.)  [Introduction 1]
91    9. The Introduction point passes this on to Bob's OP via Tor, along the
92       introduction circuit. [Introduction 2]
94   10. Bob's OP decides whether to connect to Alice, and if so, creates a
95       circuit to Alice's RP via Tor.  Establishes a shared circuit.
96       [Rendezvous 1]
98   11. The Rendezvous point forwards Bob's confirmation to Alice's OP.
99       [Rendezvous 2]
101   12. Alice's OP sends begin cells to Bob's OP.  [Connection]
103 0.3. Constants and new cell types
105   Relay cell types
106       32 -- RELAY_COMMAND_ESTABLISH_INTRO
107       33 -- RELAY_COMMAND_ESTABLISH_RENDEZVOUS
108       34 -- RELAY_COMMAND_INTRODUCE1
109       35 -- RELAY_COMMAND_INTRODUCE2
110       36 -- RELAY_COMMAND_RENDEZVOUS1
111       37 -- RELAY_COMMAND_RENDEZVOUS2
112       38 -- RELAY_COMMAND_INTRO_ESTABLISHED
113       39 -- RELAY_COMMAND_RENDEZVOUS_ESTABLISHED
114       40 -- RELAY_COMMAND_INTRODUCE_ACK
116 0.4. Version overview
118    There are several parts in the hidden service protocol that have
119    changed over time, each of them having its own version number, whereas
120    other parts remained the same. The following list of potentially
121    versioned protocol parts should help reduce some confusion:
123    - Hidden service descriptor: the binary-based v0 was the default for a
124      long time, and an ASCII-based v2 has been added by proposal 114. The
125      v0 descriptor format has been deprecated in 0.2.2.1-alpha. See 1.3.
127    - Hidden service descriptor propagation mechanism: currently related to
128      the hidden service descriptor version -- v0 publishes to the original
129      hs directory authorities, whereas v2 publishes to a rotating subset
130      of relays with the "HSDir" flag; see 1.4 and 1.6.
132    - Introduction protocol for how to generate an introduction cell:
133      v0 specified a nickname for the rendezvous point and assumed the
134      relay would know about it, whereas v2 now specifies IP address,
135      port, and onion key so the relay doesn't need to already recognize
136      it. See 1.8.
138 1. The Protocol
140 1.1. Bob configures his local OP.
142    We do not specify a format for the OP configuration file.  However,
143    OPs SHOULD allow Bob to provide more than one advertised service
144    per OP, and MUST allow Bob to specify one or more virtual ports per
145    service.  Bob provides a mapping from each of these virtual ports
146    to a local IP:Port pair.
148 1.2. Bob's OP establishes his introduction points.
150    The first time the OP provides an advertised service, it generates
151    a public/private keypair (stored locally).
153    The OP chooses a small number of Tor servers as introduction points.
154    The OP establishes a new introduction circuit to each introduction
155    point.  These circuits MUST NOT be used for anything but hidden service
156    introduction.  To establish the introduction, Bob sends a
157    RELAY_COMMAND_ESTABLISH_INTRO cell, containing:
159         KL   Key length                             [2 octets]
160         PK   Bob's public key or service key        [KL octets]
161         HS   Hash of session info                   [20 octets]
162         SIG  Signature of above information         [variable]
164    KL is the length of PK, in octets.
166    To prevent replay attacks, the HS field contains a SHA-1 hash based on the
167    shared secret KH between Bob's OP and the introduction point, as
168    follows:
169        HS = H(KH | "INTRODUCE")
170    That is:
171        HS = H(KH | [49 4E 54 52 4F 44 55 43 45])
172    (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)
174    Upon receiving such a cell, the OR first checks that the signature is
175    correct with the included public key.  If so, it checks whether HS is
176    correct given the shared state between Bob's OP and the OR.  If either
177    check fails, the OP discards the cell; otherwise, it associates the
178    circuit with Bob's public key, and dissociates any other circuits
179    currently associated with PK.  On success, the OR sends Bob a
180    RELAY_COMMAND_INTRO_ESTABLISHED cell with an empty payload.
182    Bob's OP uses either Bob's public key or a freshly generated, single-use
183    service key in the RELAY_COMMAND_ESTABLISH_INTRO cell, depending on the
184    configured hidden service descriptor version.  The public key is used for
185    v0 descriptors, the service key for v2 descriptors.  In the latter case, the
186    service keys of all introduction points are included in the v2 hidden
187    service descriptor together with the other introduction point information.
188    The reason is that the introduction point does not need to and therefore
189    should not know for which hidden service it works, so as to prevent it from
190    tracking the hidden service's activity.  If the hidden service is configured
191    to publish both v0 and v2 descriptors, two separate sets of introduction
192    points are established.
194 1.3. Bob's OP generates service descriptors.
196    For versions before 0.2.2.1-alpha, Bob's OP periodically generates and
197    publishes a descriptor of type "V0".
199    The "V0" descriptor contains:
201          KL    Key length                            [2 octets]
202          PK    Bob's public key                      [KL octets]
203          TS    A timestamp                           [4 octets]
204          NI    Number of introduction points         [2 octets]
205          Ipt   A list of NUL-terminated ORs          [variable]
206          SIG   Signature of above fields             [variable]
208    TS is the number of seconds elapsed since Jan 1, 1970.
210    The members of Ipt may be either (a) nicknames, or (b) identity key
211    digests, encoded in hex, and prefixed with a '$'.  Clients must
212    accept both forms. Services must only generate the second form.
213    Once 0.0.9.x is obsoleted, we can drop the first form.
215    [It's ok for Bob to advertise 0 introduction points. He might want
216     to do that if he previously advertised some introduction points,
217     and now he doesn't have any. -RD]
219    Beginning with 0.2.0.10-alpha, Bob's OP encodes "V2" descriptors in
220    addition to (or instead of) "V0" descriptors. The format of a "V2"
221    descriptor is as follows:
223      "rendezvous-service-descriptor" descriptor-id NL
225        [At start, exactly once]
227        Indicates the beginning of the descriptor. "descriptor-id" is a
228        periodically changing identifier of 160 bits formatted as 32 base32
229        chars that is calculated by the hidden service and its clients. The
230        "descriptor-id" is calculated by performing the following operation:
232          descriptor-id =
233              H(permanent-id | H(time-period | descriptor-cookie | replica))
235        "permanent-id" is the permanent identifier of the hidden service,
236        consisting of 80 bits. It can be calculated by computing the hash value
237        of the public hidden service key and truncating after the first 80 bits:
239          permanent-id = H(public-key)[:10]
241        Note: If Bob's OP has "stealth" authorization enabled (see Section 2.2),
242        it uses the client key in place of the public hidden service key.
244        "H(time-period | descriptor-cookie | replica)" is the (possibly
245        secret) id part that is necessary to verify that the hidden service is
246        the true originator of this descriptor and that is therefore contained
247        in the descriptor, too. The descriptor ID can only be created by the
248        hidden service and its clients, but the "signature" below can only be
249        created by the service.
251        "time-period" changes periodically as a function of time and
253        "permanent-id". The current value for "time-period" can be calculated
254        using the following formula:
256          time-period = (current-time + permanent-id-byte * 86400 / 256)
257                          / 86400
259        "current-time" contains the current system time in seconds since
260        1970-01-01 00:00, e.g. 1188241957. "permanent-id-byte" is the first
261        (unsigned) byte of the permanent identifier (which is in network
262        order), e.g. 143. Adding the product of "permanent-id-byte" and
263        86400 (seconds per day), divided by 256, prevents "time-period" from
264        changing for all descriptors at the same time of the day. The result
265        of the overall operation is a (network-ordered) 32-bit integer, e.g.
266        13753 or 0x000035B9 with the example values given above.
268        "descriptor-cookie" is an optional secret password of 128 bits that
269        is shared between the hidden service provider and its clients. If the
270        descriptor-cookie is left out, the input to the hash function is 128
271        bits shorter.
273        "replica" denotes the number of the replica. A service publishes
274        multiple descriptors with different descriptor IDs in order to
275        distribute them to different places on the ring.
277      "version" version-number NL
279        [Exactly once]
281        The version number of this descriptor's format.  In this case: 2.
283      "permanent-key" NL a public key in PEM format
285        [Exactly once]
287        The public key of the hidden service which is required to verify the
288        "descriptor-id" and the "signature".
290      "secret-id-part" secret-id-part NL
292        [Exactly once]
294        The result of the following operation as explained above, formatted as
295        32 base32 chars. Using this secret id part, everyone can verify that
296        the signed descriptor belongs to "descriptor-id".
298          secret-id-part = H(time-period | descriptor-cookie | replica)
300      "publication-time" YYYY-MM-DD HH:MM:SS NL
302        [Exactly once]
304        A timestamp when this descriptor has been created.
306      "protocol-versions" version-string NL
308        [Exactly once]
310        A comma-separated list of recognized and permitted version numbers
311        for use in INTRODUCE cells; these versions are described in section
312        1.8 below.
314      "introduction-points" NL encrypted-string
316        [At most once]
318        A list of introduction points. If the optional "descriptor-cookie" is
319        used, this list is encrypted with AES in CTR mode with a random
320        initialization vector of 128 bits that is written to
321        the beginning of the encrypted string, and the "descriptor-cookie" as
322        secret key of 128 bits length.
324        The string containing the introduction point data (either encrypted
325        or not) is encoded in base64, and surrounded with
326        "-----BEGIN MESSAGE-----" and "-----END MESSAGE-----".
328        The unencrypted string may begin with:
330          "service-authentication" auth-type auth-data NL
332            [Any number]
334            The service-specific authentication data can be used to perform
335            client authentication. This data is independent of the selected
336            introduction point as opposed to "intro-authentication" below. The
337            format of auth-data (base64-encoded or PEM format) depends on
338            auth-type. See section 2 of this document for details on auth
339            mechanisms.
341        Subsequently, an arbitrary number of introduction point entries may
342        follow, each containing the following data:
344          "introduction-point" identifier NL
346            [At start, exactly once]
348            The identifier of this introduction point: the base-32 encoded
349            hash of this introduction point's identity key.
351          "ip-address" ip-address NL
353            [Exactly once]
355            The IP address of this introduction point.
357          "onion-port" port NL
359            [Exactly once]
361            The TCP port on which the introduction point is listening for
362            incoming onion requests.
364          "onion-key" NL a public key in PEM format
366            [Exactly once]
368            The public key that can be used to encrypt messages to this
369            introduction point.
371          "service-key" NL a public key in PEM format
373            [Exactly once]
375            The public key that can be used to encrypt messages to the hidden
376            service.
378          "intro-authentication" auth-type auth-data NL
380            [Any number]
382            The introduction-point-specific authentication data can be used
383            to perform client authentication. This data depends on the
384            selected introduction point as opposed to "service-authentication"
385            above. The format of auth-data (base64-encoded or PEM format)
386            depends on auth-type. See section 2 of this document for details
387            on auth mechanisms.
389         (This ends the fields in the encrypted portion of the descriptor.)
391        [It's ok for Bob to advertise 0 introduction points. He might want
392         to do that if he previously advertised some introduction points,
393         and now he doesn't have any. -RD]
395      "signature" NL signature-string
397        [At end, exactly once]
399        A signature of all fields above with the private key of the hidden
400        service.
402 1.3.1. Other descriptor formats we don't use.
404    Support for the V0 descriptor format was dropped in 0.2.2.0-alpha-dev:
406          KL    Key length                            [2 octets]
407          PK    Bob's public key                      [KL octets]
408          TS    A timestamp                           [4 octets]
409          NI    Number of introduction points         [2 octets]
410          Ipt   A list of NUL-terminated ORs          [variable]
411          SIG   Signature of above fields             [variable]
413    KL is the length of PK, in octets.
414    TS is the number of seconds elapsed since Jan 1, 1970.
416    The members of Ipt may be either (a) nicknames, or (b) identity key
417    digests, encoded in hex, and prefixed with a '$'.
419    The V1 descriptor format was understood and accepted from
420    0.1.1.5-alpha-cvs to 0.2.0.6-alpha-dev, but no Tors generated it and
421    it was removed:
423          V     Format byte: set to 255               [1 octet]
424          V     Version byte: set to 1                [1 octet]
425          KL    Key length                            [2 octets]
426          PK    Bob's public key                      [KL octets]
427          TS    A timestamp                           [4 octets]
428          PROTO Protocol versions: bitmask            [2 octets]
429          NI    Number of introduction points         [2 octets]
430          For each introduction point: (as in INTRODUCE2 cells)
431              IP     Introduction point's address     [4 octets]
432              PORT   Introduction point's OR port     [2 octets]
433              ID     Introduction point identity ID   [20 octets]
434              KLEN   Length of onion key              [2 octets]
435              KEY    Introduction point onion key     [KLEN octets]
436          SIG   Signature of above fields             [variable]
438    A hypothetical "V1" descriptor, that has never been used but might
439    be useful for historical reasons, contains:
441          V     Format byte: set to 255               [1 octet]
442          V     Version byte: set to 1                [1 octet]
443          KL    Key length                            [2 octets]
444          PK    Bob's public key                      [KL octets]
445          TS    A timestamp                           [4 octets]
446          PROTO Rendezvous protocol versions: bitmask [2 octets]
447          NA    Number of auth mechanisms accepted    [1 octet]
448          For each auth mechanism:
449              AUTHT  The auth type that is supported  [2 octets]
450              AUTHL  Length of auth data              [1 octet]
451              AUTHD  Auth data                        [variable]
452          NI    Number of introduction points         [2 octets]
453          For each introduction point: (as in INTRODUCE2 cells)
454              ATYPE  An address type (typically 4)    [1 octet]
455              ADDR   Introduction point's IP address  [4 or 16 octets]
456              PORT   Introduction point's OR port     [2 octets]
457              AUTHT  The auth type that is supported  [2 octets]
458              AUTHL  Length of auth data              [1 octet]
459              AUTHD  Auth data                        [variable]
460              ID     Introduction point identity ID   [20 octets]
461              KLEN   Length of onion key              [2 octets]
462              KEY    Introduction point onion key     [KLEN octets]
463          SIG   Signature of above fields             [variable]
465    AUTHT specifies which authentication/authorization mechanism is
466    required by the hidden service or the introduction point. AUTHD
467    is arbitrary data that can be associated with an auth approach.
468    Currently only AUTHT of [00 00] is supported, with an AUTHL of 0.
469    See section 2 of this document for details on auth mechanisms.
471 1.4. Bob's OP advertises his service descriptor(s).
473    Bob's OP advertises his service descriptor to a fixed set of v0 hidden
474    service directory servers and/or a changing subset of all v2 hidden service
475    directories.
477    For versions before 0.2.2.1-alpha, Bob's OP opens a stream to each v0
478    directory server's directory port via Tor.  (He may re-use old circuits for
479    this.)  Over this stream, Bob's OP makes an HTTP 'POST' request, to a URL
480    "/tor/rendezvous/publish" relative to the directory server's root,
481    containing as its body Bob's service descriptor.
483    Upon receiving a descriptor, the directory server checks the signature,
484    and discards the descriptor if the signature does not match the enclosed
485    public key.  Next, the directory server checks the timestamp.  If the
486    timestamp is more than 24 hours in the past or more than 1 hour in the
487    future, or the directory server already has a newer descriptor with the
488    same public key, the server discards the descriptor.  Otherwise, the
489    server discards any older descriptors with the same public key and
490    version format, and associates the new descriptor with the public key.
491    The directory server remembers this descriptor for at least 24 hours
492    after its timestamp.  At least every 18 hours, Bob's OP uploads a
493    fresh descriptor.
495    If Bob's OP is configured to publish v2 descriptors, it does so to a
496    changing subset of all v2 hidden service directories instead of the
497    authoritative directory servers. Therefore, Bob's OP opens a stream via
498    Tor to each responsible hidden service directory. (He may re-use old
499    circuits for this.) Over this stream, Bob's OP makes an HTTP 'POST'
500    request to a URL "/tor/rendezvous2/publish" relative to the hidden service
501    directory's root, containing as its body Bob's service descriptor.
503    At any time, there are 6 hidden service directories responsible for
504    keeping replicas of a descriptor; they consist of 2 sets of 3 hidden
505    service directories with consecutive onion IDs. Bob's OP learns about
506    the complete list of hidden service directories by filtering the
507    consensus status document received from the directory authorities. A
508    hidden service directory is deemed responsible for all descriptor IDs in
509    the interval from its direct predecessor, exclusive, to its own ID,
510    inclusive; it further holds replicas for its 2 predecessors. A
511    participant only trusts its own routing list and never learns about
512    routing information from other parties.
514    Bob's OP publishes a new v2 descriptor once an hour or whenever its
515    content changes. V2 descriptors can be found by clients within a given
516    time period of 24 hours, after which they change their ID as described
517    under 1.3. If a published descriptor would be valid for less than 60
518    minutes (= 2 x 30 minutes to allow the server to be 30 minutes behind
519    and the client 30 minutes ahead), Bob's OP publishes the descriptor
520    under the ID of both, the current and the next publication period.
522 1.5. Alice receives a z.onion address.
524    When Alice receives a pointer to a location-hidden service, it is as a
525    hostname of the form "z.onion", where z is a base-32 encoding of a
526    10-octet hash of Bob's service's public key, computed as follows:
528          1. Let H = H(PK).
529          2. Let H' = the first 80 bits of H, considering each octet from
530             most significant bit to least significant bit.
531          3. Generate a 16-character encoding of H', using base32 as defined
532             in RFC 3548.
534    (We only use 80 bits instead of the 160 bits from SHA1 because we
535    don't need to worry about arbitrary collisions, and because it will
536    make handling the url's more convenient.)
538    [Yes, numbers are allowed at the beginning.  See RFC 1123. -NM]
540 1.6. Alice's OP retrieves a service descriptor.
542    Alice's OP fetches the service descriptor from the fixed set of v0 hidden
543    service directory servers and/or a changing subset of all v2 hidden service
544    directories.
546    For versions before 0.2.2.1-alpha, Alice's OP opens a stream to a directory
547    server via Tor, and makes an HTTP GET request for the document
548    '/tor/rendezvous/<z>', where '<z>' is replaced with the encoding of Bob's
549    public key as described above. (She may re-use old circuits for this.) The
550    directory replies with a 404 HTTP response if it does not recognize <z>,
551    and otherwise returns Bob's most recently uploaded service descriptor.
553    If Alice's OP receives a 404 response, it tries the other directory
554    servers, and only fails the lookup if none recognize the public key hash.
556    Upon receiving a service descriptor, Alice verifies with the same process
557    as the directory server uses, described above in section 1.4.
559    The directory server gives a 400 response if it cannot understand Alice's
560    request.
562    Alice should cache the descriptor locally, but should not use
563    descriptors that are more than 24 hours older than their timestamp.
564    [Caching may make her partitionable, but she fetched it anonymously,
565     and we can't very well *not* cache it. -RD]
567    If Alice's OP is running 0.2.1.10-alpha or higher, it fetches v2 hidden
568    service descriptors. Versions before 0.2.2.1-alpha are fetching both v0 and
569    v2 descriptors in parallel. Similar to the description in section 1.4,
570    Alice's OP fetches a v2 descriptor from a randomly chosen hidden service
571    directory out of the changing subset of 6 nodes. If the request is
572    unsuccessful, Alice retries the other remaining responsible hidden service
573    directories in a random order. Alice relies on Bob to care about a potential
574    clock skew between the two by possibly storing two sets of descriptors (see
575    end of section 1.4).
577    Alice's OP opens a stream via Tor to the chosen v2 hidden service
578    directory. (She may re-use old circuits for this.) Over this stream,
579    Alice's OP makes an HTTP 'GET' request for the document
580    "/tor/rendezvous2/<z>", where z is replaced with the encoding of the
581    descriptor ID. The directory replies with a 404 HTTP response if it does
582    not recognize <z>, and otherwise returns Bob's most recently uploaded
583    service descriptor.
585 1.7. Alice's OP establishes a rendezvous point.
587    When Alice requests a connection to a given location-hidden service,
588    and Alice's OP does not have an established circuit to that service,
589    the OP builds a rendezvous circuit.  It does this by establishing
590    a circuit to a randomly chosen OR, and sending a
591    RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell to that OR.  The body of that cell
592    contains:
594         RC   Rendezvous cookie    [20 octets]
596    The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by
597    Alice's OP. Alice SHOULD choose a new rendezvous cookie for each new
598    connection attempt.
600    Upon receiving a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell, the OR associates
601    the RC with the circuit that sent it.  It replies to Alice with an empty
602    RELAY_COMMAND_RENDEZVOUS_ESTABLISHED cell to indicate success.
604    Alice's OP MUST NOT use the circuit which sent the cell for any purpose
605    other than rendezvous with the given location-hidden service.
607 1.8. Introduction: from Alice's OP to Introduction Point
609    Alice builds a separate circuit to one of Bob's chosen introduction
610    points, and sends it a RELAY_COMMAND_INTRODUCE1 cell containing:
612        Cleartext
613           PK_ID  Identifier for Bob's PK      [20 octets]
614        Encrypted to Bob's PK: (in the v0 intro protocol)
615           RP     Rendezvous point's nickname  [20 octets]
616           RC     Rendezvous cookie            [20 octets]
617           g^x    Diffie-Hellman data, part 1 [128 octets]
618         OR (in the v1 intro protocol)
619           VER    Version byte: set to 1.        [1 octet]
620           RP     Rendezvous point nick or ID  [42 octets]
621           RC     Rendezvous cookie            [20 octets]
622           g^x    Diffie-Hellman data, part 1 [128 octets]
623         OR (in the v2 intro protocol)
624           VER    Version byte: set to 2.        [1 octet]
625           IP     Rendezvous point's address    [4 octets]
626           PORT   Rendezvous point's OR port    [2 octets]
627           ID     Rendezvous point identity ID [20 octets]
628           KLEN   Length of onion key           [2 octets]
629           KEY    Rendezvous point onion key [KLEN octets]
630           RC     Rendezvous cookie            [20 octets]
631           g^x    Diffie-Hellman data, part 1 [128 octets]
632         OR (in the v3 intro protocol)
633           VER    Version byte: set to 3.        [1 octet]
634           AUTHT  The auth type that is used     [1 octet]
635           AUTHL  Length of auth data           [2 octets]
636           AUTHD  Auth data                     [variable]
637           TS     A timestamp                   [4 octets]
638           IP     Rendezvous point's address    [4 octets]
639           PORT   Rendezvous point's OR port    [2 octets]
640           ID     Rendezvous point identity ID [20 octets]
641           KLEN   Length of onion key           [2 octets]
642           KEY    Rendezvous point onion key [KLEN octets]
643           RC     Rendezvous cookie            [20 octets]
644           g^x    Diffie-Hellman data, part 1 [128 octets]
646    PK_ID is the hash of Bob's public key or the service key, depending on the
647    hidden service descriptor version. In case of a v0 descriptor, Alice's OP
648    uses Bob's public key. If Alice has downloaded a v2 descriptor, she uses
649    the contained public key ("service-key").
651    RP is NUL-padded and terminated. In version 0 of the intro protocol, RP
652    must contain a nickname. In version 1, it must contain EITHER a nickname or
653    an identity key digest that is encoded in hex and prefixed with a '$'.
655    The hybrid encryption to Bob's PK works just like the hybrid
656    encryption in CREATE cells (see tor-spec). Thus the payload of the
657    version 0 RELAY_COMMAND_INTRODUCE1 cell on the wire will contain
658    20+42+16+20+20+128=246 bytes, and the version 1 and version 2
659    introduction formats have other sizes.
661    Through Tor 0.2.0.6-alpha, clients only generated the v0 introduction
662    format, whereas hidden services have understood and accepted v0,
663    v1, and v2 since 0.1.1.x. As of Tor 0.2.0.7-alpha and 0.1.2.18,
664    clients switched to using the v2 intro format.
666 1.9. Introduction: From the Introduction Point to Bob's OP
668    If the Introduction Point recognizes PK_ID as a public key which has
669    established a circuit for introductions as in 1.2 above, it sends the body
670    of the cell in a new RELAY_COMMAND_INTRODUCE2 cell down the corresponding
671    circuit. (If the PK_ID is unrecognized, the RELAY_COMMAND_INTRODUCE1 cell is
672    discarded.)
674    After sending the RELAY_COMMAND_INTRODUCE2 cell to Bob, the OR replies to
675    Alice with an empty RELAY_COMMAND_INTRODUCE_ACK cell.  If no
676    RELAY_COMMAND_INTRODUCE2 cell can be sent, the OR replies to Alice with a
677    non-empty cell to indicate an error.  (The semantics of the cell body may be
678    determined later; the current implementation sends a single '1' byte on
679    failure.)
681    When Bob's OP receives the RELAY_COMMAND_INTRODUCE2 cell, it decrypts it
682    with the private key for the corresponding hidden service, and extracts the
683    rendezvous point's nickname, the rendezvous cookie, and the value of g^x
684    chosen by Alice.
686 1.10. Rendezvous
688    Bob's OP builds a new Tor circuit ending at Alice's chosen rendezvous
689    point, and sends a RELAY_COMMAND_RENDEZVOUS1 cell along this circuit,
690    containing:
691        RC       Rendezvous cookie  [20 octets]
692        g^y      Diffie-Hellman     [128 octets]
693        KH       Handshake digest   [20 octets]
695    (Bob's OP MUST NOT use this circuit for any other purpose.)
697    If the RP recognizes RC, it relays the rest of the cell down the
698    corresponding circuit in a RELAY_COMMAND_RENDEZVOUS2 cell, containing:
700        g^y      Diffie-Hellman     [128 octets]
701        KH       Handshake digest   [20 octets]
703    (If the RP does not recognize the RC, it discards the cell and
704    tears down the circuit.)
706    When Alice's OP receives a RELAY_COMMAND_RENDEZVOUS2 cell on a circuit which
707    has sent a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell but which has not yet
708    received a reply, it uses g^y and H(g^xy) to complete the handshake as in
709    the Tor circuit extend process: they establish a 60-octet string as
710        K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02])
711    and generate
712        KH = K[0..15]
713        Kf = K[16..31]
714        Kb = K[32..47]
716    Subsequently, the rendezvous point passes relay cells, unchanged, from
717    each of the two circuits to the other.  When Alice's OP sends
718    RELAY cells along the circuit, it first encrypts them with the
719    Kf, then with all of the keys for the ORs in Alice's side of the circuit;
720    and when Alice's OP receives RELAY cells from the circuit, it decrypts
721    them with the keys for the ORs in Alice's side of the circuit, then
722    decrypts them with Kb.  Bob's OP does the same, with Kf and Kb
723    interchanged.
725 1.11. Creating streams
727    To open TCP connections to Bob's location-hidden service, Alice's OP sends
728    a RELAY_COMMAND_BEGIN cell along the established circuit, using the special
729    address "", and a chosen port.  Bob's OP chooses a destination IP and
730    port, based on the configuration of the service connected to the circuit,
731    and opens a TCP stream.  From then on, Bob's OP treats the stream as an
732    ordinary exit connection.
733    [ Except he doesn't include addr in the connected cell or the end
734      cell. -RD]
736    Alice MAY send multiple RELAY_COMMAND_BEGIN cells along the circuit, to open
737    multiple streams to Bob.  Alice SHOULD NOT send RELAY_COMMAND_BEGIN cells
738    for any other address along her circuit to Bob; if she does, Bob MUST reject
739    them.
741 2. Authentication and authorization.
743    The rendezvous protocol as described in Section 1 provides a few options
744    for implementing client-side authorization. There are two steps in the
745    rendezvous protocol that can be used for performing client authorization:
746    when downloading and decrypting parts of the hidden service descriptor and
747    at Bob's Tor client before contacting the rendezvous point. A service
748    provider can restrict access to his service at these two points to
749    authorized clients only.
751    There are currently two authorization protocols specified that are
752    described in more detail below:
754     1. The first protocol allows a service provider to restrict access
755        to clients with a previously received secret key only, but does not
756        attempt to hide service activity from others.
758     2. The second protocol, albeit being feasible for a limited set of about
759        16 clients, performs client authorization and hides service activity
760        from everyone but the authorized clients.
762 2.1. Service with large-scale client authorization
764    The first client authorization protocol aims at performing access control
765    while consuming as few additional resources as possible. This is the "basic"
766    authorization protocol. A service provider should be able to permit access
767    to a large number of clients while denying access for everyone else.
768    However, the price for scalability is that the service won't be able to hide
769    its activity from unauthorized or formerly authorized clients.
771    The main idea of this protocol is to encrypt the introduction-point part
772    in hidden service descriptors to authorized clients using symmetric keys.
773    This ensures that nobody else but authorized clients can learn which
774    introduction points a service currently uses, nor can someone send a
775    valid INTRODUCE1 message without knowing the introduction key. Therefore,
776    a subsequent authorization at the introduction point is not required.
778    A service provider generates symmetric "descriptor cookies" for his
779    clients and distributes them outside of Tor. The suggested key size is
780    128 bits, so that descriptor cookies can be encoded in 22 base64 chars
781    (which can hold up to 22 * 5 = 132 bits, leaving 4 bits to encode the
782    authorization type (here: "0") and allow a client to distinguish this
783    authorization protocol from others like the one proposed below).
784    Typically, the contact information for a hidden service using this
785    authorization protocol looks like this:
787      v2cbb2l4lsnpio4q.onion Ll3X7Xgz9eHGKCCnlFH0uz
789    When generating a hidden service descriptor, the service encrypts the
790    introduction-point part with a single randomly generated symmetric
791    128-bit session key using AES-CTR as described for v2 hidden service
792    descriptors in rend-spec. Afterwards, the service encrypts the session
793    key to all descriptor cookies using AES. Authorized client should be able
794    to efficiently find the session key that is encrypted for him/her, so
795    that 4 octet long client ID are generated consisting of descriptor cookie
796    and initialization vector. Descriptors always contain a number of
797    encrypted session keys that is a multiple of 16 by adding fake entries.
798    Encrypted session keys are ordered by client IDs in order to conceal
799    addition or removal of authorized clients by the service provider.
801      ATYPE  Authorization type: set to 1.                      [1 octet]
802      ALEN   Number of clients := 1 + ((clients - 1) div 16)    [1 octet]
803    for each symmetric descriptor cookie:
804      ID     Client ID: H(descriptor cookie | IV)[:4]          [4 octets]
805      SKEY   Session key encrypted with descriptor cookie     [16 octets]
806    (end of client-specific part)
807      RND    Random data      [(15 - ((clients - 1) mod 16)) * 20 octets]
808      IV     AES initialization vector                        [16 octets]
809      IPOS   Intro points, encrypted with session key  [remaining octets]
811    An authorized client needs to configure Tor to use the descriptor cookie
812    when accessing the hidden service. Therefore, a user adds the contact
813    information that she received from the service provider to her torrc
814    file. Upon downloading a hidden service descriptor, Tor finds the
815    encrypted introduction-point part and attempts to decrypt it using the
816    configured descriptor cookie. (In the rare event of two or more client
817    IDs being equal a client tries to decrypt all of them.)
819    Upon sending the introduction, the client includes her descriptor cookie
820    as auth type "1" in the INTRODUCE2 cell that she sends to the service.
821    The hidden service checks whether the included descriptor cookie is
822    authorized to access the service and either responds to the introduction
823    request, or not.
825 2.2. Authorization for limited number of clients
827    A second, more sophisticated client authorization protocol goes the extra
828    mile of hiding service activity from unauthorized clients. This is the
829    "stealth" authorization protocol. With all else being equal to the preceding
830    authorization protocol, the second protocol publishes hidden service
831    descriptors for each user separately and gets along with encrypting the
832    introduction-point part of descriptors to a single client. This allows the
833    service to stop publishing descriptors for removed clients. As long as a
834    removed client cannot link descriptors issued for other clients to the
835    service, it cannot derive service activity any more. The downside of this
836    approach is limited scalability. Even though the distributed storage of
837    descriptors (cf. proposal 114) tackles the problem of limited scalability to
838    a certain extent, this protocol should not be used for services with more
839    than 16 clients. (In fact, Tor should refuse to advertise services for more
840    than this number of clients.)
842    A hidden service generates an asymmetric "client key" and a symmetric
843    "descriptor cookie" for each client. The client key is used as
844    replacement for the service's permanent key, so that the service uses a
845    different identity for each of his clients. The descriptor cookie is used
846    to store descriptors at changing directory nodes that are unpredictable
847    for anyone but service and client, to encrypt the introduction-point
848    part, and to be included in INTRODUCE2 cells. Once the service has
849    created client key and descriptor cookie, he tells them to the client
850    outside of Tor. The contact information string looks similar to the one
851    used by the preceding authorization protocol (with the only difference
852    that it has "1" encoded as auth-type in the remaining 4 of 132 bits
853    instead of "0" as before).
855    When creating a hidden service descriptor for an authorized client, the
856    hidden service uses the client key and descriptor cookie to compute
857    secret ID part and descriptor ID:
859      secret-id-part = H(time-period | descriptor-cookie | replica)
861      descriptor-id = H(client-key[:10] | secret-id-part)
863    The hidden service also replaces permanent-key in the descriptor with
864    client-key and encrypts introduction-points with the descriptor cookie.
866      ATYPE  Authorization type: set to 2.                         [1 octet]
867      IV     AES initialization vector                           [16 octets]
868      IPOS   Intro points, encr. with descriptor cookie   [remaining octets]
870    When uploading descriptors, the hidden service needs to make sure that
871    descriptors for different clients are not uploaded at the same time (cf.
872    Section 1.1) which is also a limiting factor for the number of clients.
874    When a client is requested to establish a connection to a hidden service
875    it looks up whether it has any authorization data configured for that
876    service. If the user has configured authorization data for authorization
877    protocol "2", the descriptor ID is determined as described in the last
878    paragraph. Upon receiving a descriptor, the client decrypts the
879    introduction-point part using its descriptor cookie. Further, the client
880    includes its descriptor cookie as auth-type "2" in INTRODUCE2 cells that
881    it sends to the service.
883 2.3. Hidden service configuration
885    A hidden service that is meant to perform client authorization adds a
886    new option HiddenServiceAuthorizeClient to its hidden service
887    configuration. This option contains the authorization type which is
888    either "basic" for the protocol described in 2.1 or "stealth" for the
889    protocol in 2.2 and a comma-separated list of human-readable client
890    names, so that Tor can create authorization data for these clients:
892      HiddenServiceAuthorizeClient auth-type client-name,client-name,...
894    If this option is configured, HiddenServiceVersion is automatically
895    reconfigured to contain only version numbers of 2 or higher. There is
896    a maximum of 512 client names for basic auth and a maximum of 16 for
897    stealth auth.
899    Tor stores all generated authorization data for the authorization
900    protocols described in Sections 2.1 and 2.2 in a new file using the
901    following file format:
903      "client-name" human-readable client identifier NL
904      "descriptor-cookie" 128-bit key ^= 22 base64 chars NL
906    If the authorization protocol of Section 2.2 is used, Tor also generates
907    and stores the following data:
909      "client-key" NL a public key in PEM format
911 2.4. Client configuration
913    Clients need to make their authorization data known to Tor using another
914    configuration option that contains a service name (mainly for the sake of
915    convenience), the service address, and the descriptor cookie that is
916    required to access a hidden service (the authorization protocol number is
917    encoded in the descriptor cookie):
919      HidServAuth service-name service-address descriptor-cookie
921 3. Hidden service directory operation
923    This section has been introduced with the v2 hidden service descriptor
924    format. It describes all operations of the v2 hidden service descriptor
925    fetching and propagation mechanism that are required for the protocol
926    described in section 1 to succeed with v2 hidden service descriptors.
928 3.1. Configuring as hidden service directory
930    Every onion router that has its directory port open can decide whether it
931    wants to store and serve hidden service descriptors. An onion router which
932    is configured as such includes the "hidden-service-dir" flag in its router
933    descriptors that it sends to directory authorities.
935    The directory authorities include a new flag "HSDir" for routers that
936    decided to provide storage for hidden service descriptors and that
937    have been running for at least 24 hours.
939 3.2. Accepting publish requests
941    Hidden service directory nodes accept publish requests for v2 hidden service
942    descriptors and store them to their local memory. (It is not necessary to
943    make descriptors persistent, because after restarting, the onion router
944    would not be accepted as a storing node anyway, because it has not been
945    running for at least 24 hours.) All requests and replies are formatted as
946    HTTP messages. Requests are initiated via BEGIN_DIR cells directed to
947    the router's directory port, and formatted as HTTP POST requests to the URL
948    "/tor/rendezvous2/publish" relative to the hidden service directory's root,
949    containing as its body a v2 service descriptor.
951    A hidden service directory node parses every received descriptor and only
952    stores it when it thinks that it is responsible for storing that descriptor
953    based on its own routing table. See section 1.4 for more information on how
954    to determine responsibility for a certain descriptor ID.
956 3.3. Processing fetch requests
958    Hidden service directory nodes process fetch requests for hidden service
959    descriptors by looking them up in their local memory. (They do not need to
960    determine if they are responsible for the passed ID, because it does no harm
961    if they deliver a descriptor for which they are not (any more) responsible.)
962    All requests and replies are formatted as HTTP messages. Requests are
963    initiated via BEGIN_DIR cells directed to the router's directory port,
964    and formatted as HTTP GET requests for the document "/tor/rendezvous2/<z>",
965    where z is replaced with the encoding of the descriptor ID.