Make proposals 196/217 into an ext-orport-spec.txt.

Closes torspec#50.

6 files changed, 230 insertions, 10 deletions

diff --git a/ext-orport-spec.txt b/ext-orport-spec.txt
new file mode 100644
index 0000000..8008c4f
--- /dev/null
+++ b/ext-orport-spec.txt
@@ -0,0 +1,212 @@
+             Extended ORPort for pluggable transports
+                 George Kadianakis, Nick Mathewson
+
+1. 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.
+
+2. Establishing a connection and authenticating.
+
+  When a client (that is to say, a server-side pluggable transport)
+  connects to an Extended ORPort, the server sends:
+
+    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,
+
+  + 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.
+
+2.1. Authentication type: 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 overriden by using the
+  configuration file parameter ExtORPortCookieAuthFile, which is
+  defined as:
+
+    ExtORPortCookieAuthFile <path>
+
+  where <path> is a filesystem path.
+
+2.1.2. Cookie-file format
+
+  The format of the cookie-file is:
+
+     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.
+
+2.1.3.  SAFE_COOKIE Protocol specification
+
+
+  A client that performs the SAFE_COOKIE handshake begins by sending:
+
+     ClientNonce                                 [32 octets]
+
+  Where,
+  + ClientNonce is 32 octets of random data.
+
+  Then, the server replies with:
+
+     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:
+
+     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]
+
+  Where,
+  + Status is 1 if the authentication was successfull. If the
+    authentication failed, Status is 0.
+
+3. The extended ORPort protocol
+
+  Once a connection is established and authenticated, the parties
+  communicate with the protocol described here.
+
+3.1. Protocol
+
+  The extended server port protocol is as follows:
+
+     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.
+
+3.2. Command descriptions
+
+3.2.1. USERADDR
+
+  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.
+
+3.2.2. 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.
+
+4. 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.
+
diff --git a/proposals/000-index.txt b/proposals/000-index.txt
index ec40cd3..49261e3 100644
--- a/proposals/000-index.txt
+++ b/proposals/000-index.txt
@@ -116,7 +116,7 @@ Proposals by number:
 193  Safe cookie authentication for Tor controllers [CLOSED]
 194  Mnemonic .onion URLs [SUPERSEDED]
 195  TLS certificate normalization for Tor 0.2.4.x [DEAD]
-196  Extended ORPort and TransportControlPort [FINISHED]
+196  Extended ORPort and TransportControlPort [CLOSED]
 197  Message-based Inter-Controller IPC Channel [REJECTED]
 198  Restore semantics of TLS ClientHello [CLOSED]
 199  Integration of BridgeFinder and BridgeFinderHelper [OBSOLETE]
@@ -137,7 +137,7 @@ Proposals by number:
 214  Allow 4-byte circuit IDs in a new link protocol [CLOSED]
 215  Let the minimum consensus method change with time [CLOSED]
 216  Improved circuit-creation key exchange [CLOSED]
-217  Tor Extended ORPort Authentication [FINISHED]
+217  Tor Extended ORPort Authentication [CLOSED]
 218  Controller events to better understand connection/circuit usage [CLOSED]
 219  Support for full DNS and DNSSEC resolution in Tor [NEEDS-REVISION]
 220  Migrate server identity keys to Ed25519 [CLOSED]
@@ -249,7 +249,9 @@ Proposals by number:
 326  The "tor-relay" Well-Known Resource Identifier [OPEN]
 327  A First Take at PoW Over Introduction Circuits [DRAFT]
 328  Make Relays Report When They Are Overloaded [DRAFT]
+329  Overcoming Tor's Bottlenecks with Traffic Splitting [DRAFT]
 330  Modernizing authority contact entries [OPEN]
+331  Res tokens: Anonymous Credentials for Onion Service DoS Resilience [DRAFT]
 
 
 Proposals by status:
@@ -260,6 +262,8 @@ Proposals by status:
    316  FlashFlow: A Secure Speed Test for Tor (Parent Proposal)
    327  A First Take at PoW Over Introduction Circuits
    328  Make Relays Report When They Are Overloaded
+   329  Overcoming Tor's Bottlenecks with Traffic Splitting
+   331  Res tokens: Anonymous Credentials for Onion Service DoS Resilience
  NEEDS-REVISION:
    212  Increase Acceptable Consensus Age [for 0.2.4.x+]
    219  Support for full DNS and DNSSEC resolution in Tor [for 0.2.5.x]
@@ -309,8 +313,6 @@ Proposals by status:
    290  Continuously update consensus methods
  FINISHED:
    160  Authorities vote for bandwidth offsets in consensus [for 0.2.1.x]
-   196  Extended ORPort and TransportControlPort [in 0.2.5.2-alpha]
-   217  Tor Extended ORPort Authentication [for 0.2.5.x]
    232  Pluggable Transport through SOCKS proxy [in 0.2.6]
    260  Rendezvous Single Onion Services [in 0.2.9.3-alpha]
    282  Remove "Named" and "Unnamed" handling from consensus voting [for 0.3.3.x]
@@ -368,6 +370,7 @@ Proposals by status:
    186  Multiple addresses for one OR or bridge [for 0.2.4.x+]
    187  Reserve a cell type to allow client authorization [for 0.2.3.x]
    193  Safe cookie authentication for Tor controllers
+   196  Extended ORPort and TransportControlPort [in 0.2.5.2-alpha]
    198  Restore semantics of TLS ClientHello [for 0.2.4.x]
    200  Adding new, extensible CREATE, EXTEND, and related cells [in 0.2.4.8-alpha]
    204  Subdomain support for Hidden Service addresses
@@ -378,6 +381,7 @@ Proposals by status:
    214  Allow 4-byte circuit IDs in a new link protocol [in 0.2.4.11-alpha]
    215  Let the minimum consensus method change with time [in 0.2.6.1-alpha]
    216  Improved circuit-creation key exchange [in 0.2.4.8-alpha]
+   217  Tor Extended ORPort Authentication [for 0.2.5.x]
    218  Controller events to better understand connection/circuit usage [in 0.2.5.2-alpha]
    220  Migrate server identity keys to Ed25519 [in 0.3.0.1-alpha]
    221  Stop using CREATE_FAST [for 0.2.5.x]
diff --git a/proposals/196-transport-control-ports.txt b/proposals/196-transport-control-ports.txt
index 15a1c02..f4d8a0e 100644
--- a/proposals/196-transport-control-ports.txt
+++ b/proposals/196-transport-control-ports.txt
@@ -2,7 +2,7 @@ Filename: 196-transport-control-ports.txt
 Title: Extended ORPort and TransportControlPort
 Author: George Kadianakis, Nick Mathewson
 Created: 14 Mar 2012
-Status: Finished
+Status: Closed
 Implemented-In: 0.2.5.2-alpha
 
 1. Overview
diff --git a/proposals/217-ext-orport-auth.txt b/proposals/217-ext-orport-auth.txt
index e453ec4..3734924 100644
--- a/proposals/217-ext-orport-auth.txt
+++ b/proposals/217-ext-orport-auth.txt
@@ -2,7 +2,7 @@ Filename: 217-ext-orport-auth.txt
 Title: Tor Extended ORPort Authentication
 Author: George Kadianakis
 Created: 28-11-2012
-Status: Finished
+Status: Closed
 Target: 0.2.5.x
 
 1. Overview
diff --git a/proposals/BY_INDEX.md b/proposals/BY_INDEX.md
index 18d81a0..8000a83 100644
--- a/proposals/BY_INDEX.md
+++ b/proposals/BY_INDEX.md
@@ -113,7 +113,7 @@ Below are a list of proposals sorted by their proposal number.  See
 * [`193-safe-cookie-authentication.txt`](/proposals/193-safe-cookie-authentication.txt): Safe cookie authentication for Tor controllers [CLOSED]
 * [`194-mnemonic-urls.txt`](/proposals/194-mnemonic-urls.txt): Mnemonic .onion URLs [SUPERSEDED]
 * [`195-TLS-normalization-for-024.txt`](/proposals/195-TLS-normalization-for-024.txt): TLS certificate normalization for Tor 0.2.4.x [DEAD]
-* [`196-transport-control-ports.txt`](/proposals/196-transport-control-ports.txt): Extended ORPort and TransportControlPort [FINISHED]
+* [`196-transport-control-ports.txt`](/proposals/196-transport-control-ports.txt): Extended ORPort and TransportControlPort [CLOSED]
 * [`197-postmessage-ipc.txt`](/proposals/197-postmessage-ipc.txt): Message-based Inter-Controller IPC Channel [REJECTED]
 * [`198-restore-clienthello-semantics.txt`](/proposals/198-restore-clienthello-semantics.txt): Restore semantics of TLS ClientHello [CLOSED]
 * [`199-bridgefinder-integration.txt`](/proposals/199-bridgefinder-integration.txt): Integration of BridgeFinder and BridgeFinderHelper [OBSOLETE]
@@ -134,7 +134,7 @@ Below are a list of proposals sorted by their proposal number.  See
 * [`214-longer-circids.txt`](/proposals/214-longer-circids.txt): Allow 4-byte circuit IDs in a new link protocol [CLOSED]
 * [`215-update-min-consensus-ver.txt`](/proposals/215-update-min-consensus-ver.txt): Let the minimum consensus method change with time [CLOSED]
 * [`216-ntor-handshake.txt`](/proposals/216-ntor-handshake.txt): Improved circuit-creation key exchange [CLOSED]
-* [`217-ext-orport-auth.txt`](/proposals/217-ext-orport-auth.txt): Tor Extended ORPort Authentication [FINISHED]
+* [`217-ext-orport-auth.txt`](/proposals/217-ext-orport-auth.txt): Tor Extended ORPort Authentication [CLOSED]
 * [`218-usage-controller-events.txt`](/proposals/218-usage-controller-events.txt): Controller events to better understand connection/circuit usage [CLOSED]
 * [`219-expanded-dns.txt`](/proposals/219-expanded-dns.txt): Support for full DNS and DNSSEC resolution in Tor [NEEDS-REVISION]
 * [`220-ecc-id-keys.txt`](/proposals/220-ecc-id-keys.txt): Migrate server identity keys to Ed25519 [CLOSED]
@@ -246,5 +246,7 @@ Below are a list of proposals sorted by their proposal number.  See
 * [`326-tor-relay-well-known-uri-rfc8615.md`](/proposals/326-tor-relay-well-known-uri-rfc8615.md): The "tor-relay" Well-Known Resource Identifier [OPEN]
 * [`327-pow-over-intro.txt`](/proposals/327-pow-over-intro.txt): A First Take at PoW Over Introduction Circuits [DRAFT]
 * [`328-relay-overload-report.md`](/proposals/328-relay-overload-report.md): Make Relays Report When They Are Overloaded [DRAFT]
+* [`329-traffic-splitting.txt`](/proposals/329-traffic-splitting.txt): Overcoming Tor's Bottlenecks with Traffic Splitting [DRAFT]
 * [`330-authority-contact.md`](/proposals/330-authority-contact.md): Modernizing authority contact entries [OPEN]
+* [`331-res-tokens-for-anti-dos.md`](/proposals/331-res-tokens-for-anti-dos.md): Res tokens: Anonymous Credentials for Onion Service DoS Resilience [DRAFT]
 
diff --git a/proposals/README.md b/proposals/README.md
index 24374bb..1a83435 100644
--- a/proposals/README.md
+++ b/proposals/README.md
@@ -64,8 +64,6 @@ These proposals are implemented in some version of Tor; the proposals
 themselves still need to be merged into the specifications proper.
 
 * [`160-bandwidth-offset.txt`](/proposals/160-bandwidth-offset.txt): Authorities vote for bandwidth offsets in consensus
-* [`196-transport-control-ports.txt`](/proposals/196-transport-control-ports.txt): Extended ORPort and TransportControlPort
-* [`217-ext-orport-auth.txt`](/proposals/217-ext-orport-auth.txt): Tor Extended ORPort Authentication
 * [`232-pluggable-transports-through-proxy.txt`](/proposals/232-pluggable-transports-through-proxy.txt): Pluggable Transport through SOCKS proxy
 * [`260-rend-single-onion.txt`](/proposals/260-rend-single-onion.txt): Rendezvous Single Onion Services
 * [`282-remove-named-from-consensus.txt`](/proposals/282-remove-named-from-consensus.txt): Remove "Named" and "Unnamed" handling from consensus voting
@@ -110,6 +108,8 @@ discussion.
 * [`316-flashflow.md`](/proposals/316-flashflow.md): FlashFlow: A Secure Speed Test for Tor (Parent Proposal)
 * [`327-pow-over-intro.txt`](/proposals/327-pow-over-intro.txt): A First Take at PoW Over Introduction Circuits
 * [`328-relay-overload-report.md`](/proposals/328-relay-overload-report.md): Make Relays Report When They Are Overloaded
+* [`329-traffic-splitting.txt`](/proposals/329-traffic-splitting.txt): Overcoming Tor's Bottlenecks with Traffic Splitting
+* [`331-res-tokens-for-anti-dos.md`](/proposals/331-res-tokens-for-anti-dos.md): Res tokens: Anonymous Credentials for Onion Service DoS Resilience
 
 
 ## NEEDS-REVISION proposals: ideas that we can't implement as-is
@@ -194,6 +194,7 @@ necessary.
 * [`186-multiple-orports.txt`](/proposals/186-multiple-orports.txt): Multiple addresses for one OR or bridge
 * [`187-allow-client-auth.txt`](/proposals/187-allow-client-auth.txt): Reserve a cell type to allow client authorization
 * [`193-safe-cookie-authentication.txt`](/proposals/193-safe-cookie-authentication.txt): Safe cookie authentication for Tor controllers
+* [`196-transport-control-ports.txt`](/proposals/196-transport-control-ports.txt): Extended ORPort and TransportControlPort
 * [`198-restore-clienthello-semantics.txt`](/proposals/198-restore-clienthello-semantics.txt): Restore semantics of TLS ClientHello
 * [`200-new-create-and-extend-cells.txt`](/proposals/200-new-create-and-extend-cells.txt): Adding new, extensible CREATE, EXTEND, and related cells
 * [`204-hidserv-subdomains.txt`](/proposals/204-hidserv-subdomains.txt): Subdomain support for Hidden Service addresses
@@ -204,6 +205,7 @@ necessary.
 * [`214-longer-circids.txt`](/proposals/214-longer-circids.txt): Allow 4-byte circuit IDs in a new link protocol
 * [`215-update-min-consensus-ver.txt`](/proposals/215-update-min-consensus-ver.txt): Let the minimum consensus method change with time
 * [`216-ntor-handshake.txt`](/proposals/216-ntor-handshake.txt): Improved circuit-creation key exchange
+* [`217-ext-orport-auth.txt`](/proposals/217-ext-orport-auth.txt): Tor Extended ORPort Authentication
 * [`218-usage-controller-events.txt`](/proposals/218-usage-controller-events.txt): Controller events to better understand connection/circuit usage
 * [`220-ecc-id-keys.txt`](/proposals/220-ecc-id-keys.txt): Migrate server identity keys to Ed25519
 * [`221-stop-using-create-fast.txt`](/proposals/221-stop-using-create-fast.txt): Stop using CREATE_FAST