mirror of
https://github.com/torproject/torspec.git
synced 2024-12-13 21:48:45 +00:00
02f91927b4
These extensions are cool, but if anybody needs them it's better for them to use HTTP CONNECT.
255 lines
8.5 KiB
Plaintext
255 lines
8.5 KiB
Plaintext
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
|