path: root/rend-spec-v2.txt

                    Tor Rendezvous Specification

0. Overview and preliminaries

      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
      "OPTIONAL" in this document are to be interpreted as described in
      RFC 2119.

   Read
   https://svn.torproject.org/svn/projects/design-paper/tor-design.html#sec:rendezvous
   before you read this specification. It will make more sense.

   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 circuits to those
   introduction points, and tells them about his service.  To
   connect to Bob, Alice first builds a circuit to an OR to act as
   her "Rendezvous Point." She 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 a circuit to her
   RP, and tells it to connect him to Alice.  The RP joins their
   circuits together, and begins relaying cells.  Alice's 'BEGIN'
   cells are received directly by Bob's OP, which passes data to
   and from 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 and terminology
   as in "tor-spec.txt".  The service specified here also requires the
   existence of an onion routing network as specified in that file.

        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.

   An OP is (as defined elsewhere) an "Onion Proxy" or Tor client.

   An OR is (as defined elsewhere) an "Onion Router" or Tor server.

   An "Introduction point" is a Tor server chosen to be Bob's medium-term
   'meeting place'.  A "Rendezvous point" is a Tor server chosen by Alice to
   be a short-term communication relay between her and Bob.  All Tor servers
   potentially act as introduction and rendezvous points.

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 a long-term keypair.

   3. Bob's OP->Introduction point via Tor: [introduction setup]
        "This public key is (currently) associated to me."

   4. Bob's OP->directory service via Tor: publishes Bob's service descriptor
      [advertisement]
        "Meet public-key X at introduction point A, B, or C." (signed)

   5. Out of band, Alice receives a z.onion:port address.
      She opens a SOCKS connection to her OP, and requests z.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 1]

  11. The Rendezvous point forwards Bob's confirmation to Alice's OP.
      [Rendezvous 2]

  12. Alice's OP sends begin cells to Bob's OP.  [Connection]

0.3. Constants and new cell types

  Relay cell types

      32 -- RELAY_COMMAND_ESTABLISH_INTRO
      33 -- RELAY_COMMAND_ESTABLISH_RENDEZVOUS
      34 -- RELAY_COMMAND_INTRODUCE1
      35 -- RELAY_COMMAND_INTRODUCE2
      36 -- RELAY_COMMAND_RENDEZVOUS1
      37 -- RELAY_COMMAND_RENDEZVOUS2
      38 -- RELAY_COMMAND_INTRO_ESTABLISHED
      39 -- RELAY_COMMAND_RENDEZVOUS_ESTABLISHED
      40 -- RELAY_COMMAND_INTRODUCE_ACK

0.4. Version overview

   There are several parts in the hidden service protocol that have
   changed over time, each of them having its own version number, whereas
   other parts remained the same. The following list of potentially
   versioned protocol parts should help reduce some confusion:

   - Hidden service descriptor: the binary-based v0 was the default for a
     long time, and an ASCII-based v2 has been added by proposal 114. The
     v0 descriptor format has been deprecated in 0.2.2.1-alpha. See 1.3.

   - Hidden service descriptor propagation mechanism: currently related to
     the hidden service descriptor version -- v0 publishes to the original
     hs directory authorities, whereas v2 publishes to a rotating subset
     of relays with the "HSDir" flag; see 1.4 and 1.6.

   - Introduction protocol for how to generate an introduction cell:
     v0 specified a nickname for the rendezvous point and assumed the
     relay would know about it, whereas v2 now specifies IP address,
     port, and onion key so the relay doesn't need to already recognize
     it. See 1.8.

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 establishes his introduction points.

   The first time the OP provides an advertised service, it generates
   a public/private keypair (stored locally).

   The OP chooses a small number of Tor servers as introduction points.
   The OP establishes a new introduction circuit to each introduction
   point.  These circuits MUST NOT be used for anything but hidden service
   introduction.  To establish the introduction, Bob sends a
   RELAY_COMMAND_ESTABLISH_INTRO cell, containing:

        KL   Key length                             [2 octets]
        PK   Bob's public key or service key        [KL octets]
        HS   Hash of session info                   [20 octets]
        SIG  Signature of above information         [variable]

   KL is the length of PK, in octets.

   To prevent replay attacks, the HS field contains a SHA-1 hash based on the
   shared secret KH between Bob's OP and the introduction point, as
   follows:

       HS = H(KH | "INTRODUCE")

   That is:

       HS = H(KH | [49 4E 54 52 4F 44 55 43 45])

   (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)

   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.  On success, the OR sends Bob a
   RELAY_COMMAND_INTRO_ESTABLISHED cell with an empty payload.

   Bob's OP uses either Bob's public key or a freshly generated, single-use
   service key in the RELAY_COMMAND_ESTABLISH_INTRO cell, depending on the
   configured hidden service descriptor version.  The public key is used for
   v0 descriptors, the service key for v2 descriptors.  In the latter case, the
   service keys of all introduction points are included in the v2 hidden
   service descriptor together with the other introduction point information.
   The reason is that the introduction point does not need to and therefore
   should not know for which hidden service it works, so as to prevent it from
   tracking the hidden service's activity.  If the hidden service is configured
   to publish both v0 and v2 descriptors, two separate sets of introduction
   points are established.

1.3. Bob's OP generates service descriptors.

   For versions before 0.2.2.1-alpha, Bob's OP periodically generates and
   publishes a descriptor of type "V0".

   The "V0" descriptor contains:

         KL    Key length                            [2 octets]
         PK    Bob's public key                      [KL octets]
         TS    A timestamp                           [4 octets]
         NI    Number of introduction points         [2 octets]
         Ipt   A list of NUL-terminated ORs          [variable]
         SIG   Signature of above fields             [variable]

   TS is the number of seconds elapsed since Jan 1, 1970.

   The members of Ipt may be either (a) nicknames, or (b) identity key
   digests, encoded in hex, and prefixed with a '$'.  Clients must
   accept both forms. Services must only generate the second form.
   Once 0.0.9.x is obsoleted, we can drop the first form.

   [It's ok for Bob to advertise 0 introduction points. He might want
    to do that if he previously advertised some introduction points,
    and now he doesn't have any. -RD]

   Beginning with 0.2.0.10-alpha, Bob's OP encodes "V2" descriptors in
   addition to (or instead of) "V0" descriptors. The format of a "V2"
   descriptor is as follows:

     "rendezvous-service-descriptor" SP descriptor-id NL

       [At start, exactly once]
       [No extra arguments]

       Indicates the beginning of the descriptor. "descriptor-id" is a
       periodically changing identifier of 160 bits formatted as 32 base32
       chars that is calculated by the hidden service and its clients. The
       "descriptor-id" is calculated by performing the following operation:

         descriptor-id =
             H(permanent-id | H(time-period | descriptor-cookie | replica))

       "permanent-id" is the permanent identifier of the hidden service,
       consisting of 80 bits. It can be calculated by computing the hash value
       of the public hidden service key and truncating after the first 80 bits:

         permanent-id = H(public-key)[:10]

       Note: If Bob's OP has "stealth" authorization enabled (see Section 2.2),
       it uses the client key in place of the public hidden service key.

       "H(time-period | descriptor-cookie | replica)" is the (possibly
       secret) id part that is necessary to verify that the hidden service is
       the true originator of this descriptor and that is therefore contained
       in the descriptor, too. The descriptor ID can only be created by the
       hidden service and its clients, but the "signature" below can only be
       created by the service.

       "time-period" changes periodically as a function of time and
       "permanent-id". The current value for "time-period" can be calculated
       using the following formula:

         time-period = (current-time + permanent-id-byte * 86400 / 256)
                         / 86400

       "current-time" contains the current system time in seconds since
       1970-01-01 00:00, e.g. 1188241957. "permanent-id-byte" is the first
       (unsigned) byte of the permanent identifier (which is in network
       order), e.g. 143. Adding the product of "permanent-id-byte" and
       86400 (seconds per day), divided by 256, prevents "time-period" from
       changing for all descriptors at the same time of the day. The result
       of the overall operation is a (network-ordered) 32-bit integer, e.g.
       13753 or 0x000035B9 with the example values given above.

       "descriptor-cookie" is an optional secret password of 128 bits that
       is shared between the hidden service provider and its clients. If the
       descriptor-cookie is left out, the input to the hash function is 128
       bits shorter.  [No extra arguments]

       "replica" denotes the number of the replica. A service publishes
       multiple descriptors with different descriptor IDs in order to
       distribute them to different places on the ring.

     "version" SP version-number NL

       [Exactly once]
       [No extra arguments]

       The version number of this descriptor's format. Version numbers are a
       positive integer.

     "permanent-key" NL a public key in PEM format

       [Exactly once]
       [No extra arguments]

       The public key of the hidden service which is required to verify the
       "descriptor-id" and the "signature".

     "secret-id-part" SP secret-id-part NL

       [Exactly once]
       [No extra arguments]

       The result of the following operation as explained above, formatted as
       32 base32 chars. Using this secret id part, everyone can verify that
       the signed descriptor belongs to "descriptor-id".

         secret-id-part = H(time-period | descriptor-cookie | replica)

     "publication-time" SP YYYY-MM-DD HH:MM:SS NL

       [Exactly once]

       A timestamp when this descriptor has been created.  It should be
       rounded down to the nearest hour.

     "protocol-versions" SP version-string NL

       [Exactly once]
       [No extra arguments]

       A comma-separated list of recognized and permitted version numbers
       for use in INTRODUCE cells; these versions are described in section
       1.8 below. Version numbers are positive integers.

     "introduction-points" NL encrypted-string

       [At most once]
       [No extra arguments]

       A list of introduction points. If the optional "descriptor-cookie" is
       used, this list is encrypted with AES in CTR mode with a random
       initialization vector of 128 bits that is written to
       the beginning of the encrypted string, and the "descriptor-cookie" as
       secret key of 128 bits length.

       The string containing the introduction point data (either encrypted
       or not) is encoded in base64, and surrounded with
       "-----BEGIN MESSAGE-----" and "-----END MESSAGE-----".

       A maximum of 10 introduction point entries may follow, each containing
       the following data:

         "introduction-point" SP identifier NL

           [At start, exactly once]
           [No extra arguments]

           The identifier of this introduction point: the base32 encoded
           hash of this introduction point's identity key.

         "ip-address" SP ip4 NL

           [Exactly once]
           [No extra arguments]

           The IP address of this introduction point.

         "onion-port" SP port NL

           [Exactly once]
           [No extra arguments]

           The TCP port on which the introduction point is listening for
           incoming onion requests.

         "onion-key" NL a public key in PEM format

           [Exactly once]
           [No extra arguments]

           The public key that can be used to encrypt messages to this
           introduction point.

         "service-key" NL a public key in PEM format

           [Exactly once]
           [No extra arguments]

           The public key that can be used to encrypt messages to the hidden
           service.

         "intro-authentication" auth-type auth-data NL

           [Any number]

           The introduction-point-specific authentication data can be used
           to perform client authentication. This data depends on the
           selected introduction point as opposed to "service-authentication"
           above. The format of auth-data (base64-encoded or PEM format)
           depends on auth-type. See section 2 of this document for details
           on auth mechanisms.

        (This ends the fields in the encrypted portion of the descriptor.)

       [It's ok for Bob to advertise 0 introduction points. He might want
        to do that if he previously advertised some introduction points,
        and now he doesn't have any. -RD]

     "signature" NL signature-string

       [At end, exactly once]
       [No extra arguments]

       A signature of all fields above including '"signature" NL' with
       the private key of the hidden service.

1.3.1. Other descriptor formats we don't use.

   Support for the V0 descriptor format was dropped in 0.2.2.0-alpha-dev:

         KL    Key length                            [2 octets]
         PK    Bob's public key                      [KL octets]
         TS    A timestamp                           [4 octets]
         NI    Number of introduction points         [2 octets]
         Ipt   A list of NUL-terminated ORs          [variable]
         SIG   Signature of above fields             [variable]

   KL is the length of PK, in octets.
   TS is the number of seconds elapsed since Jan 1, 1970.

   The members of Ipt may be either (a) nicknames, or (b) identity key
   digests, encoded in hex, and prefixed with a '$'.

   The V1 descriptor format was understood and accepted from
   0.1.1.5-alpha-cvs to 0.2.0.6-alpha-dev, but no Tors generated it and
   it was removed:

         V     Format byte: set to 255               [1 octet]
         V     Version byte: set to 1                [1 octet]
         KL    Key length                            [2 octets]
         PK    Bob's public key                      [KL octets]
         TS    A timestamp                           [4 octets]
         PROTO Protocol versions: bitmask            [2 octets]
         NI    Number of introduction points         [2 octets]
         For each introduction point: (as in INTRODUCE2 cells)
             IP     Introduction point's address     [4 octets]
             PORT   Introduction point's OR port     [2 octets]
             ID     Introduction point identity ID   [20 octets]
             KLEN   Length of onion key              [2 octets]
             KEY    Introduction point onion key     [KLEN octets]
         SIG   Signature of above fields             [variable]

   A hypothetical "V1" descriptor, that has never been used but might
   be useful for historical reasons, contains:

         V     Format byte: set to 255               [1 octet]
         V     Version byte: set to 1                [1 octet]
         KL    Key length                            [2 octets]
         PK    Bob's public key                      [KL octets]
         TS    A timestamp                           [4 octets]
         PROTO Rendezvous protocol versions: bitmask [2 octets]
         NA    Number of auth mechanisms accepted    [1 octet]
         For each auth mechanism:
             AUTHT  The auth type that is supported  [2 octets]
             AUTHL  Length of auth data              [1 octet]
             AUTHD  Auth d