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