rfc.nroff

OpenSSL Source code for SFTP, SSH, and many others

.ti 0
Preparatory Operations

After successful authentication, the server waits for a request from
the client, processes the request, and responds with SSH_SMSG_SUCCESS
whenever a request has been successfully processed.  If it receives a
message that it does not recognize or it fails to honor a request, it
returns SSH_SMSG_FAILURE.  It is expected that new message types might
be added to this phase in future.

The following messages are currently defined for this phase.
.IP SSH_CMSG_REQUEST_COMPRESSION
Requests that compression be enabled for this session.  A
gzip-compatible compression level (1-9) is passed as an argument.
.IP SSH_CMSG_REQUEST_PTY
Requests that a pseudo terminal device be allocated for this session.
The user terminal type and terminal modes are supplied as arguments.
.IP SSH_CMSG_X11_REQUEST_FORWARDING
Requests forwarding of X11 connections from the remote machine to the
local machine over the secure channel.  Causes an internet-domain
socket to be allocated and the DISPLAY variable to be set on the server.
X11 authentication data is automatically passed to the server, and the
client may implement spoofing of authentication data for added
security.  The authentication data is passed as arguments.
.IP SSH_CMSG_PORT_FORWARD_REQUEST
Requests forwarding of a TCP/IP port on the server host over the
secure channel.  What happens is that whenever a connection is made to
the port on the server, a connection will be made from the client end
to the specified host/port.  Any user can forward unprivileged ports;
only the root can forward privileged ports (as determined by
authentication done earlier).
.IP SSH_CMSG_AGENT_REQUEST_FORWARDING
Requests forwarding of the connection to the authentication agent.
.IP SSH_CMSG_EXEC_SHELL
Starts a shell (command interpreter) for the user, and moves into
interactive session mode.
.IP SSH_CMSG_EXEC_CMD
Executes the given command (actually "<shell> -c <command>" or
equivalent) for the user, and moves into interactive session mode.
.RT


.ti 0
Interactive Session and Exchange of Data

During the interactive session, any data written by the shell or
command running on the server machine is forwarded to stdin or
stderr on the client machine, and any input available from stdin on
the client machine is forwarded to the program on the server machine.

All exchange is asynchronous; either side can send at any time, and
there are no acknowledgements (TCP/IP already provides reliable
transport, and the packet protocol protects against tampering or IP
spoofing).

When the client receives EOF from its standard input, it will send
SSH_CMSG_EOF; however, this in no way terminates the exchange.  The
exchange terminates and interactive mode is left when the server sends
SSH_SMSG_EXITSTATUS to indicate that the client program has
terminated.  Alternatively, either side may disconnect at any time by
sending SSH_MSG_DISCONNECT or closing the connection.

The server may send any of the following messages:
.IP SSH_SMSG_STDOUT_DATA
Data written to stdout by the program running on the server.  The data
is passed as a string argument.  The client writes this data to
stdout.
.IP SSH_SMSG_STDERR_DATA
Data written to stderr by the program running on the server.  The data
is passed as a string argument.  The client writes this data to
stderr.  (Note that if the program is running on a tty, it is not
possible to separate stdout and stderr data, and all data will be sent
as stdout data.)
.IP SSH_SMSG_EXITSTATUS
Indicates that the shell or command has exited.  Exit status is passed
as an integer argument.  This message causes termination of the
interactive session.
.IP SSH_SMSG_AGENT_OPEN
Indicates that someone on the server side is requesting a connection
to the authentication agent.  The server-side channel number is passed
as an argument.  The client must respond with either
SSH_CHANNEL_OPEN_CONFIRMATION or SSH_CHANNEL_OPEN_FAILURE.
.IP SSH_SMSG_X11_OPEN
Indicates that a connection has been made to the X11 socket on the
server side and should be forwarded to the real X server.  An integer
argument indicates the channel number allocated for this connection on
the server side.  The client should send back either
SSH_MSG_CHANNEL_OPEN_CONFIRMATION or SSH_MSG_CHANNEL_OPEN_FAILURE with
the same server side channel number.
.IP SSH_MSG_PORT_OPEN
Indicates that a connection has been made to a port on the server side
for which forwarding has been requested.  Arguments are server side
channel number, host name to connect to, and port to connect to.  The
client should send back either
SSH_MSG_CHANNEL_OPEN_CONFIRMATION or SSH_MSG_CHANNEL_OPEN_FAILURE with
the same server side channel number.
.IP SSH_MSG_CHANNEL_OPEN_CONFIRMATION
This is sent by the server to indicate that it has opened a connection
as requested in a previous message.  The first argument indicates the
client side channel number, and the second argument is the channel number
that the server has allocated for this connection.
.IP SSH_MSG_CHANNEL_OPEN_FAILURE
This is sent by the server to indicate that it failed to open a
connection as requested in a previous message.  The client-side
channel number is passed as an argument.  The client will close the
descriptor associated with the channel and free the channel.
.IP SSH_MSG_CHANNEL_DATA
This packet contains data for a channel from the server.  The first
argument is the client-side channel number, and the second argument (a
string) is the data.
.IP SSH_MSG_CHANNEL_CLOSE
This is sent by the server to indicate that whoever was in the other
end of the channel has closed it.  The argument is the client side channel
number.  The client will let all buffered data in the channel to
drain, and when ready, will close the socket, free the channel, and
send the server a SSH_MSG_CHANNEL_CLOSE_CONFIRMATION message for the
channel.
.IP SSH_MSG_CHANNEL_CLOSE_CONFIRMATION
This is send by the server to indicate that a channel previously
closed by the client has now been closed on the server side as well.
The argument indicates the client channel number.  The client frees
the channel.
.RT

The client may send any of the following messages:
.IP SSH_CMSG_STDIN_DATA
This is data to be sent as input to the program running on the server.
The data is passed as a string.
.IP SSH_CMSG_EOF
Indicates that the client has encountered EOF while reading standard
input.  The server will allow any buffered input data to drain, and
will then close the input to the program.
.IP SSH_CMSG_WINDOW_SIZE
Indicates that window size on the client has been changed.  The server
updates the window size of the tty and causes SIGWINCH to be sent to
the program.  The new window size is passed as four integer arguments:
row, col, xpixel, ypixel.
.IP SSH_MSG_PORT_OPEN
Indicates that a connection has been made to a port on the client side
for which forwarding has been requested.  Arguments are client side
channel number, host name to connect to, and port to connect to.  The
server should send back either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or
SSH_MSG_CHANNEL_OPEN_FAILURE with the same client side channel number.
.IP SSH_MSG_CHANNEL_OPEN_CONFIRMATION
This is sent by the client to indicate that it has opened a connection
as requested in a previous message.  The first argument indicates the
server side channel number, and the second argument is the channel
number that the client has allocated for this connection.
.IP SSH_MSG_CHANNEL_OPEN_FAILURE
This is sent by the client to indicate that it failed to open a
connection as requested in a previous message.  The server side
channel number is passed as an argument.  The server will close the
descriptor associated with the channel and free the channel.
.IP SSH_MSG_CHANNEL_DATA
This packet contains data for a channel from the client.  The first
argument is the server side channel number, and the second argument (a
string) is the data.
.IP SSH_MSG_CHANNEL_CLOSE
This is sent by the client to indicate that whoever was in the other
end of the channel has closed it.  The argument is the server channel
number.  The server will allow buffered data to drain, and when ready,
will close the socket, free the channel, and send the client a
SSH_MSG_CHANNEL_CLOSE_CONFIRMATION message for the channel.
.IP SSH_MSG_CHANNEL_CLOSE_CONFIRMATION
This is send by the client to indicate that a channel previously
closed by the server has now been closed on the client side as well.
The argument indicates the server channel number.  The server frees
the channel.
.RT

Any unsupported messages during interactive mode cause the connection
to be terminated with SSH_MSG_DISCONNECT and an error message.
Compatible protocol upgrades should agree about any extensions during
the preparation phase or earlier.


.ti 0
Termination of the Connection

Normal termination of the connection is always initiated by the server
by sending SSH_SMSG_EXITSTATUS after the program has exited.  The
client responds to this message by sending SSH_CMSG_EXIT_CONFIRMATION
and closes the socket; the server then closes the socket.  There are
two purposes for the confirmation: some systems may lose previously
sent data when the socket is closed, and closing the client side first
causes any TCP/IP TIME_WAIT [RFC0793] waits to occur on the client side, not
consuming server resources.

If the program terminates due to a signal, the server will send
SSH_MSG_DISCONNECT with an appropriate message.  If the connection is
closed, all file descriptors to the program will be closed and the
server will exit.  If the program runs on a tty, the kernel sends it
the SIGHUP signal when the pty master side is closed.

.ti 0
Protocol Flags

Both the server and the client pass 32 bits of protocol flags to the
other side.  The flags are intended for compatible protocol extension;
the server first announces which added capabilities it supports, and
the client then sends the capabilities that it supports.

The following flags are currently defined (the values are bit masks):
.IP "1 SSH_PROTOFLAG_SCREEN_NUMBER"
This flag can only be sent by the client.  It indicates that the X11
forwarding requests it sends will include the screen number.
.IP "2 SSH_PROTOFLAG_HOST_IN_FWD_OPEN"
If both sides specify this flag, SSH_SMSG_X11_OPEN and
SSH_MSG_PORT_OPEN messages will contain an additional field containing
a description of the host at the other end of the connection.
.RT

.ti 0
Detailed Description of Packet Types and Formats

The supported packet types and the corresponding message numbers are
given in the following table.  Messages with _MSG_ in their name may
be sent by either side.  Messages with _CMSG_ are only sent by the
client, and messages with _SMSG_ only by the server.

A packet may contain additional data after the arguments specified
below.  Any such data should be ignored by the receiver.  However, it
is recommended that no such data be stored without good reason.  (This
helps build compatible extensions.)
.IP "0 SSH_MSG_NONE"
This code is reserved.  This message type is never sent.
.IP "1 SSH_MSG_DISCONNECT"
.TS
;
l l.
string	Cause of disconnection
.TE
This message may be sent by either party at any time.  It causes the
immediate disconnection of the connection.  The message is intended to
be displayed to a human, and describes the reason for disconnection.
.IP "2 SSH_SMSG_PUBLIC_KEY"
.TS
;
l l.
8 bytes	anti_spoofing_cookie
32-bit int	server_key_bits
mp-int	server_key_public_exponent
mp-int	server_key_public_modulus
32-bit int	host_key_bits
mp-int	host_key_public_exponent
mp-int	host_key_public_modulus
32-bit int	protocol_flags
32-bit int	supported_ciphers_mask
32-bit int	supported_authentications_mask
.TE
Sent as the first message by the server.  This message gives the
server's host key, server key, protocol flags (intended for compatible
protocol extension), supported_ciphers_mask (which is the
bitwise or of (1 << cipher_number), where << is the left shift
operator, for all supported ciphers), and
supported_authentications_mask (which is the bitwise or of (1 <<
authentication_type) for all supported authentication types).  The
anti_spoofing_cookie is 64 random bytes, and must be sent back
verbatim by the client in its reply.  It is used to make IP-spoofing
more difficult (encryption and host keys are the real defense against
spoofing).
.IP "3 SSH_CMSG_SESSION_KEY"
.TS
;
l l.
1 byte	cipher_type (must be one of the supported values)
8 bytes	anti_spoofing_cookie (must match data sent by the server)
mp-int	double-encrypted session key
32-bit int	protocol_flags
.TE
Sent by the client as the first message in the session.  Selects the
cipher to use, and sends the encrypted session key to the server.  The
anti_spoofing_cookie must be the same bytes that were sent by the
server.  Protocol_flags is intended for negotiating compatible
protocol extensions.
.IP "4 SSH_CMSG_USER"
.TS
;
l l.
string	user login name on server
.TE
Sent by the client to begin authentication.  Specifies the user name
on the server to log in as.  The server responds with SSH_SMSG_SUCCESS
if no authentication is needed for this user, or SSH_SMSG_FAILURE if
authentication is needed (or the user does not exist).  [Note to the
implementator: the user name is of arbitrary size.  The implementation
must be careful not to overflow internal buffers.]
.IP "5 SSH_CMSG_AUTH_RHOSTS"
.TS
;
l l.
string	client-side user name
.TE
Requests authentication using /etc/hosts.equiv and .rhosts (or
equivalent mechanisms).  This authentication method is normally
disabled in the server because it is not secure (but this is the
method used by rsh and rlogin).  The server responds with
SSH_SMSG_SUCCESS if authentication was successful, and
SSH_SMSG_FAILURE if access was not granted.  The server should check
that the client side port number is less than 1024 (a privileged
port), and immediately reject authentication if it is not.  Supporting
this authentication method is optional.  This method should normally
not be enabled in the server because it is not safe.  (However, not
enabling this only helps if rlogind and rshd are disabled.)
.IP "6 SSH_CMSG_AUTH_RSA"
.TS
;
l l.
mp-int	identity_public_modulus
.TE
Requests authentication using pure RSA authentication.  The server
checks if the given key is permitted to log in, and if so, responds
with SSH_SMSG_AUTH_RSA_CHALLENGE.  Otherwise, it responds with
SSH_SMSG_FAILURE.  The client often tries several different keys in
sequence until one supported by the server is found.  Authentication
is accepted if the client gives the correct response to the challenge.
The server is free to add other criteria for authentication, such as a
requirement that the connection must come from a certain host.  Such