Filename: 229-further-socks5-extensions.txt
Title: Further SOCKS5 extensions
Author: Yawning Angel
Created: 25-Feb-2014
Status: Rejected
Note: These are good ideas, but it's better not to hack SOCKS any further
now that we support HTTP CONNECT tunnels.
0. Abstract
We propose extending the SOCKS5 protocol to allow passing more
per-session metadata, and to allow returning more meaningful
response 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.
If any requirement labeled with a "MUST" below in this protocol
is violated, the party receiving the violation MUST close the
connection.
All multibyte numeric values in this protocol MUST be transmitted
in network (big-endian) byte order.
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.
KLEN: 16 bits (unsigned integer)
This field specifies the length of the key in bytes. It 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 NUL terminator.
VLEN: 16 bits (unsigned integer)
This field specifies the length of the value in bytes. 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 following 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.
[XXXX What should a client if it gets a value here it does
not recognize?]
NR PAIRS, KLEN, KEY, VLEN, VALUE:
These fields have the same format as they do in Extended
Authentication requests.
The currently defined KEYs are:
* "USERNAME" The username for authentication.
* "PASSWD" The password for authentication.
[XXXX What do these do? What is their behavior? Are they
client-only? Right now, Tor uses SOCKS5 usernames and
passwords in two ways:
1) as a way to control isolation, when receiving them
from a SOCKS client.
2) as a way to encode arbitrary data, when sending data
to a PT.
Neither of these seem necessary any more. We can turn 1 into
a new KEY, and we can turn 2 into a new set of keys. -NM]
[XXX - Add some more here, Stream isolation? -YA]
[XXXX What should a client if it gets a value here it does
not recognize? -NM]
[XXXX Should we recommend any namespace conventions for these? -NM]
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.
[Actually, should this perhaps be controlled by additional KEY?
(I'm not sure.) -NM]
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 SOCKS5 is
sent in cleartext, this extension (like the rest of the SOCKS5
protocol) 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) -YA]
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
2014-02-28 (nickm's fault)
* check it into git
* clean text a little, fix redundancy
* ask some questions