idnits 2.17.1 draft-ietf-secsh-connect-12.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 7 instances of too long lines in the document, the longest one being 3 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 189: '...URE. The client MAY show the addition...' RFC 2119 keyword, line 210: '...e, the recipient MAY send the given nu...' RFC 2119 keyword, line 222: '... MAY ignore all extra data sent afte...' RFC 2119 keyword, line 244: '...send more data to a channel, it SHOULD...' RFC 2119 keyword, line 258: '...n receiving this message, a party MUST...' (28 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 110 has weird spacing: '... string req...' == Line 111 has weird spacing: '...boolean want...' == Line 151 has weird spacing: '... string cha...' == Line 184 has weird spacing: '... string add...' == Line 185 has weird spacing: '... string lan...' == (33 more instances...) == 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 (November 9, 2001) is 8203 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 860, but no explicit reference was found in the text == Unused Reference: 'SSH-TRANS' is defined on line 879, but no explicit reference was found in the text == Unused Reference: 'SSH-USERAUTH' is defined on line 882, but no explicit reference was found in the text == Unused Reference: 'SSH-CONNECT' is defined on line 885, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1766 (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 1884 (Obsoleted by RFC 2373) ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) -- Possible downref: Non-RFC (?) normative reference: ref. 'SCHEIFLER' -- Possible downref: Non-RFC (?) normative reference: ref. 'POSIX' -- 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-connect - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'SSH-CONNECT' Summary: 8 errors (**), 0 flaws (~~), 13 warnings (==), 13 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Ylonen 3 Internet-Draft T. Kivinen 4 Expires: May 10, 2002 SSH Communications Security Corp 5 M. Saarinen 6 University of Jyvaskyla 7 T. Rinne 8 S. Lehtinen 9 SSH Communications Security Corp 10 November 9, 2001 12 SSH Connection Protocol 13 draft-ietf-secsh-connect-12.txt 15 Status of this Memo 17 This document is an Internet-Draft and is in full conformance with 18 all provisions of Section 10 of RFC2026. 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 Internet- 23 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 May 10, 2002. 38 Copyright Notice 40 Copyright (C) The Internet Society (2001). All Rights Reserved. 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. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Global Requests . . . . . . . . . . . . . . . . . . . . . . 3 59 3. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . 3 60 3.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . . 4 61 3.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 5 62 3.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . . 6 63 3.4 Channel-Specific Requests . . . . . . . . . . . . . . . . . 6 64 4. Interactive Sessions . . . . . . . . . . . . . . . . . . . . 7 65 4.1 Opening a Session . . . . . . . . . . . . . . . . . . . . . 7 66 4.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 8 67 4.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 8 68 4.3.1 Requesting X11 Forwarding . . . . . . . . . . . . . . . . . 8 69 4.3.2 X11 Channels . . . . . . . . . . . . . . . . . . . . . . . . 9 70 4.4 Environment Variable Passing . . . . . . . . . . . . . . . . 9 71 4.5 Starting a Shell or a Command . . . . . . . . . . . . . . . 10 72 4.6 Session Data Transfer . . . . . . . . . . . . . . . . . . . 11 73 4.7 Window Dimension Change Message . . . . . . . . . . . . . . 11 74 4.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . . 11 75 4.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 12 76 4.10 Returning Exit Status . . . . . . . . . . . . . . . . . . . 12 77 5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . 13 78 5.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . . 13 79 5.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 14 80 6. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . 15 81 7. Summary of Message Numbers . . . . . . . . . . . . . . . . . 17 82 8. Security Considerations . . . . . . . . . . . . . . . . . . 18 83 9. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 18 84 10. Additional Information . . . . . . . . . . . . . . . . . . . 19 85 References . . . . . . . . . . . . . . . . . . . . . . . . . 19 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 19 87 Full Copyright Statement . . . . . . . . . . . . . . . . . . 21 89 1. Introduction 91 The SSH Connection Protocol has been designed to run on top of the 92 SSH transport layer and user authentication protocols. It provides 93 interactive login sessions, remote execution of commands, forwarded 94 TCP/IP connections, and forwarded X11 connections. The service name 95 for this protocol (after user authentication) is "ssh-connection". 97 This document should be read only after reading the SSH architecture 98 document [SSH-ARCH]. This document freely uses terminology and 99 notation from the architecture document without reference or further 100 explanation. 102 2. Global Requests 104 There are several kinds of requests that affect the state of the 105 remote end "globally", independent of any channels. An example is a 106 request to start TCP/IP forwarding for a specific port. All such 107 requests use the following format. 109 byte SSH_MSG_GLOBAL_REQUEST 110 string request name (restricted to US-ASCII) 111 boolean want reply 112 ... request-specific data follows 114 request names follow the DNS extensibility naming convention outlined 115 in [SSH-ARCH] 117 The recipient will respond to this message with 118 SSH_MSG_REQUEST_SUCCESS, SSH_MSG_REQUEST_FAILURE, or some request- 119 specific continuation messages if `want reply' is TRUE. 121 byte SSH_MSG_REQUEST_SUCCESS 123 If the recipient does not recognize or support the request, it simply 124 responds with SSH_MSG_REQUEST_FAILURE. 126 byte SSH_MSG_REQUEST_FAILURE 128 3. Channel Mechanism 130 All terminal sessions, forwarded connections, etc. are channels. 131 Either side may open a channel. Multiple channels are multiplexed 132 into a single connection. 134 Channels are identified by numbers at each end. The number referring 135 to a channel may be different on each side. Requests to open a 136 channel contain the sender's channel number. Any other channel- 137 related messages contain the recipient's channel number for the 138 channel. 140 Channels are flow-controlled. No data may be sent to a channel until 141 a message is received to indicate that window space is available. 143 3.1 Opening a Channel 145 When either side wishes to open a new channel, it allocates a local 146 number for the channel. It then sends the following message to the 147 other side, and includes the local channel number and initial window 148 size in the message. 150 byte SSH_MSG_CHANNEL_OPEN 151 string channel type (restricted to US-ASCII) 152 uint32 sender channel 153 uint32 initial window size 154 uint32 maximum packet size 155 ... channel type specific data follows 157 The channel type is a name as described in the SSH architecture 158 document, with similar extension mechanisms. `sender channel' is a 159 local identifier for the channel used by the sender of this message. 160 `initial window size' specifies how many bytes of channel data can be 161 sent to the sender of this message without adjusting the window. 162 `Maximum packet size' specifies the maximum size of an individual 163 data packet that can be sent to the sender (for example, one might 164 want to use smaller packets for interactive connections to get better 165 interactive response on slow links). 167 The remote side then decides whether it can open the channel, and 168 responds with either 170 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 171 uint32 recipient channel 172 uint32 sender channel 173 uint32 initial window size 174 uint32 maximum packet size 175 ... channel type specific data follows 177 where `recipient channel' is the channel number given in the original 178 open request, and `sender channel' is the channel number allocated by 179 the other side, or 181 byte SSH_MSG_CHANNEL_OPEN_FAILURE 182 uint32 recipient channel 183 uint32 reason code 184 string additional textual information (ISO-10646 UTF-8 [RFC2279]) 185 string language tag (as defined in [RFC1766]) 187 If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support 188 the specified channel type, it simply responds with 189 SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional 190 information to the user. If this is done, the client software should 191 take the precautions discussed in [SSH-ARCH]. 193 The following reason codes are defined: 195 #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 196 #define SSH_OPEN_CONNECT_FAILED 2 197 #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 198 #define SSH_OPEN_RESOURCE_SHORTAGE 4 200 3.2 Data Transfer 202 The window size specifies how many bytes the other party can send 203 before it must wait for the window to be adjusted. Both parties use 204 the following message to adjust the window. 206 byte SSH_MSG_CHANNEL_WINDOW_ADJUST 207 uint32 recipient channel 208 uint32 bytes to add 210 After receiving this message, the recipient MAY send the given number 211 of bytes more than it was previously allowed to send; the window size 212 is incremented. 214 Data transfer is done with messages of the following type. 216 byte SSH_MSG_CHANNEL_DATA 217 uint32 recipient channel 218 string data 220 The maximum amount of data allowed is the current window size. The 221 window size is decremented by the amount of data sent. Both parties 222 MAY ignore all extra data sent after the allowed window is empty. 224 Additionally, some channels can transfer several types of data. An 225 example of this is stderr data from interactive sessions. Such data 226 can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a 227 separate integer specifies the type of the data. The available types 228 and their interpretation depend on the type of the channel. 230 byte SSH_MSG_CHANNEL_EXTENDED_DATA 231 uint32 recipient_channel 232 uint32 data_type_code 233 string data 235 Data sent with these messages consumes the same window as ordinary 236 data. 238 Currently, only the following type is defined. 240 #define SSH_EXTENDED_DATA_STDERR 1 242 3.3 Closing a Channel 244 When a party will no longer send more data to a channel, it SHOULD 245 send SSH_MSG_CHANNEL_EOF. 247 byte SSH_MSG_CHANNEL_EOF 248 uint32 recipient_channel 250 No explicit response is sent to this message; however, the 251 application may send EOF to whatever is at the other end of the 252 channel. Note that the channel remains open after this message, and 253 more data may still be sent in the other direction. This message 254 does not consume window space and can be sent even if no window space 255 is available. 257 When either party wishes to terminate the channel, it sends 258 SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST 259 send back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this 260 message for the channel. The channel is considered closed for a 261 party when it has both sent and received SSH_MSG_CHANNEL_CLOSE, and 262 the party may then reuse the channel number. A party MAY send 263 SSH_MSG_CHANNEL_CLOSE without having sent or received 264 SSH_MSG_CHANNEL_EOF. 266 byte SSH_MSG_CHANNEL_CLOSE 267 uint32 recipient_channel 269 This message does not consume window space and can be sent even if no 270 window space is available. 272 It is recommended that any data sent before this message is delivered 273 to the actual destination, if possible. 275 3.4 Channel-Specific Requests 277 Many channel types have extensions that are specific to that 278 particular channel type. An example is requesting a pty (pseudo 279 terminal) for an interactive session. 281 All channel-specific requests use the following format. 283 byte SSH_MSG_CHANNEL_REQUEST 284 uint32 recipient channel 285 string request type (restricted to US-ASCII) 286 boolean want reply 287 ... type-specific data 289 If want reply is FALSE, no response will be sent to the request. 290 Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS 291 or SSH_MSG_CHANNEL_FAILURE, or request-specific continuation 292 messages. If the request is not recognized or is not supported for 293 the channel, SSH_MSG_CHANNEL_FAILURE is returned. 295 This message does not consume window space and can be sent even if no 296 window space is available. Request types are local to each channel 297 type. 299 The client is allowed to send further messages without waiting for 300 the response to the request. 302 request type names follow the DNS extensibility naming convention 303 outlined in [SSH-ARCH] 305 byte SSH_MSG_CHANNEL_SUCCESS 306 uint32 recipient_channel 308 byte SSH_MSG_CHANNEL_FAILURE 309 uint32 recipient_channel 311 These messages do not consume window space and can be sent even if no 312 window space is available. 314 4. Interactive Sessions 316 A session is a remote execution of a program. The program may be a 317 shell, an application, a system command, or some built-in subsystem. 318 It may or may not have a tty, and may or may not involve X11 319 forwarding. Multiple sessions can be active simultaneously. 321 4.1 Opening a Session 323 A session is started by sending the following message. 325 byte SSH_MSG_CHANNEL_OPEN 326 string "session" 327 uint32 sender channel 328 uint32 initial window size 329 uint32 maximum packet size 331 Client implementations SHOULD reject any session channel open 332 requests to make it more difficult for a corrupt server to attack the 333 client. 335 4.2 Requesting a Pseudo-Terminal 337 A pseudo-terminal can be allocated for the session by sending the 338 following message. 340 byte SSH_MSG_CHANNEL_REQUEST 341 uint32 recipient_channel 342 string "pty-req" 343 boolean want_reply 344 string TERM environment variable value (e.g., vt100) 345 uint32 terminal width, characters (e.g., 80) 346 uint32 terminal height, rows (e.g., 24) 347 uint32 terminal width, pixels (e.g., 640) 348 uint32 terminal height, pixels (e.g., 480) 349 string encoded terminal modes 351 The encoding of terminal modes is described in Section Encoding of 352 Terminal Modes (Section 6). Zero dimension parameters MUST be 353 ignored. The character/row dimensions override the pixel dimensions 354 (when nonzero). Pixel dimensions refer to the drawable area of the 355 window. 357 The dimension parameters are only informational. 359 The client SHOULD ignore pty requests. 361 4.3 X11 Forwarding 363 4.3.1 Requesting X11 Forwarding 365 X11 forwarding may be requested for a session by sending 367 byte SSH_MSG_CHANNEL_REQUEST 368 uint32 recipient channel 369 string "x11-req" 370 boolean want reply 371 boolean single connection 372 string x11 authentication protocol 373 string x11 authentication cookie 374 uint32 x11 screen number 376 It is recommended that the authentication cookie that is sent be a 377 fake, random cookie, and that the cookie is checked and replaced by 378 the real cookie when a connection request is received. 380 X11 connection forwarding should stop when the session channel is 381 closed; however, already opened forwardings should not be 382 automatically closed when the session channel is closed. 384 If `single connection' is TRUE, only a single connection should be 385 forwarded. No more connections will be forwarded after the first, or 386 after the session channel has been closed. 388 The `x11 authentication protocol' is the name of the X11 389 authentication method used, e.g. "MIT-MAGIC-COOKIE-1". 391 The x11 authentication cookie MUST be hexadecimal encoded. 393 X Protocol is documented in [SCHEIFLER]. 395 4.3.2 X11 Channels 397 X11 channels are opened with a channel open request. The resulting 398 channels are independent of the session, and closing the session 399 channel does not close the forwarded X11 channels. 401 byte SSH_MSG_CHANNEL_OPEN 402 string "x11" 403 uint32 sender channel 404 uint32 initial window size 405 uint32 maximum packet size 406 string originator address (e.g. "192.168.7.38") 407 uint32 originator port 409 The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION 410 or SSH_MSG_CHANNEL_OPEN_FAILURE. 412 Implementations MUST reject any X11 channel open requests if they 413 have not requested X11 forwarding. 415 4.4 Environment Variable Passing 417 Environment variables may be passed to the shell/command to be 418 started later. Typically, each machine will have a preconfigured set 419 of variables that it will allow. Since uncontrolled setting of 420 environment variables can be very dangerous, it is recommended that 421 implementations allow setting only variables whose names have been 422 explicitly configured to be allowed. 424 byte SSH_MSG_CHANNEL_REQUEST 425 uint32 recipient channel 426 string "env" 427 boolean want reply 428 string variable name 429 string variable value 431 4.5 Starting a Shell or a Command 433 Once the session has been set up, a program is started at the remote 434 end. The program can be a shell, an application program or a 435 subsystem with a host-independent name. Only one of these requests 436 can succeed per channel. 438 byte SSH_MSG_CHANNEL_REQUEST 439 uint32 recipient channel 440 string "shell" 441 boolean want reply 443 This message will request the user's default shell (typically defined 444 in /etc/passwd in UNIX systems) to be started at the other end. 446 byte SSH_MSG_CHANNEL_REQUEST 447 uint32 recipient channel 448 string "exec" 449 boolean want reply 450 string command 452 This message will request the server to start the execution of the 453 given command. The command string may contain a path. Normal 454 precautions MUST be taken to prevent the execution of unauthorized 455 commands. 457 byte SSH_MSG_CHANNEL_REQUEST 458 uint32 recipient channel 459 string "subsystem" 460 boolean want reply 461 string subsystem name 463 This last form executes a predefined subsystem. It is expected that 464 these will include a general file transfer mechanism, and possibly 465 other features. Implementations may also allow configuring more such 466 mechanisms. As the user's shell is usually used to execute the 467 subsystem, it is advisable for the subsystem protocol to have a 468 "magic cookie" at the beginning of the protocol transaction to 469 distinguish from arbitrary output from shell initialization scripts 470 etc. This spurious output from the shell may be filtered out either 471 at the server or at the client. 473 The server SHOULD not halt the execution of the protocol stack when 474 starting a shell or a program. All input and output from these 475 SHOULD be redirected to the channel or to the encrypted tunnel. 477 It is RECOMMENDED to request and check the reply for these messages. 478 The client SHOULD ignore these messages. 480 subsystem names follow the DNS extensibility naming convention 481 outlined in [SSH-ARCH] 483 4.6 Session Data Transfer 485 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 486 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The 487 extended data type SSH_EXTENDED_DATA_STDERR has been defined for 488 stderr data. 490 4.7 Window Dimension Change Message 492 When the window (terminal) size changes on the client side, it MAY 493 send a message to the other side to inform it of the new dimensions. 495 byte SSH_MSG_CHANNEL_REQUEST 496 uint32 recipient_channel 497 string "window-change" 498 boolean FALSE 499 uint32 terminal width, columns 500 uint32 terminal height, rows 501 uint32 terminal width, pixels 502 uint32 terminal height, pixels 504 No response SHOULD be sent to this message. 506 4.8 Local Flow Control 508 On many systems, it is possible to determine if a pseudo-terminal is 509 using control-S/control-Q flow control. When flow control is 510 allowed, it is often desirable to do the flow control at the client 511 end to speed up responses to user requests. This is facilitated by 512 the following notification. Initially, the server is responsible for 513 flow control. (Here, again, client means the side originating the 514 session, and server means the other side.) 515 The message below is used by the server to inform the client when it 516 can or cannot perform flow control (control-S/control-Q processing). 517 If `client can do' is TRUE, the client is allowed to do flow control 518 using control-S and control-Q. The client MAY ignore this message. 520 byte SSH_MSG_CHANNEL_REQUEST 521 uint32 recipient channel 522 string "xon-xoff" 523 boolean FALSE 524 boolean client can do 526 No response is sent to this message. 528 4.9 Signals 530 A signal can be delivered to the remote process/service using the 531 following message. Some systems may not implement signals, in which 532 case they SHOULD ignore this message. 534 byte SSH_MSG_CHANNEL_REQUEST 535 uint32 recipient channel 536 string "signal" 537 boolean FALSE 538 string signal name without the "SIG" prefix. 540 Signal names will be encoded as discussed in the "exit-signal" 541 SSH_MSG_CHANNEL_REQUEST. 543 4.10 Returning Exit Status 545 When the command running at the other end terminates, the following 546 message can be sent to return the exit status of the command. 547 Returning the status is RECOMMENDED. No acknowledgment is sent for 548 this message. The channel needs to be closed with 549 SSH_MSG_CHANNEL_CLOSE after this message. 551 The client MAY ignore these messages. 553 byte SSH_MSG_CHANNEL_REQUEST 554 uint32 recipient_channel 555 string "exit-status" 556 boolean FALSE 557 uint32 exit_status 559 The remote command may also terminate violently due to a signal. 560 Such a condition can be indicated by the following message. A zero 561 exit_status usually means that the command terminated successfully. 563 byte SSH_MSG_CHANNEL_REQUEST 564 uint32 recipient channel 565 string "exit-signal" 566 boolean FALSE 567 string signal name without the "SIG" prefix. 568 boolean core dumped 569 string error message (ISO-10646 UTF-8) 570 string language tag (as defined in [RFC1766]) 572 The signal name is one of the following (these are from [POSIX]) 574 ABRT 575 ALRM 576 FPE 577 HUP 578 ILL 579 INT 580 KILL 581 PIPE 582 QUIT 583 SEGV 584 TERM 585 USR1 586 USR2 588 Additional signal names MAY be sent in the format "sig-name@xyz", 589 where `sig-name' and `xyz' may be anything a particular implementor 590 wants (except the `@' sign). However, it is suggested that if a 591 `configure' script is used, the non-standard signal names it finds be 592 encoded as "SIG@xyz.config.guess", where `SIG' is the signal name 593 without the "SIG" prefix, and `xyz' be the host type, as determined 594 by `config.guess'. 596 The `error message' contains an additional explanation of the error 597 message. The message may consist of multiple lines. The client 598 software MAY display this message to the user. If this is done, the 599 client software should take the precautions discussed in [SSH-ARCH]. 601 5. TCP/IP Port Forwarding 603 5.1 Requesting Port Forwarding 605 A party need not explicitly request forwardings from its own end to 606 the other direction. However, if it wishes that connections to a 607 port on the other side be forwarded to the local side, it must 608 explicitly request this. 610 byte SSH_MSG_GLOBAL_REQUEST 611 string "tcpip-forward" 612 boolean want reply 613 string address to bind (e.g. "0.0.0.0") 614 uint32 port number to bind 616 `Address to bind' and `port number to bind' specify the IP address 617 and port to which the socket to be listened is bound. The address 618 should be "0.0.0.0" if connections are allowed from anywhere. (Note 619 that the client can still filter connections based on information 620 passed in the open request.) 622 Implementations should only allow forwarding privileged ports if the 623 user has been authenticated as a privileged user. 625 The client may send 0 as the port to bind to, in this case the server 626 should interpret this as meaning it should allocate the next availble 627 non privileged port and return the value in the response packet. 629 Client implementations SHOULD reject these messages; they are 630 normally only sent by the client. 632 The response to an SSH_MSG_GLOBAL_REQUEST is of the form: 634 bytes SSH_MSG_GLOBAL_REQUEST_SUCCESS 635 string "tcpip-forward" 636 unint32 port that was bound on the server 638 A port forwarding can be cancelled with the following message. Note 639 that channel open requests may be received until a reply to this 640 message is received. 642 byte SSH_MSG_GLOBAL_REQUEST 643 string "cancel-tcpip-forward" 644 boolean want reply 645 string address_to_bind (e.g. "127.0.0.1") 646 uint32 port number to bind 648 Client implementations SHOULD reject these messages; they are 649 normally only sent by the client. 651 5.2 TCP/IP Forwarding Channels 653 When a connection comes to a port for which remote forwarding has 654 been requested, a channel is opened to forward the port to the other 655 side. 657 byte SSH_MSG_CHANNEL_OPEN 658 string "forwarded-tcpip" 659 uint32 sender channel 660 uint32 initial window size 661 uint32 maximum packet size 662 string address that was connected 663 uint32 port that was connected 664 string originator IP address 665 uint32 originator port 667 Implementations MUST reject these messages unless they have 668 previously requested a remote TCP/IP port forwarding with the given 669 port number. 671 When a connection comes to a locally forwarded TCP/IP port, the 672 following packet is sent to the other side. Note that these messages 673 MAY be sent also for ports for which no forwarding has been 674 explicitly requested. The receiving side must decide whether to 675 allow the forwarding. 677 byte SSH_MSG_CHANNEL_OPEN 678 string "direct-tcpip" 679 uint32 sender channel 680 uint32 initial window size 681 uint32 maximum packet size 682 string host to connect 683 uint32 port to connect 684 string originator IP address 685 uint32 originator port 687 `Host to connect' and `port to connect' specify the TCP/IP host and 688 port where the recipient should connect the channel. `Host to 689 connect' may be either a domain name or a numeric IP address. 691 `Originator IP address' is the numeric IP address of the machine 692 where the connection request comes from, and `originator port' is the 693 port on the originator host from where the connection came from. 695 Forwarded TCP/IP channels are independent of any sessions, and 696 closing a session channel does not in any way imply that forwarded 697 connections should be closed. 699 Client implementations SHOULD reject direct TCP/IP open requests for 700 security reasons. 702 6. Encoding of Terminal Modes 704 Terminal modes (as passed in a pty request) are encoded into a byte 705 stream. It is intended that the coding be portable across different 706 environments. 708 The tty mode description is a stream of bytes. The stream consists 709 of opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). 710 Opcodes 1 to 159 have a single uint32 argument. Opcodes 160 to 255 711 are not yet defined, and cause parsing to stop (they should only be 712 used after any other data). 714 The client SHOULD put in the stream any modes it knows about, and the 715 server MAY ignore any modes it does not know about. This allows some 716 degree of machine-independence, at least between systems that use a 717 POSIX-like tty interface. The protocol can support other systems as 718 well, but the client may need to fill reasonable values for a number 719 of parameters so the server pty gets set to a reasonable mode (the 720 server leaves all unspecified mode bits in their default values, and 721 only some combinations make sense). 723 The following opcodes have been defined. The naming of opcodes 724 mostly follows the POSIX terminal mode flags. 726 0 TTY_OP_END Indicates end of options. 727 1 VINTR Interrupt character; 255 if none. Similarly for the 728 other characters. Not all of these characters are 729 supported on all systems. 730 2 VQUIT The quit character (sends SIGQUIT signal on POSIX 731 systems). 732 3 VERASE Erase the character to left of the cursor. 733 4 VKILL Kill the current input line. 734 5 VEOF End-of-file character (sends EOF from the terminal). 735 6 VEOL End-of-line character in addition to carriage return 736 and/or linefeed. 737 7 VEOL2 Additional end-of-line character. 738 8 VSTART Continues paused output (normally control-Q). 739 9 VSTOP Pauses output (normally control-S). 740 10 VSUSP Suspends the current program. 741 11 VDSUSP Another suspend character. 742 12 VREPRINT Reprints the current input line. 743 13 VWERASE Erases a word left of cursor. 744 14 VLNEXT Enter the next character typed literally, even if it 745 is a special character 746 15 VFLUSH Character to flush output. 747 16 VSWTCH Switch to a different shell layer. 748 17 VSTATUS Prints system status line (load, command, pid etc). 749 18 VDISCARD Toggles the flushing of terminal output. 750 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if 751 this flag is FALSE set, and 1 if it is TRUE. 752 31 PARMRK Mark parity and framing errors. 754 32 INPCK Enable checking of parity errors. 755 33 ISTRIP Strip 8th bit off characters. 756 34 INLCR Map NL into CR on input. 757 35 IGNCR Ignore CR on input. 758 36 ICRNL Map CR to NL on input. 759 37 IUCLC Translate uppercase characters to lowercase. 760 38 IXON Enable output flow control. 761 39 IXANY Any char will restart after stop. 762 40 IXOFF Enable input flow control. 763 41 IMAXBEL Ring bell on input queue full. 764 50 ISIG Enable signals INTR, QUIT, [D]SUSP. 765 51 ICANON Canonicalize input lines. 766 52 XCASE Enable input and output of uppercase characters by 767 preceding their lowercase equivalents with `\'. 768 53 ECHO Enable echoing. 769 54 ECHOE Visually erase chars. 770 55 ECHOK Kill character discards current line. 771 56 ECHONL Echo NL even if ECHO is off. 772 57 NOFLSH Don't flush after interrupt. 773 58 TOSTOP Stop background jobs from output. 774 59 IEXTEN Enable extensions. 775 60 ECHOCTL Echo control characters as ^(Char). 776 61 ECHOKE Visual erase for line kill. 777 62 PENDIN Retype pending input. 778 70 OPOST Enable output processing. 779 71 OLCUC Convert lowercase to uppercase. 780 72 ONLCR Map NL to CR-NL. 781 73 OCRNL Translate carriage return to newline (output). 782 74 ONOCR Translate newline to carriage return-newline 783 (output). 784 75 ONLRET Newline performs a carriage return (output). 785 90 CS7 7 bit mode. 786 91 CS8 8 bit mode. 787 92 PARENB Parity enable. 788 93 PARODD Odd parity, else even. 790 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second. 791 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second. 793 7. Summary of Message Numbers 795 #define SSH_MSG_GLOBAL_REQUEST 80 796 #define SSH_MSG_REQUEST_SUCCESS 81 797 #define SSH_MSG_REQUEST_FAILURE 82 798 #define SSH_MSG_CHANNEL_OPEN 90 799 #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 800 #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 801 #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 802 #define SSH_MSG_CHANNEL_DATA 94 803 #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 804 #define SSH_MSG_CHANNEL_EOF 96 805 #define SSH_MSG_CHANNEL_CLOSE 97 806 #define SSH_MSG_CHANNEL_REQUEST 98 807 #define SSH_MSG_CHANNEL_SUCCESS 99 808 #define SSH_MSG_CHANNEL_FAILURE 100 810 8. Security Considerations 812 This protocol is assumed to run on top of a secure, authenticated 813 transport. User authentication and protection against network-level 814 attacks are assumed to be provided by the underlying protocols. 816 This protocol can, however, be used to execute commands on remote 817 machines. The protocol also permits the server to run commands on 818 the client. Implementations may wish to disallow this to prevent an 819 attacker from coming from the server machine to the client machine. 821 X11 forwarding provides major security improvements over normal 822 cookie-based X11 forwarding. The cookie never needs to be 823 transmitted in the clear, and traffic is encrypted and integrity- 824 protected. No useful authentication data will remain on the server 825 machine after the connection has been closed. On the other hand, in 826 some situations a forwarded X11 connection might be used to get 827 access to the local X server across security perimeters. 829 Port forwardings can potentially allow an intruder to cross security 830 perimeters such as firewalls. They do not offer anything 831 fundamentally new that a user could not do otherwise; however, they 832 make opening tunnels very easy. Implementations should allow policy 833 control over what can be forwarded. Administrators should be able to 834 deny forwardings where appropriate. 836 Since this protocol normally runs inside an encrypted tunnel, 837 firewalls will not be able to examine the traffic. 839 It is RECOMMENDED that implementations disable all the potentially 840 dangerous features (e.g. agent forwarding, X11 forwarding, and 841 TCP/IP forwarding) if the host key has changed. 843 9. Trademark Issues 845 As of this writing, SSH Communications Security Oy claims ssh as its 846 trademark. As with all IPR claims the IETF takes no position 847 regarding the validity or scope of this trademark claim. 849 10. Additional Information 851 The current document editor is: Darren.Moffat@Sun.COM. Comments on 852 this internet draft should be sent to the IETF SECSH working group, 853 details at: http://ietf.org/html.charters/secsh-charter.html 855 References 857 [RFC1766] Alvestrand, H., "Tags for the Identification of 858 Languages", RFC 1766, March 1995. 860 [RFC1884] Hinden, R., Deering, S. and Editors, "IP Version 6 861 Addressing Architecture", RFC 1884, December 1995. 863 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 864 10646", RFC 2279, January 1998. 866 [SCHEIFLER] Scheifler, R., "X Window System : The Complete 867 Reference to Xlib, X Protocol, Icccm, Xlfd, 3rd 868 edition.", Digital Press ISBN 1555580882, Feburary 869 1992. 871 [POSIX] ISO/IEC, 9945-1., "Information technology -- Portable 872 Operating System Interface (POSIX)-Part 1: System 873 Application Program Interface (API) C Language", 874 ANSI/IEE Std 1003.1, July 1996. 876 [SSH-ARCH] Ylonen, T., "SSH Protocol Architecture", I-D draft- 877 ietf-architecture-09.txt, July 2001. 879 [SSH-TRANS] Ylonen, T., "SSH Transport Layer Protocol", I-D 880 draft-ietf-transport-11.txt, July 2001. 882 [SSH-USERAUTH] Ylonen, T., "SSH Authentication Protocol", I-D draft- 883 ietf-userauth-11.txt, July 2001. 885 [SSH-CONNECT] Ylonen, T., "SSH Connection Protocol", I-D draft- 886 ietf-connect-11.txt, July 2001. 888 Authors' Addresses 890 Tatu Ylonen 891 SSH Communications Security Corp 892 Fredrikinkatu 42 893 HELSINKI FIN-00100 894 Finland 896 EMail: ylo@ssh.com 898 Tero Kivinen 899 SSH Communications Security Corp 900 Fredrikinkatu 42 901 HELSINKI FIN-00100 902 Finland 904 EMail: kivinen@ssh.com 906 Markku-Juhani O. Saarinen 907 University of Jyvaskyla 909 Timo J. Rinne 910 SSH Communications Security Corp 911 Fredrikinkatu 42 912 HELSINKI FIN-00100 913 Finland 915 EMail: tri@ssh.com 917 Sami Lehtinen 918 SSH Communications Security Corp 919 Fredrikinkatu 42 920 HELSINKI FIN-00100 921 Finland 923 EMail: sjl@ssh.com 925 Full Copyright Statement 927 Copyright (C) The Internet Society (2001). All Rights Reserved. 929 This document and translations of it may be copied and furnished to 930 others, and derivative works that comment on or otherwise explain it 931 or assist in its implementation may be prepared, copied, published 932 and distributed, in whole or in part, without restriction of any 933 kind, provided that the above copyright notice and this paragraph are 934 included on all such copies and derivative works. However, this 935 document itself may not be modified in any way, such as by removing 936 the copyright notice or references to the Internet Society or other 937 Internet organizations, except as needed for the purpose of 938 developing Internet standards in which case the procedures for 939 copyrights defined in the Internet Standards process must be 940 followed, or as required to translate it into languages other than 941 English. 943 The limited permissions granted above are perpetual and will not be 944 revoked by the Internet Society or its successors or assigns. 946 This document and the information contained herein is provided on an 947 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 948 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 949 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 950 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 951 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 953 Acknowledgement 955 Funding for the RFC Editor function is currently provided by the 956 Internet Society.