idnits 2.17.1 draft-ietf-secsh-connect-06.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 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 (22 June 1999) is 9074 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 855, but no explicit reference was found in the text == Unused Reference: 'SSH-TRANS' is defined on line 864, but no explicit reference was found in the text == Unused Reference: 'SSH-USERAUTH' is defined on line 867, 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-04 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-06 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-06 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-06.txt M. Saarinen 4 Expires in six months T. Rinne 5 S. Lehtinen 6 SSH 7 22 June 1999 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 the 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. 608 5. TCP/IP Port Forwarding 610 5.1. Requesting Port Forwarding 612 A party need not explicitly request forwardings from its own end to the 613 other direction. However, it if wishes to have connections to a port on 614 the other side be forwarded to the local side, it must explicitly 615 request this. 617 byte SSH_MSG_GLOBAL_REQUEST 618 string "tcpip-forward" 619 boolean want reply 620 string address to bind (e.g. "0.0.0.0") 621 uint32 port number to bind 623 `Address to bind' and `port number to bind' specify the IP address and 624 port to which the socket to be listened is bound. The address should be 625 "0.0.0.0" if connections are allowed from anywhere. (Note that the 626 client can still filter connections based on information passed in the 627 open request.) 629 Implementations should only allow forwarding privileged ports if the 630 user has been authenticated as a privileged user. 632 Client implementations SHOULD reject these messages; they are normally 633 only sent by the client. 635 A port forwarding can be cancelled with the following message. Note 636 that channel open requests may be received until a reply to this message 637 is received. 639 byte SSH_MSG_GLOBAL_REQUEST 640 string "cancel-tcpip-forward" 641 boolean want reply 642 string address_to_bind (e.g. "127.0.0.1") 643 uint32 port number to bind 645 Client implementations SHOULD reject these messages; they are normally 646 only sent by the client. 648 5.2. TCP/IP Forwarding Channels 650 When a connection comes to a port for which remote forwarding has been 651 requested, a channel is opened to forward the port to the other side. 653 byte SSH_MSG_CHANNEL_OPEN 654 string "forwarded-tcpip" 655 uint32 sender channel 656 uint32 initial window size 657 uint32 maximum packet size 658 string address that was connected 659 uint32 port that was connected 660 string originator IP address 661 uint32 originator port 663 Implementations MUST reject these messages unless they have previously 664 requested a remote TCP/IP port forwarding with the given port number. 666 When a connection comes to a locally forwarded TCP/IP port, the 667 following packet is sent to the other side. Note that these messages 668 MAY be sent also for ports for which no forwarding has been explicitly 669 requested. The receiving side must decide whether to allow the 670 forwarding. 671 byte SSH_MSG_CHANNEL_OPEN 672 string "direct-tcpip" 673 uint32 sender channel 674 uint32 initial window size 675 uint32 maximum packet size 676 string host to connect 677 uint32 port to connect 678 string originator IP address 679 uint32 originator port 681 `Host to connect' and `port to connect' specify the TCP/IP host and port 682 where the recipient should connect the channel. `Host to connect' may 683 be either a domain name or a numeric IP address. 685 `Originator IP address' is the numeric IP address of the machine where 686 the connection request comes from, and `originator port' is the port on 687 the originator host from where the connection came from. 689 Forwarded TCP/IP channels are independent of any sessions, and closing a 690 session channel does not in any way imply that forwarded connections 691 should be closed. 693 Client implementations SHOULD reject direct TCP/IP open requests for 694 security reasons. 696 6. Encoding of Terminal Modes 698 Terminal modes (as passed in a pty request) are encoded into a byte 699 stream. It is intended that the coding be portable across different 700 environments. 702 The tty mode description is a stream of bytes. The stream consists of 703 opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). 704 Opcodes 1-159 have a single uint32 argument. Opcodes 160-255 are not yet 705 defined, and cause parsing to stop (they should only be used after any 706 other data). 708 The client SHOULD put in the stream any modes it knows about, and the 709 server MAY ignore any modes it does not know about. This allows some 710 degree of machine-independence, at least between systems that use a 711 POSIX-like tty interface. The protocol can support other systems as 712 well, but the client may need to fill reasonable values for a number of 713 parameters so the server pty gets set to a reasonable mode (the server 714 leaves all unspecified mode bits in their default values, and only some 715 combinations make sense). 717 The following opcodes have been defined. The naming of opcodes mostly 718 follows the POSIX terminal mode flags. 720 0 TTY_OP_END Indicates end of options. 721 1 VINTR Interrupt character; 255 if none. Similarly for the 722 other characters. Not all of these characters are 723 supported on all systems. 724 2 VQUIT The quit character (sends SIGQUIT signal on POSIX 725 systems). 726 3 VERASE Erase the character to left of the cursor. 727 4 VKILL Kill the current input line. 728 5 VEOF End-of-file character (sends EOF from the terminal). 730 6 VEOL End-of-line character in addition to carriage return 731 and/or linefeed. 732 7 VEOL2 Additional end-of-line character. 733 8 VSTART Continues paused output (normally control-Q). 734 9 VSTOP Pauses output (normally control-S). 735 10 VSUSP Suspends the current program. 736 11 VDSUSP Another suspend character. 737 12 VREPRINT Reprints the current input line. 738 13 VWERASE Erases a word left of cursor. 739 14 VLNEXT Enter the next character typed literally, even if it 740 is a special character 741 15 VFLUSH Character to flush output. 742 16 VSWTCH Switch to a different shell layer. 743 17 VSTATUS Prints system status line (load, command, pid etc). 744 18 VDISCARD Toggles the flushing of terminal output. 745 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if 746 this flag is FALSE set, and 1 if it is TRUE. 747 31 PARMRK Mark parity and framing errors. 748 32 INPCK Enable checking of parity errors. 749 33 ISTRIP Strip 8th bit off characters. 750 34 INLCR Map NL into CR on input. 751 35 IGNCR Ignore CR on input. 752 36 ICRNL Map CR to NL on input. 753 37 IUCLC Translate uppercase characters to lowercase. 754 38 IXON Enable output flow control. 755 39 IXANY Any char will restart after stop. 756 40 IXOFF Enable input flow control. 757 41 IMAXBEL Ring bell on input queue full. 758 50 ISIG Enable signals INTR, QUIT, [D]SUSP. 759 51 ICANON Canonicalize input lines. 760 52 XCASE Enable input and output of uppercase characters by 761 preceding their lowercase equivalents with `\'. 762 53 ECHO Enable echoing. 763 54 ECHOE Visually erase chars. 764 55 ECHOK Kill character discards current line. 765 56 ECHONL Echo NL even if ECHO is off. 766 57 NOFLSH Don't flush after interrupt. 767 58 TOSTOP Stop background jobs from output. 768 59 IEXTEN Enable extensions. 769 60 ECHOCTL Echo control characters as ^(Char). 770 61 ECHOKE Visual erase for line kill. 771 62 PENDIN Retype pending input. 772 70 OPOST Enable output processing. 773 71 OLCUC Convert lowercase to uppercase. 774 72 ONLCR Map NL to CR-NL. 775 73 OCRNL Translate carriage return to newline (output). 776 74 ONOCR Translate newline to carriage return-newline 777 (output). 778 75 ONLRET Newline performs a carriage return (output). 779 90 CS7 7 bit mode. 780 91 CS8 8 bit mode. 781 92 PARENB Parity enable. 782 93 PARODD Odd parity, else even. 784 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second. 785 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second. 787 7. Summary of Message Numbers 789 #define SSH_MSG_GLOBAL_REQUEST 80 790 #define SSH_MSG_REQUEST_SUCCESS 81 791 #define SSH_MSG_REQUEST_FAILURE 82 792 #define SSH_MSG_CHANNEL_OPEN 90 793 #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 794 #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 795 #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 796 #define SSH_MSG_CHANNEL_DATA 94 797 #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 798 #define SSH_MSG_CHANNEL_EOF 96 799 #define SSH_MSG_CHANNEL_CLOSE 97 800 #define SSH_MSG_CHANNEL_REQUEST 98 801 #define SSH_MSG_CHANNEL_SUCCESS 99 802 #define SSH_MSG_CHANNEL_FAILURE 100 804 8. Security Considerations 806 This protocol is assumed to run on top of a secure, authenticated 807 transport. User authentication and protection against network-level 808 attacks are assumed to be provided by the underlying protocols. 810 This protocol can, however, be used to execute commands on remote 811 machines. The protocol also permits the server to run commands on the 812 client. Implementations may wish to disallow this to prevent an 813 attacker from coming from the server machine to the client machine. 815 X11 forwarding provides major security improvements over normal cookie- 816 based X11 forwarding. The cookie never needs to be transmitted in the 817 clear, and traffic is encrypted and integrity-protected. No useful 818 authentication data will remain on the server machine after the 819 connection has been closed. On the other hand, in some situations a 820 forwarded X11 connection might be used to get access to the local X 821 server across security perimeters. 823 Port forwardings can potentially allow an intruder to cross security 824 perimeters such as firewalls. They do not offer anything fundamentally 825 new that a user couldn't do otherwise; however, they make opening 826 tunnels very easy. Implementations should allow policy control over 827 what can be forwarded. Administrators should be able to deny 828 forwardings where appropriate. 830 Since this protocol normally runs inside an encrypted tunnel, firewalls 831 will not be able to examine the traffic. 833 It is RECOMMENDED that implementations disable all of the potentially 834 dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP 835 forwarding) if the host key has changed. 837 9. Trademark Issues 839 SSH is a registered trademark and Secure Shell is a trademark of SSH 840 Communications Security Ltd. SSH Communications Security Ltd permits 841 the use of these trademarks as the name of this standard and protocol, 842 and permits their use to describe that a product conforms to this 843 standard, provided that the following acknowledgement is included 844 where the trademarks are used: ``SSH is a registered trademark and 845 Secure Shell is a trademark of SSH Communications Security Ltd 846 (www.ssh.fi)''. These trademarks may not be used as part of a product 847 name or in otherwise confusing manner without prior written permission 848 of SSH Communications Security Ltd. 850 10. References 852 [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages", 853 March 1995. 855 [RFC-1884] Hinden, R., and Deering, S., "IP Version 6 Addressing 856 Architecture", December 1995 858 [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and 859 ISO 10646", October 1996. 861 [SSH-ARCH] Ylonen, T., et al, "SSH Protocol Architecture", Internet 862 Draft, draft-ietf-secsh-architecture-04.txt 864 [SSH-TRANS] Ylonen, T., et al, "SSH Transport Layer Protocol", Internet 865 Draft, draft-ietf-secsh-transport-06.txt 867 [SSH-USERAUTH] Ylonen, T., et al, "SSH Authentication Protocol", 868 Internet Draft, draft-ietf-secsh-userauth-06.txt 870 11. Authors' Addresses 872 Tatu Ylonen 873 SSH Communications Security Ltd. 874 Tekniikantie 12 875 FIN-02150 ESPOO 876 Finland 877 E-mail: ylo@ssh.fi 879 Tero Kivinen 880 SSH Communications Security Ltd. 881 Tekniikantie 12 882 FIN-02150 ESPOO 883 Finland 884 E-mail: kivinen@ssh.fi 886 Markku-Juhani O. Saarinen 887 SSH Communications Security Ltd. 888 Tekniikantie 12 889 FIN-02150 ESPOO 890 Finland 891 E-mail: mjos@ssh.fi 893 Timo J. Rinne 894 SSH Communications Security Ltd. 895 Tekniikantie 12 896 FIN-02150 ESPOO 897 Finland 898 E-mail: tri@ssh.fi 900 Sami Lehtinen 901 SSH Communications Security Ltd. 902 Tekniikantie 12 903 FIN-02150 ESPOO 904 Finland 905 E-mail: sjl@ssh.fi