aboutsummaryrefslogtreecommitdiff
path: root/doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt')
-rw-r--r--doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt366
1 files changed, 0 insertions, 366 deletions
diff --git a/doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt b/doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt
deleted file mode 100644
index b22a6632..00000000
--- a/doc/draft-ietf-secsh-auth-kbdinteract-05-cleaned.txt
+++ /dev/null
@@ -1,366 +0,0 @@
-
- Generic Message Exchange Authentication For SSH
- <draft-ietf-secsh-auth-kbdinteract-05.txt>
-
-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).
-
-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".
-
-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.
-
- 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
- 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.
-
- 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
-
- 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)
-
- 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 ""
-
- 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"
-
- 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