attic/text_formats/ext-orport-spec.txt

   1              Extended ORPort for pluggable transports
   2                  George Kadianakis, Nick Mathewson
   3
   4 Table of Contents
   5
   6     1. Overview
   7     2. Establishing a connection and authenticating.
   8         2.1. Authentication type: SAFE_COOKIE
   9             2.1.2. Cookie-file format
  10             2.1.3.  SAFE_COOKIE Protocol specification
  11     3. The extended ORPort protocol
  12         3.1. Protocol
  13         3.2. Command descriptions
  14             3.2.1. USERADDR
  15             3.2.2. TRANSPORT
  16     4. Security Considerations
  17
  18 1. Overview
  19
  20   This document describes the "Extended ORPort" protocol, a wrapper
  21   around Tor's ordinary ORPort protocol for use by bridges that
  22   support pluggable transports.  It provides a way for server-side PTs
  23   and bridges to exchange additional information before beginning
  24   the actual OR connection.
  25
  26   See `tor-spec.txt` for information on the regular OR protocol, and
  27   `pt-spec.txt` for information on pluggable transports.
  28
  29   This protocol was originally proposed in proposal 196, and
  30   extended with authentication in proposal 217.
  31
  32 2. Establishing a connection and authenticating.
  33
  34   When a client (that is to say, a server-side pluggable transport)
  35   connects to an Extended ORPort, the server sends:
  36
  37     AuthTypes                                   [variable]
  38     EndAuthTypes                                [1 octet]
  39
  40   Where,
  41
  42   + AuthTypes are the authentication schemes that the server supports
  43     for this session. They are multiple concatenated 1-octet values that
  44     take values from 1 to 255.
  45   + EndAuthTypes is the special value 0.
  46
  47   The client reads the list of supported authentication schemes,
  48   chooses one, and sends it back:
  49
  50     AuthType                                    [1 octet]
  51
  52   Where,
  53
  54   + AuthType is the authentication scheme that the client wants to use
  55     for this session. A valid authentication type takes values from 1 to
  56     255. A value of 0 means that the client did not like the
  57     authentication types offered by the server.
  58
  59   If the client sent an AuthType of value 0, or an AuthType that the
  60   server does not support, the server MUST close the connection.
  61
  62 2.1. Authentication type: SAFE_COOKIE
  63
  64   We define one authentication type: SAFE_COOKIE.  Its AuthType
  65   value is 1.  It is based on the client proving to the bridge that
  66   it can access a given "cookie" file on disk.  The purpose of
  67   authentication is to defend against cross-protocol attacks.
  68
  69   If the Extended ORPort is enabled, Tor should regenerate the cookie
  70   file on startup and store it in
  71   $DataDirectory/extended_orport_auth_cookie.
  72
  73   The location of the cookie can be overridden by using the
  74   configuration file parameter ExtORPortCookieAuthFile, which is
  75   defined as:
  76
  77     ExtORPortCookieAuthFile <path>
  78
  79   where <path> is a filesystem path.
  80
  81 2.1.2. Cookie-file format
  82
  83   The format of the cookie-file is:
  84
  85      StaticHeader                                [32 octets]
  86      Cookie                                      [32 octets]
  87
  88   Where,
  89   + StaticHeader is the following string:
  90     "! Extended ORPort Auth Cookie !\x0a"
  91   + Cookie is the shared-secret. During the SAFE_COOKIE protocol, the
  92     cookie is called CookieString.
  93
  94   Extended ORPort clients MUST make sure that the StaticHeader is
  95   present in the cookie file, before proceeding with the
  96   authentication protocol.
  97
  98 2.1.3.  SAFE_COOKIE Protocol specification
  99
 100
 101   A client that performs the SAFE_COOKIE handshake begins by sending:
 102
 103      ClientNonce                                 [32 octets]
 104
 105   Where,
 106   + ClientNonce is 32 octets of random data.
 107
 108   Then, the server replies with:
 109
 110      ServerHash                                  [32 octets]
 111      ServerNonce                                 [32 octets]
 112
 113   Where,
 114   + ServerHash is computed as:
 115       HMAC-SHA256(CookieString,
 116         "ExtORPort authentication server-to-client hash" | ClientNonce | ServerNonce)
 117   + ServerNonce is 32 random octets.
 118
 119   Upon receiving that data, the client computes ServerHash, and
 120   validates it against the ServerHash provided by the server.
 121
 122   If the server-provided ServerHash is invalid, the client MUST
 123   terminate the connection.
 124
 125   Otherwise the client replies with:
 126
 127      ClientHash                                  [32 octets]
 128
 129   Where,
 130   + ClientHash is computed as:
 131       HMAC-SHA256(CookieString,
 132         "ExtORPort authentication client-to-server hash" | ClientNonce | ServerNonce)
 133
 134   Upon receiving that data, the server computes ClientHash, and
 135   validates it against the ClientHash provided by the client.
 136
 137   Finally, the server replies with:
 138
 139      Status                                      [1 octet]
 140
 141   Where,
 142   + Status is 1 if the authentication was successful. If the
 143     authentication failed, Status is 0.
 144
 145 3. The extended ORPort protocol
 146
 147   Once a connection is established and authenticated, the parties
 148   communicate with the protocol described here.
 149
 150 3.1. Protocol
 151
 152   The extended server port protocol is as follows:
 153
 154      COMMAND [2 bytes, big-endian]
 155      BODYLEN [2 bytes, big-endian]
 156      BODY [BODYLEN bytes]
 157
 158      Commands sent from the transport proxy to the bridge are:
 159
 160      [0x0000] DONE: There is no more information to give. The next
 161        bytes sent by the transport will be those tunneled over it.
 162        (body ignored)
 163
 164      [0x0001] USERADDR: an address:port string that represents the
 165        client's address.
 166
 167      [0x0002] TRANSPORT: a string of the name of the pluggable
 168        transport currently in effect on the connection.
 169
 170      Replies sent from tor to the proxy are:
 171
 172      [0x1000] OKAY: Send the user's traffic. (body ignored)
 173
 174      [0x1001] DENY: Tor would prefer not to get more traffic from
 175        this address for a while. (body ignored)
 176
 177      [0x1002] CONTROL: (Not used)
 178
 179   Parties MUST ignore command codes that they do not understand.
 180
 181   If the server receives a recognized command that does not parse, it
 182   MUST close the connection to the client.
 183
 184 3.2. Command descriptions
 185
 186 3.2.1. USERADDR
 187
 188   An ASCII string holding the TCP/IP address of the client of the
 189   pluggable transport proxy. A Tor bridge SHOULD use that address to
 190   collect statistics about its clients.  Recognized formats are:
 191     1.2.3.4:5678
 192     [1:2::3:4]:5678
 193
 194   (Current Tor versions may accept other formats, but this is a bug:
 195   transports MUST NOT send them.)
 196
 197   The string MUST not be NUL-terminated.
 198
 199 3.2.2. TRANSPORT
 200
 201   An ASCII string holding the name of the pluggable transport used by
 202   the client of the pluggable transport proxy. A Tor bridge that
 203   supports multiple transports SHOULD use that information to collect
 204   statistics about the popularity of individual pluggable transports.
 205
 206   The string MUST not be NUL-terminated.
 207
 208   Pluggable transport names are C-identifiers and Tor MUST check them
 209   for correctness.
 210
 211 4. Security Considerations
 212
 213   Extended ORPort or TransportControlPort do _not_ provide link
 214   confidentiality, authentication or integrity. Sensitive data, like
 215   cryptographic material, should not be transferred through them.
 216
 217   An attacker with superuser access is able to sniff network traffic,
 218   and capture TransportControlPort identifiers and any data passed
 219   through those ports.
 220
 221   Tor SHOULD issue a warning if the bridge operator tries to bind
 222   Extended ORPort to a non-localhost address.
 223
 224   Pluggable transport proxies SHOULD issue a warning if they are
 225   instructed to connect to a non-localhost Extended ORPort.
 226