draft-ietf-secsh-connect-20.txt   draft-ietf-secsh-connect-21.txt 
Network Working Group C. Lonvick, Ed. Network Working Group C. Lonvick, Ed.
Internet-Draft Cisco Systems, Inc Internet-Draft Cisco Systems, Inc.
Expires: April 24, 2005 October 24, 2004 Expires: May 19, 2005 November 18, 2004
SSH Connection Protocol SSH Connection Protocol
draft-ietf-secsh-connect-20.txt draft-ietf-secsh-connect-21.txt
Status of this Memo Status of this Memo
This document is an Internet-Draft and is subject to all provisions This document is an Internet-Draft and is subject to all provisions
of section 3 of RFC 3667. By submitting this Internet-Draft, each of section 3 of RFC 3667. By submitting this Internet-Draft, each
author represents that any applicable patent or other IPR claims of author represents that any applicable patent or other IPR claims of
which he or she is aware have been or will be disclosed, and any of which he or she is aware have been or will be disclosed, and any of
which he or she become aware will be disclosed, in accordance with which he or she become aware will be disclosed, in accordance with
RFC 3668. RFC 3668.
skipping to change at page 1, line 35 skipping to change at page 1, line 34
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference 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."
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.
This Internet-Draft will expire on April 24, 2005. This Internet-Draft will expire on May 19, 2005.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). Copyright (C) The Internet Society (2004).
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
services over an insecure network. services over an insecure network.
skipping to change at page 2, line 16 skipping to change at page 2, line 16
SSH transport layer and user authentication protocols. SSH transport layer and user authentication protocols.
Table of Contents Table of Contents
1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Conventions Used in This Document . . . . . . . . . . . . . . 3 3. Conventions Used in This Document . . . . . . . . . . . . . . 3
4. Global Requests . . . . . . . . . . . . . . . . . . . . . . . 3 4. Global Requests . . . . . . . . . . . . . . . . . . . . . . . 3
5. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . 4 5. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . 4
5.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . 5 5.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . 5
5.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . 6 5.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . 7
5.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . 7 5.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . 8
5.4 Channel-Specific Requests . . . . . . . . . . . . . . . . 8 5.4 Channel-Specific Requests . . . . . . . . . . . . . . . . 8
6. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . 8 6. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . 9
6.1 Opening a Session . . . . . . . . . . . . . . . . . . . . 9 6.1 Opening a Session . . . . . . . . . . . . . . . . . . . . 9
6.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . 9 6.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . 10
6.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . 9 6.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . 10
6.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . 9 6.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . 10
6.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . 10 6.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . 11
6.4 Environment Variable Passing . . . . . . . . . . . . . . . 11 6.4 Environment Variable Passing . . . . . . . . . . . . . . . 11
6.5 Starting a Shell or a Command . . . . . . . . . . . . . . 11 6.5 Starting a Shell or a Command . . . . . . . . . . . . . . 12
6.6 Session Data Transfer . . . . . . . . . . . . . . . . . . 12 6.6 Session Data Transfer . . . . . . . . . . . . . . . . . . 13
6.7 Window Dimension Change Message . . . . . . . . . . . . . 12 6.7 Window Dimension Change Message . . . . . . . . . . . . . 13
6.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . 13 6.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . 13
6.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . 13 6.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . 14
6.10 Returning Exit Status . . . . . . . . . . . . . . . . . . 13 6.10 Returning Exit Status . . . . . . . . . . . . . . . . . . 14
7. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . 15 7. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . 15
7.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . 15 7.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . 15
7.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . 16 7.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . 16
8. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . 17 8. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . 17
9. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 19 9. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 20
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 19 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 20
11. Security Considerations . . . . . . . . . . . . . . . . . . 19 11. Security Considerations . . . . . . . . . . . . . . . . . . 20
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
12.1 Normative References . . . . . . . . . . . . . . . . . . . . 20 12.1 Normative References . . . . . . . . . . . . . . . . . . . . 21
12.2 Informative References . . . . . . . . . . . . . . . . . . . 20 12.2 Informative References . . . . . . . . . . . . . . . . . . . 21
Author's Address . . . . . . . . . . . . . . . . . . . . . . . 21 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 22
Intellectual Property and Copyright Statements . . . . . . . . 22 Intellectual Property and Copyright Statements . . . . . . . . 23
1. Contributors 1. Contributors
The major original contributors of this document were: Tatu Ylonen, The major original contributors of this document were: Tatu Ylonen,
Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH
Communications Security Corp), and Markku-Juhani O. Saarinen Communications Security Corp), and Markku-Juhani O. Saarinen
(University of Jyvaskyla). Darren Moffit was the original editor of (University of Jyvaskyla). Darren Moffit was the original editor of
this document and also made very substantial contributions. this document and also made very substantial contributions.
Additional contributors to this document include [need list]. Additional contributors to this document include [need list].
skipping to change at page 4, line 4 skipping to change at page 4, line 4
The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME
FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG
APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in
this document when used to describe namespace allocation are to be this document when used to describe namespace allocation are to be
interpreted as described in [RFC2434]. interpreted as described in [RFC2434].
4. Global Requests 4. Global Requests
There are several kinds of requests that affect the state of the There are several kinds of requests that affect the state of the
remote end globally, independent of any channels. An example is a remote end globally, independent of any channels. An example is a
request to start TCP/IP forwarding for a specific port. All such request to start TCP/IP forwarding for a specific port. Note that
requests use the following format. both client and server MAY send global requests at any time, and the
receiver MUST respond appropriately. All such requests use the
following format.
byte SSH_MSG_GLOBAL_REQUEST byte SSH_MSG_GLOBAL_REQUEST
string request name in US-ASCII only string request name in US-ASCII only
boolean want reply boolean want reply
... request-specific data follows ... request-specific data follows
The value of 'request name' follows the DNS extensibility naming The value of 'request name' follows the DNS extensibility naming
convention outlined in [SSH-ARCH]. convention outlined in [SSH-ARCH].
The recipient will respond to this message with The recipient will respond to this message with
skipping to change at page 5, line 50 skipping to change at page 6, line 4
The 'recipient channel' is the channel number given in the original The '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. the other side.
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 description in ISO-10646 UTF-8 encoding [RFC3629] string description in ISO-10646 UTF-8 encoding [RFC3629]
string language tag as defined in [RFC3066] string language tag as defined in [RFC3066]
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 'description' SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the 'description'
string to the user. If this is done, the client software should take string to the user. If this is done, the client software should take
the precautions discussed in [SSH-ARCH]. the precautions discussed in [SSH-ARCH].
The following 'reason code' values are defined: The SSH_MSG_CHANNEL_OPEN_FAILURE 'reason code' values are defined in
the following table. Note that the values for the 'reason code' are
given in decimal format for readability but that they are actually
uinit32 values.
description reason code description reason code
----------- ----------- ----------- -----------
SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1
SSH_OPEN_CONNECT_FAILED 2 SSH_OPEN_CONNECT_FAILED 2
SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3
SSH_OPEN_RESOURCE_SHORTAGE 4 SSH_OPEN_RESOURCE_SHORTAGE 4
Requests for assignments of new SSH_MSG_CHANNEL_OPEN 'reason code' Requests for assignments of new SSH_MSG_CHANNEL_OPEN 'reason code'
values (and associated 'description' text) in the range of 0x00000001 values (and associated 'description' text) in the range of 0x00000005
to 0xFDFFFFFF MUST be done through the IETF CONSENSUS method as to 0x0xFDFFFFFF MUST be done through the IETF CONSENSUS method as
described in [RFC2434]. The SSH_MSG_CHANNEL_OPEN 'reason code' described in [RFC2434]. The IANA will not assign Channel Connection
values in the range of 0xFE000000 to 0xFEFFFFFF are reserved for Failure 'reason code' values in the range of 0xFF000000 to
PRIVATE USE. The SSH_MSG_CHANNEL_OPEN 'reason code' values in the 0xFFFFFFFF. Channel Connection Failure 'reason code' values in that
range of 0xFF000000 to 0xFFFFFFFF are also reserved for PRIVATE USE range are left for PRIVATE USE as described in [RFC2434].
as described in [RFC2434]. As is noted, the actual instructions to
the IANA is in [SSH-NUMBERS]. While it is understood that the IANA will have no control over the
range of 0xFF000000 to 0xFFFFFFFF, this range will be split in two
parts and administered by the following conventions.
o The range of 0xFF000000 to 0xFEFFFFFF is to be used in conjunction
with locally assigned channels. For example, if a channel is
proposed with a 'channel type' of "example_session@example.com"
but fails, then the response will contain either a 'reason code'
assigned by the IANA (as listed above and in the range of
0x00000001 to 0x0xFDFFFFFF), or with a locally assigned value in
the range of 0xFF000000 to 0xFEFFFFFF. Naturally, if the server
does not understand the proposed 'channel type', even if it is a
locally defined 'channel type', then the 'reason code' MUST be
0x00000003 as described above, if the 'reason code' is sent. If
the server does understand the 'channel type' but the channel
still fails to open, then the server SHOULD respond with a locally
assigned 'reason code' value consistent with the proposed, local
'channel type'. It is assumed that practitioners will first
attempt to use the IANA assigned 'reason code' values and then
document their locally assigned 'reason code' values.
o There are no restrictions or suggestions for the range starting
with 0xFF. No interoperability is expected for anything used in
this range. Essentially it is for experimentation.
5.2 Data Transfer 5.2 Data Transfer
The window size specifies how many bytes the other party can send The window size specifies how many bytes the other party can send
before it must wait for the window to be adjusted. Both parties use before it must wait for the window to be adjusted. Both parties use
the following message to adjust the window. the following message to adjust the window.
byte SSH_MSG_CHANNEL_WINDOW_ADJUST byte SSH_MSG_CHANNEL_WINDOW_ADJUST
uint32 recipient channel uint32 recipient channel
uint32 bytes to add uint32 bytes to add
skipping to change at page 7, line 17 skipping to change at page 7, line 43
and their interpretation depend on the type of the channel. and their interpretation depend on the type of the channel.
byte SSH_MSG_CHANNEL_EXTENDED_DATA byte SSH_MSG_CHANNEL_EXTENDED_DATA
uint32 recipient_channel uint32 recipient_channel
uint32 data_type_code uint32 data_type_code
string data string data
Data sent with these messages consumes the same window as ordinary Data sent with these messages consumes the same window as ordinary
data. data.
Currently, only the following type is defined. Currently, only the following type is defined. Note that the value
for the 'data_type_code' is given in decimal format for readability
but that the values are actually uinit32 values.
data data_type_code data data_type_code
---- -------------- ---- --------------
SSH_EXTENDED_DATA_STDERR 1 SSH_EXTENDED_DATA_STDERR 1
Extended Channel Data Transfer 'data_type_code' values MUST be
assigned sequentially. Requests for assignments of new Extended
Channel Data Transfer 'data_type_code' values, and their associated
Extended Channel Data Transfer 'data' strings, in the range of
0x00000002 to 0xFDFFFFFF MUST be done through the IETF CONSENSUS
method as described in [RFC2434]. The IANA will not assign Extended
Channel Data Transfer 'data_type_code' values in the range of
0xFE000000 to 0xFFFFFFFF. Extended Channel Data Transfer
'data_type_code' values in that range are left for PRIVATE USE as
described in [RFC2434]. As is noted, the actual instructions to the
IANA is in [SSH-NUMBERS].
5.3 Closing a Channel 5.3 Closing a Channel
When a party will no longer send more data to a channel, it SHOULD When a party will no longer send more data to a channel, it SHOULD
send SSH_MSG_CHANNEL_EOF. send SSH_MSG_CHANNEL_EOF.
byte SSH_MSG_CHANNEL_EOF byte SSH_MSG_CHANNEL_EOF
uint32 recipient_channel uint32 recipient_channel
No explicit response is sent to this message. However, the No explicit response is sent to this message. However, the
application may send EOF to whatever is at the other end of the application may send EOF to whatever is at the other end of the
skipping to change at page 17, line 17 skipping to change at page 18, line 6
Client implementations SHOULD reject direct TCP/IP open requests for Client implementations SHOULD reject direct TCP/IP open requests for
security reasons. security reasons.
8. Encoding of Terminal Modes 8. Encoding of Terminal Modes
All "encoded terminal modes" (as passed in a pty request) are encoded All "encoded terminal modes" (as passed in a pty request) are encoded
into a byte stream. It is intended that the coding be portable into a byte stream. It is intended that the coding be portable
across different environments. across different environments.
The tty mode description is a stream of bytes. The stream consists 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). of opcode-argument pairs where the opcode is a byte value. It is
Opcodes 1 to 159 have a single uint32 argument. Opcodes 160 to 255 terminated by opcode TTY_OP_END (0x00). Opcodes 1 to 159 have a
are not yet defined, and cause parsing to stop (they should only be single uint32 argument. Opcodes 160 to 255 are not yet defined, and
used after any other data). cause parsing to stop (they should only be used after any other
data).
The client SHOULD put in the stream any modes it knows about, and the The client SHOULD put in the stream any modes it knows about, and the
server MAY ignore any modes it does not know about. This allows some server MAY ignore any modes it does not know about. This allows some
degree of machine-independence, at least between systems that use a degree of machine-independence, at least between systems that use a
POSIX-like tty interface. The protocol can support other systems as POSIX-like tty interface. The protocol can support other systems as
well, but the client may need to fill reasonable values for a number well, but the client may need to fill reasonable values for a number
of parameters so the server pty gets set to a reasonable mode (the of parameters so the server pty gets set to a reasonable mode (the
server leaves all unspecified mode bits in their default values, and server leaves all unspecified mode bits in their default values, and
only some combinations make sense). only some combinations make sense).
The following opcodes have been defined. The naming of opcodes The naming of 'opcode' values mostly follows the POSIX terminal mode
mostly follows the POSIX terminal mode flags. flags. The following 'opcode' values have been defined. Note that
the values given below are in decimal format for readability but that
they are actually byte values.
opcode argument description opcode argument description
------ -------- ----------- ------ -------- -----------
0 TTY_OP_END Indicates end of options. 0 TTY_OP_END Indicates end of options.
1 VINTR Interrupt character; 255 if none. Similarly 1 VINTR Interrupt character; 255 if none. Similarly
for the other characters. Not all of these for the other characters. Not all of these
characters are supported on all systems. characters are supported on all systems.
2 VQUIT The quit character (sends SIGQUIT signal on 2 VQUIT The quit character (sends SIGQUIT signal on
POSIX systems). POSIX systems).
3 VERASE Erase the character to left of the cursor. 3 VERASE Erase the character to left of the cursor.
skipping to change at page 20, line 14 skipping to change at page 21, line 8
[SSH-ARCH]. Specific to this document, it is RECOMMENDED that [SSH-ARCH]. Specific to this document, it is RECOMMENDED that
implementations disable all the potentially dangerous features (e.g. implementations disable all the potentially dangerous features (e.g.
agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host
key has changed without notice or explanation. key has changed without notice or explanation.
12. References 12. References
12.1 Normative References 12.1 Normative References
[SSH-ARCH] [SSH-ARCH]
Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", Lonvick, C., "SSH Protocol Architecture", I-D
I-D draft-ietf-architecture-17.txt, October 2004. draft-ietf-architecture-18.txt, October 2004.
[SSH-TRANS] [SSH-TRANS]
Ylonen, T. and C. Lonvick, "SSH Transport Layer Protocol", Lonvick, C., "SSH Transport Layer Protocol", I-D
I-D draft-ietf-transport-19.txt, October 2004. draft-ietf-transport-20.txt, October 2004.
[SSH-USERAUTH] [SSH-USERAUTH]
Ylonen, T. and C. Lonvick, "SSH Authentication Protocol", Lonvick, C., "SSH Authentication Protocol", I-D
I-D draft-ietf-userauth-22.txt, October 2004. draft-ietf-userauth-23.txt, October 2004.
[SSH-NUMBERS] [SSH-NUMBERS]
Ylonen, T. and C. Lonvick, "SSH Protocol Assigned Lonvick, C., "SSH Protocol Assigned Numbers", I-D
Numbers", I-D draft-ietf-assignednumbers-07.txt, October draft-ietf-assignednumbers-08.txt, October 2004.
2004.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 10646", STD 63, RFC 3629, November 2003.
12.2 Informative References 12.2 Informative References
[RFC1884] Hinden, R. and S. Deering, "IP Version 6 Addressing [RFC1884] Hinden, R. and S. Deering, "IP Version 6 Addressing
skipping to change at page 21, line 13 skipping to change at page 22, line 8
Press ISBN 1555580882, February 1992. Press ISBN 1555580882, February 1992.
[POSIX] ISO/IEC, 9945-1., "Information technology -- Portable [POSIX] ISO/IEC, 9945-1., "Information technology -- Portable
Operating System Interface (POSIX)-Part 1: System Operating System Interface (POSIX)-Part 1: System
Application Program Interface (API) C Language", ANSI/IEE Application Program Interface (API) C Language", ANSI/IEE
Std 1003.1, July 1996. Std 1003.1, July 1996.
Author's Address Author's Address
Chris Lonvick (editor) Chris Lonvick (editor)
Cisco Systems, Inc Cisco Systems, Inc.
12515 Research Blvd. 12515 Research Blvd.
Austin 78759 Austin 78759
USA USA
EMail: clonvick@cisco.com EMail: clonvick@cisco.com
Intellectual Property Statement Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to Intellectual Property Rights or other rights that might be claimed to
 End of changes. 

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