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