1 files changed, 254 insertions, 0 deletions
diff --git a/spec/ext-orport-spec.md b/spec/ext-orport-spec.md
new file mode 100644
index 0000000..1341630
--- /dev/null
+++ b/spec/ext-orport-spec.md
@@ -0,0 +1,254 @@
+# Extended ORPort for pluggable transports
+
+```text
+               George Kadianakis, Nick Mathewson
+```
+
+<a id="ext-orport-spec.txt-1"></a>
+
+## Overview
+
+This document describes the "Extended ORPort" protocol, a wrapper
+around Tor's ordinary ORPort protocol for use by bridges that
+support pluggable transports.  It provides a way for server-side PTs
+and bridges to exchange additional information before beginning
+the actual OR connection.
+
+See `tor-spec.txt` for information on the regular OR protocol, and
+`pt-spec.txt` for information on pluggable transports.
+
+This protocol was originally proposed in proposal 196, and
+extended with authentication in proposal 217.
+
+<a id="ext-orport-spec.txt-2"></a>
+
+## Establishing a connection and authenticating { #establishing }
+
+When a client (that is to say, a server-side pluggable transport)
+connects to an Extended ORPort, the server sends:
+
+```text
+    AuthTypes                                   [variable]
+    EndAuthTypes                                [1 octet]
+
+  Where,
+
+  + AuthTypes are the authentication schemes that the server supports
+    for this session. They are multiple concatenated 1-octet values that
+    take values from 1 to 255.
+  + EndAuthTypes is the special value 0.
+```
+
+The client reads the list of supported authentication schemes,
+chooses one, and sends it back:
+
+AuthType                                    \[1 octet\]
+
+Where,
+
+```text
+  + AuthType is the authentication scheme that the client wants to use
+    for this session. A valid authentication type takes values from 1 to
+    255. A value of 0 means that the client did not like the
+    authentication types offered by the server.
+```
+
+If the client sent an AuthType of value 0, or an AuthType that the
+server does not support, the server MUST close the connection.
+
+<a id="ext-orport-spec.txt-2.1"></a>
+
+### Authentication type: SAFE_COOKIE { #SAFE_COOKIE }
+
+We define one authentication type: SAFE_COOKIE.  Its AuthType
+value is 1.  It is based on the client proving to the bridge that
+it can access a given "cookie" file on disk.  The purpose of
+authentication is to defend against cross-protocol attacks.
+
+If the Extended ORPort is enabled, Tor should regenerate the cookie
+file on startup and store it in
+$DataDirectory/extended_orport_auth_cookie.
+
+The location of the cookie can be overridden by using the
+configuration file parameter ExtORPortCookieAuthFile, which is
+defined as:
+
+`ExtORPortCookieAuthFile <path>`
+
+where `<path>` is a filesystem path.
+
+<a id="ext-orport-spec.txt-2.1.2"></a>
+
+#### Cookie-file format { #SAFE_COOKIE_file }
+
+The format of the cookie-file is:
+
+```text
+     StaticHeader                                [32 octets]
+     Cookie                                      [32 octets]
+
+  Where,
+  + StaticHeader is the following string:
+    "! Extended ORPort Auth Cookie !\x0a"
+  + Cookie is the shared-secret. During the SAFE_COOKIE protocol, the
+    cookie is called CookieString.
+```
+
+Extended ORPort clients MUST make sure that the StaticHeader is
+present in the cookie file, before proceeding with the
+authentication protocol.
+
+<a id="ext-orport-spec.txt-2.1.3"></a>
+
+#### SAFE_COOKIE Protocol specification { #SAFE_COOKIE_spec }
+
+A client that performs the SAFE_COOKIE handshake begins by sending:
+
+```text
+ClientNonce                                  [32 octets]
+```
+
+Where,
+
+- ClientNonce is 32 octets of random data.
+
+Then, the server replies with:
+
+```text
+     ServerHash                                  [32 octets]
+     ServerNonce                                 [32 octets]
+
+  Where,
+  + ServerHash is computed as:
+      HMAC-SHA256(CookieString,
+        "ExtORPort authentication server-to-client hash" | ClientNonce | ServerNonce)
+  + ServerNonce is 32 random octets.
+```
+
+Upon receiving that data, the client computes ServerHash, and
+validates it against the ServerHash provided by the server.
+
+If the server-provided ServerHash is invalid, the client MUST
+terminate the connection.
+
+Otherwise the client replies with:
+
+```text
+ClientHash                                  [32 octets]
+
+  Where,
+  + ClientHash is computed as:
+      HMAC-SHA256(CookieString,
+        "ExtORPort authentication client-to-server hash" | ClientNonce | ServerNonce)
+```
+
+Upon receiving that data, the server computes ClientHash, and
+validates it against the ClientHash provided by the client.
+
+Finally, the server replies with:
+
+Status                                      \[1 octet\]
+
+```text
+  Where,
+  + Status is 1 if the authentication was successful. If the
+    authentication failed, Status is 0.
+```
+
+<a id="ext-orport-spec.txt-3"></a>
+
+## The extended ORPort protocol { #ext_orport_protocol}
+
+Once a connection is established and authenticated, the parties
+communicate with the protocol described here.
+
+<a id="ext-orport-spec.txt-3.1"></a>
+
+### Protocol
+
+The extended server port protocol is as follows:
+
+```text
+     COMMAND [2 bytes, big-endian]
+     BODYLEN [2 bytes, big-endian]
+     BODY [BODYLEN bytes]
+
+     Commands sent from the transport proxy to the bridge are:
+
+     [0x0000] DONE: There is no more information to give. The next
+       bytes sent by the transport will be those tunneled over it.
+       (body ignored)
+
+     [0x0001] USERADDR: an address:port string that represents the
+       client's address.
+
+     [0x0002] TRANSPORT: a string of the name of the pluggable
+       transport currently in effect on the connection.
+
+     Replies sent from tor to the proxy are:
+
+     [0x1000] OKAY: Send the user's traffic. (body ignored)
+
+     [0x1001] DENY: Tor would prefer not to get more traffic from
+       this address for a while. (body ignored)
+
+     [0x1002] CONTROL: (Not used)
+
+  Parties MUST ignore command codes that they do not understand.
+```
+
+If the server receives a recognized command that does not parse, it
+MUST close the connection to the client.
+
+<a id="ext-orport-spec.txt-3.2"></a>
+
+### Command descriptions { #ext-orport-commands}
+
+<a id="ext-orport-spec.txt-3.2.1"></a>
+
+#### USERADDR
+
+```text
+  An ASCII string holding the TCP/IP address of the client of the
+  pluggable transport proxy. A Tor bridge SHOULD use that address to
+  collect statistics about its clients.  Recognized formats are:
+    1.2.3.4:5678
+    [1:2::3:4]:5678
+```
+
+(Current Tor versions may accept other formats, but this is a bug:
+transports MUST NOT send them.)
+
+The string MUST not be NUL-terminated.
+
+<a id="ext-orport-spec.txt-3.2.2"></a>
+
+#### TRANSPORT
+
+An ASCII string holding the name of the pluggable transport used by
+the client of the pluggable transport proxy. A Tor bridge that
+supports multiple transports SHOULD use that information to collect
+statistics about the popularity of individual pluggable transports.
+
+The string MUST not be NUL-terminated.
+
+Pluggable transport names are C-identifiers and Tor MUST check them
+for correctness.
+
+<a id="ext-orport-spec.txt-4"></a>
+
+## Security Considerations
+
+Extended ORPort or TransportControlPort do _not_ provide link
+confidentiality, authentication or integrity. Sensitive data, like
+cryptographic material, should not be transferred through them.
+
+An attacker with superuser access is able to sniff network traffic,
+and capture TransportControlPort identifiers and any data passed
+through those ports.
+
+Tor SHOULD issue a warning if the bridge operator tries to bind
+Extended ORPort to a non-localhost address.
+
+Pluggable transport proxies SHOULD issue a warning if they are
+instructed to connect to a non-localhost Extended ORPort.