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.
--
Yawning Angel
Attachment:
signature.asc
Description: PGP signature
_______________________________________________ tor-dev mailing list tor-dev@xxxxxxxxxxxxxxxxxxxx https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev