commit ba8c74dc5ce221a58b668040cbd08e13fc0c789d Author: Nick Mathewson nickm@torproject.org Date: Fri Feb 28 11:44:12 2014 -0500

Add socks5 extensions as proposal 229 --- proposals/000-index.txt | 2 + proposals/229-further-socks5-extensions.txt | 238 +++++++++++++++++++++++++++ 2 files changed, 240 insertions(+)

diff --git a/proposals/000-index.txt b/proposals/000-index.txt index c854980..a7a4287 100644 --- a/proposals/000-index.txt +++ b/proposals/000-index.txt @@ -149,6 +149,7 @@ Proposals by number: 226 "Scalability and Stability Improvements to BridgeDB: Switching to a Distributed Database System and RDBMS" [OPEN] 227 Include package fingerprints in consensus documents [OPEN] 228 Cross-certifying identity keys with onion keys [OPEN] +229 Further SOCKS5 extensions [DRAFT]

Proposals by status: @@ -167,6 +168,7 @@ Proposals by status: 220 Migrate server identity keys to Ed25519 [for 0.2.x.x] 224 Next-Generation Hidden Services in Tor 225 Strawman proposal: commit-and-reveal shared rng + 229 Further SOCKS5 extensions NEEDS-REVISION: 131 Help users to verify they are using Tor 190 Bridge Client Authorization Based on a Shared Secret diff --git a/proposals/229-further-socks5-extensions.txt b/proposals/229-further-socks5-extensions.txt new file mode 100644 index 0000000..0371f02 --- /dev/null +++ b/proposals/229-further-socks5-extensions.txt @@ -0,0 +1,238 @@ +Filename: 229-further-socks5-extensions.txt +Title: Further SOCKS5 extensions +Author: Yawning Angel +Created: 25-Feb-2014 +Status: Draft + +0. Abstract + + We propose extending the SOCKS5 protocol to allow passing more + per-session metadata, and to allow returning more meaningful + reponse failure codes back to the client. + +1. Introduction + + The SOCKS5 protocol is used by Tor both as the primary interface + for applications to transfer data, and as the interface by which + Tor communicates with pluggable transport implementations. + + While the current specifications allow for passing a limited + amount of per-session metadata via hijacking the + Username/Password authentication method fields, this solution is + limited in that the amount of payload that can be conveyed is + restricted to 510 bytes, does not allow the SOCKS server to + return a response, and precludes using authentication on the + SOCKS port. + + The first part of this proposal defines a new authentication + method to overcome both of these limitations. + + The second part of this proposal defines a range of SOCKS5 + response codes that can be used to signal Tor specific error + conditions when processing SOCKS requests. + +2. Proposal + +2.1. Tor Extended SOCKS5 Authentication + + We introduce a new authentication method to the SOCKS5 protocol. + + The METHOD number to be returned to indicate support for or + select this method is X'97', which belongs to the "RESERVED FOR + PRIVATE METHODS" range in RFC 1928. + + After the authentication method has been negotiated following the + standard SOCKS5 protocol, the actual authentication phase begins. + + The initiator will send an Extended Authentication request: + + +----+----------+-------+-------------+-------+-------------+--- + |VER | NR PAIRS | KLEN1 | KEY1 | VLEN1 | VALUE1 | ... + +----+----------+-------+-------------+-------+-------------+--- + | 1 | 2 | 2 | KLEN1 bytes | 2 | VLEN1 bytes | ... + +----+----------+-------+-------------+-------+-------------+--- + + VER: 8 bits (unsigned integer) + + This field specifies the version of the authentication + method. It MUST be set to X'01'. + + NR PAIRS: 16 bits (unsigned integer) + + This field specifies the number of key/value pairs to follow. + The NR PAIRS field MUST be transmitted in network byte order. + + KLEN: 16 bits (unsigned integer) + + This field specifies the length of the key in bytes. It MUST + be transmitted in network byte order, and MUST be greater + than 0. + + KEY: variable length + + This field contains the key associated with the subsequent + VALUE field as an ASCII string, without a NULL terminator. + + VLEN: 16 bits (unsigned integer) + + This field specifies the length of the value in bytes. It + MUST be tramsmitted in network byte order. It MAY be + X'0000', in which case the corresponding VALUE field is + omitted. + + VALUE: variable length, optional + + The value corresponding to the KEY. + + + The responder will verify the contents of the Extended + Authentication request and send the followint response: + + +----+--------+----------+-------+-------------+-------+-------------+--- + |VER | STATUS | NR PAIRS | KLEN1 | KEY1 | VLEN1 | VALUE1 | ... + +----+--------+----------+-------+-------------+-------+-------------+--- + | 1 | 1 | 2 | 2 | KLEN1 bytes | 2 | VLEN1 bytes | ... + +----+--------+----------+-------+-------------+-------+-------------+--- + + VER: 8 bits (unsigned integer) + + This field specifies the version of the authentication + method. It MUST be set to X'01'. + + STATUS: 8 bits (unsigned integer) + + The status of the Extended Authentication request where: + + * X'00' SUCCESS + * X'01' AUTHENTICATION FAILED + * X'02' INVALID ARGUMENTS + + If a server sends a response indicating failure (STATUS value + other than X'00') it MUST close the connection. + + NR PAIRS: 16 bits (unsigned integer) + + This field specifies the number of key/value pairs to follow. + The NR PAIRS field MUST be transmitted in network byte order. + + KLEN: 16 bits (unsigned integer) + + This field specifies the length of the key in bytes. It MUST be + transmitted in network byte order, and MUST be greater than 0. + + KEY: variable length + + This field contains the key associated with the subsequent + VALUE field as an ASCII string, without a NULL terminator. + + VLEN: 16 bits (unsigned integer) + + This field specifies the length of the value in bytes. It + MUST be tramsmitted in network byte order. It MAY be + X'0000', in which case the corresponding VALUE field is + omitted. + + VALUE: variable length, optional + + The value corresponding to the KEY. + + The currently defined KEYs are: + + * "UNAME" The username for authentication. + * "PASSWD" The password for authentication. + + [XXX - Add some more here, Stream isolation?] + +2.2. Tor Extended SOCKS5 Reply Codes + + We introduce the following additional SOCKS5 reply codes to be + sent in the REP field of a SOCKS5 message. Implementations MUST + NOT send any of the extended codes unless the initiator has + indicated that it understands the "Tor Extended SOCKS5 + Authentication" as part of the version identifier/method + selection SOCKS5 message. + + Where: + + * X'E0' Hidden Service Not Found + + The requested Tor Hidden Service was not reachable. + + * X'E1' Hidden Service Not Reachable + + The requested Tor Hidden Service was not found. + + * X'F0' Temporary Pluggable Transport failure, retry immediately + + Pluggable transports SHOULD return this status code if the + connection attempt failed, but the pluggable transport + believes that subsequent connections with the same parameters + are likely to succeed. + + Example: + + The ScrambleSuit Session Ticket handshake failed, but + reconnecting is likely to succeed as it will use the + UniformDH handshake. + + * X'F1' Pluggable transport protocol failure, invalid bridge + + Pluggable transports MUST return this status code if the + connection attempt failed in a manner that indicates that the + remote peer is not likely to accept connections at a later + time. + + Example: + + The obfs3 handshake failed. + + * X'F2' Pluggable transport internal error + + Pluggable transports SHOULD return this status code if the + connection attempt failed due to an internal error in the + pluggable transport implementation. + + Tor might wish to restart the pluggable transport executable, + or retry after a delay. + +3. Compatibility + + SOCKS5 negotiates authentication methods so backward and forward + compatibility is obtained for free, assuming a non-broken SOCKS5 + implementation on the responder side that ignores unrecognised + authentication methods in the negotiation phase. + +4. Security Considerations + + Identical security considerations to RFC 1929 Username/Password + authentication applies when doing Username/Password + authentication using the keys reserved for such. As the + UNAME/PASSWD fields are carried in cleartext, this authentication + method MUST NOT be used in scenarios where sniffing is possible. + The authors of this proposal note that binding any of the Tor + (and associated) SOCKS5 servers to non-loopback interfaces is + strongly discouraged currently, so in the current model this is + believed to be acceptable. + +5. References + + Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., Jones L., "SOCKS + Protocol Version 5", RFC 1928, March 1996. + + Tor Project, "Tor's extensions to the SOCKS protocol" + + Leech, M. "Username/Password Authentication for SOCKS V5", RFC 1929, + March 1996. + + Appelbaum, J., Mathewson, N., "Pluggable Transport Specification", + June 2012. + +[XXX - Changelog (Remove when accepted)] + + 2014-02-28 (Thanks to nickm/arma) + * Generalize to also support tor + * Add status codes for bug #6031 + * Switch from always having a username/password field to making them just + predefined keys. + * Change the auth method number to 0x97 +