HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 07:42:22 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Thu, 31 Jul 1997 16:31:00 GMT ETag: "3050cc-6a2c-33e0bdc4" Accept-Ranges: bytes Content-Length: 27180 Connection: close Content-Type: text/plain Network Working Group Tatu Ylonen INTERNET-DRAFT SSH Communications Security draft-ietf-secsh-userauth-01.txt July 30, 1997 Expires in six months SSH Authentication Protocol Status of This memo This document is an Internet-Draft. 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.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Abstract This documents describes the SSH authentication protocol. It is used to prove that the client is authorized to access the requested service with the supplied user name. This authorization can be demonstrated through possession of a password, through possession of a key, by authenticating the client host and user, by some other method, or a combination of these. Tatu Ylonen [page 1] INTERNET-DRAFT July 30, 1997 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. User Authentication . . . . . . . . . . . . . . . . . . . . . . 2 2.1. Authentication Requests . . . . . . . . . . . . . . . . . . 3 2.2. Responses to Authentication Requests . . . . . . . . . . . . 4 2.3. No Authentication . . . . . . . . . . . . . . . . . . . . . 5 2.4. Password Authentication . . . . . . . . . . . . . . . . . . 5 2.5. Challenge-Response Authentication . . . . . . . . . . . . . 6 2.6. SecurID Authentication . . . . . . . . . . . . . . . . . . . 6 2.7. Public Key Authentication . . . . . . . . . . . . . . . . . 7 2.8. Host-Based Authentication . . . . . . . . . . . . . . . . . 9 2.9. Kerberos Authentication . . . . . . . . . . . . . . . . . . 10 2.10. When Authentication Is Complete . . . . . . . . . . . . . . 11 3. Banner Message . . . . . . . . . . . . . . . . . . . . . . . . . 11 4. Message Numbers . . . . . . . . . . . . . . . . . . . . . . . . 11 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 12 6. Address of Author . . . . . . . . . . . . . . . . . . . . . . . 12 1. Introduction This protocol is designed to run over the SSH transport layer protocol using the same packet-based protocol as the transport layer. The service name is "ssh-userauth". This document should be read only after reading the transport layer document. This document uses terminology and notation from the transport layer document without further explanation. Authentication works as follows: the client declares the service name, and the user name under which to access this service. The server responds to this declaration with a set of acceptable authentication methods for the given user/service combination. The client then sends an authentication request using one of the methods listed by the server. This dialog continues until access has been granted, or until either the client or the server disconnects. When the authentication protocols protocol starts, it receives the session identifier from the transport layer protocol. The session identifier uniquely identifies this session and is suitable for signing to prove ownership of a private key. 2. User Authentication 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 ver 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. Tatu Ylonen [page 2] INTERNET-DRAFT July 30, 1997 Authentication methods are identified by names. Some methods are defined in the protocol; additional methods may be defined using the syntax "name@domainname" as the method name (for example, "footoken@footoken.com"). This ensures that private extensions can be implemented without breaking compatibility and without requiring a central registry of method names. Method names are case-sensitive, and must consist of alphanumeric characters and hyphens. The following methods are predefined: none Unsupported authentication method password Password-based authentication securid SecurID authentication otp-md4 One-time passwords using MD4 hashing otp-md5 One-time passwords using MD5 hashing otp-sha1 One-time passwords using SHA1 hashing publickey Possession of private key hostbased Client host and user (.rhosts-style) kerberos4 Kerberos v4 authentication kerberos5 Kerberos v5 authentication kerberos-afs AFS Kerberos authentication The "none" method should never be listed as supported. However, it may be sent by the client. The server should always reject this request, unless the client is to be allowed in without any authentication. The main purpose of sending this request is to get the list of supported methods from the server. There are no mandatory authentication methods; all methods are optional. The motivation for this is that which methods to use is a matter of local policy rather than protocol. However, it is strongly recommended that all implementations support at least "password" authentication. 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 may want to 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 use the same generic message format. Only the first few fields are defined; the remaining fields depend on the authentication method. byte SSH_MSG_USERAUTH_REQUEST string username string service string method name rest of the packet is method-specific Tatu Ylonen [page 3] INTERNET-DRAFT July 30, 1997 The username 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. Service 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. If the requested user does not exist, the server is allowed to 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. While there is usually little point in clients sending 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. 2.2. Responses to Authentication Requests If the server rejects the authentication request, it responds 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 weird reason. "Partial success" is TRUE if the particular authentication request, in response to which this is being sent, was accepted, but more authentication is still needed. It is FALSE if the request was not successfully processed. When the server accepts authentication, it responds with Tatu Ylonen [page 4] INTERNET-DRAFT July 30, 1997 byte SSH_MSG_USERAUTH_SUCCESS The client may send several authentication requests without waiting for responses from previous requests. The server will acknowledge any failed requests with a SSH_SMSG_AUTH_FAILURE message. However, SSH_SMSG_AUTH_SUCCESS is sent only once. Once SSH_MSG_USERAUTH_SUCCESS has been sent, any further authentication requests received after that are silently ignored, while any non- authentication messages sent by the client will be passed to the service being run above this authentication protocol. 2.3. No Authentication A client may request the list of real authentication methods that may continue by using the "none" authentication method. This is actually an authentication request: if no authentication at all is needed for the user, this returns SSH_MSG_USERAUTH_SUCCESS. Otherwise, this returns failure and with it the list of authentication methods that can continue. This method should never be listed as supported by the server. 2.4. Password Authentication Password authentication uses the following packets. Note that a server may request the user to change password. byte SSH_MSG_USERAUTH_REQUEST string username string service string "password" boolean FALSE string plaintext password byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ string prompt byte SSH_MSG_USERAUTH_REQUEST string username string service string "password" boolean TRUE string plaintext old password string plaintext new password byte SSH_MSG_USERAUTH_PASSWD_CHANGEREPLY boolean password changed Normally, the client sends the first form, and the server responds with success or failure. However, the server may also send a SSH_MSG_USERAUTH_PASSWD_CHANGEREQ. In this case, the client should request a new password from the user, and send a new request of the Tatu Ylonen [page 5] INTERNET-DRAFT July 30, 1997 second form to change the password. The server will then reply with SSH_MSG_USERAUTH_PASSWD_CHANGEREPLY. If "password changed" is true, the server will continue with either SSH_MSG_USERAUTH_SUCCESS or SSH_MSG_USERAUTH_FAILURE. Otherwise, the dialog continues and the client can try changing the password again. 2.5. Challenge-Response Authentication Most challenge-response authentication methods use the following message exchange: byte SSH_MSG_USERAUTH_REQUEST string username string service string method name boolean FALSE The server responds with either SSH_MSG_USERAUTH_FAILURE or byte SSH_MSG_USERAUTH_CHALLENGE string prompt The client then responds with either a new authentication request or byte SSH_MSG_USERAUTH_REQUEST string username string service string method name boolean TRUE string response The server responds to this message with either success or failure. The "otp-md4", "otp-md5" and "otp-sha1" methods are defined in RFC 1938, and follow this pattern. 2.6. SecurID Authentication SecurID is a timing-based hardware token authenticator. The user enters a code displayed on the token as authentication. There are different versions of the SecurID tokens. Some versions support changing the PIN (either to a server-supplied or user-supplied pin), and some might even allow textual passphrases. The method name for SecurID authentication is "securid". The following packets are used: byte SSH_MSG_USERAUTH_REQUEST string username string service string "securid" boolean is_new_pin string pin Tatu Ylonen [page 6] INTERNET-DRAFT July 30, 1997 byte SSH_MSG_USERAUTH_SECURID_PINREQ boolean user may supply string suggested pin uint32 min len uint32 max len boolean nondigits ok byte SSH_MSG_USERAUTH_SECURID_PINREPLY boolean pin accepted Authentication starts by the client sending the SSH_MSG_USERAUTH_REQUEST message with "is_new_pin" FALSE. The server responds with SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or with SSH_MSG_USERAUTH_SECURID_PINREQ if it wants the user to change his/her pincode. In this message, "user may supply" is TRUE if the user may choose the new pin, and FALSE if the server-supplied pin (in "suggested pin") must be used. "Suggested pin" is a new PIN suggested by the server, but may also be empty. "Min len" is the minimum length of the new pin, "max len" is the maximum length, and "nondigits ok" is TRUE if characters other than digits are allowed. To change the pin, the client continues with a new SSH_MSG_USERAUTH_REQUEST with "is_new_pin" TRUE and the new pin in "pin". The server responds to this message with SSH_MSG_USERAUTH_SECURID_PINREPLY (with "pin accepted" TRUE if the new pin is now in effect, FALSE otherwise), followed by either SSH_MSG_USERAUTH_SUCCESS or SSH_MSG_USERAUTH_FAILURE. Note that some versions of SecurID do not permit the user in if the pin was changed. 2.7. Public Key Authentication The possession of a private key can serve as authentication. This method works by sending a signature created with the private key of the user, which the server checks with the client user's public key. Private keys are often stored encrypted at the client host, and the user must supply a passphrase before the signature can be generated. To avoid needing to supply passphrases when it is not necessary, the client can optionally verify whether a particular key would be acceptable as authentication. This is done with the following message. byte SSH_MSG_USERAUTH_REQUEST string username string service string "publickey" boolean FALSE string public key algorithm name string public key to be used for authentication Public key algorithms are defined in the transport layer specification. The "public key to be used for authentication" may include certificates. The server will respond to this message with either Tatu Ylonen [page 7] INTERNET-DRAFT July 30, 1997 SSH_MSG_USERAUTH_FAILURE or with byte SSH_MSG_USERAUTH_PK_OK string public key algorithm name from the request string public key from the request To do actual authentication, the client should then send a signature generated using the private key. It is permissible to send the signature directly without first verifying whether the key is acceptable. byte SSH_MSG_USERAUTH_REQUEST string username 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 of the HASH of the concatenation of the following, in this order: o session identifier (which binds the signature to the server host key and the particular key exchange), o length of the user name as a 32-bit integer, msb first, o user name (without length or null characters), o length of the service name as a 32-bit integer, msb first, o service name (without length or null characters), o length of the public key algorithm name as a 32-bit integer, msb first, o public key algorithm name (without length or null characters), o length of the public key from the message as a 32-bit integer, msb first, and o public key from the message (without length or null characters). When the server receives this message, it checks whether the supplied key is acceptable for authentication, and if so, checks whether the signature is correct. If both checks succeed, authentication may be granted (the server may also require further authentication with other methods, without letting the client know at this point that authentication has partially succeeded). Tatu Ylonen [page 8] INTERNET-DRAFT July 30, 1997 2.8. Host-Based Authentication 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. The client requests this form of authentication by sending the following message. It is rather 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 usernames on the server and client, and the client host name. byte SSH_MSG_USERAUTH_REQUEST string username string service string "hostbased" string public key algorithm for host key string public host key for client host string client host name string client user name 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 for the client host of the HASH (where the hash algorithm is from the transport layer) of the concatenation of the following, in this order: o session identifier (which binds the signature to the server host key and the particular key exchange), o length of the user name as a 32-bit integer, msb first, o user name (without length or null characters), o length of the service name as a 32-bit integer, msb first, o service name (without length or null characters), o length of the public host key algorithm name as a 32-bit integer, msb first, o public host key algorithm name (without length or null characters), o length of the public host key from the message as a 32-bit integer, msb first, o public host key from the message (without length or null characters), Tatu Ylonen [page 9] INTERNET-DRAFT July 30, 1997 o length of the client host name as a 32-bit integer, msb first, o client host name (without length or null characters), o length of the client user name as a 32-bit integer, msb first, and o client user name (without length or null characters). Authentication is accepted if the server can verify that the host key actually belongs to the client host named in the message, the given user on that host is allowed to log in, and the signature is a valid signature on the appropriate value by the given host key. (The server is also allowed to ignore the 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. 2.9. Kerberos Authentication There are several ways to authenticate the user using Kerberos (OSF DCE and AFS are also incarnations of Kerberos). Different versions of Kerberos (v4, v5, DCE, and AFS) have different capabilities. Separate messages have been defined for each of these. In each case, the server should respond with success or failure. byte SSH_MSG_USERAUTH_REQUEST string username string service string "kerberos4" string kerberos v4 credentials byte SSH_MSG_USERAUTH_REQUEST string username string service string "kerberos5" string kerberos v5 credentials string kerberos v5 ticket granting ticket (may be empty) byte SSH_MSG_USERAUTH_REQUEST string username string service string "kerberos-afs" string AFS token The Kerberos authentication requests should be sent before other authentication requests. The other authentication methods may need to access files from the user's home directory, which may not be accessible until e.g. the AFS token has been passed. Note that even if these requests fail, they may have side effects, such as making the home Tatu Ylonen [page 10] INTERNET-DRAFT July 30, 1997 directory accessible. 2.10. When Authentication Is Complete Authentication is complete when the server has responded with SSH_MSG_USERAUTH_SUCCESS; any SSH_MSG_USERAUTH_REQUEST messages received after sending this message are silently ignored. When sending SSH_MSG_USERAUTH_SUCCESS, the server also starts whatever application was requested as the service. Any non-authentication messages received after this point are passed to the requested service. 3. Banner Message In some jurisdictions, sending a warning message before authentication may be relevant to getting legal protection. Many Unix machines, for example, 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 form is as follows, where "message" may contain newlines: byte SSH_MSG_USERAUTH_BANNER string message 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. 4. Message Numbers All message numbers used by this authentication protocol are in the range 20..29, which is part of the range reserved for protocols running on top of the SSH transport layer protocol. Message numbers 30 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 sent first to ease troubleshooting). After successful authentication, such messages are passed to the higher- level service. These are the general authentication message codes: #define SSH_MSG_USERAUTH_REQUEST 20 #define SSH_MSG_USERAUTH_FAILURE 21 #define SSH_MSG_USERAUTH_SUCCESS 22 Tatu Ylonen [page 11] INTERNET-DRAFT July 30, 1997 #define SSH_MSG_USERAUTH_BANNER 23 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). Differnet authentication methods reuse the same message numbers. /* Password */ #define SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 25 #define SSH_MSG_USERAUTH_PASSWD_CHANGEREPLY 26 /* Key-based */ #define SSH_MSG_USERAUTH_PK_OK 25 /* One-time passwords */ #define SSH_MSG_USERAUTH_CHALLENGE 25 /* SecurID */ #define SSH_MSG_USERAUTH_SECURID_PINREQ 25 #define SSH_MSG_USERAUTH_SECURID_PINREPLY 26 5. 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. 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. 6. Address of Author Tatu Ylonen SSH Communications Security Ltd. Tekniikantie 12 FIN-02150 ESPOO Finland E-mail: ylo@ssh.fi Tatu Ylonen [page 12]