[tor-dev] Pre-draft of Proposal XXX: Extended ORPort and TransportControlPort

[George Kadianakis]

After discussion in tickets #4773 and #3587 this is a pre-draft of a
proposal that revamps the Extended ORport, introduced in proposal 180,
and specifies the new TransportControlPort.

Comments are marked with '#', and there is also:
https://trac.torproject.org/projects/tor/ticket/4773#comment:5

Note that this proposal is not ready for prime time. It needs more
thought and lots of editing to become functional and implementable.
 
Inlining:

Filename: X
Title: Extended ORPort and TransportControlPort
Author: X
Created: X
Status: worse-than-draft-still-probably-more-thoughtful-than-sopa

1. Overview

  Proposal 180 defined Tor pluggable transports, a way to decouple
  protocol-level obfuscation from the core Tor protocol in order to
  better resist client-bridge censorship. This is achieved by
  introducing pluggable transport proxies, programs that obfuscate Tor
  traffic to resist DPI detection.

  Proposal 180 defined a way for pluggable transport proxies to
  communicate with local tor clients and bridges, so as to exchange
  traffic. This document extends this communication protocol, so that
  pluggable transport proxies can exchange arbitrary operational
  information and metadata with tor clients and bridges.

2. Motivation

   The communication protocol specified in Proposal 180 gives a way
   for transport proxies to announce the IP address of their clients
   to tor. Still, modern pluggable transports might have more (?)
   needs than this. For example:

   1. Tor might want to inform pluggable transport proxies on how to
      rate-limit incoming or outgoing connections.

   2. Server pluggable transport proxies might want to pass client
      information to an anti-active-probing system controlled by tor.

   3. Tor might want to temporarily stop a transport proxy from
      obfuscating traffic.

   To satisfy the above use cases, there must be real-time
   communication between the tor process and the pluggable transport
   proxy. To achieve this, this proposal refactors the extended ORPort
   protocol specified in Proposal 180, and introduces a new port,
   TransportControlPort, whose sole role is the exchange of control
   information between transport proxies and tor.

3. The new extended ORPort protocol

  Server transport proxies 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 proxy to the bridge are:

     [0x0000] DONE: There is no more information to give. (body ignored)

     [0x0001] USERADDR: an address:port string that represents the user's
       address.

     [0x0002] WANT_CONTROL: A body-less message which indicates that
       the transport proxy wants to use the TransportControlPort of
       the bridge.  It SHOULD be followed by a CONTROL command from
       the bridge, otherwise the transport may close the connection.

# will this work?

     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: a NUL-terminated "identifier" string, followed
       by a second NUL-terminated string of the <address>:<port> of
       the TransportControlPort. The pluggable transport proxy must
       use the "identifier" to access the TransportControlPort.

# pass TransportControlPort <address>:<port> through env. vars?

# what should parties do when they receive a command they don't
# understand?  should we enforce forward-compatibility with protocol
# versioning or with "ignore commands you don't understand", or what?

  [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 new TransportControlPort protocol

  The TransportControlPort protocol is as follows:

     COMMAND [2 bytes, big-endian]
     BODYLEN [2 bytes, big-endian]
     BODY [BODYLEN bytes]

     Association commands sent from the transport proxy to the bridge
     are:

     [0x0000] ASSOCIATE: a NUL-terminated "identifier" string. See
      'Association' section below.

     Association commands sent from the bridge to the transport proxy
     are:

     [0x1000] ASSOCIATED: Sent upon receiving a legit ASSOCIATE
       command from a transport proxy. (body ignored)

     [0x1001] NOT_ASSOCIATED: Sent after the bridge receives a
       non-legit ASSOCIATE command from a transport proxy. Also sent
       when the bridge receives a non-ASSOCIATE command from a
       non-associated transport proxy. Upon sending this command, the
       bridge SHOULD close the connection. (body ignored)

     Configuration commands sent from the transport proxy to the
     bridge:

     [0x0001] RATE_LIMITED: Message confirming that the rate limiting
       request of the bridge was carried out successfully (body
       ignored). See the 'Rate Limiting' section below.

     [0x0001] NOT_RATE_LIMITED: Message notifying that the transport
       proxy failed to carry out the rate limiting request of the
       bridge (body ignored). See the 'Rate Limiting' section below.

     Configuration commands sent from the bridge to the transport
     proxy are:

     [0x1002] RATE_LIMIT: Carries information on how the pluggable
       transport proxy should rate-limit its traffic. See the 'Rate
       Limiting' section below.

# what should parties do when they receive a command they don't understand?

3.1. Association and identifier creation

For Tor and a transport proxy to communicate using the
TransportControlPort, an identifier must have already been negotiated
using the 'CONTROL' command of Extended ORPort.

The TransportControlPort identifier should not be predictable by a
user who hasn't received a 'CONTROL' command from the Extended
ORPort. For this reason, the TransportControlPort identifier should
not be cryptographically-weak or deterministically created.

Tor should create its identifiers by generating 16 bytes of random
data and hashing them with the SHA256 cryptographic hash function.
The identifier string transmitted with the 'CONTROL' command should be
the hex representation of the SHA256 output.

4. Configuration commands

4.1. Rate Limiting

A tor relay should be able to inform a transport proxy in real-time
about its rate-limiting needs.

This can be achieved by using the TransportControlPort and sending a
'RATE_LIMIT' command to the transport proxy.

The body of the 'RATE_LIMIT' command should carry two integers, in
NUL-terminated ASCII string format, representing the bandwidth rate
and bandwidth burst in 'bytes per second', that the transport proxy
must set.

# better transmit format? After reading langsec.org, I prefer to avoid
# length fields. Not that this format is bug-proof...

When the transport proxy sets the appropriate rate limiting, it should
send back a 'RATE_LIMITED' command. If it fails while setting up rate
limiting, it should send back a 'NOT_RATE_LIMITED' command.

After sending a 'RATE_LIMIT' command. the tor bridge might want to
stop pushing data to the transport proxy, till it receives a
'RATE_LIMITED' command. If, instead, it receives a 'NOT_RATE_LIMITED'
command it might want to shutdown its connections to the transport
proxy.

# is this realistic?

5. 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.

Note that an attacker with superuser access, is able to sniff network
traffic, and capture TransportControlPort identifiers and any data
passed through those ports.

# Is it worth adding an SSL layer (passing pub. key fpr via
# env. vars?)? :/

# Talk about Incentives of tor or transport proxies to comply to the
# wishes of each other. Ways to detect nonconformism. (threat
# model. Should tor speak with 3v1l transport proxies in the first
# place?)

6. Future

In the future, we might have pluggable transports which require the
_client_ transport proxy to use the TransportControlPort and exchange
control information with the tor client. The current proposal doesn't
yet support this, but we should not add functionality that will
prevent it from being possible.