draft-ietf-secsh-connect-00.txt   draft-ietf-secsh-connect-01.txt 
Network Working Group Tatu Ylonen <ylo@ssh.fi> Network Working Group Tatu Ylonen <ylo@ssh.fi>
INTERNET-DRAFT SSH Communications Security INTERNET-DRAFT SSH Communications Security
Expires: September 1, 1997 Expires in six months
SSH Connection Protocol
Status of This memo Status of This memo
This document is an Internet-Draft. Internet-Drafts are working This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts. working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents months and may be updated, replaced, or obsoleted by other documents
skipping to change at page 1, line 28 skipping to change at page 1, line 30
material or to cite them other than as ``work in progress.'' material or to cite them other than as ``work in progress.''
To learn the current status of any Internet-Draft, please check To learn the current status of any Internet-Draft, please check
the ``1id-abstracts.txt'' listing contained in the Internet-Drafts the ``1id-abstracts.txt'' listing contained in the Internet-Drafts
Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast),
or ftp.isi.edu (US West Coast). or ftp.isi.edu (US West Coast).
Abstract Abstract
This document describes the SSH connection protocol. It runs over the This document describes the SSH connection protocol. It multiplexes a
SSH user authentication layer, and performs management of forwarded con- single encrypted tunnel into a number of channels (interactive sessions,
nections and the terminal session(s). forwarded TCP/IP ports, X11 connections, etc). It is intended to run
above the SSH user authentication layer.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . . 2 2. Global Requests . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1. Opening a Channel . . . . . . . . . . . . . . . . . . . . . 3 3. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 3 3.1. Opening a Channel . . . . . . . . . . . . . . . . . . . . . 3
2.3. Closing a Channel . . . . . . . . . . . . . . . . . . . . . 4 3.2. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 4
3. Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.3. Closing a Channel . . . . . . . . . . . . . . . . . . . . . 5
3.1. Opening a Session . . . . . . . . . . . . . . . . . . . . . 4 3.4. Channel-Specific Requests . . . . . . . . . . . . . . . . . 5
3.2. Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 5 4. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . . 6
3.3. Environment Variable Passing . . . . . . . . . . . . . . . . 5 4.1. Opening a Session . . . . . . . . . . . . . . . . . . . . . 6
3.4. Requesting X11 Forwarding . . . . . . . . . . . . . . . . . 6 4.2. Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 6
3.5. Requesting Athentication Agent Forwarding . . . . . . . . . 6 4.3. X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 7
3.6. Starting Shell or Command . . . . . . . . . . . . . . . . . 6 4.3.1. Requesting X11 Forwarding . . . . . . . . . . . . . . . 7
3.7. Session Data Transfer . . . . . . . . . . . . . . . . . . . 7 4.3.2. X11 Channels . . . . . . . . . . . . . . . . . . . . . . 7
3.8. Additional Control Messages . . . . . . . . . . . . . . . . 7 4.4. Authentication Agent Forwarding . . . . . . . . . . . . . . 8
3.8.1. Window Change Message . . . . . . . . . . . . . . . . . 7 4.4.1. Requesting Athentication Agent Forwarding . . . . . . . 8
3.8.2. Local Flow Control . . . . . . . . . . . . . . . . . . . 7 4.4.2. Authentication Agent Channels . . . . . . . . . . . . . 8
3.9. Terminating a Session . . . . . . . . . . . . . . . . . . . 8 4.5. Environment Variable Passing . . . . . . . . . . . . . . . . 8
4. X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.6. Starting Shell or Command . . . . . . . . . . . . . . . . . 9
5. Authentication Agent Forwarding . . . . . . . . . . . . . . . . 8 4.7. Session Data Transfer . . . . . . . . . . . . . . . . . . . 9
6. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . . 9 4.8. Window Change Message . . . . . . . . . . . . . . . . . . . 9
6.1. Requesting Port Forwarding . . . . . . . . . . . . . . . . . 9 4.9. Local Flow Control . . . . . . . . . . . . . . . . . . . . . 10
6.2. Opening a Forwarded Connection . . . . . . . . . . . . . . . 9 4.10. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 10
7. FTP Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.11. Returning Exit Status . . . . . . . . . . . . . . . . . . . 10
8. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . . 10 5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . . 11
9. Summary of Message Numbers . . . . . . . . . . . . . . . . . . . 14 5.1. Requesting Port Forwarding . . . . . . . . . . . . . . . . . 11
10. Address of Author . . . . . . . . . . . . . . . . . . . . . . . 15 5.2. TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 11
6. FTP Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . 12
7. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . . 12
8. Summary of Message Numbers . . . . . . . . . . . . . . . . . . . 16
9. Security Considerations . . . . . . . . . . . . . . . . . . . . 16
10. Address of Author . . . . . . . . . . . . . . . . . . . . . . . 17
1. Introduction 1. Introduction
This protocol has been designed to run over the SSH transport layer and This protocol has been designed to run over the SSH transport layer and
user authentication protocols. The service name for this protocol user authentication protocols. The service name for this protocol
(after user authentication) is "ssh-connection". It provides (after user authentication) is "ssh-connection". 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. TCP/IP connections, and forwarded X11 connections.
2. Channel Mechanism 2. 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. All such requests use the
following format.
byte SSH_MSG_GLOBAL_REQUEST
string request name
boolean want_reply
... request-specific data follows
The recipient will respond to this message with SSH_MSG_REQUEST_SUCCESS,
SSH_MSG_REQUEST_FAILURE, or some request-specific continuation messages.
If the recipient does not recognize or support the request, it simply
responds with SSH_MSG_REQUEST_FAILURE.
byte SSH_MSG_REQUEST_SUCCESS
byte SSH_MSG_REQUEST_FAILURE
3. Channel Mechanism
All terminal sessions, forwarded connections, etc. are channels. Either All terminal sessions, forwarded connections, etc. are channels. Either
side may open a channel. Multiple channels are multiplexed on the side may open a channel. Multiple channels are multiplexed on the
single connection. single connection.
There are several ways to open a channel; typically the method used
depends on the intended use of the channel. After opening, however,
different channels use the same mechanisms for communication.
Channels are identified by numbers at each end. The number referring to 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 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 sender's channel number. Any other channel-related messages
contain the recipient's channel number for the channel. contain the recipient's channel number for the channel.
All channel-related messages contain the number of the channel they
refer to.
Channels are flow-controlled. No data may be sent to a channel until a Channels are flow-controlled. No data may be sent to a channel until a
message is received to indicate that window space is available. message is received to indicate that window space is available.
2.1. Opening a Channel 3.1. Opening a Channel
Regardless of the method used to open a channel, when a side wishes to When either side wishes to open a new channel, it allocates a local
open a channel, it allocates a local number for the channel. It then number for the channel. It then sends the following message to the
sends a method-specific message to the other side, and includes the other side, and includes the local channel number and initial window
local channel number and initial window size in the message. The remote size in the message.
side then decides whether it can open the channel, and responds with
either
vlint32 SSH_MSG_CHANNEL_OPEN_CONFIRMATION byte SSH_MSG_CHANNEL_OPEN
vlint32 recipient_channel string channel type
vlint32 sender_channel uint32 sender_channel
vlint32 initial_window_size uint32 initial_window_size
uint32 max_packet_size
... channel type specific data follows
The channel type is a name as described in the transport layer protocol,
with similar extension mechanisms (the domain name suffic convention).
Sender_channel is a local identifier for the channel used by the sender
of this message. Initial_window_size specifies how many bytes of
channel data can be sent to the sender of this message without adjusting
the window. Max_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
byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION
uint32 recipient_channel
uint32 sender_channel
uint32 initial_window_size
uint32 max_packet_size
... channel type specific data follows
where recipient_channel is the channel number given in the original open where recipient_channel is the channel number given in the original open
request, and sender_channel is the channel number allocated by the other request, and sender_channel is the channel number allocated by the other
side, or side, or
vlint32 SSH_MSG_CHANNEL_OPEN_FAILURE byte SSH_MSG_CHANNEL_OPEN_FAILURE
vlint32 recipient_channel uint32 recipient_channel
uint32 reason_code
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 following reason codes are defined:
#define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1
#define SSH_OPEN_CONNECT_FAILED 2
#define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3
#define SSH_OPEN_RESOURCE_SHORTAGE 4
3.2. Data Transfer
The window size specifies how many characters the other party can send The window size specifies how many characters the other party can send
before it must wait for the window to be adjusted. Both parties use the before it must wait for the window to be adjusted. Both parties use the
following message to adjust the window. following message to adjust the window.
vlint32 SSH_MSG_CHANNEL_WINDOW_ADJUST byte SSH_MSG_CHANNEL_WINDOW_ADJUST
vlint32 recipient_channel uint32 recipient_channel
vlint32 bytes_to_add uint32 bytes_to_add
Upon receiving this message, the recipient increases the number of bytes Upon receiving this message, the recipient increases the number of bytes
it is allowed to send by the given amount. it is allowed to send by the given amount.
2.2. Data Transfer
Data transfer is done with messages of the following type. Data transfer is done with messages of the following type.
vlint32 SSH_MSG_CHANNEL_DATA byte SSH_MSG_CHANNEL_DATA
vlint32 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 the current window size. The
window size is decremented by the amount of data sent. window size is decremented by the amount of data sent.
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 can example of this is stderr data from interactive sessions. Such data can
be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a separate be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a separate
integer specifies the type of the data. The available types and their integer specifies the type of the data. The available types and their
interpretation depend on the type of the channel. interpretation depend on the type of the channel.
vlint32 SSH_MSG_CHANNEL_EXTENDED_DATA byte SSH_MSG_CHANNEL_EXTENDED_DATA
vlint32 recipient_channel uint32 recipient_channel
vlint32 data_type_code uint32 data_type_code
string data string data
Data sent with these messages consumes the same window as ordinary data. Data sent with these messages consumes the same window as ordinary data.
Currently, only the following type is defined. Currently, only the following type is defined.
#define SSH_EXTENDED_DATA_STDERR 1 #define SSH_EXTENDED_DATA_STDERR 1
2.3. Closing a Channel 3.3. Closing a Channel
When a party will no longer send more data to a channel, it should send When a party will no longer send more data to a channel, it should send
SSH_MSG_CHANNEL_EOF. SSH_MSG_CHANNEL_EOF.
vlint32 SSH_MSG_CHANNEL_EOF byte SSH_MSG_CHANNEL_EOF
vlint32 recipient_channel uint32 recipient_channel
No explicit response is sent to this message; however, the application 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 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 the channel remains open after this message, and more data may still be
sent in the other direction. 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 When either party wishes to terminate the channel, it sends
SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party must send 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 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 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 has both sent and received SSH_MSG_CHANNEL_CLOSE, and the party may then
reuse the channel number. It is legal to send SSH_MSG_CHANNEL_CLOSE reuse the channel number. It is legal to send SSH_MSG_CHANNEL_CLOSE
without having sent or received SSH_MSG_EOF. without having sent or received SSH_MSG_EOF.
vlint32 SSH_MSG_CHANNEL_CLOSE byte SSH_MSG_CHANNEL_CLOSE
vlint32 recipient_channel uint32 recipient_channel
3. Sessions This message does not consume window space and can be sent even if no
window space is available.
A session is a remote execution of a command. The command may be an It is recommended that any data sent before this message be delivered to
the actual destination, if possible. This message should not normally
flush buffers.
3.4. Channel-Specific Requests
Many channel types have extensions that are specific to that particular
channel type. An example is requesting a pty for an interactive
session.
All channel-specific requests use the following format.
byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient_channel
string request type
boolean want_reply
... type-specific data
If want_reply is FALSE, no response will be sent to the request.
Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS or
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.
Request names are local to each channel type (it is recommended that
names with the same extension rules again be used).
The client is allowed to send further messages without waiting for the
response to the request.
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.
4. Interactive Sessions
A session is a remote execution of a command. The command may be a
shell, a program, or some built-in subsystem. It may or may not have a shell, a program, or some built-in subsystem. It may or may not have a
tty, and may or may not involve X11 forwarding. Multiple sessions can tty, and may or may not involve X11 forwarding. Multiple sessions can
be active simultaneously. be active simultaneously.
A session is created by SSH_MSG_CHANNEL_CREATE_SESSION. Then, the 4.1. Opening a Session
client may send preparatory requests for the session, such as starting
X11 forwarding or allocating a pseudo-terminal. Finally, the client
requests to execute a command or to start an interactive shell.
3.1. Opening a Session
A session is started by sending the following message. While this A session is started by sending the following message. While this
message can be sent by either side, it is normally recommended for message can be sent by either side, it is normally recommended for
clients not to permit opening new sessions to avoid a corrupt server clients not to permit opening new sessions to avoid a corrupt server
from attacking clients. from attacking clients.
vlint32 SSH_MSG_CHANNEL_CREATE_SESSION byte SSH_MSG_CHANNEL_OPEN
vlint32 sender_channel string "session"
uint32 sender_channel
The server allocates a channel number and responds with open uint32 initial_window_size
confirmation or open failure. uint32 max_packet_size
3.2. Requesting a Pseudo-Terminal 4.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.
vlint32 SSH_MSG_SESSION_REQUEST_PTY byte SSH_MSG_CHANNEL_REQUEST
vlint32 recipient_channel (session) uint32 recipient_channel
string "pty-req"
boolean want_reply
string TERM environment variable value (e.g., vt100) string TERM environment variable value (e.g., vt100)
vlint32 terminal width, characters (e.g., 80) uint32 terminal width, characters (e.g., 80)
vlint32 terminal height, rows (e.g., 24) uint32 terminal height, rows (e.g., 24)
vlint32 terminal width, pixels (e.g., 480) uint32 terminal width, pixels (e.g., 480)
vlint32 terminal height, pixels (e.g., 640) uint32 terminal height, pixels (e.g., 640)
string encoded terminal modes string encoded terminal modes
The encoding of terminal modes is described in Section ``Encoding of The encoding of terminal modes is described in Section ``Encoding of
Terminal Modes''. Terminal Modes''.
The server responds with either SSH_MSG_CHANNEL_SUCCESS or 4.3. X11 Forwarding
SSH_MSG_CHANNEL_FAILURE. The client is allowed to send further messages
without waiting for the response to this message.
vlint32 SSH_MSG_CHANNEL_SUCCESS
vlint32 recipient_channel
vlint32 SSH_MSG_CHANNEL_FAILURE
vlint32 recipient_channel
3.3. Environment Variable Passing
Environment variables may be passed to the shell/command to be started
later. Typically, each machine will have a preconfigured set of
variables that it will allow. Since uncontrolled setting of environment
variables can be very dangerous, it is recommended that implementations
allow setting only variables whose names have been explicitly configured
to be allowed.
vlint32 SSH_MSG_SESSION_ENVIRONMENT_VARIABLE
vlint32 recipient_channel
string variable_name
string variable_value
The server responds with either SSH_MSG_CHANNEL_SUCCESS or
SSH_MSG_CHANNEL_FAILURE. The client is allowed to send further messages
without waiting for the response to this message.
3.4. Requesting X11 Forwarding 4.3.1. Requesting X11 Forwarding
X11 forwarding may be requested for a session by sending X11 forwarding may be requested for a session by sending
vlint32 SSH_MSG_SESSION_REQUEST_X11_FORWARDING byte SSH_MSG_CHANNEL_REQUEST
vlint32 recipient_channel (session) uint32 recipient_channel
string "x11-req"
boolean want_reply
boolean single_connection
string x11_authentication_protocol string x11_authentication_protocol
string x11_authentication_cookie string x11_authentication_cookie
vlint32 x11_screen_number uint32 x11_screen_number
It is recommended that the authentication cookie that is sent be a fake, It is recommended that the authentication cookie that is sent be a fake,
random cookie, and that the cookie is checked and replaced by the real random cookie, and that the cookie is checked and replaced by the real
cookie when a connection request is received. cookie when a connection request is received.
The server responds with either SSH_MSG_CHANNEL_SUCCESS or X11 connection forwarding should stop when the session channel is
SSH_MSG_CHANNEL_FAILURE. The client is allowed to send futher messages closed; however, already opened forwardings should not be automatically
without waiting for the reponse to this message. 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.
3.5. Requesting Athentication Agent Forwarding 4.3.2. X11 Channels
Forwarded X11 connections are normal channels, independent of the
session that originated them. X11 channels are opened with a normal
channel open request. The resulting channels are independent of the
session, and closing the session channel does not imply closing
forwarded X11 channels.
byte SSH_MSG_CHANNEL_OPEN
string "x11"
uint32 sender_channel
uint32 initial_window_size
uint32 max_packet_size
string originator_string
The recipient should respond with open confirmation or open failure.
Originator_string is a free-form implementation-dependent description of
the X11 client that made the connection. It should typically contain
the IP address and port of the client, and may also contain user name or
other information if available. It should be in a format that is
understandable by a user.
4.4. Authentication Agent Forwarding
4.4.1. Requesting Athentication Agent Forwarding
Authentication agent forwarding may be requested for a session by Authentication agent forwarding may be requested for a session by
sending sending
vlint32 SSH_MSG_SESSION_REQUEST_AGENT_FORWARDING byte SSH_MSG_CHANNEL_REQUEST
vlint32 recipient_channel (session) uint32 recipient_channel
string "auth-agent-req"
boolean want_reply
The server responds with either SSH_MSG_CHANNEL_SUCCESS or The server responds with either SSH_MSG_CHANNEL_SUCCESS or
SSH_MSG_CHANNEL_FAILURE. The client is allowed to send futher messages SSH_MSG_CHANNEL_FAILURE (if want_reply is TRUE). The client is allowed
without waiting for the reponse to this message. to send futher messages without waiting for the reponse to this message.
3.6. Starting Shell or Command 4.4.2. Authentication Agent Channels
When an application requests a connection to the authentication agent,
the following message is sent to the originator of the session.
byte SSH_MSG_CHANNEL_OPEN
string "auth-agent"
uint32 sender_channel
uint32 initial_window_size
uint32 max_packet_size
The recipient should respond with open confirmation or open failure.
4.5. Environment Variable Passing
Environment variables may be passed to the shell/command to be started
later. Typically, each machine will have a preconfigured set of
variables that it will allow. Since uncontrolled setting of environment
variables can be very dangerous, it is recommended that implementations
allow setting only variables whose names have been explicitly configured
to be allowed.
byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient_channel
string "env"
boolean want_reply
string variable_name
string variable_value
4.6. Starting Shell or Command
Once the session has been set up, a shell or command is started at the Once the session has been set up, a shell or command is started at the
remote end. This can happen in any of a number of ways. remote end. This can happen in any of a number of ways. Only one of
these requests can succeed per channel.
vlint32 SSH_MSG_SESSION_EXEC_SHELL byte SSH_MSG_CHANNEL_REQUEST
vlint32 recipient_channel uint32 recipient_channel
string "shell"
boolean want_reply
vlint32 SSH_MSG_SESSION_EXEC_COMMAND byte SSH_MSG_CHANNEL_REQUEST
vlint32 recipient_channel uint32 recipient_channel
string "exec"
boolean want_reply
string command string command
vlint32 SSH_MSG_SESSION_EXEC_PREDEFINED byte SSH_MSG_CHANNEL_REQUEST
vlint32 recipient_channel uint32 recipient_channel
vlint32 subsystem_name string "subsystem"
boolean want_reply
string subsystem_name
This last form executes a predefined subsystem. It expected that these This last form executes a predefined subsystem. It expected that these
will include a general file transfer mechanism, and possibly other will include a general file transfer mechanism, and possibly other
features. Implementations may also allow configuring more such features. Implementations may also allow configuring more such
mechanisms. Having a special message for them avoids the need to have mechanisms. Having a special message for them avoids the need to have
their paths and command names be supplied by the other side. This also their paths and command names be supplied by the other side. This also
makes it easier to implement them in the same executable as the rest of makes it easier to implement them in the same executable as the rest of
the protocol on platforms where that is desirable. the protocol on platforms where that is desirable.
3.7. Session Data Transfer It is strongly recommended to request and check the reply for these
messages.
4.7. 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 stderr extended data type SSH_EXTENDED_DATA_STDERR has been defined for stderr
data. data.
3.8. Additional Control Messages 4.8. Window Change Message
Smooth operation sometimes requires extra messages to be passed to
notify the other side of some event or change.
A single message type, SSH_MSG_SESSION_NOTIFICATION has been defined for
all of these notifications. Implementations should ignore all
notifications that they cannot interpret, and are free to ignore any
notifications.
vlint32 SSH_MSG_SESSION_NOTIFICATION
vlint32 recipient_channel
string notification_type
...
Currently, the following notification types have been defined:
window_change Window size changed
xon_xoff_flow_control Local flow control
3.8.1. Window Change Message
When the window (terminal) size changes on the client side (client here When the window (terminal) size changes on the client side (client here
means the party who sent the create message for the session), it may means the party who sent the create message for the session), it may
send a message to the other side to inform it of the new size. send a message to the other side to inform it of the new size.
vlint32 SSH_MSG_SESSION_NOTIFICATION byte SSH_MSG_CHANNEL_REQUEST
vlint32 recipient_channel uint32 recipient_channel
string "window_change" string "window-change"
vlint32 terminal width, columns boolean FALSE
vlint32 terminal height, rows uint32 terminal width, columns
vlint32 terminal width, pixels uint32 terminal height, rows
vlint32 terminal height, pixels uint32 terminal width, pixels
uint32 terminal height, pixels
3.8.2. Local Flow Control No response is sent to this message.
4.9. 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 this is the case, it is using control-S control-Q flow control. When this is the case, it is
often desirable to do the flow control at the client end to speed up often desirable to do the flow control at the client end to speed up
responses to user requests. This is facilitated by the following two responses to user requests. This is facilitated by the following two
notifications. Initially, the server is responsible for flow control. notifications. Initially, the server is responsible for flow control.
(Here, again, client means the side originating the session, and server (Here, again, client means the side originating the session, and server
the other side.) the other side.)
vlint32 SSH_MSG_SESSION_NOTIFICATION The message below is used by the server to inform the client when it can
vlint32 recipient_channel or cannot perform flow control (control-S/control-Q processing). If
string "xon_xoff_flow_control" client_can_do is true, the client is allowed to do flow control using
control-S and control-Q. The client is allowed to ignore this message.
byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient_channel
string "xon-xoff"
boolean FALSE
boolean client_can_do boolean client_can_do
If client_can_do is true, the client (originator) can do control-S If client_can_do is true, the client (originator) can do control-S
control-Q flow control locally. control-Q flow control locally.
3.9. Terminating a Session No response is sent to this message.
When the command running at the other end terminates,
SSH_MSG_SESSION_EXIT_STATUS may be sent to return the exit status of the
command. Returning the status is optional, but recommended. No
acknowledgement is sent for this message. The channel needs to be
closed with SSH_MSG_CHANNEL_CLOSE after this message.
vlint32 SSH_MSG_SESSION_EXIT_STATUS
vlint32 recipient_channel
vlint32 exit_status
4. X11 Forwarding
X11 forwarding is requested with respect to a session. However,
forwarded connections are independent of the session.
The request to forward X11 connections opens a fake X11 display on the
server. No connections are opened at this time.
When an X11 client connects the fake X11 server, a request is sent to
the originator of the session.
vlint32 SSH_MSG_X11_OPEN 4.10. Signals
vlint32 sender_channel
vlint32 initial_window_size
string originator_string
The recipient should respond with open confirmation or open failure. A signal can be delivered to the remote process/service using the
Originator_string is a free-form implementation-dependent description of following message. Some systems may not implement signals, in which
the X11 client that made the connection. It should typically contain case they will ignore this message.
the IP address and port of the client, and may also contain user name or
other information if available. It should be in a format that is
understandable by a user.
5. Authentication Agent Forwarding byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient_channel
string "signal"
boolean FALSE
uint32 signal_number
Authentication agent forwarding is requested with respect to a session. 4.11. Returning Exit Status
However, forwarded connections are independent of the session.
When an application requests a connection to the authentication agent, When the command running at the other end terminates, The following
the following message is sent to the originator of the session. message may be sent to return the exit status of the command. Returning
the status is optional, but recommended. No acknowledgement is sent for
this message. The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE
after this message.
vlint32 SSH_MSG_AGENT_OPEN byte SSH_MSG_CHANNEL_REQUEST
vlint32 sender_channel uint32 recipient_channel
vlint32 initial_window_size string "exit-status"
string originator_string string FALSE
string host_chain uint32 exit_status
The recipient should respond with open confirmation or open failure. The remote command may also terminate violently due to a signal. Such a
Originator_string is a free-form implementation-dependent description of condition can be indicated by the following message.
the application that made the connection, or empty if no description is
available. host_chain is a comma-separated list of hosts this request
has passed through. (Receiver of the message appends the sender's name,
if the message will be passed on (i.e. receiver is not the actual
agent).)
Because only one application can use a forwarded agent channel at a byte SSH_MSG_CHANNEL_REQUEST
time, multiple channels cannot be multiplexed in a ssh daemon. Instead, uint32 recipient_channel
ssh daemon must pass the request, and forward the reply all the way from string "exit-signal"
the agent to the requesting application. This results in creation of a string FALSE
private channel for application using the agent. Agent stores the host uint32 signal number
chain for every channel and uses it to determine which operations are boolean core dumped
permitted.
6. TCP/IP Port Forwarding 5. TCP/IP Port Forwarding
6.1. Requesting Port Forwarding 5.1. Requesting Port Forwarding
A party need not explicitly request forwardings from its own end to the A party need not explicitly request forwardings from its own end to the
other direction. However, it if wishes to have connections to a port on other direction. However, it if wishes to have connections to a port on
the other side be forwarded to the local side, it must explicitly the other side be forwarded to the local side, it must explicitly
request this. request this.
vlint32 SSH_MSG_REQUEST_TCPIP_PORT_FORWARDING byte SSH_MSG_GLOBAL_REQUEST
string "tcpip-forward"
boolean want_reply
string address_to_bind string address_to_bind
vlint32 port_number_to_bind uint32 port_number_to_bind
Address_to_bind and port_number_to_bind specify the IP address and port Address_to_bind and port_number_to_bind specify the IP address and port
to which the socket to be listened is bound. The address should be to which the socket to be listened is bound. The address should be
"0.0.0.0" if connections are allowed from anywhere. (Note that the "0.0.0.0" if connections are allowed from anywhere. (Note that the
client can still filter connections based on information passed in the client can still filter connections based on information passed in the
open request.) 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.
The recipient will respond to this message with either A port forwarding can be cancelled with the following message. Note
SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE. that channel open requests may be received until a reply to this message
is received.
vlint32 SSH_MSG_REQUEST_SUCCESS
vlint32 SSH_MSG_REQUEST_FAILURE byte SSH_MSG_GLOBAL_REQUEST
string "cancel-tcpip-forward"
boolean want_reply
string address_to_bind
uint32 port_number_to_bind
6.2. Opening a Forwarded Connection 5.2. TCP/IP Forwarding Channels
When a connection comes to a port for which forwarding was requested When a connection comes to a port for which remote forwarding has been
with SSH_MSG_REQUEST_TCPIP_PORT_FORWARDING, the following message is requested, a channel is opened to forward the port to the other side.
sent to the other side.
vlint32 SSH_MSG_TCPIP_REMOTE_PORT_OPEN byte SSH_MSG_CHANNEL_OPEN
vlint32 sender_channel string "forwarded-tcpip"
vlint32 initial_window_size uint32 sender_channel
vlint32 port_that_was_connected uint32 initial_window_size
uint32 max_packet_size
string address_that_was_connected
uint32 port_that_was_connected
string originator_ip_address string originator_ip_address
vlint32 originator_port uint32 originator_port
string originator_string string originator_string
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 explicitly may be sent also for ports for which no forwarding has been explicitly
requested. The receiving side must decide whether to allow the requested. The receiving side must decide whether to allow the
forwarding. forwarding.
vlint32 SSH_MSG_TCPIP_PORT_OPEN byte SSH_MSG_CHANNEL_OPEN
vlint32 sender_channel string "direct-tcpip"
vlint32 initial_window_size uint32 sender_channel
uint32 initial_window_size
uint32 max_packet_size
string host_to_connect string host_to_connect
vlint32 port_to_connect uint32 port_to_connect
string originator_ip_address string originator_ip_address
vlint32 originator_port uint32 originator_port
string originator_string string originator_string
Host_to_connect and port_to_connect specify the TCP/IP host and port Host_to_connect and port_to_connect specify the TCP/IP host and port
where the recipient should connect the channel. Host_to_connect may be where the recipient should connect the channel. Host_to_connect may be
either a domain name or a numeric IP address. either a domain name or a numeric IP address.
Originator_ip_address is the numeric IP address of the machine where the Originator_ip_address is the numeric IP address of the machine where the
connection request comes from, and originator_port is the port on the connection request comes from, and originator_port is the port on the
originator host from where the connection came from. Originator_string originator host from where the connection came from. Originator_string
is a free-form description of where the connection came in a form that is a free-form description of where the connection came in a form that
can be displayed to the user. can be displayed to the user.
7. FTP Forwarding Forwarded TCP/IP channels are independent of any sessions, and closing a
session channel does not in any way imply that forwarded connections
should be closed.
6. FTP Forwarding
XXX XXX
8. Encoding of Terminal Modes 7. Encoding of Terminal Modes
Terminal modes (as passed in SSH_MSG_SESSION_REQUEST_PTY) are encoded Terminal modes (as passed in a pty request) are encoded into a byte
into a byte stream. It is intended that the coding be portable across stream. It is intended that the coding be portable across different
different environments. environments.
The tty mode description is a stream of bytes. The stream consists of The tty mode description is a stream of bytes. The stream consists of
opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). opcode-argument pairs. It is terminated by opcode TTY_OP_END (0).
Opcodes 1-127 have one-byte arguments. Opcodes 128-159 have 32-bit Opcodes 1-127 have one-byte arguments. Opcodes 128-159 have 32-bit
integer arguments (stored msb first). Opcodes 160-255 are not yet integer arguments (stored msb first). Opcodes 160-255 are not yet
defined, and cause parsing to stop (they should only be used after any defined, and cause parsing to stop (they should only be used after any
other data). other data).
The client puts in the stream any modes it knows about, and the server The client puts in the stream any modes it knows about, and the server
ignores any modes it does not know about. This allows some degree of ignores any modes it does not know about. This allows some degree of
machine-independence, at least between systems that use a POSIX-like tty machine-independence, at least between systems that use a POSIX-like tty
interface. The protocol can support other systems as well, but the interface. The protocol can support other systems as well, but the
client may need to fill reasonable values for a number of parameters so client may need to fill reasonable values for a number of parameters so
the server pty gets set to a reasonable mode (the server leaves all the server pty gets set to a reasonable mode (the server leaves all
unspecified mode bits in their default values, and only some unspecified mode bits in their default values, and only some
combinations make sense). combinations make sense).
The following opcodes have been defined. The naming of opcodes mostly The following opcodes have been defined. The naming of opcodes mostly
follows the POSIX terminal mode flags. follows the POSIX terminal mode flags.
0 TTY_OP_END 0 TTY_OP_END
skipping to change at page 14, line 18 skipping to change at page 16, line 29
91 CS8 91 CS8
8 bits. 8 bits.
92 PARENB 92 PARENB
Parity enable. Parity enable.
93 PARODD 93 PARODD
Odd parity, else even. Odd parity, else even.
192 TTY_OP_ISPEED 128 TTY_OP_ISPEED
Specifies the input baud rate in bits per second (as a 32-bit int, Specifies the input baud rate in bits per second (as a 32-bit int,
msb first). msb first).
193 TTY_OP_OSPEED 129 TTY_OP_OSPEED
Specifies the output baud rate in bits per second (as a 32-bt int, Specifies the output baud rate in bits per second (as a 32-bt int,
msb first). msb first).
9. Summary of Message Numbers 8. Summary of Message Numbers
The following message numbers are used by this protocol. If an #define SSH_MSG_GLOBAL_REQUEST 30
unrecognized message is received, SSH_MSG_REQUEST_FAILURE should be sent #define SSH_MSG_REQUEST_SUCCESS 31
in response. #define SSH_MSG_REQUEST_FAILURE 32
#define SSH_MSG_CHANNEL_OPEN 33
#define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 34
#define SSH_MSG_CHANNEL_OPEN_FAILURE 35
#define SSH_MSG_CHANNEL_WINDOW_ADJUST 36
#define SSH_MSG_CHANNEL_DATA 37
#define SSH_MSG_CHANNEL_EXTENDED_DATA 38
#define SSH_MSG_CHANNEL_EOF 39
#define SSH_MSG_CHANNEL_CLOSE 40
#define SSH_MSG_CHANNEL_REQUEST 41
#define SSH_MSG_CHANNEL_SUCCESS 42
#define SSH_MSG_CHANNEL_FAILURE 43
#define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 40 9. Security Considerations
#define SSH_MSG_CHANNEL_OPEN_FAILURE 41
#define SSH_MSG_CHANNEL_WINDOW_ADJUST 42 This protocol is assumed to run on top of a secure, authenticated
#define SSH_MSG_CHANNEL_DATA 43 protocol. User authentication and protection against network-level
#define SSH_MSG_CHANNEL_EOF 44
#define SSH_MSG_CHANNEL_CLOSE 45 attacks are assumed to be provided by the underlying protocol.
#define SSH_MSG_CHANNEL_CREATE_SESSION 46
#define SSH_MSG_SESSION_REQUEST_PTY 47 This protocol can, however, be used to execute commands on remote
#define SSH_MSG_CHANNEL_SUCCESS 48 machines. The protocol also permits the server to run commands on the
#define SSH_MSG_CHANNEL_FAILURE 49 client. Implementations may wish to disallow this to prevent an
#define SSH_MSG_SESSION_ENVIRONMENT_VARIABLE 50 attacker from coming from the server machine to the client machine.
#define SSH_MSG_SESSION_REQUEST_X11_FORWARDING 51
#define SSH_MSG_SESSION_REQUEST_AGENT_FORWARDING 52 X11 forwarding provides major security improvements over normal cookie-
#define SSH_MSG_SESSION_EXEC_SHELL 53 based X11 forwarding. The cookie never needs to be transmitted in the
#define SSH_MSG_SESSION_EXEC_COMMAND 54 clear, and traffic is encrypted and integrity-protected. No useful
#define SSH_MSG_SESSION_EXEC_PREDEFINED 55 authentication data will remain on the server machine after the
#define SSH_MSG_SESSION_NOTIFICATION 56 connection has been closed. On the other hand, in some situations a
#define SSH_MSG_SESSION_EXIT_STATUS 57 forwarded X11 connection might be used to get access to the local X
#define SSH_MSG_X11_OPEN 58 server across security perimeters.
#define SSH_MSG_AGENT_OPEN 59
#define SSH_MSG_REQUEST_TCPIP_PORT_FORWARDING 60 Port forwardings can potentially allow an intruder to cross security
#define SSH_MSG_REQUEST_SUCCESS 61 perimeters such as firewalls. They do not offer anything fundamentally
#define SSH_MSG_REQUEST_FAILURE 62 new that a user couldn't do otherwise; however, they make opening
#define SSH_MSG_TCPIP_REMOTE_PORT_OPEN 63 tunnels very easy. Implementations should allow policy control over
#define SSH_MSG_TCPIP_PORT_OPEN 64 what can be forwarded. Administrators should be able to deny
forwardings where appropriate.
Since this protocol normally runs inside an encrypted tunnel, firewalls
will not be able to examine the traffic.
10. Address of Author 10. Address of Author
Tatu Ylonen Tatu Ylonen
SSH Communications Security Ltd. SSH Communications Security Ltd.
Tekniikantie 12 Tekniikantie 12
FIN-02150 ESPOO FIN-02150 ESPOO
Finland Finland
E-mail: ylo@ssh.fi E-mail: ylo@ssh.fi
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/