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.

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 "[email protected]", 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.
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:

MUST NOT advertise a maximum packet size that would result in transport packets larger than its transport layer is willing to receive.
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.