draft-ietf-secsh-auth-kbdinteract-00.txt   draft-ietf-secsh-auth-kbdinteract-01.txt 
Network Working Group F. Cusack
INTERNET-DRAFT Qwest Internet Solutions Network Working Group M. Forssen
draft-ietf-secsh-auth-kbdinteract-00.txt M. Forssen INTERNET-DRAFT Appgate AB
Expires September 7, 1999 Firedoor Network Security AB draft-ietf-secsh-auth-kbdinteract-01.txt F. Cusack
7 March 1999 Expires in six months Qwest Internet Solutions
12 October 2000
Generic Message Exchange Authentication For SSH Generic Message Exchange Authentication For SSH
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 2, line 22 skipping to change at page 2, line 22
This document describes a general purpose authentication method for This document describes a general purpose authentication method for
the SSH protocol, suitable for interactive authentications where the the SSH protocol, suitable for interactive authentications where the
authentication data should be entered via a keyboard. The major goal 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 of this method is to allow the SSH client to have little or no
knowledge of the underlying authentication mechanism(s) used by the knowledge of the underlying authentication mechanism(s) used by the
SSH server. This will allow the server to arbitrarily select or SSH server. This will allow the server to arbitrarily select or
change the underlying authentication mechanism(s) without having to change the underlying authentication mechanism(s) without having to
update client code. update client code.
The method name for this authentication method is "keyboard- The name for this authentication method is "keyboard-interactive".
interactive".
This document should be read only after reading the SSH architecture This document should be read only after reading the SSH architecture
document [SSH-ARCH] and the SSH authentication document [SSH- document [SSH-ARCH] and the SSH authentication document [SSH-
USERAUTH]. This document freely uses terminology and notation from USERAUTH]. This document freely uses terminology and notation from
both documents without reference or further explanation. both documents without reference or further explanation.
This document also describes some of the client interaction with the This document also describes some of the client interaction with the
user in obtaining the authentication information. While this is user in obtaining the authentication information. While this is
somewhat out of the scope of a protocol specification, it is still somewhat out of the scope of a protocol specification, it is still
described here since some aspects of the protocol are specifically described here since some aspects of the protocol are specifically
skipping to change at page 3, line 8 skipping to change at page 3, line 6
either. either.
This presents a significant advantage to other methods, such as the This presents a significant advantage to other methods, such as the
"password" method (defined in [SSH-USERAUTH]), as new (presumably "password" method (defined in [SSH-USERAUTH]), as new (presumably
stronger) methods may be added "at will" and system security can be stronger) methods may be added "at will" and system security can be
transparently enhanced. transparently enhanced.
Challenge-response and One Time Password mechanisms are also easily Challenge-response and One Time Password mechanisms are also easily
supported with this authentication method. 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 3. Protocol Exchanges
The client initiates the authentication with a The client initiates the authentication with a
SSH_MSG_USERAUTH_REQUEST message. The server then requests SSH_MSG_USERAUTH_REQUEST message. The server then requests
authentication information from the client with a authentication information from the client with a
SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the SSH_MSG_USERAUTH_INFO_REQUEST message. The client obtains the
information from the user and then responds with a information from the user and then responds with a
SSM_MSG_USERAUTH_INFO_RESPONSE message. SSM_MSG_USERAUTH_INFO_RESPONSE message.
3.1 Initial Exchange 3.1 Initial Exchange
skipping to change at page 3, line 34 skipping to change at page 3, line 36
string service name (US-ASCII) string service name (US-ASCII)
string "keyboard-interactive" (US-ASCII) string "keyboard-interactive" (US-ASCII)
string language tag (as defined in [RFC-1766]) string language tag (as defined in [RFC-1766])
string devices (ISO-10646 UTF-8) string devices (ISO-10646 UTF-8)
The language tag indicates the client's preferred language. The The language tag indicates the client's preferred language. The
server SHOULD use this language for all text that is to be presented server SHOULD use this language for all text that is to be presented
to the user in the subsequent exchanges. to the user in the subsequent exchanges.
If the server cannot support the requested language, the language to If the server cannot support the requested language, the language to
be used is implementation-defined. be used is implementation-dependent.
The devices field is a comma-separated list of authentication devices The devices field is a comma-separated list of authentication devices
(software or hardware) that are available to authenticate the user (software or hardware) that are available to authenticate the user
using the keyboard-interactive authentication method. If the client using the keyboard-interactive authentication method. If the client
has knowledge of the devices available to the user, it MAY use the has knowledge of the devices available to the user, it MAY use the
devices field to pass this information to the server. Otherwise it devices field to pass this information to the server. Otherwise it
MUST send the empty string. MUST send the empty string.
Server interpretation of the devices is implementation-defined. 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.
Device names should be registered with IANA (Internet Assigned Device names should be registered with IANA (Internet Assigned
Numbers Authority), or a locally defined name containing an at-sign Numbers Authority), or a locally defined name containing an at-sign
(@). See section 5 of [SSH-ARCH] for more discussion on name syntax. (@). 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 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 yet prompted the user for a password, and so that information is NOT
included with this initial message (unlike the "password" method). included with this initial message (unlike the "password" method).
The server MUST reply with either a SSH_MSG_USERAUTH_SUCCESS, The server MUST reply with either a SSH_MSG_USERAUTH_SUCCESS,
SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message. SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST message.
The server SHOULD NOT reply with the SSH_MSG_USERAUTH_FAILURE 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 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 SHOULD send SSH_MSG_USERAUTH_INFO_REQUEST message(s) which look just
like the one(s) which would have been sent in cases where like the one(s) which would have been sent in cases where
authentication should proceed, and then send the failure message authentication should proceed, and then send the failure message
(after a suitable delay, as described below). The goal is to make it (after a suitable delay, as described below). The goal is to make it
impossible to find valid usernames by just comparing the results when impossible to find valid user names by just comparing the results
authenticating as different users. when authenticating as different users.
3.2 Information Requests 3.2 Information Requests
Requests are generated from the server using the Requests are generated from the server using the
SSH_MSG_USERAUTH_INFO_REQUEST message. SSH_MSG_USERAUTH_INFO_REQUEST message.
The server may send as many requests as are necessary to authenticate The server may send as many requests as are necessary to authenticate
the client; the client MUST be prepared to handle multiple exchanges. the client; the client MUST be prepared to handle multiple exchanges.
The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows: The SSH_MSG_USERAUTH_INFO_REQUEST message is defined as follows:
skipping to change at page 5, line 21 skipping to change at page 5, line 28
instruction (if non-empty) as a text message inside the dialog, and instruction (if non-empty) as a text message inside the dialog, and
the appropriate number of entry fields with the prompts as labels. A the appropriate number of entry fields with the prompts as labels. A
GUI client SHOULD NOT present each prompt in a separate window. GUI client SHOULD NOT present each prompt in a separate window.
All clients MUST properly handle an instruction field with embedded All clients MUST properly handle an instruction field with embedded
newlines. They MUST also be able to display at least 30 characters newlines. They MUST also be able to display at least 30 characters
for the name and prompts. If the server presents names/prompts for the name and prompts. If the server presents names/prompts
longer than 30 characters, the client MAY truncate these fields to longer than 30 characters, the client MAY truncate these fields to
the length it can display. If the client does truncate any fields, the length it can display. If the client does truncate any fields,
there SHOULD be an obvious indication that such truncation has there SHOULD be an obvious indication that such truncation has
occured. occurred.
Clients SHOULD use control character filtering as discussed in [SSH- Clients SHOULD use control character filtering as discussed in [SSH-
ARCH] to avoid attacks by including terminal control characters in ARCH] to avoid attacks by including terminal control characters in
the fields to be displayed. the fields to be displayed.
For each prompt, the corresponding echo field indicates whether or For each prompt, the corresponding echo field indicates whether or
not the user input should be echoed as characters are typed. Clients not the user input should be echoed or not. Clients SHOULD correctly
MUST correctly echo/mask user input for each prompt independently of handle echo for each prompt independently of other prompts in the
other prompts in the request message. Clients MUST NOT add any request message. Clients SHOULD NOT add any additional characters to
additional characters to the prompt such as ": "; the server is the prompt such as ": "; the server is responsible for supplying all
reponsible for supplying all text to be displayed to the user. text to be displayed to the user. Clients MUST also accept empty
Clients MUST also accept empty responses from the user and pass them responses from the user and pass them on as empty strings.
on as empty strings.
3.4 Information Responses 3.4 Information Responses
After obtaining the requested information from the user, the client After obtaining the requested information from the user, the client
MUST respond with a SSH_MSG_USERAUTH_INFO_RESPONSE message. MUST respond with a SSH_MSG_USERAUTH_INFO_RESPONSE message.
The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as The format of the SSH_MSG_USERAUTH_INFO_RESPONSE message is as
follows: follows:
byte SSH_MSG_USERAUTH_INFO_RESPONSE byte SSH_MSG_USERAUTH_INFO_RESPONSE
int num-responses int num-responses
string response[1] (ISO-10646 UTF-8) string response[1] (ISO-10646 UTF-8)
... ...
string response[num-responses] (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 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. the server how it interprets the responses and validates them.
However, if the client reads the responses in some other encoding 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 (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 before transmitting.
encoding used on that system that is needed to verify them.
If the num-responses field does not match the num-prompts field in If the num-responses field does not match the num-prompts field in
the request message, the server MUST send a failure message. the request message, the server MUST send a failure message.
In the case that the server sends a `0' num-prompts field in the 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' request message, the client MUST send a response message with a `0'
num-responses field. num-responses field.
After receiving the response, the server MUST send either a After receiving the response, the server MUST send either a
SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another
skipping to change at page 6, line 36 skipping to change at page 6, line 45
If the server responds with a failure message, it SHOULD delay a If the server responds with a failure message, it SHOULD delay a
minimum of 2 seconds before sending the failure message, to limit minimum of 2 seconds before sending the failure message, to limit
certain types of attacks. certain types of attacks.
4. Authentication Example 4. Authentication Example
Here is an example exchange between a client and server: Here is an example exchange between a client and server:
C: byte SSH_MSG_USERAUTH_REQUEST C: byte SSH_MSG_USERAUTH_REQUEST
C: string "foo" C: string "user23"
C: string "ssh-userauth" C: string "ssh-userauth"
C: string "keyboard-interactive" C: string "keyboard-interactive"
C: string "en-US" C: string "en-US"
C: string "password" C: string ""
S: byte SSH_MSG_USERAUTH_INFO_REQUEST S: byte SSH_MSG_USERAUTH_INFO_REQUEST
S: string "Password Authentication" S: string "Password Authentication"
S: string "Enter password for foo" S: string "Enter password for user23@server"
S: string "en-US"
S: int 1 S: int 1
S: string "Password: " S: string "Password: "
S: boolean FALSE S: boolean FALSE
S: string "en-US"
[Client prompts user for password] [Client prompts user for password]
C: byte SSH_MSG_USERAUTH_INFO_RESPONSE C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
C: int 1 C: int 1
C: string "bar" C: string "bar"
S: byte SSH_MSG_USERAUTH_INFO_REQUEST S: byte SSH_MSG_USERAUTH_INFO_REQUEST
S: string "Password Expired" S: string "Password Expired"
S: string "Your password has expired." S: string "Your password has expired, you must enter a new one"
S: string "en-US"
S: int 2 S: int 2
S: string "Enter new password: " S: string "New password: "
S: boolean FALSE S: boolean FALSE
S: string "Enter it again: " S: string "Enter it again: "
S: boolean FALSE S: boolean FALSE
S: string "en-US"
[Client prompts user for new password] [Client prompts user for new password]
C: byte SSH_MSG_USERAUTH_INFO_RESPONSE C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
C: int 2 C: int 2
C: string "baz" C: string "baz"
C: string "baz" C: string "baz"
S: byte SSH_MSG_USERAUTH_SUCCESS S: byte SSH_MSG_USERAUTH_SUCCESS
skipping to change at page 7, line 43 skipping to change at page 8, line 5
SSH_MSG_USERAUTH_INFO_RESPONSE 61 SSH_MSG_USERAUTH_INFO_RESPONSE 61
6. References 6. References
[PAM] Samar, V., Schemers, R., "Unified Login With Pluggable [PAM] Samar, V., Schemers, R., "Unified Login With Pluggable
Authentication Modules (PAM)", OSF RFC 86.0, October 1995 Authentication Modules (PAM)", OSF RFC 86.0, October 1995
[RFC-1766] Alvestrand, H., "Tags for the Identification of [RFC-1766] Alvestrand, H., "Tags for the Identification of
Languages", March 1995. Languages", March 1995.
[RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode [RFC-2279] Yergeau, F., "UTF-8, a Transformation Format of Unicode
and ISO 10646", October 1996. and ISO 10646", October 1996.
[SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol [SSH-ARCH] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S.
Architecture", Internet Draft, draft-ietf-secsh-architecture-03.txt Lehtinen, "SSH Protocol Architecture", Internet Draft, draft-ietf-
secsh-architecture-05.txt
[SSH-CONNECT] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH [SSH-CONNECT] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S.
Connection Protocol", Internet Draft, draft-ietf-secsh-connect-05.txt Lehtinen, "SSH Connection Protocol", Internet Draft, draft-ietf-
[SSH-TRANS] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Transport secsh-connect-07.txt
Layer Protocol", Internet Draft, draft-ietf-secsh-transport-05.txt
[SSH-USERAUTH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH [SSH-TRANS] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S.
Authentication Protocol", Internet Draft, draft-ietf-secsh-userauth- Lehtinen, "SSH Transport Layer Protocol", Internet Draft, draft-
05.txt ietf-secsh-transport-07.txt
[SSH-USERAUTH] T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S.
Lehtinen, "SSH Authentication Protocol", Internet Draft, draft-ietf-
secsh-userauth-07.txt
7. Author's Addresses 7. Author's Addresses
Frank Cusack Frank Cusack
Qwest Internet Solutions Qwest Internet Solutions
1200 Harbor Blvd, 8th Fl. 1200 Harbor Blvd, 8th Fl.
Weehawken, NJ 07087 Weehawken, NJ 07087
Email: fcusack@iconnet.net Email: fcusack@iconnet.net
Martin Forssen Martin Forssen
Firedoor Network Security AB Appgate AB
Stora Badhusgatan 18-20 Stora Badhusgatan 18-20
SE-411 21 Gothenburg SE-411 21 Gothenburg
SWEDEN SWEDEN
Email: maf@firedoor.se Email: maf@appgate.com
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/