[tor-commits] [torspec/master] Some additions related to the Extended ORPort.

[nickm at torproject.org]

commit aeebf8950ad137478b661cc2b6fa4c47c5f88f2f
Author: George Kadianakis <desnacked at riseup.net>
Date:   Thu Dec 6 16:38:44 2012 +0200

    Some additions related to the Extended ORPort.
---
 proposals/180-pluggable-transport.txt     |   34 +---------------------------
 proposals/196-transport-control-ports.txt |   24 ++++++++++++++++++-
 pt-spec.txt                               |    6 +++++
 3 files changed, 30 insertions(+), 34 deletions(-)

diff --git a/proposals/180-pluggable-transport.txt b/proposals/180-pluggable-transport.txt
index cc279c2..2e63f2e 100644
--- a/proposals/180-pluggable-transport.txt
+++ b/proposals/180-pluggable-transport.txt
@@ -443,39 +443,9 @@ Managed proxy interface
   should set the environment variable:
     TOR_PT_MANAGED_TRANSPORT_VER=1
 
-The extended ORPort protocol
+The Extended ORPort protocol
 
-  Server transports may need to connect to the bridge and pass
-  additional information about client connections that the bridge
-  would ordinarily receive from the kernel's TCP stack.  To do this,
-  they connect to the "extended server port" as given in
-  EXTENDED_SERVER_PORT, send a short amount of information, wait for a
-  response, and then send the user traffic on that port.
-
-  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 to the server are:
-
-     [0x0000] DONE: There is no more information to give. (body ignored)
-
-     [0x0001] USERADDR: an address:port string that represents the user's
-       address.  If the transport doesn't actually do addresses,
-       this shouldn't be sent.
-
-     Replies sent from tor to the proxy are:
-
-     [0x1001] OKAY: Send the user's traffic. (body ignored)
-
-     [0x1002] DENY: Tor would prefer not to get more traffic from
-       this address for a while. (body ignored)
-
-  [We could also use an out-of-band signalling method to tell Tor
-  about client addresses, but that's a historically error-prone way
-  to go about annotating connections.]
+  The Extended ORPort protocol is described in proposal 196.
 
 Advertising bridge methods
 
diff --git a/proposals/196-transport-control-ports.txt b/proposals/196-transport-control-ports.txt
index 549e8ce..c7f1c3a 100644
--- a/proposals/196-transport-control-ports.txt
+++ b/proposals/196-transport-control-ports.txt
@@ -159,7 +159,27 @@ Target: 0.2.4.x
   command it MAY want to shutdown its connections to the transport
   proxy.
 
-5. Security Considerations
+5. Authentication
+
+  To defend against cross-protocol attacks on the Extended ORPOrt,
+  proposal 213 defines an authentication scheme that should be used to
+  protect it.
+
+  If the Extended ORPort is enabled, Tor should regenerate the cookie
+  file of proposal 213 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.
+
+  XXX should we also add an ExtORPortCookieFileGroupReadable torrc option?
+
+6. Security Considerations
 
   Extended ORPort or TransportControlPort do _not_ provide link
   confidentiality, authentication or integrity. Sensitive data, like
@@ -176,7 +196,7 @@ Target: 0.2.4.x
   instructed to connect to a non-localhost Extended ORPort or
   TransportControlPort.
 
-6. Future
+7. Future
 
   In the future, we might have pluggable transports which require the
   _client_ transport proxy to use the TransportControlPort and exchange
diff --git a/pt-spec.txt b/pt-spec.txt
index 0da004a..72662b6 100644
--- a/pt-spec.txt
+++ b/pt-spec.txt
@@ -212,6 +212,12 @@ Managed proxy interface
        doesn't recognize.
       Example: TOR_PT_SERVER_TRANSPORTS=trebuchet,ballista
 
+      "TOR_PT_AUTH_COOKIE_FILE" -- A filesystem path where the proxy
+      should expect to find the authentication cookie to be able to
+      communicate with the Extended ORPort and TransportControlPort.
+      TOR_PT_AUTH_COOKIE_FILE is optional and might not be present in
+      the environment of the proxy.
+
   The transport proxy replies by writing NL-terminated lines to
   stdout.  The line metaformat is