W3C home > Mailing lists > Public > ietf-tls@w3.org > July to September 1996

Updates to SSH protocol

From: Tatu Ylonen <ylo@ssh.fi>
Date: Thu, 26 Sep 1996 19:45:06 +0300 (EET DST)
Message-Id: <199609261645.TAA29628@pilari.ssh.fi>
To: ietf-tls@w3.org
A couple of weeks ago, Martin Abadi pointed out problems with the
published SSH transport layer protocol draft.

These problems should now be fixed, and there are a few other changes.
The basic change is in how the session identifier is calculated and
how the key exchange is in authenticated.

Additionally, a new naming scheme has been introduced for
cryptographic algorithms.  It appears that a number of (mostly
military or other government) organizations would like to use their
own, unpublished algorithms.  Many people would also like to
experiment with new algorithms without going through a central
registry of algorithm identifiers.  SSH now represents all algorithms
with NAMES.  Standard algorithms have names such as "3des-cbc" or
"hmac-sha".  Additionally, anyone can define their own algorithms by
using the syntax name@domainname, such as "our-own-cipher@ssh.fi".
This allows different implementations to negotiate whatever algorithms
they like, including extensions, without worrying about conflicting
extensions by someone else.

I'll include below the up to date SSH 2.0 transport and user
authentication protocol specs.

    Tatu

----- cut here for transport.txt ------
Network Working Group                           Tatu Ylonen <ylo@ssh.fi>
INTERNET-DRAFT                               SSH Communications Security
transport.txt                                          September 6, 1996
Expires: January 1st, 1997


                      SSH Transport Layer 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 document describes the SSH transport layer protocol.  The protocol
can be used as a basis for a number of secure network services.  It pro-
vides strong encryption, server authentication, and integrity protec-
tion.

























Tatu Ylonen <ylo@ssh.fi>                                        [page 1]

INTERNET-DRAFT                                         September 6, 1996
 
Table of Contents

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . .  2
2.  Data Type Representations Used in the Protocol  . . . . . . . . .  3
  2.1.  vlint32   . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  2.2.  string  . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  2.3.  boolean   . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  2.4.  byte  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  2.5.  uint16  . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  2.6.  uint32  . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
3.  Algorithm Naming  . . . . . . . . . . . . . . . . . . . . . . . .  4
4.  Connection Setup  . . . . . . . . . . . . . . . . . . . . . . . .  4
  4.1.  Use over TCP/IP   . . . . . . . . . . . . . . . . . . . . . .  4
  4.2.  Protocol Version Exchange   . . . . . . . . . . . . . . . . .  5
  4.3.  Compatibility with Old SSH Versions   . . . . . . . . . . . .  5
    4.3.1.  Old Client, New Server  . . . . . . . . . . . . . . . . .  5
    4.3.2.  New Client, Old Server  . . . . . . . . . . . . . . . . .  5
5.  Binary Packet Protocol  . . . . . . . . . . . . . . . . . . . . .  5
  5.1.  Maximum Packet Length   . . . . . . . . . . . . . . . . . . .  6
  5.2.  Compression   . . . . . . . . . . . . . . . . . . . . . . . .  6
  5.3.  Encryption  . . . . . . . . . . . . . . . . . . . . . . . . .  7
  5.4.  Data Integrity  . . . . . . . . . . . . . . . . . . . . . . .  8
6.  Key Exchange  . . . . . . . . . . . . . . . . . . . . . . . . . .  9
  6.1.  Algorithm Negotiation   . . . . . . . . . . . . . . . . . . .  9
  6.2.  Double-Encrypting Key Exchange  . . . . . . . . . . . . . . . 12
    6.2.1.  Server Sends Host Key   . . . . . . . . . . . . . . . . . 12
    6.2.2.  Deriving Session Identifier   . . . . . . . . . . . . . . 13
    6.2.3.  Client Sends Double-Encrypted Session Key   . . . . . . . 13
    6.2.4.  Deriving Encryption and Integrity Keys  . . . . . . . . . 14
  6.3.  Taking Keys into Use  . . . . . . . . . . . . . . . . . . . . 14
7.  Key Re-Exchange   . . . . . . . . . . . . . . . . . . . . . . . . 15
8.  Service Request   . . . . . . . . . . . . . . . . . . . . . . . . 15
9.  Stream-Based Services   . . . . . . . . . . . . . . . . . . . . . 16
10.  Additional Messages  . . . . . . . . . . . . . . . . . . . . . . 16
  10.1.  Disconnection Message  . . . . . . . . . . . . . . . . . . . 17
  10.2.  Ignored Data Message   . . . . . . . . . . . . . . . . . . . 17
  10.3.  Reserved Messages  . . . . . . . . . . . . . . . . . . . . . 17
11.  Summary of Message Numbers   . . . . . . . . . . . . . . . . . . 17
12.  Public Keys and Public Key Infrastructure  . . . . . . . . . . . 18
  12.1.  ssh-simple-rsa   . . . . . . . . . . . . . . . . . . . . . . 18



1.  Introduction

The SSH protocol is a secure transport layer protocol.  It provides
strong encryption, cryptographic host autentication, and integrity
protection.

Authentication in this protocol level is host-based; this protocol does
not perform user authentication.  It is expected that a higher level
protocol will be defined on top of this protocol that will perform user
authentication for those services that need it.


Tatu Ylonen <ylo@ssh.fi>                                        [page 2]

INTERNET-DRAFT                                         September 6, 1996
 
The protocol has been designed to be simple, flexible, allow parameter
negotiation, and minimize the number of round-trips.  Key exchange
method, public key algorithm, symmetric encryption algorithm, message
authentication algorithm, and hash algorithm are all negotiated.  It is
expected that in most environments, only 1.5 round-trips will be needed
for full key exchange, server authentication, service request, and
acceptance notification of service request.  The worst case is 2.5
round-trips.

2.  Data Type Representations Used in the Protocol

2.1.  vlint32

The vlint32 can represent arbitrary 32-bit unsigned integers.  It is
stored as a variable number of bytes (1-5 bytes), depending on the value
being stored.

Bits 6-7 of the first byte (the most significant bits) determine the
number of additional bytes that follow, and are interpreted as follows.

  Bit7  Bit6    Number of bytes that follow
   0     0       0
   0     1       1
   1     0       2
   1     1       4

Bits 0-5 of the first byte and the following bytes contain the value of
the integer, MSB first.

If bits 6-7 are both one, the remaining bits in the first byte are zero
(reserved for future extension).

2.2.  string

A string here means an arbitrary length binary string.  Strings are
allowed to contain arbitrary binary data, including null characters and
8-bit characters.

A string is represented as a vlint32 containing its length, followed by
zero or more characters that are the value of the string.  No
terminating null character is normally included in the string.

2.3.  boolean

A boolean value is represented as a single byte.  The value 0 represents
false, and the value 1 represents true.  All non-zero values are
interpreted as true, but applications should not store values other than
0 and 1.

2.4.  byte

A byte represents an arbitrary 8-bit value.  Fixed length data is
sometimes represented as an array of bytes, written byte[n], where n is


Tatu Ylonen <ylo@ssh.fi>                                        [page 3]

INTERNET-DRAFT                                         September 6, 1996
 
the number of bytes in the array.

2.5.  uint16

A 16-bit unsigned integer, represented as two bytes, MSB first.

2.6.  uint32

A 32-bit unsigned integer, represented as four bytes, MSB first.

3.  Algorithm Naming

This protocol refers to particular hash, encryption, integrity,
compression, and key exchange algorithms in various places.  There are
some standard algorithms that all implementations are required to
support.  There are also algorithms that are defined in the protocol
specification but are optional.  Furthermore, it is expected that some
organizations will want to use their own algorithms whenever possible.
This leads to the problem of how algorithm identifiers are allocated.

In this protocols, all algorithm identifiers are represented as strings.
Names are case-sensitive.  Algorithm lists are comma-separated lists of
these identifiers, without spaces.  There are two formats for algorithm
identifiers:

o  Algorithms defined in the base protocol are simple strings, such as
   "3des-cbc", "sha-1", "hmac-sha", or "zip" (the quotes are not part of
   the name).  Defined algorithms may be mandatory or optional.  All
   interoperable implementations should implement mandatory algorithms
   and offer them as a possibility in key exchanges.  Optional
   algorithms are not crucial for interoperability, but may provide
   better performance or other advantages.  It is up to an
   implementation to decide which of these are supported and which are
   offered in key exchanges by default.

o  Anyone can define additional algorithms by using names in the format
   name@domainname, e.g. "ourcipher-cbc@ssh.fi".  The format of the part
   preceding the at sign is not specified; it may contain any non-
   control characters except at signs and commas.  The part following
   the at sign should be a valid internet domain name for the
   organization defining the name.  It is up to the each organization
   how they manage its locally defined names.

4.  Connection Setup

SSH works over any 8-bit clean, binary-transparent transport.  The
client initiates the connection, and sets up the binary-transparent
transport.

4.1.  Use over TCP/IP

When used over TCP/IP, the server normally listens for connections on
port 22.  This port number has been registered with the IANA (Internet


Tatu Ylonen <ylo@ssh.fi>                                        [page 4]

INTERNET-DRAFT                                         September 6, 1996
 
Assigned Numbers Authority), and has been officially assigned for SSH.

4.2.  Protocol Version Exchange

When the connection has been established, both sides send an
identification string of the form "SSH-protoversion-softwareversion
comments", followed by a newline.  No null character is sent.  The
maximum length of the string is 255 characters, including the newline.
The protocol version described in this document is 2.0.  Version strings
should only contain printable characters, not including space or '-'.
The string is used in debugging outputs to ease debugging; the protocol
version is also used to trigger compatible extensions.  It is
recommended that the strings be as descriptive as possible.  The comment
string could include information such as the platform type which might
be useful in solving user problems.

Key exchange will begin immediately after sending this identifier
(normally without waiting for the identifier from the other side -- see
the next section for compatibility issues).  All packets following the
identification string will use the binary packet protocol, to be
described below.

4.3.  Compatibility with Old SSH Versions

During a transition period, it is important to be able to work
compatibly with installed SSH clients and servers using an older version
of the protocol.  Information in this section is only relevant for
implementations supporting compatibility with old versions.

4.3.1.  Old Client, New Server

Server implementations should support a configurable "compatibility"
flag that enables compatibility with old versions.  When this flag is
on, the server will not send any further data after its initialization
string until it has received an identification string from the client.
The server can then determine whether the client is using an old
protocol, and can revert to the old protocol if desired.

When compatibility with old clients is not needed, the server should
send its initial key exchange data immediately after the identification
string.  This saves a round-trip.

4.3.2.  New Client, Old Server

Since the new client will immediately send additional data after its
identification string (before receiving server's identification), the
old protocol has already been corrupted when the client learns that the
server is old.  When this happens, the client should close the
connection to the server, and reconnect using the old protocol this
time.

5.  Binary Packet Protocol



Tatu Ylonen <ylo@ssh.fi>                                        [page 5]

INTERNET-DRAFT                                         September 6, 1996
 
Each packet consists of the following fields:

    Length
      The length of the packet (bytes).  This represents the number of
      bytes that follow this value, not including the optional MAC.  The
      length is represented as a vlint32.

    Padding length
      Length of padding (bytes).  This field is represented as a
      vlint32.

    Payload
      The useful contents of the packet.  This field is optionally
      compressed.

    Padding
      Arbitrary-length padding, such that the total length of
      length+paddinglength+payload+padding is a multiple of the cipher
      block size or 8, whichever is larger.  It is recommended that at
      least four bytes of random padding be always used.

    MAC
      Message authentication code.  This field is optional, and its
      length depends on the algorithm in use.

Note that length of the concatenation of packet length, padding length,
payload, and padding must be a multiple of the cipher block size or 8,
whichever is larger.  This constraint is enforced even when using stream
ciphers.  Note that the packet length field is also encrypted, and
processing it requires special care when sending/receiving packets.  In
particular, one has to be extra careful when computing the amount of
padding, as changing the amount of padding can also change the size of
the length fields.  The minimum size of a packet is 8 (or cipher block
size, whichever is larger) characters (plus MAC); implementations should
decrypt the length after receiving the first 8 (or cipher block size,
whichever is larger) bytes of a packet.

When the protocol starts, no encryption is in effect, no compression is
used, and no MAC is in use.  During key exchange, an encryption method,
compression method, and a MAC method are selected.  Any further messages
will use the negotiated algorithms.

5.1.  Maximum Packet Length

The maximum length of the uncompressed payload is 32768 bytes.  The
maximum size of the entire packet, including length, padding length,
payload, padding, and MAC, is 35000 bytes.  The motivation for this
limit is to keep the protocol easy to implement on 16-bit machines.

5.2.  Compression

If compression has been negotiated, the payload field (and only it) will
be compressed using the negotiated algorithm.  The length field will


Tatu Ylonen <ylo@ssh.fi>                                        [page 6]

INTERNET-DRAFT                                         September 6, 1996
 
contain the compressed length (i.e., that transmitted on the wire).

Compressed packets must not exceed the total packet size limit; the
compression algorithm must guarantee that it does not expand the packet
too much.  The uncompressed payload size must not exceed the maximum
payload size (the compressed payload, however, may be bigger than the
maximum payload size, as long as the packet size limit is not exceeded).

The following compression methods are currently defined:

          none     mandatory       no compression
          zlib     optional        GNU ZLIB compression at level 6

The "zlib" compression is described in RFC1950.

The compression context is initialized after key exchange, and is passed
from one packet to the next with only a partial flush being performed at
the end of each packet.  A partial flush means that all data will be
output, but the next packet will continue using compression tables from
the end of the previous packet.

Compression is independent in each direction, and the different
compression methods may be used for each direction.

5.3.  Encryption

An encryption algorithm and a key will be negotiated during the key
exchange.  When encryption is in effect, the length, padding length,
payload and padding fields of each packet will be encrypted with the
given algorithm.

The encrypted data in all packets sent in one direction will be
considered a single data stream.  For example, initialization vectors
will be passed from the end of one packet to the beginning of the next
packet.

The ciphers in each direction will run independently of each other.
They will typically use a different key, and different ciphers can be
used in each direction.

The following ciphers are currently supported:

          none             optional          no encryption
          3des-cbc         mandatory         three-key 3DES in CBC mode
          idea-cbc         optional          IDEA in CBC mode
          arcfour          optional          ARCFOUR stream cipher
          blowfish-cbc     optional          Blowfish in CBC mode

The 3des-cbc encryption is three-key triple-DES (encrypt-decrypt-
encrypt), where the first 8 bytes of the key are used for the first
encryption, the next 8 bytes for the decryption, and the following 8
bytes for the final encryption.  This requires 24 bytes of key data (of
which the parity bits are not actually used).  To implement CBC mode,


Tatu Ylonen <ylo@ssh.fi>                                        [page 7]

INTERNET-DRAFT                                         September 6, 1996
 
there is only one initialization vector.

The ARCFOUR cipher is compatible with the RC4 cipher; RC4 is a trademark
of RSA Data Security, Inc.

Descriptions of all of these ciphers can be found e.g. from Bruce
Schneier: Applied Cryptography, 2nd ed., John Wiley and Sons, 1996.

5.4.  Data Integrity

Data integrity is protected by including with each packet a message
authentication code (MAC) that is computed from a shared secret, packet
sequence number, and the contents of the packet.

The message authentication algorithm and key are negotiated during key
exchange.  Initially, no MAC will be in effect, and its length will be
zero.  After key exchange, the selected MAC will be computed before
encryption from the concatenation of packet data (lengths, payload, and
padding) and a packet sequence number (stored as a 32-bit integer, MSB
first).  The integrity key is also used in the computation of the MAC,
but the way it is used depends on the MAC algorithm in use.  Note that
the MAC algorithm may be different for each direction.

The packet sequence number is only used for integrity checking.  It is
never explicitly transmitted, but it is included in MAC computation to
ensure that no packets are lost or received out of sequence.  The
sequence number of the first packet sent is zero; from there on the
sequence number is incremented by one for every packet sent (separately
for each direction).  The packet number is 32 bits and wraps around if
32 bits is not enough for representing it.  The sequence number is
incremented also for packets that are not encrypted or MACed, and is not
reset even if keys are renegotiated later.

The check bytes resulting from the MAC algorithm are transmitted without
encryption as the last part of the packet.  The number of check bytes
depends on the algorithm chosen.

The following MAC algorithms are currently defined:

          none        optional         no MAC
          hmac-md5    optional         HMAC-MD5 (length = 16)
          hmac-sha    optional         HMAC-SHA (length = 20)
          md5-8       optional         first 8 bytes MD5 key+data+key
          sha-8       optional         first 8 bytes SHA key+data+key
          sha         mandatory        SHA of key+data+key (20 bytes)

The HMAC methods are described in draft-ietf-ipsec-hmac-md5-00.txt.  XXX
change to refer to an RFC when one becomes available.

The "md5-8" method returns the first 8 bytes of MD5 of the concatenation
of the key, authenticated data, and the key again.  The "sha-8" method
is the same but using the SHA hash.



Tatu Ylonen <ylo@ssh.fi>                                        [page 8]

INTERNET-DRAFT                                         September 6, 1996
 
Even though only the "md5" method is mandatory, it is recommended that
implementations support and prefer the other methods.  (This method
exists only as a fallback should unexpected patent problems surface.)

6.  Key Exchange

Key exchange begins by each side sending lists of supported algorithms.
Each side has a preferred algorithm, and it is assumed that most
implementations at any given time will use the same preferred algorithm.
Each side will make the guess that the other side is using the same
algorithm, and may send an initial key exchange packet according to the
algorithm if appropriate for the preferred method.  If the guess is
wrong, they'll ignore the guessed packet, select a common algorithm, and
send the initial key exchange packet again, this time for the same
algorithm.

Currently, the following key exchange methods have been defined:

          double-encrypting-sha        mandatory

The implementation of these methods is described later in this section.

One should note that server authentication in the double-encrypting key
exchange is implicit, and the client doesn't really know the identity of
the server until it receives a message from the server using the correct
MAC and encryption.  This means that an attacker could fool the client
into using no encryption (if the client is willing to accept no
encryption), and the client might in some cases send sensitive data,
such as a password, before it notices that the server isn't responding
properly.  For this reason, it is recommended that clients should not
accept "none" encryption unless explicitly requested by the user.
Alternatively, they should wait for the server's response to the service
request before sending anything else.

6.1.  Algorithm Negotiation

Each side sends the following packet (this is the part that goes inside
the payload):

            vlint32   SSH_MSG_KEXINIT
            byte[16]  cookie (random bytes)
            string    kex_algorithms
            string    server_host_key_algorithms
            string    encryption_algorithms_client_to_server
            string    encryption_algorithms_server_to_client
            string    mac_algorithms_client_to_server
            string    mac_algorithms_server_to_client
            string    compression_algorithms_client_to_server
            string    compression_algorithms_server_to_client
            string    hash_algorithms
            boolean   first_kex_packet_follows
            byte[4]   0 (reserved for future extension)



Tatu Ylonen <ylo@ssh.fi>                                        [page 9]

INTERNET-DRAFT                                         September 6, 1996
 
Each of the algorithms strings are comma-separated lists of algorithm
names.  Each supported (allowed) algorithm should be listed, in order of
preference.  The preferred (guessed) algorithm should be listed first.
Each string must contain at least one algorithm name.  The value "none"
is not automatically allowed; if a party permits connections with "none"
as one of the algorithms, it should list that as an algorithm.

    cookie
      The cookies are random values generated by each side.  They are
      used when deriving keys from the shared secret.  Their purpose is
      to make it impossible for either side to fully determine the keys
      (which might open possibilities for passing certain
      signatures/authentications to third parties).

    kex_algorithms
      Key exchange algorithms were defined above.  The first algorithm
      is the preferred (and guessed) algorithm.  If both sides make the
      same guess, that algorithm is used.  Otherwise, the following
      algorithm is used to choose a key exchange method: iterate over
      client's kex algorithms, one at a time.  Choose the first
      algorithm that satisfies the following conditions: 1) the server
      also supports the algorithm 2) if the algorithm requires an
      encryption-capable host key, there is an encryption-capable
      algorithm on the server's  server_host_key_algorithms  that is
      also supported by the client 3) if the algorithm requires a
      signature-capable host key, there is a signature-capable algorithm
      on the server's  server_host_key_algorithms  that is also
      supported by the client.  If no algorithm satisfying all these
      conditions can be found, connection fails.

      The kex algorithm names were listed above.

    server_host_key_algorithms
      Lists the algorithms supported for the server host key.  The
      server lists the algorithms for which it has host keys; the client
      lists the algorithms that it is willing to accept.  (There can be
      multiple host keys for a host, possibly with different
      algorithms.)

      Some host keys may not support both signatures and encryption
      (this can be determined from the algorithm), and thus not all host
      keys are valid for all key exchange methods.

      Algorithm selection depends on whether the chosen kex algorithm
      requires a signature- or encryption capable host key.  The first
      algorithm on the client's list that satisfies the requirements and
      is also supported by the server is chosen.

      Section ``Public Key Formats'' lists the available algorithm
      names.

    encryption_algorithms
      Lists the acceptable symmetric encryption algorithms in order of


Tatu Ylonen <ylo@ssh.fi>                                       [page 10]

INTERNET-DRAFT                                         September 6, 1996
 
      preference.  The chosen encryption algorithm will be the first
      algorithm on the client's list that is also on the server's list.
      If there is no such algorithm, connection fails.

      Note that "none" must be explicitly listed if it is to be
      acceptable.  The defined algorithm names are listed in Section
      ``Encryption''.

      The algorithm to use is negotiated separately for each direction,
      and different algorithms may be chosen.

    mac_algorithms
      Lists the acceptable MAC algorithms in order of preference.  The
      chosen MAC algorithm will be the first algorithm on the client's
      list that is also on the server's list.  If there is no such
      algorithm, connection fails.

      Note that "none" must be explicitly listed if it is to be
      acceptable.  The MAC algorithm names are listed in Section ``Data
      Integrity''.

      The algorithm to use is negotiated separately for each direction,
      and different algorithms may be chosen.

    compression_algorithms
      Lists the acceptable compression algorithms in order of
      preference.  The chosen compression algorithm will be the first
      algorithm on the client's list that is also on the server's list.
      If there is no such algorithm, connection fails.

      Note that "none" must be explicitly listed if it is to be
      acceptable.  The compression algorithm names are listed in Section
      ``Compression''.

      The algorithm to use is negotiated separately for each direction,
      and different algorithms may be chosen.

    hash_algorithms
      Lists the acceptable hash algorithms in order of preference.  The
      chosen hash algorithm will be the first algorithm on the client's
      list that is also on the server's list.  If there is no such
      algorithm, connection fails.

      Implementations should only permit algorithms that they consider
      to be fairly secure, as the hash function will be used e.g. for
      deriving various keys from the shared secret.  All hash algorithms
      must produce at least 16 bytes of output.

      Currently, the following hash functions are defined.

             md5          optional      MD5 algorithm (16 byte output)
             sha-1        mandatory     SHA-1 algorithm (20 byte output)



Tatu Ylonen <ylo@ssh.fi>                                       [page 11]

INTERNET-DRAFT                                         September 6, 1996
 
    first_kex_packet_follows
      Each side makes a guess of the negotiated key exchange method.
      This is based on the assumption that at any particular time there
      will be a single key exchange method and algorithm combination
      that dominates the installed base.  Making a guess about the
      algorithm will save a round-trip in the typical case, and will
      incur little extra cost in the other cases.

      Each side will determine if they are supposed to send an initial
      packet in their guessed key exchange method.  If they are, they
      will set this field to true and follow this packet by the first
      key exchange packet.

      The guessed method is the one listed first on the kex_algorithms,
      server_host_key_algorithms, and hash_algorithms lists.  If the
      negotiated values for any of these algorithms differs from the
      first value on either side, the guess is taken to be wrong, and
      the packet sent based on the guess is ignored.  Whether the
      packets based on the guess are actually wrong is not a factor in
      this decision (the information may not be available to make this
      decision).

      After receiving the SSH_MSG_KEXINIT packet from the other side,
      each party will know whether their guess was right.  If the guess
      was wrong, and this field is true, the next packet will be
      silently ignored, and each side will then act as determined by the
      negotiated key exchange method.  If the guess was right, key
      exchange will immediately continue.

6.2.  Double-Encrypting Key Exchange

The double-encrypting key exchange requires that the server host key
supports encryption.  The idea is that the server sends its public host
key and a periodically changing key (called the server key).  The client
then verifies that it is the correct key for the server, generates a
session key, encrypts the session key using both the server host key and
the server key, and sends the encrypted session key to the server.

The server key and host keys must both support encryption, and their
sizes must be compatible in such a way that the result of encrypting a
value with one of them can be encrypted with the other.  The smaller of
the keys must be able to encrypt at least 48 bytes.  Both keys must use
the same public key algorithm.

6.2.1.  Server Sends Host Key

First, the server sends its public host and server keys in the following
packet:

            vlint32   SSH_MSG_KEXRSA_HOSTKEY
            string    public host key
            string    public server key



Tatu Ylonen <ylo@ssh.fi>                                       [page 12]

INTERNET-DRAFT                                         September 6, 1996
 
The host key and server key are stored in binary representation as
described in Section ``Public Key Formats''.  Both keys are of the type
negotiated for the server host key.

After receiving the public keys, the client validates that the host key
really belongs to the intended server.  How this verification happens is
not specified in this protocol.  Currently it may be checked against a
database of known name-key mappings; in future it will be validated
using an Internet public key infrastructure.  The key may contain
certificates to facilitate this.

If the client is not willing to trust the server host key, it should
send an SSH_MSG_DISCONNECT packet and close the connection.

The client then generates a 256 bit random session key.

6.2.2.  Deriving Session Identifier

To authenticate that no-one has been manipulating the key exchange with
the server, the client computes an SHA-1 hash of the concatenated
payloads of (in this order) the client's SSH_MSG_KEXINIT, the server's
SSH_MSG_KEXINIT, the server's SSH_MSG_KEXRSA_HOSTKEY message, and the 32
bytes of the session key.  This value is called the  session identifier,
and it is used to authenticate the key exchange.

Note that the use of SHA-1 was hard-coded here.  This is used to
authenticate the key exchange, and using HASH here would lead to all
sorts of potential problems in verifying the security of the protocol.
Using a fixed hash short-circuits verification to the properties of
SHA-1.  Should the need ever arise, the only way to switch to another
algorithm here is to define a new key exchange algorithm (which, in
fact, is not very difficult).

The session identifier is also used in host authentication and other
authentication methods as data that is signed to prove possession of a
private key.

The session identifier is computed only once; it is not changed or
recomputed if keys are later re-exchanged.

6.2.3.  Client Sends Double-Encrypted Session Key

The client forms a message to send to the server by concatenating the
following (in this order): six zero bytes (reserved for future
extension), first 10 bytes of the session identifier, and the 32 bytes
of the shared secret.  This results in a total of 48 bytes of data to be
passed to the server.  Note that the negotiated algorithms are not
explicitly passed, as the algorithms given in Section ``Algorithm
Negotiation'' fully determine the algorithms.

The resulting data is encrypted with the smaller of host key and server
key, and the result then with the larger of them.  The resulting double-
encrypted session key is then sent to the server.  Note that public-key


Tatu Ylonen <ylo@ssh.fi>                                       [page 13]

INTERNET-DRAFT                                         September 6, 1996
 
encryption probably involves padding, depending on the algorithm.

            vlint32   SSH_MSG_KEXRSA_SESSIONKEY
            string    double-encrypted session key

Upon receiving this message, the server uses its private host and server
keys to decrypt the session key.  It computes a corresponding SHA hash,
and compares the hash values.  If the hash does not match, the server
disconnects with the appropriate message.  If the hash matches, the
server responds with an SSH_MSG_NEWKEYS message and takes the keys into
use.

6.2.4.  Deriving Encryption and Integrity Keys

As a result of the key exchange, the parties have a 256-bit shared
secret.  Various keys are computed from this secret and the session
identifier.  The session identifier is used to make it impossible for
either party to alone determine the keys.

Each key is computed as HASH of the concatenation of session identifier
and 16 bytes of secret data.  The secret data is different for each key,
and is taken from the 32-byte shared secret as follows:

o  Initial IV client to server: bytes 0-15

o  Initial IV server to client: bytes 1-16

o  Encryption key client to server: bytes 5-20

o  Encryption key server to client: bytes 8-23

o  Integrity key client to server: bytes 13-28

o  Integrity key server to client: bytes 16-31

Each key is at least 16 bytes (128 bits).  For some algorithms, only
part of this amount is actually used.  If a longer key is needed for
some algorithm, the key is extended by computing HASH of the entire key
so far, and appending the resulting bytes (as many as HASH outputs) to
the key.  This process is repeated until enough key material is
available.

6.3.  Taking Keys into Use

Key exchange ends by each side sending an SSH_MSG_NEWKEYS message.  This
message is sent with the old keys and algorithms.  All messages sent
after this message use the new keys and algorithms.

When this message is received, the new keys and algorithms are taken
into use for receiving.

This message is the only valid message after key exchange, in addition
to SSH_MSG_DISCONNECT and SSH_MSG_IGNORE messages.  The purpose of this


Tatu Ylonen <ylo@ssh.fi>                                       [page 14]

INTERNET-DRAFT                                         September 6, 1996
 
message is to ensure that a party is able to respond with a disconnect
message that the other party can understand if something goes wrong with
the key exchange.

            vlint32   SSH_MSG_NEWKEYS

7.  Key Re-Exchange

Either side may request re-exchange of keys at any time after the
initial exchange (and outside other key exchanges).  The re-exchange is
not visible to the service.

Key re-exchange is started by sending a SSH_MSG_KEXINIT packet
(described in Section ``Algorithm Negotiation'').  When this message is
received, a party must respond with its own SSH_MSG_KEXINIT message.
Either party may initiate the re-exchange, but roles are not changed
(i.e., the server remains the server, and the client remains the
client).

Key re-exchange is performed under whatever encryption was in effect
when the exchange was started.  Encryption, compression, and MAC methods
are changed when SSH_MSG_NEWKEYS is sent after the key exchange (as in
the initial key exchange).  Re-exchange is processed identically to the
initial key exchange.  It is permissible to change any or all of the
algorithms during the re-exchange.  Host keys can also change.  All keys
are recomputed after the exchange.  Compression and encryption contexts
are reset.  The packet sequence number is not reset.  The session
identifier is not recomputed.

It is recommended that keys be changed after each gigabyte of
transmitted data or after each hour of connection time, whichever comes
sooner.

It is also possible to use the key re-exchange mechanism to switch to
faster algorithms after authentication, or to avoid double processing
for pre-encrypted or pre-authenticated data.  However, since the re-
exchange is a public key operation, it requires a fair amount of
processing power and should not be performed too often.

8.  Service Request

After the various authentications, the client requests a service.  The
service is identified by a name.  Service names can contain any non-
control characters.  The name must not be longer than 64 characters.
Service names are case-sensitive.

            vlint32   SSH_MSG_SERVICE_REQUEST
            string    service name

Most server implementations will have a table of services that are
supported, specifying what to do for each service.

If the server rejects the service request, it should send a


Tatu Ylonen <ylo@ssh.fi>                                       [page 15]

INTERNET-DRAFT                                         September 6, 1996
 
SSH_MSG_DISCONNECT message.

When the service starts, it will have access to the session identifier
generated during key exchange.

If the server supports the service (and permits the client to use it),
it responds with

            vlint32   SSH_MSG_SERVICE_ACCEPT

The client is permitted to send further packets without waiting for the
this message; those packets will go to the selected service if the
server accepts the service request.  Message numbers used by services
should be in the area reserved for services (see Section ``Summary of
Message Numbers'').  The transport level will continue to process its
own messages.

9.  Stream-Based Services

It is expected that many services will actually be implemented by
applications that communicate with this protocol through pipes or some
other mechanism that passes a reliable stream of binary bytes.  For
those services, we define a protocol for passing data over this
protocol.  However, it is completely up to the particular service
whether it uses this protocol or something else.

Once a service has been selected, data is transmitted in each direction
asynchronously.  The data is packetized using the following format:

  vlint32   SSH_MSG_STREAM_DATA
  string    data

When the server or client application closes its output (i.e., will not
send more data), the following message is sent to the other side:

            vlint32   SSH_MSG_STREAM_EOF

No data can be sent after sending this message.  Data can still be
transmitted in the other direction.

When either party wishes to terminate communication, it sends
SSH_MSG_STREAM_CLOSE.  Upon receiving that message, a party should
immediately send back SSH_MSG_STREAM_CLOSE unless it has already sent
that.

            vlint32   SSH_MSG_STREAM_CLOSE

After both sending and receiving this message, the communications
channel should be closed.

10.  Additional Messages

Either party may send any of the following messages at any time.


Tatu Ylonen <ylo@ssh.fi>                                       [page 16]

INTERNET-DRAFT                                         September 6, 1996
 
10.1.  Disconnection Message

            vlint32   SSH_MSG_DISCONNECT
            vlint32   reason code
            string    description

This message causes immediate termination of the connection.  The
description field gives the reason for disconnecting in human-readable
form in English.  The error code gives the reason in a machine-readable
format (suitable for localization), and can have the following values:

          #define SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT      1
          #define SSH_DISCONNECT_PROTOCOL_ERROR                   2
          #define SSH_DISCONNECT_KEY_EXCHANGE_FAILED              3
          #define SSH_DISCONNECT_HOST_AUTHENTICATION_FAILED       4
          #define SSH_DISCONNECT_MAC_ERROR                        5
          #define SSH_DISCONNECT_COMPRESSION_ERROR                6
          #define SSH_DISCONNECT_SERVICE_NOT_AVAILABLE            7
          #define SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED   8
          #define SSH_DISCONNECT_SERVER_HOST_KEY_NOT_VERIFIABLE   9

10.2.  Ignored Data Message

            vlint32   SSH_MSG_IGNORE
            string    data

All implementations must understand (and ignore) this message at any
time (after receiving the protocol version).  No implementation is
required to ever send them.

10.3.  Reserved Messages

An implementation must respond to all unrecognized messages with an
SSH_MSG_UNIMPLEMENTED message in the order in which they were received.
Later protocol versions may define other meanings for these message
types.

            vlint32   SSH_MSG_UNIMPLEMENTED
            uint32    packet sequence number of rejected message

11.  Summary of Message Numbers

The following message numbers have been defined in this protocol.

#define SSH_MSG_DISCONNECT             1
#define SSH_MSG_IGNORE                 2
#define SSH_MSG_UNIMPLEMENTED          3
#define SSH_MSG_KEXINIT               10
#define SSH_MSG_NEWKEYS               11
#define SSH_MSG_SERVICE_REQUEST       12
#define SSH_MSG_SERVICE_ACCEPT        13

/* Numbers 20-29 for kex packets.


Tatu Ylonen <ylo@ssh.fi>                                       [page 17]

INTERNET-DRAFT                                         September 6, 1996
 
   Different kex methods may reuse message numbers in
   this range. */
#define SSH_MSG_KEXRSA_HOSTKEY        15
#define SSH_MSG_KEXRSA_SESSIONKEY     16

/* Numbers 30- are reserved for service types.
   Different service types may reuse the same messages.
   Messages for stream-based services.  Other service types
   may be defined in other documents. */
#define SSH_MSG_STREAM_DATA           40
#define SSH_MSG_STREAM_EOF            41
#define SSH_MSG_STREAM_CLOSE          42

12.  Public Keys and Public Key Infrastructure

This protocol is intentionally open on public key formats, as well as
signature and encryption formats.  There is currently no generally
accepted public key infrastructure on the Internet, there are several
competing key formats, and more formats are likely to appear.  It will
probably take several years until the situation is resolved.  In
particular, it is not clear that X.509 would be the solution, although
that is also a possibility.

There are several aspects to a public key type:

o  Key format: how is the key encoded, and how are certificates
   represented.  The key blobs in this protocol may (but are not
   required to) contain certificates in addition to keys.

o  Signature and/or encryption algorithms.  Some algorithms may not
   support both encryption and decryption.

o  Encoding for signatures and encrypted data.  This includes but is not
   limited to padding, byte order, and data formats.

The following public key formats are currently defined:

          ssh-simple-rsa          RSA with (mostly) PKCS-1 encodings

Note that the key type is negotiated at the beginning of the key
exchange, and is not included in the key blob itself.

12.1.  ssh-simple-rsa

This key type defines an RSA public key, with (mostly) PKCS compatible
signature and encryption formats.  It supports both signatures and
encryption.

Public keys of this type are represented as follows:

            byte[4]       0 (reserved)
            uint32        number of bits in the modulus
            uint16        number bits in the public exponent


Tatu Ylonen <ylo@ssh.fi>                                       [page 18]

INTERNET-DRAFT                                         September 6, 1996
 
            bytes[n]      exponent, MSB first, n = floor((bits+7)/8)
            uint16        number of bits in the modulus
            bytes[n]      modulus, MSB first, n = floor((bits+7)/8)

It is permissible that there be other data (e.g., certificates)
following this; however, such data is not yet defined.

Note that private key formats are not defined here, and are
implementation-specific.

An encrypted message is formed as follows.

o  The data to be encrypted is padded into a long integer of the same
   number of bits as the modulus as follows:

              MSB             .  .  .                LSB

               0   2   RND(n bytes)   0   encrypted_data

The RND bytes represent non-zero random bytes.

o  To encrypt, this integer is raised to the public exponent, modulo the
   modulus.

o  The result is converted to a byte string of floor((bits+7)/8) bytes
   (where bits is the number of bits in the modulus), MSB first.  This
   byte string (without any length or terminating characters) is the
   result of the encryption.

A signature is formed as follows.

o  The data to be signed (typically a message digest, but not required
   to be such) is padded into a long integer of the same number of bits
   as the modulus as follows:

              MSB             .  .  .             LSB

               0   1   RND(n bytes)   0   signed_data

The RND bytes represent non-zero random bytes.  Note that this differs
from the PKCS standard, where 0xFF bytes are specified for padding.

o  To sign, this integer is raised to the private exponent, modulo the
   modulus.

o  The result is converted to a byte string of floor((bits+7)/8) bytes
   (where bits is the number of bits in the modulus), MSB first.  This
   byte string (without any length or terminating characters) is the
   signature.  Applications may add other data outside this value.





Tatu Ylonen <ylo@ssh.fi>                                       [page 19]
---------- end of transport.txt ----------------

---------- cut here for userauth.txt -----------
Network Working Group                           Tatu Ylonen <ylo@ssh.fi>
INTERNET-DRAFT                               SSH Communications Security
userauth.txt                                           September 6, 1996
Expires: January 1st, 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 <ylo@ssh.fi>                                        [page 1]

INTERNET-DRAFT                                         September 6, 1996
 
Table of Contents

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . .  2
2.  User Authentication   . . . . . . . . . . . . . . . . . . . . . .  2
  2.1.  Starting Authentication   . . . . . . . . . . . . . . . . . .  3
  2.2.  Preauthentication Message   . . . . . . . . . . . . . . . . .  3
  2.3.  Responses to Authentication Requests  . . . . . . . . . . . .  4
  2.4.  Authentication Requests   . . . . . . . . . . . . . . . . . .  4
  2.5.  Password-Style Authentications  . . . . . . . . . . . . . . .  5
    2.5.1.  Password Authentication   . . . . . . . . . . . . . . . .  5
    2.5.2.  SecurID Authentication  . . . . . . . . . . . . . . . . .  5
  2.6.  One-Time Passwords and Similar Methods  . . . . . . . . . . .  5
    2.6.1.  S/KEY   . . . . . . . . . . . . . . . . . . . . . . . . .  6
    2.6.2.  NRL OPIE  . . . . . . . . . . . . . . . . . . . . . . . .  6
  2.7.  Other Authentication Methods  . . . . . . . . . . . . . . . .  6
    2.7.1.  Public Key Authentication   . . . . . . . . . . . . . . .  6
    2.7.2.  Host-Based Authentication   . . . . . . . . . . . . . . .  7
    2.7.3.  Kerberos Authentication   . . . . . . . . . . . . . . . .  8
3.  When Authentication Is Complete   . . . . . . . . . . . . . . . .  8
4.  Message Numbers   . . . . . . . . . . . . . . . . . . . . . . . .  8



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,
"footoken@footoken.com").  This ensures that private extensions can be
implemented without breaking compatibility and without requiring a


Tatu Ylonen <ylo@ssh.fi>                                        [page 2]

INTERNET-DRAFT                                         September 6, 1996
 
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:

password             Knowledge of password
securid              SecurID authentication
skey                 S/KEY one-time passwords
opie                 NRL OPIE one-time passwords
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

2.1.  Starting Authentication

User authentication starts by the client declaring the service and user
name it wishes to access.

            vlint32   SSH_MSG_USERAUTH_START
            string    service name
            string    user name

The server will reply to this message in the same way it responds to an
authentication request; however, the client may immediately continue
with authentication requests without waiting for the reply.

This must be the first message sent in user authentication.  The user
name or service cannot be changed after authentication has begun; the
only way to change them is to disconnect and open a new connection.

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.

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 times some authentication
methods (particularly password authentication) can be tried.

2.2.  Preauthentication Message

After receiving the SSH_MSG_USERAUTH_START message, the server may
optionally send a SSH_MSG_USERAUTH_BANNER message.  This message
contains a message to be displayed to the client user before attempting
authentication.  On most Unix machines, this message is read from


Tatu Ylonen <ylo@ssh.fi>                                        [page 3]

INTERNET-DRAFT                                         September 6, 1996
 
/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

2.3.  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 methods 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.4.  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    method name
            rest of the packet is method-specific

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


Tatu Ylonen <ylo@ssh.fi>                                        [page 4]

INTERNET-DRAFT                                         September 6, 1996
 
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.

2.5.  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    method name
            string    authenticating string

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

Implementations should limit the number of times password authentication
can be attempted, and disconnect after too many attempts have been made.
The recommended maximum number of attempts is five.

2.5.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.6.  One-Time Passwords and Similar Methods

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

            vlint32   SSH_MSG_USERAUTH_REQUEST
            string    method name

The server responds with either SSH_MSG_USERAUTH_FAILURE or



Tatu Ylonen <ylo@ssh.fi>                                        [page 5]

INTERNET-DRAFT                                         September 6, 1996
 
            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

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

2.6.1.  S/KEY

S/KEY is an early one-time password mechanism.  The method name is
"skey".

2.6.2.  NRL OPIE

NRL OPIE is another one-time password mechanism.  The method name for it
is "opie".

2.7.  Other Authentication Methods

2.7.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 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    "publickey"
            string    public key algorithm name
            string    public key to be used for authentication

Public key algorithms are defined in the transport layer specification.

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.

The client should then send a signature generated by the public key:

            vlint32   SSH_MSG_USERAUTH_PK_SIGNATURE
            string    signature

The public key may contain certificates.


Tatu Ylonen <ylo@ssh.fi>                                        [page 6]

INTERNET-DRAFT                                         September 6, 1996
 
Signature  is a signature by the corresponding private key of the HASH
of the concatenation of the requested service, the requested user, the
given public key, and the session identifier (which binds the signature
to the server host key and the particular key exchange).  All of these,
except the session identifier are represented as strings: there is first
a vlint32 length, and then the characters of the string.

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.7.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    "hostbased"
            string    client host name
            string    public key algorithm
            string    public host key for client host
            string    client user name
            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 requested service, the requested user, the client host name, the
public host key of the client, the client user name, and the session
identifier (which binds the signature to the server host key and the
particular key exchange).  All of these, except the session identifier,
are represented as strings for hashing: vlint32 length and then the
bytes of the string.

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 perform additional
checks the verify that the network address obtained from the (untrusted)
network matches the given client host name.  This makes exploiting


Tatu Ylonen <ylo@ssh.fi>                                        [page 7]

INTERNET-DRAFT                                         September 6, 1996
 
compromised host keys more difficult.

2.7.3.  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   SSH_MSG_USERAUTH_REQUEST
            string    "kerberos4"
            string    kerberos v4 credentials

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

            vlint32   SSH_MSG_USERAUTH_REQUEST
            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 authentication 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.  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


Tatu Ylonen <ylo@ssh.fi>                                        [page 8]

INTERNET-DRAFT                                         September 6, 1996
 
understand.

          #define SSH_MSG_USERAUTH_START          30
          #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
          #define SSH_MSG_USERAUTH_PK_SIGNATURE   36
          /* One-time passwords */
          #define SSH_MSG_USERAUTH_OTP_PROMPT     35
          #define SSH_MSG_USERAUTH_OTP_RESPONSE   36





































Tatu Ylonen <ylo@ssh.fi>                                        [page 9]
----------- end of userauth.txt ------------
Received on Thursday, 26 September 1996 12:48:04 EDT

This archive was generated by hypermail pre-2.1.9 : Wednesday, 24 September 2003 06:34:51 EDT