home *** CD-ROM | disk | FTP | other *** search
/ Unix System Administration Handbook 1997 October / usah_oct97.iso / rfc / 1900s / rfc1961.txt < prev    next >
Text File  |  1996-06-05  |  16KB  |  508 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                         P. McMahon
  8. Request for Comments: 1961                                           ICL
  9. Category: Standards Track                                      June 1996
  10.  
  11.  
  12.            GSS-API Authentication Method for SOCKS Version 5
  13.  
  14. Status of this Memo
  15.  
  16.    This document specifies an Internet standards track protocol for the
  17.    Internet community, and requests discussion and suggestions for
  18.    improvements.  Please refer to the current edition of the "Internet
  19.    Official Protocol Standards" (STD 1) for the standardization state
  20.    and status of this protocol.  Distribution of this memo is unlimited.
  21.  
  22. Table of Contents
  23.  
  24.          1. Purpose ............................................ 1
  25.          2. Introduction ....................................... 1
  26.          3. GSS-API Security Context Establishment ............. 2
  27.          4. GSS-API Protection-level Options ................... 5
  28.          5. GSS-API Per-message Protection ..................... 7
  29.          6. GSS-API Security Context Termination ............... 8
  30.          7. References ......................................... 8
  31.          8. Acknowledgments .................................... 8
  32.          9. Security Considerations ............................ 8
  33.          10. Author's Address .................................. 9
  34.  
  35. 1. Purpose
  36.  
  37.    The protocol specification for SOCKS Version 5 specifies a
  38.    generalized framework for the use of arbitrary authentication
  39.    protocols in the initial SOCKS connection setup.  This document
  40.    provides the specification for the SOCKS V5 GSS-API authentication
  41.    protocol, and defines a GSS-API-based encapsulation for provision of
  42.    integrity, authentication and optional confidentiality.
  43.  
  44. 2. Introduction
  45.  
  46.    GSS-API provides an abstract interface which provides security
  47.    services for use in distributed applications, but isolates callers
  48.    from specific security mechanisms and implementations.
  49.  
  50.    GSS-API peers achieve interoperability by establishing a common
  51.    security mechanism for security context establishment - either
  52.    through administrative action, or through negotiation.  GSS-API is
  53.    specified in [RFC 1508], and [RFC 1509].  This specification is
  54.    intended for use with implementations of GSS-API, and the emerging
  55.  
  56.  
  57.  
  58. McMahon                     Standards Track                     [Page 1]
  59.  
  60. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  61.  
  62.  
  63.    GSS-API V2 specification.
  64.  
  65.    The approach for use of GSS-API in SOCKS V5 is to authenticate the
  66.    client and server by successfully establishing a GSS-API security
  67.    context - such that the GSS-API encapsulates any negotiation protocol
  68.    for mechanism selection, and the agreement of security service
  69.    options.
  70.  
  71.    The GSS-API enables the context initiator to know what security
  72.    services the target supports for the chosen mechanism.  The required
  73.    level of protection is then agreed by negotiation.
  74.  
  75.    The GSS-API per-message protection calls are subsequently used to
  76.    encapsulate any further TCP and UDP traffic between client and
  77.    server.
  78.  
  79. 3. GSS-API Security Context Establishment
  80.  
  81. 3.1 Preparation
  82.  
  83.    Prior to use of GSS-API primitives, the client and server should be
  84.    locally authenticated, and have established default GSS-API
  85.    credentials.
  86.  
  87.    The client should call gss_import_name to obtain an internal
  88.    representation of the server name.  For maximal portability the
  89.    default name_type GSS_C_NULL_OID should be used to specify the
  90.    default name space, and the input name_string should treated by the
  91.    client's code as an opaque name-space specific input.
  92.  
  93.    For example, when using Kerberos V5 naming, the imported name may be
  94.    of the form "SERVICE:socks@socks_server_hostname" where
  95.    "socks_server_hostname" is the fully qualified host name of the
  96.    server with all letters in lower case. Other mechanisms may, however,
  97.    have different name forms, so the client should not make assumptions
  98.    about the name syntax.
  99.  
  100. 3.2 Client Context Establishment
  101.  
  102.    The client should then call gss_init_sec_context, typically passing:
  103.  
  104.          GSS_C_NO_CREDENTIAL into cred_handle to specify the default
  105.          credential (for initiator usage),
  106.  
  107.          GSS_C_NULL_OID into mech_type to specify the default
  108.          mechanism,
  109.  
  110.  
  111.  
  112.  
  113.  
  114. McMahon                     Standards Track                     [Page 2]
  115.  
  116. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  117.  
  118.  
  119.          GSS_C_NO_CONTEXT into context_handle to specify a NULL
  120.          context (initially), and,
  121.  
  122.          the previously imported server name into target_name.
  123.  
  124.    The client must also specify its requirements for replay protection,
  125.    delegation, and sequence protection via the gss_init_sec_context
  126.    req_flags parameter.  It is required by this specification that the
  127.    client always requests these service options (i.e. passes
  128.    GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG | GSS_C_DELEG_FLAG |
  129.    GSS_C_SEQUENCE_FLAG into req_flags).
  130.  
  131.    However, GSS_C_SEQUENCE_FLAG should only be passed in for TCP-based
  132.    clients, not for UDP-based clients.
  133.  
  134. 3.3 Client Context Establishment Major Status codes
  135.  
  136.    The gss_init_sec_context returned status code can take two different
  137.    success values:
  138.  
  139.     - If gss_init_sec_context returns GSS_S_CONTINUE_NEEDED, then the
  140.       client should expect the server to issue a token in the
  141.       subsequent subnegotiation response.  The client must pass the
  142.       token to another call to gss_init_sec_context, and repeat this
  143.       procedure until "continue" operations are complete.
  144.  
  145.     - If gss_init_sec_context returns GSS_S_COMPLETE, then the client
  146.       should respond to the server with any resulting output_token.
  147.  
  148.       If there is no output_token, the client should proceed to send
  149.       the protected request details, including any required message
  150.       protection subnegotiation as specified in sections 4 and 5
  151.       below.
  152.  
  153. 3.4 Client initial token
  154.  
  155.    The client's GSS-API implementation then typically responds with the
  156.    resulting output_token which the client sends in a message to the
  157.    server.
  158.  
  159.     +------+------+------+.......................+
  160.     + ver  | mtyp | len  |       token           |
  161.     +------+------+------+.......................+
  162.     + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets |
  163.     +------+------+------+.......................+
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170. McMahon                     Standards Track                     [Page 3]
  171.  
  172. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  173.  
  174.  
  175.     Where:
  176.  
  177.     - "ver" is the protocol version number, here 1 to represent the
  178.       first version of the SOCKS/GSS-API protocol
  179.  
  180.     - "mtyp" is the message type, here 1 to represent an
  181.       authentication message
  182.  
  183.     - "len" is the length of the "token" field in octets
  184.  
  185.     - "token" is the opaque authentication token emitted by GSS-API
  186.  
  187. 3.5 Client GSS-API Initialisation Failure
  188.  
  189.    If, however, the client's GSS-API implementation failed during
  190.    gss_init_sec_context, the client must close its connection to the
  191.    server.
  192.  
  193. 3.6 Server Context Establishment
  194.  
  195.    For the case where a client successfully sends a token emitted by
  196.    gss_init_sec_context() to the server, the server must pass the
  197.    client-supplied token to gss_accept_sec_context as input_token.
  198.  
  199.    When calling gss_accept_sec_context() for the first time, the
  200.    context_handle argument is initially set to GSS_C_NO_CONTEXT.
  201.  
  202.    For portability, verifier_cred_handle is set to GSS_C_NO_CREDENTIAL
  203.    to specify default credentials (for acceptor usage).
  204.  
  205.    If gss_accept_sec_context returns GSS_CONTINUE_NEEDED, the server
  206.    should return the generated output_token to the client, and
  207.    subsequently pass the resulting client supplied token to another call
  208.    to gss_accept_sec_context.
  209.  
  210.    If gss_accept_sec_context returns GSS_S_COMPLETE, then, if an
  211.    output_token is returned, the server should return it to the client.
  212.  
  213.    If no token is returned, a zero length token should be sent by the
  214.    server to signal to the client that it is ready to receive the
  215.    client's request.
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226. McMahon                     Standards Track                     [Page 4]
  227.  
  228. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  229.  
  230.  
  231. 3.7 Server Reply
  232.  
  233.    In all continue/confirmation cases, the server uses the same message
  234.    type as for the client -> server interaction.
  235.  
  236.     +------+------+------+.......................+
  237.     + ver  | mtyp | len  |       token           |
  238.     +------+------+------+.......................+
  239.     + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets |
  240.     +------+------+------+.......................+
  241.  
  242. 3.8 Security Context Failure
  243.  
  244.    If the server refuses the client's connection for any reason (GSS-API
  245.    authentication failure or otherwise), it will return:
  246.  
  247.     +------+------+
  248.     + ver  | mtyp |
  249.     +------+------+
  250.     + 0x01 | 0xff |
  251.     +------+------+
  252.  
  253.     Where:
  254.  
  255.     - "ver" is the protocol version number, here 1 to represent the
  256.       first version of the SOCKS/GSS-API protocol
  257.  
  258.     - "mtyp" is the message type, here 0xff to represent an abort
  259.       message
  260.  
  261. 4. GSS-API Protection-level Options
  262.  
  263. 4.1 Message protection
  264.  
  265.    Establishment of a GSS-API security context enables comunicating
  266.    peers to determine which per-message protection services are
  267.    available to them through the gss_init_sec_context() and
  268.    gss_accept_sec_context() ret_flags GSS_C_INTEG_FLAG and
  269.    GSS_C_CONF_FLAG which respectively indicate message integrity and
  270.    confidentiality services.
  271.  
  272.    It is necessary to ensure that the message protection applied to the
  273.    traffic is appropriate to the sensitivity of the data, and the
  274.    severity of the threats.
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282. McMahon                     Standards Track                     [Page 5]
  283.  
  284. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  285.  
  286.  
  287. 4.2 Message Protection Subnegotiation
  288.  
  289.    For TCP and UDP clients and servers, different levels of protection
  290.    are possible in the SOCKS V5 protocol, so an additional
  291.    subnegotiation stage is needed to agree the message protection level.
  292.    After successful completion of this subnegotiation, TCP and UDP
  293.    clients and servers use GSS-API encapsulation as defined in section
  294.    5.1.
  295.  
  296.    After successful establishment of a GSS-API security context, the
  297.    client's GSS-API implementation sends its required security context
  298.    protection level to the server.  The server then returns the security
  299.    context protection level which it agrees to - which may or may not
  300.    take the the client's request into account.
  301.  
  302.    The security context protection level sent by client and server must
  303.    be one of the following values:
  304.  
  305.          1 required per-message integrity
  306.          2 required per-message integrity and confidentiality
  307.          3 selective per-message integrity or confidentiality based on
  308.            local client and server configurations
  309.  
  310.    It is anticipated that most implementations will agree on level 1 or
  311.    2 due to the practical difficulties in applying selective controls to
  312.    messages passed through a socks library.
  313.  
  314. 4.3 Message Protection Subnegotiation Message Format
  315.  
  316.    The security context protection level is sent from client to server
  317.    and vice versa using the following protected message format:
  318.  
  319.     +------+------+------+.......................+
  320.     + ver  | mtyp | len  |   token               |
  321.     +------+------+------+.......................+
  322.     + 0x01 | 0x02 | 0x02 | up to 2^16 - 1 octets |
  323.     +------+------+------+.......................+
  324.  
  325.     Where:
  326.  
  327.     - "ver" is the protocol version number, here 1 to represent the
  328.       first version of the SOCKS/GSS-API protocol
  329.  
  330.     - "mtyp" is the message type, here 2 to represent a protection
  331.       -level negotiation message
  332.  
  333.     - "len" is the length of the "token" field in octets
  334.  
  335.  
  336.  
  337.  
  338. McMahon                     Standards Track                     [Page 6]
  339.  
  340. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  341.  
  342.  
  343.     - "token" is the GSS-API encapsulated protection level
  344.  
  345. 4.4 Message Protection Subnegotiation Message Generation
  346.  
  347.    The token is produced by encapsulating an octet containing the
  348.    required protection level using gss_seal()/gss_wrap() with conf_req
  349.    set to FALSE.  The token is verified using gss_unseal()/
  350.    gss_unwrap().
  351.  
  352.    If the server's choice of protection level is unacceptable to the
  353.    client, then the client must close its connection to the server
  354.  
  355. 5. GSS-API Per-message Protection
  356.  
  357.    For TCP and UDP clients and servers, the GSS-API functions for
  358.    encapsulation and de-encapsulation shall be used by implementations -
  359.    i.e. gss_seal()/gss_wrap(), and gss_unseal()/ gss_unwrap().
  360.  
  361.    The default value of quality of protection shall be specified, and
  362.    the use of conf_req_flag shall be as determined by the previous
  363.    subnegotiation step.  If protection level 1 is agreed then
  364.    conf_req_flag MUST always be FALSE; if protection level 2 is agreed
  365.    then conf_req_flag MUST always be TRUE; and if protection level 3 is
  366.    agreed then conf_req is determined on a per-message basis by client
  367.    and server using local configuration.
  368.  
  369.    All encapsulated messages are prefixed by the following framing:
  370.  
  371.     +------+------+------+.......................+
  372.     + ver  | mtyp | len  |       token           |
  373.     +------+------+------+.......................+
  374.     + 0x01 | 0x03 | 0x02 | up to 2^16 - 1 octets |
  375.     +------+------+------+.......................+
  376.  
  377.     Where:
  378.  
  379.     - "ver" is the protocol version number, here 1 to represent the
  380.       first version of the SOCKS/GSS-API protocol
  381.  
  382.     - "mtyp" is the message type, here 3 to represent encapulated user
  383.       data
  384.  
  385.     - "len" is the length of the "token" field in octets
  386.  
  387.     - "token" is the user data encapsulated by GSS-API
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394. McMahon                     Standards Track                     [Page 7]
  395.  
  396. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  397.  
  398.  
  399. 6. GSS-API Security Context Termination
  400.  
  401.    The GSS-API context termination message (emitted by
  402.    gss_delete_sec_context) is not used by this protocol.
  403.  
  404.    When the connection is closed, each peer invokes
  405.    gss_delete_sec_context() passing GSS_C_NO_BUFFER into the
  406.    output_token argument.
  407.  
  408. 7. References
  409.  
  410.     [RFC 1508] Linn, J., "Generic Security Service API",
  411.                September 1993.
  412.  
  413.     [RFC 1509] Wray, J., "Generic Security Service API : C-bindings",
  414.                September 1993.
  415.  
  416.     [SOCKS V5] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D.,
  417.                and L. Jones, "SOCKS Protocol V5", RFC 1928, April
  418.                1996.
  419.  
  420. 8. Acknowledgment
  421.  
  422.    This document builds from a previous memo produced by Marcus Leech
  423.    (BNR) - whose comments are gratefully acknowleged.  It also reflects
  424.    input from the AFT WG, and comments arising from implementation
  425.    experience by Xavier Gosselin (IUT Lyons).
  426.  
  427. 9. Security Considerations
  428.  
  429.    The security services provided through the GSS-API are entirely
  430.    dependent on the effectiveness of the underlying security mechanisms,
  431.    and the correctness of the implementation of the underlying
  432.    algorithms and protocols.
  433.  
  434.    The user of a GSS-API service must ensure that the quality of
  435.    protection provided by the mechanism implementation is consistent
  436.    with their security policy.
  437.  
  438.    In addition, where negotiation is supported under the GSS-API,
  439.    constraints on acceptable mechanisms may be imposed to ensure
  440.    suitability for application to authenticated firewall traversal.
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450. McMahon                     Standards Track                     [Page 8]
  451.  
  452. RFC 1961          GSS-API Authentication for SOCKS V5          June 1996
  453.  
  454.  
  455. 10. Author's Address
  456.  
  457.    P. V. McMahon
  458.    ICL Enterprises
  459.    Kings House
  460.    33 Kings Road
  461.    Reading, RG1 3PX
  462.    UK
  463.  
  464.    EMail: p.v.mcmahon@rea0803.wins.icl.co.uk
  465.    Phone: +44 1734 634882
  466.    Fax:   +44 1734 855106
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506. McMahon                     Standards Track                     [Page 9]
  507.  
  508.