Network Working Group T. Ylonen INTERNET-DRAFT T. Kivinen draft-ietf-secsh-userauth-05.txt M. Saarinen Expires in six months T. Rinne S. Lehtinen SSH 22 February 1999 SSH Authentication Protocol Status of This memo This document is an Internet-Draft and is in full conformance with 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. Abstract SSH is a protocol for secure remote login and other secure network ser- vices over an insecure network. This document describes the SSH authen- tication protocol framework and public key, password, and host-based client authentication methods. Additional authentication methods are deferred to separate documents. The SSH authentication protocol runs on top the SSH transport layer protocol and provides a single authenticated tunnel for the SSH connection protocol. T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 1] INTERNET-DRAFT 6 August 1998 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. The Authentication Protocol Framework . . . . . . . . . . . . . 2 2.1. Authentication Requests . . . . . . . . . . . . . . . . . . 3 2.2. Responses to Authentication Requests . . . . . . . . . . . . 3 2.3. The none Authentication Request . . . . . . . . . . . . . . 4 2.4. Completion of User Authentication . . . . . . . . . . . . . 5 2.5. Banner Message . . . . . . . . . . . . . . . . . . . . . . . 5 3. Authentication Protocol Message Numbers . . . . . . . . . . . . 5 4. Public Key Authentication Method: publickey . . . . . . . . . . 6 5. Password Authentication Method: password . . . . . . . . . . . . 7 6. Host-Based Authentication: hostbased . . . . . . . . . . . . . . 9 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 10 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 9. Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 1. Introduction The SSH authentication protocol is a general-purpose user authentication protocol. It is intended to be run over the SSH transport layer protocol [SSH-TRANS]. This protocol assumes that the underlying protocols provide integrity and confidentiality protection. This document should be read only after reading the SSH architecture document [SSH-ARCH]. This document freely uses terminology and notation from the architecture document without reference or further explanation. The service name for this protocol is "ssh-userauth". When this protocol starts, it receives the session identifier from the lower-level protocol. The session identifier uniquely identifies this session and is suitable for signing to prove ownership of a private key. This protocol also needs to know whether the lower-level protocol provides confidentiality protection. 2. The Authentication Protocol Framework The server drives the authentication by telling the client which authentications can usefully continue the dialog at any given time. The client has the freedom to try the methods listed by the server in any order. This gives the server complete control over the authentication process if it so desired, but also gives enough flexibility for the client to use the methods it supports or that are most convenient for the user when multiple methods are offered by the server. Authentication methods are identified by names, 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 allowed in without any authentication, in which case the server MUST accept this T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 2] INTERNET-DRAFT 6 August 1998 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. 2.1. 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 encoding) string service name (in US-ASCII) string method name (US-ASCII) rest of the packet is method-specific The user name and service 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 state if they change. If it is unable to flush some authentication state, it MUST disconnect if the user 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 any time later. 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 does not exist, the server MAY disconnect, or MAY send a bogus list of acceptable authentications but never accept any. This makes it possible for the server to avoid disclosing information about which accounts exist. In any case, if the user 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 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. T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 3] INTERNET-DRAFT 6 August 1998 2.2. Responses to Authentication Requests If the server rejects the authentication request, it MUST respond with byte SSH_MSG_USERAUTH_FAILURE string authentications that can continue boolean partial success "Authentications that can continue" is a comma-separated list of authentication method names that may productively continue the authentication dialog. It is RECOMMENDED that servers only include those methods in the list that are actually useful. However, it is not illegal to include methods that cannot be used to authenticate the user. Already successfully completed authentications SHOULD NOT be included in the list, unless they really should be performed again for some reason. "Partial success" MUST be true if the authentication request to which this is a response was successful. It MUST be false if the request was not successfully processed. When the server accepts authentication, it MUST respond with byte SSH_MSG_USERAUTH_SUCCESS Note that this is not sent after each step in a multi-method authentica- tion sequence, but only when authentication is complete. The client MAY send several authentication requests without waiting for responses from previous requests. The server MUST acknowledge any failed requests with a SSH_MSG_USERAUTH_FAILURE message. However, SSH_MSG_USERAUTH_SUCCESS MUST sent only once, and once SSH_MSG_USERAUTH_SUCCESS has been sent, any further authentication requests received after that SHOULD be silently ignored. Any non-authentication messages sent by the client after the request that resulted in SSH_MSG_USERAUTH_SUCCESS being sent MUST be passed to the service being run on top of this protocol. Such messages can be identified by their message numbers (see Section ``Message Numbers''). 2.3. The none Authentication Request A client may request a list of authentication methods that may continue by using the "none" authentication method. If no authentication at all is needed for the user, the server MUST return SSH_MSG_USERAUTH_SUCCESS. Otherwise, the server MUST return SSH_MSG_USERAUTH_FAILURE and MAY return with it a list of authentication methods that can continue. This method MUST NOT be listed as supported by the server. T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 4] INTERNET-DRAFT 6 August 1998 2.4. Completion of User Authentication Authentication is complete when the server has responded with 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. 2.5. Banner Message In some jurisdictions, sending a warning message before authentication may be relevant to getting legal protection. Many UNIX machines, for example, normally display text from /etc/issue, or use "tcp wrappers" or similar software to display a banner before issuing a login prompt. The SSH server may send a SSH_MSG_USERAUTH_BANNER message at any time before authentication is successful. This message contains text to be displayed to the client user before authentication is attempted. The format is as follows. byte SSH_MSG_USERAUTH_BANNER string message (ISO-10646 UTF-8) string language tag (as defined in RFC 1766) The client SHOULD by default display the message on the screen. However, since the message is likely to be sent for every login attempt, and since some client software will need to open a separate window for this warning, the client software may allow the user to explicitly disable the display of banners from the server. The message may consist of multiple lines. If the message string is displayed, control character filtering discussed in [SSH-ARCH] SHOULD be used to avoid attacks by sending terminal control characters. 3. Authentication Protocol Message Numbers All message numbers used by this authentication protocol are in the range 50..79, which is part of the range reserved for protocols running on top of the SSH transport layer protocol. Message numbers 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 first to ease troubleshooting). After successful authentication, such messages are passed to the higher- level service. These are the general authentication message codes: T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 5] INTERNET-DRAFT 6 August 1998 #define SSH_MSG_USERAUTH_REQUEST 50 #define SSH_MSG_USERAUTH_FAILURE 51 #define SSH_MSG_USERAUTH_SUCCESS 52 #define SSH_MSG_USERAUTH_BANNER 53 In addition to the above, there is a range of message numbers (25..29) reserved for method-specific messages. These messages are only sent by the server (client only sends SSH_MSG_USERAUTH_REQUEST messages). Different authentication methods reuse the same message numbers. 4. Public Key Authentication Method: publickey The only REQUIRED authentication method is public key authentication. All implementations MUST support this method; however, not all users need to have public keys, and most local policies are not likely to require public key authentication for all users in near future. With this method, the possession of a private key serves as authentication. This method works by sending a signature created with a private key of the user. The server MUST check that the key is a valid authenticator for the user, and MUST check that the signature is valid. If both hold, the authentication request MUST be accepted; otherwise it MUST be rejected. (Note that the server MAY require additional authentications after successful authentication.) Private keys are often stored encrypted at the client host, and the user must supply a passphrase before the signature can be generated. Even if they are not, the signing operation involves some expensive computation. To avoid unnecessary processing and user interaction, the following message is provided for querying whether authentication using the key would be acceptable. byte SSH_MSG_USERAUTH_REQUEST string user name string service string "publickey" boolean FALSE string public key algorithm name string public key blob Public key algorithms are defined in the transport layer specification [SSH-TRANS]. The public key blob may contain certificates. Any public key algorithm may be offered for use in authentication. In particular, the list is not constrained by what was negotiated during key exchange (as that was affected by which algorithms the server had a host key). If the server does not support some algorithm, it MUST simply reject the request. The server MUST respond to this message with either SSH_MSG_USERAUTH_FAILURE or with byte SSH_MSG_USERAUTH_PK_OK T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 6] INTERNET-DRAFT 6 August 1998 string public key algorithm name from the request string public key blob from the request To do actual authentication, the client MAY then send a signature generated using the private key. Client MAY send the signature directly without first verifying whether the key is acceptable. The signature is sent using the following packet byte SSH_MSG_USERAUTH_REQUEST string user name string service string "publickey" boolean TRUE string public key algorithm name string public key to be used for authentication string signature Signature is a signature by the corresponding private key over the following data, in this order: o session identifier, and o packet payload without the signature. When the server receives this message, it MUST check whether the supplied key is acceptable for authentication, and if so, it MUST check whether the signature is correct. If both checks succeed, this method is successful. Note that the server may require additional authentications. The server MUST respond with SSH_MSG_USERAUTH_SUCCESS (if no more authentications are needed), or SSH_MSG_USERAUTH_FAILURE (if the request failed, or more authentications are needed). The following method-specific message numbers are used by the publickey authentication method. /* Key-based */ #define SSH_MSG_USERAUTH_PK_OK 60 5. Password Authentication Method: password Password authentication uses the following packets. Note that a server MAY request the user to change password. All implementations SHOULD support password authentication. byte SSH_MSG_USERAUTH_REQUEST string user name string service string "password" boolean FALSE string plaintext password (ISO-10646 UTF-8) T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 7] INTERNET-DRAFT 6 August 1998 Note that the password is encoded in ISO-10646 UTF-8. It is up to the server how it interprets the password and validates it against the password database. However, if the client reads the password in some other encoding (e.g., ISO 8859-1 (ISO Latin1)), 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 for passwords. Note that even though the cleartext password is transmitted in the packet, the entire packet is encrypted by the transport layer. Both the server and the client should check whether the underlying transport layer provides confidentiality (i.e., encryption is being used). If no confidentiality is provided ("none" cipher), password authentication SHOULD be disabled. If there is no confidentiality or no MAC, password change SHOULD be disabled. Normally, the server responds to this message with success or failure. However, the server MAY also respond with SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ string prompt (ISO-10646 UTF-8) string language tag (as defined in RFC 1766) In this case, the software client SHOULD request a new password from the user, and send a new request using the following message. The client may also send this message instead of the normal password authentication request without the server asking for it. byte SSH_MSG_USERAUTH_REQUEST string user name string service string "password" boolean TRUE string plaintext old password (ISO-10646 UTF-8) string plaintext new password (ISO-10646 UTF-8) The server must reply to request message with SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or another SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. The meaning of these is as follows: SSH_MSG_USERAUTH_SUCCESS Password has been changed, and authentication has been successfully completed. SSH_MSG_USERAUTH_FAILURE with partial success The password has been changed, but more authentications are needed. SSH_MSG_USERAUTH_FAILURE without partial success The password has not been changed. Either password changing was not supported, or the old password was bad. Note that if the server has already sent SSH_MSG_USERAUTH_PASSWD_CHANGEREQ, we know that it supports changing the password. T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 8] INTERNET-DRAFT 6 August 1998 SSH_MSG_USERAUTH_CHANGEREQ The password was not changed because the new password was not acceptable (e.g. too easy to guess). The following method-specific message numbers are used by the password authentication method. #define SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 60 6. Host-Based Authentication: hostbased Some sites wish to allow authentication based on the host where the user is coming from and the user name on the remote host. While this form of authentication is not suitable for high-security sites, it can be very convenient in many environments. This form of authentication is OPTIONAL. When used, special care SHOULD be taken to prevent a regular user from obtaining the private host key. The client requests this form of authentication by sending the following message. It is similar to the UNIX "rhosts" and "hosts.equiv" styles of authentication, except that the identity of the client host is checked more rigorously. This method works by having the client send a signature created with the private key of the client host, which the server checks with that host's public key. Once the client host's identity is established, authorization, but no further authentication, is performed based on the user names on the server and client, and the client host name. byte SSH_MSG_USERAUTH_REQUEST string user name string service string "hostbased" string public key algorithm for host key string public host key and certificates for client host string client host name (FQDN; US-ASCII) string client user name on the remote host (ISO-10646 UTF-8) string signature Public key algorithm names for use in "public key algorithm for host key" are defined in the transport layer specification. The "public host key for client host" may include certificates. Signature is a signature with the private host key of the following data, in this order: o session identifier, and o packet payload without the signature. The server MUST verify that the host key actually belongs to the client host named in the message, that the given user on that host is allowed to log in, and that the signature is a valid signature on the appropriate value by the given host key. The server MAY ignore the T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 9] INTERNET-DRAFT 6 August 1998 client user name, if it wants to authenticate only the client host. It is RECOMMENDED that whenever possible, the server perform additional checks to verify that the network address obtained from the (untrusted) network matches the given client host name. This makes exploiting compromised host keys more difficult. Note that this may require special handling for connections coming through a firewall. 7. Security Considerations The purpose of this protocol is to perform client user authentication. It assumed that this runs over a secure transport layer protocol, which has already authenticated the server machine, established an encrypted communications channel, and computed a unique session identifier for this session. The transport layer provides forward secrecy for password authentication and other methods that rely on secret data. The server may go into a "sleep" period after repeated unsuccesful authentications to make key search harder. If the transport layer does not provide encryption, authentication methods that rely on secret data SHOULD be disabled. If it does not provide MAC protection, requests to change authentication data (e.g. password change) SHOULD be disabled to avoid an attacker from modifying the ciphertext without being noticed, rendering the new authentication data unusable (denial of service). Several authentication methods with different security characteristics are allowed. It is up to the server's local policy to decide which methods (or combinations of methods) it is willing to accept for each user. Authentication is no stronger than the weakest combination allowed. Special care should be taken when designing debug messages. These messages may reveal surprising amounts of information about the host if not properly designed. Debug messages can be disabled (during user authentication phase) if high security is sought after. 8. References [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages", March 1995. [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and ISO 10646", October 1996. [SSH-ARCH] Ylonen, T., et al, "SSH Protocol Architecture", Internet Draft, draft-secsh-architecture-03.txt [SSH-TRANS] Ylonen, T., et al, "SSH Transport Layer Protocol", Internet Draft, draft-secsh-transport-05.txt [SSH-CONNECT] Ylonen, T., et al, "SSH Connection Protocol", Internet T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 10] INTERNET-DRAFT 6 August 1998 Draft, draft-secsh-connect-05.txt 9. Author's Address Tatu Ylonen SSH Communications Security Ltd. Tekniikantie 12 FIN-02150 ESPOO Finland E-mail: ylo@ssh.fi Tero Kivinen SSH Communications Security Ltd. Tekniikantie 12 FIN-02150 ESPOO Finland E-mail: kivinen@ssh.fi Markku-Juhani O. Saarinen SSH Communications Security Ltd. Tekniikantie 12 FIN-02150 ESPOO Finland E-mail: mjos@ssh.fi Timo J. Rinne SSH Communications Security Ltd. Tekniikantie 12 FIN-02150 ESPOO Finland E-mail: tri@ssh.fi Sami Lehtinen SSH Communications Security Ltd. Tekniikantie 12 FIN-02150 ESPOO Finland E-mail: sjl@ssh.fi T. Ylonen, T. Kivinen, M. Saarinen, T. Rinne and S. Lehtinen [page 11]