Internet Info 1997 December/Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso/drafts/draft_ietf_q_t/draft-ietf-secsh-userauth-00.txt

Text File | 1997-03-26 | 22KB | 590 lines

Network Working Group                           Tatu Ylonen <[e-mail]>
INTERNET-DRAFT                               SSH Communications Security
draft-ietf-secsh-userauth-00.txt                          March 22, 1997
Expires: September 1, 1997


                      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 access the requested service with
the supplied user name.  This authorization can be demonstrated through
possession of a password, through possession of a key, by authenticating
the client host and user, by some other method, or a combination of
these.























Tatu Ylonen <[e-mail]>                                        [page 1]

INTERNET-DRAFT                                            March 22, 1997

Table of Contents

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . .  2
2.  User Authentication   . . . . . . . . . . . . . . . . . . . . . .  2
  2.1.  Authentication Requests   . . . . . . . . . . . . . . . . . .  3
  2.2.  Responses to Authentication Requests  . . . . . . . . . . . .  4
  2.3.  No Authentication   . . . . . . . . . . . . . . . . . . . . .  4
  2.4.  Password-Style Authentications  . . . . . . . . . . . . . . .  5
    2.4.1.  Password Authentication   . . . . . . . . . . . . . . . .  5
    2.4.2.  SecurID Authentication  . . . . . . . . . . . . . . . . .  5
  2.5.  One-Time Passwords and Similar Methods  . . . . . . . . . . .  5
    2.5.1.  S/KEY   . . . . . . . . . . . . . . . . . . . . . . . . .  6
    2.5.2.  NRL OPIE  . . . . . . . . . . . . . . . . . . . . . . . .  6
  2.6.  Other Authentication Methods  . . . . . . . . . . . . . . . .  6
    2.6.1.  Public Key Authentication   . . . . . . . . . . . . . . .  6
    2.6.2.  Host-Based Authentication   . . . . . . . . . . . . . . .  7
    2.6.3.  Kerberos Authentication   . . . . . . . . . . . . . . . .  8
3.  When Authentication Is Complete   . . . . . . . . . . . . . . . .  9
4.  Banner Message  . . . . . . . . . . . . . . . . . . . . . . . . .  9
5.  Message Numbers   . . . . . . . . . . . . . . . . . . . . . . . . 10
6.  Address of Author   . . . . . . . . . . . . . . . . . . . . . . . 10



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

Authentication works by the client first declaring the service name and
the user name to be used to access the service.  The server then
responds with the set of authentication methods that are acceptable; the
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
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
authentication request, and the server responds with success or failure.
With a failure response the server informs the client which methods may
be used to continue the dialog, thus guiding the client through a
potentially complex sequence of authentications.

Authentication methods are identified by names (strings).  Some methods
are defined in the protocol; additional methods may be defined using the
syntax "name@domainname" as the method name (for example,
"[e-mail]").  This ensures that private extensions can be


Tatu Ylonen <[e-mail]>                                        [page 2]

INTERNET-DRAFT                                            March 22, 1997

implemented without breaking compatibility and without requiring a
central registry of method names.  Method names are case-sensitive.
Names must consist of non-control characters.  Commas are not allowed in
names; at signs can only be used for the purpose described above.

The following methods are predefined:

none                 Checks if no authentication ok
password             Knowledge of password
securid              SecurID authentication
skey                 S/KEY one-time passwords
opie                 NRL OPIE one-time passwords
publickeytest        Tests whether a key is acceptable
publickey            Possession of private key
hostbased            Identity of client host and user
kerberos4            Kerberos v4 authentication
kerberos5            Kerberos v5 authentication
kerberos-afs         AFS Kerberos 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 authentication attempts a
client may perform (the recommended limit is 20 attempts).

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   SSH_MSG_USERAUTH_REQUEST
            string    user
            string    service
            string    method name
            rest of the packet is method-specific

The user name and service are repeated in every new authentication
attempt, and may change.  The server implementation must carefully check
them in every message, and must flush any accumulated authentication
state if they change.

If the requested service is not available, the server may disconnect
immediately or any time later.

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.


Tatu Ylonen <[e-mail]>                                        [page 3]

INTERNET-DRAFT                                            March 22, 1997

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   SSH_MSG_USERAUTH_FAILURE
            string    authentications_that_can_continue

authentications_that_can_continue is a comma-separated list of
authentication method names that may productively continue the
authentication dialog.  Methods that require interaction with the user
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

            vlint32   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 any further authentication
requests received after that are silently ignored.

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

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


Tatu Ylonen <[e-mail]>                                        [page 4]

INTERNET-DRAFT                                            March 22, 1997

user, this returns SSH_MSG_USERAUTH_SUCCESS.  Otherwise, this returns
failure and with it the list of authentication methods that can
continue.

2.4.  Password-Style Authentications

All password-style authentication methods use a single message of the
following format.  The server responds with success or failure.

            vlint32   SSH_MSG_USERAUTH_REQUEST
            string    user
            string    service
            string    method name
            string    authenticating string

2.4.1.  Password Authentication

This is conventional password authentication.  The method name is
"password"; the authenticating string is the plaintext password.  Note
that the password is sent as plaintext in the packet, but the entire
packet (including the password) is encrypted by the transport layer.  It
is not possible for the client to hash the password, because it cannot
know how the server stores 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 is
passed in the following message.

The method name for SecurID authentication is "securid"; the
authenticating string is the code displayed on the hardware token.

2.5.  One-Time Passwords and Similar Methods

All one-time password authentication methods use the following message
exchange:

            vlint32   SSH_MSG_USERAUTH_REQUEST
            string    user
            string    service
            string    method name

The server responds with either SSH_MSG_USERAUTH_FAILURE or

            vlint32   SSH_MSG_USERAUTH_OTP_PROMPT
            string    prompt

The client then responds with either a new authentication request or

            vlint32   SSH_MSG_USERAUTH_OTP_RESPONSE
            string    response



Tatu Ylonen <[e-mail]>                                        [page 5]

INTERNET-DRAFT                                            March 22, 1997

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 is another one-time password mechanism.  The method name for it
is "opie".

2.6.  Other Authentication Methods

2.6.1.  Public Key Authentication

The possession of a private key can serve as authentication.  This
method works by sending a signature created by the private 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 whether a particular key is acceptable as
authentication.  This done with the following message.  The key may
include certificates.

            vlint32   SSH_MSG_USERAUTH_REQUEST
            string    user
            string    service
            string    "publickeytest"
            string    public key algorithm name
            string    public key to be used for authentication

Public key algorithms are defined in the transport layer specification.
The key may include certificates.

The server will respond to this message with either
SSH_MSG_USERAUTH_FAILURE or with

            vlint32   SSH_MSG_USERAUTH_PK_OK

However, no response is sent after a successful authentication.

To do actual authentication, the client should then send a signature
generated by the public key.  It is permissible to send the signature
directly without first querying whether the key is acceptable.

            vlint32   SSH_MSG_USERAUTH_REQUEST
            string    user
            string    service
            string    "publickey"
            string    public key algorithm name
            string    public key to be used for authentication


Tatu Ylonen <[e-mail]>                                        [page 6]

INTERNET-DRAFT                                            March 22, 1997

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


Tatu Ylonen <[e-mail]>                                        [page 7]

INTERNET-DRAFT                                            March 22, 1997

            string    signature

The public key may contain certificates.  Public key algorithm names are
defined in the transport layer protocol specification.

Signature is a signature by the host key of 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 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, 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 the client
host.)

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



Tatu Ylonen <[e-mail]>                                        [page 8]

INTERNET-DRAFT                                            March 22, 1997

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   SSH_MSG_USERAUTH_REQUEST
            string    user
            string    service
            string    "kerberos4"
            string    kerberos v4 credentials

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

            vlint32   SSH_MSG_USERAUTH_REQUEST
            string    user
            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.  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 will be 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 passed to the requested service.

4.  Banner Message

The server may send a SSH_MSG_USERAUTH_BANNER message at any time.  This
message contains a message 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.  The
message may contain newlines.

            vlint32   SSH_MSG_USERAUTH_BANNER
            string    message


Tatu Ylonen <[e-mail]>                                        [page 9]

INTERNET-DRAFT                                            March 22, 1997

The client should normally display the message on screen if convenient.
However, it may be sent on every login, and opening a separate window
for it would probably be too annoying.  The client is thus free to
ignore it, but displaying it should be possible at least if explicitly
requested.

5.  Message Numbers

All message numbers used by this authencation protocol are in the range
30..39, which is part of the range reserved for protocols running on top
of the SSH transport layer protocol.  Message numbers above and
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
expecting an authentication request.  These might sometimes result if
the client sends an authentication request that the server does not
understand.

#define SSH_MSG_USERAUTH_BANNER         31
#define SSH_MSG_USERAUTH_FAILURE        32
#define SSH_MSG_USERAUTH_SUCCESS        33
#define SSH_MSG_USERAUTH_REQUEST        34

/* Messages 35-39 are reserved for method-specific messages.
   Different authentication methods may reuse the same message
   numbers. */
/* Key-based */
#define SSH_MSG_USERAUTH_PK_OK          35
/* One-time passwords */
#define SSH_MSG_USERAUTH_OTP_PROMPT     35
#define SSH_MSG_USERAUTH_OTP_RESPONSE   36

6.  Address of Author

              Tatu Ylonen
              SSH Communications Security Ltd.
              Tekniikantie 12
              FIN-02150 ESPOO
              Finland

              E-mail: [e-mail]










Tatu Ylonen <[e-mail]>                                       [page 10]