Network Working Group                           Tatu Ylonen <ylo@ssh.fi>
INTERNET-DRAFT                               SSH Communications Security

Expires: September 1, 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.

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   . . . . . . . . . . . . . . . . . . . . .  4
  2.4.  Password-Style Authentications  . . . . . . . . . . . . . . .  5
    2.4.1.
  2.4.  Password Authentication   . . . . . . . . . . . . . . . .  5
    2.4.2.  SecurID Authentication  . . . . . . . . . . . . . . . . .  5
  2.5.  One-Time Passwords and Similar Methods  . . . .  Challenge-Response Authentication   . . . . . . .  5
    2.5.1.  S/KEY . . . . . .  6
  2.6.  SecurID Authentication  . . . . . . . . . . . . . . . . . . .  6
    2.5.2.  NRL OPIE  . . . . . . .
  2.7.  Public Key Authentication   . . . . . . . . . . . . . . . . .  6
  2.6.  Other  7
  2.8.  Host-Based Authentication Methods  . . .   . . . . . . . . . . . . .  6
    2.6.1.  Public Key Authentication   . . . . .  9
  2.9.  Kerberos Authentication   . . . . . . . . . .  6
    2.6.2.  Host-Based Authentication . . . . . . . . 10
  2.10.  When Authentication Is Complete  . . . . . . .  7
    2.6.3.  Kerberos Authentication . . . . . . . 11
3.  Banner Message  . . . . . . . . .  8
3.  When Authentication Is Complete . . . . . . . . . . . . . . . .  9 11
4.  Banner  Message Numbers   . . . . . . . . . . . . . . . . . . . . . . . . .  9 11
5.  Message Numbers   . . . .  Security Considerations   . . . . . . . . . . . . . . . . . . . . 10 12
6.  Address of Author   . . . . . . . . . . . . . . . . . . . . . . . 10 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 by as follows: the client first declaring declares the service name name,
and the user name to be used under which to access the this service.  The server then
responds to this declaration with the a set of acceptable authentication
methods that are acceptable; for the given user/service combination.  The client then sends
an authentication request, and this request using one of the methods listed by the server.
This dialog continues until access has been granted granted, or until either the
client or denied. the server disconnects.

When this 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

Authentication is mostly client-driven.

The client sends an server drives the authentication request, and 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 responds with success or failure.
With a failure response in any
order.  This gives the server informs complete control ver the authentication
process if it so desired, but also gives enough flexibility for the
client which methods may
be used to continue use the methods it supports or that are most convenient for
the dialog, thus guiding user when multiple methods are offered by the client through a
potentially complex sequence of authentications. server.

Authentication methods are identified by names (strings). 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.
Names case-sensitive, and
must consist of non-control characters.  Commas are not allowed in
names; at signs can only be used for the purpose described above. alphanumeric characters and hyphens.

The following methods are predefined:

          none                 Checks if no                 Unsupported authentication ok
password             Knowledge of method
          password             Password-based authentication
          securid              SecurID authentication
skey                 S/KEY one-time
          otp-md4              One-time passwords
opie                 NRL OPIE one-time using MD4 hashing
          otp-md5              One-time passwords
publickeytest        Tests whether a key is acceptable using MD5 hashing
          otp-sha1             One-time passwords using SHA1 hashing
          publickey            Possession of private key
          hostbased            Identity of client            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.

            vlint32

  byte      SSH_MSG_USERAUTH_REQUEST
  string    user    username
  string    service
  string    method name
  rest of the packet is method-specific

The user name 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.

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
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

            vlint32

            byte      SSH_MSG_USERAUTH_FAILURE
            string    authentications_that_can_continue

authentications_that_can_continue    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.  Methods

It is recommended that require interaction with servers only include those methods in the user
should not be listed unless they can list
that are actually useful.  However, it is not illegal to include methods
that cannot be used to authenticate
this the user.  Note that successful response to one method

Already successfully completed authentications should not be included in
the list may
not be enough to unless they really should be accepted; the server performed again for some weird
reason.

"Partial success" is allowed TRUE if the particular authentication request, in
response to require multiple
authentications.  The server should which this is being sent, was accepted, but more
authentication is still needed.  It is FALSE if the request was not list authentications that it has
already accepted.
successfully processed.

When the server accepts authentication, it responds with

            vlint32
            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, and once.

Once SSH_MSG_USERAUTH_SUCCESS has been sent, any further authentication
requests received after that are silently ignored.

Once SSH_MSG_USERAUTH_SUCCESS has been sent, ignored, while any non-authentication 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-Style Authentications

All password-style  Password Authentication

Password authentication methods use a single message of uses the following format.  The packets.  Note that a server responds with success or failure.

            vlint32
may request the user to change password.

            byte      SSH_MSG_USERAUTH_REQUEST
            string    user    username
            string    service
            string    method name
            string    authenticating    "password"
            boolean   FALSE
            string

2.4.1.  Password Authentication

This is conventional    plaintext password authentication.  The method name is
"password"; the authenticating

            byte      SSH_MSG_USERAUTH_PASSWD_CHANGEREQ
            string    prompt

            byte      SSH_MSG_USERAUTH_REQUEST
            string    username
            string    service
            string    "password"
            boolean   TRUE
            string is the    plaintext password.  Note
that the old password is sent as
            string    plaintext in new password

            byte      SSH_MSG_USERAUTH_PASSWD_CHANGEREPLY
            boolean   password changed

Normally, the packet, but client sends the entire
packet (including first form, and the password) is encrypted by server responds with
success or failure.  However, the transport layer.  It
is not possible for server may also send a
SSH_MSG_USERAUTH_PASSWD_CHANGEREQ.  In this case, the client to hash should
request a new password from the password, because it cannot
know how user, and send a new request of the server stores

second form to change the password.

2.4.2.  SecurID Authentication

SecurID is a timing-based hardware token authenticator.  The user enters
a code displayed on the token as authentication.  The entered token server will then reply with
SSH_MSG_USERAUTH_PASSWD_CHANGEREPLY.  If "password changed" is
passed in true, the following message.

The method name for SecurID authentication is "securid";
server will continue with either SSH_MSG_USERAUTH_SUCCESS or
SSH_MSG_USERAUTH_FAILURE.  Otherwise, the
authenticating string is dialog continues and the code displayed on
client can try changing the hardware token.

2.5.  One-Time Passwords and Similar Methods

All one-time password again.

2.5.  Challenge-Response Authentication

Most challenge-response authentication methods use the following message
exchange:

            vlint32

            byte      SSH_MSG_USERAUTH_REQUEST
            string    user    username
            string    service
            string    method name
            boolean   FALSE

The server responds with either SSH_MSG_USERAUTH_FAILURE or

            vlint32   SSH_MSG_USERAUTH_OTP_PROMPT

  byte      SSH_MSG_USERAUTH_CHALLENGE
  string    prompt

The client then responds with either a new authentication request or

            vlint32   SSH_MSG_USERAUTH_OTP_RESPONSE

            byte      SSH_MSG_USERAUTH_REQUEST
            string    response

The    username
            string    service
            string    method name
            boolean   TRUE
            string    response

The server responds to this message with either success or failure.

2.5.1.  S/KEY

S/KEY is an early one-time password mechanism.

The method name is
"skey".

2.5.2.  NRL OPIE

NRL OPIE "otp-md4", "otp-md5" and "otp-sha1" methods are defined in RFC 1938,
and follow this pattern.

2.6.  SecurID Authentication

SecurID is another one-time password mechanism. 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 it SecurID authentication is "opie".

2.6.  Other "securid".  The following
packets are used:

            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

            byte      SSH_MSG_USERAUTH_SECURID_PINREPLY
            boolean   pin accepted

Authentication Methods

2.6.1. 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 by 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 query verify whether a particular key is would be acceptable as
authentication.  This is done with the following message.  The key may
include certificates.

            vlint32

  byte      SSH_MSG_USERAUTH_REQUEST
  string    user    username
  string    service
  string    "publickeytest"    "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

SSH_MSG_USERAUTH_FAILURE or with

            vlint32

            byte      SSH_MSG_USERAUTH_PK_OK

However, no response is sent after a successful authentication.
            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 by using the public private key.  It is permissible to send the
signature directly without first querying verifying whether the key is
acceptable.

            vlint32

            byte      SSH_MSG_USERAUTH_REQUEST
            string    user    username
            string    service
            string    "publickey"
            boolean   TRUE
            string    public key algorithm name
            string    public key to be used for authentication
            string    signature

The public key may contain certificates.

Signature  is a signature by the corresponding private key of the HASH
of the concatenation of the following, in this order:

o  the  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  the  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).

2.6.2.

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.

            vlint32   SSH_MSG_USERAUTH_REQUEST
            string    user  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

The public key may contain certificates.

Public key algorithm names for use in "public key algorithm for host
key" are defined in the transport layer protocol specification.  The "public host
key for client host" may include certificates.
Signature is a signature by 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  the  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  the  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  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, 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 only wants to
authenticate only the client host.)

It is recommended that whenever possible, the server performs 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.6.3.

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.

            vlint32

            byte      SSH_MSG_USERAUTH_REQUEST
            string    user    username
            string    service
            string    "kerberos4"
            string    kerberos v4 credentials

            vlint32

            byte      SSH_MSG_USERAUTH_REQUEST
            string    user    username
            string    service
            string    "kerberos5"
            string    kerberos v5 credentials
            string    kerberos v5 ticket granting ticket (may be empty)

            vlint32

            byte      SSH_MSG_USERAUTH_REQUEST
            string    user    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.

3.

2.10.  When Authentication Is Complete

Authentication is complete when the server has responded with
SSH_MSG_USERAUTH_SUCCESS.  Any
SSH_MSG_USERAUTH_SUCCESS; any SSH_MSG_USERAUTH_REQUEST messages received
after sending this message will be 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 will be after this point are passed to the requested service.

4.

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. time
before authentication is successful.  This message contains a message text to be
displayed to the client user before
attempting authentication.  On most Unix machines, this message is read
from /etc/issue.  In some jurisdictions, sending a warning message
before authentication may be relevant to getting legal protection. is attempted.  The
message
form is as follows, where "message" may contain newlines.

            vlint32 newlines:

            byte      SSH_MSG_USERAUTH_BANNER
            string    message

The client should normally by default display the message on screen if convenient. the screen.
However, it may since the message is likely to be sent on for every login, login attempt,
and opening since some client software will need to open a separate window for it would probably be too annoying.  The
this warning, the client is thus free software may allow the user to
ignore it, but displaying it should be possible at least if explicitly
requested.

5.
disable the display of banners from the server.

4.  Message Numbers

All message numbers used by this authencation authentication protocol are in the
range
30..39, 20..29, which is part of the range reserved for protocols running
on top of the SSH transport layer protocol.

Message numbers above 30 and
including 40 higher are reserved for protocols running on top of after
this level.
Receiving authentication protocol, so receiving one of them before
authentication is complete is an error, and to which the server must respond
by disconnecting (preferably with a proper disconnect in this case. sent first to ease
troubleshooting).

After successful authentication,
these such messages are passed to the higher-level higher-
level service.

The server should ignore any method-specific messages received while
expecting an authentication request.

These might sometimes result if are the client sends an general authentication request that the server does not
understand. message codes:

#define SSH_MSG_USERAUTH_BANNER         31 SSH_MSG_USERAUTH_REQUEST            20
#define SSH_MSG_USERAUTH_FAILURE        32            21
#define SSH_MSG_USERAUTH_SUCCESS        33            22

#define SSH_MSG_USERAUTH_REQUEST        34

/* Messages 35-39 are SSH_MSG_USERAUTH_BANNER             23

In addition to the above, there is a range of message numbers (25..29)
reserved for method-specific messages.
   Different  These messages are only sent by
the server (client only sends SSH_MSG_USERAUTH_REQUEST messages).
Differnet authentication methods may 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          35              25
/* One-time passwords */
#define SSH_MSG_USERAUTH_OTP_PROMPT     35 SSH_MSG_USERAUTH_CHALLENGE          25
/* SecurID */
#define SSH_MSG_USERAUTH_SECURID_PINREQ     25
#define SSH_MSG_USERAUTH_OTP_RESPONSE   36 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