[tor-commits] [torspec/master] Add socks5 extensions as proposal 229
nickm at torproject.org
nickm at torproject.org
Fri Feb 28 16:44:16 UTC 2014
commit ba8c74dc5ce221a58b668040cbd08e13fc0c789d
Author: Nick Mathewson <nickm at 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
+
More information about the tor-commits
mailing list