[Search] [txt|pdf|bibtex] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 rfc4256                               
Network Working Group                                         M. Forssen
INTERNET-DRAFT                                                Appgate AB
draft-ietf-secsh-auth-kbdinteract-01.txt                       F. Cusack
Expires in six months                           Qwest Internet Solutions
                                                         12 October 2000

            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-

   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

   The list of Internet-Draft Shadow Directories can be accessed at


   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 have little or no knowledge of the underlying
   authentication mechanism(s) used by the SSH server.

F. Cusack, M. Forssen                                           [Page 1]

draft-ietf-secsh-auth-kbdinteract-01.txt                 12 October 2000

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

   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 have little or no
   knowledge 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
   new authentication mechanisms, and if a separate authentication layer
   is used, such as [PAM], then the server may not need any code changes

   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.

   Challenge-response and One Time Password mechanisms are also easily

F. Cusack, M. Forssen                                           [Page 2]

draft-ietf-secsh-auth-kbdinteract-01.txt                 12 October 2000

   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

3.1 Initial Exchange

   The authentication starts with the client sending the following

      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  devices (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 devices field is a comma-separated list of authentication devices
   (software or hardware) that are available to authenticate the user
   using the keyboard-interactive authentication method. If the client
   has knowledge of the devices available to the user, it MAY use the
   devices field to pass this information to the server. Otherwise it
   MUST send the empty string.

   Server interpretation of the devices is implementation-dependent.

   One possible implementation strategy of the devices field on the
   server is that, unless the user may use multiple different devices,
   the server ignores this field. If the user may authenticate using one
   of several different devices the server should treat the devices
   field as a hint on which device the user wants to use this time.

F. Cusack, M. Forssen                                           [Page 3]

draft-ietf-secsh-auth-kbdinteract-01.txt                 12 October 2000

   Device names should be registered with IANA (Internet Assigned
   Numbers Authority), or a locally defined name containing an at-sign
   (@). See section 5 of [SSH-ARCH] for more discussion on name syntax.

   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,

   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

   The server may send as many requests as are necessary to authenticate
   the client; the client MUST be prepared to handle multiple exchanges.

   The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows:

      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

F. Cusack, M. Forssen                                           [Page 4]

draft-ietf-secsh-auth-kbdinteract-01.txt                 12 October 2000

   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

   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.

   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

F. Cusack, M. Forssen                                           [Page 5]

draft-ietf-secsh-auth-kbdinteract-01.txt                 12 October 2000

      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

   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 responds with a failure message, it SHOULD delay a
   minimum of 2 seconds before sending the failure message, to limit
   certain types of attacks.

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  ""

F. Cusack, M. Forssen                                           [Page 6]

draft-ietf-secsh-auth-kbdinteract-01.txt                 12 October 2000

      S:      string  "Password Authentication"
      S:      string  "Enter password for user23@server"
      S:      string  "en-US"
      S:      int     1
      S:      string  "Password: "
      S:      boolean FALSE

      [Client prompts user for password]

      C:      int     1
      C:      string  "bar"

      S:      string  "Password Expired"
      S:      string  "Your password has expired, you must enter a new one"
      S:      string  "en-US"
      S:      int     2
      S:      string  "New password: "
      S:      boolean FALSE
      S:      string  "Enter it again: "
      S:      boolean FALSE

      [Client prompts user for new password]

      C:      int     2
      C:      string  "baz"
      C:      string  "baz"

      S:      byte    SSH_MSG_USERAUTH_SUCCESS

5. Protocol constants

   The following method-specific constants are used with this
   authentication method:


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.

F. Cusack, M. Forssen                                           [Page 7]

draft-ietf-secsh-auth-kbdinteract-01.txt                 12 October 2000

   [RFC-2279] Yergeau, F., "UTF-8, a Transformation Format of Unicode
   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-

   [SSH-CONNECT] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S.
   Lehtinen, "SSH Connection Protocol", Internet Draft, draft-ietf-

   [SSH-TRANS] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S.
   Lehtinen, "SSH Transport Layer Protocol", Internet Draft, draft-

   [SSH-USERAUTH] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S.
   Lehtinen, "SSH Authentication Protocol", Internet Draft, draft-ietf-

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
   Email: maf@appgate.com

F. Cusack, M. Forssen                                           [Page 8]