home *** CD-ROM | disk | FTP | other *** search
/ Unix System Administration Handbook 1997 October / usah_oct97.iso / rfc / 1900s / rfc1928.txt < prev    next >
Text File  |  1996-03-28  |  20KB  |  508 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                           M. Leech
  8. Request for Comments: 1928                    Bell-Northern Research Ltd
  9. Category: Standards Track                                       M. Ganis
  10.                                          International Business Machines
  11.                                                                   Y. Lee
  12.                                                   NEC Systems Laboratory
  13.                                                                 R. Kuris
  14.                                                        Unify Corporation
  15.                                                                D. Koblas
  16.                                                   Independent Consultant
  17.                                                                 L. Jones
  18.                                                  Hewlett-Packard Company
  19.                                                               March 1996
  20.  
  21.  
  22.                         SOCKS Protocol Version 5
  23.  
  24. Status of this Memo
  25.  
  26.    This document specifies an Internet standards track protocol for the
  27.    Internet community, and requests discussion and suggestions for
  28.    improvements.  Please refer to the current edition of the "Internet
  29.    Official Protocol Standards" (STD 1) for the standardization state
  30.    and status of this protocol.  Distribution of this memo is unlimited.
  31.  
  32. Acknowledgments
  33.  
  34.    This memo describes a protocol that is an evolution of the previous
  35.    version of the protocol, version 4 [1]. This new protocol stems from
  36.    active discussions and prototype implementations.  The key
  37.    contributors are: Marcus Leech: Bell-Northern Research, David Koblas:
  38.    Independent Consultant, Ying-Da Lee: NEC Systems Laboratory, LaMont
  39.    Jones: Hewlett-Packard Company, Ron Kuris: Unify Corporation, Matt
  40.    Ganis: International Business Machines.
  41.  
  42. 1.  Introduction
  43.  
  44.    The use of network firewalls, systems that effectively isolate an
  45.    organizations internal network structure from an exterior network,
  46.    such as the INTERNET is becoming increasingly popular.  These
  47.    firewall systems typically act as application-layer gateways between
  48.    networks, usually offering controlled TELNET, FTP, and SMTP access.
  49.    With the emergence of more sophisticated application layer protocols
  50.    designed to facilitate global information discovery, there exists a
  51.    need to provide a general framework for these protocols to
  52.    transparently and securely traverse a firewall.
  53.  
  54.  
  55.  
  56.  
  57.  
  58. Leech, et al                Standards Track                     [Page 1]
  59.  
  60. RFC 1928                SOCKS Protocol Version 5              March 1996
  61.  
  62.  
  63.    There exists, also, a need for strong authentication of such
  64.    traversal in as fine-grained a manner as is practical. This
  65.    requirement stems from the realization that client-server
  66.    relationships emerge between the networks of various organizations,
  67.    and that such relationships need to be controlled and often strongly
  68.    authenticated.
  69.  
  70.    The protocol described here is designed to provide a framework for
  71.    client-server applications in both the TCP and UDP domains to
  72.    conveniently and securely use the services of a network firewall.
  73.    The protocol is conceptually a "shim-layer" between the application
  74.    layer and the transport layer, and as such does not provide network-
  75.    layer gateway services, such as forwarding of ICMP messages.
  76.  
  77. 2.  Existing practice
  78.  
  79.    There currently exists a protocol, SOCKS Version 4, that provides for
  80.    unsecured firewall traversal for TCP-based client-server
  81.    applications, including TELNET, FTP and the popular information-
  82.    discovery protocols such as HTTP, WAIS and GOPHER.
  83.  
  84.    This new protocol extends the SOCKS Version 4 model to include UDP,
  85.    and extends the framework to include provisions for generalized
  86.    strong authentication schemes, and extends the addressing scheme to
  87.    encompass domain-name and V6 IP addresses.
  88.  
  89.    The implementation of the SOCKS protocol typically involves the
  90.    recompilation or relinking of TCP-based client applications to use
  91.    the appropriate encapsulation routines in the SOCKS library.
  92.  
  93. Note:
  94.  
  95.    Unless otherwise noted, the decimal numbers appearing in packet-
  96.    format diagrams represent the length of the corresponding field, in
  97.    octets.  Where a given octet must take on a specific value, the
  98.    syntax X'hh' is used to denote the value of the single octet in that
  99.    field. When the word 'Variable' is used, it indicates that the
  100.    corresponding field has a variable length defined either by an
  101.    associated (one or two octet) length field, or by a data type field.
  102.  
  103. 3.  Procedure for TCP-based clients
  104.  
  105.    When a TCP-based client wishes to establish a connection to an object
  106.    that is reachable only via a firewall (such determination is left up
  107.    to the implementation), it must open a TCP connection to the
  108.    appropriate SOCKS port on the SOCKS server system.  The SOCKS service
  109.    is conventionally located on TCP port 1080.  If the connection
  110.    request succeeds, the client enters a negotiation for the
  111.  
  112.  
  113.  
  114. Leech, et al                Standards Track                     [Page 2]
  115.  
  116. RFC 1928                SOCKS Protocol Version 5              March 1996
  117.  
  118.  
  119.    authentication method to be used, authenticates with the chosen
  120.    method, then sends a relay request.  The SOCKS server evaluates the
  121.    request, and either establishes the appropriate connection or denies
  122.    it.
  123.  
  124.    Unless otherwise noted, the decimal numbers appearing in packet-
  125.    format diagrams represent the length of the corresponding field, in
  126.    octets.  Where a given octet must take on a specific value, the
  127.    syntax X'hh' is used to denote the value of the single octet in that
  128.    field. When the word 'Variable' is used, it indicates that the
  129.    corresponding field has a variable length defined either by an
  130.    associated (one or two octet) length field, or by a data type field.
  131.  
  132.    The client connects to the server, and sends a version
  133.    identifier/method selection message:
  134.  
  135.                    +----+----------+----------+
  136.                    |VER | NMETHODS | METHODS  |
  137.                    +----+----------+----------+
  138.                    | 1  |    1     | 1 to 255 |
  139.                    +----+----------+----------+
  140.  
  141.    The VER field is set to X'05' for this version of the protocol.  The
  142.    NMETHODS field contains the number of method identifier octets that
  143.    appear in the METHODS field.
  144.  
  145.    The server selects from one of the methods given in METHODS, and
  146.    sends a METHOD selection message:
  147.  
  148.                          +----+--------+
  149.                          |VER | METHOD |
  150.                          +----+--------+
  151.                          | 1  |   1    |
  152.                          +----+--------+
  153.  
  154.    If the selected METHOD is X'FF', none of the methods listed by the
  155.    client are acceptable, and the client MUST close the connection.
  156.  
  157.    The values currently defined for METHOD are:
  158.  
  159.           o  X'00' NO AUTHENTICATION REQUIRED
  160.           o  X'01' GSSAPI
  161.           o  X'02' USERNAME/PASSWORD
  162.           o  X'03' to X'7F' IANA ASSIGNED
  163.           o  X'80' to X'FE' RESERVED FOR PRIVATE METHODS
  164.           o  X'FF' NO ACCEPTABLE METHODS
  165.  
  166.    The client and server then enter a method-specific sub-negotiation.
  167.  
  168.  
  169.  
  170. Leech, et al                Standards Track                     [Page 3]
  171.  
  172. RFC 1928                SOCKS Protocol Version 5              March 1996
  173.  
  174.  
  175.    Descriptions of the method-dependent sub-negotiations appear in
  176.    separate memos.
  177.  
  178.    Developers of new METHOD support for this protocol should contact
  179.    IANA for a METHOD number.  The ASSIGNED NUMBERS document should be
  180.    referred to for a current list of METHOD numbers and their
  181.    corresponding protocols.
  182.  
  183.    Compliant implementations MUST support GSSAPI and SHOULD support
  184.    USERNAME/PASSWORD authentication methods.
  185.  
  186. 4.  Requests
  187.  
  188.    Once the method-dependent subnegotiation has completed, the client
  189.    sends the request details.  If the negotiated method includes
  190.    encapsulation for purposes of integrity checking and/or
  191.    confidentiality, these requests MUST be encapsulated in the method-
  192.    dependent encapsulation.
  193.  
  194.    The SOCKS request is formed as follows:
  195.  
  196.         +----+-----+-------+------+----------+----------+
  197.         |VER | CMD |  RSV  | ATYP | DST.ADDR | DST.PORT |
  198.         +----+-----+-------+------+----------+----------+
  199.         | 1  |  1  | X'00' |  1   | Variable |    2     |
  200.         +----+-----+-------+------+----------+----------+
  201.  
  202.      Where:
  203.  
  204.           o  VER    protocol version: X'05'
  205.           o  CMD
  206.              o  CONNECT X'01'
  207.              o  BIND X'02'
  208.              o  UDP ASSOCIATE X'03'
  209.           o  RSV    RESERVED
  210.           o  ATYP   address type of following address
  211.              o  IP V4 address: X'01'
  212.              o  DOMAINNAME: X'03'
  213.              o  IP V6 address: X'04'
  214.           o  DST.ADDR       desired destination address
  215.           o  DST.PORT desired destination port in network octet
  216.              order
  217.  
  218.    The SOCKS server will typically evaluate the request based on source
  219.    and destination addresses, and return one or more reply messages, as
  220.    appropriate for the request type.
  221.  
  222.  
  223.  
  224.  
  225.  
  226. Leech, et al                Standards Track                     [Page 4]
  227.  
  228. RFC 1928                SOCKS Protocol Version 5              March 1996
  229.  
  230.  
  231. 5.  Addressing
  232.  
  233.    In an address field (DST.ADDR, BND.ADDR), the ATYP field specifies
  234.    the type of address contained within the field:
  235.  
  236.           o  X'01'
  237.  
  238.    the address is a version-4 IP address, with a length of 4 octets
  239.  
  240.           o  X'03'
  241.  
  242.    the address field contains a fully-qualified domain name.  The first
  243.    octet of the address field contains the number of octets of name that
  244.    follow, there is no terminating NUL octet.
  245.  
  246.           o  X'04'
  247.  
  248.    the address is a version-6 IP address, with a length of 16 octets.
  249.  
  250. 6.  Replies
  251.  
  252.    The SOCKS request information is sent by the client as soon as it has
  253.    established a connection to the SOCKS server, and completed the
  254.    authentication negotiations.  The server evaluates the request, and
  255.    returns a reply formed as follows:
  256.  
  257.         +----+-----+-------+------+----------+----------+
  258.         |VER | REP |  RSV  | ATYP | BND.ADDR | BND.PORT |
  259.         +----+-----+-------+------+----------+----------+
  260.         | 1  |  1  | X'00' |  1   | Variable |    2     |
  261.         +----+-----+-------+------+----------+----------+
  262.  
  263.      Where:
  264.  
  265.           o  VER    protocol version: X'05'
  266.           o  REP    Reply field:
  267.              o  X'00' succeeded
  268.              o  X'01' general SOCKS server failure
  269.              o  X'02' connection not allowed by ruleset
  270.              o  X'03' Network unreachable
  271.              o  X'04' Host unreachable
  272.              o  X'05' Connection refused
  273.              o  X'06' TTL expired
  274.              o  X'07' Command not supported
  275.              o  X'08' Address type not supported
  276.              o  X'09' to X'FF' unassigned
  277.           o  RSV    RESERVED
  278.           o  ATYP   address type of following address
  279.  
  280.  
  281.  
  282. Leech, et al                Standards Track                     [Page 5]
  283.  
  284. RFC 1928                SOCKS Protocol Version 5              March 1996
  285.  
  286.  
  287.              o  IP V4 address: X'01'
  288.              o  DOMAINNAME: X'03'
  289.              o  IP V6 address: X'04'
  290.           o  BND.ADDR       server bound address
  291.           o  BND.PORT       server bound port in network octet order
  292.  
  293.    Fields marked RESERVED (RSV) must be set to X'00'.
  294.  
  295.    If the chosen method includes encapsulation for purposes of
  296.    authentication, integrity and/or confidentiality, the replies are
  297.    encapsulated in the method-dependent encapsulation.
  298.  
  299. CONNECT
  300.  
  301.    In the reply to a CONNECT, BND.PORT contains the port number that the
  302.    server assigned to connect to the target host, while BND.ADDR
  303.    contains the associated IP address.  The supplied BND.ADDR is often
  304.    different from the IP address that the client uses to reach the SOCKS
  305.    server, since such servers are often multi-homed.  It is expected
  306.    that the SOCKS server will use DST.ADDR and DST.PORT, and the
  307.    client-side source address and port in evaluating the CONNECT
  308.    request.
  309.  
  310. BIND
  311.  
  312.    The BIND request is used in protocols which require the client to
  313.    accept connections from the server.  FTP is a well-known example,
  314.    which uses the primary client-to-server connection for commands and
  315.    status reports, but may use a server-to-client connection for
  316.    transferring data on demand (e.g. LS, GET, PUT).
  317.  
  318.    It is expected that the client side of an application protocol will
  319.    use the BIND request only to establish secondary connections after a
  320.    primary connection is established using CONNECT.  In is expected that
  321.    a SOCKS server will use DST.ADDR and DST.PORT in evaluating the BIND
  322.    request.
  323.  
  324.    Two replies are sent from the SOCKS server to the client during a
  325.    BIND operation.  The first is sent after the server creates and binds
  326.    a new socket.  The BND.PORT field contains the port number that the
  327.    SOCKS server assigned to listen for an incoming connection.  The
  328.    BND.ADDR field contains the associated IP address.  The client will
  329.    typically use these pieces of information to notify (via the primary
  330.    or control connection) the application server of the rendezvous
  331.    address.  The second reply occurs only after the anticipated incoming
  332.    connection succeeds or fails.
  333.  
  334.  
  335.  
  336.  
  337.  
  338. Leech, et al                Standards Track                     [Page 6]
  339.  
  340. RFC 1928                SOCKS Protocol Version 5              March 1996
  341.  
  342.  
  343.    In the second reply, the BND.PORT and BND.ADDR fields contain the
  344.    address and port number of the connecting host.
  345.  
  346. UDP ASSOCIATE
  347.  
  348.    The UDP ASSOCIATE request is used to establish an association within
  349.    the UDP relay process to handle UDP datagrams.  The DST.ADDR and
  350.    DST.PORT fields contain the address and port that the client expects
  351.    to use to send UDP datagrams on for the association.  The server MAY
  352.    use this information to limit access to the association.  If the
  353.    client is not in possesion of the information at the time of the UDP
  354.    ASSOCIATE, the client MUST use a port number and address of all
  355.    zeros.
  356.  
  357.    A UDP association terminates when the TCP connection that the UDP
  358.    ASSOCIATE request arrived on terminates.
  359.  
  360.    In the reply to a UDP ASSOCIATE request, the BND.PORT and BND.ADDR
  361.    fields indicate the port number/address where the client MUST send
  362.    UDP request messages to be relayed.
  363.  
  364. Reply Processing
  365.  
  366.    When a reply (REP value other than X'00') indicates a failure, the
  367.    SOCKS server MUST terminate the TCP connection shortly after sending
  368.    the reply.  This must be no more than 10 seconds after detecting the
  369.    condition that caused a failure.
  370.  
  371.    If the reply code (REP value of X'00') indicates a success, and the
  372.    request was either a BIND or a CONNECT, the client may now start
  373.    passing data.  If the selected authentication method supports
  374.    encapsulation for the purposes of integrity, authentication and/or
  375.    confidentiality, the data are encapsulated using the method-dependent
  376.    encapsulation.  Similarly, when data arrives at the SOCKS server for
  377.    the client, the server MUST encapsulate the data as appropriate for
  378.    the authentication method in use.
  379.  
  380. 7.  Procedure for UDP-based clients
  381.  
  382.    A UDP-based client MUST send its datagrams to the UDP relay server at
  383.    the UDP port indicated by BND.PORT in the reply to the UDP ASSOCIATE
  384.    request.  If the selected authentication method provides
  385.    encapsulation for the purposes of authenticity, integrity, and/or
  386.    confidentiality, the datagram MUST be encapsulated using the
  387.    appropriate encapsulation.  Each UDP datagram carries a UDP request
  388.    header with it:
  389.  
  390.  
  391.  
  392.  
  393.  
  394. Leech, et al                Standards Track                     [Page 7]
  395.  
  396. RFC 1928                SOCKS Protocol Version 5              March 1996
  397.  
  398.  
  399.       +----+------+------+----------+----------+----------+
  400.       |RSV | FRAG | ATYP | DST.ADDR | DST.PORT |   DATA   |
  401.       +----+------+------+----------+----------+----------+
  402.       | 2  |  1   |  1   | Variable |    2     | Variable |
  403.       +----+------+------+----------+----------+----------+
  404.  
  405.      The fields in the UDP request header are:
  406.  
  407.           o  RSV  Reserved X'0000'
  408.           o  FRAG    Current fragment number
  409.           o  ATYP    address type of following addresses:
  410.              o  IP V4 address: X'01'
  411.              o  DOMAINNAME: X'03'
  412.              o  IP V6 address: X'04'
  413.           o  DST.ADDR       desired destination address
  414.           o  DST.PORT       desired destination port
  415.           o  DATA     user data
  416.  
  417.    When a UDP relay server decides to relay a UDP datagram, it does so
  418.    silently, without any notification to the requesting client.
  419.    Similarly, it will drop datagrams it cannot or will not relay.  When
  420.    a UDP relay server receives a reply datagram from a remote host, it
  421.    MUST encapsulate that datagram using the above UDP request header,
  422.    and any authentication-method-dependent encapsulation.
  423.  
  424.    The UDP relay server MUST acquire from the SOCKS server the expected
  425.    IP address of the client that will send datagrams to the BND.PORT
  426.    given in the reply to UDP ASSOCIATE.  It MUST drop any datagrams
  427.    arriving from any source IP address other than the one recorded for
  428.    the particular association.
  429.  
  430.    The FRAG field indicates whether or not this datagram is one of a
  431.    number of fragments.  If implemented, the high-order bit indicates
  432.    end-of-fragment sequence, while a value of X'00' indicates that this
  433.    datagram is standalone.  Values between 1 and 127 indicate the
  434.    fragment position within a fragment sequence.  Each receiver will
  435.    have a REASSEMBLY QUEUE and a REASSEMBLY TIMER associated with these
  436.    fragments.  The reassembly queue must be reinitialized and the
  437.    associated fragments abandoned whenever the REASSEMBLY TIMER expires,
  438.    or a new datagram arrives carrying a FRAG field whose value is less
  439.    than the highest FRAG value processed for this fragment sequence.
  440.    The reassembly timer MUST be no less than 5 seconds.  It is
  441.    recommended that fragmentation be avoided by applications wherever
  442.    possible.
  443.  
  444.    Implementation of fragmentation is optional; an implementation that
  445.    does not support fragmentation MUST drop any datagram whose FRAG
  446.    field is other than X'00'.
  447.  
  448.  
  449.  
  450. Leech, et al                Standards Track                     [Page 8]
  451.  
  452. RFC 1928                SOCKS Protocol Version 5              March 1996
  453.  
  454.  
  455.    The programming interface for a SOCKS-aware UDP MUST report an
  456.    available buffer space for UDP datagrams that is smaller than the
  457.    actual space provided by the operating system:
  458.  
  459.           o  if ATYP is X'01' - 10+method_dependent octets smaller
  460.           o  if ATYP is X'03' - 262+method_dependent octets smaller
  461.           o  if ATYP is X'04' - 20+method_dependent octets smaller
  462.  
  463. 8.  Security Considerations
  464.  
  465.    This document describes a protocol for the application-layer
  466.    traversal of IP network firewalls.  The security of such traversal is
  467.    highly dependent on the particular authentication and encapsulation
  468.    methods provided in a particular implementation, and selected during
  469.    negotiation between SOCKS client and SOCKS server.
  470.  
  471.    Careful consideration should be given by the administrator to the
  472.    selection of authentication methods.
  473.  
  474. 9.  References
  475.  
  476.    [1] Koblas, D., "SOCKS", Proceedings: 1992 Usenix Security Symposium.
  477.  
  478. Author's Address
  479.  
  480.        Marcus Leech
  481.        Bell-Northern Research Ltd
  482.        P.O. Box 3511, Stn. C,
  483.        Ottawa, ON
  484.        CANADA K1Y 4H7
  485.  
  486.        Phone: (613) 763-9145
  487.        EMail: mleech@bnr.ca
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506. Leech, et al                Standards Track                     [Page 9]
  507.  
  508.