doc/spec/proposals/130-v2-conn-protocol.txt

   1 Filename: 130-v2-conn-protocol.txt
   2 Title: Version 2 Tor connection protocol
   3 Version: $Revision$
   4 Last-Modified: $Date$
   5 Author: Nick Mathewson
   6 Created: 2007-10-25
   7 Status: Finished
   8
   9 Overview:
  10
  11   This proposal describes the significant changes to be made in the v2
  12   Tor connection protocol.
  13
  14   This proposal relates to other proposals as follows:
  15
  16     It refers to and supersedes:
  17        Proposal 124: Blocking resistant TLS certificate usage
  18     It refers to aspects of:
  19        Proposal 105: Version negotiation for the Tor protocol
  20
  21
  22   In summary, The Tor connection protocol has been in need of a redesign
  23   for a while.  This proposal describes how we can add to the Tor
  24   protocol:
  25
  26      - A new TLS handshake (to achieve blocking resistance without
  27        breaking backward compatibility)
  28      - Version negotiation (so that future connection protocol changes
  29        can happen without breaking compatibility)
  30      - The actual changes in the v2 Tor connection protocol.
  31
  32 Motivation:
  33
  34   For motivation, see proposal 124.
  35
  36 Proposal:
  37
  38 0. Terminology
  39
  40   The version of the Tor connection protocol implemented up to now is
  41   "version 1".  This proposal describes "version 2".
  42
  43   "Old" or "Older" versions of Tor are ones not aware that version 2
  44   of this protocol exists;
  45   "New" or "Newer" versions are ones that are.
  46
  47   The connection initiator is referred to below as the Client; the
  48   connection responder is referred to below as the Server.
  49
  50 1. The revised TLS handshake.
  51
  52   For motivation, see proposal 124.  This is a simplified version of the
  53   handshake that uses TLS's renegotiation capability in order to avoid
  54   some of the extraneous steps in proposal 124.
  55
  56   The Client connects to the Server and, as in ordinary TLS, sends a
  57   list of ciphers.  Older versions of Tor will send only ciphers from
  58   the list:
  59     TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  60     TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  61     SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  62     SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  63   Clients that support the revised handshake will send the recommended
  64   list of ciphers from proposal 124, in order to emulate the behavior of
  65   a web browser.
  66
  67   If the server notices that the list of ciphers contains only ciphers
  68   from this list, it proceeds with Tor's version 1 TLS handshake as
  69   documented in tor-spec.txt.
  70
  71   (The server may also notice cipher lists used by other implementations
  72   of the Tor protocol (in particular, the BouncyCastle default cipher
  73   list as used by some Java-based implementations), and whitelist them.)
  74
  75   On the other hand, if the server sees a list of ciphers that could not
  76   have been sent from an older implementation (because it includes other
  77   ciphers, and does not match any known-old list), the server sends a
  78   reply containing a single connection certificate, constructed as for
  79   the link certificate in the v1 Tor protocol.  The subject names in
  80   this certificate SHOULD NOT have any strings to identify them as
  81   coming from a Tor server.  The server does not ask the client for
  82   certificates.
  83
  84   Old Servers will (mostly) ignore the cipher list and respond as in the v1
  85   protocol, sending back a two-certificate chain.
  86
  87   After the Client gets a response from the server, it checks for the
  88   number of certificates it received.  If there are two certificates,
  89   the client assumes a V1 connection and proceeds as in tor-spec.txt.
  90   But if there is only one certificate, the client assumes a V2 or later
  91   protocol and continues.
  92
  93   At this point, the client has established a TLS connection with the
  94   server, but the parties have not been authenticated: the server hasn't
  95   sent its identity certificate, and the client hasn't sent any
  96   certificates at all.  To fix this, the client begins a TLS session
  97   renegotiation.  This time, the server continues with two certificates
  98   as usual, and asks for certificates so that the client will send
  99   certificates of its own.  Because the TLS connection has been
 100   established, all of this is encrypted.  (The certificate sent by the
 101   server in the renegotiated connection need not be the same that
 102   as sentin the original connection.)
 103
 104   The server MUST NOT write any data until the client has renegotiated.
 105
 106   Once the renegotiation is finished, the server and client check one
 107   another's certificates as in V1.  Now they are mutually authenticated.
 108
 109 1.1. Revised TLS handshake: implementation notes.
 110
 111   It isn't so easy to adjust server behavior based on the client's
 112   ciphersuite list.  Here's how we can do it using OpenSSL.  This is a
 113   bit of an abuse of the OpenSSL APIs, but it's the best we can do, and
 114   we won't have to do it forever.
 115
 116   We can use OpenSSL's SSL_set_info_callback() to register a function to
 117   be called when the state changes.  The type/state tuple of
 118      SSL_CB_ACCEPT_LOOP/SSL3_ST_SW_SRVR_HELLO_A
 119   happens when we have completely parsed the client hello, and are about
 120   to send a response.  From this callback, we can check the cipherlist
 121   and act accordingly:
 122
 123      * If the ciphersuite list indicates a v1 protocol, we set the
 124        verify mode to SSL_VERIFY_NONE with a callback (so we get
 125        certificates).
 126
 127      * If the ciphersuite list indicates a v2 protocol, we set the
 128        verify mode to SSL_VERIFY_NONE with no callback (so we get
 129        no certificates) and set the SSL_MODE_NO_AUTO_CHAIN flag (so that
 130        we send only 1 certificate in the response.
 131
 132   Once the handshake is done, the server clears the
 133   SSL_MODE_NO_AUTO_CHAIN flag and sets the callback as for the V1
 134   protocol.  It then starts reading.
 135
 136   The other problem to take care of is missing ciphers and OpenSSL's
 137   cipher sorting algorithms. The two main issues are a) OpenSSL doesn't
 138   support some of the default ciphers that Firefox advertises, and b)
 139   OpenSSL sorts the list of ciphers it offers in a different way than
 140   Firefox sorts them, so unless we fix that Tor will still look different
 141   than Firefox.
 142   [XXXX more on this.]
 143
 144
 145 1.2. Compatibility for clients using libraries less hackable than OpenSSL.
 146
 147   As discussed in proposal 105, servers advertise which protocol
 148   versions they support in their router descriptors.  Clients can simply
 149   behave as v1 clients when connecting to servers that do not support
 150   link version 2 or higher, and as v2 clients when connecting to servers
 151   that do support link version 2 or higher.
 152
 153   (Servers can't use this strategy because we do not assume that servers
 154   know one another's capabilities when connecting.)
 155
 156 2. Version negotiation.
 157
 158   Version negotiation proceeds as described in proposal 105, except as
 159   follows:
 160
 161    * Version negotiation only happens if the TLS handshake as described
 162      above completes.
 163
 164    * The TLS renegotiation must be finished before the client sends a
 165      VERSIONS cell; the server sends its VERSIONS cell in response.
 166
 167    * The VERSIONS cell uses the following variable-width format:
 168          Circuit  [2 octets; set to 0]
 169          Command  [1 octet; set to 7 for VERSIONS]
 170          Length   [2 octets; big-endian]
 171          Data     [Length bytes]
 172
 173      The Data in the cell is a series of big-endian two-byte integers.
 174
 175    * It is not allowed to negotiate V1 conections once the v2 protocol
 176      has been used.  If this happens, Tor instances should close the
 177      connection.
 178
 179 3. The rest of the "v2" protocol
 180
 181    Once a v2 protocol has been negotiated, NETINFO cells are exchanged
 182    as in proposal 105, and communications begin as per tor-spec.txt.
 183    Until NETINFO cells have been exchanged, the connection is not open.
 184
 185