Network Working Group M. Forssen INTERNET-DRAFT Appgate AB draft-ietf-secsh-auth-kbdinteract-02.txt F. Cusack Expires in six months Qwest Internet Solutions 1 March 2001 Generic Message Exchange Authentication For SSH 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 SSH is a protocol for secure remote login and other secure network services over an insecure network. This document describes a general purpose authentication method for the SSH protocol, suitable for interactive authentications where the authentication data should be entered via a keyboard. The major goal of this method is to allow the SSH client to support a whole class of authentication mechanism(s) without knowing the specifics of the actual authentication mechanism(s). F. Cusack, M. Forssen [Page 1]
draft-ietf-secsh-auth-kbdinteract-02.txt 1 March 2001 1. Introduction The SSH authentication protocol is a general-purpose user authentication protocol. It is intended to be run over the SSH transport layer protocol [SSH-TRANS]. The protocol assumes that the underlying protocols provide integrity and confidentiality protection. This document describes a general purpose authentication method for the SSH protocol. This method is suitable for interactive authentication methods which does not need any special software support on the client side. Instead all authentication data should be entered via the keyboard. The major goal of this method is to allow the SSH client to have little or no knowledge of the specifics of the underlying authentication mechanism(s) used by the SSH server. This will allow the server to arbitrarily select or change the underlying authentication mechanism(s) without having to update client code. The name for this authentication method is "keyboard-interactive". This document should be read only after reading the SSH architecture document [SSH-ARCH] and the SSH authentication document [SSH- USERAUTH]. This document freely uses terminology and notation from both documents without reference or further explanation. This document also describes some of the client interaction with the user in obtaining the authentication information. While this is somewhat out of the scope of a protocol specification, it is still described here since some aspects of the protocol are specifically designed based on user interface issues, and omitting this information may lead to incompatible or awkward implementations. 2. Rationale Currently defined authentication methods for SSH are tightly coupled with the underlying authentication mechanism. This makes it difficult to add new mechanisms for authentication as all clients must be updated to support the new mechanism. With the generic method defined here, clients will not require code changes to support further new authentication mechanisms, provided the mechanism fits the requirements for keyboard-interactive. And if a separate authentication layer is used, such as [PAM], then the server may not need any code changes either. This presents a significant advantage to other methods, such as the "password" method (defined in [SSH-USERAUTH]), as new (presumably stronger) methods may be added "at will" and system security can be transparently enhanced. F. Cusack, M. Forssen [Page 2]
draft-ietf-secsh-auth-kbdinteract-02.txt 1 March 2001 Challenge-response and One Time Password mechanisms are also easily supported with this authentication method. This authentication method is however limited to authentication mechanisms which do not require any special code, such as hardware drivers or password mangling, on the client. 3. Protocol Exchanges The client initiates the authentication with a SSH_MSG_USERAUTH_REQUEST message. The server then requests authentication information from the client with a SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the information from the user and then responds with a SSH_MSG_USERAUTH_INFO_RESPONSE message. The server MUST not send another SSH_MSG_USERAUTH_INFO_REQUEST before it has received the answer from the client. 3.1 Initial Exchange The authentication starts with the client sending the following packet: byte SSH_MSG_USERAUTH_REQUEST string user name (ISO-10646 UTF-8) string service name (US-ASCII) string "keyboard-interactive" (US-ASCII) string language tag (as defined in [RFC-1766]) string submethods (ISO-10646 UTF-8) The language tag indicates the client's preferred language. The server SHOULD use this language for all text that is to be presented to the user in the subsequent exchanges. If the server cannot support the requested language, the language to be used is implementation-dependent. The submethods field is included so the user can give a hint of which actual methods he wants to use. It is a a comma-separated list of authentication submethods (software or hardware) which the user prefers. If the client has knowledge of the submethods preferred by the user, presumably through a configuration setting, it MAY use the submethods field to pass this information to the server. Otherwise it MUST send the empty string. The actual names of the submethods is something which the user and the server needs to agree upon. F. Cusack, M. Forssen [Page 3]
draft-ietf-secsh-auth-kbdinteract-02.txt 1 March 2001 Server interpretation of the submethods field is implementation- dependent. One possible implementation strategy of the submethods field on the server is that, unless the user may use multiple different submethods, the server ignores this field. If the user may authenticate using one of several different submethods the server should treat the submethods field as a hint on which submethod the user wants to use this time. Note that when this message is sent to the server, the client has not yet prompted the user for a password, and so that information is NOT included with this initial message (unlike the "password" method). The server MUST reply with either a SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message. The server SHOULD NOT reply with the SSH_MSG_USERAUTH_FAILURE message if the failure is based on the user name or service name; instead it SHOULD send SSH_MSG_USERAUTH_INFO_REQUEST message(s) which look just like the one(s) which would have been sent in cases where authentication should proceed, and then send the failure message (after a suitable delay, as described below). The goal is to make it impossible to find valid user names by just comparing the results when authenticating as different users. 3.2 Information Requests Requests are generated from the server using the SSH_MSG_USERAUTH_INFO_REQUEST message. The server may send as many requests as are necessary to authenticate the client; the client MUST be prepared to handle multiple exchanges. However the server MUST never have more than one SSH_MSG_USERAUTH_INFO_REQUEST message outstanding. That is it may not send another request before the client has answered. The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows: F. Cusack, M. Forssen [Page 4]
draft-ietf-secsh-auth-kbdinteract-02.txt 1 March 2001 byte SSH_MSG_USERAUTH_INFO_REQUEST string name (ISO-10646 UTF-8) string instruction (ISO-10646 UTF-8) string language tag (as defined in [RFC-1766]) int num-prompts string prompt[1] (ISO-10646 UTF-8) boolean echo[1] ... string prompt[num-prompts] (ISO-10646 UTF-8) boolean echo[num-prompts] The server SHOULD limit the length of the name and prompt fields to 30 characters. No restrictions are placed on the instruction field. The name and instruction fields MAY be empty strings, the client MUST be prepared to handle this correctly. The num-prompts field may be `0', in which case there will be no prompt/echo fields in the message, but the client MUST still display the name and instruction fields (as described below). 3.3 User Interface Upon receiving a request message, the client SHOULD prompt the user as follows: A command line interface (CLI) client SHOULD print the name and instruction (if non-empty), adding newlines. Then for each prompt in turn, the client MUST display the prompt and read the user input. A graphical user interface (GUI) client SHOULD present a dialog window, using the name (if non-empty) as the title of the window, the instruction (if non-empty) as a text message inside the dialog, and the appropriate number of entry fields with the prompts as labels. A GUI client SHOULD NOT present each prompt in a separate window. All clients MUST properly handle an instruction field with embedded newlines. They MUST also be able to display at least 30 characters for the name and prompts. If the server presents names/prompts longer than 30 characters, the client MAY truncate these fields to the length it can display. If the client does truncate any fields, there SHOULD be an obvious indication that such truncation has occurred. Clients SHOULD use control character filtering as discussed in [SSH- ARCH] to avoid attacks by including terminal control characters in the fields to be displayed. F. Cusack, M. Forssen [Page 5]
draft-ietf-secsh-auth-kbdinteract-02.txt 1 March 2001 For each prompt, the corresponding echo field indicates whether or not the user input should be echoed or not. Clients SHOULD correctly handle echo for each prompt independently of other prompts in the request message. Clients SHOULD NOT add any additional characters to the prompt such as ": "; the server is responsible for supplying all text to be displayed to the user. Clients MUST also accept empty responses from the user and pass them on as empty strings. 3.4 Information Responses After obtaining the requested information from the user, the client MUST respond with a SSH_MSG_USERAUTH_INFO_RESPONSE message. The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as follows: byte SSH_MSG_USERAUTH_INFO_RESPONSE int num-responses string response[1] (ISO-10646 UTF-8) ... string response[num-responses] (ISO-10646 UTF-8) Note that the responses are encoded in ISO-10646 UTF-8. It is up to the server how it interprets the responses and validates them. However, if the client reads the responses in some other encoding (e.g., ISO 8859-1), it MUST convert the responses to ISO-10646 UTF-8 before transmitting. If the num-responses field does not match the num-prompts field in the request message, the server MUST send a failure message. In the case that the server sends a `0' num-prompts field in the request message, the client MUST send a response message with a `0' num-responses field. After receiving the response, the server MUST send either a SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another SSH_MSG_USERAUTH_INFO_REQUEST message. If the server fails to authenticate the user (through the underlying authentication mechanism(s)), it SHOULD NOT send another request message(s) in an attempt to obtain new authentication data, instead it SHOULD send a failure message. The only time the server should send multiple request messages is if additional authentication data is needed (i.e., because there are multiple underlying authentication mechanisms that must be used to authenticate the user). If the server intends to respond with a failure message, it MAY delay F. Cusack, M. Forssen [Page 6]
draft-ietf-secsh-auth-kbdinteract-02.txt 1 March 2001 for an implementation dependent time before sending to the client. It is suspected that implementations are likely to make the time delay a configurable, a suggested default is 2 seconds. 4. Authentication Example Here is an example exchange between a client and server: C: byte SSH_MSG_USERAUTH_REQUEST C: string "user23" C: string "ssh-userauth" C: string "keyboard-interactive" C: string "en-US" C: string "" S: byte SSH_MSG_USERAUTH_INFO_REQUEST S: string "CryptoCARD Authentication" S: string "The challenge is '14315716'" S: string "en-US" S: int 1 S: string "Response: " S: boolean TRUE [Client prompts user for password] C: byte SSH_MSG_USERAUTH_INFO_RESPONSE C: int 1 C: string "6d757575" S: byte SSH_MSG_USERAUTH_SUCCESS 5. Protocol constants The following method-specific constants are used with this authentication method: SSH_MSG_USERAUTH_INFO_REQUEST 60 SSH_MSG_USERAUTH_INFO_RESPONSE 61 6. References [PAM] Samar, V., Schemers, R., "Unified Login With Pluggable Authentication Modules (PAM)", OSF RFC 86.0, October 1995 [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages", March 1995. [RFC-2279] Yergeau, F., "UTF-8, a Transformation Format of Unicode F. Cusack, M. Forssen [Page 7]
draft-ietf-secsh-auth-kbdinteract-02.txt 1 March 2001 and ISO 10646", October 1996. [SSH-ARCH] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen, "SSH Protocol Architecture", Internet Draft, draft-ietf- secsh-architecture-06.txt [SSH-CONNECT] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen, "SSH Connection Protocol", Internet Draft, draft-ietf- secsh-connect-08.txt [SSH-TRANS] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen, "SSH Transport Layer Protocol", Internet Draft, draft- ietf-secsh-transport-08.txt [SSH-USERAUTH] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen, "SSH Authentication Protocol", Internet Draft, draft-ietf- secsh-userauth-08.txt 7. Author's Addresses Frank Cusack Qwest Internet Solutions 1200 Harbor Blvd, 8th Fl. Weehawken, NJ 07087 Email: fcusack@iconnet.net Martin Forssen Appgate AB Stora Badhusgatan 18-20 SE-411 21 Gothenburg SWEDEN Email: maf@appgate.com F. Cusack, M. Forssen [Page 8]
