Hello all,
To address bug #10671: "Pluggable Transports: Improve method of transferring parameters to client-side transports", I submit the enclosed proposal for consideration.
--- Begin proposal body ---
Filename: xxx-pt-socks5-extensions.txt Title: Pluggable transport SOCKS5 extensions Author: Yawning Angel Created: 25-Feb-2014 Status: Draft
0. Abstract
We propose extending the SOCKS5 protocol when communicating with pluggable transports to allow passing more per-bridge meta-data to the transport and returning more meaningful connection failure response codes back to Tor.
1. Introduction
To allow for more sophisticated pluggable transports, it would be useful to support more than 510 bytes of per-connection data, while using the SOCKS5 pluggable transport interface. Additionally as pluggable transports increase in sophistication, it is useful for the pluggable transport to be able to return well defined errors back to Tor if the connection establishment fails.
2. Proposal
2.1. Tor Pluggable Transport Username/Password Authentication
We introduce a new authentication method to the SOCKS5 protocol based on the existing RFC 1929 Username/Password Authentication that pluggable SHOULD support.
The METHOD number to be returned to indicate support for or select this method is X'80', 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.
Tor will send a Username/Password/Extended Data request:
0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Version | Username Len | +---------------+---------------+ \ Username \ / ... / \ (Username Len bytes) \ +---------------+---------------+ | Password Len | \ +---------------+ / \ Password \ / ... / \ (Password Len bytes) \ +---------------+---------------+ | Extended Data Len | +---------------+---------------+ \ Extended Data \ / ... / \ (Extended Data Len bytes) \ +---------------+---------------+
Version: 8 bits (unsigned integer)
This field specifies the version of the authentication method. It MUST be set to X'01'.
Username Len: 8 bits (unsigned integer)
This field specifies the length of the Username field in bytes. It MAY be X'00', in which case the Username field is omitted.
Username: variable length, optional
The Username to use when authenticating.
Password Len: 8 bits (unsigned integer)
This field specifies the length of the Password field in bytes. It MAY be X'00', in which case the Password field is omitted.
Password: variable length, optional
The Password to use when authenticating.
Extended Data Len: 16 bits (unsigned integer)
This field specifies the length of the Extended Data field in bytes. It MAY be X'0000', in which case the Extended Data field is omitted. The Extended Data Len field MUST be transmitted in network byte order.
The pluggable transport verifies the supplied Username, Password, and Extended Data and sends the following response:
0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Version | Status | +---------------+---------------+
Version: 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)
This field specifies the status of the authentication request. A Status of X'00' indicates 'success'. If the pluggable transport returns a 'failure' (Status value other than X'00'), it MUST close the connection.
2.2. Tor Pluggable Transport SOCKS5 Reply Codes
We introduce the following additional SOCKS5 reply codes to be sent in the REP field of a SOCKS5 reply message.
Where:
* X'F0' Temporary 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 in the pluggable transport side that ignores unrecognised authentication methods in the negotiation phase.
The extended status codes are informative clarifications of a failure state, so existing Tor binaries will continue existing behavior for a general failure.
4. Security Considerations
Identical security considerations to RFC 1929 Username/Password authentication applies. As the Username/Password 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 pluggable transports bind to the loopback address, so in the current model this is believed to be acceptable.
5. Open Questions
Is 65535 bytes of per-bridge/per-connection data sufficient?
Pluggable transports currently have no notion of authentication due to the Username/Password fields of the RFC 1929 authentication method being hijacked to convey extended data. Is this a feature that will be implemented in the future?
6. References
Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., Jones L., "SOCKS Protocol Version 5", RFC 1928, March 1996.
Leech, M. "Username/Password Authentication for SOCKS V5", RFC 1929, March 1996.
Appelbaum, J., Mathewson, N., "Pluggable Transport Specification", June 2012.
--- End proposal body ---
Questions, comments, feedback appreciated.