draft-ietf-secsh-connect-25.txt   rfc4254.txt 
Network Working Group T. Ylonen Network Working Group T. Ylonen
Internet-Draft SSH Communications Security Corp Request for Comments: 4254 SSH Communications Security Corp
Expires: September 15, 2005 C. Lonvick, Ed. Category: Standards Track C. Lonvick, Ed.
Cisco Systems, Inc. Cisco Systems, Inc.
March 14, 2005 January 2006
SSH Connection Protocol
draft-ietf-secsh-connect-25.txt
Status of this Memo
This document is an Internet-Draft and is subject to all provisions
of Section 3 of RFC 3667. By submitting this Internet-Draft, each
author represents that any applicable patent or other IPR claims of
which he or she is aware have been or will be disclosed, and any of
which he or she become aware will be disclosed, in accordance with
RFC 3668.
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."
The list of current Internet-Drafts can be accessed at The Secure Shell (SSH) Connection Protocol
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at Status of This Memo
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on September 15, 2005. 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 Notice
Copyright (C) The Internet Society (2005). Copyright (C) The Internet Society (2006).
Abstract Abstract
SSH is a protocol for secure remote login and other secure network Secure Shell (SSH) is a protocol for secure remote login and other
services over an insecure network. secure network services over an insecure network.
This document describes the SSH Connection Protocol. It provides This document describes the SSH Connection Protocol. It provides
interactive login sessions, remote execution of commands, forwarded interactive login sessions, remote execution of commands, forwarded
TCP/IP connections, and forwarded X11 connections. All of these TCP/IP connections, and forwarded X11 connections. All of these
channels are multiplexed into a single encrypted tunnel. channels are multiplexed into a single encrypted tunnel.
The SSH Connection Protocol has been designed to run on top of the The SSH Connection Protocol has been designed to run on top of the
SSH transport layer and user authentication protocols. SSH transport layer and user authentication protocols.
Table of Contents Table of Contents
1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction ....................................................2
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Contributors ....................................................3
3. Conventions Used in This Document . . . . . . . . . . . . . . 3 3. Conventions Used in This Document ...............................3
4. Global Requests . . . . . . . . . . . . . . . . . . . . . . . 4 4. Global Requests .................................................4
5. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . 5 5. Channel Mechanism ...............................................5
5.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . 5 5.1. Opening a Channel ..........................................5
5.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . 7 5.2. Data Transfer ..............................................7
5.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . 8 5.3. Closing a Channel ..........................................9
5.4 Channel-Specific Requests . . . . . . . . . . . . . . . . 9 5.4. Channel-Specific Requests ..................................9
6. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . 10 6. Interactive Sessions ...........................................10
6.1 Opening a Session . . . . . . . . . . . . . . . . . . . . 10 6.1. Opening a Session .........................................10
6.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . 11 6.2. Requesting a Pseudo-Terminal ..............................11
6.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . 11 6.3. X11 Forwarding ............................................11
6.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . 11 6.3.1. Requesting X11 Forwarding ..........................11
6.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . 12 6.3.2. X11 Channels .......................................12
6.4 Environment Variable Passing . . . . . . . . . . . . . . . 12 6.4. Environment Variable Passing ..............................12
6.5 Starting a Shell or a Command . . . . . . . . . . . . . . 13 6.5. Starting a Shell or a Command .............................13
6.6 Session Data Transfer . . . . . . . . . . . . . . . . . . 14 6.6. Session Data Transfer .....................................14
6.7 Window Dimension Change Message . . . . . . . . . . . . . 14 6.7. Window Dimension Change Message ...........................14
6.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . 14 6.8. Local Flow Control ........................................14
6.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.9. Signals ...................................................15
6.10 Returning Exit Status . . . . . . . . . . . . . . . . . . 15 6.10. Returning Exit Status ....................................15
7. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . 16 7. TCP/IP Port Forwarding .........................................16
7.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . 16 7.1. Requesting Port Forwarding ................................16
7.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . 18 7.2. TCP/IP Forwarding Channels ................................18
8. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . 19 8. Encoding of Terminal Modes .....................................19
9. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 21 9. Summary of Message Numbers .....................................21
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 21 10. IANA Considerations ...........................................21
11. Security Considerations . . . . . . . . . . . . . . . . . . 21 11. Security Considerations .......................................21
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 12. References ....................................................22
12.1 Normative References . . . . . . . . . . . . . . . . . . . 22 12.1. Normative References .....................................22
12.2 Informative References . . . . . . . . . . . . . . . . . . 22 12.2. Informative References ...................................22
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 23 Authors' Addresses ................................................23
A. Trademark Notice . . . . . . . . . . . . . . . . . . . . . . . 23 Trademark Notice ..................................................23
Intellectual Property and Copyright Statements . . . . . . . . 24
1. Contributors 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: The major original contributors of this set of documents have been:
Tatu Ylonen, Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH Tatu Ylonen, Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH
Communications Security Corp), and Markku-Juhani O. Saarinen Communications Security Corp), and Markku-Juhani O. Saarinen
(University of Jyvaskyla). Darren Moffit was the original editor of (University of Jyvaskyla). Darren Moffat was the original editor of
this set of documents and also made very substantial contributions. this set of documents and also made very substantial contributions.
Many people contributed to the development of this document over the Many people contributed to the development of this document over the
years. People who should be acknowledged include Mats Andersson, Ben years. People who should be acknowledged include Mats Andersson, Ben
Harris, Brent McClure, Niels Moller, Damien Miller, Derek Fawcus, Harris, Bill Sommerfeld, Brent McClure, Niels Moller, Damien Miller,
Frank Cusack, Heikki Nousiainen, Jakob Schlyter, Jeff Van Dyke, Derek Fawcus, Frank Cusack, Heikki Nousiainen, Jakob Schlyter, Jeff
Jeffrey Altman, Jeffrey Hutzelman, Jon Bright, Joseph Galbraith, Ken Van Dyke, Jeffrey Altman, Jeffrey Hutzelman, Jon Bright, Joseph
Hornstein, Markus Friedl, Martin Forssen, Nicolas Williams, Niels Galbraith, Ken Hornstein, Markus Friedl, Martin Forssen, Nicolas
Provos, Perry Metzger, Peter Gutmann, Simon Josefsson, Simon Tatham, Williams, Niels Provos, Perry Metzger, Peter Gutmann, Simon
Wei Dai, Denis Bider, der Mouse, and Tadayoshi Kohno. Listing their Josefsson, Simon Tatham, Wei Dai, Denis Bider, der Mouse, and
names here does not mean that they endorse this document, but that Tadayoshi Kohno. Listing their names here does not mean that they
they have contributed to it. endorse this document, but that they have contributed to it.
2. Introduction
The SSH Connection Protocol has been designed to run on top of the
SSH transport layer and user authentication protocols. 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.
3. Conventions Used in This Document 3. Conventions Used in This Document
All documents related to the SSH protocols shall use the keywords All documents related to the SSH protocols shall use the keywords
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe
requirements. These keywords are to be interpreted as described in requirements. These keywords are to be interpreted as described in
[RFC2119]. [RFC2119].
The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME
FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG
APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in
this document when used to describe namespace allocation are to be this document when used to describe namespace allocation are to be
interpreted as described in [RFC2434]. interpreted as described in [RFC2434].
Protocol fields and possible values to fill them are defined in this Protocol fields and possible values to fill them are defined in this
set of documents. Protocol fields will be defined in the message set of documents. Protocol fields will be defined in the message
definitions. As an example, SSH_MSG_CHANNEL_DATA is defined as definitions. As an example, SSH_MSG_CHANNEL_DATA is defined as
follows. follows.
byte SSH_MSG_CHANNEL_DATA byte SSH_MSG_CHANNEL_DATA
uint32 recipient channel uint32 recipient channel
string data string data
Throughout these documents, when the fields are referenced, they will Throughout these documents, when the fields are referenced, they will
appear within single quotes. When values to fill those fields are appear within single quotes. When values to fill those fields are
referenced, they will appear within double quotes. Using the above referenced, they will appear within double quotes. Using the above
example, possible values for 'data' are "foo" and "bar". example, possible values for 'data' are "foo" and "bar".
4. Global Requests 4. Global Requests
There are several kinds of requests that affect the state of the There are several kinds of requests that affect the state of the
remote end globally, independent of any channels. An example is a remote end globally, independent of any channels. An example is a
request to start TCP/IP forwarding for a specific port. Note that request to start TCP/IP forwarding for a specific port. Note that
both client and server MAY send global requests at any time, and the both the client and server MAY send global requests at any time, and
receiver MUST respond appropriately. All such requests use the the receiver MUST respond appropriately. All such requests use the
following format. following format.
byte SSH_MSG_GLOBAL_REQUEST byte SSH_MSG_GLOBAL_REQUEST
string request name in US-ASCII only string request name in US-ASCII only
boolean want reply boolean want reply
... request-specific data follows .... request-specific data follows
The value of 'request name' follows the DNS extensibility naming The value of 'request name' follows the DNS extensibility naming
convention outlined in [SSH-ARCH]. convention outlined in [SSH-ARCH].
The recipient will respond to this message with The recipient will respond to this message with
SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if 'want reply' is SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if 'want reply' is
TRUE. TRUE.
byte SSH_MSG_REQUEST_SUCCESS byte SSH_MSG_REQUEST_SUCCESS
..... response specific data .... response specific data
Usually the 'response specific data' is non-existent. Usually, the 'response specific data' is non-existent.
If the recipient does not recognize or support the request, it simply If the recipient does not recognize or support the request, it simply
responds with SSH_MSG_REQUEST_FAILURE. responds with SSH_MSG_REQUEST_FAILURE.
byte SSH_MSG_REQUEST_FAILURE byte SSH_MSG_REQUEST_FAILURE
In general, the reply messages do not include request type In general, the reply messages do not include request type
identifiers. To make it possible for the originator of a request to identifiers. To make it possible for the originator of a request to
identify to which request each reply refers, it is REQUIRED that 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 replies to SSH_MSG_GLOBAL_REQUESTS MUST be sent in the same order as
the corresponding request messages. For channel requests, replies the corresponding request messages. For channel requests, replies
that relate to the same channel MUST also be replied to in the right that relate to the same channel MUST also be replied to in the right
order. However, channel requests for distinct channels MAY be order. However, channel requests for distinct channels MAY be
replied to out-of-order. replied to out-of-order.
5. Channel Mechanism 5. Channel Mechanism
All terminal sessions, forwarded connections, etc., are channels. All terminal sessions, forwarded connections, etc., are channels.
Either side may open a channel. Multiple channels are multiplexed Either side may open a channel. Multiple channels are multiplexed
into a single connection. into a single connection.
Channels are identified by numbers at each end. The number referring Channels are identified by numbers at each end. The number referring
to a channel may be different on each side. Requests to open a to a channel may be different on each side. Requests to open a
channel contain the sender's channel number. Any other channel contain the sender's channel number. Any other channel-
channel-related messages contain the recipient's channel number for related messages contain the recipient's channel number for the
the channel. channel.
Channels are flow-controlled. No data may be sent to a channel until Channels are flow-controlled. No data may be sent to a channel until
a message is received to indicate that window space is available. a message is received to indicate that window space is available.
5.1 Opening a Channel 5.1. Opening a Channel
When either side wishes to open a new channel, it allocates a local 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 number for the channel. It then sends the following message to the
other side, and includes the local channel number and initial window other side, and includes the local channel number and initial window
size in the message. size in the message.
byte SSH_MSG_CHANNEL_OPEN byte SSH_MSG_CHANNEL_OPEN
string channel type in US-ASCII only string channel type in US-ASCII only
uint32 sender channel uint32 sender channel
uint32 initial window size uint32 initial window size
uint32 maximum packet size uint32 maximum packet size
... channel type specific data follows .... channel type specific data follows
The 'channel type' is a name as described in [SSH-ARCH] and The 'channel type' is a name, as described in [SSH-ARCH] and
[SSH-NUMBERS], with similar extension mechanisms. The 'sender [SSH-NUMBERS], with similar extension mechanisms. The 'sender
channel' is a local identifier for the channel used by the sender of channel' is a local identifier for the channel used by the sender of
this message. The 'initial window size' specifies how many bytes of this message. The 'initial window size' specifies how many bytes of
channel data can be sent to the sender of this message without channel data can be sent to the sender of this message without
adjusting the window. The 'maximum packet size' specifies the adjusting the window. The 'maximum packet size' specifies the
maximum size of an individual data packet that can be sent to 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 sender. For example, one might want to use smaller packets for
interactive connections to get better interactive response on slow interactive connections to get better interactive response on slow
links. links.
The remote side then decides whether it can open the channel, and The remote side then decides whether it can open the channel, and
responds with either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or responds with either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or
SSH_MSG_CHANNEL_OPEN_FAILURE. SSH_MSG_CHANNEL_OPEN_FAILURE.
byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION
uint32 recipient channel uint32 recipient channel
uint32 sender channel uint32 sender channel
uint32 initial window size uint32 initial window size
uint32 maximum packet size uint32 maximum packet size
... 'channel type' specific data follows .... channel type specific data follows
The 'recipient channel' is the channel number given in the original The 'recipient channel' is the channel number given in the original
open request, and 'sender channel' is the channel number allocated by open request, and 'sender channel' is the channel number allocated by
the other side. the other side.
byte SSH_MSG_CHANNEL_OPEN_FAILURE byte SSH_MSG_CHANNEL_OPEN_FAILURE
uint32 recipient channel uint32 recipient channel
uint32 reason code uint32 reason code
string description in ISO-10646 UTF-8 encoding [RFC3629] string description in ISO-10646 UTF-8 encoding [RFC3629]
string language tag as defined in [RFC3066] string language tag [RFC3066]
If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support
the specified 'channel type', it simply responds with the specified 'channel type', it simply responds with
SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the 'description' SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the 'description'
string to the user. If this is done, the client software should take string to the user. If this is done, the client software should take
the precautions discussed in [SSH-ARCH]. the precautions discussed in [SSH-ARCH].
The SSH_MSG_CHANNEL_OPEN_FAILURE 'reason code' values are defined in The SSH_MSG_CHANNEL_OPEN_FAILURE 'reason code' values are defined in
the following table. Note that the values for the 'reason code' are the following table. Note that the values for the 'reason code' are
given in decimal format for readability but that they are actually given in decimal format for readability, but they are actually uint32
uint32 values. values.
Symbolic name reason code Symbolic name reason code
------------- ----------- ------------- -----------
SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1
SSH_OPEN_CONNECT_FAILED 2 SSH_OPEN_CONNECT_FAILED 2
SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3
SSH_OPEN_RESOURCE_SHORTAGE 4 SSH_OPEN_RESOURCE_SHORTAGE 4
Requests for assignments of new SSH_MSG_CHANNEL_OPEN 'reason code' Requests for assignments of new SSH_MSG_CHANNEL_OPEN 'reason code'
values (and associated 'description' text) in the range of 0x00000005 values (and associated 'description' text) in the range of 0x00000005
to 0xFDFFFFFF MUST be done through the IETF CONSENSUS method as to 0xFDFFFFFF MUST be done through the IETF CONSENSUS method, as
described in [RFC2434]. The IANA will not assign Channel Connection described in [RFC2434]. The IANA will not assign Channel Connection
Failure 'reason code' values in the range of 0xFE000000 to Failure 'reason code' values in the range of 0xFE000000 to
0xFFFFFFFF. Channel Connection Failure 'reason code' values in that 0xFFFFFFFF. Channel Connection Failure 'reason code' values in that
range are left for PRIVATE USE as described in [RFC2434]. range are left for PRIVATE USE, as described in [RFC2434].
While it is understood that the IANA will have no control over the 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 range of 0xFE000000 to 0xFFFFFFFF, this range will be split in two
parts and administered by the following conventions. parts and administered by the following conventions.
o The range of 0xFE000000 to 0xFEFFFFFF is to be used in conjunction o The range of 0xFE000000 to 0xFEFFFFFF is to be used in conjunction
with locally assigned channels. For example: if a channel is with locally assigned channels. For example, if a channel is
proposed with a 'channel type' of "example_session@example.com" proposed with a 'channel type' of "example_session@example.com",
but fails, then the response will contain either a 'reason code' but fails, then the response will contain either a 'reason code'
assigned by the IANA (as listed above and in the range of assigned by the IANA (as listed above and in the range of
0x00000001 to 0xFDFFFFFF), or with a locally assigned value in the 0x00000001 to 0xFDFFFFFF) or a locally assigned value in the range
range of 0xFE000000 to 0xFEFFFFFF. Naturally, if the server does of 0xFE000000 to 0xFEFFFFFF. Naturally, if the server does not
not understand the proposed 'channel type', even if it is a understand the proposed 'channel type', even if it is a locally
locally defined 'channel type', then the 'reason code' MUST be defined 'channel type', then the 'reason code' MUST be 0x00000003,
0x00000003 as described above, if the 'reason code' is sent. If as described above, if the 'reason code' is sent. If the server
the server does understand the 'channel type' but the channel does understand the 'channel type', but the channel still fails to
still fails to open, then the server SHOULD respond with a locally open, then the server SHOULD respond with a locally assigned
assigned 'reason code' value consistent with the proposed, local 'reason code' value consistent with the proposed, local 'channel
'channel type'. It is assumed that practitioners will first type'. It is assumed that practitioners will first attempt to use
attempt to use the IANA assigned 'reason code' values and then the IANA assigned 'reason code' values and then document their
document their locally assigned 'reason code' values. locally assigned 'reason code' values.
o There are no restrictions or suggestions for the range starting o There are no restrictions or suggestions for the range starting
with 0xFF. No interoperability is expected for anything used in with 0xFF. No interoperability is expected for anything used in
this range. Essentially it is for experimentation. this range. Essentially, it is for experimentation.
5.2 Data Transfer 5.2. Data Transfer
The window size specifies how many bytes the other party can send 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 before it must wait for the window to be adjusted. Both parties use
the following message to adjust the window. the following message to adjust the window.
byte SSH_MSG_CHANNEL_WINDOW_ADJUST byte SSH_MSG_CHANNEL_WINDOW_ADJUST
uint32 recipient channel uint32 recipient channel
uint32 bytes to add uint32 bytes to add
After receiving this message, the recipient MAY send the given number After receiving this message, the recipient MAY send the given number
of bytes more than it was previously allowed to send; the window size of bytes more than it was previously allowed to send; the window size
is incremented. Implementations MUST correctly handle window sizes is incremented. Implementations MUST correctly handle window sizes
of up to 2^32 - 1 bytes. The window MUST NOT be increased above 2^32 of up to 2^32 - 1 bytes. The window MUST NOT be increased above
- 1 bytes. 2^32 - 1 bytes.
Data transfer is done with messages of the following type. Data transfer is done with messages of the following type.
byte SSH_MSG_CHANNEL_DATA byte SSH_MSG_CHANNEL_DATA
uint32 recipient channel uint32 recipient channel
string data string data
The maximum amount of data allowed is the current window size. The The maximum amount of data allowed is determined by the maximum
window size is decremented by the amount of data sent. Both parties packet size for the channel, and the current window size, whichever
MAY ignore all extra data sent after the allowed window is empty. 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 Additionally, some channels can transfer several types of data. An
example of this is stderr data from interactive sessions. Such data example of this is stderr data from interactive sessions. Such data
can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a
separate integer specifies the type of the data. The available types separate integer specifies the type of data. The available types and
and their interpretation depend on the type of the channel. their interpretation depend on the type of channel.
byte SSH_MSG_CHANNEL_EXTENDED_DATA byte SSH_MSG_CHANNEL_EXTENDED_DATA
uint32 recipient_channel uint32 recipient channel
uint32 data_type_code uint32 data_type_code
string data string data
Data sent with these messages consumes the same window as ordinary Data sent with these messages consumes the same window as ordinary
data. data.
Currently, only the following type is defined. Note that the value Currently, only the following type is defined. Note that the value
for the 'data_type_code' is given in decimal format for readability for the 'data_type_code' is given in decimal format for readability,
but that the values are actually uint32 values. but the values are actually uint32 values.
Symbolic name data_type_code Symbolic name data_type_code
------------- -------------- ------------- --------------
SSH_EXTENDED_DATA_STDERR 1 SSH_EXTENDED_DATA_STDERR 1
Extended Channel Data Transfer 'data_type_code' values MUST be Extended Channel Data Transfer 'data_type_code' values MUST be
assigned sequentially. Requests for assignments of new Extended assigned sequentially. Requests for assignments of new Extended
Channel Data Transfer 'data_type_code' values, and their associated Channel Data Transfer 'data_type_code' values and their associated
Extended Channel Data Transfer 'data' strings, in the range of Extended Channel Data Transfer 'data' strings, in the range of
0x00000002 to 0xFDFFFFFF MUST be done through the IETF CONSENSUS 0x00000002 to 0xFDFFFFFF, MUST be done through the IETF CONSENSUS
method as described in [RFC2434]. The IANA will not assign Extended method as described in [RFC2434]. The IANA will not assign Extended
Channel Data Transfer 'data_type_code' values in the range of Channel Data Transfer 'data_type_code' values in the range of
0xFE000000 to 0xFFFFFFFF. Extended Channel Data Transfer 0xFE000000 to 0xFFFFFFFF. Extended Channel Data Transfer
'data_type_code' values in that range are left for PRIVATE USE as 'data_type_code' values in that range are left for PRIVATE USE, as
described in [RFC2434]. As is noted, the actual instructions to the described in [RFC2434]. As is noted, the actual instructions to the
IANA are in [SSH-NUMBERS]. IANA are in [SSH-NUMBERS].
5.3 Closing a Channel 5.3. Closing a Channel
When a party will no longer send more data to a channel, it SHOULD When a party will no longer send more data to a channel, it SHOULD
send SSH_MSG_CHANNEL_EOF. send SSH_MSG_CHANNEL_EOF.
byte SSH_MSG_CHANNEL_EOF byte SSH_MSG_CHANNEL_EOF
uint32 recipient_channel uint32 recipient channel
No explicit response is sent to this message. However, the No explicit response is sent to this message. However, the
application may send EOF to whatever is at the other end of 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 channel. Note that the channel remains open after this message, and
more data may still be sent in the other direction. This message 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 does not consume window space and can be sent even if no window space
is available. is available.
When either party wishes to terminate the channel, it sends When either party wishes to terminate the channel, it sends
SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST
send back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this send back an SSH_MSG_CHANNEL_CLOSE unless it has already sent this
message for the channel. The channel is considered closed for a message for the channel. The channel is considered closed for a
party when it has both sent and received SSH_MSG_CHANNEL_CLOSE, and 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 the party may then reuse the channel number. A party MAY send
SSH_MSG_CHANNEL_CLOSE without having sent or received SSH_MSG_CHANNEL_CLOSE without having sent or received
SSH_MSG_CHANNEL_EOF. SSH_MSG_CHANNEL_EOF.
byte SSH_MSG_CHANNEL_CLOSE byte SSH_MSG_CHANNEL_CLOSE
uint32 recipient_channel uint32 recipient channel
This message does not consume window space and can be sent even if no This message does not consume window space and can be sent even if no
window space is available. window space is available.
It is recommended that any data sent before this message is delivered It is RECOMMENDED that all data sent before this message be delivered
to the actual destination, if possible. to the actual destination, if possible.
5.4 Channel-Specific Requests 5.4. Channel-Specific Requests
Many 'channel type' values have extensions that are specific to that Many 'channel type' values have extensions that are specific to that
particular 'channel type'. An example is requesting a pty (pseudo particular 'channel type'. An example is requesting a pty (pseudo
terminal) for an interactive session. terminal) for an interactive session.
All channel-specific requests use the following format. All channel-specific requests use the following format.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel uint32 recipient channel
string request type in US-ASCII characters only string request type in US-ASCII characters only
boolean want reply boolean want reply
... type-specific data .... type-specific data follows
If 'want reply' is FALSE, no response will be sent to the request. If 'want reply' is FALSE, no response will be sent to the request.
Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS Otherwise, the recipient responds with either
or SSH_MSG_CHANNEL_FAILURE, or request-specific continuation SSH_MSG_CHANNEL_SUCCESS, SSH_MSG_CHANNEL_FAILURE, or request-specific
messages. If the request is not recognized or is not supported for continuation messages. If the request is not recognized or is not
the channel, SSH_MSG_CHANNEL_FAILURE is returned. supported for the channel, SSH_MSG_CHANNEL_FAILURE is returned.
This message does not consume window space and can be sent even if no 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 window space is available. The values of 'request type' are local to
each channel type. each channel type.
The client is allowed to send further messages without waiting for The client is allowed to send further messages without waiting for
the response to the request. the response to the request.
'request type' names follow the DNS extensibility naming convention 'request type' names follow the DNS extensibility naming convention
outlined in [SSH-ARCH] and [SSH-NUMBERS]. outlined in [SSH-ARCH] and [SSH-NUMBERS].
byte SSH_MSG_CHANNEL_SUCCESS byte SSH_MSG_CHANNEL_SUCCESS
uint32 recipient_channel uint32 recipient channel
byte SSH_MSG_CHANNEL_FAILURE byte SSH_MSG_CHANNEL_FAILURE
uint32 recipient_channel uint32 recipient channel
These messages do not consume window space and can be sent even if no These messages do not consume window space and can be sent even if no
window space is available. window space is available.
6. Interactive Sessions 6. Interactive Sessions
A session is a remote execution of a program. The program may be a 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. 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 It may or may not have a tty, and may or may not involve X11
forwarding. Multiple sessions can be active simultaneously. forwarding. Multiple sessions can be active simultaneously.
6.1 Opening a Session 6.1. Opening a Session
A session is started by sending the following message. A session is started by sending the following message.
byte SSH_MSG_CHANNEL_OPEN byte SSH_MSG_CHANNEL_OPEN
string "session" string "session"
uint32 sender channel uint32 sender channel
uint32 initial window size uint32 initial window size
uint32 maximum packet size uint32 maximum packet size
Client implementations SHOULD reject any session channel open Client implementations SHOULD reject any session channel open
requests to make it more difficult for a corrupt server to attack the requests to make it more difficult for a corrupt server to attack the
client. client.
6.2 Requesting a Pseudo-Terminal 6.2. Requesting a Pseudo-Terminal
A pseudo-terminal can be allocated for the session by sending the A pseudo-terminal can be allocated for the session by sending the
following message. following message.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient_channel uint32 recipient channel
string "pty-req" string "pty-req"
boolean want_reply boolean want_reply
string TERM environment variable value (e.g., vt100) string TERM environment variable value (e.g., vt100)
uint32 terminal width, characters (e.g., 80) uint32 terminal width, characters (e.g., 80)
uint32 terminal height, rows (e.g., 24) uint32 terminal height, rows (e.g., 24)
uint32 terminal width, pixels (e.g., 640) uint32 terminal width, pixels (e.g., 640)
uint32 terminal height, pixels (e.g., 480) uint32 terminal height, pixels (e.g., 480)
string encoded terminal modes string encoded terminal modes
The 'encoded terminal modes' are described in Section 8. Zero The 'encoded terminal modes' are described in Section 8. Zero
dimension parameters MUST be ignored. The character/row dimensions dimension parameters MUST be ignored. The character/row dimensions
override the pixel dimensions (when nonzero). Pixel dimensions refer override the pixel dimensions (when nonzero). Pixel dimensions refer
to the drawable area of the window. to the drawable area of the window.
The dimension parameters are only informational. The dimension parameters are only informational.
The client SHOULD ignore pty requests. The client SHOULD ignore pty requests.
6.3 X11 Forwarding 6.3. X11 Forwarding
6.3.1 Requesting X11 Forwarding 6.3.1. Requesting X11 Forwarding
X11 forwarding may be requested for a session by sending a X11 forwarding may be requested for a session by sending a
SSH_MSG_CHANNEL_REQUEST message. SSH_MSG_CHANNEL_REQUEST message.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel uint32 recipient channel
string "x11-req" string "x11-req"
boolean want reply boolean want reply
boolean single connection boolean single connection
string x11 authentication protocol string x11 authentication protocol
string x11 authentication cookie string x11 authentication cookie
uint32 x11 screen number uint32 x11 screen number
It is RECOMMENDED that the 'x11 authentication cookie' that is sent It is RECOMMENDED that the 'x11 authentication cookie' that is sent
be a fake, random cookie, and that the cookie is checked and replaced be a fake, random cookie, and that the cookie be checked and replaced
by the real cookie when a connection request is received. by the real cookie when a connection request is received.
X11 connection forwarding should stop when the session channel is X11 connection forwarding should stop when the session channel is
closed. However, already opened forwardings should not be closed. However, already opened forwardings should not be
automatically closed when the session channel is closed. automatically closed when the session channel is closed.
If 'single connection' is TRUE, only a single connection should be If 'single connection' is TRUE, only a single connection should be
forwarded. No more connections will be forwarded after the first, or forwarded. No more connections will be forwarded after the first, or
after the session channel has been closed. after the session channel has been closed.
The 'x11 authentication protocol' is the name of the X11 The 'x11 authentication protocol' is the name of the X11
authentication method used, e.g., "MIT-MAGIC-COOKIE-1". authentication method used, e.g., "MIT-MAGIC-COOKIE-1".
The 'x11 authentication cookie' MUST be hexadecimal encoded. The 'x11 authentication cookie' MUST be hexadecimal encoded.
The X Protocol is documented in [SCHEIFLER]. The X Protocol is documented in [SCHEIFLER].
6.3.2 X11 Channels 6.3.2. X11 Channels
X11 channels are opened with a channel open request. The resulting X11 channels are opened with a channel open request. The resulting
channels are independent of the session, and closing the session channels are independent of the session, and closing the session
channel does not close the forwarded X11 channels. channel does not close the forwarded X11 channels.
byte SSH_MSG_CHANNEL_OPEN byte SSH_MSG_CHANNEL_OPEN
string "x11" string "x11"
uint32 sender channel uint32 sender channel
uint32 initial window size uint32 initial window size
uint32 maximum packet size uint32 maximum packet size
string originator address (e.g., "192.168.7.38") string originator address (e.g., "192.168.7.38")
uint32 originator port uint32 originator port
The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION
or SSH_MSG_CHANNEL_OPEN_FAILURE. or SSH_MSG_CHANNEL_OPEN_FAILURE.
Implementations MUST reject any X11 channel open requests if they Implementations MUST reject any X11 channel open requests if they
have not requested X11 forwarding. have not requested X11 forwarding.
6.4 Environment Variable Passing 6.4. Environment Variable Passing
Environment variables may be passed to the shell/command to be Environment variables may be passed to the shell/command to be
started later. Uncontrolled setting of environment variables in a started later. Uncontrolled setting of environment variables in a
privileged process can be a security hazard. It is recommended that privileged process can be a security hazard. It is recommended that
implementations either maintain a list of allowable variable names or implementations either maintain a list of allowable variable names or
only set environment variables after the server process has dropped only set environment variables after the server process has dropped
sufficient privileges. sufficient privileges.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel uint32 recipient channel
string "env" string "env"
boolean want reply boolean want reply
string variable name string variable name
string variable value string variable value
6.5 Starting a Shell or a Command 6.5. Starting a Shell or a Command
Once the session has been set up, a program is started at the remote Once the session has been set up, a program is started at the remote
end. The program can be a shell, an application program or a end. The program can be a shell, an application program, or a
subsystem with a host-independent name. Only one of these requests subsystem with a host-independent name. Only one of these requests
can succeed per channel. can succeed per channel.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel uint32 recipient channel
string "shell" string "shell"
boolean want reply boolean want reply
This message will request the user's default shell (typically defined This message will request that the user's default shell (typically
in /etc/passwd in UNIX systems) to be started at the other end. defined in /etc/passwd in UNIX systems) be started at the other end.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel uint32 recipient channel
string "exec" string "exec"
boolean want reply boolean want reply
string command string command
This message will request the server to start the execution of the This message will request that the server start the execution of the
given command. The 'command' string may contain a path. Normal given command. The 'command' string may contain a path. Normal
precautions MUST be taken to prevent the execution of unauthorized precautions MUST be taken to prevent the execution of unauthorized
commands. commands.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel uint32 recipient channel
string "subsystem" string "subsystem"
boolean want reply boolean want reply
string subsystem name string subsystem name
This last form executes a predefined subsystem. It is expected that This last form executes a predefined subsystem. It is expected that
these will include a general file transfer mechanism, and possibly these will include a general file transfer mechanism, and possibly
other features. Implementations may also allow configuring more such other features. Implementations may also allow configuring more such
mechanisms. As the user's shell is usually used to execute the mechanisms. As the user's shell is usually used to execute the
subsystem, it is advisable for the subsystem protocol to have a subsystem, it is advisable for the subsystem protocol to have a
"magic cookie" at the beginning of the protocol transaction to "magic cookie" at the beginning of the protocol transaction to
distinguish it from arbitrary output generated by shell distinguish it from arbitrary output generated by shell
initialization scripts, etc. This spurious output from the shell may initialization scripts, etc. This spurious output from the shell may
be filtered out either at the server or at the client. be filtered out either at the server or at the client.
The server SHOULD NOT halt the execution of the protocol stack when The server SHOULD NOT halt the execution of the protocol stack when
starting a shell or a program. All input and output from these starting a shell or a program. All input and output from these
SHOULD be redirected to the channel or to the encrypted tunnel. SHOULD be redirected to the channel or to the encrypted tunnel.
It is RECOMMENDED to request and check the reply for these messages. It is RECOMMENDED that the reply to these messages be requested and
The client SHOULD ignore these messages. checked. The client SHOULD ignore these messages.
Subsystem names follow the DNS extensibility naming convention Subsystem names follow the DNS extensibility naming convention
outlined in [SSH-NUMBERS]. outlined in [SSH-NUMBERS].
6.6 Session Data Transfer 6.6. Session Data Transfer
Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and
SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The
extended data type SSH_EXTENDED_DATA_STDERR has been defined for extended data type SSH_EXTENDED_DATA_STDERR has been defined for
stderr data. stderr data.
6.7 Window Dimension Change Message 6.7. Window Dimension Change Message
When the window (terminal) size changes on the client side, it MAY When the window (terminal) size changes on the client side, it MAY
send a message to the other side to inform it of the new dimensions. send a message to the other side to inform it of the new dimensions.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient_channel uint32 recipient channel
string "window-change" string "window-change"
boolean FALSE boolean FALSE
uint32 terminal width, columns uint32 terminal width, columns
uint32 terminal height, rows uint32 terminal height, rows
uint32 terminal width, pixels uint32 terminal width, pixels
uint32 terminal height, pixels uint32 terminal height, pixels
A response SHOULD NOT be sent to this message. A response SHOULD NOT be sent to this message.
6.8 Local Flow Control 6.8. Local Flow Control
On many systems, it is possible to determine if a pseudo-terminal is On many systems, it is possible to determine if a pseudo-terminal is
using control-S/control-Q flow control. When flow control is using control-S/control-Q flow control. When flow control is
allowed, it is often desirable to do the flow control at the client allowed, it is often desirable to do the flow control at the client
end to speed up responses to user requests. This is facilitated by end to speed up responses to user requests. This is facilitated by
the following notification. Initially, the server is responsible for the following notification. Initially, the server is responsible for
flow control. (Here, again, client means the side originating the flow control. (Here, again, client means the side originating the
session, and server means the other side.) session, and server means the other side.)
The message below is used by the server to inform the client when it The message below is used by the server to inform the client when it
can or cannot perform flow control (control-S/control-Q processing). can or cannot perform flow control (control-S/control-Q processing).
If 'client can do' is TRUE, the client is allowed to do flow control If 'client can do' is TRUE, the client is allowed to do flow control
using control-S and control-Q. The client MAY ignore this message. using control-S and control-Q. The client MAY ignore this message.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel uint32 recipient channel
string "xon-xoff" string "xon-xoff"
boolean FALSE boolean FALSE
boolean client can do boolean client can do
No response is sent to this message. No response is sent to this message.
6.9 Signals 6.9. Signals
A signal can be delivered to the remote process/service using the A signal can be delivered to the remote process/service using the
following message. Some systems may not implement signals, in which following message. Some systems may not implement signals, in which
case they SHOULD ignore this message. case they SHOULD ignore this message.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel uint32 recipient channel
string "signal" string "signal"
boolean FALSE boolean FALSE
string signal name without the "SIG" prefix. string signal name (without the "SIG" prefix)
Signal names will be encoded as discussed in the "exit-signal" 'signal name' values will be encoded as discussed in the passage
SSH_MSG_CHANNEL_REQUEST. describing SSH_MSG_CHANNEL_REQUEST messages using "exit-signal" in
this section.
6.10 Returning Exit Status 6.10. Returning Exit Status
When the command running at the other end terminates, the following When the command running at the other end terminates, the following
message can be sent to return the exit status of the command. message can be sent to return the exit status of the command.
Returning the status is RECOMMENDED. No acknowledgment is sent for Returning the status is RECOMMENDED. No acknowledgement is sent for
this message. The channel needs to be closed with this message. The channel needs to be closed with
SSH_MSG_CHANNEL_CLOSE after this message. SSH_MSG_CHANNEL_CLOSE after this message.
The client MAY ignore these messages. The client MAY ignore these messages.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient_channel uint32 recipient channel
string "exit-status" string "exit-status"
boolean FALSE boolean FALSE
uint32 exit_status uint32 exit_status
The remote command may also terminate violently due to a signal. The remote command may also terminate violently due to a signal.
Such a condition can be indicated by the following message. A zero Such a condition can be indicated by the following message. A zero
'exit_status' usually means that the command terminated successfully. 'exit_status' usually means that the command terminated successfully.
o byte SSH_MSG_CHANNEL_REQUEST
o uint32 recipient channel byte SSH_MSG_CHANNEL_REQUEST
o string "exit-signal" uint32 recipient channel
o boolean FALSE string "exit-signal"
o string signal name without the "SIG" prefix. boolean FALSE
o boolean core dumped string signal name (without the "SIG" prefix)
o string error message in ISO-10646 UTF-8 encoding boolean core dumped
o string language tag as defined in [RFC3066] string error message in ISO-10646 UTF-8 encoding
The 'signal name' is one of the following (these are from [POSIX]) string language tag [RFC3066]
The 'signal name' is one of the following (these are from [POSIX]).
ABRT ABRT
ALRM ALRM
FPE FPE
HUP HUP
ILL ILL
INT INT
KILL KILL
PIPE PIPE
QUIT QUIT
SEGV SEGV
TERM TERM
USR1 USR1
USR2 USR2
Additional 'signal name' values MAY be sent in the format Additional 'signal name' values MAY be sent in the format
"sig-name@xyz", where "sig-name" and "xyz" may be anything a "sig-name@xyz", where "sig-name" and "xyz" may be anything a
particular implementor wants (except the "@" sign). However, it is particular implementer wants (except the "@" sign). However, it is
suggested that if a 'configure' script is used, any non-standard suggested that if a 'configure' script is used, any non-standard
'signal name' values it finds be encoded as "SIG@xyz.config.guess", 'signal name' values it finds be encoded as "SIG@xyz.config.guess",
where "SIG" is the 'signal name' without the "SIG" prefix, and "xyz" where "SIG" is the 'signal name' without the "SIG" prefix, and "xyz"
be the host type, as determined by "config.guess". is the host type, as determined by "config.guess".
The 'error message' contains an additional textual explanation of the The 'error message' contains an additional textual explanation of the
error message. The message may consist of multiple lines. The error message. The message may consist of multiple lines separated
client software MAY display this message to the user. If this is by CRLF (Carriage Return - Line Feed) pairs. The client software MAY
done, the client software should take the precautions discussed in display this message to the user. If this is done, the client
[SSH-ARCH]. software should take the precautions discussed in [SSH-ARCH].
7. TCP/IP Port Forwarding 7. TCP/IP Port Forwarding
7.1 Requesting Port Forwarding 7.1. Requesting Port Forwarding
A party need not explicitly request forwardings from its own end to A party need not explicitly request forwardings from its own end to
the other direction. However, if it wishes that connections to a the other direction. However, if it wishes that connections to a
port on the other side be forwarded to the local side, it must port on the other side be forwarded to the local side, it must
explicitly request this. explicitly request this.
byte SSH_MSG_GLOBAL_REQUEST byte SSH_MSG_GLOBAL_REQUEST
string "tcpip-forward" string "tcpip-forward"
boolean want reply boolean want reply
string address to bind (e.g., "0.0.0.0") string address to bind (e.g., "0.0.0.0")
uint32 port number to bind uint32 port number to bind
The 'address to bind' and 'port number to bind' specify the IP The 'address to bind' and 'port number to bind' specify the IP
address or domain name and port to which the socket to be listened is address (or domain name) and port on which connections for forwarding
bound. Some strings used for the 'address to bind' have special-case are to be accepted. Some strings used for 'address to bind' have
semantics. special-case semantics.
o "" means that connections are to be accepted on all protocol o "" means that connections are to be accepted on all protocol
families supported by the SSH implementation. families supported by the SSH implementation.
o "0.0.0.0" means to listen on all IPv4 addresses. o "0.0.0.0" means to listen on all IPv4 addresses.
o "::" means to listen on all IPv6 addresses. o "::" means to listen on all IPv6 addresses.
o "localhost" means to listen on all protocol families supported by o "localhost" means to listen on all protocol families supported by
the SSH implementation on loopback addresses only, [RFC3330] and the SSH implementation on loopback addresses only ([RFC3330] and
[RFC3513]. [RFC3513]).
o "127.0.0.1" and "::1" indicate listening on the loopback o "127.0.0.1" and "::1" indicate listening on the loopback
interfaces for IPv4 and IPv6 respectively. interfaces for IPv4 and IPv6, respectively.
Note that the client can still filter connections based on Note that the client can still filter connections based on
information passed in the open request. information passed in the open request.
Implementations should only allow forwarding privileged ports if the Implementations should only allow forwarding privileged ports if the
user has been authenticated as a privileged user. user has been authenticated as a privileged user.
Client implementations SHOULD reject these messages; they are Client implementations SHOULD reject these messages; they are
normally only sent by the client. normally only sent by the client.
If a client passes 0 as port number to bind and has 'want reply' TRUE If a client passes 0 as port number to bind and has 'want reply' as
then the server allocates the next available unprivileged port number TRUE, then the server allocates the next available unprivileged port
and replies with the following message, otherwise there is no number and replies with the following message; otherwise, there is no
response specific data. response-specific data.
byte SSH_MSG_REQUEST_SUCCESS byte SSH_MSG_REQUEST_SUCCESS
uint32 port that was bound on the server uint32 port that was bound on the server
A port forwarding can be canceled with the following message. Note A port forwarding can be canceled with the following message. Note
that channel open requests may be received until a reply to this that channel open requests may be received until a reply to this
message is received. message is received.
byte SSH_MSG_GLOBAL_REQUEST byte SSH_MSG_GLOBAL_REQUEST
string "cancel-tcpip-forward" string "cancel-tcpip-forward"
boolean want reply boolean want reply
string address_to_bind (e.g., "127.0.0.1") string address_to_bind (e.g., "127.0.0.1")
uint32 port number to bind uint32 port number to bind
Client implementations SHOULD reject these messages; they are Client implementations SHOULD reject these messages; they are
normally only sent by the client. normally only sent by the client.
7.2 TCP/IP Forwarding Channels 7.2. TCP/IP Forwarding Channels
When a connection comes to a port for which remote forwarding has When a connection comes to a port for which remote forwarding has
been requested, a channel is opened to forward the port to the other been requested, a channel is opened to forward the port to the other
side. side.
byte SSH_MSG_CHANNEL_OPEN byte SSH_MSG_CHANNEL_OPEN
string "forwarded-tcpip" string "forwarded-tcpip"
uint32 sender channel uint32 sender channel
uint32 initial window size uint32 initial window size
uint32 maximum packet size uint32 maximum packet size
string address that was connected string address that was connected
uint32 port that was connected uint32 port that was connected
string originator IP address string originator IP address
uint32 originator port uint32 originator port
Implementations MUST reject these messages unless they have Implementations MUST reject these messages unless they have
previously requested a remote TCP/IP port forwarding with the given previously requested a remote TCP/IP port forwarding with the given
port number. port number.
When a connection comes to a locally forwarded TCP/IP port, the When a connection comes to a locally forwarded TCP/IP port, the
following packet is sent to the other side. Note that these messages following packet is sent to the other side. Note that these messages
MAY be sent also for ports for which no forwarding has been MAY also be sent for ports for which no forwarding has been
explicitly requested. The receiving side must decide whether to explicitly requested. The receiving side must decide whether to
allow the forwarding. allow the forwarding.
byte SSH_MSG_CHANNEL_OPEN byte SSH_MSG_CHANNEL_OPEN
string "direct-tcpip" string "direct-tcpip"
uint32 sender channel uint32 sender channel
uint32 initial window size uint32 initial window size
uint32 maximum packet size uint32 maximum packet size
string host to connect string host to connect
uint32 port to connect uint32 port to connect
string originator IP address string originator IP address
uint32 originator port uint32 originator port
The 'host to connect' and 'port to connect' specify the TCP/IP host The 'host to connect' and 'port to connect' specify the TCP/IP host
and port where the recipient should connect the channel. The 'host and port where the recipient should connect the channel. The 'host
to connect' may be either a domain name or a numeric IP address. to connect' may be either a domain name or a numeric IP address.
The 'originator IP address' is the numeric IP address of the machine The 'originator IP address' is the numeric IP address of the machine
where the connection request comes from, and the 'originator port' is from where the connection request originates, and the 'originator
the port on the originator host from where the connection originated. port' is the port on the host from where the connection originated.
Forwarded TCP/IP channels are independent of any sessions, and Forwarded TCP/IP channels are independent of any sessions, and
closing a session channel does not in any way imply that forwarded closing a session channel does not in any way imply that forwarded
connections should be closed. connections should be closed.
Client implementations SHOULD reject direct TCP/IP open requests for Client implementations SHOULD reject direct TCP/IP open requests for
security reasons. security reasons.
8. Encoding of Terminal Modes 8. Encoding of Terminal Modes
All "encoded terminal modes" (as passed in a pty request) are encoded All 'encoded terminal modes' (as passed in a pty request) are encoded
into a byte stream. It is intended that the coding be portable into a byte stream. It is intended that the coding be portable
across different environments. across different environments. The stream consists of opcode-
argument pairs wherein the opcode is a byte value. Opcodes 1 to 159
The tty mode description is a stream of bytes. The stream consists have a single uint32 argument. Opcodes 160 to 255 are not yet
of opcode-argument pairs where the opcode is a byte value. It is defined, and cause parsing to stop (they should only be used after
terminated by opcode TTY_OP_END (0x00). Opcodes 1 to 159 have a any other data). The stream is terminated by opcode TTY_OP_END
single uint32 argument. Opcodes 160 to 255 are not yet defined, and (0x00).
cause parsing to stop (they should only be used after any other
data).
The client SHOULD put in the stream any modes it knows about, and the The client SHOULD put any modes it knows about in the stream, and the
server MAY ignore any modes it does not know about. This allows some server MAY ignore any modes it does not know about. This allows some
degree of machine-independence, at least between systems that use a degree of machine-independence, at least between systems that use a
POSIX-like tty interface. The protocol can support other systems as POSIX-like tty interface. The protocol can support other systems as
well, but the client may need to fill reasonable values for a number well, but the client may need to fill reasonable values for a number
of parameters so the server pty gets set to a reasonable mode (the of parameters so the server pty gets set to a reasonable mode (the
server leaves all unspecified mode bits in their default values, and server leaves all unspecified mode bits in their default values, and
only some combinations make sense). only some combinations make sense).
The naming of opcode values mostly follows the POSIX terminal mode The naming of opcode values mostly follows the POSIX terminal mode
flags. The following opcode values have been defined. Note that the flags. The following opcode values have been defined. Note that the
values given below are in decimal format for readability but that values given below are in decimal format for readability, but they
they are actually byte values. are actually byte values.
opcode argument description opcode mnemonic description
------ -------- ----------- ------ -------- -----------
0 TTY_OP_END Indicates end of options. 0 TTY_OP_END Indicates end of options.
1 VINTR Interrupt character; 255 if none. Similarly 1 VINTR Interrupt character; 255 if none. Similarly
for the other characters. Not all of these for the other characters. Not all of these
characters are supported on all systems. characters are supported on all systems.
2 VQUIT The quit character (sends SIGQUIT signal on 2 VQUIT The quit character (sends SIGQUIT signal on
POSIX systems). POSIX systems).
3 VERASE Erase the character to left of the cursor. 3 VERASE Erase the character to left of the cursor.
4 VKILL Kill the current input line. 4 VKILL Kill the current input line.
5 VEOF End-of-file character (sends EOF from the 5 VEOF End-of-file character (sends EOF from the
terminal). terminal).
6 VEOL End-of-line character in addition to 6 VEOL End-of-line character in addition to
carriage return and/or linefeed. carriage return and/or linefeed.
7 VEOL2 Additional end-of-line character. 7 VEOL2 Additional end-of-line character.
skipping to change at page 22, line 4 skipping to change at page 21, line 48
protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], and protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], and
this document, are detailed in [SSH-NUMBERS]. this document, are detailed in [SSH-NUMBERS].
11. Security Considerations 11. Security Considerations
This protocol is assumed to run on top of a secure, authenticated This protocol is assumed to run on top of a secure, authenticated
transport. User authentication and protection against network-level transport. User authentication and protection against network-level
attacks are assumed to be provided by the underlying protocols. attacks are assumed to be provided by the underlying protocols.
Full security considerations for this protocol are provided in Full security considerations for this protocol are provided in
[SSH-ARCH]. Specific to this document, it is RECOMMENDED that [SSH-ARCH]. Specific to this document, it is RECOMMENDED that
implementations disable all the potentially dangerous features (e.g., implementations disable all the potentially dangerous features (e.g.,
agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host
key has changed without notice or explanation. key has changed without notice or explanation.
12. References 12. References
12.1 Normative References 12.1. Normative References
[SSH-ARCH]
Lonvick, C., "SSH Protocol Architecture",
I-D draft-ietf-secsh-architecture-22.txt, March 2005.
[SSH-TRANS] [SSH-ARCH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
Lonvick, C., "SSH Transport Layer Protocol", (SSH) Protocol Architecture", RFC 4251, January 2006.
I-D draft-ietf-secsh-transport-24.txt, March 2005.
[SSH-USERAUTH] [SSH-TRANS] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
Lonvick, C., "SSH Authentication Protocol", (SSH) Transport Layer Protocol", RFC 4253, January
I-D draft-ietf-secsh-userauth-27.txt, March 2005. 2006.
[SSH-NUMBERS] [SSH-USERAUTH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
Lonvick, C., "SSH Protocol Assigned Numbers", (SSH) Authentication Protocol", RFC 4252, January
I-D draft-ietf-secsh-assignednumbers-12.txt, March 2005. 2006.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [SSH-NUMBERS] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell
Requirement Levels", BCP 14, RFC 2119, March 1997. (SSH) Protocol Assigned Numbers", RFC 4250, January
2006.
[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
IANA Considerations Section in RFCs", BCP 26, RFC 2434, Requirement Levels", BCP 14, RFC 2119, March 1997.
October 1998.
[RFC3066] Alvestrand, H., "Tags for the Identification of [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing
Languages", BCP 47, RFC 3066, January 2001. an IANA Considerations Section in RFCs", BCP 26, RFC
2434, October 1998.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3066] Alvestrand, H., "Tags for the Identification of
10646", STD 63, RFC 3629, November 2003. Languages", BCP 47, RFC 3066, January 2001.
12.2 Informative References [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC1884] Hinden, R. and S. Deering, "IP Version 6 Addressing 12.2. Informative References
Architecture", RFC 1884, December 1995.
[RFC3330] IANA, "Special-Use IPv4 Addresses", RFC 3330, September [RFC3330] IANA, "Special-Use IPv4 Addresses", RFC 3330,
2002. September 2002.
[RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version 6 [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version
(IPv6) Addressing Architecture", RFC 3513, April 2003. 6 (IPv6) Addressing Architecture", RFC 3513, April
2003.
[SCHEIFLER] [SCHEIFLER] Scheifler, R., "X Window System : The Complete
Scheifler, R., "X Window System : The Complete Reference Reference to Xlib, X Protocol, Icccm, Xlfd, 3rd
to Xlib, X Protocol, Icccm, Xlfd, 3rd edition.", Digital edition.", Digital Press ISBN 1555580882, February
Press ISBN 1555580882, February 1992. 1992.
[POSIX] ISO/IEC, 9945-1., "Information technology -- Portable [POSIX] ISO/IEC, 9945-1., "Information technology -- Portable
Operating System Interface (POSIX)-Part 1: System Operating System Interface (POSIX)-Part 1: System
Application Program Interface (API) C Language", Application Program Interface (API) C Language", ANSI/
ANSI/IEE Std 1003.1, July 1996. IEE Std 1003.1, July 1996.
Authors' Addresses Authors' Addresses
Tatu Ylonen Tatu Ylonen
SSH Communications Security Corp SSH Communications Security Corp
Fredrikinkatu 42 Valimotie 17
HELSINKI FIN-00100 00380 Helsinki
Finland Finland
Email: ylo@ssh.com EMail: ylo@ssh.com
Chris Lonvick (editor) Chris Lonvick (editor)
Cisco Systems, Inc. Cisco Systems, Inc.
12515 Research Blvd. 12515 Research Blvd.
Austin 78759 Austin 78759
USA USA
Email: clonvick@cisco.com EMail: clonvick@cisco.com
Appendix A. Trademark Notice Trademark Notice
"ssh" is a registered trademark in the United States and/or other "ssh" is a registered trademark in the United States and/or other
countries. countries.
Note to the RFC Editor: This should be a separate section like the Full Copyright Statement
subsequent ones, and not an appendix. This paragraph to be removed
before publication.
Intellectual Property Statement Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79. found in BCP 78 and BCP 79.
skipping to change at page 24, line 29 skipping to change at page 24, line 45
such proprietary rights by implementers or users of this such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr. http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at this standard. Please address the information to the IETF at
ietf-ipr@ietf.org. ietf-ipr@ietf.org.
The IETF has been notified of intellectual property rights claimed in Acknowledgement
regard to some or all of the specification contained in this
document. For more information consult the online list of claimed
rights.
Disclaimer of Validity
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Copyright Statement
Copyright (C) The Internet Society (2005). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights.
Acknowledgment
Funding for the RFC Editor function is currently provided by the Funding for the RFC Editor function is provided by the IETF
Internet Society. Administrative Support Activity (IASA).
 End of changes. 129 change blocks. 
420 lines changed or deleted 404 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/