proposals/xxx-new-create-and-extend-cells.txt

   1 Filename: xxx-new-create-and-extend-cells.txt
   2 Title: Adding new, extensible CREATE, EXTEND, and related cells
   3 Author: Robert Ransom
   4 Created: 2010-12-27
   5 Status: Open
   6
   7 Overview and Motivation:
   8
   9   In Tor's current circuit protocol, every field, including the 'onion
  10   skin', in the EXTEND relay cell has a fixed meaning and length.
  11   This prevents us from extending the current EXTEND cell to support
  12   IPv6 relays, efficient UDP-based link protocols, larger 'onion
  13   keys', new circuit-extension handshake protocols, or larger
  14   identity-key fingerprints.  We will need to support all of these
  15   extensions in the near future.  This proposal specifies a
  16   replacement EXTEND2 cell and related cells that provide more room
  17   for future extension.
  18
  19 Design:
  20
  21   FIXME - allocate command ID numbers (non-RELAY commands for CREATE2 and
  22   CREATED2; RELAY commands for EXTEND2 and EXTENDED2)
  23
  24   The CREATE2 cell contains the following payload:
  25
  26         Handshake type                        [2 bytes]
  27         Handshake data length                 [2 bytes]
  28         Handshake data                        [variable]
  29
  30   The relay payload for an EXTEND2 relay cell contains the following
  31   payload:
  32
  33         Number of link specifiers             [1 byte]
  34            N times:
  35             Link specifier type               [1 byte]
  36             Link specifier length             [1 byte]
  37             Link specifier                    [variable]
  38         Handshake type                        [2 bytes]
  39         Handshake data length                 [2 bytes]
  40         Handshake data                        [variable]
  41
  42   The CREATED2 cell and EXTENDED2 relay cell both contain the following
  43   payload:
  44
  45         Handshake data length                 [2 bytes]
  46         Handshake data                        [variable]
  47
  48   All four cell types are padded to 512-byte cells.
  49
  50   When a relay X receives an EXTEND2 relay cell:
  51
  52   * X finds or opens a link to the relay Y using the link target
  53     specifiers in the EXTEND2 relay cell; if X fails to open a link, it
  54     replies with a TRUNCATED relay cell. (FIXME: what do we do now?)
  55
  56   * X copies the handshake type and data into a CREATE2 cell and sends
  57     it along the link to Y.
  58
  59   * If the handshake data is valid, Y replies by sending a CREATED2
  60     cell along the link to X; otherwise, Y replies with a TRUNCATED
  61     relay cell. (XXX: we currently use a DESTROY cell?)
  62
  63   * X copies the contents of the CREATED2 cell into an EXTENDED2 relay
  64     cell and sends it along the circuit to the OP.
  65
  66
  67 Link target specifiers:
  68
  69   The list of link target specifiers must include at least one address and
  70   at least one identity fingerprint, in a format that the extending node is
  71   known to recognize.
  72
  73   The extending node MUST NOT accept the connection unless at least one
  74   identity matches, and should follow the current rules for making sure that
  75   addresses match.
  76
  77   [00] TLS-over-TCP, IPv4 address
  78        A four-byte IPv4 address plus two-byte ORPort
  79   [01] TLS-over-TCP, IPv6 address
  80        A sixteen-byte IPv6 address plus two-byte ORPort
  81   [02] Legacy identity
  82        A 20-byte SHA1 identity fingerprint. At most one may be listed.
  83
  84   As always, values are sent in network (big-endian) order.
  85
  86 Legacy handshake type:
  87
  88   The current "onionskin" handshake type is defined to be handshake type
  89   [00 00], or "legacy".
  90
  91   The first (client->relay) message in a handshake of type “legacy”
  92   contains the following data:
  93
  94         ‘Onion skin’ (as in CREATE cell)      [DH_LEN+KEY_LEN+PK_PAD_LEN bytes]
  95
  96   This value is generated and processed as sections 5.1 and 5.2 of
  97   tor-spec.txt specify for the current CREATE cell.
  98
  99   The second (relay->client) message in a handshake of type “legacy”
 100   contains the following data:
 101
 102         Relay DH public key                   [DH_LEN bytes]
 103         KH (see section 5.2 of tor-spec.txt)  [HASH_LEN bytes]
 104
 105   These values are generated and processed as sections 5.1 and 5.2 of
 106   tor-spec.txt specify for the current CREATED cell.
 107
 108   After successfully completing a handshake of type “legacy”, the
 109   client and relay use the current relay cryptography protocol.
 110
 111 Bugs:
 112
 113   This specification does not accommodate:
 114
 115   * circuit-extension handshakes requiring more than one round
 116
 117     No circuit-extension handshake should ever require more than one
 118     round (i.e. more than one message from the client and one reply
 119     from the relay).  We can easily extend the protocol to handle
 120     this, but we will never need to.
 121
 122   * circuit-extension handshakes in which either message cannot fit in
 123     a single 512-byte cell along with the other required fields
 124
 125     This can be handled by specifying a dummy handshake type whose
 126     data (sent from the client) consists of another handshake type and
 127     the beginning of the data required by that handshake type, and
 128     then using several (newly defined) HANDSHAKE_COMPLETION relay
 129     cells sent in each direction to transport the remaining handshake
 130     data.
 131
 132     The specification of a HANDSHAKE_COMPLETION relay cell and its
 133     associated dummy handshake type can safely be postponed until we
 134     develop a circuit-extension handshake protocol that would require
 135     it.
 136
 137   * link target specifiers that cause EXTEND2 cells to exceed 512
 138     bytes
 139
 140     This can be handled by specifying a LONG_COMMAND relay cell type
 141     that can be used to transport a large ‘virtual cell’ in multiple
 142     512-byte cells.
 143
 144     The specification of a LONG_COMMAND relay cell can safely be
 145     postponed until we develop a link target specifier, a RELAY_BEGIN2
 146     relay cell and stream target specifier, or some other relay cell
 147     type that would require it.
 148
 149