draft-ietf-secsh-connect-09.txt   draft-ietf-secsh-connect-10.txt 
Network Working Group T. Ylonen Network Working Group T. Ylonen
INTERNET-DRAFT T. Kivinen INTERNET-DRAFT T. Kivinen
draft-ietf-secsh-connect-09.txt M. Saarinen draft-ietf-secsh-connect-10.txt M. Saarinen
Expires: 9 July, 2001 T. Rinne Expires: 2 September, 2001 T. Rinne
S. Lehtinen S. Lehtinen
SSH Communications Security SSH Communications Security
9 January, 2001 2 March, 2001
SSH Connection Protocol Secure Shell Connection Protocol
Status of This Memo Status of This Memo
This document is an Internet-Draft and is in full conformance This document is an Internet-Draft and is in full conformance
with all provisions of Section 10 of RFC2026. with all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as other groups may also distribute working documents as
Internet-Drafts. Internet-Drafts.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
"work in progress." "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
Abstract Abstract
SSH is a protocol for secure remote login and other secure network ser- The Secure Shell Remote Login Protocol is a protocol for secure remote
vices over an insecure network. This document describes the SSH Connec- login and other secure network services over an insecure network. This
tion Protocol. It provides interactive login sessions, remote execution document describes the Secure Shell 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 channels
tunnel. The SSH Connection Protocol has been designed to run on top of are multiplexed into a single encrypted tunnel. The Secure Shell Con-
the SSH transport layer and user authentication protocols. nection Protocol has been designed to run on top of the Secure Shell
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 . . . . . . . . . . . . . . . . . 5 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. Environment Variable Passing . . . . . . . . . . . . . . . . 8 4.4. Environment Variable Passing . . . . . . . . . . . . . . . . 8
4.5. Starting a Shell or a Command . . . . . . . . . . . . . . . 8 4.5. Starting a Shell or a Command . . . . . . . . . . . . . . . 8
4.6. Session Data Transfer . . . . . . . . . . . . . . . . . . . 9 4.6. Session Data Transfer . . . . . . . . . . . . . . . . . . . 9
4.7. Window Dimension Change Message . . . . . . . . . . . . . . 9 4.7. Window Dimension Change Message . . . . . . . . . . . . . . 9
4.8. Local Flow Control . . . . . . . . . . . . . . . . . . . . . 10 4.8. Local Flow Control . . . . . . . . . . . . . . . . . . . . . 10
4.9. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.9. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.10. Returning Exit Status . . . . . . . . . . . . . . . . . . . 10 4.10. Returning Exit Status . . . . . . . . . . . . . . . . . . . 10
5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . . 11 5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . . 11
5.1. Requesting Port Forwarding . . . . . . . . . . . . . . . . . 11 5.1. Requesting Port Forwarding . . . . . . . . . . . . . . . . . 12
5.2. TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 12 5.2. TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 12
6. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . . 13 6. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . . 13
7. Summary of Message Numbers . . . . . . . . . . . . . . . . . . . 15 7. Summary of Message Numbers . . . . . . . . . . . . . . . . . . . 15
8. Security Considerations . . . . . . . . . . . . . . . . . . . . 15 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 15
9. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . . . 16 9. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . . . 16
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16
11. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 16 11. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction 1. Introduction
The SSH Connection Protocol has been designed to run on top of the SSH The Secure Shell Connection Protocol has been designed to run on top of
transport layer and user authentication protocols. It provides the Secure Shell transport layer and user authentication protocols. It
interactive login sessions, remote execution of commands, forwarded provides interactive login sessions, remote execution of commands,
TCP/IP connections, and forwarded X11 connections. The service name for forwarded TCP/IP connections, and forwarded X11 connections. The
this protocol (after user authentication) is "ssh-connection". service name for 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 Secure Shell Remote
document [SSH-ARCH]. This document freely uses terminology and notation Login Protocol architecture document [SECSH-ARCH]. This document freely
from the architecture document without reference or further explanation. uses terminology and notation from the architecture document without
reference or further explanation.
2. Global Requests 2. Global Requests
There are several kinds of requests that affect the state of the remote 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 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 start TCP/IP forwarding for a specific port. All such requests use the
following format. following format.
byte SSH_MSG_GLOBAL_REQUEST byte SSH_MSG_GLOBAL_REQUEST
string request name (restricted to US-ASCII) string request name (restricted to US-ASCII)
boolean want reply boolean want reply
... request-specific data follows ... request-specific data follows
The recipient will respond to this message with SSH_MSG_REQUEST_SUCCESS, The recipient will respond to this message with SSH_MSG_REQUEST_SUCCESS,
SSH_MSG_REQUEST_FAILURE, or some request-specific continuation messages SSH_MSG_REQUEST_FAILURE, or some request-specific continuation messages
if `want reply' is TRUE. if `want reply' is TRUE.
skipping to change at page 3, line 49 skipping to change at page 3, line 51
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 (restricted to US-ASCII) string channel type (restricted to US-ASCII)
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 the SSH architecture The channel type is a name as described in the architecture document,
document, with similar extension mechanisms. `sender channel' is a local with similar extension mechanisms. `sender channel' is a local
identifier for the channel used by the sender of this message. `initial 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 window size' specifies how many bytes of channel data can be sent to the
sender of this message without adjusting the window. `Maximum packet sender of this message without adjusting the window. `Maximum packet
size' specifies the maximum size of an individual data packet that can 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 be sent to the sender (for example, one might want to use smaller
packets for interactive connections to get better interactive response packets for interactive connections to get better interactive response
on slow links). on slow 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 responds with either
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
skipping to change at page 4, line 30 skipping to change at page 4, line 33
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-2279]) [RFC-2279])
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 [SECSH-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
#define SSH_OPEN_CONNECT_FAILED 2 #define SSH_OPEN_CONNECT_FAILED 2
#define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3
#define SSH_OPEN_RESOURCE_SHORTAGE 4 #define SSH_OPEN_RESOURCE_SHORTAGE 4
3.2. Data Transfer 3.2. Data Transfer
skipping to change at page 7, line 57 skipping to change at page 8, line 4
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.
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 automatically closed; however, already opened forwardings should not be automatically
closed when the session channel is closed. 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 authentication The `x11 authentication protocol' is the name of the X11 authentication
method used, i.e. "MIT-MAGIC-COOKIE-1". method used, e.g. "MIT-MAGIC-COOKIE-1".
X Protocol is documented in [SCHEIFLER]. X Protocol is documented in [SCHEIFLER].
4.3.2. X11 Channels 4.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 channel channels are independent of the session, and closing the session channel
does not close the forwarded X11 channels. does not close the forwarded X11 channels.
byte SSH_MSG_CHANNEL_OPEN byte SSH_MSG_CHANNEL_OPEN
skipping to change at page 11, line 49 skipping to change at page 11, line 51
Additional signal names MAY be sent in the format "sig-name@xyz", where Additional signal names MAY be sent in the format "sig-name@xyz", where
`sig-name' and `xyz' may be anything a particular implementor wants `sig-name' and `xyz' may be anything a particular implementor wants
(except the `@' sign). However, it is suggested that if a `configure' (except the `@' sign). However, it is suggested that if a `configure'
script is used, the non-standard signal names it finds be encoded as script is used, the non-standard signal names it finds be encoded as
"SIG@xyz.config.guess", where `SIG' is the signal name without the "SIG" "SIG@xyz.config.guess", where `SIG' is the signal name without the "SIG"
prefix, and `xyz' be the host type, as determined by `config.guess'. prefix, and `xyz' be the host type, as determined by `config.guess'.
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. If this is done, the client MAY display this message to the user. If this is done, the client
software should take the precautions discussed in [SSH-ARCH]. software should take the precautions discussed in [SECSH-ARCH].
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
other direction. However, if it wishes that connections to a port on other direction. However, if it wishes that 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.
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
`Address to bind' and `port number to bind' specify the IP address and `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 port to which the socket to be listened is bound. The address should be
skipping to change at page 16, line 16 skipping to change at page 16, line 23
Since this protocol normally runs inside an encrypted tunnel, firewalls Since this protocol normally runs inside an encrypted tunnel, firewalls
will not be able to examine the traffic. will not be able to examine the traffic.
It is RECOMMENDED that implementations disable all the potentially It is RECOMMENDED that implementations disable all the potentially
dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP
forwarding) if the host key has changed. forwarding) if the host key has changed.
9. Trademark Issues 9. Trademark Issues
SSH is a registered trademark and Secure Shell is a trademark of SSH "ssh" is a registered trademark of SSH Communications Security Corp in
Communications Security Corp. SSH Communications Security Corp permits the United States and/or other countries.
the use of these trademarks as the name of this standard and protocol,
and permits their use to describe that a product conforms to this
standard, provided that the following acknowledgement is included where
the trademarks are used: ``SSH is a registered trademark and Secure
Shell is a trademark of SSH Communications Security Corp
(www.ssh.com)''. These trademarks may not be used as part of a product
name or in otherwise confusing manner without prior written permission
of SSH Communications Security Corp.
10. References 10. References
[RFC-1766] Alvestrand, H: "Tags for the Identification of Languages", [RFC-1766] Alvestrand, H: "Tags for the Identification of Languages",
March 1995. March 1995.
[RFC-1884] Hinden, R., and Deering, S: "IP Version 6 Addressing [RFC-1884] Hinden, R., and Deering, S: "IP Version 6 Addressing
Architecture", December 1995 Architecture", December 1995
[RFC-2279] Yergeau, F: "UTF-8, a transformation format of ISO 10646", [RFC-2279] Yergeau, F: "UTF-8, a transformation format of ISO 10646",
January 1998. January 1998.
[SCHEIFLER] Scheifler, R. W., et al: "X Window System : The Complete [SCHEIFLER] Scheifler, R. W., et al: "X Window System : The Complete
Reference to Xlib, X Protocol, Icccm, Xlfd", 3rd edition, Digital Press, Reference to Xlib, X Protocol, Icccm, Xlfd", 3rd edition, Digital Press,
ISBN 1555580882, February 1992. ISBN 1555580882, February 1992.
[POSIX] ISO/IEC Std 9945-1, ANSI/IEEE Std 1003.1 Information technology [POSIX] ISO/IEC Std 9945-1, ANSI/IEEE Std 1003.1 Information technology
-- Portable Operating System Interface (POSIX)-Part 1: System -- Portable Operating System Interface (POSIX)-Part 1: System
Application Program Interface (API) [C Language], July 1996. Application Program Interface (API) [C Language], July 1996.
[SSH-ARCH] Ylonen, T., et al: "SSH Protocol Architecture", Internet- [SECSH-ARCH] Ylonen, T., et al: "Secure Shell Remote Login Protocol
Draft, draft-ietf-secsh-architecture-07.txt Architecture", Internet-Draft, draft-ietf-secsh-architecture-08.txt
[SSH-TRANS] Ylonen, T., et al: "SSH Transport Layer Protocol", Internet-
Draft, draft-ietf-secsh-transport-09.txt
[SSH-USERAUTH] Ylonen, T., et al: "SSH Authentication Protocol", [SECSH-TRANS] Ylonen, T., et al: "Secure Shell Transport Layer
Internet-Draft, draft-ietf-secsh-userauth-09.txt Protocol", Internet-Draft, draft-ietf-secsh-transport-10.txt
[SECSH-USERAUTH] Ylonen, T., et al: "Secure Shell Authentication
Protocol", Internet-Draft, draft-ietf-secsh-userauth-10.txt
11. Authors' Addresses 11. Authors' Addresses
Tatu Ylonen Tatu Ylonen
SSH Communications Security Corp SSH Communications Security Corp
Fredrikinkatu 42 Fredrikinkatu 42
FIN-00100 HELSINKI FIN-00100 HELSINKI
Finland Finland
E-mail: ylo@ssh.com E-mail: ylo@ssh.com
 End of changes. 

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