On Fri, Feb 28, 2014 at 3:53 AM, Yawning Angel yawning@schwanenlied.me wrote:

Hello all,

Based on feedback from nickm/arma, I have extended the proposal to also cover Tor's SOCKS port, including response codes related to hidden service status.

Additionally, instead of having a username/password field pre-defined, the extended authentication method has been generalized to contain key/value pairs for extra flexibility in the future.

Questions, comments, feedback appreciated as always,

This is now proposal 229! (I've wrapped the lines a little, but made no additional changes.)

After adding it to Git, I made some redundancy tweaks and asked a bunch of annoying questions that we'll probably want to figure out before implementing anything like this.

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 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