The Secure Shell (SSH) Authentication Protocol
updated by
Extracted elements (28)
A preliminary query message (with boolean FALSE) is provided so clients can check whether a particular public key is acceptable before performing the expensive signing computation or prompting the user for a passphrase to decrypt a stored private key.
Host-based authentication is similar to UNIX 'rhosts' and 'hosts.equiv' but checks client host identity more rigorously using cryptographic host keys rather than IP addresses alone. It is explicitly noted as not suitable for high-security sites.
A client MUST NOT send a subsequent authentication request if it has not received a response from the server for a previous request. A SSH_MSG_USERAUTH_FAILURE message MUST NOT be sent for an aborted method.
For host-based authentication, the server MUST verify that the host key belongs to the named client host, that the given user on that host is allowed to log in, and that the signature is valid. It is RECOMMENDED that the server also verify the network address matches the given client host name.
If no confidentiality is provided (i.e., 'none' cipher is in use), password authentication SHOULD be disabled. If there is no confidentiality or no MAC, password change SHOULD be disabled.
If the banner 'message' string is displayed, control character filtering SHOULD be used to avoid attacks by sending terminal control characters.
If the client reads a password in an encoding other than UTF-8 (e.g., ISO 8859-1), it MUST convert the password to ISO-10646 UTF-8 before transmitting, and the server MUST convert the password to the encoding used on that system.
If the requested 'user name' does not exist, the authentication request MUST NOT be accepted. The server MAY send a bogus list of acceptable authentication method names to avoid disclosing information on which accounts exist.
If the server receives a message with a number of 80 or higher before authentication is complete, it MUST respond by disconnecting, preferably with a proper disconnect message.
SSH_MSG_USERAUTH_SUCCESS MUST be sent only once. After it is sent, any further authentication requests received SHOULD be silently ignored. Non-authentication messages received after success MUST be passed to the service running on top of this protocol.
Systems supporting non-ASCII passwords SHOULD always normalize passwords and user names when added to or compared against the database. SSH implementations that both store and compare passwords SHOULD use RFC4013 (SASLprep) for normalization.
The 'none' authentication method MUST NOT be listed as supported by the server. The server MUST always reject a 'none' request unless the client is to be granted access without any authentication, in which case the server MUST accept it.
The 'publickey' authentication method is the only REQUIRED method; all implementations MUST support it. The server MUST check that the key is a valid authenticator for the user and that the signature is valid; if both hold, the request MUST be accepted.
The server MUST carefully check 'user name' and 'service name' in every SSH_MSG_USERAUTH_REQUEST message, and MUST flush any accumulated authentication states if they change. If it is unable to flush an authentication state, it MUST disconnect if these fields change.
The server MUST NOT allow an expired password to be used for authentication; it SHOULD indicate expiry by responding with SSH_MSG_USERAUTH_PASSWD_CHANGEREQ.
The server SHOULD have a timeout for authentication and disconnect if authentication has not been accepted within the timeout period. The RECOMMENDED timeout is 10 minutes. The implementation SHOULD limit failed authentication attempts to a RECOMMENDED maximum of 20 per session, and SHOULD disconnect if exceeded.
Authentication protocol message numbers occupy the range 50–79. Message numbers 80 and higher are reserved for protocols running after authentication; receiving one before authentication is complete is an error requiring disconnection. Method-specific messages occupy the range 60–79.
The 'none' authentication request allows a client to obtain the list of supported authentication methods from the server. If no authentication is needed, the server MUST return SSH_MSG_USERAUTH_SUCCESS; otherwise it MUST return SSH_MSG_USERAUTH_FAILURE with available methods.
The SSH authentication protocol runs over the SSH transport layer protocol and provides a single authenticated tunnel for the SSH connection protocol. Its service name is 'ssh-userauth'. It receives the session identifier (exchange hash H from first key exchange) from the lower-level protocol.
IANA considerations for the SSH authentication protocol, including authentication method names ('publickey', 'password', 'hostbased', 'none') and message numbers (50–79), are governed by RFC 4250 (SSH-NUMBERS) as part of the SSH protocol set.
The authentication protocol assumes it runs over a secure transport layer that has already authenticated the server, established an encrypted channel, and computed a unique session identifier. The transport layer provides forward secrecy for password authentication and other methods relying on secret data.
All authentication requests use SSH_MSG_USERAUTH_REQUEST (byte), followed by user name (string, UTF-8), service name (string, US-ASCII), method name (string, US-ASCII), and method-specific fields. The user name and service name MAY change between attempts.
Host-based authentication sends SSH_MSG_USERAUTH_REQUEST with 'hostbased', public key algorithm (string), public host key and certificates (string), client FQDN (string, US-ASCII), client user name (string, UTF-8), and signature (string). The signature covers the session identifier and all request fields.
Password authentication sends SSH_MSG_USERAUTH_REQUEST with 'password', boolean FALSE, and plaintext password (string, UTF-8). Password change request sends boolean TRUE with both old and new passwords (both UTF-8 strings). Server may respond with SSH_MSG_USERAUTH_PASSWD_CHANGEREQ (60) if the password has expired.
Public key authentication query (to check acceptability before signing) sends SSH_MSG_USERAUTH_REQUEST with 'publickey', boolean FALSE, public key algorithm name (string), and public key blob (string). Server responds with SSH_MSG_USERAUTH_PK_OK (60) or SSH_MSG_USERAUTH_FAILURE.
Public key authentication signature packet sends SSH_MSG_USERAUTH_REQUEST with 'publickey', boolean TRUE, public key algorithm name (string), public key (string), and signature (string). The signature covers: session identifier, SSH_MSG_USERAUTH_REQUEST, user name, service name, 'publickey', TRUE, algorithm name, and public key.
SSH_MSG_USERAUTH_BANNER message (byte 53) contains: message (string, UTF-8) and language tag (string, RFC3066). The server MAY send this at any time after the authentication protocol starts and before authentication is successful.
SSH_MSG_USERAUTH_FAILURE response contains: byte (message code 51), name-list of authentications that can continue (comma-separated), and boolean 'partial success' (TRUE if the prior request was successful, FALSE otherwise).