[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

Re: [tor-dev] Proposal xxx: Further SOCKS5 extensions (Was Pluggable transport SOCKS5 extensions)



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,

-- 
Yawning Angel


--- Begin proposal body ---

Filename: xxx-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 reponse 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.

   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.  The NR
       PAIRS field MUST be transmitted in network byte order.

    KLEN: 16 bits (unsigned integer)

       This field specifies the length of the key in bytes.  It MUST be
       transmitted in network byte order, and 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 NULL terminator.

    VLEN: 16 bits (unsigned integer)

       This field specifies the length of the value in bytes.  It MUST be
       tramsmitted in network byte order.  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 followint 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.

    NR PAIRS: 16 bits (unsigned integer)

       This field specifies the number of key/value pairs to follow.  The NR
       PAIRS field MUST be transmitted in network byte order.

    KLEN: 16 bits (unsigned integer)

       This field specifies the length of the key in bytes.  It MUST be
       transmitted in network byte order, and 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 NULL terminator.

    VLEN: 16 bits (unsigned integer)

       This field specifies the length of the value in bytes.  It MUST be
       tramsmitted in network byte order.  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 currently defined KEYs are:

    * "UNAME" The username for authentication.
    * "PASSWD" The password for authentication.

    [XXX - Add some more here, Stream isolation?]

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.

   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 the UNAME/PASSWD 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 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)]

   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

--- End proposal body ---

Attachment: signature.asc
Description: PGP signature

_______________________________________________
tor-dev mailing list
tor-dev@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev