draft-ietf-secsh-connect-02.txt   draft-ietf-secsh-connect-03.txt 
Network Working Group T. Ylonen Network Working Group T. Ylonen
INTERNET-DRAFT T. Kivinen INTERNET-DRAFT T. Kivinen
draft-ietf-secsh-connect-02.txt M. Saarinen draft-ietf-secsh-connect-03.txt M. Saarinen
Expires in six months SSH Expires in six months SSH
14 October 1997 7 November 1997
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.
skipping to change at page 1, line 30 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
SSH is a protocol for secure remote login and other secure network ser- SSH is a protocol for secure remote login and other secure network
vices over an insecure network. services over an insecure network.
This document describes the SSH connection protocol. It provides This document describes the SSH connection protocol. It provides
interactive login sessions, remote execution of commands, forwarded interactive login sessions, remote execution of commands, forwarded
TCP/IP connections, and forwarded X11 connections. All of these TCP/IP connections, and forwarded X11 connections. All of these
channels are multiplexed into a single encrypted tunnel. channels are multiplexed into a single encrypted tunnel.
The SSH Connection Protocol has been designed to run on top of the The SSH Connection Protocol has been designed to run on top of
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 . . . . . . . . . . . . . . . . . . . . . . 7 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. Environment Variable Passing . . . . . . . . . . . . . . . . 9
4.6. Starting a Shell or a Command . . . . . . . . . . . . . . . 9 4.6. Starting a Shell or a Command . . . . . . . . . . . . . . . 9
4.7. Session Data Transfer . . . . . . . . . . . . . . . . . . . 10 4.7. Session Data Transfer . . . . . . . . . . . . . . . . . . . 10
4.8. Window Dimension Change Message . . . . . . . . . . . . . . 10 4.8. Window Dimension Change Message . . . . . . . . . . . . . . 10
4.9. Local Flow Control . . . . . . . . . . . . . . . . . . . . . 10 4.9. Local Flow Control . . . . . . . . . . . . . . . . . . . . . 10
4.10. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.10. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.11. Returning Exit Status . . . . . . . . . . . . . . . . . . . 11 4.11. Returning Exit Status . . . . . . . . . . . . . . . . . . . 11
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. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
10. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 16 10. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 16
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
skipping to change at page 5, line 48 skipping to change at page 5, line 48
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. This message does not consume window space sent in the other direction. This message does not consume window space
and can be sent even if no window space is available. 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 a SSH_MSG_CHANNEL_CLOSE unless it has already sent this message for back a 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 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 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 reuse the channel number. A party MAY send SSH_MSG_CHANNEL_CLOSE
without having sent or received SSH_MSG_EOF. without having sent or received SSH_MSG_CHANNEL_EOF.
byte SSH_MSG_CHANNEL_CLOSE byte SSH_MSG_CHANNEL_CLOSE
uint32 recipient_channel uint32 recipient_channel
This message does not consume window space and can be sent even if no This message does not consume window space and can be sent even if no
window space is available. window space is available.
It is recommended that any data sent before this message is delivered to It is recommended that any data sent before this message is delivered to
the actual destination, if possible. the actual destination, if possible.
3.4. Channel-Specific Requests 3.4. Channel-Specific Requests
skipping to change at page 7, line 23 skipping to change at page 7, line 23
boolean want_reply boolean want_reply
string TERM environment variable value (e.g., vt100) string TERM environment variable value (e.g., vt100)
uint32 terminal width, characters (e.g., 80) uint32 terminal width, characters (e.g., 80)
uint32 terminal height, rows (e.g., 24) uint32 terminal height, rows (e.g., 24)
uint32 terminal width, pixels (e.g., 480) uint32 terminal width, pixels (e.g., 480)
uint32 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''. Zero dimension parameters MUST be ignored. The Terminal Modes''. Zero dimension parameters MUST be ignored. The
dimension parameters are only informational. character/row dimensions override the pixel dimensions (when nonzero).
Pixel dimensions refer to the drawable area of the window.
The dimension parameters are only informational.
The client SHOULD ignore pty requests. The client SHOULD ignore pty requests.
4.3. X11 Forwarding 4.3. X11 Forwarding
4.3.1. 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
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
skipping to change at page 8, line 16 skipping to change at page 8, line 18
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
string "x11" string "x11"
uint32 sender channel uint32 sender channel
uint32 initial window size uint32 initial window size
uint32 maximum packet size uint32 maximum packet size
string originator IP address (e.g. "192.168.7.38") string originator address (e.g. "192.168.7.38")
uint32 originator port uint32 originator port
The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or
SSH_MSG_CHANNEL_OPEN_FAILURE. SSH_MSG_CHANNEL_OPEN_FAILURE.
Implementations MUST reject any X11 channel open requests if they have Implementations MUST reject any X11 channel open requests if they have
not requested X11 forwarding. not requested X11 forwarding.
4.4. Authentication Agent Forwarding 4.4. Authentication Agent Forwarding
skipping to change at page 8, line 42 skipping to change at page 8, line 44
Authentication agent forwarding may be requested for a session by Authentication agent forwarding may be requested for a session by
sending sending
byte SSH_MSG_CHANNEL_REQUEST byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel uint32 recipient channel
string "auth-agent-req" string "auth-agent-req"
boolean want reply 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 (if `want reply' is TRUE). The client MAY to SSH_MSG_CHANNEL_FAILURE (if `want reply' is TRUE). The client MAY send
send further messages without waiting for the response to this message. further messages without waiting for the response to this message.
4.4.2. Authentication Agent Channels 4.4.2. Authentication Agent Channels
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
skipping to change at page 11, line 36 skipping to change at page 11, line 37
The client SHOULD ignore these messages. The client SHOULD 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. condition can be indicated by the following message. A zero exit_status
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]])
skipping to change at page 15, line 51 skipping to change at page 16, line 4
This protocol can, however, be used to execute commands on remote This protocol can, however, be used to execute commands on remote
machines. The protocol also permits the server to run commands on the machines. The protocol also permits the server to run commands on the
client. Implementations may wish to disallow this to prevent an client. Implementations may wish to disallow this to prevent an
attacker from coming from the server machine to the client machine. attacker from coming from the server machine to the client machine.
X11 forwarding provides major security improvements over normal cookie- X11 forwarding provides major security improvements over normal cookie-
based X11 forwarding. The cookie never needs to be transmitted in the based X11 forwarding. The cookie never needs to be transmitted in the
clear, and traffic is encrypted and integrity-protected. No useful clear, and traffic is encrypted and integrity-protected. No useful
authentication data will remain on the server machine after the authentication data will remain on the server machine after the
connection has been closed. On the other hand, in some situations a connection has been closed. On the other hand, in some situations a
forwarded X11 connection might be used to get access to the local X forwarded X11 connection might be used to get access to the local X
server across security perimeters. server across security perimeters.
Port forwardings can potentially allow an intruder to cross security Port forwardings can potentially allow an intruder to cross security
perimeters such as firewalls. They do not offer anything fundamentally perimeters such as firewalls. They do not offer anything fundamentally
new that a user couldn't do otherwise; however, they make opening new that a user couldn't do otherwise; however, they make opening
tunnels very easy. Implementations should allow policy control over tunnels very easy. Implementations should allow policy control over
what can be forwarded. Administrators should be able to deny what can be forwarded. Administrators should be able to deny
forwardings where appropriate. forwardings where appropriate.
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 of the potentially It is RECOMMENDED that implementations disable all of 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) of host key has changed. forwarding) if the host key has changed.
9. References 9. 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
Architecture", December 1995
[RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and
ISO 10646", October 1996. ISO 10646", October 1996.
[SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol [SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol
Architecture", Internet Draft, draft-ietf-secsh-architecture-00.txt Architecture", Internet Draft, draft-ietf-secsh-architecture-00.txt
[SSH-TRANS] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Transport [SSH-TRANS] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Transport
Layer Protocol", Internet Draft, draft-ietf-secsh-transport-02.txt Layer Protocol", Internet Draft, draft-ietf-secsh-transport-02.txt
[SSH-USERAUTH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH [SSH-USERAUTH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH
 End of changes. 

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