commit 739d70b160f51a12c06cd315546198c2a1b4be3e Author: Nick Mathewson <nickm@torproject.org> Date: Thu Mar 15 18:14:28 2012 -0400 Add "Extended ORPort and TransportControlPort" as proposal 196. --- proposals/000-index.txt | 2 + proposals/196-transport-control-ports.txt | 185 +++++++++++++++++++++++++++++ proposals/xxx-transport-control-ports.txt | 185 ----------------------------- 3 files changed, 187 insertions(+), 185 deletions(-) diff --git a/proposals/000-index.txt b/proposals/000-index.txt index fc5c508..4507a18 100644 --- a/proposals/000-index.txt +++ b/proposals/000-index.txt @@ -116,6 +116,7 @@ Proposals by number: 193 Safe cookie authentication for Tor controllers [OPEN] 194 Mnemonic .onion URLs [OPEN] 195 TLS certificate normalization for Tor 0.2.4.x [DRAFT] +196 Extended ORPort and TransportControlPort [OPEN] Proposals by status: @@ -152,6 +153,7 @@ Proposals by status: 192 Automatically retrieve and store information about bridges [for 0.2.[45].x] 193 Safe cookie authentication for Tor controllers 194 Mnemonic .onion URLs + 196 Extended ORPort and TransportControlPort [for 0.2.4.x] ACCEPTED: 117 IPv6 exits [for 0.2.3.x] 140 Provide diffs between consensuses diff --git a/proposals/196-transport-control-ports.txt b/proposals/196-transport-control-ports.txt new file mode 100644 index 0000000..549e8ce --- /dev/null +++ b/proposals/196-transport-control-ports.txt @@ -0,0 +1,185 @@ +Filename: 196-transport-control-ports.txt +Title: Extended ORPort and TransportControlPort +Author: George Kadianakis, Nick Mathewson +Created: 14 Mar 2012 +Status: Open +Target: 0.2.4.x + +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. + + Specifically, transports proxies deliver each connection to the + "Extended ORPort", where they provide metadata and agree on an + identifier for each tunneled connection. Once this handshake + occurs, the OR protocol proceeds unchanged. + + Additionally, each transport maintains a single connection to Tor's + "TransportControlPort", where it receives instructions from Tor + about rate-limiting on individual connections. + +3. The new port protocols + +3.1. The new extended ORPort 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 user's + address. + + 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. The + pluggable transport proxy must use the "identifier" to access + the TransportControlPort. See the 'Association and identifier + creation' section below. + + Parties should ignore command codes that they do not understand. + +3.2. The new TransportControlPort protocol + + The TransportControlPort protocol is as follows: + + CONNECTIONID[16 bytes, big-endian] + COMMAND [2 bytes, big-endian] + BODYLEN [2 bytes, big-endian] + BODY [BODYLEN bytes] + + 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. + + [0x0002] 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: + + [0x1001] NOT_ALLOWED: Message notifying that the CONNECTIONID + could not be matched with an authorized connection ID. The + bridge SHOULD shutdown the connection. + + [0x1001] RATE_LIMIT: Carries information on how the pluggable + transport proxy should rate-limit its traffic. See the 'Rate + Limiting' section below. + + CONNECTIONID should carry the connection identifier described in the + 'Association and identifier creation' section. + + Parties should ignore command codes that they do not understand. + +3.3. 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 MUST create its identifiers by generating 16 bytes of random + data. + +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 contain two integers, + 4 bytes each, in big-endian format. The two numbers should represent + the bandwidth rate and bandwidth burst respectively in 'bytes per + second' which the transport proxy must set as its overall + rate-limiting setting. + + 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 MAY 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 MAY want to shutdown its connections to the transport + proxy. + +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. + + 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 or TransportControlPort to a non-localhost address. + + Pluggable transport proxies SHOULD issue a warning if they are + instructed to connect to a non-localhost Extended ORPort or + TransportControlPort. + +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. diff --git a/proposals/xxx-transport-control-ports.txt b/proposals/xxx-transport-control-ports.txt deleted file mode 100644 index 61f6b3e..0000000 --- a/proposals/xxx-transport-control-ports.txt +++ /dev/null @@ -1,185 +0,0 @@ -Filename: xxx-transport-control-ports.txt -Title: Extended ORPort and TransportControlPort -Author: George Kadianakis, Nick Mathewson -Created: 14 Mar 2012 -Status: Open -Target: 0.2.4.x - -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. - - Specifically, transports proxies deliver each connection to the - "Extended ORPort", where they provide metadata and agree on an - identifier for each tunneled connection. Once this handshake - occurs, the OR protocol proceeds unchanged. - - Additionally, each transport maintains a single connection to Tor's - "TransportControlPort", where it receives instructions from Tor - about rate-limiting on individual connections. - -3. The new port protocols - -3.1. The new extended ORPort 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 user's - address. - - 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. The - pluggable transport proxy must use the "identifier" to access - the TransportControlPort. See the 'Association and identifier - creation' section below. - - Parties should ignore command codes that they do not understand. - -3.2. The new TransportControlPort protocol - - The TransportControlPort protocol is as follows: - - CONNECTIONID[16 bytes, big-endian] - COMMAND [2 bytes, big-endian] - BODYLEN [2 bytes, big-endian] - BODY [BODYLEN bytes] - - 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. - - [0x0002] 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: - - [0x1001] NOT_ALLOWED: Message notifying that the CONNECTIONID - could not be matched with an authorized connection ID. The - bridge SHOULD shutdown the connection. - - [0x1001] RATE_LIMIT: Carries information on how the pluggable - transport proxy should rate-limit its traffic. See the 'Rate - Limiting' section below. - - CONNECTIONID should carry the connection identifier described in the - 'Association and identifier creation' section. - - Parties should ignore command codes that they do not understand. - -3.3. 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 MUST create its identifiers by generating 16 bytes of random - data. - -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 contain two integers, - 4 bytes each, in big-endian format. The two numbers should represent - the bandwidth rate and bandwidth burst respectively in 'bytes per - second' which the transport proxy must set as its overall - rate-limiting setting. - - 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 MAY 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 MAY want to shutdown its connections to the transport - proxy. - -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. - - 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 or TransportControlPort to a non-localhost address. - - Pluggable transport proxies SHOULD issue a warning if they are - instructed to connect to a non-localhost Extended ORPort or - TransportControlPort. - -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.