idnits 2.17.1 draft-ietf-secsh-connect-11.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 Introduction section. (A line matching the expected section header was found, but with an unexpected indentation: ' 1. Introduction' ) ** The document seems to lack a Security Considerations section. (A line matching the expected section header was found, but with an unexpected indentation: ' 8. Security Considerations' ) ** 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.) ** 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 190: '...URE. The client MAY show the addition...' RFC 2119 keyword, line 211: '...sage, the recipient MAY send the given...' RFC 2119 keyword, line 223: '... parties MAY ignore all extra dat...' 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...' (27 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 112 has weird spacing: '... string req...' == Line 113 has weird spacing: '...boolean want...' == Line 151 has weird spacing: '... string cha...' == Line 185 has weird spacing: '... string add...' == Line 186 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 (July 20, 2001) is 8316 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) -- Missing reference section? 'SSH-ARCH' on line 875 looks like a reference -- Missing reference section? 'RFC2279' on line 862 looks like a reference -- Missing reference section? 'RFC1766' on line 856 looks like a reference -- Missing reference section? 'SCHEIFLER' on line 865 looks like a reference -- Missing reference section? 'POSIX' on line 870 looks like a reference -- Missing reference section? 'RFC1884' on line 859 looks like a reference -- Missing reference section? 'SSH-TRANS' on line 878 looks like a reference -- Missing reference section? 'SSH-USERAUTH' on line 881 looks like a reference -- Missing reference section? 'SSH-CONNECT' on line 884 looks like a reference Summary: 6 errors (**), 0 flaws (~~), 9 warnings (==), 12 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: January 18, 2002 SSH Communications Security Corp 5 M. Saarinen 6 University of Jyvaskyla 7 T. Rinne 8 S. Lehtinen 9 SSH Communications Security Corp 10 July 20, 2001 12 SSH Connection Protocol 13 draft-ietf-secsh-connect-11.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 26 months and may be updated, replaced, or obsoleted by other 27 documents at any time. It is inappropriate to use Internet-Drafts 28 as reference material or to cite them other than as "work in 29 progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on January 18, 2002. 39 Copyright Notice 41 Copyright (C) The Internet Society (2001). All Rights Reserved. 43 Abstract 45 SSH is a protocol for secure remote login and other secure network 46 services over an insecure network. 48 This document describes the SSH Connection Protocol. It provides 49 interactive login sessions, remote execution of commands, 50 forwarded TCP/IP connections, and forwarded X11 connections. All 51 of these channels are multiplexed into a single encrypted tunnel. 53 The SSH Connection Protocol has been designed to run on top of the 54 SSH transport layer and user authentication protocols. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Global Requests . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . 3 61 3.1 Opening a Channel . . . . . . . . . . . . . . . . . . . . . 4 62 3.2 Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 5 63 3.3 Closing a Channel . . . . . . . . . . . . . . . . . . . . . 6 64 3.4 Channel-Specific Requests . . . . . . . . . . . . . . . . . 7 65 4. Interactive Sessions . . . . . . . . . . . . . . . . . . . . 7 66 4.1 Opening a Session . . . . . . . . . . . . . . . . . . . . . 8 67 4.2 Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 8 68 4.3 X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 8 69 4.3.1 >Requesting X11 Forwarding . . . . . . . . . . . . . . . . . 8 70 4.3.2 >X11 Channels . . . . . . . . . . . . . . . . . . . . . . . 9 71 4.4 Environment Variable Passing . . . . . . . . . . . . . . . . 9 72 4.5 Starting a Shell or a Command . . . . . . . . . . . . . . . 10 73 4.6 Session Data Transfer . . . . . . . . . . . . . . . . . . . 11 74 4.7 Window Dimension Change Message . . . . . . . . . . . . . . 11 75 4.8 Local Flow Control . . . . . . . . . . . . . . . . . . . . . 11 76 4.9 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 12 77 4.10 Returning Exit Status . . . . . . . . . . . . . . . . . . . 12 78 5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . 13 79 5.1 Requesting Port Forwarding . . . . . . . . . . . . . . . . . 14 80 5.2 TCP/IP Forwarding Channels . . . . . . . . . . . . . . . . . 14 81 6. Encoding of Terminal Modes . . . . . . . . . . . . . . . . . 15 82 7. Summary of Message Numbers . . . . . . . . . . . . . . . . . 17 83 8. Security Considerations . . . . . . . . . . . . . . . . . . 18 84 9. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 18 85 10. Additional Information . . . . . . . . . . . . . . . . . . . 19 86 References . . . . . . . . . . . . . . . . . . . . . . . . . 19 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 20 88 Full Copyright Statement . . . . . . . . . . . . . . . . . . 21 90 1. Introduction 92 The SSH Connection Protocol has been designed to run on top of the 93 SSH transport layer and user authentication protocols. It 94 provides interactive login sessions, remote execution of commands, 95 forwarded TCP/IP connections, and forwarded X11 connections. The 96 service name for this protocol (after user authentication) is 97 "ssh-connection". 99 This document should be read only after reading the SSH 100 architecture document [SSH-ARCH]. This document freely uses 101 terminology and notation from the architecture document without 102 reference or further explanation. 104 2. Global Requests 106 There are several kinds of requests that affect the state of the 107 remote end "globally", independent of any channels. An example is 108 a request to start TCP/IP forwarding for a specific port. All 109 such requests use the following format. 111 byte SSH_MSG_GLOBAL_REQUEST 112 string request name (restricted to US-ASCII) 113 boolean want reply 114 ... request-specific data follows 116 The recipient will respond to this message with 117 SSH_MSG_REQUEST_SUCCESS, SSH_MSG_REQUEST_FAILURE, or some request- 118 specific continuation messages if `want reply' is TRUE. 120 byte SSH_MSG_REQUEST_SUCCESS 122 If the recipient does not recognize or support the request, it 123 simply responds with SSH_MSG_REQUEST_FAILURE. 125 byte SSH_MSG_REQUEST_FAILURE 127 3. Channel Mechanism 129 All terminal sessions, forwarded connections, etc. are channels. 130 Either side may open a channel. Multiple channels are multiplexed 131 into a single connection. 133 Channels are identified by numbers at each end. The number 134 referring to a channel may be different on each side. Requests to 135 open a channel contain the sender's channel number. Any other 136 channel-related messages contain the recipient's channel number 137 for the channel. 139 Channels are flow-controlled. No data may be sent to a channel 140 until a message is received to indicate that window space is 141 available. 143 3.1 Opening a Channel 145 When either side wishes to open a new channel, it allocates a 146 local number for the channel. It then sends the following message 147 to the other side, and includes the local channel number and 148 initial window size in the message. 150 byte SSH_MSG_CHANNEL_OPEN 151 string channel type (restricted to US-ASCII) 152 uint32 sender channel 153 uint32 initial window size 154 uint32 maximum packet size 155 ... channel type specific data follows 157 The channel type is a name as described in the SSH architecture 158 document, with similar extension mechanisms. `sender channel' is 159 a local identifier for the channel used by the sender of this 160 message. `initial window size' specifies how many bytes of 161 channel data can be sent to the sender of this message without 162 adjusting the window. `Maximum packet size' specifies the maximum 163 size of an individual data packet that can be sent to the sender 164 (for example, one might want to use smaller packets for 165 interactive connections to get better interactive response on slow 166 links). 168 The remote side then decides whether it can open the channel, and 169 responds with either 171 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 172 uint32 recipient channel 173 uint32 sender channel 174 uint32 initial window size 175 uint32 maximum packet size 176 ... channel type specific data follows 178 where `recipient channel' is the channel number given in the 179 original open request, and `sender channel' is the channel number 180 allocated by the other side, or 182 byte SSH_MSG_CHANNEL_OPEN_FAILURE 183 uint32 recipient channel 184 uint32 reason code 185 string additional textual information (ISO-10646 UTF-8 [RFC2279]) 186 string language tag (as defined in [RFC1766]) 188 If the recipient of the SSH_MSG_CHANNEL_OPEN message does not 189 support the specified channel type, it simply responds with 190 SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional 191 information to the user. If this is done, the client software 192 should take the precautions discussed in [SSH-ARCH]. 194 The following reason codes are defined: 196 #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 197 #define SSH_OPEN_CONNECT_FAILED 2 198 #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 199 #define SSH_OPEN_RESOURCE_SHORTAGE 4 201 3.2 Data Transfer 203 The window size specifies how many bytes the other party can send 204 before it must wait for the window to be adjusted. Both parties 205 use the following message to adjust the window. 207 byte SSH_MSG_CHANNEL_WINDOW_ADJUST 208 uint32 recipient channel 209 uint32 bytes to add 211 After receiving this message, the recipient MAY send the given 212 number of bytes more than it was previously allowed to send; the 213 window size is incremented. 215 Data transfer is done with messages of the following type. 217 byte SSH_MSG_CHANNEL_DATA 218 uint32 recipient channel 219 string data 221 The maximum amount of data allowed is the current window size. 222 The window size is decremented by the amount of data sent. Both 223 parties MAY ignore all extra data sent after the allowed window is 224 empty. 226 Additionally, some channels can transfer several types of data. 227 An example of this is stderr data from interactive sessions. Such 228 data can be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, 229 where a separate integer specifies the type of the data. The 230 available types and their interpretation depend on the type of the 231 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, 256 and more data may still be sent in the other direction. This 257 message does not consume window space and can be sent even if no 258 window space 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, 265 and 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 273 no window space is available. 275 It is recommended that any data sent before this message is 276 delivered 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 294 SSH_MSG_CHANNEL_SUCCESS or SSH_MSG_CHANNEL_FAILURE, or request- 295 specific continuation messages. If the request is not recognized 296 or is not supported for the channel, SSH_MSG_CHANNEL_FAILURE is 297 returned. 299 This message does not consume window space and can be sent even if 300 no window space is available. Request types are local to each 301 channel type. 303 The client is allowed to send further messages without waiting for 304 the response to the request. 306 byte SSH_MSG_CHANNEL_SUCCESS 307 uint32 recipient_channel 309 byte SSH_MSG_CHANNEL_FAILURE 310 uint32 recipient_channel 312 These messages do not consume window space and can be sent even if 313 no window space is available. 315 4. Interactive Sessions 317 A session is a remote execution of a program. The program may be 318 a shell, an application, a system command, or some built-in 319 subsystem. It may or may not have a tty, and may or may not 320 involve X11 forwarding. Multiple sessions can be active 321 simultaneously. 323 4.1 Opening a Session 325 A session is started by sending the following message. 327 byte SSH_MSG_CHANNEL_OPEN 328 string "session" 329 uint32 sender channel 330 uint32 initial window size 331 uint32 maximum packet size 333 Client implementations SHOULD reject any session channel open 334 requests to make it more difficult for a corrupt server to attack 335 the client. 337 4.2 Requesting a Pseudo-Terminal 339 A pseudo-terminal can be allocated for the session by sending the 340 following message. 342 byte SSH_MSG_CHANNEL_REQUEST 343 uint32 recipient_channel 344 string "pty-req" 345 boolean want_reply 346 string TERM environment variable value (e.g., vt100) 347 uint32 terminal width, characters (e.g., 80) 348 uint32 terminal height, rows (e.g., 24) 349 uint32 terminal width, pixels (e.g., 640) 350 uint32 terminal height, pixels (e.g., 480) 351 string encoded terminal modes 353 The encoding of terminal modes is described in Section Encoding of 354 Terminal Modes (Section 6). Zero dimension parameters MUST be 355 ignored. The character/row dimensions override the pixel 356 dimensions (when nonzero). Pixel dimensions refer to the drawable 357 area of the window. 359 The dimension parameters are only informational. 361 The client SHOULD ignore pty requests. 363 4.3 X11 Forwarding 365 4.3.1 >Requesting X11 Forwarding 367 X11 forwarding may be requested for a session by sending 369 byte SSH_MSG_CHANNEL_REQUEST 370 uint32 recipient channel 371 string "x11-req" 372 boolean want reply 373 boolean single connection 374 string x11 authentication protocol 375 string x11 authentication cookie 376 uint32 x11 screen number 378 It is recommended that the authentication cookie that is sent be a 379 fake, random cookie, and that the cookie is checked and replaced 380 by the real cookie when a connection request is received. 382 X11 connection forwarding should stop when the session channel is 383 closed; however, already opened forwardings should not be 384 automatically closed when the session channel is closed. 386 If `single connection' is TRUE, only a single connection should be 387 forwarded. No more connections will be forwarded after the first, 388 or after the session channel has been closed. 390 The `x11 authentication protocol' is the name of the X11 391 authentication method used, e.g. "MIT-MAGIC-COOKIE-1". 393 X Protocol is documented in [SCHEIFLER]. 395 4.3.2 >X11 Channels 397 X11 channels are opened with a channel open request. The 398 resulting channels are independent of the session, and closing the 399 session channel does not close the forwarded X11 channels. 401 byte SSH_MSG_CHANNEL_OPEN 402 string "x11" 403 uint32 sender channel 404 uint32 initial window size 405 uint32 maximum packet size 406 string originator address (e.g. "192.168.7.38") 407 uint32 originator port 409 The recipient should respond with 410 SSH_MSG_CHANNEL_OPEN_CONFIRMATION or SSH_MSG_CHANNEL_OPEN_FAILURE. 412 Implementations MUST reject any X11 channel open requests if they 413 have not requested X11 forwarding. 415 4.4 Environment Variable Passing 417 Environment variables may be passed to the shell/command to be 418 started later. Typically, each machine will have a preconfigured 419 set of variables that it will allow. Since uncontrolled setting 420 of environment variables can be very dangerous, it is recommended 421 that implementations allow setting only variables whose names have 422 been explicitly configured to be allowed. 424 byte SSH_MSG_CHANNEL_REQUEST 425 uint32 recipient channel 426 string "env" 427 boolean want reply 428 string variable name 429 string variable value 431 4.5 Starting a Shell or a Command 433 Once the session has been set up, a program is started at the 434 remote end. The program can be a shell, an application program or 435 a subsystem with a host-independent name. Only one of these 436 requests can succeed per channel. 438 byte SSH_MSG_CHANNEL_REQUEST 439 uint32 recipient channel 440 string "shell" 441 boolean want reply 443 This message will request the user's default shell (typically 444 defined in /etc/passwd in UNIX systems) to be started at the other 445 end. 447 byte SSH_MSG_CHANNEL_REQUEST 448 uint32 recipient channel 449 string "exec" 450 boolean want reply 451 string command 453 This message will request the server to start the execution of the 454 given command. The command string may contain a path. Normal 455 precautions MUST be taken to prevent the execution of unauthorized 456 commands. 458 byte SSH_MSG_CHANNEL_REQUEST 459 uint32 recipient channel 460 string "subsystem" 461 boolean want reply 462 string subsystem name 464 This last form executes a predefined subsystem. It is expected 465 that these will include a general file transfer mechanism, and 466 possibly other features. Implementations may also allow 467 configuring more such mechanisms. As the user's shell is usually 468 used to execute the subsystem, it is advisable for the subsystem 469 protocol to have a "magic cookie" at the beginning of the protocol 470 transaction to distinguish from arbitrary output from shell 471 initialization scripts etc. This spurious output from the shell 472 may be filtered out either at the server or at the client. 474 The server SHOULD not halt the execution of the protocol stack 475 when starting a shell or a program. All input and output from 476 these SHOULD be redirected to the channel or to the encrypted 477 tunnel. 479 It is RECOMMENDED to request and check the reply for these 480 messages. The client SHOULD ignore these messages. 482 4.6 Session Data Transfer 484 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 485 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. 486 The extended data type SSH_EXTENDED_DATA_STDERR has been defined 487 for stderr data. 489 4.7 Window Dimension Change Message 491 When the window (terminal) size changes on the client side, it MAY 492 send a message to the other side to inform it of the new 493 dimensions. 495 byte SSH_MSG_CHANNEL_REQUEST 496 uint32 recipient_channel 497 string "window-change" 498 boolean FALSE 499 uint32 terminal width, columns 500 uint32 terminal height, rows 501 uint32 terminal width, pixels 502 uint32 terminal height, pixels 504 No response SHOULD be sent to this message. 506 4.8 Local Flow Control 508 On many systems, it is possible to determine if a pseudo-terminal 509 is using control-S/control-Q flow control. When flow control is 510 allowed, it is often desirable to do the flow control at the 511 client end to speed up responses to user requests. This is 512 facilitated by the following notification. Initially, the server 513 is responsible for flow control. (Here, again, client means the 514 side originating the session, and server means the other side.) 516 The message below is used by the server to inform the client when 517 it can or cannot perform flow control (control-S/control-Q 518 processing). If `client can do' is TRUE, the client is allowed to 519 do flow control using control-S and control-Q. The client MAY 520 ignore this message. 522 byte SSH_MSG_CHANNEL_REQUEST 523 uint32 recipient channel 524 string "xon-xoff" 525 boolean FALSE 526 boolean client can do 528 No response is sent to this message. 530 4.9 Signals 532 A signal can be delivered to the remote process/service using the 533 following message. Some systems may not implement signals, in 534 which case they SHOULD ignore this message. 536 byte SSH_MSG_CHANNEL_REQUEST 537 uint32 recipient channel 538 string "signal" 539 boolean FALSE 540 string signal name without the "SIG" prefix. 542 Signal names will be encoded as discussed in the "exit-signal" 543 SSH_MSG_CHANNEL_REQUEST. 545 4.10 Returning Exit Status 547 When the command running at the other end terminates, the 548 following message can be sent to return the exit status of the 549 command. Returning the status is RECOMMENDED. No acknowledgment 550 is sent for this message. The channel needs to be closed with 551 SSH_MSG_CHANNEL_CLOSE after this message. 553 The client MAY ignore these messages. 555 byte SSH_MSG_CHANNEL_REQUEST 556 uint32 recipient_channel 557 string "exit-status" 558 boolean FALSE 559 uint32 exit_status 561 The remote command may also terminate violently due to a signal. 563 Such a condition can be indicated by the following message. A 564 zero exit_status usually means that the command terminated 565 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 594 implementor wants (except the `@' sign). However, it is suggested 595 that if a `configure' script is used, the non-standard signal 596 names it finds be encoded as "SIG@xyz.config.guess", where `SIG' 597 is the signal name without the "SIG" prefix, and `xyz' be the host 598 type, as determined by `config.guess'. 600 The `error message' contains an additional explanation of the 601 error message. The message may consist of multiple lines. The 602 client software MAY display this message to the user. If this is 603 done, the client software should take the precautions discussed in 604 [SSH-ARCH]. 606 5. TCP/IP Port Forwarding 607 5.1 Requesting Port Forwarding 609 A party need not explicitly request forwardings from its own end 610 to the other direction. However, if it wishes that connections to 611 a 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. 623 (Note that the client can still filter connections based on 624 information passed in the open request.) 626 Implementations should only allow forwarding privileged ports if 627 the 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 A port forwarding can be cancelled with the following message. 633 Note that channel open requests may be received until a reply to 634 this message is received. 636 byte SSH_MSG_GLOBAL_REQUEST 637 string "cancel-tcpip-forward" 638 boolean want reply 639 string address_to_bind (e.g. "127.0.0.1") 640 uint32 port number to bind 642 Client implementations SHOULD reject these messages; they are 643 normally only sent by the client. 645 5.2 TCP/IP Forwarding Channels 647 When a connection comes to a port for which remote forwarding has 648 been requested, a channel is opened to forward the port to the 649 other side. 651 byte SSH_MSG_CHANNEL_OPEN 652 string "forwarded-tcpip" 653 uint32 sender channel 654 uint32 initial window size 655 uint32 maximum packet size 656 string address that was connected 657 uint32 port that was connected 658 string originator IP address 659 uint32 originator port 661 Implementations MUST reject these messages unless they have 662 previously requested a remote TCP/IP port forwarding with the 663 given port number. 665 When a connection comes to a locally forwarded TCP/IP port, the 666 following packet is sent to the other side. Note that these 667 messages MAY be sent also for ports for which no forwarding has 668 been explicitly requested. The receiving side must decide whether 669 to allow the forwarding. 671 byte SSH_MSG_CHANNEL_OPEN 672 string "direct-tcpip" 673 uint32 sender channel 674 uint32 initial window size 675 uint32 maximum packet size 676 string host to connect 677 uint32 port to connect 678 string originator IP address 679 uint32 originator port 681 `Host to connect' and `port to connect' specify the TCP/IP host 682 and port where the recipient should connect the channel. `Host to 683 connect' may be either a domain name or a numeric IP address. 685 `Originator IP address' is the numeric IP address of the machine 686 where the connection request comes from, and `originator port' is 687 the port on the originator host from where the connection came 688 from. 690 Forwarded TCP/IP channels are independent of any sessions, and 691 closing a session channel does not in any way imply that forwarded 692 connections should be closed. 694 Client implementations SHOULD reject direct TCP/IP open requests 695 for security reasons. 697 6. Encoding of Terminal Modes 699 Terminal modes (as passed in a pty request) are encoded into a 700 byte stream. It is intended that the coding be portable across 701 different environments. 703 The tty mode description is a stream of bytes. The stream 704 consists of opcode-argument pairs. It is terminated by opcode 705 TTY_OP_END (0). Opcodes 1 to 159 have a single uint32 argument. 706 Opcodes 160 to 255 are not yet defined, and cause parsing to stop 707 (they should only be used after any other data). 709 The client SHOULD put in the stream any modes it knows about, and 710 the server MAY ignore any modes it does not know about. This 711 allows some degree of machine-independence, at least between 712 systems that use a POSIX-like tty interface. The protocol can 713 support other systems as well, but the client may need to fill 714 reasonable values for a number of parameters so the server pty 715 gets set to a reasonable mode (the server leaves all unspecified 716 mode bits in their default values, and only some combinations make 717 sense). 719 The following opcodes have been defined. The naming of opcodes 720 mostly follows the POSIX terminal mode flags. 722 0 TTY_OP_END Indicates end of options. 723 1 VINTR Interrupt character; 255 if none. Similarly for the 724 other characters. Not all of these characters are 725 supported on all systems. 726 2 VQUIT The quit character (sends SIGQUIT signal on POSIX 727 systems). 728 3 VERASE Erase the character to left of the cursor. 729 4 VKILL Kill the current input line. 730 5 VEOF End-of-file character (sends EOF from the terminal). 731 6 VEOL End-of-line character in addition to carriage return 732 and/or linefeed. 733 7 VEOL2 Additional end-of-line character. 734 8 VSTART Continues paused output (normally control-Q). 735 9 VSTOP Pauses output (normally control-S). 736 10 VSUSP Suspends the current program. 737 11 VDSUSP Another suspend character. 738 12 VREPRINT Reprints the current input line. 739 13 VWERASE Erases a word left of cursor. 740 14 VLNEXT Enter the next character typed literally, even if it 741 is a special character 742 15 VFLUSH Character to flush output. 743 16 VSWTCH Switch to a different shell layer. 744 17 VSTATUS Prints system status line (load, command, pid etc). 745 18 VDISCARD Toggles the flushing of terminal output. 746 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if 747 this flag is FALSE set, and 1 if it is TRUE. 748 31 PARMRK Mark parity and framing errors. 749 32 INPCK Enable checking of parity errors. 750 33 ISTRIP Strip 8th bit off characters. 752 34 INLCR Map NL into CR on input. 753 35 IGNCR Ignore CR on input. 754 36 ICRNL Map CR to NL on input. 755 37 IUCLC Translate uppercase characters to lowercase. 756 38 IXON Enable output flow control. 757 39 IXANY Any char will restart after stop. 758 40 IXOFF Enable input flow control. 759 41 IMAXBEL Ring bell on input queue full. 760 50 ISIG Enable signals INTR, QUIT, [D]SUSP. 761 51 ICANON Canonicalize input lines. 762 52 XCASE Enable input and output of uppercase characters by 763 preceding their lowercase equivalents with `\'. 764 53 ECHO Enable echoing. 765 54 ECHOE Visually erase chars. 766 55 ECHOK Kill character discards current line. 767 56 ECHONL Echo NL even if ECHO is off. 768 57 NOFLSH Don't flush after interrupt. 769 58 TOSTOP Stop background jobs from output. 770 59 IEXTEN Enable extensions. 771 60 ECHOCTL Echo control characters as ^(Char). 772 61 ECHOKE Visual erase for line kill. 773 62 PENDIN Retype pending input. 774 70 OPOST Enable output processing. 775 71 OLCUC Convert lowercase to uppercase. 776 72 ONLCR Map NL to CR-NL. 777 73 OCRNL Translate carriage return to newline (output). 778 74 ONOCR Translate newline to carriage return-newline 779 (output). 780 75 ONLRET Newline performs a carriage return (output). 781 90 CS7 7 bit mode. 782 91 CS8 8 bit mode. 783 92 PARENB Parity enable. 784 93 PARODD Odd parity, else even. 786 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second. 787 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second. 789 7. Summary of Message Numbers 791 #define SSH_MSG_GLOBAL_REQUEST 80 792 #define SSH_MSG_REQUEST_SUCCESS 81 793 #define SSH_MSG_REQUEST_FAILURE 82 794 #define SSH_MSG_CHANNEL_OPEN 90 795 #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 796 #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 797 #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 798 #define SSH_MSG_CHANNEL_DATA 94 799 #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 800 #define SSH_MSG_CHANNEL_EOF 96 801 #define SSH_MSG_CHANNEL_CLOSE 97 802 #define SSH_MSG_CHANNEL_REQUEST 98 803 #define SSH_MSG_CHANNEL_SUCCESS 99 804 #define SSH_MSG_CHANNEL_FAILURE 100 806 8. Security Considerations 808 This protocol is assumed to run on top of a secure, authenticated 809 transport. User authentication and protection against network- 810 level attacks are assumed to be provided by the underlying 811 protocols. 813 This protocol can, however, be used to execute commands on remote 814 machines. The protocol also permits the server to run commands on 815 the client. Implementations may wish to disallow this to prevent 816 an attacker from coming from the server machine to the client 817 machine. 819 X11 forwarding provides major security improvements over normal 820 cookie-based X11 forwarding. The cookie never needs to be 821 transmitted in the clear, and traffic is encrypted and integrity- 822 protected. No useful authentication data will remain on the 823 server machine after the connection has been closed. On the other 824 hand, in some situations a forwarded X11 connection might be used 825 to get access to the local X server across security perimeters. 827 Port forwardings can potentially allow an intruder to cross 828 security perimeters such as firewalls. They do not offer anything 829 fundamentally new that a user could not do otherwise; however, 830 they make opening tunnels very easy. Implementations should allow 831 policy control over what can be forwarded. Administrators should 832 be able to deny forwardings where appropriate. 834 Since this protocol normally runs inside an encrypted tunnel, 835 firewalls will not be able to examine the traffic. 837 It is RECOMMENDED that implementations disable all the potentially 838 dangerous features (e.g. agent forwarding, X11 forwarding, and 839 TCP/IP forwarding) if the host key has changed. 841 9. Trademark Issues 843 As of this writing, SSH Communications Security Oy claims ssh as 844 its trademark. As with all IPR claims the IETF takes no position 845 regarding the validity or scope of this trademark claim. 847 10. Additional Information 849 The current document editor is: Darren.Moffat@Sun.COM. Comments 850 on this internet draft should be sent to the IETF SECSH working 851 group, details at: http://ietf.org/html.charters/secsh- 852 charter.html 854 References 856 [RFC1766] Alvestrand, H., "Tags for the Identification of 857 Languages", RFC 1766, March 1995. 859 [RFC1884] Hinden, R., Deering, S. and Editors, "IP Version 6 860 Addressing Architecture", RFC 1884, December 1995. 862 [RFC2279] Yergeau, F., "UTF-8, a transformation format of 863 ISO 10646", RFC 2279, January 1998. 865 [SCHEIFLER] Scheifler, R., "X Window System : The Complete 866 Reference to Xlib, X Protocol, Icccm, Xlfd, 3rd 867 edition.", Digital Press ISBN 1555580882, Feburary 868 1992. 870 [POSIX] ISO/IEC, 9945-1., "Information technology -- 871 Portable Operating System Interface (POSIX)-Part 872 1: System Application Program Interface (API) C 873 Language", ANSI/IEE Std 1003.1, July 1996. 875 [SSH-ARCH] Ylonen, T., "SSH Protocol Architecture", I-D 876 draft-ietf-architecture-09.txt, July 2001. 878 [SSH-TRANS] Ylonen, T., "SSH Transport Layer Protocol", I-D 879 draft-ietf-transport-11.txt, July 2001. 881 [SSH-USERAUTH] Ylonen, T., "SSH Authentication Protocol", I-D 882 draft-ietf-userauth-11.txt, July 2001. 884 [SSH-CONNECT] Ylonen, T., "SSH Connection Protocol", I-D draft- 885 ietf-connect-11.txt, July 2001. 887 Authors' Addresses 889 Tatu Ylonen 890 SSH Communications Security Corp 891 Fredrikinkatu 42 892 HELSINKI FIN-00100 893 Finland 895 EMail: ylo@ssh.com 897 Tero Kivinen 898 SSH Communications Security Corp 899 Fredrikinkatu 42 900 HELSINKI FIN-00100 901 Finland 903 EMail: kivinen@ssh.com 905 Markku-Juhani O. Saarinen 906 University of Jyvaskyla 908 Timo J. Rinne 909 SSH Communications Security Corp 910 Fredrikinkatu 42 911 HELSINKI FIN-00100 912 Finland 914 EMail: tri@ssh.com 916 Sami Lehtinen 917 SSH Communications Security Corp 918 Fredrikinkatu 42 919 HELSINKI FIN-00100 920 Finland 922 EMail: sjl@ssh.com 924 Full Copyright Statement 926 Copyright (C) The Internet Society (2001). All Rights Reserved. 928 This document and translations of it may be copied and furnished 929 to others, and derivative works that comment on or otherwise 930 explain it or assist in its implementation may be prepared, 931 copied, published and distributed, in whole or in part, without 932 restriction of any kind, provided that the above copyright notice 933 and this paragraph are included on all such copies and derivative 934 works. However, this document itself may not be modified in any 935 way, such as by removing the copyright notice or references to the 936 Internet Society or other Internet organizations, except as needed 937 for the purpose of developing Internet standards in which case the 938 procedures for copyrights defined in the Internet Standards 939 process must be followed, or as required to translate it into 940 languages other than English. 942 The limited permissions granted above are perpetual and will not 943 be revoked by the Internet Society or its successors or assigns. 945 This document and the information contained herein is provided on 946 an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET 947 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR 948 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 949 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 950 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 952 Acknowledgement 954 Funding for the RFC Editor function is currently provided by the 955 Internet Society.