HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 00:46:53 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Mon, 10 Apr 1995 22:00:00 GMT ETag: "2e9cba-3b18-2f89aa60" Accept-Ranges: bytes Content-Length: 15128 Connection: close Content-Type: text/plain Internet-Draft GSS-API Authentication for SOCKS V5 Expires: 29SEP95 29MAR95 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 ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). Comments on this document are welcome and should be sent to aft@unify.com, the mailing list of the Authenticated Firewall Traversal Working Group of the IETF. Contents List 1. Purpose 2. Introduction 3. GSS-API Security Context Establishment 4. GSS-API Protection-level Options 5. 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 a GSS-API-based encapsulation for provision of integrity, authentication and optional confidentiality. McMahon [Page 1] 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 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'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. McMahon [Page 2] Internet-Draft GSS-API Authentication for SOCKS V5 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 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 | GSS_C_REPLAY_FLAG | GSS_C_DELEG_FLAG | 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, 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 | +------+------+------+.......................+ McMahon [Page 3] Internet-Draft GSS-API Authentication for SOCKS V5 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. For portability, verifier_cred_handle is set to GSS_C_NO_CREDENTIAL to specify default credentials (for acceptor 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 | +------+------+ McMahon [Page 4] Internet-Draft GSS-API Authentication for SOCKS V5 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: McMahon [Page 5] Internet-Draft GSS-API Authentication for SOCKS V5 +------+------+------+.......................+ + 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 configuration. 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 request. McMahon [Page 6] 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 M Leech, March 1995 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 email: p.v.mcmahon@rea0803.wins.icl.co.uk phone: +44 734 634882 fax: +44 734 855106 McMahon [Page 7]