idnits 2.17.1 draft-ietf-secsh-connect-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-29) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 170: '...LURE. The client MAY show the addition...' RFC 2119 keyword, line 191: '...e, the recipient MAY send the given nu...' RFC 2119 keyword, line 202: '... amount of data sent. Both parties MAY...' RFC 2119 keyword, line 224: '...more data to a channel, it SHOULD send...' RFC 2119 keyword, line 237: '...eiving this message, a party MUST send...' (32 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 95 has weird spacing: '... string req...' == Line 96 has weird spacing: '...boolean want...' == Line 132 has weird spacing: '... string cha...' == Line 164 has weird spacing: '... string add...' == Line 166 has weird spacing: '... string lan...' == (33 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: 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 the the channel or to the encrypted tunnel. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (6 August 1998) is 9367 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'SSH-AGENT' is mentioned on line 385, but not defined == Unused Reference: 'RFC-1884' is defined on line 834, but no explicit reference was found in the text == Unused Reference: 'SSH-TRANS' is defined on line 843, but no explicit reference was found in the text == Unused Reference: 'SSH-USERAUTH' is defined on line 846, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1766 (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 1884 (Obsoleted by RFC 2373) ** Obsolete normative reference: RFC 2044 (Obsoleted by RFC 2279) == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-00 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-02 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-02 Summary: 12 errors (**), 0 flaws (~~), 15 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group T. Ylonen 2 INTERNET-DRAFT T. Kivinen 3 draft-ietf-secsh-connect-04.txt M. Saarinen 4 Expires in six months T. Rinne 5 S. Lehtinen 6 SSH 7 6 August 1998 9 SSH Connection Protocol 11 Status of This memo 13 This document is an Internet-Draft. Internet-Drafts are working 14 documents of the Internet Engineering Task Force (IETF), its areas, 15 and its working groups. Note that other groups may also distribute 16 working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other documents 20 at any time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as ``work in progress.'' 23 To learn the current status of any Internet-Draft, please check 24 the ``1id-abstracts.txt'' listing contained in the Internet-Drafts 25 Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 26 munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), 27 or ftp.isi.edu (US West Coast). 29 Abstract 31 SSH is a protocol for secure remote login and other secure network ser- 32 vices over an insecure network. This document describes the SSH connec- 33 tion protocol. It provides interactive login sessions, remote execution 34 of commands, forwarded TCP/IP connections, and forwarded X11 connec- 35 tions. All of these channels are multiplexed into a single encrypted 36 tunnel. The SSH Connection Protocol has been designed to run on top of 37 the SSH transport layer and user authentication protocols. 39 Table of Contents 41 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 42 2. Global Requests . . . . . . . . . . . . . . . . . . . . . . . . 2 43 3. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . . 3 44 3.1. Opening a Channel . . . . . . . . . . . . . . . . . . . . . 3 45 3.2. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 4 46 3.3. Closing a Channel . . . . . . . . . . . . . . . . . . . . . 5 47 3.4. Channel-Specific Requests . . . . . . . . . . . . . . . . . 6 48 4. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . . 6 49 4.1. Opening a Session . . . . . . . . . . . . . . . . . . . . . 6 50 4.2. Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 7 51 4.3. X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 7 52 4.3.1. Requesting X11 Forwarding . . . . . . . . . . . . . . . 7 53 4.3.2. X11 Channels . . . . . . . . . . . . . . . . . . . . . . 8 54 4.4. Authentication Agent Forwarding . . . . . . . . . . . . . . 8 55 4.4.1. Requesting Authentication Agent Forwarding . . . . . . . 8 56 4.4.2. Authentication Agent Channels . . . . . . . . . . . . . 8 57 4.5. SSH1 Authentication Agent Forwarding . . . . . . . . . . . . 9 58 4.5.1. Requesting SSH1 Authentication Agent Forwarding . . . . 9 59 4.5.2. SSH1 Authentication Agent Channels . . . . . . . . . . . 9 60 4.6. Environment Variable Passing . . . . . . . . . . . . . . . . 9 61 4.7. Starting a Shell or a Command . . . . . . . . . . . . . . . 10 62 4.8. Session Data Transfer . . . . . . . . . . . . . . . . . . . 10 63 4.9. Window Dimension Change Message . . . . . . . . . . . . . . 11 64 4.10. Local Flow Control . . . . . . . . . . . . . . . . . . . . 11 65 4.11. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 11 66 4.12. Returning Exit Status . . . . . . . . . . . . . . . . . . . 12 67 5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . . 12 68 5.1. Requesting Port Forwarding . . . . . . . . . . . . . . . . . 12 69 5.2. TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 13 70 6. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . . 14 71 7. Summary of Message Numbers . . . . . . . . . . . . . . . . . . . 15 72 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 16 73 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 74 10. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 17 76 1. Introduction 78 The SSH Connection Protocol has been designed to run on top of the SSH 79 transport layer and user authentication protocols. It provides 80 interactive login sessions, remote execution of commands, forwarded 81 TCP/IP connections, and forwarded X11 connections. The service name for 82 this protocol (after user authentication) is "ssh-connection". 84 This document should be read only after reading the SSH architecture 85 document [SSH-ARCH]. This document freely uses terminology and notation 86 from the architecture document without reference or further explanation. 88 2. Global Requests 89 There are several kinds of requests that affect the state of the remote 90 end "globally", independent of any channels. An example is a request to 91 start TCP/IP forwarding for a specific port. All such requests use the 92 following format. 94 byte SSH_MSG_GLOBAL_REQUEST 95 string request name (restricted to US-ASCII) 96 boolean want reply 97 ... request-specific data follows 99 The recipient will respond to this message with SSH_MSG_REQUEST_SUCCESS, 100 SSH_MSG_REQUEST_FAILURE, or some request-specific continuation messages 101 if `want reply' is TRUE. 103 byte SSH_MSG_REQUEST_SUCCESS 105 If the recipient does not recognize or support the request, it simply 106 responds with SSH_MSG_REQUEST_FAILURE. 108 byte SSH_MSG_REQUEST_FAILURE 110 3. Channel Mechanism 112 All terminal sessions, forwarded connections, etc. are channels. Either 113 side may open a channel. Multiple channels are multiplexed into a 114 single connection. 116 Channels are identified by numbers at each end. The number referring to 117 a channel may be different on each side. Requests to open a channel 118 contain the sender's channel number. Any other channel-related messages 119 contain the recipient's channel number for the channel. 121 Channels are flow-controlled. No data may be sent to a channel until a 122 message is received to indicate that window space is available. 124 3.1. Opening a Channel 126 When either side wishes to open a new channel, it allocates a local 127 number for the channel. It then sends the following message to the 128 other side, and includes the local channel number and initial window 129 size in the message. 131 byte SSH_MSG_CHANNEL_OPEN 132 string channel type (restricted to US-ASCII) 133 uint32 sender channel 134 uint32 initial window size 135 uint32 maximum packet size 136 ... channel type specific data follows 138 The channel type is a name as described in the SSH architecture 139 document, with similar extension mechanisms. `sender channel' is a local 140 identifier for the channel used by the sender of this message. `initial 141 window size' specifies how many bytes of channel data can be sent to the 142 sender of this message without adjusting the window. `Maximum packet 143 size' specifies the maximum size of an individual data packet that can 144 be sent to the sender (for example, one might want to use smaller 145 packets for interactive connections to get better interactive response 146 on slow links). 148 The remote side then decides whether it can open the channel, and 149 responds with either 150 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 151 uint32 recipient channel 152 uint32 sender channel 153 uint32 initial window size 154 uint32 maximum packet size 155 ... channel type specific data follows 157 where `recipient channel' is the channel number given in the original 158 open request, and `sender channel' is the channel number allocated by 159 the other side, or 161 byte SSH_MSG_CHANNEL_OPEN_FAILURE 162 uint32 recipient channel 163 uint32 reason code 164 string additional textual information (ISO-10646 UTF-8 165 [RFC-2044]) 166 string language tag (as defined in [RFC-1766]) 168 If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support 169 the specified channel type, it simply responds with 170 SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional 171 information to the user. If this is done, the client software should 172 take the precautions discussed in [SSH-ARCH]. 174 The following reason codes are defined: 176 #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 177 #define SSH_OPEN_CONNECT_FAILED 2 178 #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 179 #define SSH_OPEN_RESOURCE_SHORTAGE 4 181 3.2. Data Transfer 183 The window size specifies how many bytes the other party can send before 184 it must wait for the window to be adjusted. Both parties use the 185 following message to adjust the window. 187 byte SSH_MSG_CHANNEL_WINDOW_ADJUST 188 uint32 recipient channel 189 uint32 bytes to add 191 After receiving this message, the recipient MAY send the given number of 192 bytes more that it was previously allowed to send; the window size is 193 incremented. 195 Data transfer is done with messages of the following type. 197 byte SSH_MSG_CHANNEL_DATA 198 uint32 recipient channel 199 string data 201 The maximum amount of data allowed is the current window size. The 202 window size is decremented by the amount of data sent. Both parties MAY 203 ignore all extra data sent after the allowed window is empty. 205 Additionally, some channels can transfer several types of data. An 206 example of this is stderr data from interactive sessions. Such data can 207 be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a separate 208 integer specifies the type of the data. The available types and their 209 interpretation depend on the type of the channel. 211 byte SSH_MSG_CHANNEL_EXTENDED_DATA 212 uint32 recipient_channel 213 uint32 data_type_code 214 string data 216 Data sent with these messages consumes the same window as ordinary data. 218 Currently, only the following type is defined. 220 #define SSH_EXTENDED_DATA_STDERR 1 222 3.3. Closing a Channel 224 When a party will no longer send more data to a channel, it SHOULD send 225 SSH_MSG_CHANNEL_EOF. 227 byte SSH_MSG_CHANNEL_EOF 228 uint32 recipient_channel 230 No explicit response is sent to this message; however, the application 231 may send EOF to whatever is at the other end of the channel. Note that 232 the channel remains open after this message, and more data may still be 233 sent in the other direction. This message does not consume window space 234 and can be sent even if no window space is available. 236 When either party wishes to terminate the channel, it sends 237 SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST send 238 back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this message for 239 the channel. The channel is considered closed for a party when it has 240 both sent and received SSH_MSG_CHANNEL_CLOSE, and the party may then 241 reuse the channel number. A party MAY send SSH_MSG_CHANNEL_CLOSE 242 without having sent or received SSH_MSG_CHANNEL_EOF. 243 byte SSH_MSG_CHANNEL_CLOSE 244 uint32 recipient_channel 246 This message does not consume window space and can be sent even if no 247 window space is available. 249 It is recommended that any data sent before this message is delivered to 250 the actual destination, if possible. 252 3.4. Channel-Specific Requests 254 Many channel types have extensions that are specific to that particular 255 channel type. An example is requesting a pty (pseudo terminal) for an 256 interactive session. 258 All channel-specific requests use the following format. 260 byte SSH_MSG_CHANNEL_REQUEST 261 uint32 recipient channel 262 string request type (restricted to US-ASCII) 263 boolean want reply 264 ... type-specific data 266 If want reply is FALSE, no response will be sent to the request. 267 Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS or 268 SSH_MSG_CHANNEL_FAILURE, or request-specific continuation messages. If 269 the request is not recognized or is not supported for the channel, 270 SSH_MSG_CHANNEL_FAILURE is returned. 272 This message does not consume window space and can be sent even if no 273 window space is available. Request types are local to each channel type. 275 The client is allowed to send further messages without waiting for the 276 response to the request. 278 byte SSH_MSG_CHANNEL_SUCCESS 279 uint32 recipient_channel 281 byte SSH_MSG_CHANNEL_FAILURE 282 uint32 recipient_channel 284 These messages do not consume window space and can be sent even if no 285 window space is available. 286 4. Interactive Sessions 288 A session is a remote execution of a program. The program may be a 289 shell, an application, a system command, or some built-in subsystem. It 290 may or may not have a tty, and may or may not involve X11 forwarding. 291 Multiple sessions can be active simultaneously. 293 4.1. Opening a Session 295 A session is started by sending the following message. 297 byte SSH_MSG_CHANNEL_OPEN 298 string "session" 299 uint32 sender channel 300 uint32 initial window size 301 uint32 maximum packet size 303 Client implementations SHOULD reject any session channel open requests 304 to make it more difficult for a corrupt server to attack the client. 306 4.2. Requesting a Pseudo-Terminal 308 A pseudo-terminal can be allocated for the session by sending the 309 following message. 311 byte SSH_MSG_CHANNEL_REQUEST 312 uint32 recipient_channel 313 string "pty-req" 314 boolean want_reply 315 string TERM environment variable value (e.g., vt100) 316 uint32 terminal width, characters (e.g., 80) 317 uint32 terminal height, rows (e.g., 24) 318 uint32 terminal width, pixels (e.g., 480) 319 uint32 terminal height, pixels (e.g., 640) 320 string encoded terminal modes 322 The encoding of terminal modes is described in Section ``Encoding of 323 Terminal Modes''. Zero dimension parameters MUST be ignored. The 324 character/row dimensions override the pixel dimensions (when nonzero). 325 Pixel dimensions refer to the drawable area of the window. 327 The dimension parameters are only informational. 329 The client SHOULD ignore pty requests. 331 4.3. X11 Forwarding 333 4.3.1. Requesting X11 Forwarding 335 X11 forwarding may be requested for a session by sending 337 byte SSH_MSG_CHANNEL_REQUEST 338 uint32 recipient channel 339 string "x11-req" 340 boolean want reply 341 boolean single connection 342 string x11 authentication protocol 343 string x11 authentication cookie 344 uint32 x11 screen number 346 It is recommended that the authentication cookie that is sent be a fake, 347 random cookie, and that the cookie is checked and replaced by the real 348 cookie when a connection request is received. 350 X11 connection forwarding should stop when the session channel is 351 closed; however, already opened forwardings should not be automatically 352 closed when the session channel is closed. 354 If `single connection' is TRUE, only a single connection should be 355 forwarded. No more connections will be forwarded after the first, or 356 after the session channel has been closed. 358 `X11 authentication protocol is the name of the X11 authentication 359 method used, i.e. "MIT-MAGIC-COOKIE-1". 361 4.3.2. X11 Channels 363 X11 channels are opened with a channel open request. The resulting 364 channels are independent of the session, and closing the session channel 365 does not close the forwarded X11 channels. 367 byte SSH_MSG_CHANNEL_OPEN 368 string "x11" 369 uint32 sender channel 370 uint32 initial window size 371 uint32 maximum packet size 372 string originator address (e.g. "192.168.7.38") 373 uint32 originator port 375 The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or 376 SSH_MSG_CHANNEL_OPEN_FAILURE. 378 Implementations MUST reject any X11 channel open requests if they have 379 not requested X11 forwarding. 381 4.4. Authentication Agent Forwarding 383 It is RECOMMENDED that authentication agent forwarding is allowed even 384 when either or both parties do not support the SSH authentication agent 385 protocol [SSH-AGENT]. 387 4.4.1. Requesting Authentication Agent Forwarding 389 Authentication agent forwarding may be requested for a session by 390 sending 392 byte SSH_MSG_CHANNEL_REQUEST 393 uint32 recipient channel 394 string "auth-agent-req" 395 boolean want reply 397 The server responds with either SSH_MSG_CHANNEL_SUCCESS or 398 SSH_MSG_CHANNEL_FAILURE (if `want reply' is TRUE). The client MAY send 399 further messages without waiting for the response to this message. 401 4.4.2. Authentication Agent Channels 403 When an application requests a connection to the authentication agent, 404 the following message is sent to the originator of the session. 406 byte SSH_MSG_CHANNEL_OPEN 407 string "auth-agent" 408 uint32 sender channel 409 uint32 initial window size 410 uint32 maximum packet size 412 The recipient SHOULD respond with open confirmation or open failure. 414 Implementations MUST reject any agent channel open requests if they have 415 not requested agent forwarding. 417 4.5. SSH1 Authentication Agent Forwarding 419 Implementations MAY support ssh1 authentication agent forwarding in 420 order to provide compatibility with old ssh versions. 422 4.5.1. Requesting SSH1 Authentication Agent Forwarding 424 Authentication agent forwarding may be requested for a session by 425 sending 427 byte SSH_MSG_CHANNEL_REQUEST 428 uint32 recipient channel 429 string "auth-ssh1-agent-req" 430 boolean want reply 432 The server responds with either SSH_MSG_CHANNEL_SUCCESS or 433 SSH_MSG_CHANNEL_FAILURE (if `want reply' is TRUE). The client MAY send 434 further messages without waiting for the response to this message. 436 4.5.2. SSH1 Authentication Agent Channels 438 When an application requests a connection to the authentication agent, 439 the following message is sent to the originator of the session. 441 byte SSH_MSG_CHANNEL_OPEN 442 string "auth-ssh1-agent" 443 uint32 sender channel 444 uint32 initial window size 445 uint32 maximum packet size 447 The recipient SHOULD respond with open confirmation or open failure. 449 Implementations MUST reject any agent channel open requests if they have 450 not requested ssh1 agent forwarding. 452 4.6. Environment Variable Passing 454 Environment variables may be passed to the shell/command to be started 455 later. Typically, each machine will have a preconfigured set of 456 variables that it will allow. Since uncontrolled setting of environment 457 variables can be very dangerous, it is recommended that implementations 458 allow setting only variables whose names have been explicitly configured 459 to be allowed. 461 byte SSH_MSG_CHANNEL_REQUEST 462 uint32 recipient channel 463 string "env" 464 boolean want reply 465 string variable name 466 string variable value 468 4.7. Starting a Shell or a Command 470 Once the session has been set up, a program is started at the remote 471 end. Program can be a shell, an application program or a subsystem with 472 a host-independent name. Only one of these requests can succeed per 473 channel. 475 byte SSH_MSG_CHANNEL_REQUEST 476 uint32 recipient channel 477 string "shell" 478 boolean want reply 480 This message will request the user's default shell (typically defined in 481 /etc/passwd in UNIX systems) to be started at the other end. 483 byte SSH_MSG_CHANNEL_REQUEST 484 uint32 recipient channel 485 string "exec" 486 boolean want reply 487 string command 489 This message will request the server to start the execution of the given 490 command. The command string may contain a path. Normal precautions MUST 491 be taken to prevent the execution of unauthorized commands. 493 byte SSH_MSG_CHANNEL_REQUEST 494 uint32 recipient channel 495 string "subsystem" 496 boolean want reply 497 string subsystem name 499 This last form executes a predefined subsystem. It expected that these 500 will include a general file transfer mechanism, and possibly other 501 features. Implementations may also allow configuring more such 502 mechanisms. 504 The server SHOULD not halt the execution of the protocol stack when 505 starting a shell or a program. All input and output from these SHOULD be 506 redirected the the channel or to the encrypted tunnel. 508 It is RECOMMENDED to request and check the reply for these messages. The 509 client SHOULD ignore these messages. 511 4.8. Session Data Transfer 513 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 514 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The 515 extended data type SSH_EXTENDED_DATA_STDERR has been defined for stderr 516 data. 518 4.9. Window Dimension Change Message 520 When the window (terminal) size changes on the client side, it MAY send 521 a message to the other side to inform it of the new dimensions. 523 byte SSH_MSG_CHANNEL_REQUEST 524 uint32 recipient_channel 525 string "window-change" 526 boolean FALSE 527 uint32 terminal width, columns 528 uint32 terminal height, rows 529 uint32 terminal width, pixels 530 uint32 terminal height, pixels 532 No response SHOULD be sent to this message. 534 4.10. Local Flow Control 536 On many systems it is possible to determine if a pseudo-terminal is 537 using control-S control-Q flow control. When flow control is allowed, 538 it is often desirable to do the flow control at the client end to speed 539 up responses to user requests. This is facilitated by the following 540 notification. Initially, the server is responsible for flow control. 541 (Here, again, client means the side originating the session, and server 542 the other side.) 544 The message below is used by the server to inform the client when it can 545 or cannot perform flow control (control-S/control-Q processing). If 546 `client can do' is TRUE, the client is allowed to do flow control using 547 control-S and control-Q. The client MAY ignore this message. 549 byte SSH_MSG_CHANNEL_REQUEST 550 uint32 recipient channel 551 string "xon-xoff" 552 boolean FALSE 553 boolean client can do 555 No response is sent to this message. 557 4.11. Signals 559 A signal can be delivered to the remote process/service using the 560 following message. Some systems may not implement signals, in which 561 case they SHOULD ignore this message. 563 byte SSH_MSG_CHANNEL_REQUEST 564 uint32 recipient channel 565 string "signal" 566 boolean FALSE 567 uint32 signal number 569 4.12. Returning Exit Status 571 When the command running at the other end terminates, The following 572 message can be sent to return the exit status of the command. Returning 573 the status is RECOMMENDED. No acknowledgment is sent for this message. 574 The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE after this 575 message. 577 The client MAY ignore these messages. 579 byte SSH_MSG_CHANNEL_REQUEST 580 uint32 recipient_channel 581 string "exit-status" 582 boolean FALSE 583 uint32 exit_status 585 The remote command may also terminate violently due to a signal. Such a 586 condition can be indicated by the following message. A zero exit_status 587 usually means that the command terminated successfully. 589 byte SSH_MSG_CHANNEL_REQUEST 590 uint32 recipient channel 591 string "exit-signal" 592 boolean FALSE 593 uint32 signal number 594 boolean core dumped 595 string error message (ISO-10646 UTF-8 [RFC-2044]) 596 string language tag (as defined in [RFC-1766]) 598 The `error message' contains an additional explanation of the error 599 message. The message may consist of multiple lines. The client software 600 MAY display this message to the user. 602 5. TCP/IP Port Forwarding 604 5.1. Requesting Port Forwarding 606 A party need not explicitly request forwardings from its own end to the 607 other direction. However, it if wishes to have connections to a port on 608 the other side be forwarded to the local side, it must explicitly 609 request this. 611 byte SSH_MSG_GLOBAL_REQUEST 612 string "tcpip-forward" 613 boolean want reply 614 string address to bind (e.g. "0.0.0.0") 615 uint32 port number to bind 617 `Address to bind' and `port number to bind' specify the IP address and 618 port to which the socket to be listened is bound. The address should be 619 "0.0.0.0" if connections are allowed from anywhere. (Note that the 620 client can still filter connections based on information passed in the 621 open request.) 622 Implementations should only allow forwarding privileged ports if the 623 user has been authenticated as a privileged user. 625 Client implementations SHOULD reject these messages; they are normally 626 only sent by the client. 628 A port forwarding can be cancelled with the following message. Note 629 that channel open requests may be received until a reply to this message 630 is received. 632 byte SSH_MSG_GLOBAL_REQUEST 633 string "cancel-tcpip-forward" 634 boolean want reply 635 string address_to_bind (e.g. "127.0.0.1") 636 uint32 port number to bind 638 Client implementations SHOULD reject these messages; they are normally 639 only sent by the client. 641 5.2. TCP/IP Forwarding Channels 643 When a connection comes to a port for which remote forwarding has been 644 requested, a channel is opened to forward the port to the other side. 646 byte SSH_MSG_CHANNEL_OPEN 647 string "forwarded-tcpip" 648 uint32 sender channel 649 uint32 initial window size 650 uint32 maximum packet size 651 string address that was connected 652 uint32 port that was connected 653 string originator IP address 654 uint32 originator port 656 Implementations MUST reject these messages unless they have previously 657 requested a remote TCP/IP port forwarding with the given port number. 659 When a connection comes to a locally forwarded TCP/IP port, the 660 following packet is sent to the other side. Note that these messages 661 MAY be sent also for ports for which no forwarding has been explicitly 662 requested. The receiving side must decide whether to allow the 663 forwarding. 664 byte SSH_MSG_CHANNEL_OPEN 665 string "direct-tcpip" 666 uint32 sender channel 667 uint32 initial window size 668 uint32 maximum packet size 669 string host to connect 670 uint32 port to connect 671 string originator IP address 672 uint32 originator port 674 `Host to connect' and `port to connect' specify the TCP/IP host and port 675 where the recipient should connect the channel. `Host to connect' may 676 be either a domain name or a numeric IP address. 678 `Originator IP address' is the numeric IP address of the machine where 679 the connection request comes from, and `originator port' is the port on 680 the originator host from where the connection came from. 682 Forwarded TCP/IP channels are independent of any sessions, and closing a 683 session channel does not in any way imply that forwarded connections 684 should be closed. 686 Client implementations SHOULD reject direct TCP/IP open requests for 687 security reasons. 689 6. Encoding of Terminal Modes 691 Terminal modes (as passed in a pty request) are encoded into a byte 692 stream. It is intended that the coding be portable across different 693 environments. 695 The tty mode description is a stream of bytes. The stream consists of 696 opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). 697 Opcodes 1-159 have a single uint32 argument. Opcodes 160-255 are not yet 698 defined, and cause parsing to stop (they should only be used after any 699 other data). 701 The client SHOULD put in the stream any modes it knows about, and the 702 server MAY ignore any modes it does not know about. This allows some 703 degree of machine-independence, at least between systems that use a 704 POSIX-like tty interface. The protocol can support other systems as 705 well, but the client may need to fill reasonable values for a number of 706 parameters so the server pty gets set to a reasonable mode (the server 707 leaves all unspecified mode bits in their default values, and only some 708 combinations make sense). 710 The following opcodes have been defined. The naming of opcodes mostly 711 follows the POSIX terminal mode flags. 713 0 TTY_OP_END Indicates end of options. 714 1 VINTR Interrupt character; 255 if none. Similarly for the 715 other characters. Not all of these characters are 716 supported on all systems. 717 2 VQUIT The quit character (sends SIGQUIT signal on POSIX 718 systems). 719 3 VERASE Erase the character to left of the cursor. 720 4 VKILL Kill the current input line. 721 5 VEOF End-of-file character (sends EOF from the terminal). 722 6 VEOL End-of-line character in addition to carriage return 723 and/or linefeed. 724 7 VEOL2 Additional end-of-line character. 725 8 VSTART Continues paused output (normally control-Q). 726 9 VSTOP Pauses output (normally control-S). 727 10 VSUSP Suspends the current program. 729 11 VDSUSP Another suspend character. 730 12 VREPRINT Reprints the current input line. 731 13 VWERASE Erases a word left of cursor. 732 14 VLNEXT Enter the next character typed literally, even if it 733 is a special character 734 15 VFLUSH Character to flush output. 735 16 VSWTCH Switch to a different shell layer. 736 17 VSTATUS Prints system status line (load, command, pid etc). 737 18 VDISCARD Toggles the flushing of terminal output. 738 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if 739 this flag is FALSE set, and 1 if it is TRUE. 740 31 PARMRK Mark parity and framing errors. 741 32 INPCK Enable checking of parity errors. 742 33 ISTRIP Strip 8th bit off characters. 743 34 INLCR Map NL into CR on input. 744 35 IGNCR Ignore CR on input. 745 36 ICRNL Map CR to NL on input. 746 37 IUCLC Translate uppercase characters to lowercase. 747 38 IXON Enable output flow control. 748 39 IXANY Any char will restart after stop. 749 40 IXOFF Enable input flow control. 750 41 IMAXBEL Ring bell on input queue full. 751 50 ISIG Enable signals INTR, QUIT, [D]SUSP. 752 51 ICANON Canonicalize input lines. 753 52 XCASE Enable input and output of uppercase characters by 754 preceding their lowercase equivalents with `\'. 755 53 ECHO Enable echoing. 756 54 ECHOE Visually erase chars. 757 55 ECHOK Kill character discards current line. 758 56 ECHONL Echo NL even if ECHO is off. 759 57 NOFLSH Don't flush after interrupt. 760 58 TOSTOP Stop background jobs from output. 761 59 IEXTEN Enable extensions. 762 60 ECHOCTL Echo control characters as ^(Char). 763 61 ECHOKE Visual erase for line kill. 764 62 PENDIN Retype pending input. 765 70 OPOST Enable output processing. 766 71 OLCUC Convert lowercase to uppercase. 767 72 ONLCR Map NL to CR-NL. 768 73 OCRNL Translate carriage return to newline (output). 769 74 ONOCR Translate newline to carriage return-newline 770 (output). 771 75 ONLRET Newline performs a carriage return (output). 772 90 CS7 7 bit mode. 773 91 CS8 8 bit mode. 774 92 PARENB Parity enable. 775 93 PARODD Odd parity, else even. 777 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second. 778 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second. 780 7. Summary of Message Numbers 781 #define SSH_MSG_GLOBAL_REQUEST 80 782 #define SSH_MSG_REQUEST_SUCCESS 81 783 #define SSH_MSG_REQUEST_FAILURE 82 784 #define SSH_MSG_CHANNEL_OPEN 90 785 #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 786 #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 787 #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 788 #define SSH_MSG_CHANNEL_DATA 94 789 #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 790 #define SSH_MSG_CHANNEL_EOF 96 791 #define SSH_MSG_CHANNEL_CLOSE 97 792 #define SSH_MSG_CHANNEL_REQUEST 98 793 #define SSH_MSG_CHANNEL_SUCCESS 99 794 #define SSH_MSG_CHANNEL_FAILURE 100 796 8. Security Considerations 798 This protocol is assumed to run on top of a secure, authenticated 799 transport. User authentication and protection against network-level 800 attacks are assumed to be provided by the underlying protocols. 802 This protocol can, however, be used to execute commands on remote 803 machines. The protocol also permits the server to run commands on the 804 client. Implementations may wish to disallow this to prevent an 805 attacker from coming from the server machine to the client machine. 807 X11 forwarding provides major security improvements over normal cookie- 808 based X11 forwarding. The cookie never needs to be transmitted in the 809 clear, and traffic is encrypted and integrity-protected. No useful 810 authentication data will remain on the server machine after the 811 connection has been closed. On the other hand, in some situations a 812 forwarded X11 connection might be used to get access to the local X 813 server across security perimeters. 815 Port forwardings can potentially allow an intruder to cross security 816 perimeters such as firewalls. They do not offer anything fundamentally 817 new that a user couldn't do otherwise; however, they make opening 818 tunnels very easy. Implementations should allow policy control over 819 what can be forwarded. Administrators should be able to deny 820 forwardings where appropriate. 822 Since this protocol normally runs inside an encrypted tunnel, firewalls 823 will not be able to examine the traffic. 825 It is RECOMMENDED that implementations disable all of the potentially 826 dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP 827 forwarding) if the host key has changed. 829 9. References 831 [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages", 832 March 1995. 834 [RFC-1884] Hinden, R., and Deering, S., "IP Version 6 Addressing 835 Architecture", December 1995 837 [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and 838 ISO 10646", October 1996. 840 [SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol 841 Architecture", Internet Draft, draft-ietf-secsh-architecture-00.txt 843 [SSH-TRANS] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Transport 844 Layer Protocol", Internet Draft, draft-ietf-secsh-transport-02.txt 846 [SSH-USERAUTH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH 847 Authentication Protocol", Internet Draft, draft-ietf-secsh- 848 userauth-02.txt 850 10. Authors' Addresses 852 Tatu Ylonen 853 SSH Communications Security Ltd. 854 Tekniikantie 12 855 FIN-02150 ESPOO 856 Finland 857 E-mail: ylo@ssh.fi 859 Tero Kivinen 860 SSH Communications Security Ltd. 861 Tekniikantie 12 862 FIN-02150 ESPOO 863 Finland 864 E-mail: kivinen@ssh.fi 866 Markku-Juhani O. Saarinen 867 SSH Communications Security Ltd. 868 Tekniikantie 12 869 FIN-02150 ESPOO 870 Finland 871 E-mail: mjos@ssh.fi 873 Timo J. Rinne 874 SSH Communications Security Ltd. 875 Tekniikantie 12 876 FIN-02150 ESPOO 877 Finland 878 E-mail: tri@ssh.fi 880 Sami Lehtinen 881 SSH Communications Security Ltd. 882 Tekniikantie 12 883 FIN-02150 ESPOO 884 Finland 885 E-mail: sjl@ssh.fi