commit 554d63ad3a60b705c3a5cbe2e3e9b33094a049dd Author: Nick Mathewson <nickm@torproject.org> Date: Mon Jun 28 09:43:23 2021 -0400 Make proposals 196/217 into an ext-orport-spec.txt. Closes torspec#50. --- ext-orport-spec.txt | 212 ++++++++++++++++++++++++++++++ proposals/000-index.txt | 12 +- proposals/196-transport-control-ports.txt | 2 +- proposals/217-ext-orport-auth.txt | 2 +- proposals/BY_INDEX.md | 6 +- proposals/README.md | 6 +- 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