From e4e0d93d56ee8c1aec4c2efaa7046b651f0fe55c Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Thu, 12 Oct 2023 12:27:58 -0400 Subject: Move all text-only specifications into the OLD_TXT directory. --- ext-orport-spec.txt | 226 ---------------------------------------------------- 1 file changed, 226 deletions(-) delete mode 100644 ext-orport-spec.txt (limited to 'ext-orport-spec.txt') diff --git a/ext-orport-spec.txt b/ext-orport-spec.txt deleted file mode 100644 index 6b8f8e1..0000000 --- a/ext-orport-spec.txt +++ /dev/null @@ -1,226 +0,0 @@ - Extended ORPort for pluggable transports - George Kadianakis, Nick Mathewson - -Table of Contents - - 1. Overview - 2. Establishing a connection and authenticating. - 2.1. Authentication type: SAFE_COOKIE - 2.1.2. Cookie-file format - 2.1.3. SAFE_COOKIE Protocol specification - 3. The extended ORPort protocol - 3.1. Protocol - 3.2. Command descriptions - 3.2.1. USERADDR - 3.2.2. TRANSPORT - 4. Security Considerations - -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 overridden by using the - configuration file parameter ExtORPortCookieAuthFile, which is - defined as: - - ExtORPortCookieAuthFile - - where 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 successful. 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. - -- cgit v1.2.3-54-g00ecf