idnits 2.17.1 draft-ietf-secsh-transport-00.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-19) 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 a Security Considerations section. ** 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 an Authors' Addresses Section. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 398 has weird spacing: '...mac-sha opt...' == Line 449 has weird spacing: '... string kex...' == Line 450 has weird spacing: '... string ser...' == Line 451 has weird spacing: '... string enc...' == Line 452 has weird spacing: '... string enc...' == (16 more instances...) -- 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 (March 22, 1997) is 9890 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? '16' on line 448 looks like a reference -- Missing reference section? '4' on line 459 looks like a reference Summary: 9 errors (**), 0 flaws (~~), 7 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Tatu Ylonen 2 INTERNET-DRAFT SSH Communications Security 3 draft-ietf-secsh-transport-00.txt March 22, 1997 4 Expires: September 1, 1997 6 SSH Transport Layer Protocol 8 Status of This memo 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its areas, 12 and its working groups. Note that other groups may also distribute 13 working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six 16 months and may be updated, replaced, or obsoleted by other documents 17 at any time. It is inappropriate to use Internet-Drafts as reference 18 material or to cite them other than as ``work in progress.'' 20 To learn the current status of any Internet-Draft, please check 21 the ``1id-abstracts.txt'' listing contained in the Internet-Drafts 22 Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 23 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), 24 or ftp.isi.edu (US West Coast). 26 Abstract 28 This document describes the SSH transport layer protocol. The protocol 29 can be used as a basis for a number of secure network services. It pro- 30 vides strong encryption, server authentication, and integrity protec- 31 tion. 33 Table of Contents 35 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 36 2. Data Type Representations Used in the Protocol . . . . . . . . . 3 37 2.1. vlint32 . . . . . . . . . . . . . . . . . . . . . . . . . . 3 38 2.2. string . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 39 2.3. boolean . . . . . . . . . . . . . . . . . . . . . . . . . . 3 40 2.4. byte . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 41 2.5. uint16 . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 42 2.6. uint32 . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 43 3. Algorithm Naming . . . . . . . . . . . . . . . . . . . . . . . . 4 44 4. Connection Setup . . . . . . . . . . . . . . . . . . . . . . . . 4 45 4.1. Use over TCP/IP . . . . . . . . . . . . . . . . . . . . . . 5 46 4.2. Protocol Version Exchange . . . . . . . . . . . . . . . . . 5 47 4.3. Compatibility with Old SSH Versions . . . . . . . . . . . . 5 48 4.3.1. Old Client, New Server . . . . . . . . . . . . . . . . . 5 49 4.3.2. New Client, Old Server . . . . . . . . . . . . . . . . . 5 50 5. Binary Packet Protocol . . . . . . . . . . . . . . . . . . . . . 6 51 5.1. Maximum Packet Length . . . . . . . . . . . . . . . . . . . 6 52 5.2. Compression . . . . . . . . . . . . . . . . . . . . . . . . 7 53 5.3. Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 7 54 5.4. Data Integrity . . . . . . . . . . . . . . . . . . . . . . . 8 55 6. Key Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . 9 56 6.1. Algorithm Negotiation . . . . . . . . . . . . . . . . . . . 9 57 6.2. Double-Encrypting Key Exchange . . . . . . . . . . . . . . . 12 58 6.2.1. Server Sends Host Key . . . . . . . . . . . . . . . . . 12 59 6.2.2. Deriving Exchange Hash and Session Identifier . . . . . 13 60 6.2.3. Client Sends Double-Encrypted Session Key . . . . . . . 14 61 6.2.4. Deriving Encryption and Integrity Keys . . . . . . . . . 14 62 6.3. Taking Keys into Use . . . . . . . . . . . . . . . . . . . . 15 63 7. Key Re-Exchange . . . . . . . . . . . . . . . . . . . . . . . . 15 64 8. Service Request . . . . . . . . . . . . . . . . . . . . . . . . 16 65 9. Stream-Based Services . . . . . . . . . . . . . . . . . . . . . 17 66 10. Additional Messages . . . . . . . . . . . . . . . . . . . . . . 17 67 10.1. Disconnection Message . . . . . . . . . . . . . . . . . . . 17 68 10.2. Ignored Data Message . . . . . . . . . . . . . . . . . . . 18 69 10.3. Debug Message . . . . . . . . . . . . . . . . . . . . . . . 18 70 10.4. Reserved Messages . . . . . . . . . . . . . . . . . . . . . 18 71 11. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 18 72 12. Public Keys and Public Key Infrastructure . . . . . . . . . . . 19 73 12.1. x509 . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 74 12.2. spki . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 75 12.3. ssh-rsa-pkcs1 . . . . . . . . . . . . . . . . . . . . . . . 20 76 13. Address of Author . . . . . . . . . . . . . . . . . . . . . . . 21 78 1. Introduction 80 The SSH protocol is a secure transport layer protocol. It provides 81 strong encryption, cryptographic host autentication, and integrity 82 protection. 84 Authentication in this protocol level is host-based; this protocol does 85 not perform user authentication. It is expected that a higher level 86 protocol will be defined on top of this protocol that will perform user 87 authentication for those services that need it. 89 The protocol has been designed to be simple, flexible, allow parameter 90 negotiation, and minimize the number of round-trips. Key exchange 91 method, public key algorithm, symmetric encryption algorithm, message 92 authentication algorithm, and hash algorithm are all negotiated. It is 93 expected that in most environments, only 1.5 round-trips will be needed 94 for full key exchange, server authentication, service request, and 95 acceptance notification of service request. The worst case is 2.5 96 round-trips. 98 2. Data Type Representations Used in the Protocol 100 2.1. vlint32 102 The vlint32 can represent arbitrary 32-bit unsigned integers. It is 103 stored as a variable number of bytes (1-5 bytes), depending on the value 104 being stored. 106 Bits 6-7 of the first byte (the most significant bits) determine the 107 number of additional bytes that follow, and are interpreted as follows. 109 Bit7 Bit6 Number of bytes that follow 110 0 0 0 111 0 1 1 112 1 0 2 113 1 1 4 115 Bits 0-5 of the first byte and the following bytes contain the value of 116 the integer, MSB first. 118 If bits 6-7 are both one, the remaining bits in the first byte are zero 119 (reserved for future extension). 121 2.2. string 123 A string here means an arbitrary length binary string. Strings are 124 allowed to contain arbitrary binary data, including null characters and 125 8-bit characters. 127 A string is represented as a vlint32 containing its length, followed by 128 zero or more characters that are the value of the string. No 129 terminating null character is normally included in the string. 131 2.3. boolean 133 A boolean value is represented as a single byte. The value 0 represents 134 false, and the value 1 represents true. All non-zero values are 135 interpreted as true, but applications should not store values other than 136 0 and 1. 138 2.4. byte 140 A byte represents an arbitrary 8-bit value. Fixed length data is 141 sometimes represented as an array of bytes, written byte[n], where n is 142 the number of bytes in the array. 144 2.5. uint16 146 A 16-bit unsigned integer, represented as two bytes, MSB first. 148 2.6. uint32 150 A 32-bit unsigned integer, represented as four bytes, MSB first. 152 3. Algorithm Naming 154 This protocol refers to particular hash, encryption, integrity, 155 compression, and key exchange algorithms in various places. There are 156 some standard algorithms that all implementations are required to 157 support. There are also algorithms that are defined in the protocol 158 specification but are optional. Furthermore, it is expected that some 159 organizations will want to use their own algorithms whenever possible. 160 This leads to the problem of how algorithm identifiers are allocated. 162 In this protocols, all algorithm identifiers are represented as strings. 163 Names are case-sensitive. Algorithm lists are comma-separated lists of 164 these identifiers, without spaces. There are two formats for algorithm 165 identifiers: 167 o Algorithms defined in the base protocol are simple strings, such as 168 "3des-cbc", "sha-1", "hmac-sha", or "zip" (the quotes are not part of 169 the name). Defined algorithms may be mandatory or optional. All 170 interoperable implementations should implement mandatory algorithms 171 and offer them as a possibility in key exchanges. Optional 172 algorithms are not crucial for interoperability, but may provide 173 better performance or other advantages. It is up to an 174 implementation to decide which of these are supported and which are 175 offered in key exchanges by default. 177 o Anyone can define additional algorithms by using names in the format 178 name@domainname, e.g. "ourcipher-cbc@ssh.fi". The format of the part 179 preceding the at sign is not specified; it may contain any non- 180 control characters except at signs and commas. The part following 181 the at sign should be a valid internet domain name for the 182 organization defining the name. It is up to the each organization 183 how they manage its locally defined names. 185 4. Connection Setup 187 SSH works over any 8-bit clean, binary-transparent transport. The 188 client initiates the connection, and sets up the binary-transparent 189 transport. 191 4.1. Use over TCP/IP 193 When used over TCP/IP, the server normally listens for connections on 194 port 22. This port number has been registered with the IANA (Internet 195 Assigned Numbers Authority), and has been officially assigned for SSH. 197 4.2. Protocol Version Exchange 199 When the connection has been established, both sides send an 200 identification string of the form "SSH-protoversion-softwareversion 201 comments", followed by carriage return and newline (ascii 13 and 10, 202 respectively). No null character is sent. The maximum length of the 203 string is 255 characters, including the cr and newline. The protocol 204 version described in this document is 2.0. Version strings should only 205 contain printable characters, not including space or '-'. The string is 206 used in debugging outputs to ease debugging; the protocol version is 207 also used to trigger compatible extensions. It is recommended that the 208 strings be as descriptive as possible. The comment string could include 209 information such as the platform type which might be useful in solving 210 user problems. 212 Key exchange will begin immediately after sending this identifier 213 (normally without waiting for the identifier from the other side -- see 214 the next section for compatibility issues). All packets following the 215 identification string will use the binary packet protocol, to be 216 described below. 218 4.3. Compatibility with Old SSH Versions 220 During a transition period, it is important to be able to work 221 compatibly with installed SSH clients and servers using an older version 222 of the protocol. Information in this section is only relevant for 223 implementations supporting compatibility with old versions. 225 4.3.1. Old Client, New Server 227 Server implementations should support a configurable "compatibility" 228 flag that enables compatibility with old versions. When this flag is 229 on, the server will not send any further data after its initialization 230 string until it has received an identification string from the client. 231 The server can then determine whether the client is using an old 232 protocol, and can revert to the old protocol if desired. 234 When compatibility with old clients is not needed, the server should 235 send its initial key exchange data immediately after the identification 236 string. This saves a round-trip. 238 4.3.2. New Client, Old Server 240 Since the new client will immediately send additional data after its 241 identification string (before receiving server's identification), the 242 old protocol has already been corrupted when the client learns that the 243 server is old. When this happens, the client should close the 244 connection to the server, and reconnect using the old protocol this 245 time. 247 5. Binary Packet Protocol 249 Each packet consists of the following fields: 251 Length 252 The length of the packet (bytes). This represents the number of 253 bytes that follow this value, not including the optional MAC. The 254 length is represented as a vlint32. 256 Padding length 257 Length of padding (bytes). This field is represented as a 258 vlint32. 260 Payload 261 The useful contents of the packet. This field is optionally 262 compressed. 264 Padding 265 Arbitrary-length padding, such that the total length of 266 length+paddinglength+payload+padding is a multiple of the cipher 267 block size or 8, whichever is larger. It is recommended that at 268 least four bytes of random padding be always used. 270 MAC 271 Message authentication code. This field is optional, and its 272 length depends on the algorithm in use. 274 Note that length of the concatenation of packet length, padding length, 275 payload, and padding must be a multiple of the cipher block size or 8, 276 whichever is larger. This constraint is enforced even when using stream 277 ciphers. Note that the packet length field is also encrypted, and 278 processing it requires special care when sending/receiving packets. In 279 particular, one has to be extra careful when computing the amount of 280 padding, as changing the amount of padding can also change the size of 281 the length fields. The minimum size of a packet is 8 (or cipher block 282 size, whichever is larger) characters (plus MAC); implementations should 283 decrypt the length after receiving the first 8 (or cipher block size, 284 whichever is larger) bytes of a packet. 286 When the protocol starts, no encryption is in effect, no compression is 287 used, and no MAC is in use. During key exchange, an encryption method, 288 compression method, and a MAC method are selected. Any further messages 289 will use the negotiated algorithms. 291 5.1. Maximum Packet Length 293 The maximum length of the uncompressed payload is 32768 bytes. The 294 maximum size of the entire packet, including length, padding length, 295 payload, padding, and MAC, is 35000 bytes. The motivation for this 296 limit is to keep the protocol easy to implement on 16-bit machines. 298 5.2. Compression 300 If compression has been negotiated, the payload field (and only it) will 301 be compressed using the negotiated algorithm. The length field will 302 contain the compressed length (i.e., that transmitted on the wire). 304 Compressed packets must not exceed the total packet size limit; the 305 compression algorithm must guarantee that it does not expand the packet 306 too much. The uncompressed payload size must not exceed the maximum 307 payload size (the compressed payload, however, may be bigger than the 308 maximum payload size, as long as the packet size limit is not exceeded). 310 The following compression methods are currently defined: 312 none mandatory no compression 313 zlib optional GNU ZLIB compression at level 6 315 The "zlib" compression is described in RFC1950. 317 The compression context is initialized after key exchange, and is passed 318 from one packet to the next with only a partial flush being performed at 319 the end of each packet. A partial flush means that all data will be 320 output, but the next packet will continue using compression tables from 321 the end of the previous packet. 323 Compression is independent in each direction, and the different 324 compression methods may be used for each direction. 326 5.3. Encryption 328 An encryption algorithm and a key will be negotiated during the key 329 exchange. When encryption is in effect, the length, padding length, 330 payload and padding fields of each packet will be encrypted with the 331 given algorithm. 333 The encrypted data in all packets sent in one direction will be 334 considered a single data stream. For example, initialization vectors 335 will be passed from the end of one packet to the beginning of the next 336 packet. 338 The ciphers in each direction will run independently of each other. 339 They will typically use a different key, and different ciphers can be 340 used in each direction. 342 The following ciphers are currently defined: 344 none optional no encryption 345 3des-cbc mandatory three-key 3DES in CBC mode 346 idea-cbc optional IDEA in CBC mode 347 arcfour optional ARCFOUR stream cipher 348 blowfish-cbc optional Blowfish in CBC mode 350 The 3des-cbc encryption is three-key triple-DES (encrypt-decrypt- 351 encrypt), where the first 8 bytes of the key are used for the first 352 encryption, the next 8 bytes for the decryption, and the following 8 353 bytes for the final encryption. This requires 24 bytes of key data (of 354 which the parity bits are not actually used). To implement CBC mode, 355 there is only one initialization vector. 357 For ciphers with variable-length keys, 128 bit keys are used. 359 The ARCFOUR cipher is compatible with the RC4 cipher; RC4 is a trademark 360 of RSA Data Security, Inc. 362 Descriptions of all of these ciphers can be found e.g. from Bruce 363 Schneier: Applied Cryptography, 2nd ed., John Wiley and Sons, 1996. 365 5.4. Data Integrity 367 Data integrity is protected by including with each packet a message 368 authentication code (MAC) that is computed from a shared secret, packet 369 sequence number, and the contents of the packet. 371 The message authentication algorithm and key are negotiated during key 372 exchange. Initially, no MAC will be in effect, and its length will be 373 zero. After key exchange, the selected MAC will be computed before 374 encryption from the concatenation of packet data (lengths, payload, and 375 padding) and a packet sequence number (stored as a 32-bit integer, MSB 376 first). The integrity key is also used in the computation of the MAC, 377 but the way it is used depends on the MAC algorithm in use. Note that 378 the MAC algorithm may be different for each direction. 380 The packet sequence number is only used for integrity checking. It is 381 never explicitly transmitted, but it is included in MAC computation to 382 ensure that no packets are lost or received out of sequence. The 383 sequence number of the first packet sent is zero; from there on the 384 sequence number is incremented by one for every packet sent (separately 385 for each direction). The packet number is 32 bits and wraps around if 386 32 bits is not enough for representing it. The sequence number is 387 incremented also for packets that are not encrypted or MACed, and is not 388 reset even if keys are renegotiated later. 390 The check bytes resulting from the MAC algorithm are transmitted without 391 encryption as the last part of the packet. The number of check bytes 392 depends on the algorithm chosen. 394 The following MAC algorithms are currently defined: 396 none optional no MAC 397 hmac-md5 optional HMAC-MD5 (length = 16) 398 hmac-sha optional HMAC-SHA (length = 20) 399 md5-8 optional first 8 bytes MD5 key+data+key 400 sha-8 optional first 8 bytes SHA-1 key+data+key 401 sha mandatory SHA of key+data+key (20 bytes) 403 The HMAC methods are described in RFC 2104. 405 The "md5-8" method returns the first 8 bytes of MD5 of the concatenation 406 of the key, authenticated data, and the key again. The "sha-8" method 407 is the same but using the SHA hash. 409 Even though only the "sha" method is mandatory, it is recommended that 410 implementations support and prefer the other methods. (This method 411 exists only as a fallback should unexpected patent problems surface.) 413 6. Key Exchange 415 Key exchange begins by each side sending lists of supported algorithms. 416 Each side has a preferred algorithm, and it is assumed that most 417 implementations at any given time will use the same preferred algorithm. 418 Each side will make the guess that the other side is using the same 419 algorithm, and may send an initial key exchange packet according to the 420 algorithm if appropriate for the preferred method. If the guess is 421 wrong, they'll ignore the guessed packet, select a common algorithm, and 422 send the initial key exchange packet again, this time for the same 423 algorithm. 424 Currently, the following key exchange methods have been defined: 426 double-encrypting-sha mandatory 428 The implementation of these methods is described later in this section. 430 One should note that server authentication in the double-encrypting key 431 exchange is implicit, and the client doesn't really know the identity of 432 the server until it receives a message from the server using the correct 433 MAC and encryption. This means that an attacker could fool the client 434 into using no encryption (if the client is willing to accept no 435 encryption), and the client might in some cases send sensitive data, 436 such as a password, before it notices that the server isn't responding 437 properly. For this reason, it is recommended that clients should not 438 accept "none" encryption unless explicitly requested by the user. 439 Alternatively, they should wait for the server's response to the service 440 request before sending anything else. 442 6.1. Algorithm Negotiation 444 Each side sends the following packet (this is the part that goes inside 445 the payload): 447 vlint32 SSH_MSG_KEXINIT 448 byte[16] cookie (random bytes) 449 string kex_algorithms 450 string server_host_key_algorithms 451 string encryption_algorithms_client_to_server 452 string encryption_algorithms_server_to_client 453 string mac_algorithms_client_to_server 454 string mac_algorithms_server_to_client 455 string compression_algorithms_client_to_server 456 string compression_algorithms_server_to_client 457 string hash_algorithms 458 boolean first_kex_packet_follows 459 byte[4] 0 (reserved for future extension) 461 Each of the algorithms strings are comma-separated lists of algorithm 462 names. Each supported (allowed) algorithm should be listed, in order of 463 preference. The preferred (guessed) algorithm should be listed first. 464 Each string must contain at least one algorithm name. The value "none" 465 is not automatically allowed; if a party permits connections with "none" 466 as one of the algorithms, it should list that as an algorithm. 468 cookie 469 The cookies are random values generated by each side. Their 470 purpose is to make it impossible for either side to fully 471 determine the keys (which might open possibilities for passing 472 certain signatures/authentications to third parties). 474 kex_algorithms 475 Key exchange algorithms were defined above. The first algorithm 476 is the preferred (and guessed) algorithm. If both sides make the 477 same guess, that algorithm is used. Otherwise, the following 478 algorithm is used to choose a key exchange method: iterate over 479 client's kex algorithms, one at a time. Choose the first 480 algorithm that satisfies the following conditions: 1) the server 481 also supports the algorithm 2) if the algorithm requires an 482 encryption-capable host key, there is an encryption-capable 483 algorithm on the server's server_host_key_algorithms that is 484 also supported by the client 3) if the algorithm requires a 485 signature-capable host key, there is a signature-capable algorithm 486 on the server's server_host_key_algorithms that is also 487 supported by the client. If no algorithm satisfying all these 488 conditions can be found, connection fails. 490 The kex algorithm names were listed above. 492 server_host_key_algorithms 493 Lists the algorithms supported for the server host key. The 494 server lists the algorithms for which it has host keys; the client 495 lists the algorithms that it is willing to accept. (There can be 496 multiple host keys for a host, possibly with different 497 algorithms.) 499 Some host keys may not support both signatures and encryption 500 (this can be determined from the algorithm), and thus not all host 501 keys are valid for all key exchange methods. 503 Algorithm selection depends on whether the chosen kex algorithm 504 requires a signature- or encryption capable host key. The first 505 algorithm on the client's list that satisfies the requirements and 506 is also supported by the server is chosen. 508 Section ``Public Key Formats'' lists the available algorithm 509 names. 511 encryption_algorithms 512 Lists the acceptable symmetric encryption algorithms in order of 513 preference. The chosen encryption algorithm will be the first 514 algorithm on the client's list that is also on the server's list. 515 If there is no such algorithm, connection fails. 517 Note that "none" must be explicitly listed if it is to be 518 acceptable. The defined algorithm names are listed in Section 519 ``Encryption''. 521 The algorithm to use is negotiated separately for each direction, 522 and different algorithms may be chosen. 523 mac_algorithms 524 Lists the acceptable MAC algorithms in order of preference. The 525 chosen MAC algorithm will be the first algorithm on the client's 526 list that is also on the server's list. If there is no such 527 algorithm, connection fails. 529 Note that "none" must be explicitly listed if it is to be 530 acceptable. The MAC algorithm names are listed in Section ``Data 531 Integrity''. 533 The algorithm to use is negotiated separately for each direction, 534 and different algorithms may be chosen. 536 compression_algorithms 537 Lists the acceptable compression algorithms in order of 538 preference. The chosen compression algorithm will be the first 539 algorithm on the client's list that is also on the server's list. 540 If there is no such algorithm, connection fails. 542 Note that "none" must be explicitly listed if it is to be 543 acceptable. The compression algorithm names are listed in Section 544 ``Compression''. 546 The algorithm to use is negotiated separately for each direction, 547 and different algorithms may be chosen. 549 hash_algorithms 550 Lists the acceptable hash algorithms in order of preference. The 551 chosen hash algorithm will be the first algorithm on the client's 552 list that is also on the server's list. If there is no such 553 algorithm, connection fails. 555 Implementations should only permit algorithms that they consider 556 to be fairly secure, as the hash function will be used e.g. for 557 deriving various keys from the shared secret. All hash algorithms 558 must produce at least 16 bytes of output. 560 Currently, the following hash functions are defined. 562 md5 optional MD5 algorithm (16 byte output) 563 sha mandatory SHA-1 algorithm (20 byte output) 565 first_kex_packet_follows 566 Each side makes a guess of the negotiated key exchange method. 567 This is based on the assumption that at any particular time there 568 will be a single key exchange method and algorithm combination 569 that dominates the installed base. Making a guess about the 570 algorithm will save a round-trip in the typical case, and will 571 incur little extra cost in the other cases. 573 Each side will determine if they are supposed to send an initial 574 packet in their guessed key exchange method. If they are, they 575 will set this field to true and follow this packet by the first 576 key exchange packet. 578 The guessed method is the one listed first on the kex_algorithms, 579 server_host_key_algorithms, and hash_algorithms lists. If the 580 negotiated values for any of these algorithms differs from the 581 first value on either side, the guess is taken to be wrong, and 582 the packet sent based on the guess is ignored. Whether the 583 packets based on the guess are actually wrong is not a factor in 584 this decision (the information may not be available to make this 585 decision). 587 After receiving the SSH_MSG_KEXINIT packet from the other side, 588 each party will know whether their guess was right. If the guess 589 was wrong, and this field is true, the next packet will be 590 silently ignored, and each side will then act as determined by the 591 negotiated key exchange method. If the guess was right, key 592 exchange will immediately continue. 594 6.2. Double-Encrypting Key Exchange 596 The double-encrypting key exchange requires that the server host key 597 supports encryption. The idea is that the server sends its public host 598 key and a periodically changing key (called the server key). The client 599 then verifies that it is the correct key for the server, generates a 600 session key, encrypts the session key using both a time-variant server 601 key and the server host key, and sends the encrypted session key to the 602 server. 604 The server key and host keys must both support encryption, and their 605 sizes must be such that the server key can encrypt at least 48 bytes, 606 and the server host key can encrypt the result of the first encryption. 607 Note that padding is normally added at each encryption, depending on the 608 public key method, so the actual size difference of the keys is bigger. 609 Both keys must use the same public key algorithm. 611 6.2.1. Server Sends Host Key 613 First, the server sends its public host and server keys in the following 614 packet: 616 vlint32 SSH_MSG_KEXDE_HOSTKEY 617 string public host key 618 string public server key 620 The host key and server key are stored in binary representation as 621 described in Section ``Public Key Formats''. Both keys are of the type 622 negotiated for the server host key. 624 After receiving the public keys, the client validates that the host key 625 really belongs to the intended server. How this verification happens is 626 not specified in this protocol. Currently it may be checked against a 627 database of known name-key mappings; in future it will be validated 628 using an Internet public key infrastructure. The key may contain 629 certificates to facilitate this. 631 If the client is not willing to trust the server host key, it should 632 send an SSH_MSG_DISCONNECT packet and close the connection. 634 The client then generates a 256 bit random session key (shared secret). 636 6.2.2. Deriving Exchange Hash and Session Identifier 638 To authenticate that no-one has been manipulating the key exchange with 639 the server, the client computes an SHA-1 hash of the concatenation of 640 the following (in this order): 642 1. the length of the payload of the client's SSH_MSG_KEXINIT message as 643 4 bytes, MSB first, 645 2. the payload of the client's SSH_MSG_KEXINIT message, 647 3. the length of the payload of the server's SSH_MSG_KEXINIT message as 648 4 bytes, MSB first, 650 4. the payload of the server's SSH_MSG_KEXINIT message, 652 5. the length of the payload of the server's SSH_MSG_KEXDE_HOSTKEY 653 message as 4 bytes, MSB first, 655 6. the payload of the server's SSH_MSG_KEXDE_HOSTKEY message, and 657 7. the 32 bytes of the session key. 659 This value is called the exchange hash, and it is used to 660 authenticate the key exchange. 662 Note that the use of SHA-1 was hard-coded here. This is used to 663 authenticate the key exchange, and using HASH here would lead to all 664 sorts of potential problems in verifying the security of the protocol. 665 Using a fixed hash short-circuits verification to the properties of 666 SHA-1. Should the need ever arise, the only way to switch to another 667 algorithm here is to define a new key exchange algorithm (which, in 668 fact, is not very difficult). 670 The exchange hash from the first key exchange in a connection is called 671 the session identifier. It is used in host authentication and other 672 authentication methods as data that is signed to prove possession of a 673 private key. 675 Once computed, the session identifier is not changed or recomputed even 676 if keys are later re-exchanged. The exchange hash, on the other hand, 677 is computed separately for each key exchange. 679 6.2.3. Client Sends Double-Encrypted Session Key 681 The client forms a message to send to the server by concatenating the 682 following (in this order): six zero bytes (reserved for future 683 extension), first 10 bytes of the exchange hash, and the 32 bytes of the 684 shared secret. This results in a total of 48 bytes of data to be passed 685 to the server. Note that the negotiated algorithms are not explicitly 686 passed, as the algorithms given in Section ``Algorithm Negotiation'' 687 fully determine the algorithms. 689 The resulting data is encrypted first with the time-variant server key, 690 and the result then with the server host key. The resulting double- 691 encrypted value is then sent to the server. Note that public-key 692 encryption probably involves padding, depending on the algorithm. 694 vlint32 SSH_MSG_KEXDE_SESSIONKEY 695 string double-encrypted session key 697 Upon receiving this message, the server uses its private host and server 698 keys to decrypt the session key. It computes a corresponding SHA hash, 699 and compares the hash values. If the hash does not match, the server 700 disconnects with the appropriate message. If the hash matches, the 701 server responds with an SSH_MSG_NEWKEYS message and takes the keys into 702 use. 704 6.2.4. Deriving Encryption and Integrity Keys 706 As a result of the key exchange, the parties have a 256-bit shared 707 secret. Various keys are computed from this secret and the exchange 708 hash. The session identifier is used to make it impossible for either 709 party to alone determine the keys. 711 Each key is computed as HASH of the concatenation of the session 712 identifier and 16 bytes of secret data. The secret data is different 713 for each key, and is taken from the 32-byte shared secret as follows: 715 o Initial IV client to server: bytes 0-15 717 o Initial IV server to client: bytes 1-16 719 o Encryption key client to server: bytes 5-20 721 o Encryption key server to client: bytes 8-23 723 o Integrity key client to server: bytes 13-28 724 o Integrity key server to client: bytes 16-31 726 Key data is taken from the beginning of the hash output. 128 bits (16 727 bytes) will be used for algorithms with variable-length keys. For other 728 algorithms, as many bytes are needed from the beginning of the hash 729 value as are needed. If a longer key is needed for some algorithm than 730 is the output of the hash, the key is extended by computing HASH of the 731 entire key so far, and appending the resulting bytes (as many as HASH 732 outputs) to the key. This process is repeated until enough key material 733 is available; the key is taken from the beginning of this value. (Note 734 that extending the key does not increase its strength or entropy; 735 however, 128 bits already provides enough entropy.) 737 6.3. Taking Keys into Use 739 Key exchange ends by each side sending an SSH_MSG_NEWKEYS message. This 740 message is sent with the old keys and algorithms. All messages sent 741 after this message use the new keys and algorithms. 743 When this message is received, the new keys and algorithms are taken 744 into use for receiving. 746 This message is the only valid message after key exchange, in addition 747 to SSH_MSG_DISCONNECT and SSH_MSG_IGNORE messages. The purpose of this 748 message is to ensure that a party is able to respond with a disconnect 749 message that the other party can understand if something goes wrong with 750 the key exchange. 752 vlint32 SSH_MSG_NEWKEYS 754 7. Key Re-Exchange 756 Either side may request re-exchange of keys at any time after the 757 service request has been accepted (and outside other key exchanges). 758 The re-exchange is not visible to the service. 760 Key re-exchange is started by sending a SSH_MSG_KEXINIT packet 761 (described in Section ``Algorithm Negotiation''). When this message is 762 received, a party must respond with its own SSH_MSG_KEXINIT message. 763 Either party may initiate the re-exchange, but roles are not changed 764 (i.e., the server remains the server, and the client remains the 765 client). 766 Key re-exchange is performed under whatever encryption was in effect 767 when the exchange was started. Encryption, compression, and MAC methods 768 are changed when SSH_MSG_NEWKEYS is sent after the key exchange (as in 769 the initial key exchange). Re-exchange is processed identically to the 770 initial key exchange. It is permissible to change any or all of the 771 algorithms during the re-exchange. Host keys can also change. All keys 772 and initialization vectors are recomputed after the exchange. 773 Compression and encryption contexts are reset. The packet sequence 774 number is not reset. The session identifier is not changed. 776 It is recommended that keys be changed after each gigabyte of 777 transmitted data or after each hour of connection time, whichever comes 778 sooner. 780 It is also possible to use the key re-exchange mechanism to switch to 781 faster algorithms after authentication, or to avoid double processing 782 for pre-encrypted or pre-authenticated data. However, since the re- 783 exchange is a public key operation, it requires a fair amount of 784 processing power and should not be performed too often. 786 More application data may be sent after the SSH_MSG_NEWKEYS packet has 787 been sent. 789 8. Service Request 791 After the various authentications, the client requests a service. The 792 service is identified by a name. Service names can contain any non- 793 control characters. The name must not be longer than 64 characters. 794 Service names are case-sensitive. 796 vlint32 SSH_MSG_SERVICE_REQUEST 797 string service name 799 Most server implementations will have a table of services that are 800 supported, specifying what to do for each service. 802 If the server rejects the service request, it should send a 803 SSH_MSG_DISCONNECT message. 805 When the service starts, it will have access to the session identifier 806 generated during key exchange. 808 If the server supports the service (and permits the client to use it), 809 it responds with 811 vlint32 SSH_MSG_SERVICE_ACCEPT 813 The client is permitted to send further packets without waiting for the 814 this message; those packets will go to the selected service if the 815 server accepts the service request. Message numbers used by services 816 should be in the area reserved for services (see Section ``Summary of 817 Message Numbers''). The transport level will continue to process its 818 own messages. 820 The service name is not considered confidential information. An active 821 network-level attacker may discover the service name by a man-in-the- 822 middle attack. Successful reception of the service accept message will 823 confirm to the client that the server successfully received the session 824 key and that the key exchange was not tampered with. 826 If the negotiated cipher is "none", the client must wait until the 827 service accept message has been successfully received before sending any 828 more data. Otherwise, an attacker could learn this data by modifying 829 negotiation parameters in such a way that the "none" cipher gets 830 selected. 832 9. Stream-Based Services 834 It is expected that many services will actually be implemented by 835 applications that communicate with this protocol through pipes or some 836 other mechanism that passes a reliable stream of binary bytes. For 837 those services, we define a protocol for passing data over this 838 protocol. However, it is completely up to the particular service 839 whether it uses this protocol or something else. 841 Once a service has been selected, data is transmitted in each direction 842 asynchronously. The data is packetized using the following format: 844 vlint32 SSH_MSG_STREAM_DATA 845 string data 847 When the server or client application closes its output (i.e., will not 848 send more data), the following message is sent to the other side: 850 vlint32 SSH_MSG_STREAM_EOF 852 No data can be sent after sending this message. Data can still be 853 transmitted in the other direction. 855 When either party wishes to terminate communication, it sends 856 SSH_MSG_STREAM_CLOSE. Upon receiving that message, a party should 857 immediately send back SSH_MSG_STREAM_CLOSE unless it has already sent 858 that. 859 vlint32 SSH_MSG_STREAM_CLOSE 861 After both sending and receiving this message, the communications 862 channel should be closed. 864 10. Additional Messages 866 Either party may send any of the following messages at any time. 868 10.1. Disconnection Message 870 vlint32 SSH_MSG_DISCONNECT 871 vlint32 reason code 872 string description 874 This message causes immediate termination of the connection. The 875 description field gives the reason for disconnecting in human-readable 876 form in English. The error code gives the reason in a machine-readable 877 format (suitable for localization), and can have the following values: 879 #define SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1 880 #define SSH_DISCONNECT_PROTOCOL_ERROR 2 881 #define SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3 882 #define SSH_DISCONNECT_HOST_AUTHENTICATION_FAILED 4 883 #define SSH_DISCONNECT_MAC_ERROR 5 884 #define SSH_DISCONNECT_COMPRESSION_ERROR 6 885 #define SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7 886 #define SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8 887 #define SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9 888 #define SSH_DISCONNECT_CONNECTION_LOST 10 889 #define SSH_DISCONNECT_BY_APPLICATION 11 891 10.2. Ignored Data Message 893 vlint32 SSH_MSG_IGNORE 894 string data 896 All implementations must understand (and ignore) this message at any 897 time (after receiving the protocol version). No implementation is 898 required to ever send them. 900 10.3. Debug Message 902 vlint32 SSH_MSG_DEBUG 903 vlint32 type 904 string message 906 All implementations must understand this message, but they are allowed 907 to ignore it. This message is used to pass information to the other 908 side which may help debugging problems. The type may have any of the 909 following values: 911 0 SSH_DEBUG_DEBUG 912 The message contains information that may be useful for debugging 913 problems; however, it should not normally be shown to the user. 914 It is recommended that the data be available to the user for 915 debugging purposes if explicitly requested. 917 1 SSH_DEBUG_DISPLAY 918 The message contains information that should preferably be shown 919 to the user regardless of whether debugging information has been 920 requested. 922 The message need not contain a newline. It is, however, allowed to 923 consist of multiple lines separated by newlines. 925 10.4. Reserved Messages 927 An implementation must respond to all unrecognized messages with an 928 SSH_MSG_UNIMPLEMENTED message in the order in which they were received. 929 Later protocol versions may define other meanings for these message 930 types. 932 vlint32 SSH_MSG_UNIMPLEMENTED 933 uint32 packet sequence number of rejected message 935 11. Summary of Message Numbers 937 The following message numbers have been defined in this protocol. 939 #define SSH_MSG_DISCONNECT 1 940 #define SSH_MSG_IGNORE 2 941 #define SSH_MSG_UNIMPLEMENTED 3 942 #define SSH_MSG_DEBUG 4 943 #define SSH_MSG_KEXINIT 10 944 #define SSH_MSG_NEWKEYS 11 945 #define SSH_MSG_SERVICE_REQUEST 12 946 #define SSH_MSG_SERVICE_ACCEPT 13 948 /* Numbers 15-19 for kex packets. 949 Different kex methods may reuse message numbers in 950 this range. */ 951 #define SSH_MSG_KEXDE_HOSTKEY 15 952 #define SSH_MSG_KEXDE_SESSIONKEY 16 954 /* Numbers 20- are reserved for service types. 955 Different service types may reuse the same messages. 956 Messages for stream-based services. Other service types 957 may be defined in other documents. */ 958 #define SSH_MSG_STREAM_DATA 20 959 #define SSH_MSG_STREAM_EOF 21 960 #define SSH_MSG_STREAM_CLOSE 22 962 12. Public Keys and Public Key Infrastructure 964 This protocol has been designed to be able to operate with almost any 965 public key format, encoding, and algorithm. 967 There are several aspects that define a public key type: 969 o Key format: how is the key encoded and how are certificates 970 represented. The key blobs in this protocol may (but are not 971 required to) contain certificates in addition to keys. 973 o Signature and/or encryption algorithms. Some algorithms may not 974 support both encryption and decryption. Key usage may also be 975 restricted by policy statements in e.g. certificates. 977 o Encoding of signatures and encrypted data. This includes but is not 978 limited to padding, byte order, and data formats. 980 The following public key formats are currently defined: 982 x509 X.509 certificate 983 spki IETF SPKI certificate 984 ssh-rsa-pkcs1 RSA key with PKCS-1 encodings 986 Note that the key type is negotiated at the beginning of the key 987 exchange, and is not included in the key blob itself. 989 12.1. x509 991 X.509 is the most widely used certificate format at the time of this 992 writing. However, X.509 has many serious problems, both on a conceptual 993 and implementation level. X.509v3 has addressed many of these problems, 994 and may be more usable than previous versions. 996 The key blob for an "x509" key blob is an X.509 (v3) certificate in 997 ASN.1 (DER) format. 999 12.2. spki 1001 SPKI (Simple Public Key Infrastructure) is based on the philosophy that 1002 most applications actually require authorization, not identification. 1003 SPKI also addresses naming and policy issues in an explicit and useful 1004 way. 1006 The key blob for an "spki" key blob contains a SPKI key optionally 1007 followed by certificates. 1009 12.3. ssh-rsa-pkcs1 1011 This key type defines an RSA public key, with (mostly) PKCS compatible 1012 signature and encryption formats. It supports both signatures and 1013 encryption. 1015 Public keys of this type are represented as follows: 1017 uint32 number of bits in the modulus 1018 uint32 number bits in the public exponent 1019 bytes[n] exponent, MSB first, n = floor((bits+7)/8) 1020 uint32 number of bits in the modulus 1021 bytes[n] modulus, MSB first, n = floor((bits+7)/8) 1023 It is permissible that there be other data (e.g., certificates) 1024 following this; however, such data is not yet defined. 1026 Note that private key formats are not defined here, and are 1027 implementation-specific. 1029 An encrypted message is formed as follows (this follows PKCS-1 padding 1030 rules). 1032 o The data to be encrypted is padded into a long integer of the same 1033 number of bits as the modulus as follows: 1035 MSB . . . LSB 1037 0 2 RND(n bytes) 0 encrypted_data 1039 The RND bytes represent non-zero random bytes. 1041 o To encrypt, this integer is raised to the public exponent, modulo the 1042 modulus. 1044 o The result is converted to a byte string of floor((bits+7)/8) bytes 1045 (where bits is the number of bits in the modulus), MSB first. This 1046 byte string (without any length or terminating characters) is the 1047 result of the encryption. 1049 A signature is formed as follows. 1051 o The data to be signed (typically a message digest, but not required 1052 to be such) is padded into a long integer of the same number of bits 1053 as the modulus as follows: 1055 MSB . . . LSB 1057 0 1 FF (n bytes) 0 signed_data 1059 o To sign, this integer is raised to the private exponent, modulo the 1060 modulus. 1062 o The result is converted to a byte string of floor((bits+7)/8) bytes 1063 (where bits is the number of bits in the modulus), MSB first. This 1064 byte string (without any length or terminating characters) is the 1065 signature. Applications may add other data outside this value. 1067 13. Address of Author 1069 Tatu Ylonen 1070 SSH Communications Security Ltd. 1071 Tekniikantie 12 1072 FIN-02150 ESPOO 1073 Finland 1075 E-mail: ylo@ssh.fi