Network Working Group J. Galbraith INTERNET-DRAFT J. Van Dyke Expires September 2001 Van Dyke Technologies V. Welch University of Chicago March 2001 SECSH GSS-API Authentication Method < draft-galb-secsh-gssapi-01.txt > Status of This Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 documents 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract SECSH is a protocol for secure remote login and other secure network services over an insecure network. GSSAPI is a general-purpose user authentication method based on RFC 2743. This document describes a method for encoding GSSAPI onto the model described in the SECSH authentication protocol framework [SSH-AUTH]. 1. Introduction The SECSH GSSAPI authentication method is a general-purpose user authentication method based on RFC 2743. It is intended to be run over the SECSH userauth service layer protocol [SSH-AUTH]. This document should be read only after reading the SECSH architecture document [SSH-ARCH] and the SECSH authentication document [SSH-AUTH]. This document freely uses terminology and notation from the architecture document without reference or further explanation. The authentication method name for this protocol is "gssapi". When this method starts, it receives the server's host key from the lower-level protocol. 2. GSSAPI Authentication Overview GSSAPI authentication must maintain a context. Authentication begins when the client sends a SSH_MSG_USERAUTH_REQUEST, which specifies the mechanism OIDs the client supports. If the server supports any of the requested mechanism OIDs, the server sends a SSH_MSG_USERAUTH_GSSAPI_RESPONSE message containing the mechanism OID. After the client receives SSH_MSG_USERAUTH_GSSAPI_RESPONSE, the client and server exchange SSH_MSG_USERAUTH_GSSAPI_TOKEN packets until the authentication mechanism either succeeds or fails. If at any time during the exchange, the client sends a new SSH_MSG_USERAUTH_REQUEST packet, the GSSAPI context is completely discarded and destroyed, and any further GSSAPI authentication MUST restart from the beginning. 2.1 SECSH terminology The data types used in the packets are defined in the SECSH architecture document [SSH-ARCH]. It is important to note the definition of string allows binary content. Quoting from the architecture document: string Arbitrary length binary string. Strings are allowed to contain arbitrary binary data, including null characters and 8-bit characters. They are stored as a uint32 containing its length (number of bytes that follow) and zero (= empty string) or more bytes that are the value of the string. Terminating null characters are not used. The SSH_MSG_USERAUTH_REQUEST packet refers to a service; this service name is a SECSH service name, and has no relationship to GSSAPI service names. Currently, the only defined service name is "ssh-connection", which refers to the SECSH connection protocol [SSH-CONNECT]. 3. GSSAPI Authentication Method The GSSAPI authentication method defines four message identifiers: SSH_MSG_USERAUTH_GSSAPI_RESPONSE 60 SSH_MSG_USERAUTH_GSSAPI_TOKEN 61 SSH_MSG_USERAUTH_GSSAPI_HASH 62 SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE 63 3.1 Initiating GSSAPI authentication The GSSAPI authentication method is initiated when the client sends a SSH_MSG_USERAUTH_REQUEST: byte SSH_MSG_USERAUTH_REQUEST string username (in ISO-10646 UTF-8 encoding) string service name (in US-ASCII) string "gssapi" (US-ASCII method name) uint32 n, the number of mechanism OIDs client supports string[n] mechanism OIDs The mechanism OIDs MUST be listed in order of preference, the server must choose the first mechanism OID on the list that it supports. The client SHOULD NOT send more then one gssapi mechanism OID unless there are no non-GSSAPI authentication methods between the GSSAPI mechanisms in the order of preference, otherwise, authentication methods may be executed out of order. If the server does not support any of the specified OIDs, the server MUST fail the request by sending a SSH_MSG_USERAUTH_FAILURE packet. The username may be an empty string if it can be deduced from the results of the gssapi authentication. If the requested username is not empty, and does not exist, the server MAY disconnect, or MAY send a bogus list of acceptable authentications but never accept any. This makes it possible for the server to avoid disclosing information about which accounts exist. In any case, if the user does not exist, the authentication request MUST NOT be accepted. The client MAY at any time continue with a new SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST abandon the previous authentication attempt and continue with the new one. Mechanism OIDs are encoded as specified in RFC2743, section 3.1 item #5: 5. Object identifier octets -- variable number of octets, -- encoded per ASN.1 BER rules: 5a. The first octet contains the sum of two values: (1) the top-level object identifier component, multiplied by 40 (decimal), and (2) the second-level object identifier component. This special case is the only point within an object identifier encoding where a single octet represents contents of more than one component. 5b. Subsequent octets, if required, encode successively-lower components in the represented object identifier. A component's encoding may span multiple octets, encoding 7 bits per octet (most significant bits first) and with bit 8 set to "1" on all but the final octet in the component's encoding. The minimum number of octets shall be used to encode each component (i.e., no octets representing leading zeros shall be included within a component's encoding). 3.1.1 SPNEGO The use of the Simple and Protected GSS-API Negotiation Mechanism [SPNEGO] in conjunction with the gssapi algorithm method described in this document is both unnecessary and undesirable. As a result, authentication mechanisms conforming to this document MUST NOT use SPNEGO as the underlying GSSAPI mechanism. Since SSH performs its own negotiation of authentication methods, and this mechanism provides a method to negotiate the gssapi mechanism to be used, the negotiation capability of SPNEGO alone does not provide any added benefit. In fact, as described below, it has the potential to result in the use of a weaker method than desired. Normally, SPNEGO provides the added benefit of protecting the GSSAPI mechanism negotiation. SECSH already provides a secure, integrity checked layer which this authentication mechanism runs over. Thus, the extra level of protection offered by SPNEGO is unnecessary in this case. The use of SPNEGO combined with GSSAPI mechanisms used without SPNEGO can lead to interoperability problems. For example, a client which supports authentication using the Kerberos V5 GSSAPI mechanism [KRB5-GSS] only underneath SPNEGO will not interoperate with a server which supports authentication only using the Kerberos V5 GSSAPI mechanism directly. As a result, allowing GSSAPI mechanisms to be used both with and without SPNEGO is undesirable. If a client's policy is to first prefer GSSAPI-based authentication method X, then non-GSSAPI method Y, then GSSAPI-based method Z, and if a server supports mechanisms Y and Z but not X, then an attempt to use SPNEGO to negotiate a GSSAPI mechanism might result in the use of method Z when method Y would have been preferable. As a result, the use of SPNEGO could result in the subversion of the negotiation algorithm for authentication methods. 3.2 Initial server response The server responds to the SSH_MSG_USERAUTH_REQUEST with either a SSH_MSG_USERAUTH_FAILURE if none of the mechanisms are supported, or with SSH_MSG_USERAUTH_GSSAPI_RESPONSE as follows: byte SSH_MSG_USERAUTH_GSSAPI_RESPONSE string selected mechanism OID The mechanism OID must be one of the OIDs sent by the client in the SSH_MSG_USERAUTH_REQUEST packet. 3.3 GSSAPI session Once the mechanism OID has been selected, the client will then initiate an exchange of one or more pairs of SSH_MSG_USERAUTH_GSSAPI_TOKEN packets. These packets contain the tokens produced from the 'GSS_Init_sec_context()' and 'GSS_Accept_sec_context()' calls. The actual number of packets exchanged is determined by the underlying GSSAPI library. byte SSH_MSG_USERAUTH_GSSAPI_TOKEN string data returned from either GSS_Init_sec_context() or GSS_Accept_sec_context() If an error occurs during this exchange on server side, the server can terminate the method by sending a SSH_MSG_USERAUTH_FAILURE packet. If an error occurs on client side, the client can terminate the method by sending a new SSH_MSG_USERAUTH_REQUEST packet. The server ends the GSSAPI session by sending a SSH_MSG_USERAUTH_GSSAPI_HASH packet (see below.) The client MAY use the deleg_req_flag in calls to GSS_Init_sec_context() to request credential delegation. The mutual_req_flag MUST be specified in order for the GSS_GetMIC() to provide additional security (see Section 3.4) The client MUST use the integ_req_flag, since GSS_GetMIC() and GSS_VerifyMIC() will be used (see Section 3.4) The authentication MUST fail if GSS_S_COMPLETE is returned and either the mutual_state or integ avail flags are not true. Additional SSH_MSG_USERAUTH_GSSAPI_TOKEN messages are sent if and only if the calls to the GSSAPI routines produce send tokens of non-zero length. Any major status code other than GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED SHOULD be a failure. The service name to be used in calling GSS_Init_sec_context() is a GSSAPI host-based service name, generated by calling GSS_Import_name() with type GSS_C_NT_HOSTBASED_SERVICE and the string 'host@foo.bar' where host is the literal string 'host' and foo.bar is the fully-qualified hostname. For example, to connect to a host myserver.mydomain.com, the name 'host@myserver.mydomain.com' would be used. 3.4 Client acknowledgement It is possible for the server to successfully complete the gssapi method and the client to fail. If the server simply assumed success on the part of the client and completed the authentication service, it is possible that the client would fail to complete the authentication method, but not be able to retry other methods because the server had already moved on. Therefore, the client MUST send the following message when it has successfully called GSS_Init_sec_context() and gotten GSS_S_COMPLETE: byte SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE This message MUST be sent if and only if GSS_Init_sec_context() returned GSS_S_COMPLETE and both the mutual_state and integ_avail flags are true. If GSS_Init_sec_context() failed, or mutual_state or integ_avail were not true, the client MUST terminate the method by sending a new SSH_MSG_USERAUTH_REQUEST. 3.5 Increasing confidence in host key authenticity In order to provide stronger authentication of the host key, the server MUST send an SSH_MSG_USERAUTH_GSSAPI_HASH packet as soon as the server receives the SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE packet. byte SSH_MSG_USERAUTH_GSSAPI_HASH string output of GSS_GetMIC() applied to the session id. This allows the client to verify the session id sent earlier during key exchange, which, if successful, implies that the host key sent during key exchange was authentic. This can prevent a man-in-the-middle attack in situations where the server's host key is unknown to the client. If the GSS_VerifyMIC() function fails to verify the session id, the client MUST disconnect from the server by sending a SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE message. If the client fails to receive a SSH_MSG_USERAUTH_GSSAPI_HASH message it MUST disconnect with SSH_DISCONNECT_PROTOCOL_ERROR. 3.6 Completion As with all SECSH authentication methods, successful completion is indicated by a SSH_MSG_USERAUTH_SUCCESS if no other authentication is required, or a SSH_MSG_USERAUTH_FAILURE with the partial success flag set if the server requires further authentication. This packet should be sent immediately following the SSH_MSG_USERAUTH_GSSAPI_HASH packet. 4. References [SSH-ARCH] Ylonen, T., et al, "SSH Protocol Architecture", Internet Draft, draft-secsh-architecture-07.txt [SSH-TRANS] Ylonen, T., et al, "SSH Transport Layer Protocol", Internet Draft, draft-secsh-transport-09.txt [SSH-USERAUTH] Ylonen, T., et al, "SSH Authentication Protocol", Internet Draft, draft-ietf-secsh-userauth-09.txt [SSH-CONNECT] Ylonen, T., et al, "SSH Connection Protocol", Internet Draft, draft-secsh-connect-09.txt [RFC-2743] Linn, J., "Generic Security Service Application Program Interface, Version 2, Update 1", January 2000. [RFC-2279] Yergeau, F., "UTF-8, a Transformation Format of Unicode and ISO 10646", October 1996. 5. Authors addresses Joseph Galbraith Van Dyke Technologies, Inc. 4848 Tramway Ridge Dr. NE Suite 101 Albuquerque, NM 87111 USA E-mail: galb@vandyke.com Jeff Van Dyke Van Dyke Technologies, Inc. 4848 Tramway Ridge Dr. NE Suite 101 Albuquerque, NM 87111 USA E-mail: jpv@vandyke.com Von Welch Distributed Systems Laboratory University of Chicago & Argonne National Laboratory 701 E. Washington Urbana, IL 61801 USA E-mail: welch@mcs.anl.gov This draft expires September 2001.