idnits 2.17.1 draft-ietf-secsh-connect-09.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. ** 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 171: '...LURE. The client MAY show the addition...' RFC 2119 keyword, line 192: '...e, the recipient MAY send the given nu...' RFC 2119 keyword, line 203: '... amount of data sent. Both parties MAY...' RFC 2119 keyword, line 225: '...more data to a channel, it SHOULD send...' RFC 2119 keyword, line 238: '...eiving this message, a party MUST send...' (25 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 95 has weird spacing: '... string req...' == Line 96 has weird spacing: '...boolean want...' == Line 132 has weird spacing: '... string cha...' == Line 165 has weird spacing: '... string add...' == Line 167 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.) -- Couldn't find a document date in the document -- date freshness check skipped. -- 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: 'RFC-1884' is defined on line 814, but no explicit reference was found in the text == Unused Reference: 'SSH-TRANS' is defined on line 830, but no explicit reference was found in the text == Unused Reference: 'SSH-USERAUTH' is defined on line 833, 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' == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-07 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-09 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-09 Summary: 7 errors (**), 0 flaws (~~), 14 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group T. Ylonen 2 INTERNET-DRAFT T. Kivinen 3 draft-ietf-secsh-connect-09.txt M. Saarinen 4 Expires: 9 July, 2001 T. Rinne 5 S. Lehtinen 6 SSH Communications Security 7 9 January, 2001 9 SSH Connection Protocol 11 Status of This Memo 13 This document is an Internet-Draft and is in full conformance 14 with 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 22 months and may be updated, replaced, or obsoleted by other 23 documents at any time. It is inappropriate to use Internet- 24 Drafts as reference material or to cite them other than as 25 "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 Abstract 35 SSH is a protocol for secure remote login and other secure network ser- 36 vices over an insecure network. This document describes the SSH Connec- 37 tion Protocol. It provides interactive login sessions, remote execution 38 of commands, forwarded TCP/IP connections, and forwarded X11 connec- 39 tions. All of these channels are multiplexed into a single encrypted 40 tunnel. The SSH Connection Protocol has been designed to run on top of 41 the SSH transport layer and user authentication protocols. 43 Table of Contents 45 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 46 2. Global Requests . . . . . . . . . . . . . . . . . . . . . . . . 2 47 3. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . . 3 48 3.1. Opening a Channel . . . . . . . . . . . . . . . . . . . . . 3 49 3.2. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 4 50 3.3. Closing a Channel . . . . . . . . . . . . . . . . . . . . . 5 51 3.4. Channel-Specific Requests . . . . . . . . . . . . . . . . . 5 52 4. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . . 6 53 4.1. Opening a Session . . . . . . . . . . . . . . . . . . . . . 6 54 4.2. Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 7 55 4.3. X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 7 56 4.3.1. Requesting X11 Forwarding . . . . . . . . . . . . . . . 7 57 4.3.2. X11 Channels . . . . . . . . . . . . . . . . . . . . . . 8 58 4.4. Environment Variable Passing . . . . . . . . . . . . . . . . 8 59 4.5. Starting a Shell or a Command . . . . . . . . . . . . . . . 8 60 4.6. Session Data Transfer . . . . . . . . . . . . . . . . . . . 9 61 4.7. Window Dimension Change Message . . . . . . . . . . . . . . 9 62 4.8. Local Flow Control . . . . . . . . . . . . . . . . . . . . . 10 63 4.9. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 10 64 4.10. Returning Exit Status . . . . . . . . . . . . . . . . . . . 10 65 5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . . 11 66 5.1. Requesting Port Forwarding . . . . . . . . . . . . . . . . . 11 67 5.2. TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 12 68 6. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . . . 13 69 7. Summary of Message Numbers . . . . . . . . . . . . . . . . . . . 15 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 15 71 9. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . . . 16 72 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 73 11. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 16 75 1. Introduction 77 The SSH Connection Protocol has been designed to run on top of the SSH 78 transport layer and user authentication protocols. It provides 79 interactive login sessions, remote execution of commands, forwarded 80 TCP/IP connections, and forwarded X11 connections. The service name for 81 this protocol (after user authentication) is "ssh-connection". 83 This document should be read only after reading the SSH architecture 84 document [SSH-ARCH]. This document freely uses terminology and notation 85 from the architecture document without reference or further explanation. 87 2. Global Requests 89 There are several kinds of requests that affect the state of the remote 90 end "globally", independent of any channels. An example is a request to 91 start TCP/IP forwarding for a specific port. All such requests use the 92 following format. 94 byte SSH_MSG_GLOBAL_REQUEST 95 string request name (restricted to US-ASCII) 96 boolean want reply 97 ... request-specific data follows 99 The recipient will respond to this message with SSH_MSG_REQUEST_SUCCESS, 100 SSH_MSG_REQUEST_FAILURE, or some request-specific continuation messages 101 if `want reply' is TRUE. 103 byte SSH_MSG_REQUEST_SUCCESS 105 If the recipient does not recognize or support the request, it simply 106 responds with SSH_MSG_REQUEST_FAILURE. 108 byte SSH_MSG_REQUEST_FAILURE 110 3. Channel Mechanism 112 All terminal sessions, forwarded connections, etc. are channels. Either 113 side may open a channel. Multiple channels are multiplexed into a 114 single connection. 116 Channels are identified by numbers at each end. The number referring to 117 a channel may be different on each side. Requests to open a channel 118 contain the sender's channel number. Any other channel-related messages 119 contain the recipient's channel number for the channel. 121 Channels are flow-controlled. No data may be sent to a channel until a 122 message is received to indicate that window space is available. 124 3.1. Opening a Channel 126 When either side wishes to open a new channel, it allocates a local 127 number for the channel. It then sends the following message to the 128 other side, and includes the local channel number and initial window 129 size in the message. 131 byte SSH_MSG_CHANNEL_OPEN 132 string channel type (restricted to US-ASCII) 133 uint32 sender channel 134 uint32 initial window size 135 uint32 maximum packet size 136 ... channel type specific data follows 138 The channel type is a name as described in the SSH architecture 139 document, with similar extension mechanisms. `sender channel' is a local 140 identifier for the channel used by the sender of this message. `initial 141 window size' specifies how many bytes of channel data can be sent to the 142 sender of this message without adjusting the window. `Maximum packet 143 size' specifies the maximum size of an individual data packet that can 144 be sent to the sender (for example, one might want to use smaller 145 packets for interactive connections to get better interactive response 146 on slow links). 148 The remote side then decides whether it can open the channel, and 149 responds with either 151 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 152 uint32 recipient channel 153 uint32 sender channel 154 uint32 initial window size 155 uint32 maximum packet size 156 ... channel type specific data follows 158 where `recipient channel' is the channel number given in the original 159 open request, and `sender channel' is the channel number allocated by 160 the other side, or 162 byte SSH_MSG_CHANNEL_OPEN_FAILURE 163 uint32 recipient channel 164 uint32 reason code 165 string additional textual information (ISO-10646 UTF-8 166 [RFC-2279]) 167 string language tag (as defined in [RFC-1766]) 169 If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support 170 the specified channel type, it simply responds with 171 SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional 172 information to the user. If this is done, the client software should 173 take the precautions discussed in [SSH-ARCH]. 175 The following reason codes are defined: 177 #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 178 #define SSH_OPEN_CONNECT_FAILED 2 179 #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 180 #define SSH_OPEN_RESOURCE_SHORTAGE 4 182 3.2. Data Transfer 184 The window size specifies how many bytes the other party can send before 185 it must wait for the window to be adjusted. Both parties use the 186 following message to adjust the window. 188 byte SSH_MSG_CHANNEL_WINDOW_ADJUST 189 uint32 recipient channel 190 uint32 bytes to add 192 After receiving this message, the recipient MAY send the given number of 193 bytes more than it was previously allowed to send; the window size is 194 incremented. 196 Data transfer is done with messages of the following type. 198 byte SSH_MSG_CHANNEL_DATA 199 uint32 recipient channel 200 string data 202 The maximum amount of data allowed is the current window size. The 203 window size is decremented by the amount of data sent. Both parties MAY 204 ignore all extra data sent after the allowed window is empty. 206 Additionally, some channels can transfer several types of data. An 207 example of this is stderr data from interactive sessions. Such data can 208 be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a separate 209 integer specifies the type of the data. The available types and their 210 interpretation depend on the type of the channel. 212 byte SSH_MSG_CHANNEL_EXTENDED_DATA 213 uint32 recipient_channel 214 uint32 data_type_code 215 string data 217 Data sent with these messages consumes the same window as ordinary data. 219 Currently, only the following type is defined. 221 #define SSH_EXTENDED_DATA_STDERR 1 223 3.3. Closing a Channel 225 When a party will no longer send more data to a channel, it SHOULD send 226 SSH_MSG_CHANNEL_EOF. 228 byte SSH_MSG_CHANNEL_EOF 229 uint32 recipient_channel 231 No explicit response is sent to this message; however, the application 232 may send EOF to whatever is at the other end of the channel. Note that 233 the channel remains open after this message, and more data may still be 234 sent in the other direction. This message does not consume window space 235 and can be sent even if no window space is available. 237 When either party wishes to terminate the channel, it sends 238 SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST send 239 back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this message for 240 the channel. The channel is considered closed for a party when it has 241 both sent and received SSH_MSG_CHANNEL_CLOSE, and the party may then 242 reuse the channel number. A party MAY send SSH_MSG_CHANNEL_CLOSE 243 without having sent or received SSH_MSG_CHANNEL_EOF. 245 byte SSH_MSG_CHANNEL_CLOSE 246 uint32 recipient_channel 248 This message does not consume window space and can be sent even if no 249 window space is available. 251 It is recommended that any data sent before this message is delivered to 252 the actual destination, if possible. 254 3.4. Channel-Specific Requests 256 Many channel types have extensions that are specific to that particular 257 channel type. An example is requesting a pty (pseudo terminal) for an 258 interactive session. 260 All channel-specific requests use the following format. 262 byte SSH_MSG_CHANNEL_REQUEST 263 uint32 recipient channel 264 string request type (restricted to US-ASCII) 265 boolean want reply 266 ... type-specific data 268 If want reply is FALSE, no response will be sent to the request. 269 Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS or 270 SSH_MSG_CHANNEL_FAILURE, or request-specific continuation messages. If 271 the request is not recognized or is not supported for the channel, 272 SSH_MSG_CHANNEL_FAILURE is returned. 274 This message does not consume window space and can be sent even if no 275 window space is available. Request types are local to each channel type. 277 The client is allowed to send further messages without waiting for the 278 response to the request. 280 byte SSH_MSG_CHANNEL_SUCCESS 281 uint32 recipient_channel 283 byte SSH_MSG_CHANNEL_FAILURE 284 uint32 recipient_channel 286 These messages do not consume window space and can be sent even if no 287 window space is available. 289 4. Interactive Sessions 291 A session is a remote execution of a program. The program may be a 292 shell, an application, a system command, or some built-in subsystem. It 293 may or may not have a tty, and may or may not involve X11 forwarding. 294 Multiple sessions can be active simultaneously. 296 4.1. Opening a Session 298 A session is started by sending the following message. 300 byte SSH_MSG_CHANNEL_OPEN 301 string "session" 302 uint32 sender channel 303 uint32 initial window size 304 uint32 maximum packet size 306 Client implementations SHOULD reject any session channel open requests 307 to make it more difficult for a corrupt server to attack the client. 309 4.2. Requesting a Pseudo-Terminal 311 A pseudo-terminal can be allocated for the session by sending the 312 following message. 314 byte SSH_MSG_CHANNEL_REQUEST 315 uint32 recipient_channel 316 string "pty-req" 317 boolean want_reply 318 string TERM environment variable value (e.g., vt100) 319 uint32 terminal width, characters (e.g., 80) 320 uint32 terminal height, rows (e.g., 24) 321 uint32 terminal width, pixels (e.g., 480) 322 uint32 terminal height, pixels (e.g., 640) 323 string encoded terminal modes 325 The encoding of terminal modes is described in Section ``Encoding of 326 Terminal Modes''. Zero dimension parameters MUST be ignored. The 327 character/row dimensions override the pixel dimensions (when nonzero). 328 Pixel dimensions refer to the drawable area of the window. 330 The dimension parameters are only informational. 332 The client SHOULD ignore pty requests. 334 4.3. X11 Forwarding 336 4.3.1. Requesting X11 Forwarding 338 X11 forwarding may be requested for a session by sending 340 byte SSH_MSG_CHANNEL_REQUEST 341 uint32 recipient channel 342 string "x11-req" 343 boolean want reply 344 boolean single connection 345 string x11 authentication protocol 346 string x11 authentication cookie 347 uint32 x11 screen number 349 It is recommended that the authentication cookie that is sent be a fake, 350 random cookie, and that the cookie is checked and replaced by the real 351 cookie when a connection request is received. 353 X11 connection forwarding should stop when the session channel is 354 closed; however, already opened forwardings should not be automatically 355 closed when the session channel is closed. 357 If `single connection' is TRUE, only a single connection should be 358 forwarded. No more connections will be forwarded after the first, or 359 after the session channel has been closed. 361 The `x11 authentication protocol' is the name of the X11 authentication 362 method used, i.e. "MIT-MAGIC-COOKIE-1". 364 X Protocol is documented in [SCHEIFLER]. 366 4.3.2. X11 Channels 368 X11 channels are opened with a channel open request. The resulting 369 channels are independent of the session, and closing the session channel 370 does not close the forwarded X11 channels. 372 byte SSH_MSG_CHANNEL_OPEN 373 string "x11" 374 uint32 sender channel 375 uint32 initial window size 376 uint32 maximum packet size 377 string originator address (e.g. "192.168.7.38") 378 uint32 originator port 380 The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or 381 SSH_MSG_CHANNEL_OPEN_FAILURE. 383 Implementations MUST reject any X11 channel open requests if they have 384 not requested X11 forwarding. 386 4.4. Environment Variable Passing 388 Environment variables may be passed to the shell/command to be started 389 later. Typically, each machine will have a preconfigured set of 390 variables that it will allow. Since uncontrolled setting of environment 391 variables can be very dangerous, it is recommended that implementations 392 allow setting only variables whose names have been explicitly configured 393 to be allowed. 395 byte SSH_MSG_CHANNEL_REQUEST 396 uint32 recipient channel 397 string "env" 398 boolean want reply 399 string variable name 400 string variable value 402 4.5. Starting a Shell or a Command 404 Once the session has been set up, a program is started at the remote 405 end. The program can be a shell, an application program or a subsystem 406 with a host-independent name. Only one of these requests can succeed 407 per channel. 409 byte SSH_MSG_CHANNEL_REQUEST 410 uint32 recipient channel 411 string "shell" 412 boolean want reply 414 This message will request the user's default shell (typically defined in 415 /etc/passwd in UNIX systems) to be started at the other end. 417 byte SSH_MSG_CHANNEL_REQUEST 418 uint32 recipient channel 419 string "exec" 420 boolean want reply 421 string command 423 This message will request the server to start the execution of the given 424 command. The command string may contain a path. Normal precautions MUST 425 be taken to prevent the execution of unauthorized commands. 427 byte SSH_MSG_CHANNEL_REQUEST 428 uint32 recipient channel 429 string "subsystem" 430 boolean want reply 431 string subsystem name 433 This last form executes a predefined subsystem. It is expected that 434 these will include a general file transfer mechanism, and possibly other 435 features. Implementations may also allow configuring more such 436 mechanisms. As the user's shell is usually used to execute the 437 subsystem, it is advisable for the subsystem protocol to have a "magic 438 cookie" at the beginning of the protocol transaction to distinguish from 439 arbitrary output from shell initialization scripts etc. This spurious 440 output from the shell may be filtered out either at the server or at the 441 client. 443 The server SHOULD not halt the execution of the protocol stack when 444 starting a shell or a program. All input and output from these SHOULD be 445 redirected to the channel or to the encrypted tunnel. 447 It is RECOMMENDED to request and check the reply for these messages. The 448 client SHOULD ignore these messages. 450 4.6. Session Data Transfer 452 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 453 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The 454 extended data type SSH_EXTENDED_DATA_STDERR has been defined for stderr 455 data. 457 4.7. Window Dimension Change Message 459 When the window (terminal) size changes on the client side, it MAY send 460 a message to the other side to inform it of the new dimensions. 462 byte SSH_MSG_CHANNEL_REQUEST 463 uint32 recipient_channel 464 string "window-change" 465 boolean FALSE 466 uint32 terminal width, columns 467 uint32 terminal height, rows 468 uint32 terminal width, pixels 469 uint32 terminal height, pixels 471 No response SHOULD be sent to this message. 473 4.8. Local Flow Control 475 On many systems, it is possible to determine if a pseudo-terminal is 476 using control-S/control-Q flow control. When flow control is allowed, 477 it is often desirable to do the flow control at the client end to speed 478 up responses to user requests. This is facilitated by the following 479 notification. Initially, the server is responsible for flow control. 480 (Here, again, client means the side originating the session, and server 481 means the other side.) 483 The message below is used by the server to inform the client when it can 484 or cannot perform flow control (control-S/control-Q processing). If 485 `client can do' is TRUE, the client is allowed to do flow control using 486 control-S and control-Q. The client MAY ignore this message. 488 byte SSH_MSG_CHANNEL_REQUEST 489 uint32 recipient channel 490 string "xon-xoff" 491 boolean FALSE 492 boolean client can do 494 No response is sent to this message. 496 4.9. Signals 498 A signal can be delivered to the remote process/service using the 499 following message. Some systems may not implement signals, in which 500 case they SHOULD ignore this message. 502 byte SSH_MSG_CHANNEL_REQUEST 503 uint32 recipient channel 504 string "signal" 505 boolean FALSE 506 string signal name without the "SIG" prefix. 508 Signal names will be encoded as discussed in the "exit-signal" 509 SSH_MSG_CHANNEL_REQUEST. 511 4.10. Returning Exit Status 513 When the command running at the other end terminates, the following 514 message can be sent to return the exit status of the command. Returning 515 the status is RECOMMENDED. No acknowledgment is sent for this message. 516 The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE after this 517 message. 519 The client MAY ignore these messages. 521 byte SSH_MSG_CHANNEL_REQUEST 522 uint32 recipient_channel 523 string "exit-status" 524 boolean FALSE 525 uint32 exit_status 527 The remote command may also terminate violently due to a signal. Such a 528 condition can be indicated by the following message. A zero exit_status 529 usually means that the command terminated successfully. 530 byte SSH_MSG_CHANNEL_REQUEST 531 uint32 recipient channel 532 string "exit-signal" 533 boolean FALSE 534 string signal name without the "SIG" prefix. 535 boolean core dumped 536 string error message (ISO-10646 UTF-8) 537 string language tag (as defined in [RFC-1766]) 539 The signal name is one of the following (these are from [POSIX]): 541 ABRT 542 ALRM 543 FPE 544 HUP 545 ILL 546 INT 547 KILL 548 PIPE 549 QUIT 550 SEGV 551 TERM 552 USR1 553 USR2 555 Additional signal names MAY be sent in the format "sig-name@xyz", where 556 `sig-name' and `xyz' may be anything a particular implementor wants 557 (except the `@' sign). However, it is suggested that if a `configure' 558 script is used, the non-standard signal names it finds be encoded as 559 "SIG@xyz.config.guess", where `SIG' is the signal name without the "SIG" 560 prefix, and `xyz' be the host type, as determined by `config.guess'. 562 The `error message' contains an additional explanation of the error 563 message. The message may consist of multiple lines. The client software 564 MAY display this message to the user. If this is done, the client 565 software should take the precautions discussed in [SSH-ARCH]. 567 5. TCP/IP Port Forwarding 569 5.1. Requesting Port Forwarding 571 A party need not explicitly request forwardings from its own end to the 572 other direction. However, if it wishes that connections to a port on 573 the other side be forwarded to the local side, it must explicitly 574 request this. 576 byte SSH_MSG_GLOBAL_REQUEST 577 string "tcpip-forward" 578 boolean want reply 579 string address to bind (e.g. "0.0.0.0") 580 uint32 port number to bind 582 `Address to bind' and `port number to bind' specify the IP address and 583 port to which the socket to be listened is bound. The address should be 584 "0.0.0.0" if connections are allowed from anywhere. (Note that the 585 client can still filter connections based on information passed in the 586 open request.) 588 Implementations should only allow forwarding privileged ports if the 589 user has been authenticated as a privileged user. 591 Client implementations SHOULD reject these messages; they are normally 592 only sent by the client. 594 A port forwarding can be cancelled with the following message. Note 595 that channel open requests may be received until a reply to this message 596 is received. 598 byte SSH_MSG_GLOBAL_REQUEST 599 string "cancel-tcpip-forward" 600 boolean want reply 601 string address_to_bind (e.g. "127.0.0.1") 602 uint32 port number to bind 604 Client implementations SHOULD reject these messages; they are normally 605 only sent by the client. 607 5.2. TCP/IP Forwarding Channels 609 When a connection comes to a port for which remote forwarding has been 610 requested, a channel is opened to forward the port to the other side. 612 byte SSH_MSG_CHANNEL_OPEN 613 string "forwarded-tcpip" 614 uint32 sender channel 615 uint32 initial window size 616 uint32 maximum packet size 617 string address that was connected 618 uint32 port that was connected 619 string originator IP address 620 uint32 originator port 622 Implementations MUST reject these messages unless they have previously 623 requested a remote TCP/IP port forwarding with the given port number. 625 When a connection comes to a locally forwarded TCP/IP port, the 626 following packet is sent to the other side. Note that these messages 627 MAY be sent also for ports for which no forwarding has been explicitly 628 requested. The receiving side must decide whether to allow the 629 forwarding. 631 byte SSH_MSG_CHANNEL_OPEN 632 string "direct-tcpip" 633 uint32 sender channel 634 uint32 initial window size 635 uint32 maximum packet size 636 string host to connect 637 uint32 port to connect 638 string originator IP address 639 uint32 originator port 641 `Host to connect' and `port to connect' specify the TCP/IP host and port 642 where the recipient should connect the channel. `Host to connect' may 643 be either a domain name or a numeric IP address. 645 `Originator IP address' is the numeric IP address of the machine where 646 the connection request comes from, and `originator port' is the port on 647 the originator host from where the connection came from. 649 Forwarded TCP/IP channels are independent of any sessions, and closing a 650 session channel does not in any way imply that forwarded connections 651 should be closed. 653 Client implementations SHOULD reject direct TCP/IP open requests for 654 security reasons. 656 6. Encoding of Terminal Modes 658 Terminal modes (as passed in a pty request) are encoded into a byte 659 stream. It is intended that the coding be portable across different 660 environments. 662 The tty mode description is a stream of bytes. The stream consists of 663 opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). 664 Opcodes 1 to 159 have a single uint32 argument. Opcodes 160 to 255 are 665 not yet defined, and cause parsing to stop (they should only be used 666 after any other data). 668 The client SHOULD put in the stream any modes it knows about, and the 669 server MAY ignore any modes it does not know about. This allows some 670 degree of machine-independence, at least between systems that use a 671 POSIX-like tty interface. The protocol can support other systems as 672 well, but the client may need to fill reasonable values for a number of 673 parameters so the server pty gets set to a reasonable mode (the server 674 leaves all unspecified mode bits in their default values, and only some 675 combinations make sense). 677 The following opcodes have been defined. The naming of opcodes mostly 678 follows the POSIX terminal mode flags. 680 0 TTY_OP_END Indicates end of options. 681 1 VINTR Interrupt character; 255 if none. Similarly for the 682 other characters. Not all of these characters are 683 supported on all systems. 684 2 VQUIT The quit character (sends SIGQUIT signal on POSIX 685 systems). 686 3 VERASE Erase the character to left of the cursor. 687 4 VKILL Kill the current input line. 688 5 VEOF End-of-file character (sends EOF from the terminal). 689 6 VEOL End-of-line character in addition to carriage return 690 and/or linefeed. 691 7 VEOL2 Additional end-of-line character. 692 8 VSTART Continues paused output (normally control-Q). 693 9 VSTOP Pauses output (normally control-S). 694 10 VSUSP Suspends the current program. 695 11 VDSUSP Another suspend character. 696 12 VREPRINT Reprints the current input line. 697 13 VWERASE Erases a word left of cursor. 698 14 VLNEXT Enter the next character typed literally, even if it 699 is a special character 700 15 VFLUSH Character to flush output. 701 16 VSWTCH Switch to a different shell layer. 702 17 VSTATUS Prints system status line (load, command, pid etc). 703 18 VDISCARD Toggles the flushing of terminal output. 704 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if 705 this flag is FALSE set, and 1 if it is TRUE. 706 31 PARMRK Mark parity and framing errors. 707 32 INPCK Enable checking of parity errors. 708 33 ISTRIP Strip 8th bit off characters. 709 34 INLCR Map NL into CR on input. 710 35 IGNCR Ignore CR on input. 711 36 ICRNL Map CR to NL on input. 712 37 IUCLC Translate uppercase characters to lowercase. 713 38 IXON Enable output flow control. 714 39 IXANY Any char will restart after stop. 715 40 IXOFF Enable input flow control. 716 41 IMAXBEL Ring bell on input queue full. 717 50 ISIG Enable signals INTR, QUIT, [D]SUSP. 718 51 ICANON Canonicalize input lines. 719 52 XCASE Enable input and output of uppercase characters by 720 preceding their lowercase equivalents with `\'. 721 53 ECHO Enable echoing. 722 54 ECHOE Visually erase chars. 723 55 ECHOK Kill character discards current line. 724 56 ECHONL Echo NL even if ECHO is off. 725 57 NOFLSH Don't flush after interrupt. 726 58 TOSTOP Stop background jobs from output. 727 59 IEXTEN Enable extensions. 728 60 ECHOCTL Echo control characters as ^(Char). 729 61 ECHOKE Visual erase for line kill. 730 62 PENDIN Retype pending input. 731 70 OPOST Enable output processing. 732 71 OLCUC Convert lowercase to uppercase. 734 72 ONLCR Map NL to CR-NL. 735 73 OCRNL Translate carriage return to newline (output). 736 74 ONOCR Translate newline to carriage return-newline 737 (output). 738 75 ONLRET Newline performs a carriage return (output). 739 90 CS7 7 bit mode. 740 91 CS8 8 bit mode. 741 92 PARENB Parity enable. 742 93 PARODD Odd parity, else even. 744 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second. 745 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second. 747 7. Summary of Message Numbers 749 #define SSH_MSG_GLOBAL_REQUEST 80 750 #define SSH_MSG_REQUEST_SUCCESS 81 751 #define SSH_MSG_REQUEST_FAILURE 82 752 #define SSH_MSG_CHANNEL_OPEN 90 753 #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 754 #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 755 #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 756 #define SSH_MSG_CHANNEL_DATA 94 757 #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 758 #define SSH_MSG_CHANNEL_EOF 96 759 #define SSH_MSG_CHANNEL_CLOSE 97 760 #define SSH_MSG_CHANNEL_REQUEST 98 761 #define SSH_MSG_CHANNEL_SUCCESS 99 762 #define SSH_MSG_CHANNEL_FAILURE 100 764 8. Security Considerations 766 This protocol is assumed to run on top of a secure, authenticated 767 transport. User authentication and protection against network-level 768 attacks are assumed to be provided by the underlying protocols. 770 This protocol can, however, be used to execute commands on remote 771 machines. The protocol also permits the server to run commands on the 772 client. Implementations may wish to disallow this to prevent an 773 attacker from coming from the server machine to the client machine. 775 X11 forwarding provides major security improvements over normal cookie- 776 based X11 forwarding. The cookie never needs to be transmitted in the 777 clear, and traffic is encrypted and integrity-protected. No useful 778 authentication data will remain on the server machine after the 779 connection has been closed. On the other hand, in some situations a 780 forwarded X11 connection might be used to get access to the local X 781 server across security perimeters. 782 Port forwardings can potentially allow an intruder to cross security 783 perimeters such as firewalls. They do not offer anything fundamentally 784 new that a user could not do otherwise; however, they make opening 785 tunnels very easy. Implementations should allow policy control over 786 what can be forwarded. Administrators should be able to deny 787 forwardings where appropriate. 789 Since this protocol normally runs inside an encrypted tunnel, firewalls 790 will not be able to examine the traffic. 792 It is RECOMMENDED that implementations disable all the potentially 793 dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP 794 forwarding) if the host key has changed. 796 9. Trademark Issues 798 SSH is a registered trademark and Secure Shell is a trademark of SSH 799 Communications Security Corp. SSH Communications Security Corp permits 800 the use of these trademarks as the name of this standard and protocol, 801 and permits their use to describe that a product conforms to this 802 standard, provided that the following acknowledgement is included where 803 the trademarks are used: ``SSH is a registered trademark and Secure 804 Shell is a trademark of SSH Communications Security Corp 805 (www.ssh.com)''. These trademarks may not be used as part of a product 806 name or in otherwise confusing manner without prior written permission 807 of SSH Communications Security Corp. 809 10. References 811 [RFC-1766] Alvestrand, H: "Tags for the Identification of Languages", 812 March 1995. 814 [RFC-1884] Hinden, R., and Deering, S: "IP Version 6 Addressing 815 Architecture", December 1995 817 [RFC-2279] Yergeau, F: "UTF-8, a transformation format of ISO 10646", 818 January 1998. 820 [SCHEIFLER] Scheifler, R. W., et al: "X Window System : The Complete 821 Reference to Xlib, X Protocol, Icccm, Xlfd", 3rd edition, Digital Press, 822 ISBN 1555580882, February 1992. 824 [POSIX] ISO/IEC Std 9945-1, ANSI/IEEE Std 1003.1 Information technology 825 -- Portable Operating System Interface (POSIX)-Part 1: System 826 Application Program Interface (API) [C Language], July 1996. 828 [SSH-ARCH] Ylonen, T., et al: "SSH Protocol Architecture", Internet- 829 Draft, draft-ietf-secsh-architecture-07.txt 830 [SSH-TRANS] Ylonen, T., et al: "SSH Transport Layer Protocol", Internet- 831 Draft, draft-ietf-secsh-transport-09.txt 833 [SSH-USERAUTH] Ylonen, T., et al: "SSH Authentication Protocol", 834 Internet-Draft, draft-ietf-secsh-userauth-09.txt 836 11. Authors' Addresses 838 Tatu Ylonen 839 SSH Communications Security Corp 840 Fredrikinkatu 42 841 FIN-00100 HELSINKI 842 Finland 843 E-mail: ylo@ssh.com 845 Tero Kivinen 846 SSH Communications Security Corp 847 Fredrikinkatu 42 848 FIN-00100 HELSINKI 849 Finland 850 E-mail: kivinen@ssh.com 852 Markku-Juhani O. Saarinen 853 University of Jyvaskyla 855 Timo J. Rinne 856 SSH Communications Security Corp 857 Fredrikinkatu 42 858 FIN-00100 HELSINKI 859 Finland 860 E-mail: tri@ssh.com 862 Sami Lehtinen 863 SSH Communications Security Corp 864 Fredrikinkatu 42 865 FIN-00100 HELSINKI 866 Finland 867 E-mail: sjl@ssh.com