idnits 2.17.1 draft-ietf-secsh-connect-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. 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. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == 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 169: '...LURE. The client MAY show the addition...' RFC 2119 keyword, line 190: '...e, the recipient MAY send the given nu...' RFC 2119 keyword, line 201: '... amount of data sent. Both parties MAY...' RFC 2119 keyword, line 223: '...more data to a channel, it SHOULD send...' RFC 2119 keyword, line 236: '...eiving this message, a party MUST send...' (27 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 94 has weird spacing: '... string req...' == Line 95 has weird spacing: '...boolean want...' == Line 131 has weird spacing: '... string cha...' == Line 163 has weird spacing: '... string add...' == Line 165 has weird spacing: '... string lan...' == (32 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 the 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 (7 November 1997) is 9666 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: 'SSH-AGENT' is mentioned on line 384, but not defined == Unused Reference: 'RFC-1766' is defined on line 798, but no explicit reference was found in the text == Unused Reference: 'RFC-1884' is defined on line 801, but no explicit reference was found in the text == Unused Reference: 'RFC-2044' is defined on line 804, but no explicit reference was found in the text == Unused Reference: 'SSH-TRANS' is defined on line 810, but no explicit reference was found in the text == Unused Reference: 'SSH-USERAUTH' is defined on line 813, 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) == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-00 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-02 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-02 Summary: 12 errors (**), 0 flaws (~~), 17 warnings (==), 3 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-03.txt M. Saarinen 4 Expires in six months SSH 5 7 November 1997 7 SSH Connection Protocol 9 Status of This memo 11 This document is an Internet-Draft. Internet-Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its areas, 13 and its working groups. Note that other groups may also distribute 14 working documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six 17 months and may be updated, replaced, or obsoleted by other documents 18 at any time. It is inappropriate to use Internet-Drafts as reference 19 material or to cite them other than as ``work in progress.'' 21 To learn the current status of any Internet-Draft, please check 22 the ``1id-abstracts.txt'' listing contained in the Internet-Drafts 23 Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 24 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), 25 or ftp.isi.edu (US West Coast). 27 Abstract 29 SSH is a protocol for secure remote login and other secure network 30 services over an insecure network. 32 This document describes the SSH connection protocol. It provides 33 interactive login sessions, remote execution of commands, forwarded 34 TCP/IP connections, and forwarded X11 connections. All of these 35 channels are multiplexed into a single encrypted tunnel. 37 The SSH Connection Protocol has been designed to run on top of 38 the SSH transport layer and user authentication protocols. 40 Table of Contents 42 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 43 2. Global Requests . . . . . . . . . . . . . . . . . . . . . . . . 2 44 3. Channel Mechanism . . . . . . . . . . . . . . . . . . . . . . . 3 45 3.1. Opening a Channel . . . . . . . . . . . . . . . . . . . . . 3 46 3.2. Data Transfer . . . . . . . . . . . . . . . . . . . . . . . 4 47 3.3. Closing a Channel . . . . . . . . . . . . . . . . . . . . . 5 48 3.4. Channel-Specific Requests . . . . . . . . . . . . . . . . . 6 49 4. Interactive Sessions . . . . . . . . . . . . . . . . . . . . . . 6 50 4.1. Opening a Session . . . . . . . . . . . . . . . . . . . . . 6 51 4.2. Requesting a Pseudo-Terminal . . . . . . . . . . . . . . . . 7 52 4.3. X11 Forwarding . . . . . . . . . . . . . . . . . . . . . . . 7 53 4.3.1. Requesting X11 Forwarding . . . . . . . . . . . . . . . 7 54 4.3.2. X11 Channels . . . . . . . . . . . . . . . . . . . . . . 8 55 4.4. Authentication Agent Forwarding . . . . . . . . . . . . . . 8 56 4.4.1. Requesting Authentication Agent Forwarding . . . . . . . 8 57 4.4.2. Authentication Agent Channels . . . . . . . . . . . . . 8 58 4.5. Environment Variable Passing . . . . . . . . . . . . . . . . 9 59 4.6. Starting a Shell or a Command . . . . . . . . . . . . . . . 9 60 4.7. Session Data Transfer . . . . . . . . . . . . . . . . . . . 10 61 4.8. Window Dimension Change Message . . . . . . . . . . . . . . 10 62 4.9. Local Flow Control . . . . . . . . . . . . . . . . . . . . . 10 63 4.10. Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 11 64 4.11. Returning Exit Status . . . . . . . . . . . . . . . . . . . 11 65 5. TCP/IP Port Forwarding . . . . . . . . . . . . . . . . . . . . . 11 66 5.1. Requesting Port Forwarding . . . . . . . . . . . . . . . . . 12 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. References . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 72 10. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 16 74 1. Introduction 76 The SSH Connection Protocol has been designed to run on top of the SSH 77 transport layer and user authentication protocols. It provides 78 interactive login sessions, remote execution of commands, forwarded 79 TCP/IP connections, and forwarded X11 connections. The service name for 80 this protocol (after user authentication) is "ssh-connection". 82 This document should be read only after reading the SSH architecture 83 document [SSH-ARCH]. This document freely uses terminology and notation 84 from the architecture document without reference or further explanation. 86 2. Global Requests 88 There are several kinds of requests that affect the state of the remote 89 end "globally", independent of any channels. An example is a request to 90 start TCP/IP forwarding for a specific port. All such requests use the 91 following format. 93 byte SSH_MSG_GLOBAL_REQUEST 94 string request name (restricted to US-ASCII) 95 boolean want reply 96 ... request-specific data follows 98 The recipient will respond to this message with SSH_MSG_REQUEST_SUCCESS, 99 SSH_MSG_REQUEST_FAILURE, or some request-specific continuation messages 100 if `want reply' is TRUE. 102 byte SSH_MSG_REQUEST_SUCCESS 104 If the recipient does not recognize or support the request, it simply 105 responds with SSH_MSG_REQUEST_FAILURE. 107 byte SSH_MSG_REQUEST_FAILURE 109 3. Channel Mechanism 111 All terminal sessions, forwarded connections, etc. are channels. Either 112 side may open a channel. Multiple channels are multiplexed into a 113 single connection. 115 Channels are identified by numbers at each end. The number referring to 116 a channel may be different on each side. Requests to open a channel 117 contain the sender's channel number. Any other channel-related messages 118 contain the recipient's channel number for the channel. 120 Channels are flow-controlled. No data may be sent to a channel until a 121 message is received to indicate that window space is available. 123 3.1. Opening a Channel 125 When either side wishes to open a new channel, it allocates a local 126 number for the channel. It then sends the following message to the 127 other side, and includes the local channel number and initial window 128 size in the message. 130 byte SSH_MSG_CHANNEL_OPEN 131 string channel type (restricted to US-ASCII) 132 uint32 sender channel 133 uint32 initial window size 134 uint32 maximum packet size 135 ... channel type specific data follows 137 The channel type is a name as described in the SSH architecture 138 document, with similar extension mechanisms. `sender channel' is a local 139 identifier for the channel used by the sender of this message. `initial 140 window size' specifies how many bytes of channel data can be sent to the 141 sender of this message without adjusting the window. `Maximum packet 142 size' specifies the maximum size of an individual data packet that can 143 be sent to the sender (for example, one might want to use smaller 144 packets for interactive connections to get better interactive response 145 on slow links). 147 The remote side then decides whether it can open the channel, and 148 responds with either 149 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 150 uint32 recipient channel 151 uint32 sender channel 152 uint32 initial window size 153 uint32 maximum packet size 154 ... channel type specific data follows 156 where `recipient channel' is the channel number given in the original 157 open request, and `sender channel' is the channel number allocated by 158 the other side, or 160 byte SSH_MSG_CHANNEL_OPEN_FAILURE 161 uint32 recipient channel 162 uint32 reason code 163 string additional textual information (ISO-10646 UTF-8 164 [[RFC-2044]]) 165 string language tag (as defined in [[RFC-1766]]) 167 If the recipient of the SSH_MSG_CHANNEL_OPEN message does not support 168 the specified channel type, it simply responds with 169 SSH_MSG_CHANNEL_OPEN_FAILURE. The client MAY show the additional 170 information to the user. If this is done, the client software should 171 take the precautions discussed in [SSH-ARCH]. 173 The following reason codes are defined: 175 #define SSH_OPEN_ADMINISTRATIVELY_PROHIBITED 1 176 #define SSH_OPEN_CONNECT_FAILED 2 177 #define SSH_OPEN_UNKNOWN_CHANNEL_TYPE 3 178 #define SSH_OPEN_RESOURCE_SHORTAGE 4 180 3.2. Data Transfer 182 The window size specifies how many bytes the other party can send before 183 it must wait for the window to be adjusted. Both parties use the 184 following message to adjust the window. 186 byte SSH_MSG_CHANNEL_WINDOW_ADJUST 187 uint32 recipient channel 188 uint32 bytes to add 190 After receiving this message, the recipient MAY send the given number of 191 bytes more that it was previously allowed to send; the window size is 192 incremented. 194 Data transfer is done with messages of the following type. 196 byte SSH_MSG_CHANNEL_DATA 197 uint32 recipient channel 198 string data 200 The maximum amount of data allowed is the current window size. The 201 window size is decremented by the amount of data sent. Both parties MAY 202 ignore all extra data sent after the allowed window is empty. 204 Additionally, some channels can transfer several types of data. An 205 example of this is stderr data from interactive sessions. Such data can 206 be passed with SSH_MSG_CHANNEL_EXTENDED_DATA messages, where a separate 207 integer specifies the type of the data. The available types and their 208 interpretation depend on the type of the channel. 210 byte SSH_MSG_CHANNEL_EXTENDED_DATA 211 uint32 recipient_channel 212 uint32 data_type_code 213 string data 215 Data sent with these messages consumes the same window as ordinary data. 217 Currently, only the following type is defined. 219 #define SSH_EXTENDED_DATA_STDERR 1 221 3.3. Closing a Channel 223 When a party will no longer send more data to a channel, it SHOULD send 224 SSH_MSG_CHANNEL_EOF. 226 byte SSH_MSG_CHANNEL_EOF 227 uint32 recipient_channel 229 No explicit response is sent to this message; however, the application 230 may send EOF to whatever is at the other end of the channel. Note that 231 the channel remains open after this message, and more data may still be 232 sent in the other direction. This message does not consume window space 233 and can be sent even if no window space is available. 235 When either party wishes to terminate the channel, it sends 236 SSH_MSG_CHANNEL_CLOSE. Upon receiving this message, a party MUST send 237 back a SSH_MSG_CHANNEL_CLOSE unless it has already sent this message for 238 the channel. The channel is considered closed for a party when it has 239 both sent and received SSH_MSG_CHANNEL_CLOSE, and the party may then 240 reuse the channel number. A party MAY send SSH_MSG_CHANNEL_CLOSE 241 without having sent or received SSH_MSG_CHANNEL_EOF. 242 byte SSH_MSG_CHANNEL_CLOSE 243 uint32 recipient_channel 245 This message does not consume window space and can be sent even if no 246 window space is available. 248 It is recommended that any data sent before this message is delivered to 249 the actual destination, if possible. 251 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 4.3.2. X11 Channels 362 X11 channels are opened with a channel open request. The resulting 363 channels are independent of the session, and closing the session channel 364 does not close the forwarded X11 channels. 366 byte SSH_MSG_CHANNEL_OPEN 367 string "x11" 368 uint32 sender channel 369 uint32 initial window size 370 uint32 maximum packet size 371 string originator address (e.g. "192.168.7.38") 372 uint32 originator port 374 The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or 375 SSH_MSG_CHANNEL_OPEN_FAILURE. 377 Implementations MUST reject any X11 channel open requests if they have 378 not requested X11 forwarding. 380 4.4. Authentication Agent Forwarding 382 It is RECOMMENDED that authentication agent forwarding is allowed even 383 when either or both parties do not support the SSH authentication agent 384 protocol [SSH-AGENT]. 386 4.4.1. Requesting Authentication Agent Forwarding 388 Authentication agent forwarding may be requested for a session by 389 sending 391 byte SSH_MSG_CHANNEL_REQUEST 392 uint32 recipient channel 393 string "auth-agent-req" 394 boolean want reply 396 The server responds with either SSH_MSG_CHANNEL_SUCCESS or 397 SSH_MSG_CHANNEL_FAILURE (if `want reply' is TRUE). The client MAY send 398 further messages without waiting for the response to this message. 400 4.4.2. Authentication Agent Channels 402 When an application requests a connection to the authentication agent, 403 the following message is sent to the originator of the session. 405 byte SSH_MSG_CHANNEL_OPEN 406 string "auth-agent" 407 uint32 sender channel 408 uint32 initial window size 409 uint32 maximum packet size 411 The recipient should respond with open confirmation or open failure. 413 Implementations MUST reject any agent channel open requests if they have 414 not requested agent forwarding. 416 4.5. Environment Variable Passing 418 Environment variables may be passed to the shell/command to be started 419 later. Typically, each machine will have a preconfigured set of 420 variables that it will allow. Since uncontrolled setting of environment 421 variables can be very dangerous, it is recommended that implementations 422 allow setting only variables whose names have been explicitly configured 423 to be allowed. 425 byte SSH_MSG_CHANNEL_REQUEST 426 uint32 recipient channel 427 string "env" 428 boolean want reply 429 string variable name 430 string variable value 432 4.6. Starting a Shell or a Command 434 Once the session has been set up, a program is started at the remote 435 end. Program can be a shell, an application program or a subsystem with 436 a host-independent name. Only one of these requests can succeed per 437 channel. 439 byte SSH_MSG_CHANNEL_REQUEST 440 uint32 recipient channel 441 string "shell" 442 boolean want reply 444 This message will request the user's default shell (typically defined in 445 /etc/passwd in UNIX systems) to be started at the other 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 given 454 command. The command string may contain a path. Normal precautions MUST 455 be taken to prevent the execution of unauthorized commands. 457 byte SSH_MSG_CHANNEL_REQUEST 458 uint32 recipient channel 459 string "subsystem" 460 boolean want reply 461 string subsystem name 463 This last form executes a predefined subsystem. It expected that these 464 will include a general file transfer mechanism, and possibly other 465 features. Implementations may also allow configuring more such 466 mechanisms. 468 The server SHOULD not halt the execution of the protocol stack when 469 starting a shell or a program. All input and output from these SHOULD be 470 redirected the the channel or to the encrypted tunnel. 472 It is RECOMMENDED to request and check the reply for these messages. The 473 client SHOULD ignore these messages. 475 4.7. Session Data Transfer 477 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 478 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The 479 extended data type SSH_EXTENDED_DATA_STDERR has been defined for stderr 480 data. 482 4.8. Window Dimension Change Message 484 When the window (terminal) size changes on the client side, it MAY send 485 a message to the other side to inform it of the new dimensions. 487 byte SSH_MSG_CHANNEL_REQUEST 488 uint32 recipient_channel 489 string "window-change" 490 boolean FALSE 491 uint32 terminal width, columns 492 uint32 terminal height, rows 493 uint32 terminal width, pixels 494 uint32 terminal height, pixels 496 No response SHOULD be sent to this message. 498 4.9. Local Flow Control 500 On many systems it is possible to determine if a pseudo-terminal is 501 using control-S control-Q flow control. When flow control is allowed, 502 it is often desirable to do the flow control at the client end to speed 503 up responses to user requests. This is facilitated by the following 504 notification. Initially, the server is responsible for flow control. 505 (Here, again, client means the side originating the session, and server 506 the other side.) 508 The message below is used by the server to inform the client when it can 509 or cannot perform flow control (control-S/control-Q processing). If 510 `client can do' is TRUE, the client is allowed to do flow control using 511 control-S and control-Q. The client MAY ignore this message. 513 byte SSH_MSG_CHANNEL_REQUEST 514 uint32 recipient channel 515 string "xon-xoff" 516 boolean FALSE 517 boolean client can do 519 No response is sent to this message. 521 4.10. Signals 523 A signal can be delivered to the remote process/service using the 524 following message. Some systems may not implement signals, in which 525 case they SHOULD ignore this message. 527 byte SSH_MSG_CHANNEL_REQUEST 528 uint32 recipient channel 529 string "signal" 530 boolean FALSE 531 uint32 signal number 533 4.11. Returning Exit Status 535 When the command running at the other end terminates, The following 536 message can be sent to return the exit status of the command. Returning 537 the status is RECOMMENDED. No acknowledgment is sent for this message. 538 The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE after this 539 message. 541 The client SHOULD ignore these messages. 543 byte SSH_MSG_CHANNEL_REQUEST 544 uint32 recipient_channel 545 string "exit-status" 546 boolean FALSE 547 uint32 exit_status 549 The remote command may also terminate violently due to a signal. Such a 550 condition can be indicated by the following message. A zero exit_status 551 usually means that the command terminated successfully. 553 byte SSH_MSG_CHANNEL_REQUEST 554 uint32 recipient channel 555 string "exit-signal" 556 boolean FALSE 557 uint32 signal number 558 boolean core dumped 559 string error message (ISO-10646 UTF-8 [[RFC-2044]]) 560 string language tag (as defined in [[RFC-1766]]) 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. 566 5. TCP/IP Port Forwarding 568 5.1. Requesting Port Forwarding 570 A party need not explicitly request forwardings from its own end to the 571 other direction. However, it if wishes to have connections to a port on 572 the other side be forwarded to the local side, it must explicitly 573 request this. 575 byte SSH_MSG_GLOBAL_REQUEST 576 string "tcpip-forward" 577 boolean want reply 578 string address to bind (e.g. "0.0.0.0") 579 uint32 port number to bind 581 `Address to bind' and `port number to bind' specify the IP address and 582 port to which the socket to be listened is bound. The address should be 583 "0.0.0.0" if connections are allowed from anywhere. (Note that the 584 client can still filter connections based on information passed in the 585 open request.) 587 Implementations should only allow forwarding privileged ports if the 588 user has been authenticated as a privileged user. 590 Client implementations SHOULD reject these messages; they are normally 591 only sent by the client. 593 A port forwarding can be cancelled with the following message. Note 594 that channel open requests may be received until a reply to this message 595 is received. 597 byte SSH_MSG_GLOBAL_REQUEST 598 string "cancel-tcpip-forward" 599 boolean want reply 600 string address_to_bind (e.g. "127.0.0.1") 601 uint32 port number to bind 603 Client implementations SHOULD reject these messages; they are normally 604 only sent by the client. 606 5.2. TCP/IP Forwarding Channels 608 When a connection comes to a port for which remote forwarding has been 609 requested, a channel is opened to forward the port to the other side. 611 byte SSH_MSG_CHANNEL_OPEN 612 string "forwarded-tcpip" 613 uint32 sender channel 614 uint32 initial window size 615 uint32 maximum packet size 616 string address that was connected 617 uint32 port that was connected 618 string originator IP address 619 uint32 originator port 621 Implementations MUST reject these messages unless they have previously 622 requested a remote TCP/IP port forwarding with the given port number. 624 When a connection comes to a locally forwarded TCP/IP port, the 625 following packet is sent to the other side. Note that these messages 626 MAY be sent also for ports for which no forwarding has been explicitly 627 requested. The receiving side must decide whether to allow the 628 forwarding. 630 byte SSH_MSG_CHANNEL_OPEN 631 string "direct-tcpip" 632 uint32 sender channel 633 uint32 initial window size 634 uint32 maximum packet size 635 string host to connect 636 uint32 port to connect 637 string originator IP address 638 uint32 originator port 640 `Host to connect' and `port to connect' specify the TCP/IP host and port 641 where the recipient should connect the channel. `Host to connect' may 642 be either a domain name or a numeric IP address. 644 `Originator IP address' is the numeric IP address of the machine where 645 the connection request comes from, and `originator port' is the port on 646 the originator host from where the connection came from. 648 Forwarded TCP/IP channels are independent of any sessions, and closing a 649 session channel does not in any way imply that forwarded connections 650 should be closed. 652 Client implementations SHOULD reject direct TCP/IP open requests for 653 security reasons. 655 6. Encoding of Terminal Modes 657 Terminal modes (as passed in a pty request) are encoded into a byte 658 stream. It is intended that the coding be portable across different 659 environments. 661 The tty mode description is a stream of bytes. The stream consists of 662 opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). 663 Opcodes 1-159 have a single uint32 argument. Opcodes 160-255 are not yet 664 defined, and cause parsing to stop (they should only be used after any 665 other data). 667 The client SHOULD put in the stream any modes it knows about, and the 668 server MAY ignore any modes it does not know about. This allows some 669 degree of machine-independence, at least between systems that use a 670 POSIX-like tty interface. The protocol can support other systems as 671 well, but the client may need to fill reasonable values for a number of 672 parameters so the server pty gets set to a reasonable mode (the server 673 leaves all unspecified mode bits in their default values, and only some 674 combinations make sense). 676 The following opcodes have been defined. The naming of opcodes mostly 677 follows the POSIX terminal mode flags. 679 0 TTY_OP_END Indicates end of options. 680 1 VINTR Interrupt character; 255 if none. Similarly for the 681 other characters. Not all of these characters are 682 supported on all systems. 683 2 VQUIT The quit character (sends SIGQUIT signal on POSIX 684 systems). 685 3 VERASE Erase the character to left of the cursor. 686 4 VKILL Kill the current input line. 687 5 VEOF End-of-file character (sends EOF from the terminal). 688 6 VEOL End-of-line character in addition to carriage return 689 and/or linefeed. 690 7 VEOL2 Additional end-of-line character. 691 8 VSTART Continues paused output (normally control-Q). 692 9 VSTOP Pauses output (normally control-S). 693 10 VSUSP Suspends the current program. 694 11 VDSUSP Another suspend character. 695 12 VREPRINT Reprints the current input line. 696 13 VWERASE Erases a word left of cursor. 697 14 VLNEXT Enter the next character typed literally, even if it 698 is a special character 699 15 VFLUSH Character to flush output. 700 16 VSWTCH Switch to a different shell layer. 701 17 VSTATUS Prints system status line (load, command, pid etc). 702 18 VDISCARD Toggles the flushing of terminal output. 703 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if 704 this flag is FALSE set, and 1 if it is TRUE. 705 31 PARMRK Mark parity and framing errors. 706 32 INPCK Enable checking of parity errors. 707 33 ISTRIP Strip 8th bit off characters. 708 34 INLCR Map NL into CR on input. 709 35 IGNCR Ignore CR on input. 710 36 ICRNL Map CR to NL on input. 711 37 IUCLC Translate uppercase characters to lowercase. 712 38 IXON Enable output flow control. 713 39 IXANY Any char will restart after stop. 714 40 IXOFF Enable input flow control. 715 41 IMAXBEL Ring bell on input queue full. 716 50 ISIG Enable signals INTR, QUIT, [[D]]SUSP. 717 51 ICANON Canonicalize input lines. 718 52 XCASE Enable input and output of uppercase characters by 719 preceding their lowercase equivalents with `\'. 720 53 ECHO Enable echoing. 721 54 ECHOE Visually erase chars. 722 55 ECHOK Kill character discards current line. 723 56 ECHONL Echo NL even if ECHO is off. 724 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. 733 72 ONLCR Map NL to CR-NL. 734 73 OCRNL Translate carriage return to newline (output). 735 74 ONOCR Translate newline to carriage return-newline 736 (output). 737 75 ONLRET Newline performs a carriage return (output). 738 90 CS7 7 bit mode. 739 91 CS8 8 bit mode. 740 92 PARENB Parity enable. 741 93 PARODD Odd parity, else even. 743 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second. 744 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second. 746 7. Summary of Message Numbers 748 #define SSH_MSG_GLOBAL_REQUEST 80 749 #define SSH_MSG_REQUEST_SUCCESS 81 750 #define SSH_MSG_REQUEST_FAILURE 82 751 #define SSH_MSG_CHANNEL_OPEN 90 752 #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 753 #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 754 #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 755 #define SSH_MSG_CHANNEL_DATA 94 756 #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 757 #define SSH_MSG_CHANNEL_EOF 96 758 #define SSH_MSG_CHANNEL_CLOSE 97 759 #define SSH_MSG_CHANNEL_REQUEST 98 760 #define SSH_MSG_CHANNEL_SUCCESS 99 761 #define SSH_MSG_CHANNEL_FAILURE 100 763 8. Security Considerations 765 This protocol is assumed to run on top of a secure, authenticated 766 transport. User authentication and protection against network-level 767 attacks are assumed to be provided by the underlying protocols. 769 This protocol can, however, be used to execute commands on remote 770 machines. The protocol also permits the server to run commands on the 771 client. Implementations may wish to disallow this to prevent an 772 attacker from coming from the server machine to the client machine. 774 X11 forwarding provides major security improvements over normal cookie- 775 based X11 forwarding. The cookie never needs to be transmitted in the 776 clear, and traffic is encrypted and integrity-protected. No useful 777 authentication data will remain on the server machine after the 778 connection has been closed. On the other hand, in some situations a 779 forwarded X11 connection might be used to get access to the local X 780 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 couldn't 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 of the potentially 793 dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP 794 forwarding) if the host key has changed. 796 9. References 798 [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages", 799 March 1995. 801 [RFC-1884] Hinden, R., and Deering, S., "IP Version 6 Addressing 802 Architecture", December 1995 804 [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and 805 ISO 10646", October 1996. 807 [SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol 808 Architecture", Internet Draft, draft-ietf-secsh-architecture-00.txt 810 [SSH-TRANS] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Transport 811 Layer Protocol", Internet Draft, draft-ietf-secsh-transport-02.txt 813 [SSH-USERAUTH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH 814 Authentication Protocol", Internet Draft, draft-ietf-secsh- 815 userauth-02.txt 817 10. Authors' Addresses 819 Tatu Ylonen 820 SSH Communications Security Ltd. 821 Tekniikantie 12 822 FIN-02150 ESPOO 823 Finland 824 E-mail: ylo@ssh.fi 826 Tero Kivinen 827 SSH Communications Security Ltd. 828 Tekniikantie 12 829 FIN-02150 ESPOO 830 Finland 831 E-mail: kivinen@ssh.fi 832 Markku-Juhani O. Saarinen 833 SSH Communications Security Ltd. 834 Tekniikantie 12 835 FIN-02150 ESPOO 836 Finland 837 E-mail: mjos@ssh.fi