130-v2-conn-protocol.txt 7.4 KB

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