idnits 2.17.1 draft-ietf-secsh-connect-19.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 6 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 138 has weird spacing: '... string req...' == Line 139 has weird spacing: '...boolean want...' == Line 182 has weird spacing: '... string cha...' == Line 213 has weird spacing: '... string add...' == Line 215 has weird spacing: '... string lan...' == (33 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). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: The server SHOULD not halt the execution of the protocol stack when starting a shell or a program. All input and output from these SHOULD be redirected to the channel or to the encrypted tunnel. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 2, 2004) is 7268 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC1884' is defined on line 881, but no explicit reference was found in the text -- No information found for draft-ietf-architecture - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SSH-ARCH' -- No information found for draft-ietf-transport - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SSH-TRANS' -- No information found for draft-ietf-userauth - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SSH-USERAUTH' -- No information found for draft-ietf-assignednumbers - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SSH-NUMBERS' -- Obsolete informational reference (is this intentional?): RFC 1884 (Obsoleted by RFC 2373) -- Obsolete informational reference (is this intentional?): RFC 2279 (Obsoleted by RFC 3629) -- Obsolete informational reference (is this intentional?): RFC 3066 (Obsoleted by RFC 4646, RFC 4647) Summary: 2 errors (**), 0 flaws (~~), 11 warnings (==), 14 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: December 1, 2004 C. Lonvick, Ed. 5 Cisco Systems, Inc 6 June 2, 2004 8 SSH Connection Protocol 9 draft-ietf-secsh-connect-19.txt 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as 19 Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on December 1, 2004. 34 Copyright Notice 36 Copyright (C) The Internet Society (2004). All Rights Reserved. 38 Abstract 40 SSH is a protocol for secure remote login and other secure network 41 services over an insecure network. 43 This document describes the SSH Connection Protocol. It provides 44 interactive login sessions, remote execution of commands, forwarded 45 TCP/IP connections, and forwarded X11 connections. All of these 46 channels are multiplexed into a single encrypted tunnel. 48 The SSH Connection Protocol has been designed to run on top of the 49 SSH transport layer and user authentication protocols. 51 Table of Contents 53 1. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. Conventions Used in This Document . . . . . . . . . . . . . . 3 56 4. Global Requests . . . . . . . . . . . . . . . . . . . . . . . 3 57 5. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . 4 58 5.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . 4 59 5.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . 6 60 5.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . 6 61 5.4 Channel-Specific Requests . . . . . . . . . . . . . . . . 7 62 6. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . 8 63 6.1 Opening a Session . . . . . . . . . . . . . . . . . . . . 8 64 6.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . 8 65 6.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . 9 66 6.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . 9 67 6.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . 10 68 6.4 Environment Variable Passing . . . . . . . . . . . . . . . 10 69 6.5 Starting a Shell or a Command . . . . . . . . . . . . . . 10 70 6.6 Session Data Transfer . . . . . . . . . . . . . . . . . . 11 71 6.7 Window Dimension Change Message . . . . . . . . . . . . . 12 72 6.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . 12 73 6.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . 12 74 6.10 Returning Exit Status . . . . . . . . . . . . . . . . . . 13 75 7. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . 14 76 7.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . 14 77 7.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . 15 78 8. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . 16 79 9. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 18 80 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 18 81 11. Security Considerations . . . . . . . . . . . . . . . . . . 18 82 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 83 12.1 Normative References . . . . . . . . . . . . . . . . . . . . 19 84 12.2 Informative References . . . . . . . . . . . . . . . . . . . 19 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 20 86 Intellectual Property and Copyright Statements . . . . . . . . 21 88 1. Contributors 90 The major original contributors of this document were: Tatu Ylonen, 91 Tero Kivinen, Timo J. Rinne, Sami Lehtinen (all of SSH 92 Communications Security Corp), and Markku-Juhani O. Saarinen 93 (University of Jyvaskyla). Darren Moffit was the original editor of 94 this document and also made very substantial contributions. 96 Additional contributors to this document include [need list]. 97 Listing their names here does not mean that they endorse this 98 document, but that they have contributed to it. 100 Comments on this internet draft should be sent to the IETF SECSH 101 working group, details at: 102 http://ietf.org/html.charters/secsh-charter.html Note: This paragraph 103 will be removed before this document progresses to become an RFC. 105 2. Introduction 107 The SSH Connection Protocol has been designed to run on top of the 108 SSH transport layer and user authentication protocols. It provides 109 interactive login sessions, remote execution of commands, forwarded 110 TCP/IP connections, and forwarded X11 connections. The service name 111 for this protocol is "ssh-connection". 113 This document should be read only after reading the SSH architecture 114 document [SSH-ARCH]. This document freely uses terminology and 115 notation from the architecture document without reference or further 116 explanation. 118 3. Conventions Used in This Document 120 The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", 121 and "MAY" that appear in this document are to be interpreted as 122 described in [RFC2119]. 124 The used data types and terminology are specified in the architecture 125 document [SSH-ARCH]. 127 The architecture document also discusses the algorithm naming 128 conventions that MUST be used with the SSH protocols. 130 4. Global Requests 132 There are several kinds of requests that affect the state of the 133 remote end "globally", independent of any channels. An example is a 134 request to start TCP/IP forwarding for a specific port. All such 135 requests use the following format. 137 byte SSH_MSG_GLOBAL_REQUEST 138 string request name in US-ASCII only 139 boolean want reply 140 ... request-specific data follows 142 Request names follow the DNS extensibility naming convention outlined 143 in [SSH-ARCH]. 145 The recipient will respond to this message with 146 SSH_MSG_REQUEST_SUCCESS or SSH_MSG_REQUEST_FAILURE if `want reply' is 147 TRUE. 149 byte SSH_MSG_REQUEST_SUCCESS 150 ..... response specific data 152 Usually the response specific data is non-existent. 154 If the recipient does not recognize or support the request, it simply 155 responds with SSH_MSG_REQUEST_FAILURE. 157 byte SSH_MSG_REQUEST_FAILURE 159 5. Channel Mechanism 161 All terminal sessions, forwarded connections, etc. are channels. 162 Either side may open a channel. Multiple channels are multiplexed 163 into a single connection. 165 Channels are identified by numbers at each end. The number referring 166 to a channel may be different on each side. Requests to open a 167 channel contain the sender's channel number. Any other 168 channel-related messages contain the recipient's channel number for 169 the channel. 171 Channels are flow-controlled. No data may be sent to a channel until 172 a message is received to indicate that window space is available. 174 5.1 Opening a Channel 176 When either side wishes to open a new channel, it allocates a local 177 number for the channel. It then sends the following message to the 178 other side, and includes the local channel number and initial window 179 size in the message. 181 byte SSH_MSG_CHANNEL_OPEN 182 string channel type in US-ASCII only 183 uint32 sender channel 184 uint32 initial window size 185 uint32 maximum packet size 186 ... channel type specific data follows 188 The channel type is a name as described in the SSH architecture 189 document, with similar extension mechanisms. `sender channel' is a 190 local identifier for the channel used by the sender of this message. 191 `initial window size' specifies how many bytes of channel data can be 192 sent to the sender of this message without adjusting the window. 193 `Maximum packet size' specifies the maximum size of an individual 194 data packet that can be sent to the sender (for example, one might 195 want to use smaller packets for interactive connections to get better 196 interactive response on slow links). 198 The remote side then decides whether it can open the channel, and 199 responds with either 200 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 201 uint32 recipient channel 202 uint32 sender channel 203 uint32 initial window size 204 uint32 maximum packet size 205 ... channel type specific data follows 207 where `recipient channel' is the channel number given in the original 208 open request, and `sender channel' is the channel number allocated by 209 the other side, or 210 byte SSH_MSG_CHANNEL_OPEN_FAILURE 211 uint32 recipient channel 212 uint32 reason code 213 string additional textual information in ISO-10646 UTF-8 214 encoding [RFC2279] 215 string language tag as defined in [RFC3066] 217 If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support 218 the specified channel type, it simply responds with 219 SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional 220 information to the user. If this is done, the client software should 221 take the precautions discussed in [SSH-ARCH]. 223 The following reason codes are defined: 225 #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 226 #define SSH_OPEN_CONNECT_FAILED 2 227 #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 228 #define SSH_OPEN_RESOURCE_SHORTAGE 4 230 5.2 Data Transfer 232 The window size specifies how many bytes the other party can send 233 before it must wait for the window to be adjusted. Both parties use 234 the following message to adjust the window. 236 byte SSH_MSG_CHANNEL_WINDOW_ADJUST 237 uint32 recipient channel 238 uint32 bytes to add 240 After receiving this message, the recipient MAY send the given number 241 of bytes more than it was previously allowed to send; the window size 242 is incremented. 244 Data transfer is done with messages of the following type. 246 byte SSH_MSG_CHANNEL_DATA 247 uint32 recipient channel 248 string data 250 The maximum amount of data allowed is the current window size. The 251 window size is decremented by the amount of data sent. Both parties 252 MAY ignore all extra data sent after the allowed window is empty. 254 Additionally, some channels can transfer several types of data. An 255 example of this is stderr data from interactive sessions. Such data 256 can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a 257 separate integer specifies the type of the data. The available types 258 and their interpretation depend on the type of the channel. 260 byte SSH_MSG_CHANNEL_EXTENDED_DATA 261 uint32 recipient_channel 262 uint32 data_type_code 263 string data 265 Data sent with these messages consumes the same window as ordinary 266 data. 268 Currently, only the following type is defined. 270 #define SSH_EXTENDED_DATA_STDERR 1 272 5.3 Closing a Channel 274 When a party will no longer send more data to a channel, it SHOULD 275 send SSH_MSG_CHANNEL_EOF. 277 byte SSH_MSG_CHANNEL_EOF 278 uint32 recipient_channel 280 No explicit response is sent to this message; however, the 281 application may send EOF to whatever is at the other end of the 282 channel. Note that the channel remains open after this message, and 283 more data may still be sent in the other direction. This message 284 does not consume window space and can be sent even if no window space 285 is available. 287 When either party wishes to terminate the channel, it sends 288 SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST 289 send back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this 290 message for the channel. The channel is considered closed for a 291 party when it has both sent and received SSH_MSG_CHANNEL_CLOSE, and 292 the party may then reuse the channel number. A party MAY send 293 SSH_MSG_CHANNEL_CLOSE without having sent or received 294 SSH_MSG_CHANNEL_EOF. 296 byte SSH_MSG_CHANNEL_CLOSE 297 uint32 recipient_channel 299 This message does not consume window space and can be sent even if no 300 window space is available. 302 It is recommended that any data sent before this message is delivered 303 to the actual destination, if possible. 305 5.4 Channel-Specific Requests 307 Many channel types have extensions that are specific to that 308 particular channel type. An example is requesting a pty (pseudo 309 terminal) for an interactive session. 311 All channel-specific requests use the following format. 313 byte SSH_MSG_CHANNEL_REQUEST 314 uint32 recipient channel 315 string request type in US-ASCII characters only 316 boolean want reply 317 ... type-specific data 319 If want reply is FALSE, no response will be sent to the request. 320 Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS 321 or SSH_MSG_CHANNEL_FAILURE, or request-specific continuation 322 messages. If the request is not recognized or is not supported for 323 the channel, SSH_MSG_CHANNEL_FAILURE is returned. 325 This message does not consume window space and can be sent even if no 326 window space is available. Request types are local to each channel 327 type. 329 The client is allowed to send further messages without waiting for 330 the response to the request. 332 request type names follow the DNS extensibility naming convention 333 outlined in [SSH-ARCH] 335 byte SSH_MSG_CHANNEL_SUCCESS 336 uint32 recipient_channel 338 byte SSH_MSG_CHANNEL_FAILURE 339 uint32 recipient_channel 341 These messages do not consume window space and can be sent even if no 342 window space is available. 344 6. Interactive Sessions 346 A session is a remote execution of a program. The program may be a 347 shell, an application, a system command, or some built-in subsystem. 348 It may or may not have a tty, and may or may not involve X11 349 forwarding. Multiple sessions can be active simultaneously. 351 6.1 Opening a Session 353 A session is started by sending the following message. 355 byte SSH_MSG_CHANNEL_OPEN 356 string "session" 357 uint32 sender channel 358 uint32 initial window size 359 uint32 maximum packet size 361 Client implementations SHOULD reject any session channel open 362 requests to make it more difficult for a corrupt server to attack the 363 client. 365 6.2 Requesting a Pseudo-Terminal 367 A pseudo-terminal can be allocated for the session by sending the 368 following message. 370 byte SSH_MSG_CHANNEL_REQUEST 371 uint32 recipient_channel 372 string "pty-req" 373 boolean want_reply 374 string TERM environment variable value (e.g., vt100) 375 uint32 terminal width, characters (e.g., 80) 376 uint32 terminal height, rows (e.g., 24) 377 uint32 terminal width, pixels (e.g., 640) 378 uint32 terminal height, pixels (e.g., 480) 379 string encoded terminal modes 381 The encoding of terminal modes is described in Section Encoding of 382 Terminal Modes (Section 8). Zero dimension parameters MUST be 383 ignored. The character/row dimensions override the pixel dimensions 384 (when nonzero). Pixel dimensions refer to the drawable area of the 385 window. 387 The dimension parameters are only informational. 389 The client SHOULD ignore pty requests. 391 6.3 X11 Forwarding 393 6.3.1 Requesting X11 Forwarding 395 X11 forwarding may be requested for a session by sending 397 byte SSH_MSG_CHANNEL_REQUEST 398 uint32 recipient channel 399 string "x11-req" 400 boolean want reply 401 boolean single connection 402 string x11 authentication protocol 403 string x11 authentication cookie 404 uint32 x11 screen number 406 It is recommended that the authentication cookie that is sent be a 407 fake, random cookie, and that the cookie is checked and replaced by 408 the real cookie when a connection request is received. 410 X11 connection forwarding should stop when the session channel is 411 closed; however, already opened forwardings should not be 412 automatically closed when the session channel is closed. 414 If `single connection' is TRUE, only a single connection should be 415 forwarded. No more connections will be forwarded after the first, or 416 after the session channel has been closed. 418 The "x11 authentication protocol" is the name of the X11 419 authentication method used, e.g. "MIT-MAGIC-COOKIE-1". 421 The x11 authentication cookie MUST be hexadecimal encoded. 423 X Protocol is documented in [SCHEIFLER]. 425 6.3.2 X11 Channels 427 X11 channels are opened with a channel open request. The resulting 428 channels are independent of the session, and closing the session 429 channel does not close the forwarded X11 channels. 431 byte SSH_MSG_CHANNEL_OPEN 432 string "x11" 433 uint32 sender channel 434 uint32 initial window size 435 uint32 maximum packet size 436 string originator address (e.g. "192.168.7.38") 437 uint32 originator port 439 The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION 440 or SSH_MSG_CHANNEL_OPEN_FAILURE. 442 Implementations MUST reject any X11 channel open requests if they 443 have not requested X11 forwarding. 445 6.4 Environment Variable Passing 447 Environment variables may be passed to the shell/command to be 448 started later. Uncontrolled setting of environment variables in a 449 privileged process can be a security hazard. It is recommended that 450 implementations either maintain a list of allowable variable names or 451 only set environment variables after the server process has dropped 452 sufficient privileges. 454 byte SSH_MSG_CHANNEL_REQUEST 455 uint32 recipient channel 456 string "env" 457 boolean want reply 458 string variable name 459 string variable value 461 6.5 Starting a Shell or a Command 463 Once the session has been set up, a program is started at the remote 464 end. The program can be a shell, an application program or a 465 subsystem with a host-independent name. Only one of these requests 466 can succeed per channel. 468 byte SSH_MSG_CHANNEL_REQUEST 469 uint32 recipient channel 470 string "shell" 471 boolean want reply 473 This message will request the user's default shell (typically defined 474 in /etc/passwd in UNIX systems) to be started at the other end. 476 byte SSH_MSG_CHANNEL_REQUEST 477 uint32 recipient channel 478 string "exec" 479 boolean want reply 480 string command 482 This message will request the server to start the execution of the 483 given command. The command string may contain a path. Normal 484 precautions MUST be taken to prevent the execution of unauthorized 485 commands. 487 byte SSH_MSG_CHANNEL_REQUEST 488 uint32 recipient channel 489 string "subsystem" 490 boolean want reply 491 string subsystem name 493 This last form executes a predefined subsystem. It is expected that 494 these will include a general file transfer mechanism, and possibly 495 other features. Implementations may also allow configuring more such 496 mechanisms. As the user's shell is usually used to execute the 497 subsystem, it is advisable for the subsystem protocol to have a 498 "magic cookie" at the beginning of the protocol transaction to 499 distinguish it from arbitrary output generated by shell 500 initialization scripts etc. This spurious output from the shell may 501 be filtered out either at the server or at the client. 503 The server SHOULD not halt the execution of the protocol stack when 504 starting a shell or a program. All input and output from these 505 SHOULD be redirected to the channel or to the encrypted tunnel. 507 It is RECOMMENDED to request and check the reply for these messages. 508 The client SHOULD ignore these messages. 510 Subsystem names follow the DNS extensibility naming convention 511 outlined in [SSH-ARCH]. 513 6.6 Session Data Transfer 515 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 516 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The 517 extended data type SSH_EXTENDED_DATA_STDERR has been defined for 518 stderr data. 520 6.7 Window Dimension Change Message 522 When the window (terminal) size changes on the client side, it MAY 523 send a message to the other side to inform it of the new dimensions. 525 byte SSH_MSG_CHANNEL_REQUEST 526 uint32 recipient_channel 527 string "window-change" 528 boolean FALSE 529 uint32 terminal width, columns 530 uint32 terminal height, rows 531 uint32 terminal width, pixels 532 uint32 terminal height, pixels 534 No response SHOULD be sent to this message. 536 6.8 Local Flow Control 538 On many systems, it is possible to determine if a pseudo-terminal is 539 using control-S/control-Q flow control. When flow control is 540 allowed, it is often desirable to do the flow control at the client 541 end to speed up responses to user requests. This is facilitated by 542 the following notification. Initially, the server is responsible for 543 flow control. (Here, again, client means the side originating the 544 session, and server means the other side.) 546 The message below is used by the server to inform the client when it 547 can or cannot perform flow control (control-S/control-Q processing). 548 If `client can do' is TRUE, the client is allowed to do flow control 549 using control-S and control-Q. The client MAY ignore this message. 551 byte SSH_MSG_CHANNEL_REQUEST 552 uint32 recipient channel 553 string "xon-xoff" 554 boolean FALSE 555 boolean client can do 557 No response is sent to this message. 559 6.9 Signals 561 A signal can be delivered to the remote process/service using the 562 following message. Some systems may not implement signals, in which 563 case they SHOULD ignore this message. 565 byte SSH_MSG_CHANNEL_REQUEST 566 uint32 recipient channel 567 string "signal" 568 boolean FALSE 569 string signal name without the "SIG" prefix. 571 Signal names will be encoded as discussed in the "exit-signal" 572 SSH_MSG_CHANNEL_REQUEST. 574 6.10 Returning Exit Status 576 When the command running at the other end terminates, the following 577 message can be sent to return the exit status of the command. 578 Returning the status is RECOMMENDED. No acknowledgment is sent for 579 this message. The channel needs to be closed with 580 SSH_MSG_CHANNEL_CLOSE after this message. 582 The client MAY ignore these messages. 584 byte SSH_MSG_CHANNEL_REQUEST 585 uint32 recipient_channel 586 string "exit-status" 587 boolean FALSE 588 uint32 exit_status 590 The remote command may also terminate violently due to a signal. 591 Such a condition can be indicated by the following message. A zero 592 exit_status usually means that the command terminated successfully. 593 byte SSH_MSG_CHANNEL_REQUEST 594 uint32 recipient channel 595 string "exit-signal" 596 boolean FALSE 597 string signal name without the "SIG" prefix. 598 boolean core dumped 599 string error message in ISO-10646 UTF-8 encoding 600 string language tag as defined in [RFC3066] 602 The signal name is one of the following (these are from [POSIX]) 604 ABRT 605 ALRM 606 FPE 607 HUP 608 ILL 609 INT 610 KILL 611 PIPE 612 QUIT 613 SEGV 614 TERM 615 USR1 616 USR2 618 Additional signal names MAY be sent in the format "sig-name@xyz", 619 where `sig-name' and `xyz' may be anything a particular implementor 620 wants (except the `@' sign). However, it is suggested that if a 621 `configure' script is used, the non-standard signal names it finds be 622 encoded as "SIG@xyz.config.guess", where `SIG' is the signal name 623 without the "SIG" prefix, and `xyz' be the host type, as determined 624 by `config.guess'. 626 The `error message' contains an additional explanation of the error 627 message. The message may consist of multiple lines. The client 628 software MAY display this message to the user. If this is done, the 629 client software should take the precautions discussed in [SSH-ARCH]. 631 7. TCP/IP Port Forwarding 633 7.1 Requesting Port Forwarding 635 A party need not explicitly request forwardings from its own end to 636 the other direction. However, if it wishes that connections to a 637 port on the other side be forwarded to the local side, it must 638 explicitly request this. 640 byte SSH_MSG_GLOBAL_REQUEST 641 string "tcpip-forward" 642 boolean want reply 643 string address to bind (e.g. "0.0.0.0") 644 uint32 port number to bind 646 `Address to bind' and `port number to bind' specify the IP address 647 and port to which the socket to be listened is bound. The address 648 should be "0.0.0.0" if connections are allowed from anywhere. (Note 649 that the client can still filter connections based on information 650 passed in the open request.) 652 Implementations should only allow forwarding privileged ports if the 653 user has been authenticated as a privileged user. 655 Client implementations SHOULD reject these messages; they are 656 normally only sent by the client. 658 If a client passes 0 as port number to bind and has want reply TRUE 659 then the server allocates the next available unprivileged port number 660 and replies with the following message, otherwise there is no 661 response specific data. 663 byte SSH_MSG_GLOBAL_REQUEST_SUCCESS 664 uint32 port that was bound on the server 666 A port forwarding can be canceled with the following message. Note 667 that channel open requests may be received until a reply to this 668 message is received. 670 byte SSH_MSG_GLOBAL_REQUEST 671 string "cancel-tcpip-forward" 672 boolean want reply 673 string address_to_bind (e.g. "127.0.0.1") 674 uint32 port number to bind 676 Client implementations SHOULD reject these messages; they are 677 normally only sent by the client. 679 7.2 TCP/IP Forwarding Channels 681 When a connection comes to a port for which remote forwarding has 682 been requested, a channel is opened to forward the port to the other 683 side. 685 byte SSH_MSG_CHANNEL_OPEN 686 string "forwarded-tcpip" 687 uint32 sender channel 688 uint32 initial window size 689 uint32 maximum packet size 690 string address that was connected 691 uint32 port that was connected 692 string originator IP address 693 uint32 originator port 695 Implementations MUST reject these messages unless they have 696 previously requested a remote TCP/IP port forwarding with the given 697 port number. 699 When a connection comes to a locally forwarded TCP/IP port, the 700 following packet is sent to the other side. Note that these messages 701 MAY be sent also for ports for which no forwarding has been 702 explicitly requested. The receiving side must decide whether to 703 allow the forwarding. 705 byte SSH_MSG_CHANNEL_OPEN 706 string "direct-tcpip" 707 uint32 sender channel 708 uint32 initial window size 709 uint32 maximum packet size 710 string host to connect 711 uint32 port to connect 712 string originator IP address 713 uint32 originator port 715 `Host to connect' and `port to connect' specify the TCP/IP host and 716 port where the recipient should connect the channel. `Host to 717 connect' may be either a domain name or a numeric IP address. 719 `Originator IP address' is the numeric IP address of the machine 720 where the connection request comes from, and `originator port' is the 721 port on the originator host from where the connection came from. 723 Forwarded TCP/IP channels are independent of any sessions, and 724 closing a session channel does not in any way imply that forwarded 725 connections should be closed. 727 Client implementations SHOULD reject direct TCP/IP open requests for 728 security reasons. 730 8. Encoding of Terminal Modes 732 Terminal modes (as passed in a pty request) are encoded into a byte 733 stream. It is intended that the coding be portable across different 734 environments. 736 The tty mode description is a stream of bytes. The stream consists 737 of opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). 738 Opcodes 1 to 159 have a single uint32 argument. Opcodes 160 to 255 739 are not yet defined, and cause parsing to stop (they should only be 740 used after any other data). 742 The client SHOULD put in the stream any modes it knows about, and the 743 server MAY ignore any modes it does not know about. This allows some 744 degree of machine-independence, at least between systems that use a 745 POSIX-like tty interface. The protocol can support other systems as 746 well, but the client may need to fill reasonable values for a number 747 of parameters so the server pty gets set to a reasonable mode (the 748 server leaves all unspecified mode bits in their default values, and 749 only some combinations make sense). 751 The following opcodes have been defined. The naming of opcodes 752 mostly follows the POSIX terminal mode flags. 754 0 TTY_OP_END Indicates end of options. 755 1 VINTR Interrupt character; 255 if none. Similarly for the 756 other characters. Not all of these characters are 757 supported on all systems. 758 2 VQUIT The quit character (sends SIGQUIT signal on POSIX 759 systems). 760 3 VERASE Erase the character to left of the cursor. 761 4 VKILL Kill the current input line. 762 5 VEOF End-of-file character (sends EOF from the terminal). 763 6 VEOL End-of-line character in addition to carriage return 764 and/or linefeed. 765 7 VEOL2 Additional end-of-line character. 766 8 VSTART Continues paused output (normally control-Q). 767 9 VSTOP Pauses output (normally control-S). 768 10 VSUSP Suspends the current program. 769 11 VDSUSP Another suspend character. 770 12 VREPRINT Reprints the current input line. 771 13 VWERASE Erases a word left of cursor. 772 14 VLNEXT Enter the next character typed literally, even if it 773 is a special character 774 15 VFLUSH Character to flush output. 775 16 VSWTCH Switch to a different shell layer. 776 17 VSTATUS Prints system status line (load, command, pid etc). 777 18 VDISCARD Toggles the flushing of terminal output. 778 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if 779 this flag is FALSE set, and 1 if it is TRUE. 780 31 PARMRK Mark parity and framing errors. 781 32 INPCK Enable checking of parity errors. 782 33 ISTRIP Strip 8th bit off characters. 783 34 INLCR Map NL into CR on input. 784 35 IGNCR Ignore CR on input. 785 36 ICRNL Map CR to NL on input. 786 37 IUCLC Translate uppercase characters to lowercase. 787 38 IXON Enable output flow control. 788 39 IXANY Any char will restart after stop. 789 40 IXOFF Enable input flow control. 790 41 IMAXBEL Ring bell on input queue full. 791 50 ISIG Enable signals INTR, QUIT, [D]SUSP. 792 51 ICANON Canonicalize input lines. 793 52 XCASE Enable input and output of uppercase characters by 794 preceding their lowercase equivalents with `\'. 795 53 ECHO Enable echoing. 796 54 ECHOE Visually erase chars. 797 55 ECHOK Kill character discards current line. 798 56 ECHONL Echo NL even if ECHO is off. 799 57 NOFLSH Don't flush after interrupt. 800 58 TOSTOP Stop background jobs from output. 801 59 IEXTEN Enable extensions. 803 60 ECHOCTL Echo control characters as ^(Char). 804 61 ECHOKE Visual erase for line kill. 805 62 PENDIN Retype pending input. 806 70 OPOST Enable output processing. 807 71 OLCUC Convert lowercase to uppercase. 808 72 ONLCR Map NL to CR-NL. 809 73 OCRNL Translate carriage return to newline (output). 810 74 ONOCR Translate newline to carriage return-newline 811 (output). 812 75 ONLRET Newline performs a carriage return (output). 813 90 CS7 7 bit mode. 814 91 CS8 8 bit mode. 815 92 PARENB Parity enable. 816 93 PARODD Odd parity, else even. 818 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second. 819 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second. 821 9. Summary of Message Numbers 823 #define SSH_MSG_GLOBAL_REQUEST 80 824 #define SSH_MSG_REQUEST_SUCCESS 81 825 #define SSH_MSG_REQUEST_FAILURE 82 826 #define SSH_MSG_CHANNEL_OPEN 90 827 #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 828 #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 829 #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 830 #define SSH_MSG_CHANNEL_DATA 94 831 #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 832 #define SSH_MSG_CHANNEL_EOF 96 833 #define SSH_MSG_CHANNEL_CLOSE 97 834 #define SSH_MSG_CHANNEL_REQUEST 98 835 #define SSH_MSG_CHANNEL_SUCCESS 99 836 #define SSH_MSG_CHANNEL_FAILURE 100 838 10. IANA Considerations 840 This document is part of a set. The IANA considerations for the SSH 841 protocol as defined in [SSH-ARCH], [SSH-TRANS], [SSH-USERAUTH], and 842 this document, are detailed in [SSH-NUMBERS]. 844 11. Security Considerations 846 This protocol is assumed to run on top of a secure, authenticated 847 transport. User authentication and protection against network-level 848 attacks are assumed to be provided by the underlying protocols. 850 Full security considerations for this protocol are provided in 851 [SSH-ARCH]. Specific to this document, it is RECOMMENDED that 852 implementations disable all the potentially dangerous features (e.g. 853 agent forwarding, X11 forwarding, and TCP/IP forwarding) if the host 854 key has changed without notice or explanation. 856 12. References 858 12.1 Normative References 860 [SSH-ARCH] 861 Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", 862 I-D draft-ietf-architecture-16.txt, May 2004. 864 [SSH-TRANS] 865 Ylonen, T. and C. Lonvick, "SSH Transport Layer Protocol", 866 I-D draft-ietf-transport-18.txt, May 2004. 868 [SSH-USERAUTH] 869 Ylonen, T. and C. Lonvick, "SSH Authentication Protocol", 870 I-D draft-ietf-userauth-21.txt, May 2004. 872 [SSH-NUMBERS] 873 Ylonen, T. and C. Lonvick, "SSH Protocol Assigned 874 Numbers", I-D draft-ietf-assignednumbers-06.txt, May 2004. 876 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 877 Requirement Levels", BCP 14, RFC 2119, March 1997. 879 12.2 Informative References 881 [RFC1884] Hinden, R. and S. Deering, "IP Version 6 Addressing 882 Architecture", RFC 1884, December 1995. 884 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 885 10646", RFC 2279, January 1998. 887 [RFC3066] Alvestrand, H., "Tags for the Identification of 888 Languages", BCP 47, RFC 3066, January 2001. 890 [SCHEIFLER] 891 Scheifler, R., "X Window System : The Complete Reference 892 to Xlib, X Protocol, Icccm, Xlfd, 3rd edition.", Digital 893 Press ISBN 1555580882, February 1992. 895 [POSIX] ISO/IEC, 9945-1., "Information technology -- Portable 896 Operating System Interface (POSIX)-Part 1: System 897 Application Program Interface (API) C Language", ANSI/IEE 898 Std 1003.1, July 1996. 900 Authors' Addresses 902 Tatu Ylonen 903 SSH Communications Security Corp 904 Fredrikinkatu 42 905 HELSINKI FIN-00100 906 Finland 908 EMail: ylo@ssh.com 910 Chris Lonvick (editor) 911 Cisco Systems, Inc 912 12515 Research Blvd. 913 Austin 78759 914 USA 916 EMail: clonvick@cisco.com 918 Intellectual Property Statement 920 The IETF takes no position regarding the validity or scope of any 921 intellectual property or other rights that might be claimed to 922 pertain to the implementation or use of the technology described in 923 this document or the extent to which any license under such rights 924 might or might not be available; neither does it represent that it 925 has made any effort to identify any such rights. Information on the 926 IETF's procedures with respect to rights in standards-track and 927 standards-related documentation can be found in BCP-11. Copies of 928 claims of rights made available for publication and any assurances of 929 licenses to be made available, or the result of an attempt made to 930 obtain a general license or permission for the use of such 931 proprietary rights by implementors or users of this specification can 932 be obtained from the IETF Secretariat. 934 The IETF invites any interested party to bring to its attention any 935 copyrights, patents or patent applications, or other proprietary 936 rights which may cover technology that may be required to practice 937 this standard. Please address the information to the IETF Executive 938 Director. 940 The IETF has been notified of intellectual property rights claimed in 941 regard to some or all of the specification contained in this 942 document. For more information consult the online list of claimed 943 rights. 945 Full Copyright Statement 947 Copyright (C) The Internet Society (2004). All Rights Reserved. 949 This document and translations of it may be copied and furnished to 950 others, and derivative works that comment on or otherwise explain it 951 or assist in its implementation may be prepared, copied, published 952 and distributed, in whole or in part, without restriction of any 953 kind, provided that the above copyright notice and this paragraph are 954 included on all such copies and derivative works. However, this 955 document itself may not be modified in any way, such as by removing 956 the copyright notice or references to the Internet Society or other 957 Internet organizations, except as needed for the purpose of 958 developing Internet standards in which case the procedures for 959 copyrights defined in the Internet Standards process must be 960 followed, or as required to translate it into languages other than 961 English. 963 The limited permissions granted above are perpetual and will not be 964 revoked by the Internet Society or its successors or assignees. 966 This document and the information contained herein is provided on an 967 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 968 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 969 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 970 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 971 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 973 Acknowledgment 975 Funding for the RFC Editor function is currently provided by the 976 Internet Society.