idnits 2.17.1 draft-ietf-secsh-connect-02.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 (14 October 1997) is 9690 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 381, but not defined == Unused Reference: 'RFC-1766' is defined on line 794, but no explicit reference was found in the text == Unused Reference: 'RFC-2044' is defined on line 797, but no explicit reference was found in the text == Unused Reference: 'SSH-TRANS' is defined on line 803, but no explicit reference was found in the text == Unused Reference: 'SSH-USERAUTH' is defined on line 806, but no explicit reference was found in the text ** Obsolete normative reference: RFC 1766 (Obsoleted by RFC 3066, RFC 3282) ** 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: 11 errors (**), 0 flaws (~~), 16 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-02.txt M. Saarinen 4 Expires in six months SSH 5 14 October 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 ser- 30 vices 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 the 38 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 . . . . . . . . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . 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. 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_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 dimension parameters are only informational. 325 The client SHOULD ignore pty requests. 327 4.3. X11 Forwarding 329 4.3.1. Requesting X11 Forwarding 331 X11 forwarding may be requested for a session by sending 333 byte SSH_MSG_CHANNEL_REQUEST 334 uint32 recipient channel 335 string "x11-req" 336 boolean want reply 337 boolean single connection 338 string x11 authentication protocol 339 string x11 authentication cookie 340 uint32 x11 screen number 342 It is recommended that the authentication cookie that is sent be a fake, 343 random cookie, and that the cookie is checked and replaced by the real 344 cookie when a connection request is received. 346 X11 connection forwarding should stop when the session channel is 347 closed; however, already opened forwardings should not be automatically 348 closed when the session channel is closed. 350 If `single connection' is TRUE, only a single connection should be 351 forwarded. No more connections will be forwarded after the first, or 352 after the session channel has been closed. 354 `X11 authentication protocol is the name of the X11 authentication 355 method used, i.e. "MIT-MAGIC-COOKIE-1". 357 4.3.2. X11 Channels 359 X11 channels are opened with a channel open request. The resulting 360 channels are independent of the session, and closing the session channel 361 does not close the forwarded X11 channels. 363 byte SSH_MSG_CHANNEL_OPEN 364 string "x11" 365 uint32 sender channel 366 uint32 initial window size 367 uint32 maximum packet size 368 string originator IP address (e.g. "192.168.7.38") 369 uint32 originator port 371 The recipient should respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or 372 SSH_MSG_CHANNEL_OPEN_FAILURE. 374 Implementations MUST reject any X11 channel open requests if they have 375 not requested X11 forwarding. 377 4.4. Authentication Agent Forwarding 379 It is RECOMMENDED that authentication agent forwarding is allowed even 380 when either or both parties do not support the SSH authentication agent 381 protocol [SSH-AGENT]. 383 4.4.1. Requesting Authentication Agent Forwarding 385 Authentication agent forwarding may be requested for a session by 386 sending 388 byte SSH_MSG_CHANNEL_REQUEST 389 uint32 recipient channel 390 string "auth-agent-req" 391 boolean want reply 393 The server responds with either SSH_MSG_CHANNEL_SUCCESS or 394 SSH_MSG_CHANNEL_FAILURE (if `want reply' is TRUE). The client MAY to 395 send further messages without waiting for the response to this message. 397 4.4.2. Authentication Agent Channels 399 When an application requests a connection to the authentication agent, 400 the following message is sent to the originator of the session. 402 byte SSH_MSG_CHANNEL_OPEN 403 string "auth-agent" 404 uint32 sender channel 405 uint32 initial window size 406 uint32 maximum packet size 408 The recipient should respond with open confirmation or open failure. 410 Implementations MUST reject any agent channel open requests if they have 411 not requested agent forwarding. 413 4.5. Environment Variable Passing 415 Environment variables may be passed to the shell/command to be started 416 later. Typically, each machine will have a preconfigured set of 417 variables that it will allow. Since uncontrolled setting of environment 418 variables can be very dangerous, it is recommended that implementations 419 allow setting only variables whose names have been explicitly configured 420 to be allowed. 422 byte SSH_MSG_CHANNEL_REQUEST 423 uint32 recipient channel 424 string "env" 425 boolean want reply 426 string variable name 427 string variable value 429 4.6. Starting a Shell or a Command 431 Once the session has been set up, a program is started at the remote 432 end. Program can be a shell, an application program or a subsystem with 433 a host-independent name. Only one of these requests can succeed per 434 channel. 436 byte SSH_MSG_CHANNEL_REQUEST 437 uint32 recipient channel 438 string "shell" 439 boolean want reply 441 This message will request the user's default shell (typically defined in 442 /etc/passwd in UNIX systems) to be started at the other end. 444 byte SSH_MSG_CHANNEL_REQUEST 445 uint32 recipient channel 446 string "exec" 447 boolean want reply 448 string command 450 This message will request the server to start the execution of the given 451 command. The command string may contain a path. Normal precautions MUST 452 be taken to prevent the execution of unauthorized commands. 454 byte SSH_MSG_CHANNEL_REQUEST 455 uint32 recipient channel 456 string "subsystem" 457 boolean want reply 458 string subsystem name 460 This last form executes a predefined subsystem. It expected that these 461 will include a general file transfer mechanism, and possibly other 462 features. Implementations may also allow configuring more such 463 mechanisms. 465 The server SHOULD not halt the execution of the protocol stack when 466 starting a shell or a program. All input and output from these SHOULD be 467 redirected the the channel or to the encrypted tunnel. 469 It is RECOMMENDED to request and check the reply for these messages. The 470 client SHOULD ignore these messages. 472 4.7. Session Data Transfer 474 Data transfer for a session is done using SSH_MSG_CHANNEL_DATA and 475 SSH_MSG_CHANNEL_EXTENDED_DATA packets and the window mechanism. The 476 extended data type SSH_EXTENDED_DATA_STDERR has been defined for stderr 477 data. 479 4.8. Window Dimension Change Message 481 When the window (terminal) size changes on the client side, it MAY send 482 a message to the other side to inform it of the new dimensions. 484 byte SSH_MSG_CHANNEL_REQUEST 485 uint32 recipient_channel 486 string "window-change" 487 boolean FALSE 488 uint32 terminal width, columns 489 uint32 terminal height, rows 490 uint32 terminal width, pixels 491 uint32 terminal height, pixels 493 No response SHOULD be sent to this message. 495 4.9. Local Flow Control 497 On many systems it is possible to determine if a pseudo-terminal is 498 using control-S control-Q flow control. When flow control is allowed, 499 it is often desirable to do the flow control at the client end to speed 500 up responses to user requests. This is facilitated by the following 501 notification. Initially, the server is responsible for flow control. 502 (Here, again, client means the side originating the session, and server 503 the other side.) 505 The message below is used by the server to inform the client when it can 506 or cannot perform flow control (control-S/control-Q processing). If 507 `client can do' is TRUE, the client is allowed to do flow control using 508 control-S and control-Q. The client MAY ignore this message. 510 byte SSH_MSG_CHANNEL_REQUEST 511 uint32 recipient channel 512 string "xon-xoff" 513 boolean FALSE 514 boolean client can do 516 No response is sent to this message. 518 4.10. Signals 520 A signal can be delivered to the remote process/service using the 521 following message. Some systems may not implement signals, in which 522 case they SHOULD ignore this message. 524 byte SSH_MSG_CHANNEL_REQUEST 525 uint32 recipient channel 526 string "signal" 527 boolean FALSE 528 uint32 signal number 530 4.11. Returning Exit Status 532 When the command running at the other end terminates, The following 533 message can be sent to return the exit status of the command. Returning 534 the status is RECOMMENDED. No acknowledgment is sent for this message. 535 The channel needs to be closed with SSH_MSG_CHANNEL_CLOSE after this 536 message. 538 The client SHOULD ignore these messages. 540 byte SSH_MSG_CHANNEL_REQUEST 541 uint32 recipient_channel 542 string "exit-status" 543 boolean FALSE 544 uint32 exit_status 546 The remote command may also terminate violently due to a signal. Such a 547 condition can be indicated by the following message. 549 byte SSH_MSG_CHANNEL_REQUEST 550 uint32 recipient channel 551 string "exit-signal" 552 boolean FALSE 553 uint32 signal number 554 boolean core dumped 555 string error message (ISO-10646 UTF-8 [[RFC-2044]]) 556 string language tag (as defined in [[RFC-1766]]) 558 The `error message' contains an additional explanation of the error 559 message. The message may consist of multiple lines. The client software 560 MAY display this message to the user. 562 5. TCP/IP Port Forwarding 564 5.1. Requesting Port Forwarding 566 A party need not explicitly request forwardings from its own end to the 567 other direction. However, it if wishes to have connections to a port on 568 the other side be forwarded to the local side, it must explicitly 569 request this. 571 byte SSH_MSG_GLOBAL_REQUEST 572 string "tcpip-forward" 573 boolean want reply 574 string address to bind (e.g. "0.0.0.0") 575 uint32 port number to bind 577 `Address to bind' and `port number to bind' specify the IP address and 578 port to which the socket to be listened is bound. The address should be 579 "0.0.0.0" if connections are allowed from anywhere. (Note that the 580 client can still filter connections based on information passed in the 581 open request.) 583 Implementations should only allow forwarding privileged ports if the 584 user has been authenticated as a privileged user. 586 Client implementations SHOULD reject these messages; they are normally 587 only sent by the client. 589 A port forwarding can be cancelled with the following message. Note 590 that channel open requests may be received until a reply to this message 591 is received. 593 byte SSH_MSG_GLOBAL_REQUEST 594 string "cancel-tcpip-forward" 595 boolean want reply 596 string address_to_bind (e.g. "127.0.0.1") 597 uint32 port number to bind 599 Client implementations SHOULD reject these messages; they are normally 600 only sent by the client. 602 5.2. TCP/IP Forwarding Channels 604 When a connection comes to a port for which remote forwarding has been 605 requested, a channel is opened to forward the port to the other side. 607 byte SSH_MSG_CHANNEL_OPEN 608 string "forwarded-tcpip" 609 uint32 sender channel 610 uint32 initial window size 611 uint32 maximum packet size 612 string address that was connected 613 uint32 port that was connected 614 string originator IP address 615 uint32 originator port 617 Implementations MUST reject these messages unless they have previously 618 requested a remote TCP/IP port forwarding with the given port number. 620 When a connection comes to a locally forwarded TCP/IP port, the 621 following packet is sent to the other side. Note that these messages 622 MAY be sent also for ports for which no forwarding has been explicitly 623 requested. The receiving side must decide whether to allow the 624 forwarding. 626 byte SSH_MSG_CHANNEL_OPEN 627 string "direct-tcpip" 628 uint32 sender channel 629 uint32 initial window size 630 uint32 maximum packet size 631 string host to connect 632 uint32 port to connect 633 string originator IP address 634 uint32 originator port 636 `Host to connect' and `port to connect' specify the TCP/IP host and port 637 where the recipient should connect the channel. `Host to connect' may 638 be either a domain name or a numeric IP address. 640 `Originator IP address' is the numeric IP address of the machine where 641 the connection request comes from, and `originator port' is the port on 642 the originator host from where the connection came from. 644 Forwarded TCP/IP channels are independent of any sessions, and closing a 645 session channel does not in any way imply that forwarded connections 646 should be closed. 648 Client implementations SHOULD reject direct TCP/IP open requests for 649 security reasons. 651 6. Encoding of Terminal Modes 653 Terminal modes (as passed in a pty request) are encoded into a byte 654 stream. It is intended that the coding be portable across different 655 environments. 657 The tty mode description is a stream of bytes. The stream consists of 658 opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). 659 Opcodes 1-159 have a single uint32 argument. Opcodes 160-255 are not yet 660 defined, and cause parsing to stop (they should only be used after any 661 other data). 663 The client SHOULD put in the stream any modes it knows about, and the 664 server MAY ignore any modes it does not know about. This allows some 665 degree of machine-independence, at least between systems that use a 666 POSIX-like tty interface. The protocol can support other systems as 667 well, but the client may need to fill reasonable values for a number of 668 parameters so the server pty gets set to a reasonable mode (the server 669 leaves all unspecified mode bits in their default values, and only some 670 combinations make sense). 672 The following opcodes have been defined. The naming of opcodes mostly 673 follows the POSIX terminal mode flags. 675 0 TTY_OP_END Indicates end of options. 676 1 VINTR Interrupt character; 255 if none. Similarly for the 677 other characters. Not all of these characters are 678 supported on all systems. 679 2 VQUIT The quit character (sends SIGQUIT signal on POSIX 680 systems). 681 3 VERASE Erase the character to left of the cursor. 682 4 VKILL Kill the current input line. 683 5 VEOF End-of-file character (sends EOF from the terminal). 684 6 VEOL End-of-line character in addition to carriage return 685 and/or linefeed. 686 7 VEOL2 Additional end-of-line character. 687 8 VSTART Continues paused output (normally control-Q). 688 9 VSTOP Pauses output (normally control-S). 689 10 VSUSP Suspends the current program. 690 11 VDSUSP Another suspend character. 691 12 VREPRINT Reprints the current input line. 692 13 VWERASE Erases a word left of cursor. 693 14 VLNEXT Enter the next character typed literally, even if it 694 is a special character 695 15 VFLUSH Character to flush output. 696 16 VSWTCH Switch to a different shell layer. 697 17 VSTATUS Prints system status line (load, command, pid etc). 698 18 VDISCARD Toggles the flushing of terminal output. 699 30 IGNPAR The ignore parity flag. The parameter SHOULD be 0 if 700 this flag is FALSE set, and 1 if it is TRUE. 701 31 PARMRK Mark parity and framing errors. 702 32 INPCK Enable checking of parity errors. 703 33 ISTRIP Strip 8th bit off characters. 704 34 INLCR Map NL into CR on input. 705 35 IGNCR Ignore CR on input. 706 36 ICRNL Map CR to NL on input. 707 37 IUCLC Translate uppercase characters to lowercase. 708 38 IXON Enable output flow control. 709 39 IXANY Any char will restart after stop. 710 40 IXOFF Enable input flow control. 711 41 IMAXBEL Ring bell on input queue full. 712 50 ISIG Enable signals INTR, QUIT, [[D]]SUSP. 713 51 ICANON Canonicalize input lines. 714 52 XCASE Enable input and output of uppercase characters by 715 preceding their lowercase equivalents with `\'. 716 53 ECHO Enable echoing. 717 54 ECHOE Visually erase chars. 718 55 ECHOK Kill character discards current line. 719 56 ECHONL Echo NL even if ECHO is off. 720 57 NOFLSH Don't flush after interrupt. 721 58 TOSTOP Stop background jobs from output. 722 59 IEXTEN Enable extensions. 723 60 ECHOCTL Echo control characters as ^(Char). 724 61 ECHOKE Visual erase for line kill. 725 62 PENDIN Retype pending input. 726 70 OPOST Enable output processing. 727 71 OLCUC Convert lowercase to uppercase. 729 72 ONLCR Map NL to CR-NL. 730 73 OCRNL Translate carriage return to newline (output). 731 74 ONOCR Translate newline to carriage return-newline 732 (output). 733 75 ONLRET Newline performs a carriage return (output). 734 90 CS7 7 bit mode. 735 91 CS8 8 bit mode. 736 92 PARENB Parity enable. 737 93 PARODD Odd parity, else even. 739 128 TTY_OP_ISPEED Specifies the input baud rate in bits per second. 740 129 TTY_OP_OSPEED Specifies the output baud rate in bits per second. 742 7. Summary of Message Numbers 744 #define SSH_MSG_GLOBAL_REQUEST 80 745 #define SSH_MSG_REQUEST_SUCCESS 81 746 #define SSH_MSG_REQUEST_FAILURE 82 747 #define SSH_MSG_CHANNEL_OPEN 90 748 #define SSH_MSG_CHANNEL_OPEN_CONFIRMATION 91 749 #define SSH_MSG_CHANNEL_OPEN_FAILURE 92 750 #define SSH_MSG_CHANNEL_WINDOW_ADJUST 93 751 #define SSH_MSG_CHANNEL_DATA 94 752 #define SSH_MSG_CHANNEL_EXTENDED_DATA 95 753 #define SSH_MSG_CHANNEL_EOF 96 754 #define SSH_MSG_CHANNEL_CLOSE 97 755 #define SSH_MSG_CHANNEL_REQUEST 98 756 #define SSH_MSG_CHANNEL_SUCCESS 99 757 #define SSH_MSG_CHANNEL_FAILURE 100 759 8. Security Considerations 761 This protocol is assumed to run on top of a secure, authenticated 762 transport. User authentication and protection against network-level 763 attacks are assumed to be provided by the underlying protocols. 765 This protocol can, however, be used to execute commands on remote 766 machines. The protocol also permits the server to run commands on the 767 client. Implementations may wish to disallow this to prevent an 768 attacker from coming from the server machine to the client machine. 770 X11 forwarding provides major security improvements over normal cookie- 771 based X11 forwarding. The cookie never needs to be transmitted in the 772 clear, and traffic is encrypted and integrity-protected. No useful 773 authentication data will remain on the server machine after the 774 connection has been closed. On the other hand, in some situations a 775 forwarded X11 connection might be used to get access to the local X 776 server across security perimeters. 778 Port forwardings can potentially allow an intruder to cross security 779 perimeters such as firewalls. They do not offer anything fundamentally 780 new that a user couldn't do otherwise; however, they make opening 781 tunnels very easy. Implementations should allow policy control over 782 what can be forwarded. Administrators should be able to deny 783 forwardings where appropriate. 785 Since this protocol normally runs inside an encrypted tunnel, firewalls 786 will not be able to examine the traffic. 788 It is RECOMMENDED that implementations disable all of the potentially 789 dangerous features (e.g. agent forwarding, X11 forwarding, and TCP/IP 790 forwarding) of host key has changed. 792 9. References 794 [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages", 795 March 1995. 797 [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and 798 ISO 10646", October 1996. 800 [SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol 801 Architecture", Internet Draft, draft-ietf-secsh-architecture-00.txt 803 [SSH-TRANS] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Transport 804 Layer Protocol", Internet Draft, draft-ietf-secsh-transport-02.txt 806 [SSH-USERAUTH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH 807 Authentication Protocol", Internet Draft, draft-ietf-secsh- 808 userauth-02.txt 810 10. Authors' Addresses 812 Tatu Ylonen 813 SSH Communications Security Ltd. 814 Tekniikantie 12 815 FIN-02150 ESPOO 816 Finland 817 E-mail: ylo@ssh.fi 819 Tero Kivinen 820 SSH Communications Security Ltd. 821 Tekniikantie 12 822 FIN-02150 ESPOO 823 Finland 824 E-mail: kivinen@ssh.fi 826 Markku-Juhani O. Saarinen 827 SSH Communications Security Ltd. 828 Tekniikantie 12 829 FIN-02150 ESPOO 830 Finland 831 E-mail: mjos@ssh.fi