home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_q_t / draft-ietf-secsh-connect-02.txt < prev    next >
Text File  |  1997-10-14  |  35KB  |  943 lines
  1. Network Working Group                                          T. Ylonen
  2. INTERNET-DRAFT                                                T. Kivinen
  3. draft-ietf-secsh-connect-02.txt                              M. Saarinen
  4. Expires in six months                                                SSH
  5.                                                          14 October 1997
  6.  
  7.                         SSH Connection Protocol
  8.  
  9. Status of This memo
  10.  
  11. This document is an Internet-Draft. Internet-Drafts are working
  12. documents of the Internet Engineering Task Force (IETF), its areas,
  13. and its working groups. Note that other groups may also distribute
  14. working documents as Internet-Drafts.
  15.  
  16. Internet-Drafts are draft documents valid for a maximum of six
  17. months and may be updated, replaced, or obsoleted by other documents
  18. at any time. It is inappropriate to use Internet-Drafts as reference
  19. material or to cite them other than as ``work in progress.''
  20.  
  21. To learn the current status of any Internet-Draft, please check
  22. the ``1id-abstracts.txt'' listing contained in the Internet-Drafts
  23. Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
  24. munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast),
  25. or ftp.isi.edu (US West Coast).
  26.  
  27. Abstract
  28.  
  29. SSH is a protocol for secure remote login and other secure network ser-
  30. vices over an insecure network. 
  31.  
  32. This document describes the SSH connection protocol. It provides 
  33. interactive login sessions, remote execution of commands, forwarded 
  34. TCP/IP connections, and forwarded X11 connections. All of these 
  35. channels are multiplexed into a single encrypted tunnel.  
  36.  
  37. The SSH Connection Protocol has been designed to run on top of the 
  38. SSH transport layer and user authentication protocols.
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58. T. Ylonen, T. Kivinen, and M. Saarinen                          [page 1]
  59.  
  60. INTERNET-DRAFT                                           14 October 1997
  61.  
  62. Table of Contents
  63.  
  64. 1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . .  2
  65. 2.  Global Requests   . . . . . . . . . . . . . . . . . . . . . . . .  2
  66. 3.  Channel Mechanism   . . . . . . . . . . . . . . . . . . . . . . .  3
  67.   3.1.  Opening a Channel   . . . . . . . . . . . . . . . . . . . . .  3
  68.   3.2.  Data Transfer   . . . . . . . . . . . . . . . . . . . . . . .  4
  69.   3.3.  Closing a Channel   . . . . . . . . . . . . . . . . . . . . .  5
  70.   3.4.  Channel-Specific Requests   . . . . . . . . . . . . . . . . .  6
  71. 4.  Interactive Sessions  . . . . . . . . . . . . . . . . . . . . . .  6
  72.   4.1.  Opening a Session   . . . . . . . . . . . . . . . . . . . . .  6
  73.   4.2.  Requesting a Pseudo-Terminal  . . . . . . . . . . . . . . . .  7
  74.   4.3.  X11 Forwarding  . . . . . . . . . . . . . . . . . . . . . . .  7
  75.     4.3.1.  Requesting X11 Forwarding   . . . . . . . . . . . . . . .  7
  76.     4.3.2.  X11 Channels  . . . . . . . . . . . . . . . . . . . . . .  7
  77.   4.4.  Authentication Agent Forwarding   . . . . . . . . . . . . . .  8
  78.     4.4.1.  Requesting Authentication Agent Forwarding  . . . . . . .  8
  79.     4.4.2.  Authentication Agent Channels   . . . . . . . . . . . . .  8
  80.   4.5.  Environment Variable Passing  . . . . . . . . . . . . . . . .  9
  81.   4.6.  Starting a Shell or a Command   . . . . . . . . . . . . . . .  9
  82.   4.7.  Session Data Transfer   . . . . . . . . . . . . . . . . . . . 10
  83.   4.8.  Window Dimension Change Message   . . . . . . . . . . . . . . 10
  84.   4.9.  Local Flow Control  . . . . . . . . . . . . . . . . . . . . . 10
  85.   4.10.  Signals  . . . . . . . . . . . . . . . . . . . . . . . . . . 11
  86.   4.11.  Returning Exit Status  . . . . . . . . . . . . . . . . . . . 11
  87. 5.  TCP/IP Port Forwarding  . . . . . . . . . . . . . . . . . . . . . 11
  88.   5.1.  Requesting Port Forwarding  . . . . . . . . . . . . . . . . . 11
  89.   5.2.  TCP/IP Forwarding Channels  . . . . . . . . . . . . . . . . . 12
  90. 6.  Encoding of Terminal Modes  . . . . . . . . . . . . . . . . . . . 13
  91. 7.  Summary of Message Numbers  . . . . . . . . . . . . . . . . . . . 15
  92. 8.  Security Considerations   . . . . . . . . . . . . . . . . . . . . 15
  93. 9.  References  . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
  94. 10.  Authors' Addresses   . . . . . . . . . . . . . . . . . . . . . . 16
  95.  
  96.  
  97.  
  98. 1.  Introduction
  99.  
  100. The SSH Connection Protocol has been designed to run on top of the SSH
  101. transport layer and user authentication protocols. It provides
  102. interactive login sessions, remote execution of commands, forwarded
  103. TCP/IP connections, and forwarded X11 connections.  The service name for
  104. this protocol (after user authentication) is "ssh-connection".
  105.  
  106. This document should be read only after reading the SSH architecture
  107. document [SSH-ARCH]. This document freely uses terminology and notation
  108. from the architecture document without reference or further explanation.
  109.  
  110. 2.  Global Requests
  111.  
  112. There are several kinds of requests that affect the state of the remote
  113. end "globally", independent of any channels.  An example is a request to
  114. start TCP/IP forwarding for a specific port.  All such requests use the
  115.  
  116.  
  117. T. Ylonen, T. Kivinen, and M. Saarinen                          [page 2]
  118.  
  119. INTERNET-DRAFT                                           14 October 1997
  120.  
  121. following format.
  122.  
  123.   byte      SSH_MSG_GLOBAL_REQUEST
  124.   string    request name (restricted to US-ASCII)
  125.   boolean   want reply
  126.   ... request-specific data follows
  127.  
  128. The recipient will respond to this message with SSH_MSG_REQUEST_SUCCESS,
  129. SSH_MSG_REQUEST_FAILURE, or some request-specific continuation messages
  130. if `want reply' is TRUE.
  131.  
  132.   byte      SSH_MSG_REQUEST_SUCCESS
  133.  
  134. If the recipient does not recognize or support the request, it simply
  135. responds with SSH_MSG_REQUEST_FAILURE.
  136.  
  137.   byte      SSH_MSG_REQUEST_FAILURE
  138.  
  139. 3.  Channel Mechanism
  140.  
  141. All terminal sessions, forwarded connections, etc. are channels.  Either
  142. side may open a channel.  Multiple channels are multiplexed into a
  143. single connection.
  144.  
  145. Channels are identified by numbers at each end.  The number referring to
  146. a channel may be different on each side.  Requests to open a channel
  147. contain the sender's channel number.  Any other channel-related messages
  148. contain the recipient's channel number for the channel.
  149.  
  150. Channels are flow-controlled.  No data may be sent to a channel until a
  151. message is received to indicate that window space is available.
  152.  
  153. 3.1.  Opening a Channel
  154.  
  155. When either side wishes to open a new channel, it allocates a local
  156. number for the channel.  It then sends the following message to the
  157. other side, and includes the local channel number and initial window
  158. size in the message.
  159.  
  160.   byte      SSH_MSG_CHANNEL_OPEN
  161.   string    channel type (restricted to US-ASCII)
  162.   uint32    sender channel
  163.   uint32    initial window size
  164.   uint32    maximum packet size
  165.   ... channel type specific data follows
  166.  
  167. The channel type is a name as described in the SSH architecture
  168. document, with similar extension mechanisms. `sender channel' is a local
  169. identifier for the channel used by the sender of this message.  `initial
  170. window size' specifies how many bytes of channel data can be sent to the
  171. sender of this message without adjusting the window. `Maximum packet
  172. size' specifies the maximum size of an individual data packet that can
  173. be sent to the sender (for example, one might want to use smaller
  174.  
  175.  
  176. T. Ylonen, T. Kivinen, and M. Saarinen                          [page 3]
  177.  
  178. INTERNET-DRAFT                                           14 October 1997
  179.  
  180. packets for interactive connections to get better interactive response
  181. on slow links).
  182.  
  183. The remote side then decides whether it can open the channel, and
  184. responds with either
  185.   byte      SSH_MSG_CHANNEL_OPEN_CONFIRMATION
  186.   uint32    recipient channel
  187.   uint32    sender channel
  188.   uint32    initial window size
  189.   uint32    maximum packet size
  190.   ... channel type specific data follows
  191.  
  192. where `recipient channel' is the channel number given in the original
  193. open request, and `sender channel' is the channel number allocated by
  194. the other side, or
  195.  
  196.   byte      SSH_MSG_CHANNEL_OPEN_FAILURE
  197.   uint32    recipient channel
  198.   uint32    reason code
  199.   string    additional textual information (ISO-10646 UTF-8
  200.             [[RFC-2044]])
  201.   string    language tag (as defined in [[RFC-1766]])
  202.  
  203. If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support
  204. the specified channel type, it simply responds with
  205. SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional
  206. information to the user. If this is done, the client software should
  207. take the precautions discussed in [SSH-ARCH].
  208.  
  209. The following reason codes are defined:
  210.  
  211. #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED    1
  212. #define SSH_OPEN_CONNECT_FAILED                 2
  213. #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE           3
  214. #define SSH_OPEN_RESOURCE_SHORTAGE              4
  215.  
  216. 3.2.  Data Transfer
  217.  
  218. The window size specifies how many bytes the other party can send before
  219. it must wait for the window to be adjusted.  Both parties use the
  220. following message to adjust the window.
  221.  
  222.   byte      SSH_MSG_CHANNEL_WINDOW_ADJUST
  223.   uint32    recipient channel
  224.   uint32    bytes to add
  225.  
  226. After receiving this message, the recipient MAY send the given number of
  227. bytes more that it was previously allowed to send; the window size is
  228. incremented.
  229.  
  230. Data transfer is done with messages of the following type.
  231.  
  232.   byte      SSH_MSG_CHANNEL_DATA
  233.  
  234.  
  235. T. Ylonen, T. Kivinen, and M. Saarinen                          [page 4]
  236.  
  237. INTERNET-DRAFT                                           14 October 1997
  238.  
  239.   uint32    recipient channel
  240.   string    data
  241.  
  242. The maximum amount of data allowed is the current window size.  The
  243. window size is decremented by the amount of data sent. Both parties MAY
  244. ignore all extra data sent after the allowed window is empty.
  245.  
  246. Additionally, some channels can transfer several types of data.  An
  247. example of this is stderr data from interactive sessions.  Such data can
  248. be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a separate
  249. integer specifies the type of the data.  The available types and their
  250. interpretation depend on the type of the channel.
  251.  
  252.   byte      SSH_MSG_CHANNEL_EXTENDED_DATA
  253.   uint32    recipient_channel
  254.   uint32    data_type_code
  255.   string    data
  256.  
  257. Data sent with these messages consumes the same window as ordinary data.
  258.  
  259. Currently, only the following type is defined.
  260.  
  261. #define SSH_EXTENDED_DATA_STDERR                1
  262.  
  263. 3.3.  Closing a Channel
  264.  
  265. When a party will no longer send more data to a channel, it SHOULD send
  266. SSH_MSG_CHANNEL_EOF.
  267.  
  268.   byte      SSH_MSG_CHANNEL_EOF
  269.   uint32    recipient_channel
  270.  
  271. No explicit response is sent to this message; however, the application
  272. may send EOF to whatever is at the other end of the channel.  Note that
  273. the channel remains open after this message, and more data may still be
  274. sent in the other direction.  This message does not consume window space
  275. and can be sent even if no window space is available.
  276.  
  277. When either party wishes to terminate the channel, it sends
  278. SSH_MSG_CHANNEL_CLOSE.  Upon receiving this message, a party MUST send
  279. back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this message for
  280. the channel.  The channel is considered closed for a party when it has
  281. both sent and received SSH_MSG_CHANNEL_CLOSE, and the party may then
  282. reuse the channel number.  A party MAY send SSH_MSG_CHANNEL_CLOSE
  283. without having sent or received SSH_MSG_EOF.
  284.   byte      SSH_MSG_CHANNEL_CLOSE
  285.   uint32    recipient_channel
  286.  
  287. This message does not consume window space and can be sent even if no
  288. window space is available.
  289.  
  290. It is recommended that any data sent before this message is delivered to
  291. the actual destination, if possible.
  292.  
  293.  
  294. T. Ylonen, T. Kivinen, and M. Saarinen                          [page 5]
  295.  
  296. INTERNET-DRAFT                                           14 October 1997
  297.  
  298. 3.4.  Channel-Specific Requests
  299.  
  300. Many channel types have extensions that are specific to that particular
  301. channel type.  An example is requesting a pty (pseudo terminal) for an
  302. interactive session.
  303.  
  304. All channel-specific requests use the following format.
  305.  
  306.   byte      SSH_MSG_CHANNEL_REQUEST
  307.   uint32    recipient channel
  308.   string    request type (restricted to US-ASCII)
  309.   boolean   want reply
  310.   ... type-specific data
  311.  
  312. If want reply is FALSE, no response will be sent to the request.
  313. Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS or
  314. SSH_MSG_CHANNEL_FAILURE, or request-specific continuation messages.  If
  315. the request is not recognized or is not supported for the channel,
  316. SSH_MSG_CHANNEL_FAILURE is returned.
  317.  
  318. This message does not consume window space and can be sent even if no
  319. window space is available. Request types are local to each channel type.
  320.  
  321. The client is allowed to send further messages without waiting for the
  322. response to the request.
  323.  
  324.   byte      SSH_MSG_CHANNEL_SUCCESS
  325.   uint32    recipient_channel
  326.  
  327.   byte      SSH_MSG_CHANNEL_FAILURE
  328.   uint32    recipient_channel
  329.  
  330. These messages do not consume window space and can be sent even if no
  331. window space is available.
  332. 4.  Interactive Sessions
  333.  
  334. A session is a remote execution of a program.  The program may be a
  335. shell, an application, a system command, or some built-in subsystem.  It
  336. may or may not have a tty, and may or may not involve X11 forwarding.
  337. Multiple sessions can be active simultaneously.
  338.  
  339. 4.1.  Opening a Session
  340.  
  341. A session is started by sending the following message.
  342.  
  343.   byte      SSH_MSG_CHANNEL_OPEN
  344.   string    "session"
  345.   uint32    sender channel
  346.   uint32    initial window size
  347.   uint32    maximum packet size
  348.  
  349. Client implementations SHOULD reject any session channel open requests
  350. to make it more difficult for a corrupt server to attack the client.
  351.  
  352.  
  353. T. Ylonen, T. Kivinen, and M. Saarinen                          [page 6]
  354.  
  355. INTERNET-DRAFT                                           14 October 1997
  356.  
  357. 4.2.  Requesting a Pseudo-Terminal
  358.  
  359. A pseudo-terminal can be allocated for the session by sending the
  360. following message.
  361.  
  362.   byte      SSH_MSG_CHANNEL_REQUEST
  363.   uint32    recipient_channel
  364.   string    "pty-req"
  365.   boolean   want_reply
  366.   string    TERM environment variable value (e.g., vt100)
  367.   uint32    terminal width, characters (e.g., 80)
  368.   uint32    terminal height, rows (e.g., 24)
  369.   uint32    terminal width, pixels (e.g., 480)
  370.   uint32    terminal height, pixels (e.g., 640)
  371.   string    encoded terminal modes
  372.  
  373. The encoding of terminal modes is described in Section ``Encoding of
  374. Terminal Modes''. Zero dimension parameters MUST be ignored. The
  375. dimension parameters are only informational.
  376.  
  377. The client SHOULD ignore pty requests.
  378.  
  379. 4.3.  X11 Forwarding
  380.  
  381. 4.3.1.  Requesting X11 Forwarding
  382.  
  383. X11 forwarding may be requested for a session by sending
  384.  
  385.   byte      SSH_MSG_CHANNEL_REQUEST
  386.   uint32    recipient channel
  387.   string    "x11-req"
  388.   boolean   want reply
  389.   boolean   single connection
  390.   string    x11 authentication protocol
  391.   string    x11 authentication cookie
  392.   uint32    x11 screen number
  393.  
  394. It is recommended that the authentication cookie that is sent be a fake,
  395. random cookie, and that the cookie is checked and replaced by the real
  396. cookie when a connection request is received.
  397.  
  398. X11 connection forwarding should stop when the session channel is
  399. closed; however, already opened forwardings should not be automatically
  400. closed when the session channel is closed.
  401.  
  402. If `single connection' is TRUE, only a single connection should be
  403. forwarded.  No more connections will be forwarded after the first, or
  404. after the session channel has been closed.
  405.  
  406. `X11 authentication protocol is the name of the X11 authentication
  407. method used, i.e. "MIT-MAGIC-COOKIE-1".
  408.  
  409.  
  410.  
  411.  
  412. T. Ylonen, T. Kivinen, and M. Saarinen                          [page 7]
  413.  
  414. INTERNET-DRAFT                                           14 October 1997
  415.  
  416. 4.3.2.  X11 Channels
  417.  
  418. X11 channels are opened with a channel open request.  The resulting
  419. channels are independent of the session, and closing the session channel
  420. does not close the forwarded X11 channels.
  421.  
  422.   byte      SSH_MSG_CHANNEL_OPEN
  423.   string    "x11"
  424.   uint32    sender channel
  425.   uint32    initial window size
  426.   uint32    maximum packet size
  427.   string    originator IP address (e.g. "192.168.7.38")
  428.   uint32    originator port
  429.  
  430. The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or
  431. SSH_MSG_CHANNEL_OPEN_FAILURE.
  432.  
  433. Implementations MUST reject any X11 channel open requests if they have
  434. not requested X11 forwarding.
  435.  
  436. 4.4.  Authentication Agent Forwarding
  437.  
  438. It is RECOMMENDED that authentication agent forwarding is allowed even
  439. when either or both parties do not support the SSH authentication agent
  440. protocol [SSH-AGENT].
  441.  
  442. 4.4.1.  Requesting Authentication Agent Forwarding
  443.  
  444. Authentication agent forwarding may be requested for a session by
  445. sending
  446.  
  447.   byte      SSH_MSG_CHANNEL_REQUEST
  448.   uint32    recipient channel
  449.   string    "auth-agent-req"
  450.   boolean   want reply
  451.  
  452. The server responds with either SSH_MSG_CHANNEL_SUCCESS or
  453. SSH_MSG_CHANNEL_FAILURE (if `want reply' is TRUE).  The client MAY to
  454. send further messages without waiting for the response to this message.
  455.  
  456. 4.4.2.  Authentication Agent Channels
  457.  
  458. When an application requests a connection to the authentication agent,
  459. the following message is sent to the originator of the session.
  460.  
  461.   byte      SSH_MSG_CHANNEL_OPEN
  462.   string    "auth-agent"
  463.   uint32    sender channel
  464.   uint32    initial window size
  465.   uint32    maximum packet size
  466.  
  467. The recipient should respond with open confirmation or open failure.
  468.  
  469.  
  470.  
  471. T. Ylonen, T. Kivinen, and M. Saarinen                          [page 8]
  472.  
  473. INTERNET-DRAFT                                           14 October 1997
  474.  
  475. Implementations MUST reject any agent channel open requests if they have
  476. not requested agent forwarding.
  477.  
  478. 4.5.  Environment Variable Passing
  479.  
  480. Environment variables may be passed to the shell/command to be started
  481. later.  Typically, each machine will have a preconfigured set of
  482. variables that it will allow.  Since uncontrolled setting of environment
  483. variables can be very dangerous, it is recommended that implementations
  484. allow setting only variables whose names have been explicitly configured
  485. to be allowed.
  486.  
  487.   byte      SSH_MSG_CHANNEL_REQUEST
  488.   uint32    recipient channel
  489.   string    "env"
  490.   boolean   want reply
  491.   string    variable name
  492.   string    variable value
  493.  
  494. 4.6.  Starting a Shell or a Command
  495.  
  496. Once the session has been set up, a program is started at the remote
  497. end. Program can be a shell, an application program or a subsystem with
  498. a host-independent name.  Only one of these requests can succeed per
  499. channel.
  500.  
  501.   byte      SSH_MSG_CHANNEL_REQUEST
  502.   uint32    recipient channel
  503.   string    "shell"
  504.   boolean   want reply
  505.  
  506. This message will request the user's default shell (typically defined in
  507. /etc/passwd in UNIX systems) to be started at the other end.
  508.  
  509.   byte      SSH_MSG_CHANNEL_REQUEST
  510.   uint32    recipient channel
  511.   string    "exec"
  512.   boolean   want reply
  513.   string    command
  514.  
  515. This message will request the server to start the execution of the given
  516. command. The command string may contain a path. Normal precautions MUST
  517. be taken to prevent the execution of unauthorized commands.
  518.  
  519.   byte      SSH_MSG_CHANNEL_REQUEST
  520.   uint32    recipient channel
  521.   string    "subsystem"
  522.   boolean   want reply
  523.   string    subsystem name
  524.  
  525. This last form executes a predefined subsystem.  It expected that these
  526. will include a general file transfer mechanism, and possibly other
  527. features.  Implementations may also allow configuring more such
  528.  
  529.  
  530. T. Ylonen, T. Kivinen, and M. Saarinen                          [page 9]
  531.  
  532. INTERNET-DRAFT                                           14 October 1997
  533.  
  534. mechanisms.
  535.  
  536. The server SHOULD not halt the execution of the protocol stack when
  537. starting a shell or a program. All input and output from these SHOULD be
  538. redirected the the channel or to the encrypted tunnel.
  539.  
  540. It is RECOMMENDED to request and check the reply for these messages. The
  541. client SHOULD ignore these messages.
  542.  
  543. 4.7.  Session Data Transfer
  544.  
  545. Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and
  546. SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism.  The
  547. extended data type SSH_EXTENDED_DATA_STDERR has been defined for stderr
  548. data.
  549.  
  550. 4.8.  Window Dimension Change Message
  551.  
  552. When the window (terminal) size changes on the client side, it MAY send
  553. a message to the other side to inform it of the new dimensions.
  554.  
  555.   byte      SSH_MSG_CHANNEL_REQUEST
  556.   uint32    recipient_channel
  557.   string    "window-change"
  558.   boolean   FALSE
  559.   uint32    terminal width, columns
  560.   uint32    terminal height, rows
  561.   uint32    terminal width, pixels
  562.   uint32    terminal height, pixels
  563.  
  564. No response SHOULD be sent to this message.
  565.  
  566. 4.9.  Local Flow Control
  567.  
  568. On many systems it is possible to determine if a pseudo-terminal is
  569. using control-S control-Q flow control.  When flow control is allowed,
  570. it is often desirable to do the flow control at the client end to speed
  571. up responses to user requests.  This is facilitated by the following
  572. notification.  Initially, the server is responsible for flow control.
  573. (Here, again, client means the side originating the session, and server
  574. the other side.)
  575.  
  576. The message below is used by the server to inform the client when it can
  577. or cannot perform flow control (control-S/control-Q processing).  If
  578. `client can do' is TRUE, the client is allowed to do flow control using
  579. control-S and control-Q.  The client MAY ignore this message.
  580.  
  581.   byte      SSH_MSG_CHANNEL_REQUEST
  582.   uint32    recipient channel
  583.   string    "xon-xoff"
  584.   boolean   FALSE
  585.   boolean   client can do
  586.  
  587.  
  588.  
  589. T. Ylonen, T. Kivinen, and M. Saarinen                         [page 10]
  590.  
  591. INTERNET-DRAFT                                           14 October 1997
  592.  
  593. No response is sent to this message.
  594.  
  595. 4.10.  Signals
  596.  
  597. A signal can be delivered to the remote process/service using the
  598. following message.  Some systems may not implement signals, in which
  599. case they SHOULD ignore this message.
  600.  
  601.   byte      SSH_MSG_CHANNEL_REQUEST
  602.   uint32    recipient channel
  603.   string    "signal"
  604.   boolean   FALSE
  605.   uint32    signal number
  606.  
  607. 4.11.  Returning Exit Status
  608.  
  609. When the command running at the other end terminates, The following
  610. message can be sent to return the exit status of the command.  Returning
  611. the status is RECOMMENDED.  No acknowledgment is sent for this message.
  612. The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE after this
  613. message.
  614.  
  615. The client SHOULD ignore these messages.
  616.  
  617.   byte      SSH_MSG_CHANNEL_REQUEST
  618.   uint32    recipient_channel
  619.   string    "exit-status"
  620.   boolean   FALSE
  621.   uint32    exit_status
  622.  
  623. The remote command may also terminate violently due to a signal.  Such a
  624. condition can be indicated by the following message.
  625.  
  626.   byte      SSH_MSG_CHANNEL_REQUEST
  627.   uint32    recipient channel
  628.   string    "exit-signal"
  629.   boolean   FALSE
  630.   uint32    signal number
  631.   boolean   core dumped
  632.   string    error message (ISO-10646 UTF-8 [[RFC-2044]])
  633.   string    language tag (as defined in [[RFC-1766]])
  634.  
  635. The `error message' contains an additional explanation of the error
  636. message. The message may consist of multiple lines. The client software
  637. MAY display this message to the user.
  638.  
  639. 5.  TCP/IP Port Forwarding
  640.  
  641. 5.1.  Requesting Port Forwarding
  642.  
  643. A party need not explicitly request forwardings from its own end to the
  644. other direction.  However, it if wishes to have connections to a port on
  645. the other side be forwarded to the local side, it must explicitly
  646.  
  647.  
  648. T. Ylonen, T. Kivinen, and M. Saarinen                         [page 11]
  649.  
  650. INTERNET-DRAFT                                           14 October 1997
  651.  
  652. request this.
  653.  
  654.   byte      SSH_MSG_GLOBAL_REQUEST
  655.   string    "tcpip-forward"
  656.   boolean   want reply
  657.   string    address to bind (e.g. "0.0.0.0")
  658.   uint32    port number to bind
  659.  
  660. `Address to bind' and `port number to bind' specify the IP address and
  661. port to which the socket to be listened is bound.  The address should be
  662. "0.0.0.0" if connections are allowed from anywhere.  (Note that the
  663. client can still filter connections based on information passed in the
  664. open request.)
  665.  
  666. Implementations should only allow forwarding privileged ports if the
  667. user has been authenticated as a privileged user.
  668.  
  669. Client implementations SHOULD reject these messages; they are normally
  670. only sent by the client.
  671.  
  672. A port forwarding can be cancelled with the following message.  Note
  673. that channel open requests may be received until a reply to this message
  674. is received.
  675.  
  676.   byte      SSH_MSG_GLOBAL_REQUEST
  677.   string    "cancel-tcpip-forward"
  678.   boolean   want reply
  679.   string    address_to_bind (e.g. "127.0.0.1")
  680.   uint32    port number to bind
  681.  
  682. Client implementations SHOULD reject these messages; they are normally
  683. only sent by the client.
  684.  
  685. 5.2.  TCP/IP Forwarding Channels
  686.  
  687. When a connection comes to a port for which remote forwarding has been
  688. requested, a channel is opened to forward the port to the other side.
  689.  
  690.   byte      SSH_MSG_CHANNEL_OPEN
  691.   string    "forwarded-tcpip"
  692.   uint32    sender channel
  693.   uint32    initial window size
  694.   uint32    maximum packet size
  695.   string    address that was connected
  696.   uint32    port that was connected
  697.   string    originator IP address
  698.   uint32    originator port
  699.  
  700. Implementations MUST reject these messages unless they have previously
  701. requested a remote TCP/IP port forwarding with the given port number.
  702.  
  703. When a connection comes to a locally forwarded TCP/IP port, the
  704. following packet is sent to the other side.  Note that these messages
  705.  
  706.  
  707. T. Ylonen, T. Kivinen, and M. Saarinen                         [page 12]
  708.  
  709. INTERNET-DRAFT                                           14 October 1997
  710.  
  711. MAY be sent also for ports for which no forwarding has been explicitly
  712. requested.  The receiving side must decide whether to allow the
  713. forwarding.
  714.  
  715.   byte      SSH_MSG_CHANNEL_OPEN
  716.   string    "direct-tcpip"
  717.   uint32    sender channel
  718.   uint32    initial window size
  719.   uint32    maximum packet size
  720.   string    host to connect
  721.   uint32    port to connect
  722.   string    originator IP address
  723.   uint32    originator port
  724.  
  725. `Host to connect' and `port to connect' specify the TCP/IP host and port
  726. where the recipient should connect the channel.  `Host to connect' may
  727. be either a domain name or a numeric IP address.
  728.  
  729. `Originator IP address' is the numeric IP address of the machine where
  730. the connection request comes from, and `originator port' is the port on
  731. the originator host from where the connection came from.
  732.  
  733. Forwarded TCP/IP channels are independent of any sessions, and closing a
  734. session channel does not in any way imply that forwarded connections
  735. should be closed.
  736.  
  737. Client implementations SHOULD reject direct TCP/IP open requests for
  738. security reasons.
  739.  
  740. 6.  Encoding of Terminal Modes
  741.  
  742. Terminal modes (as passed in a pty request) are encoded into a byte
  743. stream.  It is intended that the coding be portable across different
  744. environments.
  745.  
  746. The tty mode description is a stream of bytes.  The stream consists of
  747. opcode-argument pairs.  It is terminated by opcode TTY_OP_END (0).
  748. Opcodes 1-159 have a single uint32 argument. Opcodes 160-255 are not yet
  749. defined, and cause parsing to stop (they should only be used after any
  750. other data).
  751.  
  752. The client SHOULD put in the stream any modes it knows about, and the
  753. server MAY ignore any modes it does not know about.  This allows some
  754. degree of machine-independence, at least between systems that use a
  755. POSIX-like tty interface.  The protocol can support other systems as
  756. well, but the client may need to fill reasonable values for a number of
  757. parameters so the server pty gets set to a reasonable mode (the server
  758. leaves all unspecified mode bits in their default values, and only some
  759. combinations make sense).
  760.  
  761. The following opcodes have been defined.  The naming of opcodes mostly
  762. follows the POSIX terminal mode flags.
  763.  
  764.  
  765.  
  766. T. Ylonen, T. Kivinen, and M. Saarinen                         [page 13]
  767.  
  768. INTERNET-DRAFT                                           14 October 1997
  769.  
  770. 0   TTY_OP_END     Indicates end of options.
  771. 1   VINTR          Interrupt character; 255 if none.  Similarly for the
  772.                    other characters. Not all of these characters are
  773.                    supported on all systems.
  774. 2   VQUIT          The quit character (sends SIGQUIT signal on POSIX
  775.                    systems).
  776. 3   VERASE         Erase the character to left of the cursor.
  777. 4   VKILL          Kill the current input line.
  778. 5   VEOF           End-of-file character (sends EOF from the terminal).
  779. 6   VEOL           End-of-line character in addition to carriage return
  780.                    and/or linefeed.
  781. 7   VEOL2          Additional end-of-line character.
  782. 8   VSTART         Continues paused output (normally control-Q).
  783. 9   VSTOP          Pauses output (normally control-S).
  784. 10  VSUSP          Suspends the current program.
  785. 11  VDSUSP         Another suspend character.
  786. 12  VREPRINT       Reprints the current input line.
  787. 13  VWERASE        Erases a word left of cursor.
  788. 14  VLNEXT         Enter the next character typed literally, even if it
  789.                    is a special character
  790. 15  VFLUSH         Character to flush output.
  791. 16  VSWTCH         Switch to a different shell layer.
  792. 17  VSTATUS        Prints system status line (load, command, pid etc).
  793. 18  VDISCARD       Toggles the flushing of terminal output.
  794. 30  IGNPAR         The ignore parity flag.  The parameter SHOULD be 0 if
  795.                    this flag is FALSE set, and 1 if it is TRUE.
  796. 31  PARMRK         Mark parity and framing errors.
  797. 32  INPCK          Enable checking of parity errors.
  798. 33  ISTRIP         Strip 8th bit off characters.
  799. 34  INLCR          Map NL into CR on input.
  800. 35  IGNCR          Ignore CR on input.
  801. 36  ICRNL          Map CR to NL on input.
  802. 37  IUCLC          Translate uppercase characters to lowercase.
  803. 38  IXON           Enable output flow control.
  804. 39  IXANY          Any char will restart after stop.
  805. 40  IXOFF          Enable input flow control.
  806. 41  IMAXBEL        Ring bell on input queue full.
  807. 50  ISIG           Enable signals INTR, QUIT, [[D]]SUSP.
  808. 51  ICANON         Canonicalize input lines.
  809. 52  XCASE          Enable input and output of uppercase characters by
  810.                    preceding their lowercase equivalents with `\'.
  811. 53  ECHO           Enable echoing.
  812. 54  ECHOE          Visually erase chars.
  813. 55  ECHOK          Kill character discards current line.
  814. 56  ECHONL         Echo NL even if ECHO is off.
  815. 57  NOFLSH         Don't flush after interrupt.
  816. 58  TOSTOP         Stop background jobs from output.
  817. 59  IEXTEN         Enable extensions.
  818. 60  ECHOCTL        Echo control characters as ^(Char).
  819. 61  ECHOKE         Visual erase for line kill.
  820. 62  PENDIN         Retype pending input.
  821. 70  OPOST          Enable output processing.
  822. 71  OLCUC          Convert lowercase to uppercase.
  823.  
  824.  
  825. T. Ylonen, T. Kivinen, and M. Saarinen                         [page 14]
  826.  
  827. INTERNET-DRAFT                                           14 October 1997
  828.  
  829. 72  ONLCR          Map NL to CR-NL.
  830. 73  OCRNL          Translate carriage return to newline (output).
  831. 74  ONOCR          Translate newline to carriage return-newline
  832.                    (output).
  833. 75  ONLRET         Newline performs a carriage return (output).
  834. 90  CS7            7 bit mode.
  835. 91  CS8            8 bit mode.
  836. 92  PARENB         Parity enable.
  837. 93  PARODD         Odd parity, else even.
  838.  
  839. 128 TTY_OP_ISPEED  Specifies the input baud rate in bits per second.
  840. 129 TTY_OP_OSPEED  Specifies the output baud rate in bits per second.
  841.  
  842. 7.  Summary of Message Numbers
  843.  
  844.   #define SSH_MSG_GLOBAL_REQUEST                  80
  845.   #define SSH_MSG_REQUEST_SUCCESS                 81
  846.   #define SSH_MSG_REQUEST_FAILURE                 82
  847.   #define SSH_MSG_CHANNEL_OPEN                    90
  848.   #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION       91
  849.   #define SSH_MSG_CHANNEL_OPEN_FAILURE            92
  850.   #define SSH_MSG_CHANNEL_WINDOW_ADJUST           93
  851.   #define SSH_MSG_CHANNEL_DATA                    94
  852.   #define SSH_MSG_CHANNEL_EXTENDED_DATA           95
  853.   #define SSH_MSG_CHANNEL_EOF                     96
  854.   #define SSH_MSG_CHANNEL_CLOSE                   97
  855.   #define SSH_MSG_CHANNEL_REQUEST                 98
  856.   #define SSH_MSG_CHANNEL_SUCCESS                 99
  857.   #define SSH_MSG_CHANNEL_FAILURE                 100
  858.  
  859. 8.  Security Considerations
  860.  
  861. This protocol is assumed to run on top of a secure, authenticated
  862. transport.  User authentication and protection against network-level
  863. attacks are assumed to be provided by the underlying protocols.
  864.  
  865. This protocol can, however, be used to execute commands on remote
  866. machines.  The protocol also permits the server to run commands on the
  867. client.  Implementations may wish to disallow this to prevent an
  868. attacker from coming from the server machine to the client machine.
  869.  
  870. X11 forwarding provides major security improvements over normal cookie-
  871. based X11 forwarding.  The cookie never needs to be transmitted in the
  872. clear, and traffic is encrypted and integrity-protected.  No useful
  873. authentication data will remain on the server machine after the
  874. connection has been closed.  On the other hand, in some situations a
  875. forwarded X11 connection might be used to get access to the local X
  876. server across security perimeters.
  877.  
  878. Port forwardings can potentially allow an intruder to cross security
  879. perimeters such as firewalls.  They do not offer anything fundamentally
  880. new that a user couldn't do otherwise; however, they make opening
  881. tunnels very easy.  Implementations should allow policy control over
  882.  
  883.  
  884. T. Ylonen, T. Kivinen, and M. Saarinen                         [page 15]
  885.  
  886. INTERNET-DRAFT                                           14 October 1997
  887.  
  888. what can be forwarded.  Administrators should be able to deny
  889. forwardings where appropriate.
  890.  
  891. Since this protocol normally runs inside an encrypted tunnel, firewalls
  892. will not be able to examine the traffic.
  893.  
  894. It is RECOMMENDED that implementations disable all of the potentially
  895. dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP
  896. forwarding) of host key has changed.
  897.  
  898. 9.  References
  899.  
  900. [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages",
  901. March 1995.
  902.  
  903. [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and
  904. ISO 10646", October 1996.
  905.  
  906. [SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol
  907. Architecture", Internet Draft, draft-ietf-secsh-architecture-00.txt
  908.  
  909. [SSH-TRANS] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Transport
  910. Layer Protocol", Internet Draft, draft-ietf-secsh-transport-02.txt
  911.  
  912. [SSH-USERAUTH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH
  913. Authentication Protocol", Internet Draft, draft-ietf-secsh-
  914. userauth-02.txt
  915.  
  916. 10.  Authors' Addresses
  917.  
  918.     Tatu Ylonen
  919.     SSH Communications Security Ltd.
  920.     Tekniikantie 12
  921.     FIN-02150 ESPOO
  922.     Finland
  923.     E-mail: ylo@ssh.fi
  924.  
  925.     Tero Kivinen
  926.     SSH Communications Security Ltd.
  927.     Tekniikantie 12
  928.     FIN-02150 ESPOO
  929.     Finland
  930.     E-mail: kivinen@ssh.fi
  931.  
  932.     Markku-Juhani O. Saarinen
  933.     SSH Communications Security Ltd.
  934.     Tekniikantie 12
  935.     FIN-02150 ESPOO
  936.     Finland
  937.     E-mail: mjos@ssh.fi
  938.  
  939.  
  940.  
  941.  
  942. T. Ylonen, T. Kivinen, and M. Saarinen                         [page 16]
  943.