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