idnits 2.17.1 draft-ietf-secsh-connect-25.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 18. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1103. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1075. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1082. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1088. ** 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 146 has weird spacing: '... string dat...' == Line 163 has weird spacing: '... string req...' == Line 164 has weird spacing: '...boolean want...' == Line 216 has weird spacing: '... string cha...' == Line 251 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 (March 14, 2005) is 6973 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 1020, but no explicit reference was found in the text ** 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 (~~), 10 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Ylonen 3 Internet-Draft SSH Communications Security Corp 4 Expires: September 15, 2005 C. Lonvick, Ed. 5 Cisco Systems, Inc. 6 March 14, 2005 8 SSH Connection Protocol 9 draft-ietf-secsh-connect-25.txt 11 Status of this Memo 13 This document is an Internet-Draft and is subject to all provisions 14 of Section 3 of RFC 3667. By submitting this Internet-Draft, each 15 author represents that any applicable patent or other IPR claims of 16 which he or she is aware have been or will be disclosed, and any of 17 which he or she become aware will be disclosed, in accordance with 18 RFC 3668. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as 23 Internet-Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 This Internet-Draft will expire on September 15, 2005. 38 Copyright Notice 40 Copyright (C) The Internet Society (2005). 42 Abstract 44 SSH is a protocol for secure remote login and other secure network 45 services over an insecure network. 47 This document describes the SSH Connection Protocol. It provides 48 interactive login sessions, remote execution of commands, forwarded 49 TCP/IP connections, and forwarded X11 connections. All of these 50 channels are multiplexed into a single encrypted tunnel. 52 The SSH Connection Protocol has been designed to run on top of the 53 SSH transport layer and user authentication protocols. 55 Table of Contents 57 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 3. Conventions Used in This Document . . . . . . . . . . . . . . 3 60 4. Global Requests . . . . . . . . . . . . . . . . . . . . . . . 4 61 5. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . 5 62 5.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . 5 63 5.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . 7 64 5.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . 8 65 5.4 Channel-Specific Requests . . . . . . . . . . . . . . . . 9 66 6. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . 10 67 6.1 Opening a Session . . . . . . . . . . . . . . . . . . . . 10 68 6.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . 11 69 6.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . 11 70 6.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . 11 71 6.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . 12 72 6.4 Environment Variable Passing . . . . . . . . . . . . . . . 12 73 6.5 Starting a Shell or a Command . . . . . . . . . . . . . . 13 74 6.6 Session Data Transfer . . . . . . . . . . . . . . . . . . 14 75 6.7 Window Dimension Change Message . . . . . . . . . . . . . 14 76 6.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . 14 77 6.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . 15 78 6.10 Returning Exit Status . . . . . . . . . . . . . . . . . . 15 79 7. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . 16 80 7.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . 16 81 7.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . 18 82 8. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . 19 83 9. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 21 84 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 21 85 11. Security Considerations . . . . . . . . . . . . . . . . . . 21 86 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 87 12.1 Normative References . . . . . . . . . . . . . . . . . . . 22 88 12.2 Informative References . . . . . . . . . . . . . . . . . . 22 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 23 90 A. Trademark Notice . . . . . . . . . . . . . . . . . . . . . . . 23 91 Intellectual Property and Copyright Statements . . . . . . . . 24 93 1. Contributors 95 The major original contributors of this set of documents have been: 96 Tatu Ylonen, Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH 97 Communications Security Corp), and Markku-Juhani O. Saarinen 98 (University of Jyvaskyla). Darren Moffit was the original editor of 99 this set of documents and also made very substantial contributions. 101 Many people contributed to the development of this document over the 102 years. People who should be acknowledged include Mats Andersson, Ben 103 Harris, Brent McClure, Niels Moller, Damien Miller, Derek Fawcus, 104 Frank Cusack, Heikki Nousiainen, Jakob Schlyter, Jeff Van Dyke, 105 Jeffrey Altman, Jeffrey Hutzelman, Jon Bright, Joseph Galbraith, Ken 106 Hornstein, Markus Friedl, Martin Forssen, Nicolas Williams, Niels 107 Provos, Perry Metzger, Peter Gutmann, Simon Josefsson, Simon Tatham, 108 Wei Dai, Denis Bider, der Mouse, and Tadayoshi Kohno. Listing their 109 names here does not mean that they endorse this document, but that 110 they have contributed to it. 112 2. Introduction 114 The SSH Connection Protocol has been designed to run on top of the 115 SSH transport layer and user authentication protocols. It provides 116 interactive login sessions, remote execution of commands, forwarded 117 TCP/IP connections, and forwarded X11 connections. The service name 118 for this protocol is "ssh-connection". 120 This document should be read only after reading the SSH architecture 121 document [SSH-ARCH]. This document freely uses terminology and 122 notation from the architecture document without reference or further 123 explanation. 125 3. Conventions Used in This Document 127 All documents related to the SSH protocols shall use the keywords 128 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 129 "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" to describe 130 requirements. These keywords are to be interpreted as described in 131 [RFC2119]. 133 The keywords "PRIVATE USE", "HIERARCHICAL ALLOCATION", "FIRST COME 134 FIRST SERVED", "EXPERT REVIEW", "SPECIFICATION REQUIRED", "IESG 135 APPROVAL", "IETF CONSENSUS", and "STANDARDS ACTION" that appear in 136 this document when used to describe namespace allocation are to be 137 interpreted as described in [RFC2434]. 139 Protocol fields and possible values to fill them are defined in this 140 set of documents. Protocol fields will be defined in the message 141 definitions. As an example, SSH_MSG_CHANNEL_DATA is defined as 142 follows. 144 byte SSH_MSG_CHANNEL_DATA 145 uint32 recipient channel 146 string data 148 Throughout these documents, when the fields are referenced, they will 149 appear within single quotes. When values to fill those fields are 150 referenced, they will appear within double quotes. Using the above 151 example, possible values for 'data' are "foo" and "bar". 153 4. Global Requests 155 There are several kinds of requests that affect the state of the 156 remote end globally, independent of any channels. An example is a 157 request to start TCP/IP forwarding for a specific port. Note that 158 both client and server MAY send global requests at any time, and the 159 receiver MUST respond appropriately. All such requests use the 160 following format. 162 byte SSH_MSG_GLOBAL_REQUEST 163 string request name in US-ASCII only 164 boolean want reply 165 ... request-specific data follows 167 The value of 'request name' follows the DNS extensibility naming 168 convention outlined in [SSH-ARCH]. 170 The recipient will respond to this message with 171 SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if 'want reply' is 172 TRUE. 174 byte SSH_MSG_REQUEST_SUCCESS 175 ..... response specific data 177 Usually the 'response specific data' is non-existent. 179 If the recipient does not recognize or support the request, it simply 180 responds with SSH_MSG_REQUEST_FAILURE. 182 byte SSH_MSG_REQUEST_FAILURE 184 In general, the reply messages do not include request type 185 identifiers. To make it possible for the originator of a request to 186 identify to which request each reply refers, it is REQUIRED that 187 replies to SSH_MSG_GLOBAL_REQUESTS MUST be sent in the same order as 188 the corresponding request messages. For channel requests, replies 189 that relate to the same channel MUST also be replied to in the right 190 order. However, channel requests for distinct channels MAY be 191 replied to out-of-order. 193 5. Channel Mechanism 195 All terminal sessions, forwarded connections, etc., are channels. 196 Either side may open a channel. Multiple channels are multiplexed 197 into a single connection. 199 Channels are identified by numbers at each end. The number referring 200 to a channel may be different on each side. Requests to open a 201 channel contain the sender's channel number. Any other 202 channel-related messages contain the recipient's channel number for 203 the channel. 205 Channels are flow-controlled. No data may be sent to a channel until 206 a message is received to indicate that window space is available. 208 5.1 Opening a Channel 210 When either side wishes to open a new channel, it allocates a local 211 number for the channel. It then sends the following message to the 212 other side, and includes the local channel number and initial window 213 size in the message. 215 byte SSH_MSG_CHANNEL_OPEN 216 string channel type in US-ASCII only 217 uint32 sender channel 218 uint32 initial window size 219 uint32 maximum packet size 220 ... channel type specific data follows 222 The 'channel type' is a name as described in [SSH-ARCH] and 223 [SSH-NUMBERS], with similar extension mechanisms. The 'sender 224 channel' is a local identifier for the channel used by the sender of 225 this message. The 'initial window size' specifies how many bytes of 226 channel data can be sent to the sender of this message without 227 adjusting the window. The 'maximum packet size' specifies the 228 maximum size of an individual data packet that can be sent to the 229 sender. For example: one might want to use smaller packets for 230 interactive connections to get better interactive response on slow 231 links. 233 The remote side then decides whether it can open the channel, and 234 responds with either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or 235 SSH_MSG_CHANNEL_OPEN_FAILURE. 237 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 238 uint32 recipient channel 239 uint32 sender channel 240 uint32 initial window size 241 uint32 maximum packet size 242 ... 'channel type' specific data follows 244 The 'recipient channel' is the channel number given in the original 245 open request, and 'sender channel' is the channel number allocated by 246 the other side. 248 byte SSH_MSG_CHANNEL_OPEN_FAILURE 249 uint32 recipient channel 250 uint32 reason code 251 string description in ISO-10646 UTF-8 encoding [RFC3629] 252 string language tag as defined in [RFC3066] 254 If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support 255 the specified 'channel type', it simply responds with 256 SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the 'description' 257 string to the user. If this is done, the client software should take 258 the precautions discussed in [SSH-ARCH]. 260 The SSH_MSG_CHANNEL_OPEN_FAILURE 'reason code' values are defined in 261 the following table. Note that the values for the 'reason code' are 262 given in decimal format for readability but that they are actually 263 uint32 values. 265 Symbolic name reason code 266 ------------- ----------- 267 SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 268 SSH_OPEN_CONNECT_FAILED 2 269 SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 270 SSH_OPEN_RESOURCE_SHORTAGE 4 272 Requests for assignments of new SSH_MSG_CHANNEL_OPEN 'reason code' 273 values (and associated 'description' text) in the range of 0x00000005 274 to 0xFDFFFFFF MUST be done through the IETF CONSENSUS method as 275 described in [RFC2434]. The IANA will not assign Channel Connection 276 Failure 'reason code' values in the range of 0xFE000000 to 277 0xFFFFFFFF. Channel Connection Failure 'reason code' values in that 278 range are left for PRIVATE USE as described in [RFC2434]. 280 While it is understood that the IANA will have no control over the 281 range of 0xFE000000 to 0xFFFFFFFF, this range will be split in two 282 parts and administered by the following conventions. 284 o The range of 0xFE000000 to 0xFEFFFFFF is to be used in conjunction 285 with locally assigned channels. For example: if a channel is 286 proposed with a 'channel type' of "example_session@example.com" 287 but fails, then the response will contain either a 'reason code' 288 assigned by the IANA (as listed above and in the range of 289 0x00000001 to 0xFDFFFFFF), or with a locally assigned value in the 290 range of 0xFE000000 to 0xFEFFFFFF. Naturally, if the server does 291 not understand the proposed 'channel type', even if it is a 292 locally defined 'channel type', then the 'reason code' MUST be 293 0x00000003 as described above, if the 'reason code' is sent. If 294 the server does understand the 'channel type' but the channel 295 still fails to open, then the server SHOULD respond with a locally 296 assigned 'reason code' value consistent with the proposed, local 297 'channel type'. It is assumed that practitioners will first 298 attempt to use the IANA assigned 'reason code' values and then 299 document their locally assigned 'reason code' values. 301 o There are no restrictions or suggestions for the range starting 302 with 0xFF. No interoperability is expected for anything used in 303 this range. Essentially it is for experimentation. 305 5.2 Data Transfer 307 The window size specifies how many bytes the other party can send 308 before it must wait for the window to be adjusted. Both parties use 309 the following message to adjust the window. 311 byte SSH_MSG_CHANNEL_WINDOW_ADJUST 312 uint32 recipient channel 313 uint32 bytes to add 315 After receiving this message, the recipient MAY send the given number 316 of bytes more than it was previously allowed to send; the window size 317 is incremented. Implementations MUST correctly handle window sizes 318 of up to 2^32 - 1 bytes. The window MUST NOT be increased above 2^32 319 - 1 bytes. 321 Data transfer is done with messages of the following type. 323 byte SSH_MSG_CHANNEL_DATA 324 uint32 recipient channel 325 string data 327 The maximum amount of data allowed is the current window size. The 328 window size is decremented by the amount of data sent. Both parties 329 MAY ignore all extra data sent after the allowed window is empty. 331 Additionally, some channels can transfer several types of data. An 332 example of this is stderr data from interactive sessions. Such data 333 can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a 334 separate integer specifies the type of the data. The available types 335 and their interpretation depend on the type of the channel. 337 byte SSH_MSG_CHANNEL_EXTENDED_DATA 338 uint32 recipient_channel 339 uint32 data_type_code 340 string data 342 Data sent with these messages consumes the same window as ordinary 343 data. 345 Currently, only the following type is defined. Note that the value 346 for the 'data_type_code' is given in decimal format for readability 347 but that the values are actually uint32 values. 349 Symbolic name data_type_code 350 ------------- -------------- 351 SSH_EXTENDED_DATA_STDERR 1 353 Extended Channel Data Transfer 'data_type_code' values MUST be 354 assigned sequentially. Requests for assignments of new Extended 355 Channel Data Transfer 'data_type_code' values, and their associated 356 Extended Channel Data Transfer 'data' strings, in the range of 357 0x00000002 to 0xFDFFFFFF MUST be done through the IETF CONSENSUS 358 method as described in [RFC2434]. The IANA will not assign Extended 359 Channel Data Transfer 'data_type_code' values in the range of 360 0xFE000000 to 0xFFFFFFFF. Extended Channel Data Transfer 361 'data_type_code' values in that range are left for PRIVATE USE as 362 described in [RFC2434]. As is noted, the actual instructions to the 363 IANA are in [SSH-NUMBERS]. 365 5.3 Closing a Channel 367 When a party will no longer send more data to a channel, it SHOULD 368 send SSH_MSG_CHANNEL_EOF. 370 byte SSH_MSG_CHANNEL_EOF 371 uint32 recipient_channel 373 No explicit response is sent to this message. However, the 374 application may send EOF to whatever is at the other end of the 375 channel. Note that the channel remains open after this message, and 376 more data may still be sent in the other direction. This message 377 does not consume window space and can be sent even if no window space 378 is available. 380 When either party wishes to terminate the channel, it sends 381 SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST 382 send back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this 383 message for the channel. The channel is considered closed for a 384 party when it has both sent and received SSH_MSG_CHANNEL_CLOSE, and 385 the party may then reuse the channel number. A party MAY send 386 SSH_MSG_CHANNEL_CLOSE without having sent or received 387 SSH_MSG_CHANNEL_EOF. 389 byte SSH_MSG_CHANNEL_CLOSE 390 uint32 recipient_channel 392 This message does not consume window space and can be sent even if no 393 window space is available. 395 It is recommended that any data sent before this message is delivered 396 to the actual destination, if possible. 398 5.4 Channel-Specific Requests 400 Many 'channel type' values have extensions that are specific to that 401 particular 'channel type'. An example is requesting a pty (pseudo 402 terminal) for an interactive session. 404 All channel-specific requests use the following format. 406 byte SSH_MSG_CHANNEL_REQUEST 407 uint32 recipient channel 408 string request type in US-ASCII characters only 409 boolean want reply 410 ... type-specific data 412 If 'want reply' is FALSE, no response will be sent to the request. 413 Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS 414 or SSH_MSG_CHANNEL_FAILURE, or request-specific continuation 415 messages. If the request is not recognized or is not supported for 416 the channel, SSH_MSG_CHANNEL_FAILURE is returned. 418 This message does not consume window space and can be sent even if no 419 window space is available. The values of 'request type' are local to 420 each channel type. 422 The client is allowed to send further messages without waiting for 423 the response to the request. 425 'request type' names follow the DNS extensibility naming convention 426 outlined in [SSH-ARCH] and [SSH-NUMBERS]. 428 byte SSH_MSG_CHANNEL_SUCCESS 429 uint32 recipient_channel 431 byte SSH_MSG_CHANNEL_FAILURE 432 uint32 recipient_channel 434 These messages do not consume window space and can be sent even if no 435 window space is available. 437 6. Interactive Sessions 439 A session is a remote execution of a program. The program may be a 440 shell, an application, a system command, or some built-in subsystem. 441 It may or may not have a tty, and may or may not involve X11 442 forwarding. Multiple sessions can be active simultaneously. 444 6.1 Opening a Session 446 A session is started by sending the following message. 448 byte SSH_MSG_CHANNEL_OPEN 449 string "session" 450 uint32 sender channel 451 uint32 initial window size 452 uint32 maximum packet size 454 Client implementations SHOULD reject any session channel open 455 requests to make it more difficult for a corrupt server to attack the 456 client. 458 6.2 Requesting a Pseudo-Terminal 460 A pseudo-terminal can be allocated for the session by sending the 461 following message. 463 byte SSH_MSG_CHANNEL_REQUEST 464 uint32 recipient_channel 465 string "pty-req" 466 boolean want_reply 467 string TERM environment variable value (e.g., vt100) 468 uint32 terminal width, characters (e.g., 80) 469 uint32 terminal height, rows (e.g., 24) 470 uint32 terminal width, pixels (e.g., 640) 471 uint32 terminal height, pixels (e.g., 480) 472 string encoded terminal modes 474 The 'encoded terminal modes' are described in Section 8. Zero 475 dimension parameters MUST be ignored. The character/row dimensions 476 override the pixel dimensions (when nonzero). Pixel dimensions refer 477 to the drawable area of the window. 479 The dimension parameters are only informational. 481 The client SHOULD ignore pty requests. 483 6.3 X11 Forwarding 485 6.3.1 Requesting X11 Forwarding 487 X11 forwarding may be requested for a session by sending a 488 SSH_MSG_CHANNEL_REQUEST message. 490 byte SSH_MSG_CHANNEL_REQUEST 491 uint32 recipient channel 492 string "x11-req" 493 boolean want reply 494 boolean single connection 495 string x11 authentication protocol 496 string x11 authentication cookie 497 uint32 x11 screen number 499 It is RECOMMENDED that the 'x11 authentication cookie' that is sent 500 be a fake, random cookie, and that the cookie is checked and replaced 501 by the real cookie when a connection request is received. 503 X11 connection forwarding should stop when the session channel is 504 closed. However, already opened forwardings should not be 505 automatically closed when the session channel is closed. 507 If 'single connection' is TRUE, only a single connection should be 508 forwarded. No more connections will be forwarded after the first, or 509 after the session channel has been closed. 511 The 'x11 authentication protocol' is the name of the X11 512 authentication method used, e.g., "MIT-MAGIC-COOKIE-1". 514 The 'x11 authentication cookie' MUST be hexadecimal encoded. 516 The X Protocol is documented in [SCHEIFLER]. 518 6.3.2 X11 Channels 520 X11 channels are opened with a channel open request. The resulting 521 channels are independent of the session, and closing the session 522 channel does not close the forwarded X11 channels. 524 byte SSH_MSG_CHANNEL_OPEN 525 string "x11" 526 uint32 sender channel 527 uint32 initial window size 528 uint32 maximum packet size 529 string originator address (e.g., "192.168.7.38") 530 uint32 originator port 532 The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION 533 or SSH_MSG_CHANNEL_OPEN_FAILURE. 535 Implementations MUST reject any X11 channel open requests if they 536 have not requested X11 forwarding. 538 6.4 Environment Variable Passing 540 Environment variables may be passed to the shell/command to be 541 started later. Uncontrolled setting of environment variables in a 542 privileged process can be a security hazard. It is recommended that 543 implementations either maintain a list of allowable variable names or 544 only set environment variables after the server process has dropped 545 sufficient privileges. 547 byte SSH_MSG_CHANNEL_REQUEST 548 uint32 recipient channel 549 string "env" 550 boolean want reply 551 string variable name 552 string variable value 554 6.5 Starting a Shell or a Command 556 Once the session has been set up, a program is started at the remote 557 end. The program can be a shell, an application program or a 558 subsystem with a host-independent name. Only one of these requests 559 can succeed per channel. 561 byte SSH_MSG_CHANNEL_REQUEST 562 uint32 recipient channel 563 string "shell" 564 boolean want reply 566 This message will request the user's default shell (typically defined 567 in /etc/passwd in UNIX systems) to be started at the other end. 569 byte SSH_MSG_CHANNEL_REQUEST 570 uint32 recipient channel 571 string "exec" 572 boolean want reply 573 string command 575 This message will request the server to start the execution of the 576 given command. The 'command' string may contain a path. Normal 577 precautions MUST be taken to prevent the execution of unauthorized 578 commands. 580 byte SSH_MSG_CHANNEL_REQUEST 581 uint32 recipient channel 582 string "subsystem" 583 boolean want reply 584 string subsystem name 586 This last form executes a predefined subsystem. It is expected that 587 these will include a general file transfer mechanism, and possibly 588 other features. Implementations may also allow configuring more such 589 mechanisms. As the user's shell is usually used to execute the 590 subsystem, it is advisable for the subsystem protocol to have a 591 "magic cookie" at the beginning of the protocol transaction to 592 distinguish it from arbitrary output generated by shell 593 initialization scripts, etc. This spurious output from the shell may 594 be filtered out either at the server or at the client. 596 The server SHOULD NOT halt the execution of the protocol stack when 597 starting a shell or a program. All input and output from these 598 SHOULD be redirected to the channel or to the encrypted tunnel. 600 It is RECOMMENDED to request and check the reply for these messages. 601 The client SHOULD ignore these messages. 603 Subsystem names follow the DNS extensibility naming convention 604 outlined in [SSH-NUMBERS]. 606 6.6 Session Data Transfer 608 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 609 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The 610 extended data type SSH_EXTENDED_DATA_STDERR has been defined for 611 stderr data. 613 6.7 Window Dimension Change Message 615 When the window (terminal) size changes on the client side, it MAY 616 send a message to the other side to inform it of the new dimensions. 618 byte SSH_MSG_CHANNEL_REQUEST 619 uint32 recipient_channel 620 string "window-change" 621 boolean FALSE 622 uint32 terminal width, columns 623 uint32 terminal height, rows 624 uint32 terminal width, pixels 625 uint32 terminal height, pixels 627 A response SHOULD NOT be sent to this message. 629 6.8 Local Flow Control 631 On many systems, it is possible to determine if a pseudo-terminal is 632 using control-S/control-Q flow control. When flow control is 633 allowed, it is often desirable to do the flow control at the client 634 end to speed up responses to user requests. This is facilitated by 635 the following notification. Initially, the server is responsible for 636 flow control. (Here, again, client means the side originating the 637 session, and server means the other side.) 639 The message below is used by the server to inform the client when it 640 can or cannot perform flow control (control-S/control-Q processing). 641 If 'client can do' is TRUE, the client is allowed to do flow control 642 using control-S and control-Q. The client MAY ignore this message. 644 byte SSH_MSG_CHANNEL_REQUEST 645 uint32 recipient channel 646 string "xon-xoff" 647 boolean FALSE 648 boolean client can do 650 No response is sent to this message. 652 6.9 Signals 654 A signal can be delivered to the remote process/service using the 655 following message. Some systems may not implement signals, in which 656 case they SHOULD ignore this message. 658 byte SSH_MSG_CHANNEL_REQUEST 659 uint32 recipient channel 660 string "signal" 661 boolean FALSE 662 string signal name without the "SIG" prefix. 664 Signal names will be encoded as discussed in the "exit-signal" 665 SSH_MSG_CHANNEL_REQUEST. 667 6.10 Returning Exit Status 669 When the command running at the other end terminates, the following 670 message can be sent to return the exit status of the command. 671 Returning the status is RECOMMENDED. No acknowledgment is sent for 672 this message. The channel needs to be closed with 673 SSH_MSG_CHANNEL_CLOSE after this message. 675 The client MAY ignore these messages. 677 byte SSH_MSG_CHANNEL_REQUEST 678 uint32 recipient_channel 679 string "exit-status" 680 boolean FALSE 681 uint32 exit_status 683 The remote command may also terminate violently due to a signal. 684 Such a condition can be indicated by the following message. A zero 685 'exit_status' usually means that the command terminated successfully. 686 o byte SSH_MSG_CHANNEL_REQUEST 687 o uint32 recipient channel 688 o string "exit-signal" 689 o boolean FALSE 690 o string signal name without the "SIG" prefix. 691 o boolean core dumped 692 o string error message in ISO-10646 UTF-8 encoding 693 o string language tag as defined in [RFC3066] 694 The 'signal name' is one of the following (these are from [POSIX]) 696 ABRT 697 ALRM 698 FPE 699 HUP 700 ILL 701 INT 702 KILL 703 PIPE 704 QUIT 705 SEGV 706 TERM 707 USR1 708 USR2 710 Additional 'signal name' values MAY be sent in the format 711 "sig-name@xyz", where "sig-name" and "xyz" may be anything a 712 particular implementor wants (except the "@" sign). However, it is 713 suggested that if a 'configure' script is used, any non-standard 714 'signal name' values it finds be encoded as "SIG@xyz.config.guess", 715 where "SIG" is the 'signal name' without the "SIG" prefix, and "xyz" 716 be the host type, as determined by "config.guess". 718 The 'error message' contains an additional textual explanation of the 719 error message. The message may consist of multiple lines. The 720 client software MAY display this message to the user. If this is 721 done, the client software should take the precautions discussed in 722 [SSH-ARCH]. 724 7. TCP/IP Port Forwarding 726 7.1 Requesting Port Forwarding 728 A party need not explicitly request forwardings from its own end to 729 the other direction. However, if it wishes that connections to a 730 port on the other side be forwarded to the local side, it must 731 explicitly request this. 733 byte SSH_MSG_GLOBAL_REQUEST 734 string "tcpip-forward" 735 boolean want reply 736 string address to bind (e.g., "0.0.0.0") 737 uint32 port number to bind 739 The 'address to bind' and 'port number to bind' specify the IP 740 address or domain name and port to which the socket to be listened is 741 bound. Some strings used for the 'address to bind' have special-case 742 semantics. 744 o "" means that connections are to be accepted on all protocol 745 families supported by the SSH implementation. 747 o "0.0.0.0" means to listen on all IPv4 addresses. 749 o "::" means to listen on all IPv6 addresses. 751 o "localhost" means to listen on all protocol families supported by 752 the SSH implementation on loopback addresses only, [RFC3330] and 753 [RFC3513]. 755 o "127.0.0.1" and "::1" indicate listening on the loopback 756 interfaces for IPv4 and IPv6 respectively. 758 Note that the client can still filter connections based on 759 information passed in the open request. 761 Implementations should only allow forwarding privileged ports if the 762 user has been authenticated as a privileged user. 764 Client implementations SHOULD reject these messages; they are 765 normally only sent by the client. 767 If a client passes 0 as port number to bind and has 'want reply' TRUE 768 then the server allocates the next available unprivileged port number 769 and replies with the following message, otherwise there is no 770 response specific data. 772 byte SSH_MSG_REQUEST_SUCCESS 773 uint32 port that was bound on the server 775 A port forwarding can be canceled with the following message. Note 776 that channel open requests may be received until a reply to this 777 message is received. 779 byte SSH_MSG_GLOBAL_REQUEST 780 string "cancel-tcpip-forward" 781 boolean want reply 782 string address_to_bind (e.g., "127.0.0.1") 783 uint32 port number to bind 785 Client implementations SHOULD reject these messages; they are 786 normally only sent by the client. 788 7.2 TCP/IP Forwarding Channels 790 When a connection comes to a port for which remote forwarding has 791 been requested, a channel is opened to forward the port to the other 792 side. 794 byte SSH_MSG_CHANNEL_OPEN 795 string "forwarded-tcpip" 796 uint32 sender channel 797 uint32 initial window size 798 uint32 maximum packet size 799 string address that was connected 800 uint32 port that was connected 801 string originator IP address 802 uint32 originator port 804 Implementations MUST reject these messages unless they have 805 previously requested a remote TCP/IP port forwarding with the given 806 port number. 808 When a connection comes to a locally forwarded TCP/IP port, the 809 following packet is sent to the other side. Note that these messages 810 MAY be sent also for ports for which no forwarding has been 811 explicitly requested. The receiving side must decide whether to 812 allow the forwarding. 814 byte SSH_MSG_CHANNEL_OPEN 815 string "direct-tcpip" 816 uint32 sender channel 817 uint32 initial window size 818 uint32 maximum packet size 819 string host to connect 820 uint32 port to connect 821 string originator IP address 822 uint32 originator port 824 The 'host to connect' and 'port to connect' specify the TCP/IP host 825 and port where the recipient should connect the channel. The 'host 826 to connect' may be either a domain name or a numeric IP address. 828 The 'originator IP address' is the numeric IP address of the machine 829 where the connection request comes from, and the 'originator port' is 830 the port on the originator host from where the connection originated. 832 Forwarded TCP/IP channels are independent of any sessions, and 833 closing a session channel does not in any way imply that forwarded 834 connections should be closed. 836 Client implementations SHOULD reject direct TCP/IP open requests for 837 security reasons. 839 8. Encoding of Terminal Modes 841 All "encoded terminal modes" (as passed in a pty request) are encoded 842 into a byte stream. It is intended that the coding be portable 843 across different environments. 845 The tty mode description is a stream of bytes. The stream consists 846 of opcode-argument pairs where the opcode is a byte value. It is 847 terminated by opcode TTY_OP_END (0x00). Opcodes 1 to 159 have a 848 single uint32 argument. Opcodes 160 to 255 are not yet defined, and 849 cause parsing to stop (they should only be used after any other 850 data). 852 The client SHOULD put in the stream any modes it knows about, and the 853 server MAY ignore any modes it does not know about. This allows some 854 degree of machine-independence, at least between systems that use a 855 POSIX-like tty interface. The protocol can support other systems as 856 well, but the client may need to fill reasonable values for a number 857 of parameters so the server pty gets set to a reasonable mode (the 858 server leaves all unspecified mode bits in their default values, and 859 only some combinations make sense). 861 The naming of opcode values mostly follows the POSIX terminal mode 862 flags. The following opcode values have been defined. Note that the 863 values given below are in decimal format for readability but that 864 they are actually byte values. 866 opcode argument description 867 ------ -------- ----------- 868 0 TTY_OP_END Indicates end of options. 869 1 VINTR Interrupt character; 255 if none. Similarly 870 for the other characters. Not all of these 871 characters are supported on all systems. 872 2 VQUIT The quit character (sends SIGQUIT signal on 873 POSIX systems). 874 3 VERASE Erase the character to left of the cursor. 875 4 VKILL Kill the current input line. 876 5 VEOF End-of-file character (sends EOF from the 877 terminal). 878 6 VEOL End-of-line character in addition to 879 carriage return and/or linefeed. 880 7 VEOL2 Additional end-of-line character. 881 8 VSTART Continues paused output (normally 882 control-Q). 883 9 VSTOP Pauses output (normally control-S). 885 10 VSUSP Suspends the current program. 886 11 VDSUSP Another suspend character. 887 12 VREPRINT Reprints the current input line. 888 13 VWERASE Erases a word left of cursor. 889 14 VLNEXT Enter the next character typed literally, 890 even if it is a special character 891 15 VFLUSH Character to flush output. 892 16 VSWTCH Switch to a different shell layer. 893 17 VSTATUS Prints system status line (load, command, 894 pid, etc). 895 18 VDISCARD Toggles the flushing of terminal output. 896 30 IGNPAR The ignore parity flag. The parameter 897 SHOULD be 0 if this flag is FALSE, 898 and 1 if it is TRUE. 899 31 PARMRK Mark parity and framing errors. 900 32 INPCK Enable checking of parity errors. 901 33 ISTRIP Strip 8th bit off characters. 902 34 INLCR Map NL into CR on input. 903 35 IGNCR Ignore CR on input. 904 36 ICRNL Map CR to NL on input. 905 37 IUCLC Translate uppercase characters to 906 lowercase. 907 38 IXON Enable output flow control. 908 39 IXANY Any char will restart after stop. 909 40 IXOFF Enable input flow control. 910 41 IMAXBEL Ring bell on input queue full. 911 50 ISIG Enable signals INTR, QUIT, [D]SUSP. 912 51 ICANON Canonicalize input lines. 913 52 XCASE Enable input and output of uppercase 914 characters by preceding their lowercase 915 equivalents with "\". 916 53 ECHO Enable echoing. 917 54 ECHOE Visually erase chars. 918 55 ECHOK Kill character discards current line. 919 56 ECHONL Echo NL even if ECHO is off. 920 57 NOFLSH Don't flush after interrupt. 921 58 TOSTOP Stop background jobs from output. 922 59 IEXTEN Enable extensions. 923 60 ECHOCTL Echo control characters as ^(Char). 924 61 ECHOKE Visual erase for line kill. 925 62 PENDIN Retype pending input. 926 70 OPOST Enable output processing. 927 71 OLCUC Convert lowercase to uppercase. 928 72 ONLCR Map NL to CR-NL. 929 73 OCRNL Translate carriage return to newline 930 (output). 931 74 ONOCR Translate newline to carriage 932 return-newline (output). 934 75 ONLRET Newline performs a carriage return 935 (output). 936 90 CS7 7 bit mode. 937 91 CS8 8 bit mode. 938 92 PARENB Parity enable. 939 93 PARODD Odd parity, else even. 941 128 TTY_OP_ISPEED Specifies the input baud rate in 942 bits per second. 943 129 TTY_OP_OSPEED Specifies the output baud rate in 944 bits per second. 946 9. Summary of Message Numbers 948 The following is a summary of messages and their associated message 949 number. 951 SSH_MSG_GLOBAL_REQUEST 80 952 SSH_MSG_REQUEST_SUCCESS 81 953 SSH_MSG_REQUEST_FAILURE 82 954 SSH_MSG_CHANNEL_OPEN 90 955 SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 956 SSH_MSG_CHANNEL_OPEN_FAILURE 92 957 SSH_MSG_CHANNEL_WINDOW_ADJUST 93 958 SSH_MSG_CHANNEL_DATA 94 959 SSH_MSG_CHANNEL_EXTENDED_DATA 95 960 SSH_MSG_CHANNEL_EOF 96 961 SSH_MSG_CHANNEL_CLOSE 97 962 SSH_MSG_CHANNEL_REQUEST 98 963 SSH_MSG_CHANNEL_SUCCESS 99 964 SSH_MSG_CHANNEL_FAILURE 100 966 10. IANA Considerations 968 This document is part of a set. The IANA considerations for the SSH 969 protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], and 970 this document, are detailed in [SSH-NUMBERS]. 972 11. Security Considerations 974 This protocol is assumed to run on top of a secure, authenticated 975 transport. User authentication and protection against network-level 976 attacks are assumed to be provided by the underlying protocols. 978 Full security considerations for this protocol are provided in 980 [SSH-ARCH]. Specific to this document, it is RECOMMENDED that 981 implementations disable all the potentially dangerous features (e.g., 982 agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host 983 key has changed without notice or explanation. 985 12. References 987 12.1 Normative References 989 [SSH-ARCH] 990 Lonvick, C., "SSH Protocol Architecture", 991 I-D draft-ietf-secsh-architecture-22.txt, March 2005. 993 [SSH-TRANS] 994 Lonvick, C., "SSH Transport Layer Protocol", 995 I-D draft-ietf-secsh-transport-24.txt, March 2005. 997 [SSH-USERAUTH] 998 Lonvick, C., "SSH Authentication Protocol", 999 I-D draft-ietf-secsh-userauth-27.txt, March 2005. 1001 [SSH-NUMBERS] 1002 Lonvick, C., "SSH Protocol Assigned Numbers", 1003 I-D draft-ietf-secsh-assignednumbers-12.txt, March 2005. 1005 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1006 Requirement Levels", BCP 14, RFC 2119, March 1997. 1008 [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1009 IANA Considerations Section in RFCs", BCP 26, RFC 2434, 1010 October 1998. 1012 [RFC3066] Alvestrand, H., "Tags for the Identification of 1013 Languages", BCP 47, RFC 3066, January 2001. 1015 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1016 10646", STD 63, RFC 3629, November 2003. 1018 12.2 Informative References 1020 [RFC1884] Hinden, R. and S. Deering, "IP Version 6 Addressing 1021 Architecture", RFC 1884, December 1995. 1023 [RFC3330] IANA, "Special-Use IPv4 Addresses", RFC 3330, September 1024 2002. 1026 [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version 6 1027 (IPv6) Addressing Architecture", RFC 3513, April 2003. 1029 [SCHEIFLER] 1030 Scheifler, R., "X Window System : The Complete Reference 1031 to Xlib, X Protocol, Icccm, Xlfd, 3rd edition.", Digital 1032 Press ISBN 1555580882, February 1992. 1034 [POSIX] ISO/IEC, 9945-1., "Information technology -- Portable 1035 Operating System Interface (POSIX)-Part 1: System 1036 Application Program Interface (API) C Language", 1037 ANSI/IEE Std 1003.1, July 1996. 1039 Authors' Addresses 1041 Tatu Ylonen 1042 SSH Communications Security Corp 1043 Fredrikinkatu 42 1044 HELSINKI FIN-00100 1045 Finland 1047 Email: ylo@ssh.com 1049 Chris Lonvick (editor) 1050 Cisco Systems, Inc. 1051 12515 Research Blvd. 1052 Austin 78759 1053 USA 1055 Email: clonvick@cisco.com 1057 Appendix A. Trademark Notice 1059 "ssh" is a registered trademark in the United States and/or other 1060 countries. 1062 Note to the RFC Editor: This should be a separate section like the 1063 subsequent ones, and not an appendix. This paragraph to be removed 1064 before publication. 1066 Intellectual Property Statement 1068 The IETF takes no position regarding the validity or scope of any 1069 Intellectual Property Rights or other rights that might be claimed to 1070 pertain to the implementation or use of the technology described in 1071 this document or the extent to which any license under such rights 1072 might or might not be available; nor does it represent that it has 1073 made any independent effort to identify any such rights. Information 1074 on the procedures with respect to rights in RFC documents can be 1075 found in BCP 78 and BCP 79. 1077 Copies of IPR disclosures made to the IETF Secretariat and any 1078 assurances of licenses to be made available, or the result of an 1079 attempt made to obtain a general license or permission for the use of 1080 such proprietary rights by implementers or users of this 1081 specification can be obtained from the IETF on-line IPR repository at 1082 http://www.ietf.org/ipr. 1084 The IETF invites any interested party to bring to its attention any 1085 copyrights, patents or patent applications, or other proprietary 1086 rights that may cover technology that may be required to implement 1087 this standard. Please address the information to the IETF at 1088 ietf-ipr@ietf.org. 1090 The IETF has been notified of intellectual property rights claimed in 1091 regard to some or all of the specification contained in this 1092 document. For more information consult the online list of claimed 1093 rights. 1095 Disclaimer of Validity 1097 This document and the information contained herein are provided on an 1098 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1099 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1100 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1101 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1102 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1103 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1105 Copyright Statement 1107 Copyright (C) The Internet Society (2005). This document is subject 1108 to the rights, licenses and restrictions contained in BCP 78, and 1109 except as set forth therein, the authors retain all their rights. 1111 Acknowledgment 1113 Funding for the RFC Editor function is currently provided by the 1114 Internet Society.