Request for Comments: 4254 SSH Communications Security Corp
Category: Standards Track C. Lonvick, Ed.
Cisco Systems, Inc.
January 2006
The Secure Shell (SSH) Connection Protocol
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
Secure Shell (SSH) is a protocol for secure remote login and other
secure network services over an insecure network.
This document describes the SSH Connection Protocol. It provides
interactive login sessions, remote execution of commands, forwarded
TCP/IP connections, and forwarded X11 connections. All of these
channels are multiplexed into a single encrypted tunnel.
The SSH Connection Protocol has been designed to run on top of the
SSH transport layer and user authentication protocols.
Table of Contents
1. Introduction ....................................................2
2. Contributors ....................................................3
3. Conventions Used in This Document ...............................3
4. Global Requests .................................................4
5. Channel Mechanism ...............................................5
5.1. Opening a Channel ..........................................5
5.2. Data Transfer ..............................................7
5.3. Closing a Channel ..........................................9
5.4. Channel-Specific Requests ..................................9
6. Interactive Sessions ...........................................10
6.1. Opening a Session .........................................10
6.2. Requesting a Pseudo-Terminal ..............................11
6.3. X11 Forwarding ............................................11
6.3.1. Requesting X11 Forwarding ..........................11
6.3.2. X11 Channels .......................................12
6.4. Environment Variable Passing ..............................12
6.5. Starting a Shell or a Command .............................13
6.6. Session Data Transfer .....................................14
6.7. Window Dimension Change Message ...........................14
6.8. Local Flow Control ........................................14
6.9. Signals ...................................................15
6.10. Returning Exit Status ....................................15
7. TCP/IP Port Forwarding .........................................16
7.1. Requesting Port Forwarding ................................16
7.2. TCP/IP Forwarding Channels ................................18
8. Encoding of Terminal Modes .....................................19
9. Summary of Message Numbers .....................................21
10. IANA Considerations ...........................................21
11. Security Considerations .......................................21
12. References ....................................................22
12.1. Normative References .....................................22
12.2. Informative References ...................................22
Authors’ Addresses ................................................23
Trademark Notice ..................................................23
1. Introduction
The SSH Connection Protocol has been designed to run on top of the
SSH transport layer and user authentication protocols ([SSH-TRANS]
and [SSH-USERAUTH]). It provides interactive login sessions, remote
execution of commands, forwarded TCP/IP connections, and forwarded
X11 connections.
The ’service name’ for this protocol is "ssh-connection".
This document should be read only after reading the SSH architecture
document [SSH-ARCH]. This document freely uses terminology and
notation from the architecture document without reference or further
explanation.
2. Contributors
The major original contributors of this set of documents have been:
Tatu Ylonen, Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH
Communications Security Corp), and Markku-Juhani O. Saarinen
(University of Jyvaskyla). Darren Moffat was the original editor of
this set of documents and also made very substantial contributions.
Many people contributed to the development of this document over the
years. People who should be acknowledged include Mats Andersson, Ben
Harris, Bill Sommerfeld, Brent McClure, Niels Moller, Damien Miller,
Derek Fawcus, Frank Cusack, Heikki Nousiainen, Jakob Schlyter, Jeff
Van Dyke, Jeffrey Altman, Jeffrey Hutzelman, Jon Bright, Joseph
Galbraith, Ken Hornstein, Markus Friedl, Martin Forssen, Nicolas
Williams, Niels Provos, Perry Metzger, Peter Gutmann, Simon
Josefsson, Simon Tatham, Wei Dai, Denis Bider, der Mouse, and
Tadayoshi Kohno. Listing their names here does not mean that they
endorse this document, but that they have contributed to it.
3. Conventions Used in This Document
All documents related to the SSH protocols shall use the keywords
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe
requirements. These keywords are to be interpreted as described in
[RFC2119].
The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME
FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG
APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in
this document when used to describe namespace allocation are to be
interpreted as described in [RFC2434].
Protocol fields and possible values to fill them are defined in this
set of documents. Protocol fields will be defined in the message
definitions. As an example, SSH_MSG_CHANNEL_DATA is defined as
follows.
byte SSH_MSG_CHANNEL_DATA
uint32 recipient channel
string data
Throughout these documents, when the fields are referenced, they will
appear within single quotes. When values to fill those fields are
referenced, they will appear within double quotes. Using the above
example, possible values for ’data’ are "foo" and "bar".
4. Global Requests
There are several kinds of requests that affect the state of the
remote end globally, independent of any channels. An example is a
request to start TCP/IP forwarding for a specific port. Note that
both the client and server MAY send global requests at any time, and
the receiver MUST respond appropriately. All such requests use the
following format.
byte SSH_MSG_GLOBAL_REQUEST
string request name in US-ASCII only
boolean want reply
.... request-specific data follows
The value of ’request name’ follows the DNS extensibility naming
convention outlined in [SSH-ARCH].
The recipient will respond to this message with
SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if ’want reply’ is
TRUE.
byte SSH_MSG_REQUEST_SUCCESS
.... response specific data
Usually, the ’response specific data’ is non-existent.
If the recipient does not recognize or support the request, it simply
responds with SSH_MSG_REQUEST_FAILURE.
byte SSH_MSG_REQUEST_FAILURE
In general, the reply messages do not include request type
identifiers. To make it possible for the originator of a request to
identify to which request each reply refers, it is REQUIRED that
replies to SSH_MSG_GLOBAL_REQUESTS MUST be sent in the same order as
the corresponding request messages. For channel requests, replies
that relate to the same channel MUST also be replied to in the right
order. However, channel requests for distinct channels MAY be
replied to out-of-order.
5. Channel Mechanism
All terminal sessions, forwarded connections, etc., are channels.
Either side may open a channel. Multiple channels are multiplexed
into a single connection.
Channels are identified by numbers at each end. The number referring
to a channel may be different on each side. Requests to open a
channel contain the sender’s channel number. Any other channel-
related messages contain the recipient’s channel number for the
channel.
Channels are flow-controlled. No data may be sent to a channel until
a message is received to indicate that window space is available.
5.1. Opening a Channel
When either side wishes to open a new channel, it allocates a local
number for the channel. It then sends the following message to the
other side, and includes the local channel number and initial window
size in the message.
byte SSH_MSG_CHANNEL_OPEN
string channel type in US-ASCII only
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
.... channel type specific data follows
The ’channel type’ is a name, as described in [SSH-ARCH] and
[SSH-NUMBERS], with similar extension mechanisms. The ’sender
channel’ is a local identifier for the channel used by the sender of
this message. The ’initial window size’ specifies how many bytes of
channel data can be sent to the sender of this message without
adjusting the window. The ’maximum packet size’ specifies the
maximum size of an individual data packet that can be sent to the
sender. For example, one might want to use smaller packets for
interactive connections to get better interactive response on slow
links.
The remote side then decides whether it can open the channel, and
responds with either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or
SSH_MSG_CHANNEL_OPEN_FAILURE.
byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION
uint32 recipient channel
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
.... channel type specific data follows
The ’recipient channel’ is the channel number given in the original
open request, and ’sender channel’ is the channel number allocated by
the other side.
byte SSH_MSG_CHANNEL_OPEN_FAILURE
uint32 recipient channel
uint32 reason code
string description in ISO-10646 UTF-8 encoding [RFC3629]
string language tag [RFC3066]
If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support
the specified ’channel type’, it simply responds with
SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the ’description’
string to the user. If this is done, the client software should take
the precautions discussed in [SSH-ARCH].
The SSH_MSG_CHANNEL_OPEN_FAILURE ’reason code’ values are defined in
the following table. Note that the values for the ’reason code’ are
given in decimal format for readability, but they are actually uint32
values.
Symbolic name reason code
------------- -----------
SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1
SSH_OPEN_CONNECT_FAILED 2
SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3
SSH_OPEN_RESOURCE_SHORTAGE 4
Requests for assignments of new SSH_MSG_CHANNEL_OPEN ’reason code’
values (and associated ’description’ text) in the range of 0x00000005
to 0xFDFFFFFF MUST be done through the IETF CONSENSUS method, as
described in [RFC2434]. The IANA will not assign Channel Connection
Failure ’reason code’ values in the range of 0xFE000000 to
0xFFFFFFFF. Channel Connection Failure ’reason code’ values in that
range are left for PRIVATE USE, as described in [RFC2434].
While it is understood that the IANA will have no control over the
range of 0xFE000000 to 0xFFFFFFFF, this range will be split in two
parts and administered by the following conventions.
o The range of 0xFE000000 to 0xFEFFFFFF is to be used in conjunction
with locally assigned channels. For example, if a channel is
proposed with a ’channel type’ of "example_session@example.com",
but fails, then the response will contain either a ’reason code’
assigned by the IANA (as listed above and in the range of
0x00000001 to 0xFDFFFFFF) or a locally assigned value in the range
of 0xFE000000 to 0xFEFFFFFF. Naturally, if the server does not
understand the proposed ’channel type’, even if it is a locally
defined ’channel type’, then the ’reason code’ MUST be 0x00000003,
as described above, if the ’reason code’ is sent. If the server
does understand the ’channel type’, but the channel still fails to
open, then the server SHOULD respond with a locally assigned
’reason code’ value consistent with the proposed, local ’channel
type’. It is assumed that practitioners will first attempt to use
the IANA assigned ’reason code’ values and then document their
locally assigned ’reason code’ values.
o There are no restrictions or suggestions for the range starting
with 0xFF. No interoperability is expected for anything used in
this range. Essentially, it is for experimentation.
5.2. Data Transfer
The window size specifies how many bytes the other party can send
before it must wait for the window to be adjusted. Both parties use
the following message to adjust the window.
byte SSH_MSG_CHANNEL_WINDOW_ADJUST
uint32 recipient channel
uint32 bytes to add
After receiving this message, the recipient MAY send the given number
of bytes more than it was previously allowed to send; the window size
is incremented. Implementations MUST correctly handle window sizes
of up to 2^32 - 1 bytes. The window MUST NOT be increased above
2^32 - 1 bytes.
Data transfer is done with messages of the following type.
byte SSH_MSG_CHANNEL_DATA
uint32 recipient channel
string data
The maximum amount of data allowed is determined by the maximum
packet size for the channel, and the current window size, whichever
is smaller. The window size is decremented by the amount of data
sent. Both parties MAY ignore all extra data sent after the allowed
window is empty.
Implementations are expected to have some limit on the SSH transport
layer packet size (any limit for received packets MUST be 32768 bytes
or larger, as described in [SSH-TRANS]). The implementation of the
SSH connection layer
o MUST NOT advertise a maximum packet size that would result in
transport packets larger than its transport layer is willing to
receive.
o MUST NOT generate data packets larger than its transport layer is
willing to send, even if the remote end would be willing to accept
very large packets.
Additionally, some channels can transfer several types of data. An
example of this is stderr data from interactive sessions. Such data
can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a
separate integer specifies the type of data. The available types and
their interpretation depend on the type of channel.
byte SSH_MSG_CHANNEL_EXTENDED_DATA
uint32 recipient channel
uint32 data_type_code
string data
Data sent with these messages consumes the same window as ordinary
data.
Currently, only the following type is defined. Note that the value
for the ’data_type_code’ is given in decimal format for readability,
but the values are actually uint32 values.
Symbolic name data_type_code
------------- --------------
SSH_EXTENDED_DATA_STDERR 1
Extended Channel Data Transfer ’data_type_code’ values MUST be
assigned sequentially. Requests for assignments of new Extended
Channel Data Transfer ’data_type_code’ values and their associated
Extended Channel Data Transfer ’data’ strings, in the range of
0x00000002 to 0xFDFFFFFF, MUST be done through the IETF CONSENSUS
method as described in [RFC2434]. The IANA will not assign Extended
Channel Data Transfer ’data_type_code’ values in the range of
0xFE000000 to 0xFFFFFFFF. Extended Channel Data Transfer
’data_type_code’ values in that range are left for PRIVATE USE, as
described in [RFC2434]. As is noted, the actual instructions to the
IANA are in [SSH-NUMBERS].
5.3. Closing a Channel
When a party will no longer send more data to a channel, it SHOULD
send SSH_MSG_CHANNEL_EOF.
byte SSH_MSG_CHANNEL_EOF
uint32 recipient channel
No explicit response is sent to this message. However, the
application may send EOF to whatever is at the other end of the
channel. Note that the channel remains open after this message, and
more data may still be sent in the other direction. This message
does not consume window space and can be sent even if no window space
is available.
When either party wishes to terminate the channel, it sends
SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST
send back an SSH_MSG_CHANNEL_CLOSE unless it has already sent this
message for the channel. The channel is considered closed for a
party when it has both sent and received SSH_MSG_CHANNEL_CLOSE, and
the party may then reuse the channel number. A party MAY send
SSH_MSG_CHANNEL_CLOSE without having sent or received
SSH_MSG_CHANNEL_EOF.
byte SSH_MSG_CHANNEL_CLOSE
uint32 recipient channel
This message does not consume window space and can be sent even if no
window space is available.
It is RECOMMENDED that all data sent before this message be delivered
to the actual destination, if possible.
5.4. Channel-Specific Requests
Many ’channel type’ values have extensions that are specific to that
particular ’channel type’. An example is requesting a pty (pseudo
terminal) for an interactive session.
All channel-specific requests use the following format.
byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string request type in US-ASCII characters only
boolean want reply
.... type-specific data follows
If ’want reply’ is FALSE, no response will be sent to the request.
Otherwise, the recipient responds with either
SSH_MSG_CHANNEL_SUCCESS, SSH_MSG_CHANNEL_FAILURE, or request-specific
continuation messages. If the request is not recognized or is not
supported for the channel, SSH_MSG_CHANNEL_FAILURE is returned.
This message does not consume window space and can be sent even if no
window space is available. The values of ’request type’ are local to
each channel type.
The client is allowed to send further messages without waiting for
the response to the request.
’request type’ names follow the DNS extensibility naming convention
outlined in [SSH-ARCH] and [SSH-NUMBERS].
byte SSH_MSG_CHANNEL_SUCCESS
uint32 recipient channel
byte SSH_MSG_CHANNEL_FAILURE
uint32 recipient channel
These messages do not consume window space and can be sent even if no
window space is available.
6. Interactive Sessions
A session is a remote execution of a program. The program may be a
shell, an application, a system command, or some built-in subsystem.
It may or may not have a tty, and may or may not involve X11
forwarding. Multiple sessions can be active simultaneously.
6.1. Opening a Session
A session is started by sending the following message.
byte SSH_MSG_CHANNEL_OPEN
string "session"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
Client implementations SHOULD reject any session channel open
requests to make it more difficult for a corrupt server to attack the
client.
6.2. Requesting a Pseudo-Terminal
A pseudo-terminal can be allocated for the session by sending the
following message.
byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "pty-req"
boolean want_reply
string TERM environment variable value (e.g., vt100)
uint32 terminal width, characters (e.g., 80)
uint32 terminal height, rows (e.g., 24)
uint32 terminal width, pixels (e.g., 640)
uint32 terminal height, pixels (e.g., 480)
string encoded terminal modes
The ’encoded terminal modes’ are described in Section 8. Zero
dimension parameters MUST be ignored. The character/row dimensions
override the pixel dimensions (when nonzero). Pixel dimensions refer
to the drawable area of the window.
The dimension parameters are only informational.
The client SHOULD ignore pty requests.
6.3. X11 Forwarding
6.3.1. Requesting X11 Forwarding
X11 forwarding may be requested for a session by sending a
SSH_MSG_CHANNEL_REQUEST message.
byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "x11-req"
boolean want reply
boolean single connection
string x11 authentication protocol
string x11 authentication cookie
uint32 x11 screen number
It is RECOMMENDED that the ’x11 authentication cookie’ that is sent
be a fake, random cookie, and that the cookie be checked and replaced
by the real cookie when a connection request is received.
X11 connection forwarding should stop when the session channel is
closed. However, already opened forwardings should not be
automatically closed when the session channel is closed.
If ’single connection’ is TRUE, only a single connection should be
forwarded. No more connections will be forwarded after the first, or
after the session channel has been closed.
The ’x11 authentication protocol’ is the name of the X11
authentication method used, e.g., "MIT-MAGIC-COOKIE-1".
The ’x11 authentication cookie’ MUST be hexadecimal encoded.
The X Protocol is documented in [SCHEIFLER].
6.3.2. X11 Channels
X11 channels are opened with a channel open request. The resulting
channels are independent of the session, and closing the session
channel does not close the forwarded X11 channels.
byte SSH_MSG_CHANNEL_OPEN
string "x11"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
string originator address (e.g., "192.168.7.38")
uint32 originator port
The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION
or SSH_MSG_CHANNEL_OPEN_FAILURE.
Implementations MUST reject any X11 channel open requests if they
have not requested X11 forwarding.
6.4. Environment Variable Passing
Environment variables may be passed to the shell/command to be
started later. Uncontrolled setting of environment variables in a
privileged process can be a security hazard. It is recommended that
implementations either maintain a list of allowable variable names or
only set environment variables after the server process has dropped