idnits 2.17.1 draft-ietf-secsh-connect-20.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1.a on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1000. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 972. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 979. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 985. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 142 has weird spacing: '... string req...' == Line 143 has weird spacing: '...boolean want...' == Line 195 has weird spacing: '... string cha...' == Line 230 has weird spacing: '... string des...' == Line 231 has weird spacing: '... string lan...' == (34 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (October 24, 2004) is 7118 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC1884' is defined on line 933, but no explicit reference was found in the text -- No information found for draft-ietf-architecture - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SSH-ARCH' -- No information found for draft-ietf-transport - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SSH-TRANS' -- No information found for draft-ietf-userauth - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SSH-USERAUTH' -- No information found for draft-ietf-assignednumbers - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SSH-NUMBERS' -- Obsolete informational reference (is this intentional?): RFC 1884 (Obsoleted by RFC 2373) -- Obsolete informational reference (is this intentional?): RFC 2434 (Obsoleted by RFC 5226) -- Obsolete informational reference (is this intentional?): RFC 3066 (Obsoleted by RFC 4646, RFC 4647) Summary: 5 errors (**), 0 flaws (~~), 10 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Lonvick, Ed. 3 Internet-Draft Cisco Systems, Inc 4 Expires: April 24, 2005 October 24, 2004 6 SSH Connection Protocol 7 draft-ietf-secsh-connect-20.txt 9 Status of this Memo 11 This document is an Internet-Draft and is subject to all provisions 12 of section 3 of RFC 3667. By submitting this Internet-Draft, each 13 author represents that any applicable patent or other IPR claims of 14 which he or she is aware have been or will be disclosed, and any of 15 which he or she become aware will be disclosed, in accordance with 16 RFC 3668. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as 21 Internet-Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on April 24, 2005. 36 Copyright Notice 38 Copyright (C) The Internet Society (2004). 40 Abstract 42 SSH is a protocol for secure remote login and other secure network 43 services over an insecure network. 45 This document describes the SSH Connection Protocol. It provides 46 interactive login sessions, remote execution of commands, forwarded 47 TCP/IP connections, and forwarded X11 connections. All of these 48 channels are multiplexed into a single encrypted tunnel. 50 The SSH Connection Protocol has been designed to run on top of the 51 SSH transport layer and user authentication protocols. 53 Table of Contents 55 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. Conventions Used in This Document . . . . . . . . . . . . . . 3 58 4. Global Requests . . . . . . . . . . . . . . . . . . . . . . . 3 59 5. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . 4 60 5.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . 5 61 5.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . 6 62 5.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . 7 63 5.4 Channel-Specific Requests . . . . . . . . . . . . . . . . 8 64 6. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . 8 65 6.1 Opening a Session . . . . . . . . . . . . . . . . . . . . 9 66 6.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . 9 67 6.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . 9 68 6.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . 9 69 6.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . 10 70 6.4 Environment Variable Passing . . . . . . . . . . . . . . . 11 71 6.5 Starting a Shell or a Command . . . . . . . . . . . . . . 11 72 6.6 Session Data Transfer . . . . . . . . . . . . . . . . . . 12 73 6.7 Window Dimension Change Message . . . . . . . . . . . . . 12 74 6.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . 13 75 6.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . 13 76 6.10 Returning Exit Status . . . . . . . . . . . . . . . . . . 13 77 7. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . 15 78 7.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . 15 79 7.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . 16 80 8. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . 17 81 9. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 19 82 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 19 83 11. Security Considerations . . . . . . . . . . . . . . . . . . 19 84 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 85 12.1 Normative References . . . . . . . . . . . . . . . . . . . . 20 86 12.2 Informative References . . . . . . . . . . . . . . . . . . . 20 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 21 88 Intellectual Property and Copyright Statements . . . . . . . . 22 90 1. Contributors 92 The major original contributors of this document were: Tatu Ylonen, 93 Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH 94 Communications Security Corp), and Markku-Juhani O. Saarinen 95 (University of Jyvaskyla). Darren Moffit was the original editor of 96 this document and also made very substantial contributions. 98 Additional contributors to this document include [need list]. 99 Listing their names here does not mean that they endorse this 100 document, but that they have contributed to it. 102 Comments on this internet draft should be sent to the IETF SECSH 103 working group, details at: 104 http://ietf.org/html.charters/secsh-charter.html Note: This paragraph 105 will be removed before this document progresses to become an RFC. 107 2. Introduction 109 The SSH Connection Protocol has been designed to run on top of the 110 SSH transport layer and user authentication protocols. It provides 111 interactive login sessions, remote execution of commands, forwarded 112 TCP/IP connections, and forwarded X11 connections. The service name 113 for this protocol is "ssh-connection". 115 This document should be read only after reading the SSH architecture 116 document [SSH-ARCH]. This document freely uses terminology and 117 notation from the architecture document without reference or further 118 explanation. 120 3. Conventions Used in This Document 122 All documents related to the SSH protocols shall use the keywords 123 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 124 "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe 125 requirements. These keywords are to be interpreted as described in 126 [RFC2119]. 128 The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME 129 FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG 130 APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in 131 this document when used to describe namespace allocation are to be 132 interpreted as described in [RFC2434]. 134 4. Global Requests 136 There are several kinds of requests that affect the state of the 137 remote end globally, independent of any channels. An example is a 138 request to start TCP/IP forwarding for a specific port. All such 139 requests use the following format. 141 byte SSH_MSG_GLOBAL_REQUEST 142 string request name in US-ASCII only 143 boolean want reply 144 ... request-specific data follows 146 The value of 'request name' follows the DNS extensibility naming 147 convention outlined in [SSH-ARCH]. 149 The recipient will respond to this message with 150 SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if 'want reply' is 151 TRUE. 153 byte SSH_MSG_REQUEST_SUCCESS 154 ..... response specific data 156 Usually the 'response specific data' is non-existent. 158 If the recipient does not recognize or support the request, it simply 159 responds with SSH_MSG_REQUEST_FAILURE. 161 byte SSH_MSG_REQUEST_FAILURE 163 In general, the reply messages do not include request type 164 identifiers. To make it possible for the originator of a request to 165 identify to which request each reply refers, it is REQUIRED that 166 replies to SSH_MSG_GLOBAL_REQUESTS MUST be sent in the same order as 167 the corresponding request messages. For channel requests, replies 168 that relate to the same channel MUST also be replied to in the right 169 order. However, channel requests for distinct channels MAY be 170 replied to out-of-order. 172 5. Channel Mechanism 174 All terminal sessions, forwarded connections, etc., are channels. 175 Either side may open a channel. Multiple channels are multiplexed 176 into a single connection. 178 Channels are identified by numbers at each end. The number referring 179 to a channel may be different on each side. Requests to open a 180 channel contain the sender's channel number. Any other 181 channel-related messages contain the recipient's channel number for 182 the channel. 184 Channels are flow-controlled. No data may be sent to a channel until 185 a message is received to indicate that window space is available. 187 5.1 Opening a Channel 189 When either side wishes to open a new channel, it allocates a local 190 number for the channel. It then sends the following message to the 191 other side, and includes the local channel number and initial window 192 size in the message. 194 byte SSH_MSG_CHANNEL_OPEN 195 string channel type in US-ASCII only 196 uint32 sender channel 197 uint32 initial window size 198 uint32 maximum packet size 199 ... channel type specific data follows 201 The 'channel type' is a name as described in [SSH-ARCH] and 202 [SSH-NUMBERS], with similar extension mechanisms. The 'sender 203 channel' is a local identifier for the channel used by the sender of 204 this message. The 'initial window size' specifies how many bytes of 205 channel data can be sent to the sender of this message without 206 adjusting the window. The 'maximum packet size' specifies the 207 maximum size of an individual data packet that can be sent to the 208 sender. For example, one might want to use smaller packets for 209 interactive connections to get better interactive response on slow 210 links. 212 The remote side then decides whether it can open the channel, and 213 responds with either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or 214 SSH_MSG_CHANNEL_OPEN_FAILURE. 216 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 217 uint32 recipient channel 218 uint32 sender channel 219 uint32 initial window size 220 uint32 maximum packet size 221 ... 'channel type' specific data follows 223 The 'recipient channel' is the channel number given in the original 224 open request, and 'sender channel' is the channel number allocated by 225 the other side. 227 byte SSH_MSG_CHANNEL_OPEN_FAILURE 228 uint32 recipient channel 229 uint32 reason code 230 string description in ISO-10646 UTF-8 encoding [RFC3629] 231 string language tag as defined in [RFC3066] 233 If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support 234 the specified 'channel type', it simply responds with 235 SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the 'description' 236 string to the user. If this is done, the client software should take 237 the precautions discussed in [SSH-ARCH]. 239 The following 'reason code' values are defined: 241 description reason code 242 ----------- ----------- 243 SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 244 SSH_OPEN_CONNECT_FAILED 2 245 SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 246 SSH_OPEN_RESOURCE_SHORTAGE 4 248 Requests for assignments of new SSH_MSG_CHANNEL_OPEN 'reason code' 249 values (and associated 'description' text) in the range of 0x00000001 250 to 0xFDFFFFFF MUST be done through the IETF CONSENSUS method as 251 described in [RFC2434]. The SSH_MSG_CHANNEL_OPEN 'reason code' 252 values in the range of 0xFE000000 to 0xFEFFFFFF are reserved for 253 PRIVATE USE. The SSH_MSG_CHANNEL_OPEN 'reason code' values in the 254 range of 0xFF000000 to 0xFFFFFFFF are also reserved for PRIVATE USE 255 as described in [RFC2434]. As is noted, the actual instructions to 256 the IANA is in [SSH-NUMBERS]. 258 5.2 Data Transfer 260 The window size specifies how many bytes the other party can send 261 before it must wait for the window to be adjusted. Both parties use 262 the following message to adjust the window. 264 byte SSH_MSG_CHANNEL_WINDOW_ADJUST 265 uint32 recipient channel 266 uint32 bytes to add 268 After receiving this message, the recipient MAY send the given number 269 of bytes more than it was previously allowed to send; the window size 270 is incremented. 272 Data transfer is done with messages of the following type. 274 byte SSH_MSG_CHANNEL_DATA 275 uint32 recipient channel 276 string data 278 The maximum amount of data allowed is the current window size. The 279 window size is decremented by the amount of data sent. Both parties 280 MAY ignore all extra data sent after the allowed window is empty. 282 Additionally, some channels can transfer several types of data. An 283 example of this is stderr data from interactive sessions. Such data 284 can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a 285 separate integer specifies the type of the data. The available types 286 and their interpretation depend on the type of the channel. 288 byte SSH_MSG_CHANNEL_EXTENDED_DATA 289 uint32 recipient_channel 290 uint32 data_type_code 291 string data 293 Data sent with these messages consumes the same window as ordinary 294 data. 296 Currently, only the following type is defined. 298 data data_type_code 299 ---- -------------- 300 SSH_EXTENDED_DATA_STDERR 1 302 5.3 Closing a Channel 304 When a party will no longer send more data to a channel, it SHOULD 305 send SSH_MSG_CHANNEL_EOF. 307 byte SSH_MSG_CHANNEL_EOF 308 uint32 recipient_channel 310 No explicit response is sent to this message. However, the 311 application may send EOF to whatever is at the other end of the 312 channel. Note that the channel remains open after this message, and 313 more data may still be sent in the other direction. This message 314 does not consume window space and can be sent even if no window space 315 is available. 317 When either party wishes to terminate the channel, it sends 318 SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST 319 send back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this 320 message for the channel. The channel is considered closed for a 321 party when it has both sent and received SSH_MSG_CHANNEL_CLOSE, and 322 the party may then reuse the channel number. A party MAY send 323 SSH_MSG_CHANNEL_CLOSE without having sent or received 324 SSH_MSG_CHANNEL_EOF. 326 byte SSH_MSG_CHANNEL_CLOSE 327 uint32 recipient_channel 329 This message does not consume window space and can be sent even if no 330 window space is available. 332 It is recommended that any data sent before this message is delivered 333 to the actual destination, if possible. 335 5.4 Channel-Specific Requests 337 Many 'channel type' values have extensions that are specific to that 338 particular 'channel type'. An example is requesting a pty (pseudo 339 terminal) for an interactive session. 341 All channel-specific requests use the following format. 343 byte SSH_MSG_CHANNEL_REQUEST 344 uint32 recipient channel 345 string request type in US-ASCII characters only 346 boolean want reply 347 ... type-specific data 349 If 'want reply' is FALSE, no response will be sent to the request. 350 Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS 351 or SSH_MSG_CHANNEL_FAILURE, or request-specific continuation 352 messages. If the request is not recognized or is not supported for 353 the channel, SSH_MSG_CHANNEL_FAILURE is returned. 355 This message does not consume window space and can be sent even if no 356 window space is available. The values of 'request type' are local to 357 each channel type. 359 The client is allowed to send further messages without waiting for 360 the response to the request. 362 'request type' names follow the DNS extensibility naming convention 363 outlined in [SSH-ARCH] and [SSH-NUMBERS]. 365 byte SSH_MSG_CHANNEL_SUCCESS 366 uint32 recipient_channel 368 byte SSH_MSG_CHANNEL_FAILURE 369 uint32 recipient_channel 371 These messages do not consume window space and can be sent even if no 372 window space is available. 374 6. Interactive Sessions 376 A session is a remote execution of a program. The program may be a 377 shell, an application, a system command, or some built-in subsystem. 378 It may or may not have a tty, and may or may not involve X11 379 forwarding. Multiple sessions can be active simultaneously. 381 6.1 Opening a Session 383 A session is started by sending the following message. 385 byte SSH_MSG_CHANNEL_OPEN 386 string "session" 387 uint32 sender channel 388 uint32 initial window size 389 uint32 maximum packet size 391 Client implementations SHOULD reject any session channel open 392 requests to make it more difficult for a corrupt server to attack the 393 client. 395 6.2 Requesting a Pseudo-Terminal 397 A pseudo-terminal can be allocated for the session by sending the 398 following message. 400 byte SSH_MSG_CHANNEL_REQUEST 401 uint32 recipient_channel 402 string "pty-req" 403 boolean want_reply 404 string TERM environment variable value (e.g., vt100) 405 uint32 terminal width, characters (e.g., 80) 406 uint32 terminal height, rows (e.g., 24) 407 uint32 terminal width, pixels (e.g., 640) 408 uint32 terminal height, pixels (e.g., 480) 409 string encoded terminal modes 411 The 'encoded terminal modes' are described in Section 8. Zero 412 dimension parameters MUST be ignored. The character/row dimensions 413 override the pixel dimensions (when nonzero). Pixel dimensions refer 414 to the drawable area of the window. 416 The dimension parameters are only informational. 418 The client SHOULD ignore pty requests. 420 6.3 X11 Forwarding 422 6.3.1 Requesting X11 Forwarding 424 X11 forwarding may be requested for a session by sending a 425 SSH_MSG_CHANNEL_REQUEST message. 427 byte SSH_MSG_CHANNEL_REQUEST 428 uint32 recipient channel 429 string "x11-req" 430 boolean want reply 431 boolean single connection 432 string x11 authentication protocol 433 string x11 authentication cookie 434 uint32 x11 screen number 436 It is RECOMMENDED that the 'x11 authentication cookie' that is sent 437 be a fake, random cookie, and that the cookie is checked and replaced 438 by the real cookie when a connection request is received. 440 X11 connection forwarding should stop when the session channel is 441 closed. However, already opened forwardings should not be 442 automatically closed when the session channel is closed. 444 If 'single connection' is TRUE, only a single connection should be 445 forwarded. No more connections will be forwarded after the first, or 446 after the session channel has been closed. 448 The 'x11 authentication protocol' is the name of the X11 449 authentication method used, e.g. "MIT-MAGIC-COOKIE-1". 451 The 'x11 authentication cookie' MUST be hexadecimal encoded. 453 The X Protocol is documented in [SCHEIFLER]. 455 6.3.2 X11 Channels 457 X11 channels are opened with a channel open request. The resulting 458 channels are independent of the session, and closing the session 459 channel does not close the forwarded X11 channels. 461 byte SSH_MSG_CHANNEL_OPEN 462 string "x11" 463 uint32 sender channel 464 uint32 initial window size 465 uint32 maximum packet size 466 string originator address (e.g. "192.168.7.38") 467 uint32 originator port 469 The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION 470 or SSH_MSG_CHANNEL_OPEN_FAILURE. 472 Implementations MUST reject any X11 channel open requests if they 473 have not requested X11 forwarding. 475 6.4 Environment Variable Passing 477 Environment variables may be passed to the shell/command to be 478 started later. Uncontrolled setting of environment variables in a 479 privileged process can be a security hazard. It is recommended that 480 implementations either maintain a list of allowable variable names or 481 only set environment variables after the server process has dropped 482 sufficient privileges. 484 byte SSH_MSG_CHANNEL_REQUEST 485 uint32 recipient channel 486 string "env" 487 boolean want reply 488 string variable name 489 string variable value 491 6.5 Starting a Shell or a Command 493 Once the session has been set up, a program is started at the remote 494 end. The program can be a shell, an application program or a 495 subsystem with a host-independent name. Only one of these requests 496 can succeed per channel. 498 byte SSH_MSG_CHANNEL_REQUEST 499 uint32 recipient channel 500 string "shell" 501 boolean want reply 503 This message will request the user's default shell (typically defined 504 in /etc/passwd in UNIX systems) to be started at the other end. 506 byte SSH_MSG_CHANNEL_REQUEST 507 uint32 recipient channel 508 string "exec" 509 boolean want reply 510 string command 512 This message will request the server to start the execution of the 513 given command. The 'command' string may contain a path. Normal 514 precautions MUST be taken to prevent the execution of unauthorized 515 commands. 517 byte SSH_MSG_CHANNEL_REQUEST 518 uint32 recipient channel 519 string "subsystem" 520 boolean want reply 521 string subsystem name 523 This last form executes a predefined subsystem. It is expected that 524 these will include a general file transfer mechanism, and possibly 525 other features. Implementations may also allow configuring more such 526 mechanisms. As the user's shell is usually used to execute the 527 subsystem, it is advisable for the subsystem protocol to have a 528 "magic cookie" at the beginning of the protocol transaction to 529 distinguish it from arbitrary output generated by shell 530 initialization scripts, etc. This spurious output from the shell may 531 be filtered out either at the server or at the client. 533 The server SHOULD NOT halt the execution of the protocol stack when 534 starting a shell or a program. All input and output from these 535 SHOULD be redirected to the channel or to the encrypted tunnel. 537 It is RECOMMENDED to request and check the reply for these messages. 538 The client SHOULD ignore these messages. 540 Subsystem names follow the DNS extensibility naming convention 541 outlined in [SSH-NUMBERS]. 543 6.6 Session Data Transfer 545 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 546 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The 547 extended data type SSH_EXTENDED_DATA_STDERR has been defined for 548 stderr data. 550 6.7 Window Dimension Change Message 552 When the window (terminal) size changes on the client side, it MAY 553 send a message to the other side to inform it of the new dimensions. 555 byte SSH_MSG_CHANNEL_REQUEST 556 uint32 recipient_channel 557 string "window-change" 558 boolean FALSE 559 uint32 terminal width, columns 560 uint32 terminal height, rows 561 uint32 terminal width, pixels 562 uint32 terminal height, pixels 564 A response SHOULD NOT be sent to this message. 566 6.8 Local Flow Control 568 On many systems, it is possible to determine if a pseudo-terminal is 569 using control-S/control-Q flow control. When flow control is 570 allowed, it is often desirable to do the flow control at the client 571 end to speed up responses to user requests. This is facilitated by 572 the following notification. Initially, the server is responsible for 573 flow control. (Here, again, client means the side originating the 574 session, and server means the other side.) 576 The message below is used by the server to inform the client when it 577 can or cannot perform flow control (control-S/control-Q processing). 578 If 'client can do' is TRUE, the client is allowed to do flow control 579 using control-S and control-Q. The client MAY ignore this message. 581 byte SSH_MSG_CHANNEL_REQUEST 582 uint32 recipient channel 583 string "xon-xoff" 584 boolean FALSE 585 boolean client can do 587 No response is sent to this message. 589 6.9 Signals 591 A signal can be delivered to the remote process/service using the 592 following message. Some systems may not implement signals, in which 593 case they SHOULD ignore this message. 595 byte SSH_MSG_CHANNEL_REQUEST 596 uint32 recipient channel 597 string "signal" 598 boolean FALSE 599 string signal name without the "SIG" prefix. 601 Signal names will be encoded as discussed in the "exit-signal" 602 SSH_MSG_CHANNEL_REQUEST. 604 6.10 Returning Exit Status 606 When the command running at the other end terminates, the following 607 message can be sent to return the exit status of the command. 608 Returning the status is RECOMMENDED. No acknowledgment is sent for 609 this message. The channel needs to be closed with 610 SSH_MSG_CHANNEL_CLOSE after this message. 612 The client MAY ignore these messages. 614 byte SSH_MSG_CHANNEL_REQUEST 615 uint32 recipient_channel 616 string "exit-status" 617 boolean FALSE 618 uint32 exit_status 620 The remote command may also terminate violently due to a signal. 621 Such a condition can be indicated by the following message. A zero 622 'exit_status' usually means that the command terminated successfully. 623 byte SSH_MSG_CHANNEL_REQUEST 624 uint32 recipient channel 625 string "exit-signal" 626 boolean FALSE 627 string signal name without the "SIG" prefix. 628 boolean core dumped 629 string error message in ISO-10646 UTF-8 encoding 630 string language tag as defined in [RFC3066] 632 The 'signal name' is one of the following (these are from [POSIX]) 634 ABRT 635 ALRM 636 FPE 637 HUP 638 ILL 639 INT 640 KILL 641 PIPE 642 QUIT 643 SEGV 644 TERM 645 USR1 646 USR2 648 Additional 'signal name' values MAY be sent in the format 649 "sig-name@xyz", where "sig-name" and "xyz" may be anything a 650 particular implementor wants (except the "@" sign). However, it is 651 suggested that if a 'configure' script is used, any non-standard 652 'signal name' values it finds be encoded as "SIG@xyz.config.guess", 653 where "SIG" is the 'signal name' without the "SIG" prefix, and "xyz" 654 be the host type, as determined by "config.guess". 656 The 'error message' contains an additional textual explanation of the 657 error message. The message may consist of multiple lines. The 658 client software MAY display this message to the user. If this is 659 done, the client software should take the precautions discussed in 660 [SSH-ARCH]. 662 7. TCP/IP Port Forwarding 664 7.1 Requesting Port Forwarding 666 A party need not explicitly request forwardings from its own end to 667 the other direction. However, if it wishes that connections to a 668 port on the other side be forwarded to the local side, it must 669 explicitly request this. 671 byte SSH_MSG_GLOBAL_REQUEST 672 string "tcpip-forward" 673 boolean want reply 674 string address to bind (e.g. "0.0.0.0") 675 uint32 port number to bind 677 The 'address to bind' and 'port number to bind' specify the IP 678 address and port to which the socket to be listened is bound. The 679 address should be "0.0.0.0" if connections are allowed from anywhere. 680 (Note that the client can still filter connections based on 681 information passed in the open request.) 683 Implementations should only allow forwarding privileged ports if the 684 user has been authenticated as a privileged user. 686 Client implementations SHOULD reject these messages; they are 687 normally only sent by the client. 689 If a client passes 0 as port number to bind and has 'want reply' TRUE 690 then the server allocates the next available unprivileged port number 691 and replies with the following message, otherwise there is no 692 response specific data. 694 byte SSH_MSG_REQUEST_SUCCESS 695 uint32 port that was bound on the server 697 A port forwarding can be canceled with the following message. Note 698 that channel open requests may be received until a reply to this 699 message is received. 701 byte SSH_MSG_GLOBAL_REQUEST 702 string "cancel-tcpip-forward" 703 boolean want reply 704 string address_to_bind (e.g. "127.0.0.1") 705 uint32 port number to bind 707 Client implementations SHOULD reject these messages; they are 708 normally only sent by the client. 710 7.2 TCP/IP Forwarding Channels 712 When a connection comes to a port for which remote forwarding has 713 been requested, a channel is opened to forward the port to the other 714 side. 716 byte SSH_MSG_CHANNEL_OPEN 717 string "forwarded-tcpip" 718 uint32 sender channel 719 uint32 initial window size 720 uint32 maximum packet size 721 string address that was connected 722 uint32 port that was connected 723 string originator IP address 724 uint32 originator port 726 Implementations MUST reject these messages unless they have 727 previously requested a remote TCP/IP port forwarding with the given 728 port number. 730 When a connection comes to a locally forwarded TCP/IP port, the 731 following packet is sent to the other side. Note that these messages 732 MAY be sent also for ports for which no forwarding has been 733 explicitly requested. The receiving side must decide whether to 734 allow the forwarding. 736 byte SSH_MSG_CHANNEL_OPEN 737 string "direct-tcpip" 738 uint32 sender channel 739 uint32 initial window size 740 uint32 maximum packet size 741 string host to connect 742 uint32 port to connect 743 string originator IP address 744 uint32 originator port 746 The 'host to connect' and 'port to connect' specify the TCP/IP host 747 and port where the recipient should connect the channel. The 'host 748 to connect' may be either a domain name or a numeric IP address. 750 The 'originator IP address' is the numeric IP address of the machine 751 where the connection request comes from, and the 'originator port' is 752 the port on the originator host from where the connection originated. 754 Forwarded TCP/IP channels are independent of any sessions, and 755 closing a session channel does not in any way imply that forwarded 756 connections should be closed. 758 Client implementations SHOULD reject direct TCP/IP open requests for 759 security reasons. 761 8. Encoding of Terminal Modes 763 All "encoded terminal modes" (as passed in a pty request) are encoded 764 into a byte stream. It is intended that the coding be portable 765 across different environments. 767 The tty mode description is a stream of bytes. The stream consists 768 of opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). 769 Opcodes 1 to 159 have a single uint32 argument. Opcodes 160 to 255 770 are not yet defined, and cause parsing to stop (they should only be 771 used after any other data). 773 The client SHOULD put in the stream any modes it knows about, and the 774 server MAY ignore any modes it does not know about. This allows some 775 degree of machine-independence, at least between systems that use a 776 POSIX-like tty interface. The protocol can support other systems as 777 well, but the client may need to fill reasonable values for a number 778 of parameters so the server pty gets set to a reasonable mode (the 779 server leaves all unspecified mode bits in their default values, and 780 only some combinations make sense). 782 The following opcodes have been defined. The naming of opcodes 783 mostly follows the POSIX terminal mode flags. 785 opcode argument description 786 ------ -------- ----------- 787 0 TTY_OP_END Indicates end of options. 788 1 VINTR Interrupt character; 255 if none. Similarly 789 for the other characters. Not all of these 790 characters are supported on all systems. 791 2 VQUIT The quit character (sends SIGQUIT signal on 792 POSIX systems). 793 3 VERASE Erase the character to left of the cursor. 794 4 VKILL Kill the current input line. 795 5 VEOF End-of-file character (sends EOF from the 796 terminal). 797 6 VEOL End-of-line character in addition to 798 carriage return and/or linefeed. 799 7 VEOL2 Additional end-of-line character. 800 8 VSTART Continues paused output (normally 801 control-Q). 802 9 VSTOP Pauses output (normally control-S). 804 10 VSUSP Suspends the current program. 805 11 VDSUSP Another suspend character. 806 12 VREPRINT Reprints the current input line. 807 13 VWERASE Erases a word left of cursor. 808 14 VLNEXT Enter the next character typed literally, 809 even if it is a special character 810 15 VFLUSH Character to flush output. 811 16 VSWTCH Switch to a different shell layer. 812 17 VSTATUS Prints system status line (load, command, 813 pid, etc). 814 18 VDISCARD Toggles the flushing of terminal output. 815 30 IGNPAR The ignore parity flag. The parameter 816 SHOULD be 0 if this flag is FALSE set, 817 and 1 if it is TRUE. 818 31 PARMRK Mark parity and framing errors. 819 32 INPCK Enable checking of parity errors. 820 33 ISTRIP Strip 8th bit off characters. 821 34 INLCR Map NL into CR on input. 822 35 IGNCR Ignore CR on input. 823 36 ICRNL Map CR to NL on input. 824 37 IUCLC Translate uppercase characters to 825 lowercase. 826 38 IXON Enable output flow control. 827 39 IXANY Any char will restart after stop. 828 40 IXOFF Enable input flow control. 829 41 IMAXBEL Ring bell on input queue full. 830 50 ISIG Enable signals INTR, QUIT, [D]SUSP. 831 51 ICANON Canonicalize input lines. 832 52 XCASE Enable input and output of uppercase 833 characters by preceding their lowercase 834 equivalents with "\". 835 53 ECHO Enable echoing. 836 54 ECHOE Visually erase chars. 837 55 ECHOK Kill character discards current line. 838 56 ECHONL Echo NL even if ECHO is off. 839 57 NOFLSH Don't flush after interrupt. 840 58 TOSTOP Stop background jobs from output. 841 59 IEXTEN Enable extensions. 842 60 ECHOCTL Echo control characters as ^(Char). 843 61 ECHOKE Visual erase for line kill. 844 62 PENDIN Retype pending input. 845 70 OPOST Enable output processing. 846 71 OLCUC Convert lowercase to uppercase. 847 72 ONLCR Map NL to CR-NL. 848 73 OCRNL Translate carriage return to newline 849 (output). 850 74 ONOCR Translate newline to carriage 851 return-newline (output). 853 75 ONLRET Newline performs a carriage return 854 (output). 855 90 CS7 7 bit mode. 856 91 CS8 8 bit mode. 857 92 PARENB Parity enable. 858 93 PARODD Odd parity, else even. 860 128 TTY_OP_ISPEED Specifies the input baud rate in 861 bits per second. 862 129 TTY_OP_OSPEED Specifies the output baud rate in 863 bits per second. 865 9. Summary of Message Numbers 867 The following is a summary of messages and their associated message 868 number. 870 SSH_MSG_GLOBAL_REQUEST 80 871 SSH_MSG_REQUEST_SUCCESS 81 872 SSH_MSG_REQUEST_FAILURE 82 873 SSH_MSG_CHANNEL_OPEN 90 874 SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 875 SSH_MSG_CHANNEL_OPEN_FAILURE 92 876 SSH_MSG_CHANNEL_WINDOW_ADJUST 93 877 SSH_MSG_CHANNEL_DATA 94 878 SSH_MSG_CHANNEL_EXTENDED_DATA 95 879 SSH_MSG_CHANNEL_EOF 96 880 SSH_MSG_CHANNEL_CLOSE 97 881 SSH_MSG_CHANNEL_REQUEST 98 882 SSH_MSG_CHANNEL_SUCCESS 99 883 SSH_MSG_CHANNEL_FAILURE 100 885 10. IANA Considerations 887 This document is part of a set. The IANA considerations for the SSH 888 protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], and 889 this document, are detailed in [SSH-NUMBERS]. 891 11. Security Considerations 893 This protocol is assumed to run on top of a secure, authenticated 894 transport. User authentication and protection against network-level 895 attacks are assumed to be provided by the underlying protocols. 897 Full security considerations for this protocol are provided in 899 [SSH-ARCH]. Specific to this document, it is RECOMMENDED that 900 implementations disable all the potentially dangerous features (e.g. 901 agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host 902 key has changed without notice or explanation. 904 12. References 906 12.1 Normative References 908 [SSH-ARCH] 909 Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", 910 I-D draft-ietf-architecture-17.txt, October 2004. 912 [SSH-TRANS] 913 Ylonen, T. and C. Lonvick, "SSH Transport Layer Protocol", 914 I-D draft-ietf-transport-19.txt, October 2004. 916 [SSH-USERAUTH] 917 Ylonen, T. and C. Lonvick, "SSH Authentication Protocol", 918 I-D draft-ietf-userauth-22.txt, October 2004. 920 [SSH-NUMBERS] 921 Ylonen, T. and C. Lonvick, "SSH Protocol Assigned 922 Numbers", I-D draft-ietf-assignednumbers-07.txt, October 923 2004. 925 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 926 Requirement Levels", BCP 14, RFC 2119, March 1997. 928 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 929 10646", STD 63, RFC 3629, November 2003. 931 12.2 Informative References 933 [RFC1884] Hinden, R. and S. Deering, "IP Version 6 Addressing 934 Architecture", RFC 1884, December 1995. 936 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 937 IANA Considerations Section in RFCs", BCP 26, RFC 2434, 938 October 1998. 940 [RFC3066] Alvestrand, H., "Tags for the Identification of 941 Languages", BCP 47, RFC 3066, January 2001. 943 [SCHEIFLER] 944 Scheifler, R., "X Window System : The Complete Reference 945 to Xlib, X Protocol, Icccm, Xlfd, 3rd edition.", Digital 946 Press ISBN 1555580882, February 1992. 948 [POSIX] ISO/IEC, 9945-1., "Information technology -- Portable 949 Operating System Interface (POSIX)-Part 1: System 950 Application Program Interface (API) C Language", ANSI/IEE 951 Std 1003.1, July 1996. 953 Author's Address 955 Chris Lonvick (editor) 956 Cisco Systems, Inc 957 12515 Research Blvd. 958 Austin 78759 959 USA 961 EMail: clonvick@cisco.com 963 Intellectual Property Statement 965 The IETF takes no position regarding the validity or scope of any 966 Intellectual Property Rights or other rights that might be claimed to 967 pertain to the implementation or use of the technology described in 968 this document or the extent to which any license under such rights 969 might or might not be available; nor does it represent that it has 970 made any independent effort to identify any such rights. Information 971 on the procedures with respect to rights in RFC documents can be 972 found in BCP 78 and BCP 79. 974 Copies of IPR disclosures made to the IETF Secretariat and any 975 assurances of licenses to be made available, or the result of an 976 attempt made to obtain a general license or permission for the use of 977 such proprietary rights by implementers or users of this 978 specification can be obtained from the IETF on-line IPR repository at 979 http://www.ietf.org/ipr. 981 The IETF invites any interested party to bring to its attention any 982 copyrights, patents or patent applications, or other proprietary 983 rights that may cover technology that may be required to implement 984 this standard. Please address the information to the IETF at 985 ietf-ipr@ietf.org. 987 The IETF has been notified of intellectual property rights claimed in 988 regard to some or all of the specification contained in this 989 document. For more information consult the online list of claimed 990 rights. 992 Disclaimer of Validity 994 This document and the information contained herein are provided on an 995 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 996 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 997 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 998 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 999 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1000 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1002 Copyright Statement 1004 Copyright (C) The Internet Society (2004). This document is subject 1005 to the rights, licenses and restrictions contained in BCP 78, and 1006 except as set forth therein, the authors retain all their rights. 1008 Acknowledgment 1010 Funding for the RFC Editor function is currently provided by the 1011 Internet Society.