[tor-dev] [draft]: Proposal xxx: Pluggable transport SOCKS5 extensions

[Yawning Angel]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://lists.torproject.org/pipermail/tor-dev/attachments/20140225/35854ef8/attachment-0001.sig>