draft-ietf-secsh-userauth-01.txt   draft-ietf-secsh-userauth-02.txt 
Network Working Group Tatu Ylonen <ylo@ssh.fi> Network Working Group T. Ylonen
INTERNET-DRAFT SSH Communications Security INTERNET-DRAFT T. Kivinen
draft-ietf-secsh-userauth-02.txt M. Saarinen
Expires in six months Expires in six months SSH
14 October 1997
SSH Authentication Protocol SSH Authentication Protocol
Status of This memo Status of This memo
This document is an Internet-Draft. Internet-Drafts are working This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts. working documents as Internet-Drafts.
skipping to change at page 1, line 29 skipping to change at page 1, line 30
material or to cite them other than as ``work in progress.'' material or to cite them other than as ``work in progress.''
To learn the current status of any Internet-Draft, please check To learn the current status of any Internet-Draft, please check
the ``1id-abstracts.txt'' listing contained in the Internet-Drafts the ``1id-abstracts.txt'' listing contained in the Internet-Drafts
Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast),
or ftp.isi.edu (US West Coast). or ftp.isi.edu (US West Coast).
Abstract Abstract
This documents describes the SSH authentication protocol. It is used to SSH is a protocol for secure remote login and other secure network ser-
prove that the client is authorized to access the requested service with vices over an insecure network.
the supplied user name. This authorization can be demonstrated through
possession of a password, through possession of a key, by authenticating This document describes the SSH authentication protocol framework and
the client host and user, by some other method, or a combination of public key, password, and host-based client authentication methods.
these. 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.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. User Authentication . . . . . . . . . . . . . . . . . . . . . . 2 2. The Authentication Protocol Framework . . . . . . . . . . . . . 2
2.1. Authentication Requests . . . . . . . . . . . . . . . . . . 3 2.1. Authentication Requests . . . . . . . . . . . . . . . . . . 3
2.2. Responses to Authentication Requests . . . . . . . . . . . . 4 2.2. Responses to Authentication Requests . . . . . . . . . . . . 3
2.3. No Authentication . . . . . . . . . . . . . . . . . . . . . 5 2.3. The none Authentication Request . . . . . . . . . . . . . . 4
2.4. Password Authentication . . . . . . . . . . . . . . . . . . 5 2.4. Completion of User Authentication . . . . . . . . . . . . . 5
2.5. Challenge-Response Authentication . . . . . . . . . . . . . 6 2.5. Banner Message . . . . . . . . . . . . . . . . . . . . . . . 5
2.6. SecurID Authentication . . . . . . . . . . . . . . . . . . . 6 3. Authentication Protocol Message Numbers . . . . . . . . . . . . 5
2.7. Public Key Authentication . . . . . . . . . . . . . . . . . 7 4. Public Key Authentication Method: publickey . . . . . . . . . . 6
2.8. Host-Based Authentication . . . . . . . . . . . . . . . . . 9 5. Password Authentication Method: password . . . . . . . . . . . . 7
2.9. Kerberos Authentication . . . . . . . . . . . . . . . . . . 10 6. Host-Based Authentication: hostbased . . . . . . . . . . . . . . 9
2.10. When Authentication Is Complete . . . . . . . . . . . . . . 11 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 10
3. Banner Message . . . . . . . . . . . . . . . . . . . . . . . . . 11 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4. Message Numbers . . . . . . . . . . . . . . . . . . . . . . . . 11 9. Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10
5. Security Considerations . . . . . . . . . . . . . . . . . . . . 12
6. Address of Author . . . . . . . . . . . . . . . . . . . . . . . 12
1. Introduction 1. Introduction
This protocol is designed to run over the SSH transport layer protocol The SSH authentication protocol is a general-purpose user authentication
using the same packet-based protocol as the transport layer. The protocol. It is intended to be run over the SSH transport layer
service name is "ssh-userauth". protocol [SSH-TRANS]. This protocol assumes that the underlying
protocols provide integrity and confidentiality protection.
This document should be read only after reading the transport layer This document should be read only after reading the SSH architecture
document. This document uses terminology and notation from the document [SSH-ARCH]. This document freely uses terminology and notation
transport layer document without further explanation. from the architecture document without reference or further explanation.
Authentication works as follows: the client declares the service name, The service name for this protocol is "ssh-userauth".
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 When this protocol starts, it receives the session identifier from the
session identifier from the transport layer protocol. The session lower-level protocol. The session identifier uniquely identifies this
identifier uniquely identifies this session and is suitable for signing session and is suitable for signing to prove ownership of a private key.
to prove ownership of a private key. This protocol also needs to know whether the lower-level protocol
provides confidentiality protection.
2. User Authentication 2. The Authentication Protocol Framework
The server drives the authentication by telling the client which The server drives the authentication by telling the client which
authentications can usefully continue the dialog at any given time. The 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 client has the freedom to try the methods listed by the server in any
order. This gives the server complete control ver the authentication order. This gives the server complete control over the authentication
process if it so desired, but also gives enough flexibility for the 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 client to use the methods it supports or that are most convenient for
the user when multiple methods are offered by the server. the user when multiple methods are offered by the server.
Authentication methods are identified by names. Some methods are Authentication methods are identified by names, as defined in [SSH-
defined in the protocol; additional methods may be defined using the ARCH]. The "none" method is reserved, and MUST NOT be listed as
syntax "name@domainname" as the method name (for example, supported. However, it MAY be sent by the client. The server MUST
"footoken@footoken.com"). This ensures that private extensions can be always reject this request, unless the client is to be allowed in
implemented without breaking compatibility and without requiring a without any authentication, in which case the server MUST accept this
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. request. The main purpose of sending this request is to get the list of
The motivation for this is that which methods to use is a matter of supported methods from the server.
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 server SHOULD have a timeout for authentication, and disconnect if
the authentication has not been accepted within the timeout period. The the authentication has not been accepted within the timeout period. The
recommended timeout period is 10 minutes. Additionally, the RECOMMENDED timeout period is 10 minutes. Additionally, the
implementation may want to limit the number of failed authentication implementation SHOULD limit the number of failed authentication attempts
attempts a client may perform in a single session (the recommended limit a client may perform in a single session (the RECOMMENDED limit is 20
is 20 attempts). If the threshold is exceeded, the server should attempts). If the threshold is exceeded, the server SHOULD disconnect.
disconnect.
2.1. Authentication Requests 2.1. Authentication Requests
All authentication requests use the same generic message format. Only All authentication requests MUST use the following message format. Only
the first few fields are defined; the remaining fields depend on the the first few fields are defined; the remaining fields depend on the
authentication method. authentication method.
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string username string user name (in ISO-10646 UTF-8 encoding)
string service string service name (in US-ASCII)
string method name string method name (US-ASCII)
rest of the packet is method-specific rest of the packet is method-specific
The username and service are repeated in every new authentication The username and service are repeated in every new authentication
attempt, and may change. The server implementation must carefully check attempt, and MAY change. The server implementation MUST carefully check
them in every message, and must flush any accumulated authentication them in every message, and MUST flush any accumulated authentication
state if they change. state if they change. If it is unable to flush some authentication
state, it MUST disconnect if the user or service name changes.
Service specifies the service to start after authentication. There may The service name specifies the service to start after authentication.
be several different authenticated services provided. If the requested There may be several different authenticated services provided. If the
service is not available, the server may disconnect immediately or any requested service is not available, the server MAY disconnect
time later. Sending a proper disconnect message is recommended. 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 is allowed to If the requested user does not exist, the server MAY disconnect, or MAY
disconnect, or may send a bogus list of acceptable authentications but send a bogus list of acceptable authentications but never accept any.
never accept any. This makes it possible for the server to avoid This makes it possible for the server to avoid disclosing information
disclosing information about which accounts exist. 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 in clients sending requests that the While there is usually little point for clients to send requests that
server does not list as acceptable, sending such requests is not an 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 error, and the server SHOULD simply reject requests that it does not
recognize. recognize.
An authentication request may result in a further exchange of messages. An authentication request MAY result in a further exchange of messages.
All such messages depend on the authentication method used, and the All such messages depend on the authentication method used, and the
client may at any time continue with a new SSH_MSG_USERAUTH_REQUEST client MAY at any time continue with a new SSH_MSG_USERAUTH_REQUEST
message, in which case the server must abandon the previous message, in which case the server MUST abandon the previous
authentication attempt and continue with the new one. authentication attempt and continue with the new one.
2.2. Responses to Authentication Requests 2.2. Responses to Authentication Requests
If the server rejects the authentication request, it responds with If the server rejects the authentication request, it MUST respond with
byte SSH_MSG_USERAUTH_FAILURE byte SSH_MSG_USERAUTH_FAILURE
string authentications that can continue string authentications that can continue
boolean partial success boolean partial success
"Authentications that can continue" is a comma-separated list of "Authentications that can continue" is a comma-separated list of
authentication method names that may productively continue the authentication method names that may productively continue the
authentication dialog. authentication dialog.
It is recommended that servers only include those methods in the list 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 are actually useful. However, it is not illegal to include methods
that cannot be used to authenticate the user. that cannot be used to authenticate the user.
Already successfully completed authentications should not be included in Already successfully completed authentications SHOULD NOT be included in
the list unless they really should be performed again for some weird the list, unless they really should be performed again for some reason.
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
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 "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.
A client may request the list of real authentication methods that may When the server accepts authentication, it MUST respond with
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. byte SSH_MSG_USERAUTH_SUCCESS
2.4. Password Authentication Note that this is not sent after each step in a multi-method authentica-
tion sequence, but only when authentication is complete.
Password authentication uses the following packets. Note that a server The client MAY send several authentication requests without waiting for
may request the user to change password. 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.
byte SSH_MSG_USERAUTH_REQUEST Any non-authentication messages sent by the client after the request
string username that resulted in SSH_MSG_USERAUTH_SUCCESS being sent MUST be passed to
string service the service being run on top of this protocol. Such messages can be
string "password" identified by their message numbers (see Section ``Message Numbers'').
boolean FALSE
string plaintext password
byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 2.3. The none Authentication Request
string prompt
byte SSH_MSG_USERAUTH_REQUEST A client may request a list of authentication methods that may continue
string username by using the "none" authentication method.
string service
string "password"
boolean TRUE
string plaintext old password
string plaintext new password
byte SSH_MSG_USERAUTH_PASSWD_CHANGEREPLY If no authentication at all is needed for the user, the server MUST
boolean password changed 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.
Normally, the client sends the first form, and the server responds with This method MUST NOT be listed as supported by the server.
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
second form to change the password. The server will then reply with 2.4. Completion of User Authentication
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 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.
Most challenge-response authentication methods use the following message After sending SSH_MSG_USERAUTH_SUCCESS, the server starts the requested
exchange: service.
byte SSH_MSG_USERAUTH_REQUEST 2.5. Banner Message
string username
string service
string method name
boolean FALSE
The server responds with either SSH_MSG_USERAUTH_FAILURE or 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.
byte SSH_MSG_USERAUTH_CHALLENGE The SSH server may send a SSH_MSG_USERAUTH_BANNER message at any time
string prompt before authentication is successful. This message contains text to be
displayed to the client user before authentication is attempted. The
format is as follows.
The client then responds with either a new authentication request or byte SSH_MSG_USERAUTH_BANNER
string message (ISO-10646 UTF-8)
string language tag (as defined in RFC 1766)
byte SSH_MSG_USERAUTH_REQUEST The client SHOULD by default display the message on the screen.
string username However, since the message is likely to be sent for every login attempt,
string service and since some client software will need to open a separate window for
string method name this warning, the client software may allow the user to explicitly
boolean TRUE disable the display of banners from the server. The message may consist
string response of multiple lines.
The server responds to this message with either success or failure. If the message string is displayed, control character filtering
discussed in [SSH-ARCH] SHOULD be used to avoid attacks by sending
terminal control characters.
The "otp-md4", "otp-md5" and "otp-sha1" methods are defined in RFC 1938, 3. Authentication Protocol Message Numbers
and follow this pattern.
2.6. SecurID Authentication 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.
SecurID is a timing-based hardware token authenticator. The user enters Message numbers 80 and higher are reserved for protocols running after
a code displayed on the token as authentication. There are different this authentication protocol, so receiving one of them before
versions of the SecurID tokens. Some versions support changing the PIN authentication is complete is an error, to which the server MUST respond
(either to a server-supplied or user-supplied pin), and some might even by disconnecting (preferably with a proper disconnect message sent first
allow textual passphrases. to ease troubleshooting).
The method name for SecurID authentication is "securid". The following After successful authentication, such messages are passed to the higher-
packets are used: level service.
byte SSH_MSG_USERAUTH_REQUEST These are the general authentication message codes:
string username
string service
string "securid"
boolean is_new_pin
string pin
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 #define SSH_MSG_USERAUTH_REQUEST 50
boolean pin accepted #define SSH_MSG_USERAUTH_FAILURE 51
#define SSH_MSG_USERAUTH_SUCCESS 52
#define SSH_MSG_USERAUTH_BANNER 53
Authentication starts by the client sending the SSH_MSG_USERAUTH_REQUEST In addition to the above, there is a range of message numbers (25..29)
message with "is_new_pin" FALSE. The server responds with reserved for method-specific messages. These messages are only sent by
SSH_MSG_USERAUTH_SUCCESS, SSH_MSG_USERAUTH_FAILURE, or with the server (client only sends SSH_MSG_USERAUTH_REQUEST messages).
SSH_MSG_USERAUTH_SECURID_PINREQ if it wants the user to change his/her Different authentication methods reuse the same message numbers.
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 4. Public Key Authentication Method: publickey
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 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.
The possession of a private key can serve as authentication. This With this method, the possession of a private key serves as
method works by sending a signature created with the private key of the authentication. This method works by sending a signature created with a
user, which the server checks with the client user's public key. 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 Private keys are often stored encrypted at the client host, and the user
must supply a passphrase before the signature can be generated. To must supply a passphrase before the signature can be generated. Even if
avoid needing to supply passphrases when it is not necessary, the client they are not, the signing operation involves some expensive computation.
can optionally verify whether a particular key would be acceptable as To avoid unnecessary processing and user interaction, the following
authentication. This is done with the following message. message is provided for querying whether authentication using the key
would be acceptable.
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string username string username
string service string service
string "publickey" string "publickey"
boolean FALSE boolean FALSE
string public key algorithm name string public key algorithm name
string public key to be used for authentication string public key blob
Public key algorithms are defined in the transport layer specification. Public key algorithms are defined in the transport layer specification
The "public key to be used for authentication" may include certificates. [SSH-TRANS]. The public key blob may contain certificates.
The server will respond to this message with either 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 SSH_MSG_USERAUTH_FAILURE or with
byte SSH_MSG_USERAUTH_PK_OK byte SSH_MSG_USERAUTH_PK_OK
string public key algorithm name from the request string public key algorithm name from the request
string public key from the request string public key blob from the request
To do actual authentication, the client should then send a signature To do actual authentication, the client MAY then send a signature
generated using the private key. It is permissible to send the generated using the private key. Client MAY send the signature directly
signature directly without first verifying whether the key is without first verifying whether the key is acceptable. The signature is
acceptable. sent using the following packet
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string username string username
string service string service
string "publickey" string "publickey"
boolean TRUE boolean TRUE
string public key algorithm name string public key algorithm name
string public key to be used for authentication string public key to be used for authentication
string signature string signature
Signature is a signature by the corresponding private key of the HASH Signature is a signature by the corresponding private key over the
of the concatenation of the following, in this order: following data, in this order:
o session identifier (which binds the signature to the server host key o session identifier, and
and the particular key exchange),
o length of the user name as a 32-bit integer, msb first, o packet payload without the signature.
o user name (without length or null characters), 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.
o length of the service name as a 32-bit integer, msb first, 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).
o service name (without length or null characters), The following method-specific message numbers are used by the publickey
authentication method.
o length of the public key algorithm name as a 32-bit integer, msb /* Key-based */
first, #define SSH_MSG_USERAUTH_PK_OK 60
o public key algorithm name (without length or null characters), 5. Password Authentication Method: password
o length of the public key from the message as a 32-bit integer, msb Password authentication uses the following packets. Note that a server
first, and MAY request the user to change password. All implementations SHOULD
support password authentication.
o public key from the message (without length or null characters). byte SSH_MSG_USERAUTH_REQUEST
string user name
string service
string "password"
boolean FALSE
string plaintext password (ISO-10646 UTF-8)
When the server receives this message, it checks whether the supplied Note that the password is encoded in ISO-10646 UTF-8. It is up to the
key is acceptable for authentication, and if so, checks whether the server how it interprets the password and validates it against the
signature is correct. 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.
If both checks succeed, authentication may be granted (the server may Note that even though the cleartext password is transmitted in the
also require further authentication with other methods, without letting packet, the entire packet is encrypted by the transport layer. Both the
the client know at this point that authentication has partially server and the client should check whether the underlying transport
succeeded). 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.
2.8. Host-Based Authentication 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.
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 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 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 authentication is not suitable for high-security sites, it can be very
convenient in many environments. The client requests this form of convenient in many environments. This form of authentication is
authentication by sending the following message. It is rather similar OPTIONAL. When used, special care SHOULD be taken to prevent a regular
to the Unix "rhosts" and "hosts.equiv" styles of authentication, except user from obtaining the private host key.
that the identity of the client host is checked more rigorously. 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 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 private key of the client host, which the server checks with that host's
public key. Once the client host's identity is established, public key. Once the client host's identity is established,
authorization, but no further authentication, is performed based on the authorization, but no further authentication, is performed based on the
usernames on the server and client, and the client host name. usernames on the server and client, and the client host name.
byte SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string username string username
string service string service
string "hostbased" string "hostbased"
string public key algorithm for host key string public key algorithm for host key
string public host key for client host string public host key and certificates for client host
string client host name string client host name (FQDN; US-ASCII)
string client user name string client user name on the remote host (ISO-10646 UTF-8)
string signature string signature
Public key algorithm names for use in "public key algorithm for host Public key algorithm names for use in "public key algorithm for host
key" are defined in the transport layer specification. The "public host key" are defined in the transport layer specification. The "public host
key for client host" may include certificates. 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 Signature is a signature with the private host key of the following
first, data, in this order:
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),
o length of the client host name as a 32-bit integer, msb first,
o client host name (without length or null characters), o session identifier, and
o length of the client user name as a 32-bit integer, msb first, and o packet payload without the signature.
o client user name (without length or null characters). 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
Authentication is accepted if the server can verify that the host key client user name, if it wants to authenticate only the client host.
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 It is RECOMMENDED that whenever possible, the server perform additional
checks to verify that the network address obtained from the (untrusted) checks to verify that the network address obtained from the (untrusted)
network matches the given client host name. This makes exploiting network matches the given client host name. This makes exploiting
compromised host keys more difficult. Note that this may require compromised host keys more difficult. Note that this may require
special handling for connections coming through a firewall. special handling for connections coming through a firewall.
2.9. Kerberos Authentication 7. Security Considerations
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
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 The purpose of this protocol is to perform client user authentication.
this authentication protocol, so receiving one of them before It assumed that this runs over a secure transport layer protocol, which
authentication is complete is an error, to which the server must respond has already authenticated the server machine, established an encrypted
by disconnecting (preferably with a proper disconnect sent first to ease communications channel, and computed a unique session identifier for
troubleshooting). this session. The transport layer provides forward secrecy for password
authentication and other methods that rely on secret data.
After successful authentication, such messages are passed to the higher- If the transport layer does not provide encryption, authentication
level service. 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).
These are the general authentication message codes: 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.
#define SSH_MSG_USERAUTH_REQUEST 20 Special care should be taken when designing debug messages. These
#define SSH_MSG_USERAUTH_FAILURE 21 messages may reveal surprising amounts of information about the host if
#define SSH_MSG_USERAUTH_SUCCESS 22 not properly designed. Debug messages can be disabled (during user
authentication phase) if high security is sought after.
#define SSH_MSG_USERAUTH_BANNER 23 8. References
In addition to the above, there is a range of message numbers (25..29) [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages",
reserved for method-specific messages. These messages are only sent by March 1995.
the server (client only sends SSH_MSG_USERAUTH_REQUEST messages).
Differnet authentication methods reuse the same message numbers.
/* Password */ [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and
#define SSH_MSG_USERAUTH_PASSWD_CHANGEREQ 25 ISO 10646", October 1996.
#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 [SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol
Architecture", Internet Draft, draft-secsh-architecture-00.txt
The purpose of this protocol is to perform client user authentication. [SSH-TRANS] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Transport
It assumed that this runs over a secure transport layer protocol, which Layer Protocol", Internet Draft, draft-secsh-transport-02.txt
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 [SSH-CONNECT] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Connection
are allowed. It is up to the server's local policy to decide which Protocol", Internet Draft, draft-secsh-connect-02.txt
methods (or combinations of methods) it is willing to accept for each
user.
6. Address of Author 9. Author's Address
Tatu Ylonen Tatu Ylonen
SSH Communications Security Ltd. SSH Communications Security Ltd.
Tekniikantie 12 Tekniikantie 12
FIN-02150 ESPOO FIN-02150 ESPOO
Finland Finland
E-mail: ylo@ssh.fi 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
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/