Internet-Draft                      GSS-API Authentication for SOCKS V5
    Expires: 25SEP95                                                24MAR95
    <draft-ietf-aft-gssapi-00.txt> 29SEP95                                                29MAR95
    <draft-ietf-aft-gssapi-01.txt>                         P V McMahon, ICL

                GSS-API Authentication Method for SOCKS Version 5

    Status of this Memo

       This document is an Internet-Draft. Internet-Drafts are working
       documents of the Internet Engineering Task Force (IETF), its areas,
       and its working groups. Note that other groups may also distribute
       working documents as Internet-Drafts.

       Internet-Drafts are draft document valid for a maximum of six months
       and may be updated, replaced or obsoleted by other documents at any
       time. It is inappropriate to use Internet-Drafts as reference
       material or to cite them other than as "work in progress".

       To learn the current status of any Internet-Draft, please check the
       "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
       Directories on (US East Coast),
       (Europe), (US West Coast), or (Pacific

       Comments on this document are welcome and should be sent to, the mailing list of the Authenticated Firewall
       Traversal Working Group of the IETF.

    Contents List

         1. Purpose
         2. Introduction
         3. GSS-API Call Specification for SOCKS V5 Security Context Establishment
         4. References GSS-API Protection-level Options
         5. Acknowledgments GSS-API Per-message Protection
         6. References
         7. Acknowledgments
         8. Security Considerations
         9. Author's Address

    1. Purpose

    The protocol specification for SOCKS Version 5 specifies a generalized
    framework for the use of arbitrary authentication protocols in the
    initial SOCKS connection setup.  This document provides the
    specification for the SOCKS V5 GSS-API authentication protocol, and
    defines an GSS-API authentication method a GSS-API-based encapsulation that provides for provision of integrity,
    authentication and optional confidentiality.

    Internet-Draft                      GSS-API Authentication for SOCKS V5

    2. Introduction

    GSS-API provides an abstract interface which provides security services
    for use in distributed applications, but isolates callers from specific
    security mechanisms and implementations.

    GSS-API peers achieve interoperability by establishing a common
    security mechanism for security context establishment - either through
    administrative action, or through negotiation.  GSS-API is specified in
    [RFC 1508], and [RFC 1509].

    The approach for use of GSS-API in SOCKS V5 is to authenticate the
    client and server by successfully establishing a GSS-API security
    context - such that the GSS-API encapsulates any negotiation protocol
    for mechanism selection, and the agreement of security service options.
    The GSS-API gss_init_sec_context() interface enables the context
    initiator to know what security services the target supports for the
    chosen mechanism.

    The GSS-API per-message protection calls are used to encapsulate any
    further TCP traffic between client and server, and, for integrity
    protection of UDP datagrams.

    3. GSS-API Call Specification for SOCKS V5 Security Context Establishment

    3.1 Preparation

    Prior to use of GSS-API primitives, the client and server should
    be locally authenticated, and have established GSS-API credentials.

    The client should call gss_import_name to obtain an internal
    representation of the server name.  For maximal portability
    the default name_type GSS_C_NULL_OID should be used to specify
    the default name space, and the input name_string should
    treated by the client client's code as an opaque name-space specific input.
    For example, when using Kerberos V5 naming, the imported name
    is of the form "SERVICE:socks@socks_server_hostname" where
    "socks_server_hostname" is the fully qualified host name of
    the server with all letters in lower case. Other mechanisms may,
    however, have different name forms, so the client should not make
    assumptions about the name syntax.

    3.2 Client Context Establishment

    The client should then call gss_init_sec_context, typically
    passing GSS_C_NO_CREDENTIAL into cred_han to specify the default
    credential (for initiator usage), GSS_C_NULL_OID into mech_type to
    specify the default mechanism, GSS_C_NO_CONTEXT into context_handle to

    Internet-Draft                      GSS-API Authentication for SOCKS V5
    specify a NULL context (initially), and the previously imported server
    name into targ_name.

    The client must also specify its requirements for replay protection,
    delegation, and sequence protection via the gss_init_sec_context
    req_flags parameter.  It is required by this specification that the
    client always requests these service options (i.e. passes
    GSS_C_MUTUAL_FLAG into req_flags).  However, GSS_C_SEQUENCE_FLAG should
    only be passed in for TCP-based clients, not for UDP-based clients.

    3.3 Client Context Establishment Major Status codes

    The gss_init_sec_context returned status code can take two different
    success values:

    - If gss_init_sec_context returns GSS_S_CONTINUE_NEEDED, then the
      client should expect the server to issue a token in the subsequent
      subnegotiation response.  The client must pass the token to another
      call to gss_init_sec_context, and repeat this procedure until
      continue operations are complete.

    - If gss_init_sec_context returns GSS_S_COMPLETE, then the client
      should respond to the server with any resulting output_token.  If
      there is no output_token, the client should proceed to sending the
      protected request details. details, including any required message protection
      subnegotiation as specified in sections 4 and 5 below.

    3.4 Client initial token

    The client's GSS-API implementation then typically responds with the
    resulting output_token which the client sends in a message to
    the server.

    + ver  | mtyp | len  |       token           |
    + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets |
    If, however, the client's GSS-API implementation failed during
    gss_init_sec_context, the the client must close its connection to
    the server.

    3.5 Server Context Establishment

    For the case where a client successfully sends a token emitted by
    gss_init_sec_context() to the server, the server must pass the
    client-supplied token to gss_accept_sec_context as input_token.

    Internet-Draft                      GSS-API Authentication for SOCKS V5
    For portability, verifier_cred_handle is set to GSS_C_NO_CREDENTIAL to
    specify default credentials (for acceptor usage), usage). In addition,
    context_handle initially set to GSS_C_NO_CONTEXT.

    If gss_accept_sec_context returns GSS_CONTINUE_NEEDED, the server
    should return the generated output_token to the client, and
    subsequently pass the resulting client supplied token to another call
    to gss_accept_sec_context.

    If gss_accept_sec_context returns GSS_S_COMPLETE, then if an
    output_token is returned, the server should return it to the client.
    If no token is returned, a zero length token should be sent
    by the server to signal to the client that it is ready to receive
    the client's request.

    3.6 Server Reply

    In all continue/confirmation cases, the server uses the same message
    type as for the client -> server interaction.

    + ver  | mtyp | len  |       token           |
    + 0x01 | 0x01 | 0x02 | up to 2^16 - 1 octets |

    3.7 Security Context Failure

    If the server refuses the client's connection for any reason (GSS-API
    authentication failure or otherwise), it will return:

    + ver  | mtyp |
    + 0x01 | 0xff |

    4. GSS-API Protection-level Options

    4.1 TCP Message protection

    Establishment of a GSS-API security context enables comunicating peers
    to determine which per-message protection services are available to
    them through the gss_init_sec_context() and gss_accept_sec_context()
    ret_flags GSS_C_INTEG and GSS_C_CONF which respectively indicate
    message integrity and confidentiality services.

    It is necessary to ensure that the message protection applied to the
    traffic is appropriate to the sensitivity of the data, and the severity
    of the threats.

    4.2 UDP Message Protection level

    For UDP, SOCKS V5 supports integrity protection only.  UDP clients and
    servers therefore MUST use integrity protection as defined in [SOCKS
    V5] and section 5.2 below.  No additional subnegotiation is required.

    4.3 TCP Message Protection Subnegotiation

    For TCP clients and servers, different levels of protection are
    possible in the SOCKS V5 protocol, so an additional subnegotiation
    stage is needed to agree the message protection level.  After
    successful completion of this subnegotiation, TCP clients and servers
    use GSS-API encapsulation as defined in section 5.1.

    After successful establishment of a GSS-API security context, the
    client's GSS-API implementation sends its required security context
    protection level to the server.  The server then returns the security
    context protection level which it agrees to - which may or may not take
    the the client's request into account.

    The security context protection level sent by client and server must be
    one of the following values:-
         1 required per-message integrity
         2 required per-message integrity and confidentiality
         3 selective per-message integrity or confidentiality based on
           local client and server configurations

    It is anticipated that most implementations will agree on level 1 or 2
    due to the practical difficulties in applying selective controls to
    messages passed through a socks library.

    The security context protection level is sent from client to server and
    vice versa using the following protected message format:

    + ver  | mtyp | len  |   token               |
    + 0x01 | 0x02 | 0x02 | up to 2^16 - 1 octets |

    The token is produced by encapsulating an octet containing the required
    protection level using gss_wrap() with conf_req set to FALSE.  The
    token is verified using gss_unwrap().

    If the server's choice of protection level is unacceptable to the
    client, then the client must close its connection to the server

    5. GSS-API Per-message Protection

    5.1 TCP Protection

    For TCP clients and servers, the GSS-API functions for encapsulation
    and de-encapsulation shall be used by implementations - i.e.
    gss_wrap(), and gss_unwrap().

    The default value of quality of protection shall be specified, and the
    use of conf_req_flag shall be as determined by the previous
    subnegotiation step.  If protection level 1 is agreed then conf_req
    MUST always be FALSE; if protection level 2 is agreed then conf_req
    MUST always be TRUE; and if protection level 3 is agreed then conf_req
    is determined on a per-message basis by client and server using local

    5.2 UDP Protection

    When using GSS-API, the authentication key material identified in
    [SOCKS V5] for computation of the value for the XCOOKIE digest within
    the UDP MAC field is encapsulated by the authentication mechanism.

    Therefore, for UDP-based clients, the XCOOKIE digest value for UDP is
    derived by invoking gss_get_mic() for the COOKIE from the UDP ASSOCIATE

    Internet-Draft                      GSS-API Authentication for SOCKS V5


    6. References

    [RFC 1508] Generic Security Service API, J Linn,
               September 1993

    [RFC 1509] Generic Security Service API : C-bindings, J Wray,
               September 1993

    [SOCKS V5] SOCKS Protocol V5, draft-ietf-aft-socks-proto-v5-01.txt
    7. Acknowledgment

    This document builds from a previous draft produced by Marcus Leech
    (BNR) - whose comments are gratefully acknowleged.


    8. Security Considerations

    The security services provided through the GSS-API are entirely
    dependent on the effectiveness of the underlying security mechanisms,
    and the correctness of the implementation of the underlying algorithms
    and protocols.

    The user of a GSS-API service must ensure that the quality of
    protection provided by the mechanism implementation is consistent with
    their security policy.

    In addition, where negotiation is supported under the GSS-API,
    constraints on acceptable mechanisms may be imposed to ensure
    suitability for application to authenticated firewall traversal.


    9. Author's Address

    P V McMahon
    post: ICL Enterprises, Kings House, 33 Kings Road, Reading, RG1 3PX, UK
    phone: +44 734 634882
    fax:   +44 734 855106