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