draft-ietf-secsh-connect-03.txt   draft-ietf-secsh-connect-04.txt 
Network Working Group T. Ylonen Network Working Group T. Ylonen
INTERNET-DRAFT T. Kivinen INTERNET-DRAFT T. Kivinen
draft-ietf-secsh-connect-03.txt M. Saarinen draft-ietf-secsh-connect-04.txt M. Saarinen
Expires in six months SSH Expires in six months T. Rinne
7 November 1997 S. Lehtinen
SSH
6 August 1998
SSH Connection Protocol 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
at any time. It is inappropriate to use Internet-Drafts as reference at any time. It is inappropriate to use Internet-Drafts as reference
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), ftp.ietf.org (US East Coast),
or ftp.isi.edu (US West Coast). or ftp.isi.edu (US West Coast).
Abstract Abstract
SSH is a protocol for secure remote login and other secure network SSH is a protocol for secure remote login and other secure network ser-
services over an insecure network. vices over an insecure network. This document describes the SSH connec-
tion protocol. It provides interactive login sessions, remote execution
This document describes the SSH connection protocol. It provides of commands, forwarded TCP/IP connections, and forwarded X11 connec-
interactive login sessions, remote execution of commands, forwarded tions. All of these channels are multiplexed into a single encrypted
TCP/IP connections, and forwarded X11 connections. All of these tunnel. The SSH Connection Protocol has been designed to run on top of
channels are multiplexed into a single encrypted tunnel.
The SSH Connection Protocol has been designed to run on top of
the SSH transport layer and user authentication protocols. the SSH transport layer and user authentication protocols.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Global Requests . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Global Requests . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . . 3 3. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Opening a Channel . . . . . . . . . . . . . . . . . . . . . 3 3.1. Opening a Channel . . . . . . . . . . . . . . . . . . . . . 3
3.2. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 4
3.3. Closing a Channel . . . . . . . . . . . . . . . . . . . . . 5 3.3. Closing a Channel . . . . . . . . . . . . . . . . . . . . . 5
3.4. Channel-Specific Requests . . . . . . . . . . . . . . . . . 6 3.4. Channel-Specific Requests . . . . . . . . . . . . . . . . . 6
4. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . . 6 4. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . . 6
4.1. Opening a Session . . . . . . . . . . . . . . . . . . . . . 6 4.1. Opening a Session . . . . . . . . . . . . . . . . . . . . . 6
4.2. Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 7 4.2. Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 7
4.3. X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 7 4.3. X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 7
4.3.1. Requesting X11 Forwarding . . . . . . . . . . . . . . . 7 4.3.1. Requesting X11 Forwarding . . . . . . . . . . . . . . . 7
4.3.2. X11 Channels . . . . . . . . . . . . . . . . . . . . . . 8 4.3.2. X11 Channels . . . . . . . . . . . . . . . . . . . . . . 8
4.4. Authentication Agent Forwarding . . . . . . . . . . . . . . 8 4.4. Authentication Agent Forwarding . . . . . . . . . . . . . . 8
4.4.1. Requesting Authentication Agent Forwarding . . . . . . . 8 4.4.1. Requesting Authentication Agent Forwarding . . . . . . . 8
4.4.2. Authentication Agent Channels . . . . . . . . . . . . . 8 4.4.2. Authentication Agent Channels . . . . . . . . . . . . . 8
4.5. Environment Variable Passing . . . . . . . . . . . . . . . . 9 4.5. SSH1 Authentication Agent Forwarding . . . . . . . . . . . . 9
4.6. Starting a Shell or a Command . . . . . . . . . . . . . . . 9 4.5.1. Requesting SSH1 Authentication Agent Forwarding . . . . 9
4.7. Session Data Transfer . . . . . . . . . . . . . . . . . . . 10 4.5.2. SSH1 Authentication Agent Channels . . . . . . . . . . . 9
4.8. Window Dimension Change Message . . . . . . . . . . . . . . 10 4.6. Environment Variable Passing . . . . . . . . . . . . . . . . 9
4.9. Local Flow Control . . . . . . . . . . . . . . . . . . . . . 10 4.7. Starting a Shell or a Command . . . . . . . . . . . . . . . 10
4.10. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.8. Session Data Transfer . . . . . . . . . . . . . . . . . . . 10
4.11. Returning Exit Status . . . . . . . . . . . . . . . . . . . 11 4.9. Window Dimension Change Message . . . . . . . . . . . . . . 11
5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . . 11 4.10. Local Flow Control . . . . . . . . . . . . . . . . . . . . 11
4.11. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.12. Returning Exit Status . . . . . . . . . . . . . . . . . . . 12
5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . . 12
5.1. Requesting Port Forwarding . . . . . . . . . . . . . . . . . 12 5.1. Requesting Port Forwarding . . . . . . . . . . . . . . . . . 12
5.2. TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 12 5.2. TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 13
6. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . . 13 6. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . . 14
7. Summary of Message Numbers . . . . . . . . . . . . . . . . . . . 15 7. Summary of Message Numbers . . . . . . . . . . . . . . . . . . . 15
8. Security Considerations . . . . . . . . . . . . . . . . . . . . 15 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 16
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
10. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 16 10. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 17
1. Introduction 1. Introduction
The SSH Connection Protocol has been designed to run on top of the SSH The SSH Connection Protocol has been designed to run on top of the SSH
transport layer and user authentication protocols. It provides transport layer and user authentication protocols. 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. The service name for TCP/IP connections, and forwarded X11 connections. The service name for
this protocol (after user authentication) is "ssh-connection". this protocol (after user authentication) is "ssh-connection".
This document should be read only after reading the SSH architecture This document should be read only after reading the SSH architecture
skipping to change at page 4, line 25 skipping to change at page 4, line 28
... channel type specific data follows ... channel type specific data follows
where `recipient channel' is the channel number given in the original where `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, or the other side, or
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 additional textual information (ISO-10646 UTF-8 string additional textual information (ISO-10646 UTF-8
[[RFC-2044]]) [RFC-2044])
string language tag (as defined in [[RFC-1766]]) string language tag (as defined in [RFC-1766])
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 additional SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional
information to the user. If this is done, the client software should information to the user. If this is done, the client software should
take the precautions discussed in [SSH-ARCH]. take the precautions discussed in [SSH-ARCH].
The following reason codes are defined: The following reason codes are defined:
#define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1
skipping to change at page 9, line 5 skipping to change at page 9, line 7
When an application requests a connection to the authentication agent, When an application requests a connection to the authentication agent,
the following message is sent to the originator of the session. the following message is sent to the originator of the session.
byte SSH_MSG_CHANNEL_OPEN byte SSH_MSG_CHANNEL_OPEN
string "auth-agent" string "auth-agent"
uint32 sender channel uint32 sender channel
uint32 initial window size uint32 initial window size
uint32 maximum packet size uint32 maximum packet size
The recipient should respond with open confirmation or open failure. The recipient SHOULD respond with open confirmation or open failure.
Implementations MUST reject any agent channel open requests if they have Implementations MUST reject any agent channel open requests if they have
not requested agent forwarding. not requested agent forwarding.
4.5. Environment Variable Passing 4.5. SSH1 Authentication Agent Forwarding
Implementations MAY support ssh1 authentication agent forwarding in
order to provide compatibility with old ssh versions.
4.5.1. Requesting SSH1 Authentication Agent Forwarding
Authentication agent forwarding may be requested for a session by
sending
byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "auth-ssh1-agent-req"
boolean want reply
The server responds with either SSH_MSG_CHANNEL_SUCCESS or
SSH_MSG_CHANNEL_FAILURE (if `want reply' is TRUE). The client MAY send
further messages without waiting for the response to this message.
4.5.2. SSH1 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-ssh1-agent"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
The recipient SHOULD respond with open confirmation or open failure.
Implementations MUST reject any agent channel open requests if they have
not requested ssh1 agent forwarding.
4.6. Environment Variable Passing
Environment variables may be passed to the shell/command to be started Environment variables may be passed to the shell/command to be started
later. Typically, each machine will have a preconfigured set of later. Typically, each machine will have a preconfigured set of
variables that it will allow. Since uncontrolled setting of environment variables that it will allow. Since uncontrolled setting of environment
variables can be very dangerous, it is recommended that implementations variables can be very dangerous, it is recommended that implementations
allow setting only variables whose names have been explicitly configured allow setting only variables whose names have been explicitly configured
to be allowed. to be allowed.
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
4.6. Starting a Shell or a Command 4.7. 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. Program can be a shell, an application program or a subsystem with end. Program can be a shell, an application program or a subsystem with
a host-independent name. Only one of these requests can succeed per a host-independent name. Only one of these requests can succeed per
channel. 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
skipping to change at page 10, line 16 skipping to change at page 10, line 53
features. Implementations may also allow configuring more such features. Implementations may also allow configuring more such
mechanisms. mechanisms.
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 SHOULD be starting a shell or a program. All input and output from these SHOULD be
redirected the the channel or to the encrypted tunnel. redirected the the channel or to the encrypted tunnel.
It is RECOMMENDED to request and check the reply for these messages. The It is RECOMMENDED to request and check the reply for these messages. The
client SHOULD ignore these messages. client SHOULD ignore these messages.
4.7. Session Data Transfer 4.8. 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.
4.8. Window Dimension Change Message 4.9. Window Dimension Change Message
When the window (terminal) size changes on the client side, it MAY send 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. 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
No response SHOULD be sent to this message. No response SHOULD be sent to this message.
4.9. Local Flow Control 4.10. 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 allowed, using control-S control-Q flow control. When flow control is allowed,
it is often desirable to do the flow control at the client end to speed it is often desirable to do the flow control at the client end to speed
up responses to user requests. This is facilitated by the following up responses to user requests. This is facilitated by the following
notification. Initially, the server is responsible for flow control. notification. 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.)
The message below is used by the server to inform the client when it can The message below is used by the server to inform the client when it can
skipping to change at page 11, line 8 skipping to change at page 11, line 47
control-S and control-Q. The client MAY ignore this message. 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.
4.10. Signals 4.11. 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
uint32 signal number uint32 signal number
4.11. Returning Exit Status 4.12. 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. Returning message can be sent to return the exit status of the command. Returning
the status is RECOMMENDED. No acknowledgment is sent for this message. the status is RECOMMENDED. No acknowledgment is sent for this message.
The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE after this The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE after this
message. message.
The client SHOULD 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. Such a The remote command may also terminate violently due to a signal. Such a
condition can be indicated by the following message. A zero exit_status condition can be indicated by the following message. A zero exit_status
usually means that the command terminated successfully. usually means that the command terminated successfully.
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel uint32 recipient channel
string "exit-signal" string "exit-signal"
boolean FALSE boolean FALSE
uint32 signal number uint32 signal number
boolean core dumped boolean core dumped
string error message (ISO-10646 UTF-8 [[RFC-2044]]) string error message (ISO-10646 UTF-8 [RFC-2044])
string language tag (as defined in [[RFC-1766]]) string language tag (as defined in [RFC-1766])
The `error message' contains an additional explanation of the error The `error message' contains an additional explanation of the error
message. The message may consist of multiple lines. The client software message. The message may consist of multiple lines. The client software
MAY display this message to the user. MAY display this message to the user.
5. TCP/IP Port Forwarding 5. TCP/IP Port Forwarding
5.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
skipping to change at page 14, line 49 skipping to change at page 15, line 27
32 INPCK Enable checking of parity errors. 32 INPCK Enable checking of parity errors.
33 ISTRIP Strip 8th bit off characters. 33 ISTRIP Strip 8th bit off characters.
34 INLCR Map NL into CR on input. 34 INLCR Map NL into CR on input.
35 IGNCR Ignore CR on input. 35 IGNCR Ignore CR on input.
36 ICRNL Map CR to NL on input. 36 ICRNL Map CR to NL on input.
37 IUCLC Translate uppercase characters to lowercase. 37 IUCLC Translate uppercase characters to lowercase.
38 IXON Enable output flow control. 38 IXON Enable output flow control.
39 IXANY Any char will restart after stop. 39 IXANY Any char will restart after stop.
40 IXOFF Enable input flow control. 40 IXOFF Enable input flow control.
41 IMAXBEL Ring bell on input queue full. 41 IMAXBEL Ring bell on input queue full.
50 ISIG Enable signals INTR, QUIT, [[D]]SUSP. 50 ISIG Enable signals INTR, QUIT, [D]SUSP.
51 ICANON Canonicalize input lines. 51 ICANON Canonicalize input lines.
52 XCASE Enable input and output of uppercase characters by 52 XCASE Enable input and output of uppercase characters by
preceding their lowercase equivalents with `\'. preceding their lowercase equivalents with `\'.
53 ECHO Enable echoing. 53 ECHO Enable echoing.
54 ECHOE Visually erase chars. 54 ECHOE Visually erase chars.
55 ECHOK Kill character discards current line. 55 ECHOK Kill character discards current line.
56 ECHONL Echo NL even if ECHO is off. 56 ECHONL Echo NL even if ECHO is off.
57 NOFLSH Don't flush after interrupt. 57 NOFLSH Don't flush after interrupt.
58 TOSTOP Stop background jobs from output. 58 TOSTOP Stop background jobs from output.
59 IEXTEN Enable extensions. 59 IEXTEN Enable extensions.
60 ECHOCTL Echo control characters as ^(Char). 60 ECHOCTL Echo control characters as ^(Char).
61 ECHOKE Visual erase for line kill. 61 ECHOKE Visual erase for line kill.
62 PENDIN Retype pending input. 62 PENDIN Retype pending input.
70 OPOST Enable output processing. 70 OPOST Enable output processing.
71 OLCUC Convert lowercase to uppercase. 71 OLCUC Convert lowercase to uppercase.
72 ONLCR Map NL to CR-NL. 72 ONLCR Map NL to CR-NL.
73 OCRNL Translate carriage return to newline (output). 73 OCRNL Translate carriage return to newline (output).
74 ONOCR Translate newline to carriage return-newline 74 ONOCR Translate newline to carriage return-newline
skipping to change at page 17, line 4 skipping to change at page 17, line 36
FIN-02150 ESPOO FIN-02150 ESPOO
Finland Finland
E-mail: ylo@ssh.fi E-mail: ylo@ssh.fi
Tero Kivinen Tero Kivinen
SSH Communications Security Ltd. SSH Communications Security Ltd.
Tekniikantie 12 Tekniikantie 12
FIN-02150 ESPOO FIN-02150 ESPOO
Finland Finland
E-mail: kivinen@ssh.fi E-mail: kivinen@ssh.fi
Markku-Juhani O. Saarinen Markku-Juhani O. Saarinen
SSH Communications Security Ltd. SSH Communications Security Ltd.
Tekniikantie 12 Tekniikantie 12
FIN-02150 ESPOO FIN-02150 ESPOO
Finland Finland
E-mail: mjos@ssh.fi E-mail: mjos@ssh.fi
Timo J. Rinne
SSH Communications Security Ltd.
Tekniikantie 12
FIN-02150 ESPOO
Finland
E-mail: tri@ssh.fi
Sami Lehtinen
SSH Communications Security Ltd.
Tekniikantie 12
FIN-02150 ESPOO
Finland
E-mail: sjl@ssh.fi
 End of changes. 

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