rfc.nroff

OpenSSL Source code for SFTP, SSH, and many others

example, the value 0x00012345 would have 17 bits).  The value zero has
zero bits.  It is permissible that the number of bits be larger than the
real number of bits.

The number of bits is followed by (bits + 7) / 8 bytes of binary data,
msb first, giving the value of the integer.
.RT


.ti 0
TCP/IP Port Number and Other Options

The server listens for connections on TCP/IP port 22.

The client may connect the server from any port.  However, if the
client wishes to use any form of .rhosts or /etc/hosts.equiv
authentication, it must connect from a privileged port (less than
1024).

For the IP Type of Service field [RFC0791], it is recommended that
interactive sessions (those having a user terminal or forwarding X11
connections) use the IPTOS_LOWDELAY, and non-interactive connections
use IPTOS_THROUGHPUT.

It is recommended that keepalives are used, because otherwise programs
on the server may never notice if the other end of the connection is
rebooted.


.ti 0
Protocol Version Identification

After the socket is opened, the server sends an identification string,
which is of the form
"SSH-<protocolmajor>.<protocolminor>-<version>\\n", where
<protocolmajor> and <protocolminor> are integers and specify the
protocol version number (not software distribution version).
<version> is server side software version string (max 40 characters);
it is not interpreted by the remote side but may be useful for
debugging.

The client parses the server's string, and sends a corresponding
string with its own information in response.  If the server has lower
version number, and the client contains special code to emulate it,
the client responds with the lower number; otherwise it responds with
its own number.  The server then compares the version number the
client sent with its own, and determines whether they can work
together.  The server either disconnects, or sends the first packet
using the binary packet protocol and both sides start working
according to the lower of the protocol versions.

By convention, changes which keep the protocol compatible with
previous versions keep the same major protocol version; changes that
are not compatible increment the major version (which will hopefully
never happen).  The version described in this document is 1.3.

The client will 

.ti 0
Key Exchange and Server Host Authentication

The first message sent by the server using the packet protocol is
SSH_SMSG_PUBLIC_KEY.  It declares the server's host key, server public
key, supported ciphers, supported authentication methods, and flags
for protocol extensions.  It also contains a 64-bit random number
(cookie) that must be returned in the client's reply (to make IP
spoofing more difficult).  No encryption is used for this message.

Both sides compute a session id as follows.  The modulus of the server
key is interpreted as a byte string (without explicit length field,
with minimum length able to hold the whole value), most significant
byte first.  This string is concatenated with the server host key
interpreted the same way.  Additionally, the cookie is concatenated
with this.  Both sides compute MD5 of the resulting string.  The
resulting 16 bytes (128 bits) are stored by both parties and are
called the session id.

The client responds with a SSH_CMSG_SESSION_KEY message, which
contains the selected cipher type, a copy of the 64-bit cookie sent by
the server, client's protocol flags, and a session key encrypted
with both the server's host key and server key.  No encryption is used
for this message.

The session key is 32 8-bit bytes (a total of 256 random bits
generated by the client).  The client first xors the 16 bytes of the
session id with the first 16 bytes of the session key.  The resulting
string is then encrypted using the smaller key (one with smaller
modulus), and the result is then encrypted using the other key.  The
number of bits in the public modulus of the two keys must differ by at
least 128 bits.

At each encryption step, a multiple-precision integer is constructed
from the data to be encrypted as follows (the integer is here
interpreted as a sequence of bytes, msb first; the number of bytes is
the number of bytes needed to represent the modulus).

The most significant byte (which is only partial as the value must be
less than the public modulus, which is never a power of two) is zero.

The next byte contains the value 2 (which stands for public-key
encrypted data in the PKCS standard [PKCS#1]).  Then, there are
non-zero random bytes to fill any unused space, a zero byte, and the
data to be encrypted in the least significant bytes, the last byte of
the data in the least significant byte.

This algorithm is used twice.  First, it is used to encrypt the 32
random bytes generated by the client to be used as the session key
(xored by the session id).  This value is converted to an integer as
described above, and encrypted with RSA using the key with the smaller
modulus.  The resulting integer is converted to a byte stream, msb
first.  This byte stream is padded and encrypted identically using the
key with the larger modulus.

After the client has sent the session key, it starts to use the
selected algorithm and key for decrypting any received packets, and
for encrypting any sent packets.  Separate ciphers are used for
different directions (that is, both directions have separate
initialization vectors or other state for the ciphers).

When the server has received the session key message, and has turned
on encryption, it sends a SSH_SMSG_SUCCESS message to the client.

The recommended size of the host key is 1024 bits, and 768 bits for
the server key.  The minimum size is 512 bits for the smaller key.


.ti 0
Declaring the User Name

The client then sends a SSH_CMSG_USER message to the server.  This
message specifies the user name to log in as.

The server validates that such a user exists, checks whether
authentication is needed, and responds with either SSH_SMSG_SUCCESS or
SSH_SMSG_FAILURE.  SSH_SMSG_SUCCESS indicates that no authentication
is needed for this user (no password), and authentication phase has
now been completed.  SSH_SMSG_FAILURE indicates that authentication is
needed (or the user does not exist).

If the user does not exist, it is recommended that this returns
failure, but the server keeps reading messages from the client, and
responds to any messages (except SSH_MSG_DISCONNECT, SSH_MSG_IGNORE,
and SSH_MSG_DEBUG) with SSH_SMSG_FAILURE.  This way the client cannot
be certain whether the user exists.


.ti 0
Authentication Phase

Provided the server didn't immediately accept the login, an
authentication exchange begins.  The client sends messages to the
server requesting different types of authentication in arbitrary order as
many times as desired (however, the server may close the connection
after a timeout).  The server always responds with SSH_SMSG_SUCCESS if
it has accepted the authentication, and with SSH_SMSG_FAILURE if it has
denied authentication with the requested method or it does not
recognize the message.  Some authentication methods cause an exchange
of further messages before the final result is sent.  The
authentication phase ends when the server responds with success.

The recommended value for the authentication timeout (timeout before
disconnecting if no successful authentication has been made) is 5
minutes.

The following authentication methods are currently supported:
.TS
center;
l r l.
SSH_AUTH_RHOSTS	1	.rhosts or /etc/hosts.equiv
SSH_AUTH_RSA	2	pure RSA authentication
SSH_AUTH_PASSWORD	3	password authentication
SSH_AUTH_RHOSTS_RSA	4	.rhosts with RSA host authentication
.TE
.IP SSH_AUTH_RHOSTS

This is the authentication method used by rlogin and rsh [RFC1282].

The client sends SSH_CMSG_AUTH_RHOSTS with the client-side user name
as an argument.

The server checks whether to permit authentication.  On UNIX systems,
this is usually done by checking /etc/hosts.equiv, and .rhosts in the
user's home directory.  The connection must come from a privileged
port.

It is recommended that the server checks that there are no IP options
(such as source routing) specified for the socket before accepting
this type of authentication.  The client host name should be
reverse-mapped and then forward mapped to ensure that it has the
proper IP-address.

This authentication method trusts the remote host (root on the remote
host can pretend to be any other user on that host), the name
services, and partially the network: anyone who can see packets coming
out from the server machine can do IP-spoofing and pretend to be any
machine; however, the protocol prevents blind IP-spoofing (which used
to be possible with rlogin).

Many sites probably want to disable this authentication method because
of the fundamental insecurity of conventional .rhosts or
/etc/hosts.equiv authentication when faced with spoofing.  It is
recommended that this method not be supported by the server by
default.
.IP SSH_AUTH_RHOSTS_RSA

In addition to conventional .rhosts and hosts.equiv authentication,
this method additionally requires that the client host be
authenticated using RSA.

The client sends SSH_CMSG_AUTH_RHOSTS_RSA specifying the client-side
user name, and the public host key of the client host.

The server first checks if normal .rhosts or /etc/hosts.equiv
authentication would be accepted, and if not, responds with
SSH_SMSG_FAILURE.  Otherwise, it checks whether it knows the host key
for the client machine (using the same name for the host that was used
for checking the .rhosts and /etc/hosts.equiv files).  If it does not
know the RSA key for the client, access is denied and SSH_SMSG_FAILURE
is sent.

If the server knows the host key of the client machine, it verifies
that the given host key matches that known for the client.  If not,
access is denied and SSH_SMSG_FAILURE is sent.

The server then sends a SSH_SMSG_AUTH_RSA_CHALLENGE message containing
an encrypted challenge for the client.  The challenge is 32 8-bit
random bytes (256 bits).  When encrypted, the highest (partial) byte
is left as zero, the next byte contains the value 2, the following are
non-zero random bytes, followed by a zero byte, and the challenge put
in the remaining bytes.  This is then encrypted using RSA with the
client host's public key.  (The padding and encryption algorithm is
the same as that used for the session key.)

The client decrypts the challenge using its private host key,
concatenates this with the session id, and computes an MD5 checksum
of the resulting 48 bytes.  The MD5 output is returned as 16 bytes in
a SSH_CMSG_AUTH_RSA_RESPONSE message.  (MD5 is used to deter chosen
plaintext attacks against RSA; the session id binds it to a specific
session).

The server verifies that the MD5 of the decrypted challenge returned by
the client matches that of the original value, and sends SSH_SMSG_SUCCESS if
so.  Otherwise it sends SSH_SMSG_FAILURE and refuses the
authentication attempt.

This authentication method trusts the client side machine in that root
on that machine can pretend to be any user on that machine.
Additionally, it trusts the client host key.  The name and/or IP
address of the client host is only used to select the public host key.
The same host name is used when scanning .rhosts or /etc/hosts.equiv
and when selecting the host key.  It would in principle be possible to
eliminate the host name entirely and substitute it directly by the
host key.  IP and/or DNS [RFC1034] spoofing can only be used
to pretend to be a host for which the attacker has the private host
key.
.IP SSH_AUTH_RSA

The idea behind RSA authentication is that the server recognizes the
public key offered by the client, generates a random challenge, and
encrypts the challenge with the public key.  The client must then
prove that it has the corresponding private key by decrypting the
challenge.

The client sends SSH_CMSG_AUTH_RSA with public key modulus (n) as an
argument.

The server may respond immediately with SSH_SMSG_FAILURE if it does
not permit authentication with this key.  Otherwise it generates a
challenge, encrypts it using the user's public key (stored on the
server and identified using the modulus), and sends
SSH_SMSG_AUTH_RSA_CHALLENGE with the challenge (mp-int) as an
argument.

The challenge is 32 8-bit random bytes (256 bits).  When encrypted,
the highest (partial) byte is left as zero, the next byte contains the
value 2, the following are non-zero random bytes, followed by a zero
byte, and the challenge put in the remaining bytes.  This is then
encrypted with the public key.  (The padding and encryption algorithm
is the same as that used for the session key.)

The client decrypts the challenge using its private key, concatenates
it with the session id, and computes an MD5 checksum of the resulting
48 bytes.  The MD5 output is returned as 16 bytes in a
SSH_CMSG_AUTH_RSA_RESPONSE message.  (Note that the MD5 is necessary
to avoid chosen plaintext attacks against RSA; the session id binds it
to a specific session.)

The server verifies that the MD5 of the decrypted challenge returned
by the client matches that of the original value, and sends
SSH_SMSG_SUCCESS if so.  Otherwise it sends SSH_SMSG_FAILURE and
refuses the authentication attempt.

This authentication method does not trust the remote host, the
network, name services, or anything else.  Authentication is based
solely on the possession of the private identification keys.  Anyone
in possession of the private keys can log in, but nobody else.

The server may have additional requirements for a successful
authentiation.  For example, to limit damage due to a compromised RSA
key, a server might restrict access to a limited set of hosts.
.IP SSH_AUTH_PASSWORD

The client sends a SSH_CMSG_AUTH_PASSWORD message with the plain text
password.  (Note that even though the password is plain text inside
the message, it is normally encrypted by the packet mechanism.)

The server verifies the password, and sends SSH_SMSG_SUCCESS if
authentication was accepted and SSH_SMSG_FAILURE otherwise.

Note that the password is read from the user by the client; the user
never interacts with a login program.

This authentication method does not trust the remote host, the
network, name services or anything else.  Authentication is based
solely on the possession of the password.  Anyone in possession of the
password can log in, but nobody else.
.RT