idnits 2.17.1 draft-ietf-secsh-connect-24.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 1073. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1045. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1052. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1058. ** 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 141 has weird spacing: '... string dat...' == Line 158 has weird spacing: '... string req...' == Line 159 has weird spacing: '...boolean want...' == Line 211 has weird spacing: '... string cha...' == Line 246 has weird spacing: '... string des...' == (35 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 (February 17, 2005) is 6980 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 1007, but no explicit reference was found in the text == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-21 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-23 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-26 == Outdated reference: A later version (-12) exists of draft-ietf-secsh-assignednumbers-11 ** 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) -- Obsolete informational reference (is this intentional?): RFC 3330 (Obsoleted by RFC 5735) -- Obsolete informational reference (is this intentional?): RFC 3513 (Obsoleted by RFC 4291) Summary: 7 errors (**), 0 flaws (~~), 14 warnings (==), 10 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: August 21, 2005 February 17, 2005 6 SSH Connection Protocol 7 draft-ietf-secsh-connect-24.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 August 21, 2005. 36 Copyright Notice 38 Copyright (C) The Internet Society (2005). 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 . . . . . . . . . . . . . . . . . . . . . . . 4 59 5. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . 5 60 5.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . 5 61 5.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . 7 62 5.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . 8 63 5.4 Channel-Specific Requests . . . . . . . . . . . . . . . . 9 64 6. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . 10 65 6.1 Opening a Session . . . . . . . . . . . . . . . . . . . . 10 66 6.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . 10 67 6.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . 11 68 6.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . 11 69 6.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . 11 70 6.4 Environment Variable Passing . . . . . . . . . . . . . . . 12 71 6.5 Starting a Shell or a Command . . . . . . . . . . . . . . 12 72 6.6 Session Data Transfer . . . . . . . . . . . . . . . . . . 13 73 6.7 Window Dimension Change Message . . . . . . . . . . . . . 13 74 6.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . 14 75 6.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . 14 76 6.10 Returning Exit Status . . . . . . . . . . . . . . . . . . 14 77 7. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . 16 78 7.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . 16 79 7.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . 17 80 8. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . 18 81 9. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 20 82 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 21 83 11. Security Considerations . . . . . . . . . . . . . . . . . . 21 84 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 85 12.1 Normative References . . . . . . . . . . . . . . . . . . . 21 86 12.2 Informative References . . . . . . . . . . . . . . . . . . 22 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 22 88 Intellectual Property and Copyright Statements . . . . . . . . 23 90 1. Contributors 92 The major original contributors of this set of documents have been: 93 Tatu Ylonen, 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 set of documents 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 Protocol fields and possible values to fill them are defined in this 135 set of documents. Protocol fields will be defined in the message 136 definitions. As an example, SSH_MSG_CHANNEL_DATA is defined as 137 follows. 139 byte SSH_MSG_CHANNEL_DATA 140 uint32 recipient channel 141 string data 143 Throughout these documents, when the fields are referenced, they will 144 appear within single quotes. When values to fill those fields are 145 referenced, they will appear within double quotes. Using the above 146 example, possible values for 'data' are "foo" and "bar". 148 4. Global Requests 150 There are several kinds of requests that affect the state of the 151 remote end globally, independent of any channels. An example is a 152 request to start TCP/IP forwarding for a specific port. Note that 153 both client and server MAY send global requests at any time, and the 154 receiver MUST respond appropriately. All such requests use the 155 following format. 157 byte SSH_MSG_GLOBAL_REQUEST 158 string request name in US-ASCII only 159 boolean want reply 160 ... request-specific data follows 162 The value of 'request name' follows the DNS extensibility naming 163 convention outlined in [SSH-ARCH]. 165 The recipient will respond to this message with 166 SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if 'want reply' is 167 TRUE. 169 byte SSH_MSG_REQUEST_SUCCESS 170 ..... response specific data 172 Usually the 'response specific data' is non-existent. 174 If the recipient does not recognize or support the request, it simply 175 responds with SSH_MSG_REQUEST_FAILURE. 177 byte SSH_MSG_REQUEST_FAILURE 179 In general, the reply messages do not include request type 180 identifiers. To make it possible for the originator of a request to 181 identify to which request each reply refers, it is REQUIRED that 182 replies to SSH_MSG_GLOBAL_REQUESTS MUST be sent in the same order as 183 the corresponding request messages. For channel requests, replies 184 that relate to the same channel MUST also be replied to in the right 185 order. However, channel requests for distinct channels MAY be 186 replied to out-of-order. 188 5. Channel Mechanism 190 All terminal sessions, forwarded connections, etc., are channels. 191 Either side may open a channel. Multiple channels are multiplexed 192 into a single connection. 194 Channels are identified by numbers at each end. The number referring 195 to a channel may be different on each side. Requests to open a 196 channel contain the sender's channel number. Any other 197 channel-related messages contain the recipient's channel number for 198 the channel. 200 Channels are flow-controlled. No data may be sent to a channel until 201 a message is received to indicate that window space is available. 203 5.1 Opening a Channel 205 When either side wishes to open a new channel, it allocates a local 206 number for the channel. It then sends the following message to the 207 other side, and includes the local channel number and initial window 208 size in the message. 210 byte SSH_MSG_CHANNEL_OPEN 211 string channel type in US-ASCII only 212 uint32 sender channel 213 uint32 initial window size 214 uint32 maximum packet size 215 ... channel type specific data follows 217 The 'channel type' is a name as described in [SSH-ARCH] and 218 [SSH-NUMBERS], with similar extension mechanisms. The 'sender 219 channel' is a local identifier for the channel used by the sender of 220 this message. The 'initial window size' specifies how many bytes of 221 channel data can be sent to the sender of this message without 222 adjusting the window. The 'maximum packet size' specifies the 223 maximum size of an individual data packet that can be sent to the 224 sender. For example: one might want to use smaller packets for 225 interactive connections to get better interactive response on slow 226 links. 228 The remote side then decides whether it can open the channel, and 229 responds with either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or 230 SSH_MSG_CHANNEL_OPEN_FAILURE. 232 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 233 uint32 recipient channel 234 uint32 sender channel 235 uint32 initial window size 236 uint32 maximum packet size 237 ... 'channel type' specific data follows 239 The 'recipient channel' is the channel number given in the original 240 open request, and 'sender channel' is the channel number allocated by 241 the other side. 243 byte SSH_MSG_CHANNEL_OPEN_FAILURE 244 uint32 recipient channel 245 uint32 reason code 246 string description in ISO-10646 UTF-8 encoding [RFC3629] 247 string language tag as defined in [RFC3066] 249 If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support 250 the specified 'channel type', it simply responds with 251 SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the 'description' 252 string to the user. If this is done, the client software should take 253 the precautions discussed in [SSH-ARCH]. 255 The SSH_MSG_CHANNEL_OPEN_FAILURE 'reason code' values are defined in 256 the following table. Note that the values for the 'reason code' are 257 given in decimal format for readability but that they are actually 258 uint32 values. 260 Symbolic name reason code 261 ------------- ----------- 262 SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 263 SSH_OPEN_CONNECT_FAILED 2 264 SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 265 SSH_OPEN_RESOURCE_SHORTAGE 4 267 Requests for assignments of new SSH_MSG_CHANNEL_OPEN 'reason code' 268 values (and associated 'description' text) in the range of 0x00000005 269 to 0xFDFFFFFF MUST be done through the IETF CONSENSUS method as 270 described in [RFC2434]. The IANA will not assign Channel Connection 271 Failure 'reason code' values in the range of 0xFE000000 to 272 0xFFFFFFFF. Channel Connection Failure 'reason code' values in that 273 range are left for PRIVATE USE as described in [RFC2434]. 275 While it is understood that the IANA will have no control over the 276 range of 0xFE000000 to 0xFFFFFFFF, this range will be split in two 277 parts and administered by the following conventions. 278 o The range of 0xFE000000 to 0xFEFFFFFF is to be used in conjunction 279 with locally assigned channels. For example: if a channel is 280 proposed with a 'channel type' of "example_session@example.com" 281 but fails, then the response will contain either a 'reason code' 282 assigned by the IANA (as listed above and in the range of 283 0x00000001 to 0xFDFFFFFF), or with a locally assigned value in the 284 range of 0xFE000000 to 0xFEFFFFFF. Naturally, if the server does 285 not understand the proposed 'channel type', even if it is a 286 locally defined 'channel type', then the 'reason code' MUST be 287 0x00000003 as described above, if the 'reason code' is sent. If 288 the server does understand the 'channel type' but the channel 289 still fails to open, then the server SHOULD respond with a locally 290 assigned 'reason code' value consistent with the proposed, local 291 'channel type'. It is assumed that practitioners will first 292 attempt to use the IANA assigned 'reason code' values and then 293 document their locally assigned 'reason code' values. 294 o There are no restrictions or suggestions for the range starting 295 with 0xFF. No interoperability is expected for anything used in 296 this range. Essentially it is for experimentation. 298 5.2 Data Transfer 300 The window size specifies how many bytes the other party can send 301 before it must wait for the window to be adjusted. Both parties use 302 the following message to adjust the window. 304 byte SSH_MSG_CHANNEL_WINDOW_ADJUST 305 uint32 recipient channel 306 uint32 bytes to add 308 After receiving this message, the recipient MAY send the given number 309 of bytes more than it was previously allowed to send; the window size 310 is incremented. 312 Data transfer is done with messages of the following type. 314 byte SSH_MSG_CHANNEL_DATA 315 uint32 recipient channel 316 string data 318 The maximum amount of data allowed is the current window size. The 319 window size is decremented by the amount of data sent. Both parties 320 MAY ignore all extra data sent after the allowed window is empty. 322 Additionally, some channels can transfer several types of data. An 323 example of this is stderr data from interactive sessions. Such data 324 can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a 325 separate integer specifies the type of the data. The available types 326 and their interpretation depend on the type of the channel. 328 byte SSH_MSG_CHANNEL_EXTENDED_DATA 329 uint32 recipient_channel 330 uint32 data_type_code 331 string data 333 Data sent with these messages consumes the same window as ordinary 334 data. 336 Currently, only the following type is defined. Note that the value 337 for the 'data_type_code' is given in decimal format for readability 338 but that the values are actually uint32 values. 340 Symbolic name data_type_code 341 ------------- -------------- 342 SSH_EXTENDED_DATA_STDERR 1 344 Extended Channel Data Transfer 'data_type_code' values MUST be 345 assigned sequentially. Requests for assignments of new Extended 346 Channel Data Transfer 'data_type_code' values, and their associated 347 Extended Channel Data Transfer 'data' strings, in the range of 348 0x00000002 to 0xFDFFFFFF MUST be done through the IETF CONSENSUS 349 method as described in [RFC2434]. The IANA will not assign Extended 350 Channel Data Transfer 'data_type_code' values in the range of 351 0xFE000000 to 0xFFFFFFFF. Extended Channel Data Transfer 352 'data_type_code' values in that range are left for PRIVATE USE as 353 described in [RFC2434]. As is noted, the actual instructions to the 354 IANA are in [SSH-NUMBERS]. 356 5.3 Closing a Channel 358 When a party will no longer send more data to a channel, it SHOULD 359 send SSH_MSG_CHANNEL_EOF. 361 byte SSH_MSG_CHANNEL_EOF 362 uint32 recipient_channel 364 No explicit response is sent to this message. However, the 365 application may send EOF to whatever is at the other end of the 366 channel. Note that the channel remains open after this message, and 367 more data may still be sent in the other direction. This message 368 does not consume window space and can be sent even if no window space 369 is available. 371 When either party wishes to terminate the channel, it sends 372 SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST 373 send back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this 374 message for the channel. The channel is considered closed for a 375 party when it has both sent and received SSH_MSG_CHANNEL_CLOSE, and 376 the party may then reuse the channel number. A party MAY send 377 SSH_MSG_CHANNEL_CLOSE without having sent or received 378 SSH_MSG_CHANNEL_EOF. 380 byte SSH_MSG_CHANNEL_CLOSE 381 uint32 recipient_channel 383 This message does not consume window space and can be sent even if no 384 window space is available. 386 It is recommended that any data sent before this message is delivered 387 to the actual destination, if possible. 389 5.4 Channel-Specific Requests 391 Many 'channel type' values have extensions that are specific to that 392 particular 'channel type'. An example is requesting a pty (pseudo 393 terminal) for an interactive session. 395 All channel-specific requests use the following format. 397 byte SSH_MSG_CHANNEL_REQUEST 398 uint32 recipient channel 399 string request type in US-ASCII characters only 400 boolean want reply 401 ... type-specific data 403 If 'want reply' is FALSE, no response will be sent to the request. 404 Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS 405 or SSH_MSG_CHANNEL_FAILURE, or request-specific continuation 406 messages. If the request is not recognized or is not supported for 407 the channel, SSH_MSG_CHANNEL_FAILURE is returned. 409 This message does not consume window space and can be sent even if no 410 window space is available. The values of 'request type' are local to 411 each channel type. 413 The client is allowed to send further messages without waiting for 414 the response to the request. 416 'request type' names follow the DNS extensibility naming convention 417 outlined in [SSH-ARCH] and [SSH-NUMBERS]. 419 byte SSH_MSG_CHANNEL_SUCCESS 420 uint32 recipient_channel 422 byte SSH_MSG_CHANNEL_FAILURE 423 uint32 recipient_channel 425 These messages do not consume window space and can be sent even if no 426 window space is available. 428 6. Interactive Sessions 430 A session is a remote execution of a program. The program may be a 431 shell, an application, a system command, or some built-in subsystem. 432 It may or may not have a tty, and may or may not involve X11 433 forwarding. Multiple sessions can be active simultaneously. 435 6.1 Opening a Session 437 A session is started by sending the following message. 439 byte SSH_MSG_CHANNEL_OPEN 440 string "session" 441 uint32 sender channel 442 uint32 initial window size 443 uint32 maximum packet size 445 Client implementations SHOULD reject any session channel open 446 requests to make it more difficult for a corrupt server to attack the 447 client. 449 6.2 Requesting a Pseudo-Terminal 451 A pseudo-terminal can be allocated for the session by sending the 452 following message. 454 byte SSH_MSG_CHANNEL_REQUEST 455 uint32 recipient_channel 456 string "pty-req" 457 boolean want_reply 458 string TERM environment variable value (e.g., vt100) 459 uint32 terminal width, characters (e.g., 80) 460 uint32 terminal height, rows (e.g., 24) 461 uint32 terminal width, pixels (e.g., 640) 462 uint32 terminal height, pixels (e.g., 480) 463 string encoded terminal modes 465 The 'encoded terminal modes' are described in Section 8. Zero 466 dimension parameters MUST be ignored. The character/row dimensions 467 override the pixel dimensions (when nonzero). Pixel dimensions refer 468 to the drawable area of the window. 470 The dimension parameters are only informational. 472 The client SHOULD ignore pty requests. 474 6.3 X11 Forwarding 476 6.3.1 Requesting X11 Forwarding 478 X11 forwarding may be requested for a session by sending a 479 SSH_MSG_CHANNEL_REQUEST message. 481 byte SSH_MSG_CHANNEL_REQUEST 482 uint32 recipient channel 483 string "x11-req" 484 boolean want reply 485 boolean single connection 486 string x11 authentication protocol 487 string x11 authentication cookie 488 uint32 x11 screen number 490 It is RECOMMENDED that the 'x11 authentication cookie' that is sent 491 be a fake, random cookie, and that the cookie is checked and replaced 492 by the real cookie when a connection request is received. 494 X11 connection forwarding should stop when the session channel is 495 closed. However, already opened forwardings should not be 496 automatically closed when the session channel is closed. 498 If 'single connection' is TRUE, only a single connection should be 499 forwarded. No more connections will be forwarded after the first, or 500 after the session channel has been closed. 502 The 'x11 authentication protocol' is the name of the X11 503 authentication method used, e.g., "MIT-MAGIC-COOKIE-1". 505 The 'x11 authentication cookie' MUST be hexadecimal encoded. 507 The X Protocol is documented in [SCHEIFLER]. 509 6.3.2 X11 Channels 511 X11 channels are opened with a channel open request. The resulting 512 channels are independent of the session, and closing the session 513 channel does not close the forwarded X11 channels. 515 byte SSH_MSG_CHANNEL_OPEN 516 string "x11" 517 uint32 sender channel 518 uint32 initial window size 519 uint32 maximum packet size 520 string originator address (e.g., "192.168.7.38") 521 uint32 originator port 523 The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION 524 or SSH_MSG_CHANNEL_OPEN_FAILURE. 526 Implementations MUST reject any X11 channel open requests if they 527 have not requested X11 forwarding. 529 6.4 Environment Variable Passing 531 Environment variables may be passed to the shell/command to be 532 started later. Uncontrolled setting of environment variables in a 533 privileged process can be a security hazard. It is recommended that 534 implementations either maintain a list of allowable variable names or 535 only set environment variables after the server process has dropped 536 sufficient privileges. 538 byte SSH_MSG_CHANNEL_REQUEST 539 uint32 recipient channel 540 string "env" 541 boolean want reply 542 string variable name 543 string variable value 545 6.5 Starting a Shell or a Command 547 Once the session has been set up, a program is started at the remote 548 end. The program can be a shell, an application program or a 549 subsystem with a host-independent name. Only one of these requests 550 can succeed per channel. 552 byte SSH_MSG_CHANNEL_REQUEST 553 uint32 recipient channel 554 string "shell" 555 boolean want reply 557 This message will request the user's default shell (typically defined 558 in /etc/passwd in UNIX systems) to be started at the other end. 560 byte SSH_MSG_CHANNEL_REQUEST 561 uint32 recipient channel 562 string "exec" 563 boolean want reply 564 string command 566 This message will request the server to start the execution of the 567 given command. The 'command' string may contain a path. Normal 568 precautions MUST be taken to prevent the execution of unauthorized 569 commands. 571 byte SSH_MSG_CHANNEL_REQUEST 572 uint32 recipient channel 573 string "subsystem" 574 boolean want reply 575 string subsystem name 577 This last form executes a predefined subsystem. It is expected that 578 these will include a general file transfer mechanism, and possibly 579 other features. Implementations may also allow configuring more such 580 mechanisms. As the user's shell is usually used to execute the 581 subsystem, it is advisable for the subsystem protocol to have a 582 "magic cookie" at the beginning of the protocol transaction to 583 distinguish it from arbitrary output generated by shell 584 initialization scripts, etc. This spurious output from the shell may 585 be filtered out either at the server or at the client. 587 The server SHOULD NOT halt the execution of the protocol stack when 588 starting a shell or a program. All input and output from these 589 SHOULD be redirected to the channel or to the encrypted tunnel. 591 It is RECOMMENDED to request and check the reply for these messages. 592 The client SHOULD ignore these messages. 594 Subsystem names follow the DNS extensibility naming convention 595 outlined in [SSH-NUMBERS]. 597 6.6 Session Data Transfer 599 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 600 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The 601 extended data type SSH_EXTENDED_DATA_STDERR has been defined for 602 stderr data. 604 6.7 Window Dimension Change Message 606 When the window (terminal) size changes on the client side, it MAY 607 send a message to the other side to inform it of the new dimensions. 609 byte SSH_MSG_CHANNEL_REQUEST 610 uint32 recipient_channel 611 string "window-change" 612 boolean FALSE 613 uint32 terminal width, columns 614 uint32 terminal height, rows 615 uint32 terminal width, pixels 616 uint32 terminal height, pixels 618 A response SHOULD NOT be sent to this message. 620 6.8 Local Flow Control 622 On many systems, it is possible to determine if a pseudo-terminal is 623 using control-S/control-Q flow control. When flow control is 624 allowed, it is often desirable to do the flow control at the client 625 end to speed up responses to user requests. This is facilitated by 626 the following notification. Initially, the server is responsible for 627 flow control. (Here, again, client means the side originating the 628 session, and server means the other side.) 630 The message below is used by the server to inform the client when it 631 can or cannot perform flow control (control-S/control-Q processing). 632 If 'client can do' is TRUE, the client is allowed to do flow control 633 using control-S and control-Q. The client MAY ignore this message. 635 byte SSH_MSG_CHANNEL_REQUEST 636 uint32 recipient channel 637 string "xon-xoff" 638 boolean FALSE 639 boolean client can do 641 No response is sent to this message. 643 6.9 Signals 645 A signal can be delivered to the remote process/service using the 646 following message. Some systems may not implement signals, in which 647 case they SHOULD ignore this message. 649 byte SSH_MSG_CHANNEL_REQUEST 650 uint32 recipient channel 651 string "signal" 652 boolean FALSE 653 string signal name without the "SIG" prefix. 655 Signal names will be encoded as discussed in the "exit-signal" 656 SSH_MSG_CHANNEL_REQUEST. 658 6.10 Returning Exit Status 660 When the command running at the other end terminates, the following 661 message can be sent to return the exit status of the command. 662 Returning the status is RECOMMENDED. No acknowledgment is sent for 663 this message. The channel needs to be closed with 664 SSH_MSG_CHANNEL_CLOSE after this message. 666 The client MAY ignore these messages. 668 byte SSH_MSG_CHANNEL_REQUEST 669 uint32 recipient_channel 670 string "exit-status" 671 boolean FALSE 672 uint32 exit_status 674 The remote command may also terminate violently due to a signal. 675 Such a condition can be indicated by the following message. A zero 676 'exit_status' usually means that the command terminated successfully. 677 o byte SSH_MSG_CHANNEL_REQUEST 678 o uint32 recipient channel 679 o string "exit-signal" 680 o boolean FALSE 681 o string signal name without the "SIG" prefix. 682 o boolean core dumped 683 o string error message in ISO-10646 UTF-8 encoding 684 o string language tag as defined in [RFC3066] 686 The 'signal name' is one of the following (these are from [POSIX]) 688 ABRT 689 ALRM 690 FPE 691 HUP 692 ILL 693 INT 694 KILL 695 PIPE 696 QUIT 697 SEGV 698 TERM 699 USR1 700 USR2 702 Additional 'signal name' values MAY be sent in the format 703 "sig-name@xyz", where "sig-name" and "xyz" may be anything a 704 particular implementor wants (except the "@" sign). However, it is 705 suggested that if a 'configure' script is used, any non-standard 706 'signal name' values it finds be encoded as "SIG@xyz.config.guess", 707 where "SIG" is the 'signal name' without the "SIG" prefix, and "xyz" 708 be the host type, as determined by "config.guess". 710 The 'error message' contains an additional textual explanation of the 711 error message. The message may consist of multiple lines. The 712 client software MAY display this message to the user. If this is 713 done, the client software should take the precautions discussed in 714 [SSH-ARCH]. 716 7. TCP/IP Port Forwarding 718 7.1 Requesting Port Forwarding 720 A party need not explicitly request forwardings from its own end to 721 the other direction. However, if it wishes that connections to a 722 port on the other side be forwarded to the local side, it must 723 explicitly request this. 725 byte SSH_MSG_GLOBAL_REQUEST 726 string "tcpip-forward" 727 boolean want reply 728 string address to bind (e.g., "0.0.0.0") 729 uint32 port number to bind 731 The 'address to bind' and 'port number to bind' specify the IP 732 address or domain name and port to which the socket to be listened is 733 bound. Some strings used for the 'address to bind' have special-case 734 semantics. 735 o "" means that connections are to be accepted on all protocol 736 families supported by the SSH implementation. 737 o "0.0.0.0" means to listen on all IPv4 addresses. 738 o "::" means to listen on all IPv6 addresses. 739 o "localhost" means to listen on all protocol families supported by 740 the SSH implementation on loopback addresses only, [RFC3330] and 741 [RFC3513]. 742 o "127.0.0.1" and "::1" indicate listening on the loopback 743 interfaces for IPv4 and IPv6 respectively. 745 Note that the client can still filter connections based on 746 information passed in the open request. 748 Implementations should only allow forwarding privileged ports if the 749 user has been authenticated as a privileged user. 751 Client implementations SHOULD reject these messages; they are 752 normally only sent by the client. 754 If a client passes 0 as port number to bind and has 'want reply' TRUE 755 then the server allocates the next available unprivileged port number 756 and replies with the following message, otherwise there is no 757 response specific data. 759 byte SSH_MSG_REQUEST_SUCCESS 760 uint32 port that was bound on the server 762 A port forwarding can be canceled with the following message. Note 763 that channel open requests may be received until a reply to this 764 message is received. 766 byte SSH_MSG_GLOBAL_REQUEST 767 string "cancel-tcpip-forward" 768 boolean want reply 769 string address_to_bind (e.g., "127.0.0.1") 770 uint32 port number to bind 772 Client implementations SHOULD reject these messages; they are 773 normally only sent by the client. 775 7.2 TCP/IP Forwarding Channels 777 When a connection comes to a port for which remote forwarding has 778 been requested, a channel is opened to forward the port to the other 779 side. 781 byte SSH_MSG_CHANNEL_OPEN 782 string "forwarded-tcpip" 783 uint32 sender channel 784 uint32 initial window size 785 uint32 maximum packet size 786 string address that was connected 787 uint32 port that was connected 788 string originator IP address 789 uint32 originator port 791 Implementations MUST reject these messages unless they have 792 previously requested a remote TCP/IP port forwarding with the given 793 port number. 795 When a connection comes to a locally forwarded TCP/IP port, the 796 following packet is sent to the other side. Note that these messages 797 MAY be sent also for ports for which no forwarding has been 798 explicitly requested. The receiving side must decide whether to 799 allow the forwarding. 801 byte SSH_MSG_CHANNEL_OPEN 802 string "direct-tcpip" 803 uint32 sender channel 804 uint32 initial window size 805 uint32 maximum packet size 806 string host to connect 807 uint32 port to connect 808 string originator IP address 809 uint32 originator port 811 The 'host to connect' and 'port to connect' specify the TCP/IP host 812 and port where the recipient should connect the channel. The 'host 813 to connect' may be either a domain name or a numeric IP address. 815 The 'originator IP address' is the numeric IP address of the machine 816 where the connection request comes from, and the 'originator port' is 817 the port on the originator host from where the connection originated. 819 Forwarded TCP/IP channels are independent of any sessions, and 820 closing a session channel does not in any way imply that forwarded 821 connections should be closed. 823 Client implementations SHOULD reject direct TCP/IP open requests for 824 security reasons. 826 8. Encoding of Terminal Modes 828 All "encoded terminal modes" (as passed in a pty request) are encoded 829 into a byte stream. It is intended that the coding be portable 830 across different environments. 832 The tty mode description is a stream of bytes. The stream consists 833 of opcode-argument pairs where the opcode is a byte value. It is 834 terminated by opcode TTY_OP_END (0x00). Opcodes 1 to 159 have a 835 single uint32 argument. Opcodes 160 to 255 are not yet defined, and 836 cause parsing to stop (they should only be used after any other 837 data). 839 The client SHOULD put in the stream any modes it knows about, and the 840 server MAY ignore any modes it does not know about. This allows some 841 degree of machine-independence, at least between systems that use a 842 POSIX-like tty interface. The protocol can support other systems as 843 well, but the client may need to fill reasonable values for a number 844 of parameters so the server pty gets set to a reasonable mode (the 845 server leaves all unspecified mode bits in their default values, and 846 only some combinations make sense). 848 The naming of opcode values mostly follows the POSIX terminal mode 849 flags. The following opcode values have been defined. Note that the 850 values given below are in decimal format for readability but that 851 they are actually byte values. 853 opcode argument description 854 ------ -------- ----------- 855 0 TTY_OP_END Indicates end of options. 857 1 VINTR Interrupt character; 255 if none. Similarly 858 for the other characters. Not all of these 859 characters are supported on all systems. 860 2 VQUIT The quit character (sends SIGQUIT signal on 861 POSIX systems). 862 3 VERASE Erase the character to left of the cursor. 863 4 VKILL Kill the current input line. 864 5 VEOF End-of-file character (sends EOF from the 865 terminal). 866 6 VEOL End-of-line character in addition to 867 carriage return and/or linefeed. 868 7 VEOL2 Additional end-of-line character. 869 8 VSTART Continues paused output (normally 870 control-Q). 871 9 VSTOP Pauses output (normally control-S). 872 10 VSUSP Suspends the current program. 873 11 VDSUSP Another suspend character. 874 12 VREPRINT Reprints the current input line. 875 13 VWERASE Erases a word left of cursor. 876 14 VLNEXT Enter the next character typed literally, 877 even if it is a special character 878 15 VFLUSH Character to flush output. 879 16 VSWTCH Switch to a different shell layer. 880 17 VSTATUS Prints system status line (load, command, 881 pid, etc). 882 18 VDISCARD Toggles the flushing of terminal output. 883 30 IGNPAR The ignore parity flag. The parameter 884 SHOULD be 0 if this flag is FALSE, 885 and 1 if it is TRUE. 886 31 PARMRK Mark parity and framing errors. 887 32 INPCK Enable checking of parity errors. 888 33 ISTRIP Strip 8th bit off characters. 889 34 INLCR Map NL into CR on input. 890 35 IGNCR Ignore CR on input. 891 36 ICRNL Map CR to NL on input. 892 37 IUCLC Translate uppercase characters to 893 lowercase. 894 38 IXON Enable output flow control. 895 39 IXANY Any char will restart after stop. 896 40 IXOFF Enable input flow control. 897 41 IMAXBEL Ring bell on input queue full. 898 50 ISIG Enable signals INTR, QUIT, [D]SUSP. 899 51 ICANON Canonicalize input lines. 900 52 XCASE Enable input and output of uppercase 901 characters by preceding their lowercase 902 equivalents with "\". 903 53 ECHO Enable echoing. 904 54 ECHOE Visually erase chars. 906 55 ECHOK Kill character discards current line. 907 56 ECHONL Echo NL even if ECHO is off. 908 57 NOFLSH Don't flush after interrupt. 909 58 TOSTOP Stop background jobs from output. 910 59 IEXTEN Enable extensions. 911 60 ECHOCTL Echo control characters as ^(Char). 912 61 ECHOKE Visual erase for line kill. 913 62 PENDIN Retype pending input. 914 70 OPOST Enable output processing. 915 71 OLCUC Convert lowercase to uppercase. 916 72 ONLCR Map NL to CR-NL. 917 73 OCRNL Translate carriage return to newline 918 (output). 919 74 ONOCR Translate newline to carriage 920 return-newline (output). 921 75 ONLRET Newline performs a carriage return 922 (output). 923 90 CS7 7 bit mode. 924 91 CS8 8 bit mode. 925 92 PARENB Parity enable. 926 93 PARODD Odd parity, else even. 928 128 TTY_OP_ISPEED Specifies the input baud rate in 929 bits per second. 930 129 TTY_OP_OSPEED Specifies the output baud rate in 931 bits per second. 933 9. Summary of Message Numbers 935 The following is a summary of messages and their associated message 936 number. 938 SSH_MSG_GLOBAL_REQUEST 80 939 SSH_MSG_REQUEST_SUCCESS 81 940 SSH_MSG_REQUEST_FAILURE 82 941 SSH_MSG_CHANNEL_OPEN 90 942 SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 943 SSH_MSG_CHANNEL_OPEN_FAILURE 92 944 SSH_MSG_CHANNEL_WINDOW_ADJUST 93 945 SSH_MSG_CHANNEL_DATA 94 946 SSH_MSG_CHANNEL_EXTENDED_DATA 95 947 SSH_MSG_CHANNEL_EOF 96 948 SSH_MSG_CHANNEL_CLOSE 97 949 SSH_MSG_CHANNEL_REQUEST 98 950 SSH_MSG_CHANNEL_SUCCESS 99 951 SSH_MSG_CHANNEL_FAILURE 100 953 10. IANA Considerations 955 This document is part of a set. The IANA considerations for the SSH 956 protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], and 957 this document, are detailed in [SSH-NUMBERS]. 959 11. Security Considerations 961 This protocol is assumed to run on top of a secure, authenticated 962 transport. User authentication and protection against network-level 963 attacks are assumed to be provided by the underlying protocols. 965 Full security considerations for this protocol are provided in 966 [SSH-ARCH]. Specific to this document, it is RECOMMENDED that 967 implementations disable all the potentially dangerous features (e.g., 968 agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host 969 key has changed without notice or explanation. 971 12. References 973 12.1 Normative References 975 [SSH-ARCH] 976 Lonvick, C., "SSH Protocol Architecture", 977 I-D draft-ietf-secsh-architecture-21.txt, February 2005. 979 [SSH-TRANS] 980 Lonvick, C., "SSH Transport Layer Protocol", 981 I-D draft-ietf-secsh-transport-23.txt, February 2005. 983 [SSH-USERAUTH] 984 Lonvick, C., "SSH Authentication Protocol", 985 I-D draft-ietf-secsh-userauth-26.txt, February 2005. 987 [SSH-NUMBERS] 988 Lonvick, C., "SSH Protocol Assigned Numbers", 989 I-D draft-ietf-secsh-assignednumbers-11.txt, February 990 2005. 992 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 993 Requirement Levels", BCP 14, RFC 2119, March 1997. 995 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 996 IANA Considerations Section in RFCs", BCP 26, RFC 2434, 997 October 1998. 999 [RFC3066] Alvestrand, H., "Tags for the Identification of 1000 Languages", BCP 47, RFC 3066, January 2001. 1002 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1003 10646", STD 63, RFC 3629, November 2003. 1005 12.2 Informative References 1007 [RFC1884] Hinden, R. and S. Deering, "IP Version 6 Addressing 1008 Architecture", RFC 1884, December 1995. 1010 [RFC3330] IANA, "Special-Use IPv4 Addresses", RFC 3330, September 1011 2002. 1013 [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version 6 1014 (IPv6) Addressing Architecture", RFC 3513, April 2003. 1016 [SCHEIFLER] 1017 Scheifler, R., "X Window System : The Complete Reference 1018 to Xlib, X Protocol, Icccm, Xlfd, 3rd edition.", Digital 1019 Press ISBN 1555580882, February 1992. 1021 [POSIX] ISO/IEC, 9945-1., "Information technology -- Portable 1022 Operating System Interface (POSIX)-Part 1: System 1023 Application Program Interface (API) C Language", 1024 ANSI/IEE Std 1003.1, July 1996. 1026 Author's Address 1028 Chris Lonvick (editor) 1029 Cisco Systems, Inc. 1030 12515 Research Blvd. 1031 Austin 78759 1032 USA 1034 Email: clonvick@cisco.com 1036 Intellectual Property Statement 1038 The IETF takes no position regarding the validity or scope of any 1039 Intellectual Property Rights or other rights that might be claimed to 1040 pertain to the implementation or use of the technology described in 1041 this document or the extent to which any license under such rights 1042 might or might not be available; nor does it represent that it has 1043 made any independent effort to identify any such rights. Information 1044 on the procedures with respect to rights in RFC documents can be 1045 found in BCP 78 and BCP 79. 1047 Copies of IPR disclosures made to the IETF Secretariat and any 1048 assurances of licenses to be made available, or the result of an 1049 attempt made to obtain a general license or permission for the use of 1050 such proprietary rights by implementers or users of this 1051 specification can be obtained from the IETF on-line IPR repository at 1052 http://www.ietf.org/ipr. 1054 The IETF invites any interested party to bring to its attention any 1055 copyrights, patents or patent applications, or other proprietary 1056 rights that may cover technology that may be required to implement 1057 this standard. Please address the information to the IETF at 1058 ietf-ipr@ietf.org. 1060 The IETF has been notified of intellectual property rights claimed in 1061 regard to some or all of the specification contained in this 1062 document. For more information consult the online list of claimed 1063 rights. 1065 Disclaimer of Validity 1067 This document and the information contained herein are provided on an 1068 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1069 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1070 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1071 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1072 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1073 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1075 Copyright Statement 1077 Copyright (C) The Internet Society (2005). This document is subject 1078 to the rights, licenses and restrictions contained in BCP 78, and 1079 except as set forth therein, the authors retain all their rights. 1081 Acknowledgment 1083 Funding for the RFC Editor function is currently provided by the 1084 Internet Society.