draft-ietf-secsh-userauth-00.txt   draft-ietf-secsh-userauth-01.txt 
Network Working Group Tatu Ylonen <ylo@ssh.fi> Network Working Group Tatu Ylonen <ylo@ssh.fi>
INTERNET-DRAFT SSH Communications Security INTERNET-DRAFT SSH Communications Security
Expires: September 1, 1997 Expires in six months
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 31 skipping to change at page 1, line 30
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 This documents describes the SSH authentication protocol. It is used to
prove that the client is authorized access the requested service with prove that the client is authorized to access the requested service with
the supplied user name. This authorization can be demonstrated through the supplied user name. This authorization can be demonstrated through
possession of a password, through possession of a key, by authenticating possession of a password, through possession of a key, by authenticating
the client host and user, by some other method, or a combination of the client host and user, by some other method, or a combination of
these. these.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. User Authentication . . . . . . . . . . . . . . . . . . . . . . 2 2. User Authentication . . . . . . . . . . . . . . . . . . . . . . 2
2.1. Authentication Requests . . . . . . . . . . . . . . . . . . 3 2.1. Authentication Requests . . . . . . . . . . . . . . . . . . 3
2.2. Responses to Authentication Requests . . . . . . . . . . . . 4 2.2. Responses to Authentication Requests . . . . . . . . . . . . 4
2.3. No Authentication . . . . . . . . . . . . . . . . . . . . . 4 2.3. No Authentication . . . . . . . . . . . . . . . . . . . . . 5
2.4. Password-Style Authentications . . . . . . . . . . . . . . . 5 2.4. Password Authentication . . . . . . . . . . . . . . . . . . 5
2.4.1. Password Authentication . . . . . . . . . . . . . . . . 5 2.5. Challenge-Response Authentication . . . . . . . . . . . . . 6
2.4.2. SecurID Authentication . . . . . . . . . . . . . . . . . 5 2.6. SecurID Authentication . . . . . . . . . . . . . . . . . . . 6
2.5. One-Time Passwords and Similar Methods . . . . . . . . . . . 5 2.7. Public Key Authentication . . . . . . . . . . . . . . . . . 7
2.5.1. S/KEY . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.8. Host-Based Authentication . . . . . . . . . . . . . . . . . 9
2.5.2. NRL OPIE . . . . . . . . . . . . . . . . . . . . . . . . 6 2.9. Kerberos Authentication . . . . . . . . . . . . . . . . . . 10
2.6. Other Authentication Methods . . . . . . . . . . . . . . . . 6 2.10. When Authentication Is Complete . . . . . . . . . . . . . . 11
2.6.1. Public Key Authentication . . . . . . . . . . . . . . . 6 3. Banner Message . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.6.2. Host-Based Authentication . . . . . . . . . . . . . . . 7 4. Message Numbers . . . . . . . . . . . . . . . . . . . . . . . . 11
2.6.3. Kerberos Authentication . . . . . . . . . . . . . . . . 8 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 12
3. When Authentication Is Complete . . . . . . . . . . . . . . . . 9 6. Address of Author . . . . . . . . . . . . . . . . . . . . . . . 12
4. Banner Message . . . . . . . . . . . . . . . . . . . . . . . . . 9
5. Message Numbers . . . . . . . . . . . . . . . . . . . . . . . . 10
6. Address of Author . . . . . . . . . . . . . . . . . . . . . . . 10
1. Introduction 1. Introduction
This protocol is designed to run over the SSH transport layer protocol This protocol is designed to run over the SSH transport layer protocol
using the same packet-based protocol as the transport layer. The using the same packet-based protocol as the transport layer. The
service name is "ssh-userauth". service name is "ssh-userauth".
Authentication works by the client first declaring the service name and This document should be read only after reading the transport layer
the user name to be used to access the service. The server then document. This document uses terminology and notation from the
responds with the set of authentication methods that are acceptable; the transport layer document without further explanation.
client then sends an authentication request, and this dialog continues
until access has been granted or denied.
When this protocol starts, it receives the session identifier from the Authentication works as follows: the client declares the service name,
transport layer protocol. The session identifier uniquely identifies and the user name under which to access this service. The server
this session and is suitable for signing to prove ownership of a private responds to this declaration with a set of acceptable authentication
key. 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 2. User Authentication
Authentication is mostly client-driven. The client sends an The server drives the authentication by telling the client which
authentication request, and the server responds with success or failure. authentications can usefully continue the dialog at any given time. The
With a failure response the server informs the client which methods may client has the freedom to try the methods listed by the server in any
be used to continue the dialog, thus guiding the client through a order. This gives the server complete control ver the authentication
potentially complex sequence of authentications. 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 (strings). Some methods Authentication methods are identified by names. Some methods are
are defined in the protocol; additional methods may be defined using the defined in the protocol; additional methods may be defined using the
syntax "name@domainname" as the method name (for example, syntax "name@domainname" as the method name (for example,
"footoken@footoken.com"). This ensures that private extensions can be "footoken@footoken.com"). This ensures that private extensions can be
implemented without breaking compatibility and without requiring a implemented without breaking compatibility and without requiring a
central registry of method names. Method names are case-sensitive. central registry of method names. Method names are case-sensitive, and
Names must consist of non-control characters. Commas are not allowed in must consist of alphanumeric characters and hyphens.
names; at signs can only be used for the purpose described above.
The following methods are predefined: The following methods are predefined:
none Checks if no authentication ok none Unsupported authentication method
password Knowledge of password password Password-based authentication
securid SecurID authentication securid SecurID authentication
skey S/KEY one-time passwords otp-md4 One-time passwords using MD4 hashing
opie NRL OPIE one-time passwords otp-md5 One-time passwords using MD5 hashing
publickeytest Tests whether a key is acceptable otp-sha1 One-time passwords using SHA1 hashing
publickey Possession of private key publickey Possession of private key
hostbased Identity of client host and user hostbased Client host and user (.rhosts-style)
kerberos4 Kerberos v4 authentication kerberos4 Kerberos v4 authentication
kerberos5 Kerberos v5 authentication kerberos5 Kerberos v5 authentication
kerberos-afs AFS Kerberos 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 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 authentication attempts a implementation may want to limit the number of failed authentication
client may perform (the recommended limit is 20 attempts). 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 2.1. Authentication Requests
All authentication requests use the same generic message format. Only All authentication requests use the same generic 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.
vlint32 SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user string username
string service string service
string method name string method name
rest of the packet is method-specific rest of the packet is method-specific
The user name and service are repeated in every new authentication The user name 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 the requested service is not available, the server may disconnect Service specifies the service to start after authentication. There may
immediately or any time later. 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 If the requested user does not exist, the server is allowed to
disconnect, or may send a bogus list of acceptable authentications but disconnect, or may send a bogus list of acceptable authentications but
never accept any. This makes it possible for the server to avoid never accept any. This makes it possible for the server to avoid
disclosing information about which accounts exist. disclosing information about which accounts exist.
There are several authentication methods that basically work by the
client sending some kind of identifying string (or other data) to the
server, and the server directly responding with success or failure.
Examples of this style of authentication are "password" and "securid"
methods. Other such methods may be defined later.
Another common form is one where the server sends a prompt (a
challenge), and the client is supposed to respond appropriately based on
the challenge. Most one-time password methods use this form; examples
include "skey" and "opie".
While there is usually little point in clients sending requests that the While there is usually little point in clients sending requests that the
server does not list as acceptable, sending such requests is not an 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 responds with
vlint32 SSH_MSG_USERAUTH_FAILURE byte SSH_MSG_USERAUTH_FAILURE
string authentications_that_can_continue string authentications that can continue
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. Methods that require interaction with the user authentication dialog.
should not be listed unless they can actually be used to authenticate
this user. Note that successful response to one method in the list may
not be enough to be accepted; the server is allowed to require multiple
authentications. The server should not list authentications that it has
already accepted.
When the server accepts authentication, it responds with 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.
vlint32 SSH_MSG_USERAUTH_SUCCESS 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
byte SSH_MSG_USERAUTH_SUCCESS
The client may send several authentication requests without waiting for The client may send several authentication requests without waiting for
responses from previous requests. The server will acknowledge any responses from previous requests. The server will acknowledge any
failed requests with a SSH_SMSG_AUTH_FAILURE message. However, failed requests with a SSH_SMSG_AUTH_FAILURE message. However,
SSH_SMSG_AUTH_SUCCESS is sent only once, and any further authentication SSH_SMSG_AUTH_SUCCESS is sent only once.
requests received after that are silently ignored.
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.
Once SSH_MSG_USERAUTH_SUCCESS has been sent, any non-authentication
messages sent by the client will be passed to the service being run
above this authentication protocol.
2.3. No Authentication 2.3. No Authentication
A client may request the list of real authentication methods that may A client may request the list of real authentication methods that may
continue by using the "none" authentication method. This is actually an continue by using the "none" authentication method. This is actually an
authentication request: if no authentication at all is needed for the authentication request: if no authentication at all is needed for the
user, this returns SSH_MSG_USERAUTH_SUCCESS. Otherwise, this returns user, this returns SSH_MSG_USERAUTH_SUCCESS. Otherwise, this returns
failure and with it the list of authentication methods that can failure and with it the list of authentication methods that can
continue. continue.
2.4. Password-Style Authentications This method should never be listed as supported by the server.
All password-style authentication methods use a single message of the 2.4. Password Authentication
following format. The server responds with success or failure.
vlint32 SSH_MSG_USERAUTH_REQUEST Password authentication uses the following packets. Note that a server
string user may request the user to change password.
byte SSH_MSG_USERAUTH_REQUEST
string username
string service string service
string method name string "password"
string authenticating string boolean FALSE
string plaintext password
2.4.1. Password Authentication byte SSH_MSG_USERAUTH_PASSWD_CHANGEREQ
string prompt
This is conventional password authentication. The method name is byte SSH_MSG_USERAUTH_REQUEST
"password"; the authenticating string is the plaintext password. Note string username
that the password is sent as plaintext in the packet, but the entire string service
packet (including the password) is encrypted by the transport layer. It string "password"
is not possible for the client to hash the password, because it cannot boolean TRUE
know how the server stores the password. string plaintext old password
string plaintext new password
2.4.2. SecurID Authentication byte SSH_MSG_USERAUTH_PASSWD_CHANGEREPLY
boolean password changed
SecurID is a timing-based hardware token authenticator. The user enters Normally, the client sends the first form, and the server responds with
a code displayed on the token as authentication. The entered token is success or failure. However, the server may also send a
passed in the following message. 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
The method name for SecurID authentication is "securid"; the second form to change the password. The server will then reply with
authenticating string is the code displayed on the hardware token. 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. One-Time Passwords and Similar Methods 2.5. Challenge-Response Authentication
All one-time password authentication methods use the following message Most challenge-response authentication methods use the following message
exchange: exchange:
vlint32 SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user string username
string service string service
string method name string method name
boolean FALSE
The server responds with either SSH_MSG_USERAUTH_FAILURE or The server responds with either SSH_MSG_USERAUTH_FAILURE or
vlint32 SSH_MSG_USERAUTH_OTP_PROMPT byte SSH_MSG_USERAUTH_CHALLENGE
string prompt string prompt
The client then responds with either a new authentication request or The client then responds with either a new authentication request or
vlint32 SSH_MSG_USERAUTH_OTP_RESPONSE byte SSH_MSG_USERAUTH_REQUEST
string username
string service
string method name
boolean TRUE
string response string response
The server responds to this message with either success or failure. The server responds to this message with either success or failure.
2.5.1. S/KEY The "otp-md4", "otp-md5" and "otp-sha1" methods are defined in RFC 1938,
and follow this pattern.
S/KEY is an early one-time password mechanism. The method name is 2.6. SecurID Authentication
"skey".
2.5.2. NRL OPIE 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.
NRL OPIE is another one-time password mechanism. The method name for it The method name for SecurID authentication is "securid". The following
is "opie". packets are used:
2.6. Other Authentication Methods byte SSH_MSG_USERAUTH_REQUEST
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
2.6.1. Public Key Authentication 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 The possession of a private key can serve as authentication. This
method works by sending a signature created by the private key. 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 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. To
avoid needing to supply passphrases when it is not necessary, the client avoid needing to supply passphrases when it is not necessary, the client
can optionally query whether a particular key is acceptable as can optionally verify whether a particular key would be acceptable as
authentication. This done with the following message. The key may authentication. This is done with the following message.
include certificates.
vlint32 SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user string username
string service string service
string "publickeytest" string "publickey"
boolean FALSE
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
Public key algorithms are defined in the transport layer specification. Public key algorithms are defined in the transport layer specification.
The key may include certificates. The "public key to be used for authentication" may include certificates.
The server will respond to this message with either The server will respond to this message with either
SSH_MSG_USERAUTH_FAILURE or with
vlint32 SSH_MSG_USERAUTH_PK_OK SSH_MSG_USERAUTH_FAILURE or with
However, no response is sent after a successful authentication. 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 To do actual authentication, the client should then send a signature
generated by the public key. It is permissible to send the signature generated using the private key. It is permissible to send the
directly without first querying whether the key is acceptable. signature directly without first verifying whether the key is
acceptable.
vlint32 SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user string username
string service string service
string "publickey" string "publickey"
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
The public key may contain certificates.
Signature is a signature by the corresponding private key of the HASH Signature is a signature by the corresponding private key of the HASH
of the concatenation of the following, in this order: of the concatenation of the following, in this order:
o the session identifier (which binds the signature to the server host o session identifier (which binds the signature to the server host key
key and the particular key exchange), and the particular key exchange),
o length of the user name as a 32-bit integer, msb first, o length of the user name as a 32-bit integer, msb first,
o user name (without length or null characters), o user name (without length or null characters),
o length of the service name as a 32-bit integer, msb first, o length of the service name as a 32-bit integer, msb first,
o service name (without length or null characters), o service name (without length or null characters),
o length of the public key algorithm name as a 32-bit integer, msb o length of the public key algorithm name as a 32-bit integer, msb
first, first,
o public key algorithm name (without length or null characters), 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 o length of the public key from the message as a 32-bit integer, msb
first, and first, and
o the public key from the message (without length or null characters). o public key from the message (without length or null characters).
When the server receives this message, it checks whether the supplied When the server receives this message, it checks whether the supplied
key is acceptable for authentication, and if so, checks whether the key is acceptable for authentication, and if so, checks whether the
signature is correct. signature is correct.
If both checks succeed, authentication may be granted (the server may If both checks succeed, authentication may be granted (the server may
also require further authentication with other methods, without letting also require further authentication with other methods, without letting
the client know at this point that authentication has partially the client know at this point that authentication has partially
succeeded). succeeded).
2.6.2. Host-Based Authentication 2.8. Host-Based Authentication
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. The client requests this form of
authentication by sending the following message. 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.
vlint32 SSH_MSG_USERAUTH_REQUEST This method works by having the client send a signature created with the
string user 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 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 for client host
string client host name string client host name
string client user name string client user name
string signature string signature
The public key may contain certificates. Public key algorithm names are Public key algorithm names for use in "public key algorithm for host
defined in the transport layer protocol specification. key" are defined in the transport layer specification. The "public host
key for client host" may include certificates.
Signature is a signature by the host key of HASH of the concatenation of Signature is a signature with the private host key for the client host
the following, in this order: of the HASH (where the hash algorithm is from the transport layer) of
the concatenation of the following, in this order:
o the session identifier (which binds the signature to the server host o session identifier (which binds the signature to the server host key
key and the particular key exchange), and the particular key exchange),
o length of the user name as a 32-bit integer, msb first, o length of the user name as a 32-bit integer, msb first,
o user name (without length or null characters), o user name (without length or null characters),
o length of the service name as a 32-bit integer, msb first, o length of the service name as a 32-bit integer, msb first,
o service name (without length or null characters), o service name (without length or null characters),
o length of the public host key algorithm name as a 32-bit integer, msb o length of the public host key algorithm name as a 32-bit integer, msb
first, first,
o public host key algorithm name (without length or null characters), 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, o length of the public host key from the message as a 32-bit integer,
msb first, msb first,
o the public host key from the message (without length or null o public host key from the message (without length or null characters),
characters),
o length of the client host name as a 32-bit integer, msb first, o length of the client host name as a 32-bit integer, msb first,
o client host name (without length or null characters), 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 length of the client user name as a 32-bit integer, msb first, and
o client user name (without length or null characters). o client user name (without length or null characters).
Authentication is accepted if the server can verify that the host key Authentication is accepted if the server can verify that the host key
actually belongs to the client host, the given user on that host is actually belongs to the client host named in the message, the given user
allowed to log in, and the signature is a valid signature on the on that host is allowed to log in, and the signature is a valid
appropriate value by the given host key. (The server is also allowed to signature on the appropriate value by the given host key. (The server
ignore the client user name, if it only wants to authenticate the client is also allowed to ignore the client user name, if it wants to
host.) authenticate only the client host.)
It is recommended that whenever possible, the server performs 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.6.3. Kerberos Authentication 2.9. Kerberos Authentication
There are several ways to authenticate the user using Kerberos (OSF DCE There are several ways to authenticate the user using Kerberos (OSF DCE
and AFS are also incarnations of Kerberos). Different versions of and AFS are also incarnations of Kerberos). Different versions of
Kerberos (v4, v5, DCE, and AFS) have different capabilities. Separate Kerberos (v4, v5, DCE, and AFS) have different capabilities. Separate
messages have been defined for each of these. In each case, the server messages have been defined for each of these. In each case, the server
should respond with success or failure. should respond with success or failure.
vlint32 SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user string username
string service string service
string "kerberos4" string "kerberos4"
string kerberos v4 credentials string kerberos v4 credentials
vlint32 SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user string username
string service string service
string "kerberos5" string "kerberos5"
string kerberos v5 credentials string kerberos v5 credentials
string kerberos v5 ticket granting ticket (may be empty) string kerberos v5 ticket granting ticket (may be empty)
vlint32 SSH_MSG_USERAUTH_REQUEST byte SSH_MSG_USERAUTH_REQUEST
string user string username
string service string service
string "kerberos-afs" string "kerberos-afs"
string AFS token string AFS token
The Kerberos authentication requests should be sent before other The Kerberos authentication requests should be sent before other
authentication requests. The other authentication methods may need to authentication requests. The other authentication methods may need to
access files from the user's home directory, which may not be accessible 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 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 requests fail, they may have side effects, such as making the home
directory accessible. directory accessible.
3. When Authentication Is Complete 2.10. When Authentication Is Complete
Authentication is complete when the server has responded with Authentication is complete when the server has responded with
SSH_MSG_USERAUTH_SUCCESS. Any SSH_MSG_USERAUTH_REQUEST messages SSH_MSG_USERAUTH_SUCCESS; any SSH_MSG_USERAUTH_REQUEST messages received
received after sending this message will be silently ignored. after sending this message are silently ignored.
When sending SSH_MSG_USERAUTH_SUCCESS, the server also starts whatever When sending SSH_MSG_USERAUTH_SUCCESS, the server also starts whatever
application was requested as the service. Any non-authentication application was requested as the service. Any non-authentication
messages received will be passed to the requested service. messages received after this point are passed to the requested service.
4. Banner Message 3. Banner Message
The server may send a SSH_MSG_USERAUTH_BANNER message at any time. This In some jurisdictions, sending a warning message before authentication
message contains a message to be displayed to the client user before may be relevant to getting legal protection. Many Unix machines, for
attempting authentication. On most Unix machines, this message is read example, display text from /etc/issue, or use "tcp_wrappers" or similar
from /etc/issue. In some jurisdictions, sending a warning message software to display a banner before issuing a login prompt.
before authentication may be relevant to getting legal protection. The
message may contain newlines.
vlint32 SSH_MSG_USERAUTH_BANNER 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 string message
The client should normally display the message on screen if convenient. The client should by default display the message on the screen.
However, it may be sent on every login, and opening a separate window However, since the message is likely to be sent for every login attempt,
for it would probably be too annoying. The client is thus free to and since some client software will need to open a separate window for
ignore it, but displaying it should be possible at least if explicitly this warning, the client software may allow the user to explicitly
requested. disable the display of banners from the server.
5. Message Numbers 4. Message Numbers
All message numbers used by this authencation protocol are in the range All message numbers used by this authentication protocol are in the
30..39, which is part of the range reserved for protocols running on top range 20..29, which is part of the range reserved for protocols running
of the SSH transport layer protocol. Message numbers above and on top of the SSH transport layer protocol.
including 40 are reserved for protocols running on top of this level.
Receiving them before authentication is complete is an error, and the
server must disconnect in this case. After successful authentication,
these messages are passed to the higher-level service.
The server should ignore any method-specific messages received while Message numbers 30 and higher are reserved for protocols running after
expecting an authentication request. These might sometimes result if this authentication protocol, so receiving one of them before
the client sends an authentication request that the server does not authentication is complete is an error, to which the server must respond
understand. by disconnecting (preferably with a proper disconnect sent first to ease
troubleshooting).
#define SSH_MSG_USERAUTH_BANNER 31 After successful authentication, such messages are passed to the higher-
#define SSH_MSG_USERAUTH_FAILURE 32 level service.
#define SSH_MSG_USERAUTH_SUCCESS 33
#define SSH_MSG_USERAUTH_REQUEST 34
/* Messages 35-39 are reserved for method-specific messages. These are the general authentication message codes:
Different authentication methods may reuse the same message
numbers. */ #define SSH_MSG_USERAUTH_REQUEST 20
#define SSH_MSG_USERAUTH_FAILURE 21
#define SSH_MSG_USERAUTH_SUCCESS 22
#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 */ /* Key-based */
#define SSH_MSG_USERAUTH_PK_OK 35 #define SSH_MSG_USERAUTH_PK_OK 25
/* One-time passwords */ /* One-time passwords */
#define SSH_MSG_USERAUTH_OTP_PROMPT 35 #define SSH_MSG_USERAUTH_CHALLENGE 25
#define SSH_MSG_USERAUTH_OTP_RESPONSE 36 /* 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 6. Address of Author
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
 End of changes. 

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