Commit 554d63ad authored by Nick Mathewson's avatar Nick Mathewson 🤹
Browse files

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

Closes #50.
parent 1850a1eb
Loading
Loading
Loading
Loading

ext-orport-spec.txt

0 → 100644
+212 −0
Original line number Diff line number Diff line
             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.
+8 −4
Original line number Diff line number Diff line
@@ -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]
+1 −1
Original line number Diff line number Diff line
@@ -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
+1 −1
Original line number Diff line number Diff line
@@ -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
+4 −2
Original line number Diff line number Diff line
@@ -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]
Loading