Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)
Extracted elements (25)
The keyboard-interactive method was designed so that SSH clients require little or no knowledge of the underlying authentication mechanism(s), allowing the server to arbitrarily select or change authentication mechanisms without requiring client code updates — a significant advantage over tightly-coupled methods like 'password'.
To prevent username enumeration, the server should not distinguish failed authentication due to invalid usernames from valid ones; it should proceed as if authentication is continuing (sending INFO_REQUEST) and only send failure after a suitable delay (suggested default: 2 seconds).
The client MUST be prepared to handle multiple SSH_MSG_USERAUTH_INFO_REQUEST/RESPONSE exchanges in sequence, as the server may send as many requests as needed. However, only one request may be outstanding at a time.
When num-prompts is 0 in an INFO_REQUEST, the client SHOULD still display name and instruction fields. The client MUST send a response with num-responses set to 0 to complete the exchange.
After receiving an INFO_RESPONSE, the server MUST send either SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another SSH_MSG_USERAUTH_INFO_REQUEST. If authentication fails, the server SHOULD NOT send additional request messages to obtain new data; it SHOULD send a failure message.
All clients MUST properly handle an instruction field with embedded newlines, and SHOULD be able to display at least 30 characters for name and prompt fields. If truncation occurs, there MUST be an obvious indication.
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 SHOULD use control character filtering, as discussed in SSH-ARCH, to avoid attacks by including terminal control characters in the fields to be displayed.
If the client does not honor the echo field for a prompt, it MUST err on the side of masking input. Clients MUST also accept empty responses from the user and pass them on as empty strings.
If the client has knowledge of preferred submethods it MAY pass them as a comma-separated list; otherwise it MUST send the empty string. Server interpretation of submethods is implementation-dependent.
If the num-responses field does not match the num-prompts field in the request message, the server MUST send a failure message.
Responses MUST be encoded in ISO-10646 UTF-8. If the client reads responses in another encoding (e.g., ISO 8859-1), it MUST convert them to UTF-8 before transmitting.
Systems supporting non-ASCII passwords SHOULD always normalize passwords and usernames when added to a database or compared to existing entries. SSH implementations that store and compare passwords SHOULD use SASLprep (RFC 4013) for normalization.
The language tag field in SSH_MSG_USERAUTH_REQUEST and SSH_MSG_USERAUTH_INFO_REQUEST is deprecated and SHOULD be the empty string; the server SHOULD instead select language based on tags communicated during key exchange.
The prompt field(s) in SSH_MSG_USERAUTH_INFO_REQUEST MUST NOT be empty strings, while the name and instruction fields MAY be empty; the client MUST be prepared to handle empty name and instruction fields.
The server MUST NOT send another SSH_MSG_USERAUTH_INFO_REQUEST before it has received the answer from the client; only one outstanding request is permitted at a time.
The server MUST reply to the initial SSH_MSG_USERAUTH_REQUEST with one of SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or SSH_MSG_USERAUTH_INFO_REQUEST.
The server SHOULD NOT reply with SSH_MSG_USERAUTH_FAILURE if the failure is based on the user name or service name; instead it SHOULD send INFO_REQUEST message(s) that look identical to normal authentication, then send the failure after a suitable delay, to prevent username enumeration.
The 'keyboard-interactive' authentication method uses a message exchange where the client sends SSH_MSG_USERAUTH_REQUEST, the server issues one or more SSH_MSG_USERAUTH_INFO_REQUEST messages, and the client responds with SSH_MSG_USERAUTH_INFO_RESPONSE messages. The method name is 'keyboard-interactive'.
IANA registration: the userauth type 'keyboard-interactive' is defined for use with the SSH authentication protocol. Message numbers SSH_MSG_USERAUTH_INFO_REQUEST (60) and SSH_MSG_USERAUTH_INFO_RESPONSE (61) are assigned as method-specific constants.
The keyboard-interactive authentication method depends on the confidentiality of the underlying SSH transport layer. Without transport-layer confidentiality, all authentication data passed using this method is subject to interception.
The number of client-server exchanges to complete authentication may be variable, and an observer could gain information by counting exchanges. For example, an observer may infer that a user's password has expired and potentially determine the site's password expiration policy.
SSH_MSG_USERAUTH_INFO_REQUEST contains: byte (message type), string (name, UTF-8), string (instruction, UTF-8), string (language tag, deprecated), int (num-prompts), followed by num-prompts pairs of string (prompt, UTF-8) and boolean (echo).
SSH_MSG_USERAUTH_INFO_RESPONSE contains: byte (message type), int (num-responses), followed by num-responses strings (response[1..n], ISO-10646 UTF-8). Responses MUST be ordered to match the prompts.
SSH_MSG_USERAUTH_REQUEST for keyboard-interactive contains: byte (message type), string (user name, UTF-8), string (service name, US-ASCII), string ('keyboard-interactive', US-ASCII), string (language tag, deprecated), string (submethods, UTF-8).