Network Working Group J. Galbraith INTERNET-DRAFT J. Van Dyke Expires May 2001 Van Dyke Technologies V. Welch NCSA/University of Illinois November 2000 SSH GSS-API Authentication Method < draft-galb-secsh-gssapi-00.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, or requests GSSAPI session negotiation. If the server supports any of the requested mechanism OIDs, the server sends a SSH_MSG_USERAUTH_GSSAPI_RESPONSE message containing the mechanism OID. If GSSAPI session negotiation was requested, the server sends an empty SSH_MSG_USERAUTH_GSSAPI_RESPONSE. 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. 3. GSSAPI Authentication Method The GSSAPI authentication method defines three message identifiers: SSH_MSG_USERAUTH_GSSAPI_RESPONSE 60 SSH_MSG_USERAUTH_GSSAPI_TOKEN 61 SSH_MSG_USERAUTH_GSSAPI_HASH 62 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 A packet with 0 mechanism OIDs is a request for gssapi session negotiation. If the server does not support any of the specified OIDs, or GSSAPI session negotiation is requested and not supported, 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 directly in binary as they would be passed to a GSSAPI call that requires an OID. 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 boolean negotiate session string mechanism OID If negotiate session is true, the mechanism id field MUST be omitted. If negotiate session is true, GSSAPI session negotiation should be run. If the client did not request session negotiate, the server MUST NOT set negotiate session to true. 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 may terminate the method by sending a SSH_MSG_USERAUTH_FAILURE packet. If an error occurs on client side, the client may 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.) 3.4 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 GSSAPI library indicates it is done with token exchange. byte SSH_MSG_USERAUTH_GSSAPI_HASH string output of gss_wrap() applied to the server's host key. this allows the client to verify the host key sent earlier during key exchange. 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_unwrap() function fails to verify the server's host key, the client should disconnect from the server by sending a SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE message. 3.5 Successful 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-05.txt [SSH-TRANS] Ylonen, T., et al, "SSH Transport Layer Protocol", Internet Draft, draft-secsh-transport-07.txt [SSH-USERAUTH] Ylonen, T., et al, "SSH Authentication Protocol", Internet Draft, draft-ietf-secsh-userauth-07.txt [SSH-CONNECT] Ylonen, T., et al, "SSH Connection Protocol", Internet Draft, draft-secsh-connect-07.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 NCSA/University of Illinois 701 E. Washington Urbana, IL 61801 USA E-mail: welch@mcs.anl.gov This draft expires May 2001.