idnits 2.17.1 draft-ietf-secsh-connect-08.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: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. == 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 170: '...LURE. The client MAY show the addition...' RFC 2119 keyword, line 191: '...e, the recipient MAY send the given nu...' RFC 2119 keyword, line 202: '... amount of data sent. Both parties MAY...' RFC 2119 keyword, line 224: '...more data to a channel, it SHOULD send...' RFC 2119 keyword, line 237: '...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 164 has weird spacing: '... string add...' == Line 166 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 806, but no explicit reference was found in the text == Unused Reference: 'SSH-TRANS' is defined on line 823, but no explicit reference was found in the text == Unused Reference: 'SSH-USERAUTH' is defined on line 826, 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 2044 (Obsoleted by RFC 2279) -- 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-05 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-07 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-07 Summary: 8 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-08.txt M. Saarinen 4 Expires in six months T. Rinne 5 S. Lehtinen 6 SSH Communications Security 7 21 Nov, 2000 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 . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . . . . 9 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 150 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 151 uint32 recipient channel 152 uint32 sender channel 153 uint32 initial window size 154 uint32 maximum packet size 155 ... channel type specific data follows 157 where `recipient channel' is the channel number given in the original 158 open request, and `sender channel' is the channel number allocated by 159 the other side, or 161 byte SSH_MSG_CHANNEL_OPEN_FAILURE 162 uint32 recipient channel 163 uint32 reason code 164 string additional textual information (ISO-10646 UTF-8 165 [RFC-2044]) 166 string language tag (as defined in [RFC-1766]) 168 If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support 169 the specified channel type, it simply responds with 170 SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional 171 information to the user. If this is done, the client software should 172 take the precautions discussed in [SSH-ARCH]. 174 The following reason codes are defined: 176 #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 177 #define SSH_OPEN_CONNECT_FAILED 2 178 #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 179 #define SSH_OPEN_RESOURCE_SHORTAGE 4 181 3.2. Data Transfer 183 The window size specifies how many bytes the other party can send before 184 it must wait for the window to be adjusted. Both parties use the 185 following message to adjust the window. 187 byte SSH_MSG_CHANNEL_WINDOW_ADJUST 188 uint32 recipient channel 189 uint32 bytes to add 191 After receiving this message, the recipient MAY send the given number of 192 bytes more than it was previously allowed to send; the window size is 193 incremented. 195 Data transfer is done with messages of the following type. 197 byte SSH_MSG_CHANNEL_DATA 198 uint32 recipient channel 199 string data 201 The maximum amount of data allowed is the current window size. The 202 window size is decremented by the amount of data sent. Both parties MAY 203 ignore all extra data sent after the allowed window is empty. 205 Additionally, some channels can transfer several types of data. An 206 example of this is stderr data from interactive sessions. Such data can 207 be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a separate 208 integer specifies the type of the data. The available types and their 209 interpretation depend on the type of the channel. 211 byte SSH_MSG_CHANNEL_EXTENDED_DATA 212 uint32 recipient_channel 213 uint32 data_type_code 214 string data 216 Data sent with these messages consumes the same window as ordinary data. 218 Currently, only the following type is defined. 220 #define SSH_EXTENDED_DATA_STDERR 1 222 3.3. Closing a Channel 224 When a party will no longer send more data to a channel, it SHOULD send 225 SSH_MSG_CHANNEL_EOF. 227 byte SSH_MSG_CHANNEL_EOF 228 uint32 recipient_channel 230 No explicit response is sent to this message; however, the application 231 may send EOF to whatever is at the other end of the channel. Note that 232 the channel remains open after this message, and more data may still be 233 sent in the other direction. This message does not consume window space 234 and can be sent even if no window space is available. 236 When either party wishes to terminate the channel, it sends 237 SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST send 238 back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this message for 239 the channel. The channel is considered closed for a party when it has 240 both sent and received SSH_MSG_CHANNEL_CLOSE, and the party may then 241 reuse the channel number. A party MAY send SSH_MSG_CHANNEL_CLOSE 242 without having sent or received SSH_MSG_CHANNEL_EOF. 243 byte SSH_MSG_CHANNEL_CLOSE 244 uint32 recipient_channel 246 This message does not consume window space and can be sent even if no 247 window space is available. 249 It is recommended that any data sent before this message is delivered to 250 the actual destination, if possible. 252 3.4. Channel-Specific Requests 253 Many channel types have extensions that are specific to that particular 254 channel type. An example is requesting a pty (pseudo terminal) for an 255 interactive session. 257 All channel-specific requests use the following format. 259 byte SSH_MSG_CHANNEL_REQUEST 260 uint32 recipient channel 261 string request type (restricted to US-ASCII) 262 boolean want reply 263 ... type-specific data 265 If want reply is FALSE, no response will be sent to the request. 266 Otherwise, the recipient responds with either SSH_MSG_CHANNEL_SUCCESS or 267 SSH_MSG_CHANNEL_FAILURE, or request-specific continuation messages. If 268 the request is not recognized or is not supported for the channel, 269 SSH_MSG_CHANNEL_FAILURE is returned. 271 This message does not consume window space and can be sent even if no 272 window space is available. Request types are local to each channel type. 274 The client is allowed to send further messages without waiting for the 275 response to the request. 277 byte SSH_MSG_CHANNEL_SUCCESS 278 uint32 recipient_channel 280 byte SSH_MSG_CHANNEL_FAILURE 281 uint32 recipient_channel 283 These messages do not consume window space and can be sent even if no 284 window space is available. 285 4. Interactive Sessions 287 A session is a remote execution of a program. The program may be a 288 shell, an application, a system command, or some built-in subsystem. It 289 may or may not have a tty, and may or may not involve X11 forwarding. 290 Multiple sessions can be active simultaneously. 292 4.1. Opening a Session 294 A session is started by sending the following message. 296 byte SSH_MSG_CHANNEL_OPEN 297 string "session" 298 uint32 sender channel 299 uint32 initial window size 300 uint32 maximum packet size 302 Client implementations SHOULD reject any session channel open requests 303 to make it more difficult for a corrupt server to attack the client. 305 4.2. Requesting a Pseudo-Terminal 307 A pseudo-terminal can be allocated for the session by sending the 308 following message. 310 byte SSH_MSG_CHANNEL_REQUEST 311 uint32 recipient_channel 312 string "pty-req" 313 boolean want_reply 314 string TERM environment variable value (e.g., vt100) 315 uint32 terminal width, characters (e.g., 80) 316 uint32 terminal height, rows (e.g., 24) 317 uint32 terminal width, pixels (e.g., 480) 318 uint32 terminal height, pixels (e.g., 640) 319 string encoded terminal modes 321 The encoding of terminal modes is described in Section ``Encoding of 322 Terminal Modes''. Zero dimension parameters MUST be ignored. The 323 character/row dimensions override the pixel dimensions (when nonzero). 324 Pixel dimensions refer to the drawable area of the window. 326 The dimension parameters are only informational. 328 The client SHOULD ignore pty requests. 330 4.3. X11 Forwarding 332 4.3.1. Requesting X11 Forwarding 334 X11 forwarding may be requested for a session by sending 336 byte SSH_MSG_CHANNEL_REQUEST 337 uint32 recipient channel 338 string "x11-req" 339 boolean want reply 340 boolean single connection 341 string x11 authentication protocol 342 string x11 authentication cookie 343 uint32 x11 screen number 345 It is recommended that the authentication cookie that is sent be a fake, 346 random cookie, and that the cookie is checked and replaced by the real 347 cookie when a connection request is received. 349 X11 connection forwarding should stop when the session channel is 350 closed; however, already opened forwardings should not be automatically 351 closed when the session channel is closed. 353 If `single connection' is TRUE, only a single connection should be 354 forwarded. No more connections will be forwarded after the first, or 355 after the session channel has been closed. 357 `X11 authentication protocol is the name of the X11 authentication 358 method used, i.e. "MIT-MAGIC-COOKIE-1". 360 X Protocol is documented in [Scheifler]. 362 4.3.2. X11 Channels 364 X11 channels are opened with a channel open request. The resulting 365 channels are independent of the session, and closing the session channel 366 does not close the forwarded X11 channels. 368 byte SSH_MSG_CHANNEL_OPEN 369 string "x11" 370 uint32 sender channel 371 uint32 initial window size 372 uint32 maximum packet size 373 string originator address (e.g. "192.168.7.38") 374 uint32 originator port 376 The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or 377 SSH_MSG_CHANNEL_OPEN_FAILURE. 379 Implementations MUST reject any X11 channel open requests if they have 380 not requested X11 forwarding. 382 4.4. Environment Variable Passing 384 Environment variables may be passed to the shell/command to be started 385 later. Typically, each machine will have a preconfigured set of 386 variables that it will allow. Since uncontrolled setting of environment 387 variables can be very dangerous, it is recommended that implementations 388 allow setting only variables whose names have been explicitly configured 389 to be allowed. 391 byte SSH_MSG_CHANNEL_REQUEST 392 uint32 recipient channel 393 string "env" 394 boolean want reply 395 string variable name 396 string variable value 398 4.5. Starting a Shell or a Command 400 Once the session has been set up, a program is started at the remote 401 end. The program can be a shell, an application program or a subsystem 402 with a host-independent name. Only one of these requests can succeed 403 per channel. 405 byte SSH_MSG_CHANNEL_REQUEST 406 uint32 recipient channel 407 string "shell" 408 boolean want reply 410 This message will request the user's default shell (typically defined in 411 /etc/passwd in UNIX systems) to be started at the other end. 412 byte SSH_MSG_CHANNEL_REQUEST 413 uint32 recipient channel 414 string "exec" 415 boolean want reply 416 string command 418 This message will request the server to start the execution of the given 419 command. The command string may contain a path. Normal precautions MUST 420 be taken to prevent the execution of unauthorized commands. 422 byte SSH_MSG_CHANNEL_REQUEST 423 uint32 recipient channel 424 string "subsystem" 425 boolean want reply 426 string subsystem name 428 This last form executes a predefined subsystem. It expected that these 429 will include a general file transfer mechanism, and possibly other 430 features. Implementations may also allow configuring more such 431 mechanisms. 433 The server SHOULD not halt the execution of the protocol stack when 434 starting a shell or a program. All input and output from these SHOULD be 435 redirected to the channel or to the encrypted tunnel. 437 It is RECOMMENDED to request and check the reply for these messages. The 438 client SHOULD ignore these messages. 440 4.6. Session Data Transfer 442 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 443 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The 444 extended data type SSH_EXTENDED_DATA_STDERR has been defined for stderr 445 data. 447 4.7. Window Dimension Change Message 449 When the window (terminal) size changes on the client side, it MAY send 450 a message to the other side to inform it of the new dimensions. 452 byte SSH_MSG_CHANNEL_REQUEST 453 uint32 recipient_channel 454 string "window-change" 455 boolean FALSE 456 uint32 terminal width, columns 457 uint32 terminal height, rows 458 uint32 terminal width, pixels 459 uint32 terminal height, pixels 461 No response SHOULD be sent to this message. 463 4.8. Local Flow Control 465 On many systems, it is possible to determine if a pseudo-terminal is 466 using control-S/control-Q flow control. When flow control is allowed, 467 it is often desirable to do the flow control at the client end to speed 468 up responses to user requests. This is facilitated by the following 469 notification. Initially, the server is responsible for flow control. 470 (Here, again, client means the side originating the session, and server 471 means the other side.) 473 The message below is used by the server to inform the client when it can 474 or cannot perform flow control (control-S/control-Q processing). If 475 `client can do' is TRUE, the client is allowed to do flow control using 476 control-S and control-Q. The client MAY ignore this message. 478 byte SSH_MSG_CHANNEL_REQUEST 479 uint32 recipient channel 480 string "xon-xoff" 481 boolean FALSE 482 boolean client can do 484 No response is sent to this message. 486 4.9. Signals 488 A signal can be delivered to the remote process/service using the 489 following message. Some systems may not implement signals, in which 490 case they SHOULD ignore this message. 492 byte SSH_MSG_CHANNEL_REQUEST 493 uint32 recipient channel 494 string "signal" 495 boolean FALSE 496 string signal name without the "SIG" prefix. 498 Signal names will be encoded as discussed in the "exit-signal" 499 SSH_MSG_CHANNEL_REQUEST. 501 4.10. Returning Exit Status 503 When the command running at the other end terminates, the following 504 message can be sent to return the exit status of the command. Returning 505 the status is RECOMMENDED. No acknowledgment is sent for this message. 506 The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE after this 507 message. 509 The client MAY ignore these messages. 511 byte SSH_MSG_CHANNEL_REQUEST 512 uint32 recipient_channel 513 string "exit-status" 514 boolean FALSE 515 uint32 exit_status 517 The remote command may also terminate violently due to a signal. Such a 518 condition can be indicated by the following message. A zero exit_status 519 usually means that the command terminated successfully. 521 byte SSH_MSG_CHANNEL_REQUEST 522 uint32 recipient channel 523 string "exit-signal" 524 boolean FALSE 525 string signal name without the "SIG" prefix. 526 boolean core dumped 527 string error message (ISO-10646 UTF-8 [RFC-2044]) 528 string language tag (as defined in [RFC-1766]) 530 The signal name is one of the following (these are from [POSIX]): 532 ABRT 533 ALRM 534 FPE 535 HUP 536 ILL 537 INT 538 KILL 539 PIPE 540 QUIT 541 SEGV 542 TERM 543 USR1 544 USR2 546 Additional signal names MAY be sent in the format "sig-name@xyz", where 547 `sig-name' and `xyz' may be anything a particular implementor wants 548 (except the `@' sign). However, it is suggested that if a `configure' 549 script is used, the non-standard signal names it finds be encoded as 550 "SIG@xyz.config.guess", where `SIG' is the signal name without the "SIG" 551 prefix, and `xyz' be the host type, as determined by `config.guess'. 553 The `error message' contains an additional explanation of the error 554 message. The message may consist of multiple lines. The client software 555 MAY display this message to the user. If this is done, the client 556 software should take the precautions discussed in [SSH-ARCH]. 558 5. TCP/IP Port Forwarding 560 5.1. Requesting Port Forwarding 562 A party need not explicitly request forwardings from its own end to the 563 other direction. However, if it wishes that connections to a port on 564 the other side be forwarded to the local side, it must explicitly 565 request this. 567 byte SSH_MSG_GLOBAL_REQUEST 568 string "tcpip-forward" 569 boolean want reply 570 string address to bind (e.g. "0.0.0.0") 571 uint32 port number to bind 573 `Address to bind' and `port number to bind' specify the IP address and 574 port to which the socket to be listened is bound. The address should be 575 "0.0.0.0" if connections are allowed from anywhere. (Note that the 576 client can still filter connections based on information passed in the 577 open request.) 579 Implementations should only allow forwarding privileged ports if the 580 user has been authenticated as a privileged user. 582 Client implementations SHOULD reject these messages; they are normally 583 only sent by the client. 585 A port forwarding can be cancelled with the following message. Note 586 that channel open requests may be received until a reply to this message 587 is received. 589 byte SSH_MSG_GLOBAL_REQUEST 590 string "cancel-tcpip-forward" 591 boolean want reply 592 string address_to_bind (e.g. "127.0.0.1") 593 uint32 port number to bind 595 Client implementations SHOULD reject these messages; they are normally 596 only sent by the client. 598 5.2. TCP/IP Forwarding Channels 600 When a connection comes to a port for which remote forwarding has been 601 requested, a channel is opened to forward the port to the other side. 603 byte SSH_MSG_CHANNEL_OPEN 604 string "forwarded-tcpip" 605 uint32 sender channel 606 uint32 initial window size 607 uint32 maximum packet size 608 string address that was connected 609 uint32 port that was connected 610 string originator IP address 611 uint32 originator port 613 Implementations MUST reject these messages unless they have previously 614 requested a remote TCP/IP port forwarding with the given port number. 616 When a connection comes to a locally forwarded TCP/IP port, the 617 following packet is sent to the other side. Note that these messages 618 MAY be sent also for ports for which no forwarding has been explicitly 619 requested. The receiving side must decide whether to allow the 620 forwarding. 622 byte SSH_MSG_CHANNEL_OPEN 623 string "direct-tcpip" 624 uint32 sender channel 625 uint32 initial window size 626 uint32 maximum packet size 627 string host to connect 628 uint32 port to connect 629 string originator IP address 630 uint32 originator port 632 `Host to connect' and `port to connect' specify the TCP/IP host and port 633 where the recipient should connect the channel. `Host to connect' may 634 be either a domain name or a numeric IP address. 636 `Originator IP address' is the numeric IP address of the machine where 637 the connection request comes from, and `originator port' is the port on 638 the originator host from where the connection came from. 640 Forwarded TCP/IP channels are independent of any sessions, and closing a 641 session channel does not in any way imply that forwarded connections 642 should be closed. 644 Client implementations SHOULD reject direct TCP/IP open requests for 645 security reasons. 647 6. Encoding of Terminal Modes 649 Terminal modes (as passed in a pty request) are encoded into a byte 650 stream. It is intended that the coding be portable across different 651 environments. 653 The tty mode description is a stream of bytes. The stream consists of 654 opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). 655 Opcodes 1 to 159 have a single uint32 argument. Opcodes 160 to 255 are 656 not yet defined, and cause parsing to stop (they should only be used 657 after any other data). 659 The client SHOULD put in the stream any modes it knows about, and the 660 server MAY ignore any modes it does not know about. This allows some 661 degree of machine-independence, at least between systems that use a 662 POSIX-like tty interface. The protocol can support other systems as 663 well, but the client may need to fill reasonable values for a number of 664 parameters so the server pty gets set to a reasonable mode (the server 665 leaves all unspecified mode bits in their default values, and only some 666 combinations make sense). 668 The following opcodes have been defined. The naming of opcodes mostly 669 follows the POSIX terminal mode flags. 671 0 TTY_OP_END Indicates end of options. 672 1 VINTR Interrupt character; 255 if none. Similarly for the 673 other characters. Not all of these characters are 674 supported on all systems. 675 2 VQUIT The quit character (sends SIGQUIT signal on POSIX 676 systems). 677 3 VERASE Erase the character to left of the cursor. 678 4 VKILL Kill the current input line. 679 5 VEOF End-of-file character (sends EOF from the terminal). 680 6 VEOL End-of-line character in addition to carriage return 681 and/or linefeed. 682 7 VEOL2 Additional end-of-line character. 683 8 VSTART Continues paused output (normally control-Q). 684 9 VSTOP Pauses output (normally control-S). 685 10 VSUSP Suspends the current program. 686 11 VDSUSP Another suspend character. 687 12 VREPRINT Reprints the current input line. 688 13 VWERASE Erases a word left of cursor. 689 14 VLNEXT Enter the next character typed literally, even if it 690 is a special character 691 15 VFLUSH Character to flush output. 692 16 VSWTCH Switch to a different shell layer. 693 17 VSTATUS Prints system status line (load, command, pid etc). 694 18 VDISCARD Toggles the flushing of terminal output. 695 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if 696 this flag is FALSE set, and 1 if it is TRUE. 697 31 PARMRK Mark parity and framing errors. 698 32 INPCK Enable checking of parity errors. 699 33 ISTRIP Strip 8th bit off characters. 700 34 INLCR Map NL into CR on input. 701 35 IGNCR Ignore CR on input. 702 36 ICRNL Map CR to NL on input. 703 37 IUCLC Translate uppercase characters to lowercase. 704 38 IXON Enable output flow control. 705 39 IXANY Any char will restart after stop. 706 40 IXOFF Enable input flow control. 707 41 IMAXBEL Ring bell on input queue full. 708 50 ISIG Enable signals INTR, QUIT, [D]SUSP. 709 51 ICANON Canonicalize input lines. 710 52 XCASE Enable input and output of uppercase characters by 711 preceding their lowercase equivalents with `\'. 712 53 ECHO Enable echoing. 713 54 ECHOE Visually erase chars. 714 55 ECHOK Kill character discards current line. 715 56 ECHONL Echo NL even if ECHO is off. 716 57 NOFLSH Don't flush after interrupt. 717 58 TOSTOP Stop background jobs from output. 718 59 IEXTEN Enable extensions. 719 60 ECHOCTL Echo control characters as ^(Char). 720 61 ECHOKE Visual erase for line kill. 721 62 PENDIN Retype pending input. 722 70 OPOST Enable output processing. 723 71 OLCUC Convert lowercase to uppercase. 724 72 ONLCR Map NL to CR-NL. 725 73 OCRNL Translate carriage return to newline (output). 726 74 ONOCR Translate newline to carriage return-newline 727 (output). 728 75 ONLRET Newline performs a carriage return (output). 730 90 CS7 7 bit mode. 731 91 CS8 8 bit mode. 732 92 PARENB Parity enable. 733 93 PARODD Odd parity, else even. 735 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second. 736 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second. 738 7. Summary of Message Numbers 740 #define SSH_MSG_GLOBAL_REQUEST 80 741 #define SSH_MSG_REQUEST_SUCCESS 81 742 #define SSH_MSG_REQUEST_FAILURE 82 743 #define SSH_MSG_CHANNEL_OPEN 90 744 #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 745 #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 746 #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 747 #define SSH_MSG_CHANNEL_DATA 94 748 #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 749 #define SSH_MSG_CHANNEL_EOF 96 750 #define SSH_MSG_CHANNEL_CLOSE 97 751 #define SSH_MSG_CHANNEL_REQUEST 98 752 #define SSH_MSG_CHANNEL_SUCCESS 99 753 #define SSH_MSG_CHANNEL_FAILURE 100 755 8. Security Considerations 757 This protocol is assumed to run on top of a secure, authenticated 758 transport. User authentication and protection against network-level 759 attacks are assumed to be provided by the underlying protocols. 761 This protocol can, however, be used to execute commands on remote 762 machines. The protocol also permits the server to run commands on the 763 client. Implementations may wish to disallow this to prevent an 764 attacker from coming from the server machine to the client machine. 766 X11 forwarding provides major security improvements over normal cookie- 767 based X11 forwarding. The cookie never needs to be transmitted in the 768 clear, and traffic is encrypted and integrity-protected. No useful 769 authentication data will remain on the server machine after the 770 connection has been closed. On the other hand, in some situations a 771 forwarded X11 connection might be used to get access to the local X 772 server across security perimeters. 774 Port forwardings can potentially allow an intruder to cross security 775 perimeters such as firewalls. They do not offer anything fundamentally 776 new that a user could not do otherwise; however, they make opening 777 tunnels very easy. Implementations should allow policy control over 778 what can be forwarded. Administrators should be able to deny 779 forwardings where appropriate. 781 Since this protocol normally runs inside an encrypted tunnel, firewalls 782 will not be able to examine the traffic. 784 It is RECOMMENDED that implementations disable all the potentially 785 dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP 786 forwarding) if the host key has changed. 788 9. Trademark Issues 790 SSH is a registered trademark and Secure Shell is a trademark of SSH 791 Communications Security Corp. SSH Communications Security Corp permits 792 the use of these trademarks as the name of this standard and protocol, 793 and permits their use to describe that a product conforms to this 794 standard, provided that the following acknowledgement is included where 795 the trademarks are used: ``SSH is a registered trademark and Secure 796 Shell is a trademark of SSH Communications Security Corp 797 (www.ssh.com)''. These trademarks may not be used as part of a product 798 name or in otherwise confusing manner without prior written permission 799 of SSH Communications Security Corp. 801 10. References 803 [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages", 804 March 1995. 806 [RFC-1884] Hinden, R., and Deering, S., "IP Version 6 Addressing 807 Architecture", December 1995 809 [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and 810 ISO 10646", October 1996. 812 [Scheifler] Scheifler, R. W., et al, "X Window System : The Complete 813 Reference to Xlib, X Protocol, Icccm, Xlfd", 3rd edition, Digital Press, 814 ISBN 1555580882, February 1992. 816 [POSIX] ISO/IEC Std 9945-1, ANSI/IEEE Std 1003.1 Information 817 technology-- Portable Operating System Interface (POSIX)-Part 1: System 818 Application Program Interface (API) [C Language], July 1996. 820 [SSH-ARCH] Ylonen, T., et al, "SSH Protocol Architecture", Internet 821 Draft, draft-ietf-secsh-architecture-05.txt 823 [SSH-TRANS] Ylonen, T., et al, "SSH Transport Layer Protocol", Internet 824 Draft, draft-ietf-secsh-transport-07.txt 826 [SSH-USERAUTH] Ylonen, T., et al, "SSH Authentication Protocol", 827 Internet Draft, draft-ietf-secsh-userauth-07.txt 829 11. Authors' Addresses 831 Tatu Ylonen 832 SSH Communications Security Corp 833 Fredrikinkatu 42 834 FIN-00100 HELSINKI 835 Finland 836 E-mail: ylo@ssh.com 837 Tero Kivinen 838 SSH Communications Security Corp 839 Fredrikinkatu 42 840 FIN-00100 HELSINKI 841 Finland 842 E-mail: kivinen@ssh.com 844 Markku-Juhani O. Saarinen 845 University of Jyvaskyla 847 Timo J. Rinne 848 SSH Communications Security Corp 849 Fredrikinkatu 42 850 FIN-00100 HELSINKI 851 Finland 852 E-mail: tri@ssh.com 854 Sami Lehtinen 855 SSH Communications Security Corp 856 Fredrikinkatu 42 857 FIN-00100 HELSINKI 858 Finland 859 E-mail: sjl@ssh.com