RFC 4254 The Secure Shell (SSH) Connection Protocol

Network Working Group T. Ylonen
Request for Comments: 4254 SSH Communications Security Corp
Category: Standards Track C. Lonvick, Ed.
Cisco Systems, Inc.
January 2006

The Secure Shell (SSH) Connection Protocol

Status of This Memo

This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.

Abstract

Secure Shell (SSH) is a protocol for secure remote login and other
secure network services over an insecure network.

This document describes the SSH Connection Protocol. It provides
interactive login sessions, remote execution of commands, forwarded
TCP/IP connections, and forwarded X11 connections. All of these
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.

Table of Contents

1. Introduction
2. Contributors
3. Conventions Used in This Document
4. Global Requests
5. Channel Mechanism
5.1. Opening a Channel
5.2. Data Transfer
5.3. Closing a Channel
5.4. Channel-Specific Requests
6. Interactive Sessions
6.1. Opening a Session
6.2. Requesting a Pseudo-Terminal
6.3. X11 Forwarding
6.3.1. Requesting X11 Forwarding
6.3.2. X11 Channels
6.4. Environment Variable Passing
6.5. Starting a Shell or a Command
6.6. Session Data Transfer
6.7. Window Dimension Change Message
6.8. Local Flow Control
6.9. Signals
6.10. Returning Exit Status
7. TCP/IP Port Forwarding
7.1. Requesting Port Forwarding
7.2. TCP/IP Forwarding Channels
8. Encoding of Terminal Modes
9. Summary of Message Numbers
10. IANA Considerations
11. Security Considerations
12. References
12.1. Normative References
12.2. Informative References
Authors' Addresses
Trademark Notice

1. Introduction

The SSH Connection Protocol has been designed to run on top of the
SSH transport layer and user authentication protocols ([SSH-TRANS]
and [SSH-USERAUTH]). It provides interactive login sessions, remote
execution of commands, forwarded TCP/IP connections, and forwarded
X11 connections.

The 'service name' for this protocol is "ssh-connection".

This document should be read only after reading the SSH architecture
document [SSH-ARCH]. This document freely uses terminology and
notation from the architecture document without reference or further
explanation.

2. Contributors

The major original contributors of this set of documents have been:
Tatu Ylonen, Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH
Communications Security Corp), and Markku-Juhani O. Saarinen
(University of Jyvaskyla). Darren Moffat was the original editor of
this set of documents and also made very substantial contributions.

Many people contributed to the development of this document over the
years. People who should be acknowledged include Mats Andersson, Ben
Harris, Bill Sommerfeld, Brent McClure, Niels Moller, Damien Miller,
Derek Fawcus, Frank Cusack, Heikki Nousiainen, Jakob Schlyter, Jeff
Van Dyke, Jeffrey Altman, Jeffrey Hutzelman, Jon Bright, Joseph
Galbraith, Ken Hornstein, Markus Friedl, Martin Forssen, Nicolas
Williams, Niels Provos, Perry Metzger, Peter Gutmann, Simon
Josefsson, Simon Tatham, Wei Dai, Denis Bider, der Mouse, and
Tadayoshi Kohno. Listing their names here does not mean that they
endorse this document, but that they have contributed to it.

3. Conventions Used in This Document

All documents related to the SSH protocols shall use the keywords
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe
requirements. These keywords are to be interpreted as described in
[RFC2119].

The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME
FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG
APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in
this document when used to describe namespace allocation are to be
interpreted as described in [RFC2434].

Protocol fields and possible values to fill them are defined in this
set of documents. Protocol fields will be defined in the message
definitions. As an example, SSH_MSG_CHANNEL_DATA is defined as
follows.

byte SSH_MSG_CHANNEL_DATA
uint32 recipient channel
string data

Throughout these documents, when the fields are referenced, they will
appear within single quotes. When values to fill those fields are
referenced, they will appear within double quotes. Using the above
example, possible values for 'data' are "foo" and "bar".

4. 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. Note that
both the 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 (id 80)
string request name in US-ASCII only
boolean want reply
.... request-specific data follows

The value of 'request name' follows the DNS extensibility naming
convention outlined in [SSH-ARCH].

The recipient will respond to this message with
SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if 'want reply' is
TRUE.

byte SSH_MSG_REQUEST_SUCCESS (id 81)
.... response specific data

Usually, the 'response specific data' is non-existent.

If the recipient does not recognize or support the request, it simply
responds with SSH_MSG_REQUEST_FAILURE.

byte SSH_MSG_REQUEST_FAILURE (id 82)

In general, the reply messages do not include request type
identifiers. To make it possible for the originator of a request to
identify to which request each reply refers, it is REQUIRED that
replies to SSH_MSG_GLOBAL_REQUESTS MUST be sent in the same order as
the corresponding request messages. For channel requests, replies
that relate to the same channel MUST also be replied to in the right
order. However, channel requests for distinct channels MAY be
replied to out-of-order.

5. Channel Mechanism

Все терминальные сессии, прокинутые соединения и т.д. являются каналами.
Любая сторона может открыть канал. Несколько каналов мультиплексируются
в единственное соединение.

Каналы идентифицируются по номерам на каждом конце. Номер ссылающийся
на канал может быть различным на каждой стороне. Запросы на открытие
канала содержат номер канала отправителя. Любые другие относящиеся
к каналу сообщения содержат номер канала получателя для этого
канала.

Channels are flow-controlled. No data may be sent to a channel until
a message is received to indicate that window space is available.

5.1. Открытие канала

Когда какая-либо сторона хочет открыть новый канал, она назначает локальный
номер для канала. Потом она посылает следующее сообщение другой
стороне и включает в сообщение локальный номер канала и начальный размер окна.

byte SSH_MSG_CHANNEL_OPEN (id 90)
string channel type in US-ASCII only
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
.... channel type specific data follows

Поле 'channel type' это имя, описанное в [SSH-ARCH] и
[SSH-NUMBERS], with similar extension mechanisms.
Поле 'sender channel' это локальный идентификатор канала используемого
отправителем этого сообщения.
Поле 'initial window size' определяет как много байт данных канала
может быть отправлено отправителю этого сообщения без корректировки окна.
Поле 'maximum packet size' определяет максимальный размер индивидуального
пакета данных который может быть отправлен отправителю.
Например, один хочет использовать маленькие пакеты для интерактивных
соединений для получения лучшего интерактивного ответа на медленных
подключениях.

Удалённая сторона решает может ли она открыть канал и отвечает
либо SSH_MSG_CHANNEL_OPEN_CONFIRMATION либо SSH_MSG_CHANNEL_OPEN_FAILURE.

byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION (id 91)
uint32 recipient channel
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
.... channel type specific data follows

Поле 'recipient channel' это номер канала переданный в начальном
запросе открытия и поле 'sender channel' это номер канала назначенный
другой стороной.

byte SSH_MSG_CHANNEL_OPEN_FAILURE (id 92)
uint32 recipient channel
uint32 reason code
string description in ISO-10646 UTF-8 encoding [RFC3629]
string language tag [RFC3066]

Если получатель сообщения the SSH_MSG_CHANNEL_OPEN не поддерживает
указанный 'channel type', то он просто отвечает SSH_MSG_CHANNEL_OPEN_FAILURE.
Клиент МОЖЕТ показать строку 'description' пользователю. Если это будет
сделано, то клиент должен принять меры предосторожности обсуждаемые в
[SSH-ARCH].

Значение 'reason code' определено в следующей таблице.
Учтите, что значения 'reason code' даны в десятичном формате для читаемости,
но на самом деле они являются значениями типа uint32.

Symbolic name reason code
------------- -----------
SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1
SSH_OPEN_CONNECT_FAILED 2
SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3
SSH_OPEN_RESOURCE_SHORTAGE 4

Requests for assignments of new SSH_MSG_CHANNEL_OPEN 'reason code'
values (and associated 'description' text) in the range of 0x00000005
to 0xFDFFFFFF MUST be done through the IETF CONSENSUS method, as
described in [RFC2434]. The IANA will not assign Channel Connection
Failure 'reason code' values in the range of 0xFE000000 to
0xFFFFFFFF. Channel Connection Failure 'reason code' values in that
range are left for PRIVATE USE, as described in [RFC2434].

While it is understood that the IANA will have no control over the
range of 0xFE000000 to 0xFFFFFFFF, this range will be split in two
parts and administered by the following conventions.

o The range of 0xFE000000 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 0xFDFFFFFF) or a locally assigned value in the range
of 0xFE000000 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. Передача данных

Размер окна указывает количество байт которое другая сторона может послать
прежде чем она должна будет ждать перенастройки окна. Обе стороны используют
следующее сообщение для настройки окна.

byte SSH_MSG_CHANNEL_WINDOW_ADJUST (id 93)
uint32 recipient channel
uint32 bytes to add

После получения этого сообщения, получатель МОЖЕТ послать на указанное число
байт больше чем ему раньше было позволено отправлять; размер окна
увеличивается. Реализации ДОЛЖНЫ коректно обрабатывать окно размером
до 2^32 - 1 байт. Окно НЕ ДОЛЖНО расти больше чем до 2^32 - 1 байт.

Передача данных выполняется сообщением следующего типа:

byte SSH_MSG_CHANNEL_DATA (id 94)
uint32 recipient channel
string data

The maximum amount of data allowed is determined by the maximum
packet size for the channel, and the current window size, whichever
is smaller. The window size is decremented by the amount of data
sent. Both parties MAY ignore all extra data sent after the allowed
window is empty.

Implementations are expected to have some limit on the SSH transport
layer packet size (any limit for received packets MUST be 32768 bytes
or larger, as described in [SSH-TRANS]). The implementation of the
SSH connection layer

o MUST NOT advertise a maximum packet size that would result in
transport packets larger than its transport layer is willing to
receive.

o MUST NOT generate data packets larger than its transport layer is
willing to send, even if the remote end would be willing to accept
very large packets.

Дополнительно, некоторые каналы могут передавать несколько типов данных.
Примером этого служат данные stderr из интерактивной сессии. Такие данные
могут быть переданы сообщением SSH_MSG_CHANNEL_EXTENDED_DATA, где
отдельные целые числа указывают тип данных. Доступные типы и
их интерпретация зависят от типа канала.

byte SSH_MSG_CHANNEL_EXTENDED_DATA (id 95)
uint32 recipient channel
uint32 data_type_code
string data

Data sent with these messages consumes the same window as ordinary
data.

Currently, only the following type is defined. Note that the value
for the 'data_type_code' is given in decimal format for readability,
but the values are actually uint32 values.

Symbolic name data_type_code
------------- --------------
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 are in [SSH-NUMBERS].

5.3. Закрытие канала

Когда сторона не хочет больше посылать данные в канал, она ДОЛЖНА
послать SSH_MSG_CHANNEL_EOF.

byte SSH_MSG_CHANNEL_EOF (id 96)
uint32 recipient channel

Никакого явного ответа не посылается на это сообщение. However, the
application may send EOF to whatever is at the other end of the
channel. Учтите что канал остаётся открытым после этого сообщения и
данные могут всё ещё быть отправлены в другом направлении. Это сообщение
не использует пространство окна и может быть отправлено даже если нет
доступного пространства окна.

Когда любая из сторон хочет закрыть канал, она отправляет сообщение
SSH_MSG_CHANNEL_CLOSE. После получения этого сообщения сторона ДОЛЖНА
отправить обратно SSH_MSG_CHANNEL_CLOSE если только она уже не отправила это
сообщение для канала. Канал считается закрытым для стороны когда она имеет
оба отправленное и полученное сообщения SSH_MSG_CHANNEL_CLOSE и сторона
может позже снова использовать этот номер канала. Сторона МОЖЕТ послать
SSH_MSG_CHANNEL_CLOSE без предварительной отправки или получения
SSH_MSG_CHANNEL_EOF.

byte SSH_MSG_CHANNEL_CLOSE (id 97)
uint32 recipient channel

Это сообщение не использует пространство окна и может быть отправлено
даже если нет доступного пространства окна.

РЕКОМЕНДУЕТСЯ чтобы все данные отправленные до этого сообщения были доставлены
по назначению, если возможно.

5.4. Channel-Specific Requests

Много значений 'channel type' имеют расширения that are specific to that
particular 'channel type'. An example is requesting a pty (pseudo
terminal) for an interactive session.

Все специфичные для канала запросы используют следующий формат:

byte SSH_MSG_CHANNEL_REQUEST (id 98)
uint32 recipient channel
string request type in US-ASCII characters only
boolean want reply
.... type-specific data follows

Если 'want reply' равно FALSE, на запрос ответа не последует.
Иначе, получатель ответит либо SSH_MSG_CHANNEL_SUCCESS, либо
SSH_MSG_CHANNEL_FAILURE, либо сообщение специфичным для запроса.
Если запрос не распознан или не поддерживается для канала, то возвращается
SSH_MSG_CHANNEL_FAILURE.

Это сообщение не использует пространство окна и может быть отправлено
даже если нет доступного пространства окна.
Значения 'request type' являются локальными для каждого типа канала.

Клиенту позволяется отправлять дальнейшие сообщения без ожидания
ответа на запрос.

Имена 'request type' follow the DNS extensibility naming convention
outlined in [SSH-ARCH] and [SSH-NUMBERS].

byte SSH_MSG_CHANNEL_SUCCESS (id 99)
uint32 recipient channel

byte SSH_MSG_CHANNEL_FAILURE (id 100)
uint32 recipient channel

Эти сообщения не используют пространство окна и могут быть отправлены
даже если нет доступного пространства окна.

6. Interactive Sessions

Сессия это удалённое выполнение программы. Программой может быть
оболочка, приложение, системная команда или какая-нибудь встроенная подсистема.
Она может или может не иметь tty, и может или не включать пересылку X11.
Несколько сессий могут быть активны одновременно.

6.1. Открытие сессии

Сессия открывается отправкой следующего сообщения:

byte SSH_MSG_CHANNEL_OPEN
string "session"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size

Клиентские реализации ДОЛЖНЫ отклонять любые запросы открытия канала сессии
в целях усложнения атаки на клиента взломанным сервером.

6.2. Запрос псевдотерминала

A pseudo-terminal can be allocated for the session by sending the
following message.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "pty-req"
boolean want_reply
string TERM environment variable value (e.g., vt100)
uint32 terminal width, characters (e.g., 80)
uint32 terminal height, rows (e.g., 24)
uint32 terminal width, pixels (e.g., 640)
uint32 terminal height, pixels (e.g., 480)
string encoded terminal modes

Поле 'encoded terminal modes' описано в разделе 8. Нулевые
параметры размеров ДОЛЖНЫ игнорироваться. Размеры символы/строки
переопределяют размеры в пикселах (если не равны нулю). Размеры в пикселах
относятся к отрисовываемой области окна.

Параметры размеров носят информативный характер.

Клиенту СЛЕДУЕТ игнорировать запросы pty (псевдотерминал).

6.3. Передача X11

6.3.1. Запрос передачи X11

X11 forwarding may be requested for a session by sending a
SSH_MSG_CHANNEL_REQUEST message.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "x11-req"
boolean want reply
boolean single connection
string x11 authentication protocol
string x11 authentication cookie
uint32 x11 screen number

It is RECOMMENDED that the 'x11 authentication cookie' that is sent
be a fake, random cookie, and that the cookie be checked and replaced
by the real cookie when a connection request is received.

X11 connection forwarding should stop when the session channel is
closed. However, already opened forwardings should not be
automatically closed when the session channel is closed.

Если 'single connection' равно TRUE, то только одно соединение должно быть
передано. No more connections will be forwarded after the first, or
after the session channel has been closed.

Поле 'x11 authentication protocol' это используемое имя метода
аутентификации X11, например, "MIT-MAGIC-COOKIE-1".

Поле 'x11 authentication cookie' ДОЛЖНО быть в шестнадцатеричной кодировке.

Протокол X задокументирован в [SCHEIFLER].

6.3.2. X11 Channels

X11 channels are opened with a channel open request. The resulting
channels are independent of the session, and closing the session
channel does not close the forwarded X11 channels.

byte SSH_MSG_CHANNEL_OPEN
string "x11"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
string originator address (e.g., "192.168.7.38")
uint32 originator port

The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION
or SSH_MSG_CHANNEL_OPEN_FAILURE.

Implementations MUST reject any X11 channel open requests if they
have not requested X11 forwarding.

6.4. Передача переменных окружения

Переменные окружения могут быть переданы оболочке/команде которые будут
запущены позже. Неконтролируемая установка переменных среды в
привилегированном процессе может быть опасным риском. It is recommended that
implementations either maintain a list of allowable variable names or
only set environment variables after the server process has dropped
sufficient privileges.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "env"
boolean want reply
string variable name
string variable value

6.5. Запуск оболочки или команды

Once the session has been set up, a program is started at the remote
end. The program can be a shell, an application program, or a
subsystem with a host-independent name. Only one of these requests
can succeed per channel.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "shell"
boolean want reply

Это сообщение будет запрашивать оболочку пользователя (обычно определяется
в /etc/passwd в системах UNIX) которая запуститься на другом конце.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "exec"
boolean want reply
string command

Это сообщение будет запрашивать сервером выполненить данную команду.
Строка 'command' может содержать путь. Обычные меры предосторожности ДОЛЖНЫ
быть приняты для предотвращения выполнения неавторизированных команд.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "subsystem"
boolean want reply
string subsystem name

Эта последняя форма выполняет предопределённую подсистему. Ожидается, что
это будет включать основной механизм передачи файлов и, возможно,
другие возможности. Implementations may also allow configuring more such
mechanisms. As the user's shell is usually used to execute the
subsystem, it is advisable for the subsystem protocol to have a
"magic cookie" at the beginning of the protocol transaction to
distinguish it from arbitrary output generated by shell
initialization scripts, etc. This spurious output from the shell may
be filtered out either at the server or at the client.

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 redirected to the channel or to the encrypted tunnel.

It is RECOMMENDED that the reply to these messages be requested and
checked. Клиент ДОЛЖЕН игнорировать эти сообщения.

Subsystem names follow the DNS extensibility naming convention
outlined in [SSH-NUMBERS].

6.6. Session Data Transfer

Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and
SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The
extended data type SSH_EXTENDED_DATA_STDERR has been defined for
stderr data.

6.7. Window Dimension Change Message

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.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "window-change"
boolean FALSE
uint32 terminal width, columns
uint32 terminal height, rows
uint32 terminal width, pixels
uint32 terminal height, pixels

A response SHOULD NOT be sent to this message.

6.8. Local Flow Control

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, 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 notification. Initially, the server is responsible for
flow control. (Here, again, client means the side originating the
session, and server means the other side.)

The message below is used by the server to inform the client when it
can or cannot perform flow control (control-S/control-Q processing).
If 'client can do' is TRUE, the client is allowed to do flow control
using control-S and control-Q. The client MAY ignore this message.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "xon-xoff"
boolean FALSE
boolean client can do

No response is sent to this message.

6.9. Signals

A signal can be delivered to the remote process/service using the
following message. Some systems may not implement signals, in which
case they SHOULD ignore this message.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "signal"
boolean FALSE
string signal name (without the "SIG" prefix)

'signal name' values will be encoded as discussed in the passage
describing SSH_MSG_CHANNEL_REQUEST messages using "exit-signal" in
this section.

6.10. Returning Exit Status

When the command running at the other end terminates, the following
message can be sent to return the exit status of the command.
Returning the status is RECOMMENDED. No acknowledgement is sent for
this message. The channel needs to be closed with
SSH_MSG_CHANNEL_CLOSE after this message.

The client MAY ignore these messages.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "exit-status"
boolean FALSE
uint32 exit_status

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' usually means that the command terminated successfully.

byte SSH_MSG_CHANNEL_REQUEST
uint32 recipient channel
string "exit-signal"
boolean FALSE
string signal name (without the "SIG" prefix)
boolean core dumped
string error message in ISO-10646 UTF-8 encoding
string language tag [RFC3066]

The 'signal name' is one of the following (these are from [POSIX]).

ABRT
ALRM
FPE
HUP
ILL
INT
KILL
PIPE
QUIT
SEGV
TERM
USR1
USR2

Additional 'signal name' values MAY be sent in the format
"sig-name@xyz", where "sig-name" and "xyz" may be anything a
particular implementer wants (except the "@" sign). However, it is
suggested that if a 'configure' script is used, any non-standard
'signal name' values it finds be encoded as "SIG@xyz.config.guess",
where "SIG" is the 'signal name' without the "SIG" prefix, and "xyz"
is the host type, as determined by "config.guess".

The 'error message' contains an additional textual explanation of the
error message. The message may consist of multiple lines separated
by CRLF (Carriage Return - Line Feed) pairs. The client software MAY
display this message to the user. If this is done, the client
software should take the precautions discussed in [SSH-ARCH].

7. TCP/IP Port Forwarding

7.1. Requesting Port Forwarding

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 the other side be forwarded to the local side, it must
explicitly request this.

byte SSH_MSG_GLOBAL_REQUEST
string "tcpip-forward"
boolean want reply
string address to bind (e.g., "0.0.0.0")
uint32 port number to bind

The 'address to bind' and 'port number to bind' specify the IP
address (or domain name) and port on which connections for forwarding
are to be accepted. Some strings used for 'address to bind' have
special-case semantics.

o "" means that connections are to be accepted on all protocol
families supported by the SSH implementation.

o "0.0.0.0" means to listen on all IPv4 addresses.

o "::" means to listen on all IPv6 addresses.

o "localhost" means to listen on all protocol families supported by
the SSH implementation on loopback addresses only ([RFC3330] and
[RFC3513]).

o "127.0.0.1" and "::1" indicate listening on the loopback
interfaces for IPv4 and IPv6, respectively.

Note that the client can still filter connections based on
information passed in the open request.

Implementations should only allow forwarding privileged ports if the
user has been authenticated as a privileged user.

Client implementations SHOULD reject these messages; they are
normally only sent by the client.

If a client passes 0 as port number to bind and has 'want reply' as
TRUE, then the server allocates the next available unprivileged port
number and replies with the following message; otherwise, there is no
response-specific data.

byte SSH_MSG_REQUEST_SUCCESS
uint32 port that was bound on the server

A port forwarding can be canceled with the following message. Note
that channel open requests may be received until a reply to this
message is received.

byte SSH_MSG_GLOBAL_REQUEST
string "cancel-tcpip-forward"
boolean want reply
string address_to_bind (e.g., "127.0.0.1")
uint32 port number to bind

Client implementations SHOULD reject these messages; they are
normally only sent by the client.

7.2. TCP/IP Forwarding Channels

When a connection comes to a port for which remote forwarding has
been requested, a channel is opened to forward the port to the other
side.

byte SSH_MSG_CHANNEL_OPEN
string "forwarded-tcpip"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
string address that was connected
uint32 port that was connected
string originator IP address
uint32 originator port

Implementations MUST reject these messages unless they have
previously requested a remote TCP/IP port forwarding with the given
port number.

When a connection comes to a locally forwarded TCP/IP port, the
following packet is sent to the other side. Note that these messages
MAY also be sent for ports for which no forwarding has been
explicitly requested. The receiving side must decide whether to
allow the forwarding.

byte SSH_MSG_CHANNEL_OPEN
string "direct-tcpip"
uint32 sender channel
uint32 initial window size
uint32 maximum packet size
string host to connect
uint32 port to connect
string originator IP address
uint32 originator port

The 'host to connect' and 'port to connect' specify the TCP/IP host
and port where the recipient should connect the channel. The 'host
to connect' may be either a domain name or a numeric IP address.

The 'originator IP address' is the numeric IP address of the machine
from where the connection request originates, and the 'originator
port' is the port on the host from where the connection originated.

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.

Client implementations SHOULD reject direct TCP/IP open requests for
security reasons.

8. Encoding of Terminal Modes

All 'encoded terminal modes' (as passed in a pty request) are encoded
into a byte stream. It is intended that the coding be portable
across different environments. The stream consists of opcode-
argument pairs wherein the opcode is a byte value. Opcodes 1 to 159
have a single uint32 argument. Opcodes 160 to 255 are not yet
defined, and cause parsing to stop (they should only be used after
any other data). The stream is terminated by opcode TTY_OP_END
(0x00).

The client SHOULD put any modes it knows about in the stream, and the
server MAY ignore any modes it does not know about. This allows some
degree of machine-independence, at least between systems that use a
POSIX-like tty interface. The protocol can support other systems as
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
server leaves all unspecified mode bits in their default values, and
only some combinations make sense).

The naming of opcode values mostly follows the POSIX terminal mode
flags. The following opcode values have been defined. Note that the
values given below are in decimal format for readability, but they
are actually byte values.

opcode mnemonic description
------ -------- -----------
0 TTY_OP_END Indicates end of options.
1 VINTR Interrupt character; 255 if none. Similarly
for the other characters. Not all of these
characters are supported on all systems.
2 VQUIT The quit character (sends SIGQUIT signal on
POSIX systems).
3 VERASE Erase the character to left of the cursor.
4 VKILL Kill the current input line.
5 VEOF End-of-file character (sends EOF from the
terminal).
6 VEOL End-of-line character in addition to
carriage return and/or linefeed.
7 VEOL2 Additional end-of-line character.
8 VSTART Continues paused output (normally
control-Q).
9 VSTOP Pauses output (normally control-S).
10 VSUSP Suspends the current program.
11 VDSUSP Another suspend character.
12 VREPRINT Reprints the current input line.
13 VWERASE Erases a word left of cursor.
14 VLNEXT Enter the next character typed literally,
even if it is a special character
15 VFLUSH Character to flush output.
16 VSWTCH Switch to a different shell layer.
17 VSTATUS Prints system status line (load, command,
pid, etc).
18 VDISCARD Toggles the flushing of terminal output.
30 IGNPAR The ignore parity flag. The parameter
SHOULD be 0 if this flag is FALSE,
and 1 if it is TRUE.
31 PARMRK Mark parity and framing errors.
32 INPCK Enable checking of parity errors.
33 ISTRIP Strip 8th bit off characters.
34 INLCR Map NL into CR on input.
35 IGNCR Ignore CR on input.
36 ICRNL Map CR to NL on input.
37 IUCLC Translate uppercase characters to
lowercase.
38 IXON Enable output flow control.
39 IXANY Any char will restart after stop.
40 IXOFF Enable input flow control.
41 IMAXBEL Ring bell on input queue full.
50 ISIG Enable signals INTR, QUIT, [D]SUSP.
51 ICANON Canonicalize input lines.
52 XCASE Enable input and output of uppercase
characters by preceding their lowercase
equivalents with "\".
53 ECHO Enable echoing.
54 ECHOE Visually erase chars.
55 ECHOK Kill character discards current line.
56 ECHONL Echo NL even if ECHO is off.
57 NOFLSH Don't flush after interrupt.
58 TOSTOP Stop background jobs from output.
59 IEXTEN Enable extensions.
60 ECHOCTL Echo control characters as ^(Char).
61 ECHOKE Visual erase for line kill.
62 PENDIN Retype pending input.
70 OPOST Enable output processing.
71 OLCUC Convert lowercase to uppercase.
72 ONLCR Map NL to CR-NL.
73 OCRNL Translate carriage return to newline
(output).
74 ONOCR Translate newline to carriage
return-newline (output).
75 ONLRET Newline performs a carriage return
(output).
90 CS7 7 bit mode.
91 CS8 8 bit mode.
92 PARENB Parity enable.
93 PARODD Odd parity, else even.

128 TTY_OP_ISPEED Specifies the input baud rate in
bits per second.
129 TTY_OP_OSPEED Specifies the output baud rate in
bits per second.

9. Summary of Message Numbers

The following is a summary of messages and their associated message
number.

SSH_MSG_GLOBAL_REQUEST 80
SSH_MSG_REQUEST_SUCCESS 81
SSH_MSG_REQUEST_FAILURE 82
SSH_MSG_CHANNEL_OPEN 90
SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91
SSH_MSG_CHANNEL_OPEN_FAILURE 92
SSH_MSG_CHANNEL_WINDOW_ADJUST 93
SSH_MSG_CHANNEL_DATA 94
SSH_MSG_CHANNEL_EXTENDED_DATA 95
SSH_MSG_CHANNEL_EOF 96
SSH_MSG_CHANNEL_CLOSE 97
SSH_MSG_CHANNEL_REQUEST 98
SSH_MSG_CHANNEL_SUCCESS 99
SSH_MSG_CHANNEL_FAILURE 100

10. IANA Considerations

This document is part of a set. The IANA considerations for the SSH
protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], and
this document, are detailed in [SSH-NUMBERS].

11. Security Considerations

This protocol is assumed to run on top of a secure, authenticated
transport. User authentication and protection against network-level
attacks are assumed to be provided by the underlying protocols.

Full security considerations for this protocol are provided in
[SSH-ARCH]. Specific to this document, it is RECOMMENDED that
implementations disable all the potentially dangerous features (e.g.,
agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host
key has changed without notice or explanation.

12. References

12.1. Normative References

[SSH-ARCH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
(SSH) Protocol Architecture", RFC 4251, January 2006.

[SSH-TRANS] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
(SSH) Transport Layer Protocol", RFC 4253, January
2006.

[SSH-USERAUTH] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell
(SSH) Authentication Protocol", RFC 4252, January
2006.

[SSH-NUMBERS] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell
(SSH) Protocol Assigned Numbers", RFC 4250, January
2006.

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing
an IANA Considerations Section in RFCs", BCP 26, RFC
2434, October 1998.

[RFC3066] Alvestrand, H., "Tags for the Identification of
Languages", BCP 47, RFC 3066, January 2001.

[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.

12.2. Informative References

[RFC3330] IANA, "Special-Use IPv4 Addresses", RFC 3330,
September 2002.

[RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version
6 (IPv6) Addressing Architecture", RFC 3513, April
2003.

[SCHEIFLER] Scheifler, R., "X Window System : The Complete
Reference to Xlib, X Protocol, Icccm, Xlfd, 3rd
edition.", Digital Press ISBN 1555580882, February
1992.

[POSIX] ISO/IEC, 9945-1., "Information technology -- Portable
Operating System Interface (POSIX)-Part 1: System
Application Program Interface (API) C Language", ANSI/
IEE Std 1003.1, July 1996.

Authors' Addresses

Tatu Ylonen
SSH Communications Security Corp
Valimotie 17
00380 Helsinki
Finland

EMail: ylo@ssh.com

Chris Lonvick (editor)
Cisco Systems, Inc.
12515 Research Blvd.
Austin 78759
USA

EMail: clonvick@cisco.com

Trademark Notice

"ssh" is a registered trademark in the United States and/or other
countries.

Full Copyright Statement

This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.

This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.

Acknowledgement

Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).