aboutsummaryrefslogtreecommitdiff
path: root/doc/draft-ietf-secsh-auth-kbdinteract-05.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/draft-ietf-secsh-auth-kbdinteract-05.txt')
-rw-r--r--doc/draft-ietf-secsh-auth-kbdinteract-05.txt619
1 files changed, 619 insertions, 0 deletions
diff --git a/doc/draft-ietf-secsh-auth-kbdinteract-05.txt b/doc/draft-ietf-secsh-auth-kbdinteract-05.txt
new file mode 100644
index 0000000..99504db
--- /dev/null
+++ b/doc/draft-ietf-secsh-auth-kbdinteract-05.txt
@@ -0,0 +1,619 @@
+
+
+
+Network Working Group F. Cusack
+INTERNET-DRAFT Google, Inc.
+Expires November 1, 2003 M. Forssen
+ Appgate AB
+ May 1, 2003
+
+
+
+
+ Generic Message Exchange Authentication For SSH
+ <draft-ietf-secsh-auth-kbdinteract-05.txt>
+
+Status of this Memo
+
+ This document is an Internet-Draft and is subject to 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>.
+
+ This Internet-Draft will expire on November 1, 2003.
+
+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 Expires November 1, 2003 [Page 1]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+1. Introduction
+
+ The SSH authentication protocol [SSH-USERAUTH] is a general-purpose
+ user authentication protocol. It is intended to be run over the SSH
+ transport layer protocol [SSH-TRANS]. The authentication protocol
+ assumes that the underlying protocols provide integrity and
+ confidentiality protection.
+
+ This document describes a general purpose authentication method for
+ the SSH authentication protocol. This method is suitable for
+ interactive authentication methods which do 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
+ described here anyway 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.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC-2119].
+
+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.
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 2]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ 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
+ 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
+ SSM_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, as defined in [RFC-2279])
+ string service name (US-ASCII)
+ string "keyboard-interactive" (US-ASCII)
+ string language tag (as defined in [RFC-3066])
+ string submethods (ISO-10646 UTF-8)
+
+ The language tag is deprecated and SHOULD be the empty string. It
+ may be removed in a future revision of this specification. The
+ server SHOULD instead select the language used based on the tags
+ communicated during key exchange [SSH-TRANS].
+
+ If the language tag is not the empty string, the server SHOULD use
+ the specified language for any messages sent to the client as part of
+ this protocol. The language tag SHOULD NOT be used for language
+ selection for messages outside of this protocol. The language to be
+ used if the server does not support the requested language is
+ implementation-dependent.
+
+ The submethods field is included so the user can give a hint of which
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 3]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ 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.
+
+ 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 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.
+ However the server MUST NOT ever have more than one
+ SSH_MSG_USERAUTH_INFO_REQUEST message outstanding. That is, it may
+ not send another request before the client has answered.
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 4]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ 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-3066])
+ 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 take into consideration that some clients may not
+ be able to properly display a long name or prompt field (see next
+ section), and limit the lengths of those fields if possible. For
+ example, instead of an instruction field of "Enter Password" and a
+ prompt field of "Password for user23@host.domain: ", a better choice
+ might be an instruction field of
+ "Password authentication for user23@host.domain" and a prompt field
+ of "Password: ". It is expected that this authentication method
+ would typically be backended by [PAM] and so such choices would not
+ be possible.
+
+ The name and instruction fields MAY be empty strings, the client MUST
+ be prepared to handle this correctly. The prompt field(s) MUST NOT
+ be empty strings.
+
+ The language tag SHOULD describe the language used in the textual
+ fields. If the server does not know the language used, or if
+ multiple languages are used, the language tag MUST be the empty
+ string.
+
+ The num-prompts field may be `0', in which case there will be no
+ prompt/echo fields in the message, but the client SHOULD 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 SHOULD display the prompt and read the user input.
+
+ A graphical user interface (GUI) client has many choices on how to
+ prompt the user. One possibility is to use the name field (possibly
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 5]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ prefixed with the application's name) as the title of a dialog window
+ in which the prompt(s) are presented. In that dialog window, the
+ instruction field would be a text message, and the prompts would be
+ labels for text entry fields. All fields SHOULD be presented to the
+ user, for example an implementation SHOULD NOT discard the name field
+ because its windows lack titles; it SHOULD instead find another way
+ to display this information. If prompts are presented in a dialog
+ window, then the client SHOULD NOT present each prompt in a separate
+ window.
+
+ All clients MUST properly handle an instruction field with embedded
+ newlines. They SHOULD also be able to display at least 30 characters
+ for the name and prompts. If the server presents names or 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 MUST be an obvious indication that such truncation has occured.
+ The instruction field SHOULD NOT be truncated.
+
+ 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
+ SHOULD correctly echo/mask user input for each prompt independently
+ of other prompts in the request message. If a client does not honor
+ the echo field for whatever reason, then the client MUST err on the
+ side of masking input. A GUI client might like to have a checkbox
+ toggling echo/mask. Clients SHOULD NOT add any additional characters
+ to the prompt such as ": " (colon-space); 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)
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 6]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ 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.
+
+ The responses MUST be ordered as the prompts were ordered. That is,
+ response[n] MUST be the answer to prompt[n].
+
+ 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
+ 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 Examples
+
+ Here are two example exchanges between a client and server. The
+ first is an example of challenge/response with a handheld token.
+ This is an authentication that is not otherwise possible with other
+ authentication methods.
+
+ C: byte SSH_MSG_USERAUTH_REQUEST
+ C: string "user23"
+ C: string "ssh-userauth"
+ C: string "keyboard-interactive"
+ C: string ""
+ C: string ""
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 7]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ 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
+
+ The second example is of a standard password authentication, in
+ this case the user's password is expired.
+
+ 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 "Password Authentication"
+ S: string ""
+ S: string "en-US"
+ S: int 1
+ S: string "Password: "
+ S: boolean FALSE
+
+ [Client prompts user for password]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 1
+ C: string "password"
+
+
+
+
+
+
+
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 8]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ S: byte SSH_MSG_USERAUTH_INFO_REQUEST
+ S: string "Password Expired"
+ S: string "Your password has expired."
+ S: string "en-US"
+ S: int 2
+ S: string "Enter new password: "
+ S: boolean FALSE
+ S: string "Enter it again: "
+ S: boolean FALSE
+
+ [Client prompts user for new password]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 2
+ C: string "newpass"
+ C: string "newpass"
+
+ S: byte SSH_MSG_USERAUTH_INFO_REQUEST
+ S: string "Password changed"
+ S: string "Password successfully changed for user23."
+ S: string "en-US"
+ S: int 0
+
+ [Client displays message to user]
+
+ C: byte SSH_MSG_USERAUTH_INFO_RESPONSE
+ C: int 0
+
+ S: byte SSH_MSG_USERAUTH_SUCCESS
+
+5. IANA Considerations
+
+ The userauth type "keyboard-interactive" is used for this
+ authentication method.
+
+ The following method-specific constants are used with this
+ authentication method:
+
+ SSH_MSG_USERAUTH_INFO_REQUEST 60
+ SSH_MSG_USERAUTH_INFO_RESPONSE 61
+
+6. Security Considerations
+
+ The authentication protocol, and this authentication method, depends
+ on the security of the underlying SSH transport layer. Without the
+ confidentiality provided therein, any authentication data passed with
+ this method is subject to interception.
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 9]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+ The number of client-server exchanges required to complete an
+ authentication using this method may be variable. It is possible
+ that an observer may gain valuable information simply by counting
+ that number. For example, an observer may guess that a user's
+ password has expired, and with further observation may be able to
+ determine the frequency of a site's password expiration policy.
+
+7. References
+
+7.1 Normative References
+
+
+ [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Level", BCP 14, RFC 2119, March 1997.
+
+
+ [RFC-2279] Yergeau, F., "UTF-8, a transformation format of
+ Unicode and ISO 10646", RFC 2279, October 1996.
+
+
+ [RFC-3066] Alvestrand, H., "Tags for the Identification of
+ Languages", BCP 47, RFC 3066, January 2001.
+
+
+ [SSH-ARCH] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
+ Lehtinen, S., "SSH Protocol Architecture", work in
+ progress, draft-ietf-secsh-architecture-13.txt,
+ September, 2002.
+
+
+ [SSH-CONNECT] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
+ Lehtinen, S., "SSH Connection Protocol", work in
+ progress, draft-ietf-secsh-connect-16.txt, September,
+ 2002.
+
+
+ [SSH-TRANS] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
+ Lehtinen, S., "SSH Transport Layer Protocol", work in
+ progress, draft-ietf-secsh-transport-15.txt,
+ September, 2002.
+
+
+ [SSH-USERAUTH] Ylonen, T., Kivinen, T, Saarinen, M., Rinne, T., and
+ Lehtinen, S., "SSH Authentication Protocol", work in
+ progress, draft-ietf-secsh-userauth-16.txt,
+ September, 2002.
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 10]
+
+Internet Draft SSH Generic Interactive Authentication May 1, 2003
+
+
+7.2 Informative References
+
+
+ [PAM] Samar, V., Schemers, R., "Unified Login With
+ Pluggable Authentication Modules (PAM)", OSF RFC
+ 86.0, October 1995
+
+8. Author's Addresses
+
+ Frank Cusack
+ Google, Inc.
+ 2400 Bayshore Parkway
+ Mountain View, CA 94043
+ Email: frank@google.com
+
+ Martin Forssen
+ Appgate AB
+ Stora Badhusgatan 18-20
+ SE-411 21 Gothenburg
+ SWEDEN
+ Email: maf@appgate.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+F. Cusack, M. Forssen Expires November 1, 2003 [Page 11]
+ \ No newline at end of file