Network Working Group F. Cusack

Network Working Group F. Cusack
INTERNET-DRAFT Qwest Internet Solutions
draft-ietf-secsh-auth-kbdinteract-00.txt M. Forssen
Expires September 7, 1999 Firedoor Network Security AB
7 March 1999

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 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-00.txt 7 March 1999

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, 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 method 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
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-00.txt 7 March 1999

Challenge-response and One Time Password mechanisms are also easily
supported with this authentication method.

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
SSM_MSG_USERAUTH_INFO_RESPONSE message.

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 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-defined.

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-defined.

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).

F. Cusack, M. Forssen [Page 3]

draft-ietf-secsh-auth-kbdinteract-00.txt 7 March 1999

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 usernames 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.

The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows:

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:

F. Cusack, M. Forssen [Page 4]

draft-ietf-secsh-auth-kbdinteract-00.txt 7 March 1999

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
occured.

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 as characters are typed. Clients
MUST correctly echo/mask user input for each prompt independently of
other prompts in the request message. Clients MUST NOT add any
additional characters to the prompt such as ": "; the server is
reponsible 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

F. Cusack, M. Forssen [Page 5]

draft-ietf-secsh-auth-kbdinteract-00.txt 7 March 1999

(e.g., ISO 8859-1), it MUST convert the responses to ISO-10646 UTF-8
before transmitting, and the server MUST convert the responses to the
encoding used on that system that is needed to verify them.

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 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 "foo"
C: string "ssh-userauth"
C: string "keyboard-interactive"
C: string "en-US"
C: string "password"

S: byte SSH_MSG_USERAUTH_INFO_REQUEST
S: string "Password Authentication"
S: string "Enter password for foo"
S: int 1
S: string "Password: "
S: boolean FALSE
S: string "en-US"

[Client prompts user for password]

F. Cusack, M. Forssen [Page 6]

draft-ietf-secsh-auth-kbdinteract-00.txt 7 March 1999

C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
C: int 1
C: string "bar"

S: byte SSH_MSG_USERAUTH_INFO_REQUEST
S: string "Password Expired"
S: string "Your password has expired."
S: int 2
S: string "Enter new password: "
S: boolean FALSE
S: string "Enter it again: "
S: boolean FALSE
S: string "en-US"

[Client prompts user for new password]

C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
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:

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-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode
and ISO 10646", October 1996.

[SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol
Architecture", Internet Draft, draft-ietf-secsh-architecture-03.txt

[SSH-CONNECT] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH
Connection Protocol", Internet Draft, draft-ietf-secsh-connect-05.txt

F. Cusack, M. Forssen [Page 7]

draft-ietf-secsh-auth-kbdinteract-00.txt 7 March 1999

[SSH-TRANS] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Transport
Layer Protocol", Internet Draft, draft-ietf-secsh-transport-05.txt

[SSH-USERAUTH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH
Authentication Protocol", Internet Draft, draft-ietf-secsh-userauth-
05.txt

7. Author's Addresses

Frank Cusack
Qwest Internet Solutions
1200 Harbor Blvd, 8th Fl.
Weehawken, NJ 07087
Email: [email protected]

Martin Forssen
Firedoor Network Security AB
Stora Badhusgatan 18-20
SE-411 21 Gothenburg
SWEDEN
Email: [email protected]

F. Cusack, M. Forssen [Page 8]