The Secure Shell Protocol (SSH) is a protocol for secure remote login and other secure network services over an insecure network. My aim here is to describe the SSH authentication protocol framework and public key, password, and host-based client authentication methods.
The SSH authentication protocol runs on top of the SSH transport layer protocol and provides a single authenticated tunnel for the SSH connection protocol.
Authentication methods are identified by their name, as defined in
[SSH-ARCH]. The "none" method is reserved, and MUST NOT be listed as
supported. However, it MAY be sent by the client. The server MUST
always reject this request, unless the client is to be granted access
without any authentication, in which case, the server MUST accept
this request. The main purpose of sending this request is to get the
list of supported methods from the server.
The server SHOULD have a timeout for authentication and disconnect if the authentication has not been accepted within the timeout period.
The RECOMMENDED timeout period is 10 minutes. Additionally, the implementation SHOULD limit the number of failed authentication attempts a client may perform in a single session (the RECOMMENDED limit is 20 attempts). If the threshold is exceeded, the server SHOULD disconnect.
Only the first few fields are defined; the remaining fields depend on the authentication method.
byte : SSH_MSG_USERAUTH_REQUEST
string: user name in ISO-10646 UTF-8 encodin string: service name in US-ASCII string: method name in US-ASCII
.... : method specific fields
The 'user name' and 'service name' are repeated in every new authentication attempt, and MAY change. The server implementation MUST carefully check them in every message, and MUST flush any accumulated authentication states if they change. If it is unable to
flush an authentication state, it MUST disconnect if the 'user name' or 'service name' changes.
The 'service name' specifies the service to start after authentication. There may be several different authenticated services provided. If the requested service is not available, the
server MAY disconnect immediately or at any later time. Sending a proper disconnect message is RECOMMENDED. In any case, if the
service does not exist, authentication MUST NOT be accepted.
If the requested 'user name' does not exist, the server MAY disconnect, or MAY send a bogus list of acceptable authentication 'method name' values, but never accept any. This makes it possible for the server to avoid disclosing information on which accounts exist. In any case, if the 'user name' does not exist, the authentication request MUST NOT be accepted.
While there is usually little point for clients to send requests that the server does not list as acceptable, sending such requests is not an error, and the server SHOULD simply reject requests that it does not recognize.
An authentication request MAY result in a further exchange of messages. All such messages depend on the authentication 'method name' used, and the client MAY at any time continue with a new SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST abandon the previous authentication attempt and continue with the new one.
The following 'method name' values are defined.
"publickey" REQUIRED
"password" OPTIONAL "hostbased" OPTIONAL
"none" NOT RECOMMENDED
byte : SSH_MSG_USERAUTH_FAILUR
name-list: authentications that can continue
boolean: partial success
When the server accepts authentication, it MUST respond with the following:
byte: SSH_MSG_USERAUTH_SUCCESS
SSH_MSG_USERAUTH_SUCCESS. All authentication related messages received after sending this message SHOULD be silently ignored.
After sending SSH_MSG_USERAUTH_SUCCESS, the server starts the requested service.
After successful authentication, such messages are passed to the higher-level service.
These are the general authentication message codes:
SSH_MSG_USERAUTH_REQUEST 50
SSH_MSG_USERAUTH_FAILURE 51
SSH_MSG_USERAUTH_SUCCESS 52
SSH_MSG_USERAUTH_BANNER 53
In addition to the above, there is a range of message numbers (60 to79) reserved for method-specific messages. These messages are only
sent by the server (client sends only SSH_MSG_USERAUTH_REQUEST messages). Different authentication methods reuse the same message
numbers.
The SSH authentication protocol runs on top of the SSH transport layer protocol and provides a single authenticated tunnel for the SSH connection protocol.
Authentication methods are identified by their name, as defined in
[SSH-ARCH]. The "none" method is reserved, and MUST NOT be listed as
supported. However, it MAY be sent by the client. The server MUST
always reject this request, unless the client is to be granted access
without any authentication, in which case, the server MUST accept
this request. The main purpose of sending this request is to get the
list of supported methods from the server.
The server SHOULD have a timeout for authentication and disconnect if the authentication has not been accepted within the timeout period.
The RECOMMENDED timeout period is 10 minutes. Additionally, the implementation SHOULD limit the number of failed authentication attempts a client may perform in a single session (the RECOMMENDED limit is 20 attempts). If the threshold is exceeded, the server SHOULD disconnect.
Authentication Requests
All authentication requests MUST use the following message format.Only the first few fields are defined; the remaining fields depend on the authentication method.
byte : SSH_MSG_USERAUTH_REQUEST
string: user name in ISO-10646 UTF-8 encodin string: service name in US-ASCII string: method name in US-ASCII
.... : method specific fields
The 'user name' and 'service name' are repeated in every new authentication attempt, and MAY change. The server implementation MUST carefully check them in every message, and MUST flush any accumulated authentication states if they change. If it is unable to
flush an authentication state, it MUST disconnect if the 'user name' or 'service name' changes.
The 'service name' specifies the service to start after authentication. There may be several different authenticated services provided. If the requested service is not available, the
server MAY disconnect immediately or at any later time. Sending a proper disconnect message is RECOMMENDED. In any case, if the
service does not exist, authentication MUST NOT be accepted.
If the requested 'user name' does not exist, the server MAY disconnect, or MAY send a bogus list of acceptable authentication 'method name' values, but never accept any. This makes it possible for the server to avoid disclosing information on which accounts exist. In any case, if the 'user name' does not exist, the authentication request MUST NOT be accepted.
While there is usually little point for clients to send requests that the server does not list as acceptable, sending such requests is not an error, and the server SHOULD simply reject requests that it does not recognize.
An authentication request MAY result in a further exchange of messages. All such messages depend on the authentication 'method name' used, and the client MAY at any time continue with a new SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST abandon the previous authentication attempt and continue with the new one.
The following 'method name' values are defined.
"publickey" REQUIRED
"password" OPTIONAL "hostbased" OPTIONAL
"none" NOT RECOMMENDED
Responses to Authentication Requests
If the server rejects the authentication request, it MUST respond with the following:byte : SSH_MSG_USERAUTH_FAILUR
name-list: authentications that can continue
boolean: partial success
When the server accepts authentication, it MUST respond with the following:
byte: SSH_MSG_USERAUTH_SUCCESS
Completion of User Authentication
Authentication is complete when the server has responded withSSH_MSG_USERAUTH_SUCCESS. All authentication related messages received after sending this message SHOULD be silently ignored.
After sending SSH_MSG_USERAUTH_SUCCESS, the server starts the requested service.
Authentication Protocol Message Numbers
All message numbers used by this authentication protocol are in the range from 50 to 79, which is part of the range reserved for protocols running on top of the SSH transport layer protocol. Message numbers of 80 and higher are reserved for protocols running after this authentication protocol, so receiving one of them before authentication is complete is an error, to which the server MUST respond by disconnecting, preferably with a proper disconnect message sent to ease troubleshooting.After successful authentication, such messages are passed to the higher-level service.
These are the general authentication message codes:
SSH_MSG_USERAUTH_REQUEST 50
SSH_MSG_USERAUTH_FAILURE 51
SSH_MSG_USERAUTH_SUCCESS 52
SSH_MSG_USERAUTH_BANNER 53
In addition to the above, there is a range of message numbers (60 to79) reserved for method-specific messages. These messages are only
sent by the server (client sends only SSH_MSG_USERAUTH_REQUEST messages). Different authentication methods reuse the same message
numbers.
