idnits 2.17.1 draft-ietf-tls-ssh-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-24) 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 == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 59 lines 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 379 has weird spacing: '... string kex...' == Line 380 has weird spacing: '... string hos...' == Line 381 has weird spacing: '... string pub...' == Line 382 has weird spacing: '... string enc...' == Line 383 has weird spacing: '... string enc...' == (17 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 (June 13, 1996) is 10177 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 378 looks like a reference -- Missing reference section? '4' on line 885 looks like a reference Summary: 9 errors (**), 0 flaws (~~), 8 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Tatu Ylonen 3 INTERNET-DRAFT SSH Communications Security 4 draft-ietf-tls-ssh-00.txt June 13, 1996 5 Expires: December 1st, 1996 7 SSH Transport Layer 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 This document describes the SSH transport layer protocol. The protocol 30 can be used as a basis for a number of secure network services. It pro- 31 vides strong encryption, mutual authentication, and integrity protec- 32 tion. 34 Table of Contents 36 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 37 2. Data Type Representations Used in the Protocol . . . . . . . . . 3 38 2.1. vlint32 . . . . . . . . . . . . . . . . . . . . . . . . . . 3 39 2.2. string . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 40 2.3. boolean . . . . . . . . . . . . . . . . . . . . . . . . . . 3 41 2.4. byte . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 42 2.5. uint16 . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 43 2.6. uint32 . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 44 3. Connection Setup . . . . . . . . . . . . . . . . . . . . . . . . 4 45 3.1. Use over TCP/IP . . . . . . . . . . . . . . . . . . . . . . 4 46 3.2. Protocol Version Exchange . . . . . . . . . . . . . . . . . 4 47 3.3. Compatibility with Old SSH Versions . . . . . . . . . . . . 4 48 3.3.1. Old Client, New Server . . . . . . . . . . . . . . . . . 4 49 3.3.2. New Client, Old Server . . . . . . . . . . . . . . . . . 5 50 4. Binary Packet Protocol . . . . . . . . . . . . . . . . . . . . . 5 51 4.1. Maximum Packet Length . . . . . . . . . . . . . . . . . . . 5 52 4.2. Compression . . . . . . . . . . . . . . . . . . . . . . . . 6 53 4.3. Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 6 54 4.4. Data Integrity . . . . . . . . . . . . . . . . . . . . . . . 7 55 5. Key Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . 7 56 5.1. Sending Supported Algorithm Lists . . . . . . . . . . . . . 8 57 5.2. RSA-Style Key Exchange . . . . . . . . . . . . . . . . . . . 11 58 5.2.1. Server Sends Host Key . . . . . . . . . . . . . . . . . 11 59 5.2.2. Client Sends Double-Encrypted Session Key . . . . . . . 11 60 5.3. Diffie-Hellman Style Key Exchange . . . . . . . . . . . . . 12 61 5.4. Deriving Encryption and Integrity Keys . . . . . . . . . . . 12 62 6. Client Host Authentication . . . . . . . . . . . . . . . . . . . 13 63 7. Service Request . . . . . . . . . . . . . . . . . . . . . . . . 14 64 8. Data Exchange . . . . . . . . . . . . . . . . . . . . . . . . . 14 65 9. Key Re-Exchange . . . . . . . . . . . . . . . . . . . . . . . . 15 66 10. Additional Messages . . . . . . . . . . . . . . . . . . . . . . 16 67 10.1. Disconnection Message . . . . . . . . . . . . . . . . . . . 16 68 10.2. Ignored Data Message . . . . . . . . . . . . . . . . . . . 16 69 10.3. Reserved Messages . . . . . . . . . . . . . . . . . . . . . 16 70 11. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 17 71 12. Public Keys and Public Key Infrastructure . . . . . . . . . . . 17 72 12.1. SSH_PK_SIMPLE_RSA_PKCS . . . . . . . . . . . . . . . . . . 17 74 1. Introduction 76 The SSH protocol is a secure transport layer protocol. It provides 77 strong encryption, cryptographic host autentication, and integrity 78 protection. 80 Authentication in this protocol level is host-based; this protocol does 81 not perform user authentication. It is expected that a higher level 82 protocol will be defined on top of this protocol that will perform user 83 authentication for those services that need it. 85 The protocol has been designed to be simple, flexible, allow parameter 86 negotiation, and minimize the number of round-trips. Key exchange 87 method, public key algorithm, symmetric encryption algorithm, message 88 authentication algorithm, and hash algorithm are all negotiated. It is 89 expected that in most environments, only 1.5 round-trips will be needed 90 for full key exchange, mutual authentication, service request, and 91 acceptance notification of service request. The worst case is 2.5 92 round-trips for a proper implementation. 94 2. Data Type Representations Used in the Protocol 96 2.1. vlint32 98 The vlint32 can represent arbitrary 32-bit unsigned integers. It is 99 stored as a variable number of bytes (1-5 bytes), depending on the value 100 being stored. 102 Bits 6-7 of the first byte determine the number of additional bytes that 103 follow, and are interpreted as follows. 105 Bit7 Bit6 Number of bytes that follow 106 0 0 0 107 0 1 1 108 1 0 2 109 1 1 4 111 Bits 0-6 of the first byte and the following bytes contain the value of 112 the integer, MSB first. 114 If bits 6-7 are both one, the remaining bits in the first byte are zero 115 (reserved for future extension). 117 2.2. string 119 A string here means an arbitrary length binary string. Strings are 120 allowed to contain arbitrary binary data, including null characters and 121 8-bit characters. 123 A string is represented as a vlint32 containing its length, followed by 124 zero or more characters that are the value of the string. 126 2.3. boolean 128 A boolean value is represented as a single byte. The value 0 represents 129 false, and the value 1 represents true. All non-zero values are 130 interpreted as true, but applications should not store values other than 131 0 and 1. 133 2.4. byte 135 A byte represents an arbitrary 8-bit value. Fixed length data is 136 sometimes represented as byte array of bytes, written byte[n], where n 137 is the number of bytes in the array. 139 2.5. uint16 141 A 16-bit unsigned integer, represented as two bytes, MSB first. 143 2.6. uint32 145 A 32-bit unsigned integer, represented as four bytes, MSB first. 147 3. Connection Setup 149 SSH works over any 8-bit clean, binary-transparent transport. The 150 client initiates the connection, and sets up the binary-transparent 151 transport. 153 3.1. Use over TCP/IP 155 When used over TCP/IP, the server normally listens for connections on 156 port 22. This port number has been registered with the IANA (Internet 157 Assigned Numbers Authority), and has been officially assigned for SSH. 159 3.2. Protocol Version Exchange 161 When the connection has been established, both sides send an 162 identification string of the form "SSH-protoversion-softwareversion 163 comments", followed by a newline. The maximum length of the string is 164 255 characters, including the newline. The protocol version described 165 in this document is 2.0. 167 Key exchange will begin immediately after sending this identifier 168 (normally without waiting for the identifier from the other side -- see 169 the next section for compatibility issues). All packets following the 170 identification string will use the binary packet protocol, to be 171 described below. 173 3.3. Compatibility with Old SSH Versions 175 During a transition period, it is important to be able to work 176 compatibly with installed SSH clients and servers using an older version 177 of the protocol. Information in this section is only relevant for 178 implementations supporting compatibility with old versions. 180 3.3.1. Old Client, New Server 182 Server implementations should support a configurable "compatibility" 183 flag that enables compatibility with old versions. When this flag is 184 on, the server will not send any further data after its initialization 185 string until it has received an identification string from the client. 186 The server can then determine whether the client is using an old 187 protocol, and can revert to the old protocol if desired. 189 When compatibility with old clients is not needed, the server should 190 send its initial key exchange data immediately after the identification 191 string. This saves a round-trip. 193 3.3.2. New Client, Old Server 195 Since the new client will immediately send additional data after its 196 identification string (before receiving server's identification), the 197 old protocol has already been corrupted when the client learns that the 198 server is old. When this happens, the client should close the 199 connection to the server, and reconnect using the old protocol this 200 time. 202 4. Binary Packet Protocol 204 Each packet consists of the following fields: 206 Length 207 The length of the packet (bytes). This represents the number of 208 bytes that follow this value, including the optional MAC. The 209 length is represented as a vlint32. 211 Padding length 212 Length of padding (bytes). This field is represented as a 213 vlint32. 215 Payload 216 The useful contents of the packet. 218 Padding 219 Arbitrary-length padding, such that the total length of 220 length+paddinglength+payload+padding is a multiple of 8 bytes. It 221 is recommended that at least four bytes of random padding be 222 always used. 224 MAC 225 Message authentication code. This field is optional, and its 226 length depends on the algorithm in use. 228 Note that length of the concatenation of packet length, padding length, 229 payload, and padding must be a multiple of 8. This constraint is 230 enforced even when using stream ciphers. Note that the packet length 231 field is also encrypted, and processing it requires special care when 232 sending/receiving packets. In particular, one has to be extra careful 233 when computing the amount of padding, as changing the amount of padding 234 can also change the size of the length fields. The minimum size of a 235 packet is 8 characters (plus MAC); implementations should decrypt the 236 length after receiving the first 8 bytes of a packet. 238 When the protocol starts, no encryption is in effect, no compression is 239 used, and no MAC is in use. During key exchange, an encryption method, 240 compression method, and a MAC method are selected. Any further messages 241 will use the negotiated algorithms. 243 4.1. Maximum Packet Length 245 The maximum length of the uncompressed payload is 32768 bytes. The 246 maximum size of the entire packet, including length, padding length, 247 payload, padding, and MAC, is 35000 bytes. The motivation for this 248 limit is to keep the protocol easy to implement on 16-bit machines. 250 4.2. Compression 252 If compression has been negotiated, the payload field will be compressed 253 using the negotiated algorithm. The length field will contain the 254 compressed length (i.e., that transmitted on the wire). 256 Compressed packets must not exceed the total packet size limit; the 257 compression algorithm must guarantee that it does not expand the packet 258 too much. The uncompressed payload size must not exceed the maximum 259 payload size (the compressed payload, however, may be bigger than the 260 maximum payload size, as long as the packet size limit is not exceeded). 262 The following compression methods are currently supported: 264 #define SSH_COMPRESS_NONE 0 /* no compression */ 265 #define SSH_COMPRESS_ZIP 1 /* ZIP compression */ 267 SSH_COMPRESS_ZIP is the ZLIB compression. Its data format is described 268 in the Internet-Draft draft-deutsch-zlib-spec-04.txt and its references. 269 Compression level 6 is recommended. 271 The compression context is initialized after key exchange, and is passed 272 from one packet to the next with only a partial flush being performed at 273 the end of each packet. A partial flush means that all data will be 274 output, but the next packet will continue using compression tables from 275 the end of the previous packet. 277 Compression is independent in each direction, and the different 278 compression methods may be used for each direction. 279 4.3. Encryption 281 An encryption algorithm and a key will be negotiated during the key 282 exchange. When encryption is in effect, the length, payload and padding 283 fields of each packet will be encrypted with the given algorithm. 285 The encrypted data in all packets sent in one direction will be 286 considered a single data stream. For example, initialization vectors 287 will be passed from the end of one packet to the beginning of the next 288 packet. 290 The ciphers in each direction will run independently of each other. 291 They will typically use a different key, and different ciphers can be 292 used in each direction. 294 The following ciphers/mode combinations are currently supported: 296 #define SSH_CALG_NONE 0 /* No encryption */ 297 #define SSH_CALG_IDEA_CBC 1 /* IDEA in CBC mode */ 298 #define SSH_CALG_3DES_CBC 2 /* 3DES in CBC mode */ 299 #define SSH_CALG_DES_CBC 3 /* DES in CBC mode (warning: weak!) */ 300 #define SSH_CALG_ARCFOUR 4 /* ARCFOUR stream cipher */ 302 The ARCFOUR cipher is compatible with the RC4 cipher; RC4 is a trademark 303 of RSA Data Security, Inc. 305 4.4. Data Integrity 307 Data integrity is protected by including with each packet a message 308 authentication code (MAC) that is computed from a shared secret, packet 309 sequence number, and the contents of the packet. 311 The message authentication algorithm and key are negotiated during key 312 exchange. Initially, no MAC will be in effect, and its length will be 313 zero. After key exchange, the selected MAC will be computed before 314 encryption from the concatenation of packet data (length, payload, and 315 padding) and a packet sequence number (stored as a 32-bit integer, MSB 316 first). The integrity key is also used in the computation of the MAC, 317 but the way it is used depends on the MAC algorithm in use. Note that 318 the MAC algorithm may be different for each direction. 320 The packet sequence number is only used for integrity checking. It is 321 never explicitly transmitted, but it is included in MAC computation to 322 ensure that no packets are lost. The sequence number of the first 323 packet sent is zero; from there on the sequence number is incremented by 324 one for every packet sent (separately for each direction). The packet 325 number is 32 bits and wraps around if 32 bits is not enough for 326 representing it. The sequence number is incremented also for packets 327 that are not encrypted or MACed, and is not reset even if keys are 328 renegotiated later. 330 The check bytes resulting from the MAC algorithm are transmitted without 331 encryption as the last part of the packet. The number of check bytes 332 depends on the algorithm chosen. 334 The following MAC algorithms are currently defined: 336 #define SSH_MAC_NONE 0 /* No MAC in use (length = 0) */ 337 #define SSH_MAC_HMAC_MD5 1 /* HMAC-MD5 (length = 16) */ 338 #define SSH_MAC_HMAC_SHA 2 /* HMAC-SHA-1 (length = 20) */ 339 #define SSH_MAC_MD5 3 /* MD5 of data+key (length = 16) */ 341 The HMAC methods are described in draft-ietf-ipsec-hmac-md5-00.txt. 343 The SSH_MAC_MD5 method returns the MD5 of the concatenation of the 344 authenticated data and the key. 346 5. Key Exchange 348 Key exchange begins by each side sending lists of supported algorithms. 349 Each side has a preferred algorithm, and it is assumed that most 350 implementations at any given time will use the same preferred algorithm. 351 Each side will make the guess that the other side is using the same 352 algorithm, and may send an initial key exchange packet according to the 353 algorithm if the preferred method so dictates. If the guess is wrong, 354 they'll ignore each other's first data, select a common algorithm, and 355 send the initial key exchange packet again, this time for the same 356 algorithm. 358 At this time, there are two styles of key exchanges, RSA-style exchange 359 and Diffie-Hellman style exchange (several methods may be available in 360 each group). RSA-style exchange is based on the server sending two 361 encryption public keys (host key and server key), the client generating 362 a session key, sending it encrypted by the public keys, and server 363 decrypting it with private keys. In Diffie-Hellman style exchange the 364 parties derive a shared secret via a message exchange, and then check 365 against man-in-the-middle attacks with a signature of the exchange. 367 Currently, the following key exchange methods have been defined: 369 #define SSH_KEX_RSA_SHA 1 /* RSA key exchange with SHA-1 */ 370 #define SSH_KEX_DH_SHA 2 /* Diffie-Hellman kex with SHA-1 */ 372 5.1. Sending Supported Algorithm Lists 374 Each side sends the following packet (this is the part that goes inside 375 the payload): 377 vlint32 SSH_MSG_KEXINIT 378 byte[16] cookie (random bytes) 379 string kex_algorithms 380 string host_key_algorithms 381 string public_key_algorithms 382 string encryption_algorithms_client_to_server 383 string encryption_algorithms_server_to_client 384 string mac_algorithms_client_to_server 385 string mac_algorithms_server_to_client 386 string compression_algorithms_client_to_server 387 string compression_algorithms_server_to_client 388 string hash_algorithms 389 boolean first_kex_packet_follows 390 byte[4] 0 (reserved for future extension) 392 Each of the algorithms strings contains algorithm numbers, one per byte. 393 Each supported (allowed) algorithm should be listed, in order of 394 preference. Each string must contain at least one value. The value 395 "NONE" is not automatically allowed; if a party permits connections with 396 NONE as one of the algorithms, it should list that as an algorithm. 398 cookie 399 The cookies are random values generated by each side. They are 400 used when deriving keys from the shared secret. Their purpose is 401 to make it impossible for either side to fully determine the keys 402 (which might open possibilities for passing certain 403 signatures/authentications to third parties). 405 kex_algorithms 406 Key exchange algorithms were defined above. The first algorithm 407 is the preferred (and guessed) algorithm. If both sides make the 408 same guess, that algorithm is used. Otherwise, the following 409 algorithm is used to choose a key exchange method: iterate over 410 client's kex algorithms, one at a time. Choose the first 411 algorithm that satisfies the following conditions: 1) the server 412 also supports the algorithm 2) if the algorithm requires an 413 encryption-capable host key, there is an encryption-capable 414 algorithm on the server's host_key_algorithms that is also 415 supported by the client 3) if the algorithm requires a signature- 416 capable host key, there is a signature-capable algorithm on the 417 server's host_key_algorithms that is also supported by the 418 client. If no algorithm satisfying all these conditions can be 419 found, connection fails. 421 The available algorithm numbers were listed above. 422 host_key_algorithms 423 Lists the public key algorithms/formats for which the host has a 424 valid host key. (There can be multiple host keys for a host, 425 possibly with different algorithm.) Some host keys may not 426 support both signatures and encryption (this can be determined 427 from the algorithm), and thus not all host keys are valid for all 428 key exchange methods. Algorithms listed in this field must also 429 be present in public_key_algorithms. 431 See Section ``Public Key Formats'' for information on the 432 algorithm numbers. 434 public_key_algorithms 435 Lists the public key algorithms supported by the host. See 436 Section ``Public Key Formats'' for information on the algorithm 437 numbers. 439 encryption_algorithms 440 Lists the acceptable symmetric encryption algorithms in order of 441 preference. The chosen encryption algorithm will be the first 442 algorithm on the client's list that is also on the server's list. 443 If there is no such algorithm, connection fails. 445 Note that SSH_CALG_NONE must be explicitly listed if it is to be 446 acceptable. The available algorithm numbers are listed in Section 447 ``Encryption''. 449 The algorithm to use is negotiated separately for each direction, 450 and different algorithms may be chosen. 452 mac_algorithms 453 Lists the acceptable MAC algorithms in order of preference. The 454 chosen MAC algorithm will be the first algorithm on the client's 455 list that is also on the server's list. If there is no such 456 algorithm, connection fails. 458 Note that SSH_MAC_NONE must be explicitly listed if it is to be 459 acceptable. The available MAC algorithm numbers are listed in 460 Section ``Data Integrity''. 462 The algorithm to use is negotiated separately for each direction, 463 and different algorithms may be chosen. 465 compression_algorithms 466 Lists the acceptable compression algorithms in order of 467 preference. The chosen compression algorithm will be the first 468 algorithm on the client's list that is also on the server's list. 469 If there is no such algorithm, connection fails. 471 Note that SSH_COMPRESS_NONE must be explicitly listed if it is to 472 be acceptable. The available compression algorithm numbers are 473 listed in Section ``Compression''. 475 The algorithm to use is negotiated separately for each direction, 476 and different algorithms may be chosen. 478 hash_algorithms 479 Lists the acceptable hash algorithms in order of preference. The 480 chosen hash algorithm will be the first algorithm on the client's 481 list that is also on the server's list. If there is no such 482 algorithm, connection fails. 484 Implementations should only permit algorithms that they consider 485 to be fairly secure, as the hash function will be used e.g. for 486 deriving various keys from the shared secret. All hash algorithms 487 must produce at least 16 bytes of output. 489 Currently, the following hash functions are defined: 491 #define SSH_HASH_SHA 1 /* returns 20 bytes */ 492 #define SSH_HASH_MD5 2 /* returns 16 bytes */ 494 first_kex_packet_follows 495 Each side makes a guess of the negotiated key exchange method. 496 This is based on the assumption that at any particular time there 497 will be a single key exchange method and host key algorithm 498 combination that dominates the installed base. Making a guess 499 about the algorithm will save a round-trip in the typical case, 500 and will incur little extra cost in the other cases. 502 Each side will determine if they are supposed to send an initial 503 packet in their guessed key exchange method. If they are, they 504 will set this field to true and follow this packet by the first 505 key exchange packet. 507 After receiving the SSH_MSG_KEXINIT packet from the other side, 508 each party will know whether their guess was right. If the guess 509 was wrong, and this field is true, the next packet will be 510 silently ignored, and each side will then act as determined by the 511 negotiated key exchange method. If the guess was right, key 512 exchange will immediately continue. 514 5.2. RSA-Style Key Exchange 516 RSA-style key exchange requires that the server host key supports 517 encryption. The idea is that the server sends its public host key and a 518 periodically changing key (called the server key). The client then 519 verifies that it is the correct key for the server, generates a session 520 key, encrypts the session key using both the server host key and the 521 server key, and sends the encrypted session key to the server. 523 The server key and host keys must both support encryption, and their 524 sizes must be compatible in such a way that the result of encrypting a 525 value with one of them can be encrypted with the other. The smaller of 526 the keys must be able to encrypt at least 48 bytes. 528 The host key should be larger than the server key, because this causes 529 the server key encryption to be done first, and prevents an outside 530 attacker from replacing the outer layer of encryption by an active man- 531 in-the-middle attack. Such an attack would not directly compromise 532 security, but would allow the attacker to later decrypt intercepted 533 sessions if he somehow obtains the private host key. 535 5.2.1. Server Sends Host Key 537 First, the server sends its public host and server keys in the following 538 packet: 540 vlint32 SSH_MSG_KEXRSA_HOSTKEY 541 string public host key 542 string public server key 544 The host key and server key are stored in binary representation as 545 described in Section ``Public Key Formats''. 547 5.2.2. Client Sends Double-Encrypted Session Key 549 After receiving the public keys, the client validates that the host key 550 really belongs to the intended server. How this verification happens is 551 not specified in this protocol. Currently it may be checked against a 552 database of known name-key mappings; in future it will probably be 553 validated using an Internet public key infrastructure. 555 If the client is not willing to trust the server host key, it simply 556 closes the connection and the protocol terminates. 558 Otherwise, the client chooses an encryption algorithm that is supported 559 by both parties. It also chooses a MAC algorithm and a compression 560 algorithm that are supported by both parties. 562 To authenticate that no-one has been manipulating the key exchange with 563 the server, the client also computes an SHA-1 hash of the concatenated 564 payloads of (in this order): client's SSH_MSG_KEXINIT, server's 565 SSH_MSG_KEXINIT, and server's SSH_MSG_KEXRSA_HOSTKEY message. 567 The client then generates a 256 bit random session key. A message to be 568 passed to the server is formed by concatenating the following (in this 569 order): six zero bytes (reserved for future), first 10 bytes of the 570 SHA-1 hash of the key exchange, session key. This results in a total of 571 48 bytes of data to be passed to the server. Note that the negotiated 572 algorithms are not explicitly passed, as the algorithms given in Section 573 ``Sending Supported Algorithm Lists'' fully determine the algorithms. 575 Note that the use of SHA-1 was hard-coded here. This is used to 576 authenticate the key exchange, and using HASH here would lead to all 577 sorts of potential problems in verifying the security of the protocol. 578 Using a fixed hash short-circuits verification to the properties of the 579 hash. Should the need ever arise, the only way to switch to another 580 algorithm here is to define a new key exchange algorithm (which, in 581 fact, is not very difficult). 583 The resulting data is encrypted with the smaller of host key and server 584 key, and the result then with the larger of them. The resulting double- 585 encrypted session key is then sent to the server for verification. Note 586 that public-key encryption probably involves padding, depending on the 587 algorithm. 589 vlint32 SSH_MSG_KEXRSA_SESSIONKEY 590 string double-encrypted session key 592 Upon receiving this message, the server uses its private host and server 593 keys to decrypt the session key. It computes a corresponding SHA hash, 594 and compares the hash values. If the hash does not match, the server 595 disconnects. Otherwise, encryption, compression, and integrity 596 protection are taken into effect immediately after this message. 598 The server does not acknowledge this message in any way. The client may 599 continue by sending further protocol requests using the negotiated 600 encryption. If the server was not able to decrypt the session key, it 601 won't be able to determine what the futher requests are or to respond to 602 them. 604 5.3. Diffie-Hellman Style Key Exchange 606 XXX To be defined later. 608 5.4. Deriving Encryption and Integrity Keys 610 As a result of the key exchange, the parties have a 256-bit shared 611 secret. 613 Various keys are computed from this secret and from the cookies 614 exchanged during algorithm negotiation. The cookies are used to make it 615 impossible for either party to alone determine the keys. 617 Each key is computed as HASH of the concatenation of client's cookie, 618 server's cookie, and 16 bytes of secret data. The secret data is 619 different for each key, and is taken from the 32-byte shared secret as 620 follows: 622 o Initial IV client to server: bytes 0-15 624 o Initial IV server to client: bytes 1-16 626 o Encryption key client to server: bytes 5-20 628 o Encryption key server to client: bytes 8-23 630 o Integrity key client to server: bytes 13-28 632 o Integrity key server to client: bytes 16-31 634 Each key is at least 16 bytes (128 bits). For some algorithms, only 635 part of this amount is actually used. If a longer key is needed for 636 some algorithm, the key is extended by computing HASH of the entire key 637 so far, and appending the resulting bytes (as many as HASH outputs) to 638 the key. This process is repeated until enough key material is 639 available. 641 6. Client Host Authentication 643 Next, the client can (but is not required to) send its own host 644 authentication message. If this message is not sent, the server will 645 consider the client unnamed for authentication purposes. It is expected 646 that many servers will refuse to talk to clients that do not first 647 authenticate themselves. 649 Note that this message passes the host name, and can be used to 650 authenticate hosts on the other side of a firewall. 652 To authenticate itself, the client computes HASH of the 653 concatenatenation of (in this order) the client host name, client's 654 cookie, and server's cookie. It then signs this hash using its private 655 host key (one that uses an algorithm which is supported by the server), 656 and sends the following value to the server: 658 vlint32 SSH_MSG_HOSTAUTH 659 string client host name 660 string client public host key 661 string signature of host name+client cookie+server cookie 663 The host key is stored in binary representation as described in Section 664 ``Public Key Formats''. 666 The server will verify that the client host name is really associated 667 with the given key. If the name-key association cannot be verified, the 668 server may at its option either disconnect or ignore the client host 669 authentication. 671 If the name-key association can be verified, the signature is checked. 672 If it is incorrect, the connection is closed. Otherwise, the server 673 updates its state to the fact that the client has been cryptographically 674 authenticated. 676 The server may also attempt to validate whether the host name supplied 677 by the client matches with a name obtained from network protocol headers 678 or other sources (e.g., it may require the supplied name to match a DNS 679 reverse mapped name, unless the reverse mapped name is a firewall host). 680 However, such validation is not always possible, and is not required by 681 this protocol. If the server finds a mismatch between the client- 682 supplied name and the name obtained from the network protocols, the 683 server may disconnect. 685 Some servers may refuse to continue the dialog with the client unless 686 the client is able to authenticate itself cryptographically. Likewise, 687 some servers may refuse to talk to certain clients, and may disconnect 688 at this point. It is recommended that such disconnections use 689 SSH_MSG_DISCONNECT and explain the reason for disconnecting. 691 7. Service Request 693 After the various authentications, the client requests a service. The 694 service is identified by a name, which must consists of alphanumeric 695 characters, hyphens ('-'), and underscores ('_'). The name must not be 696 longer than 64 characters. 698 vlint32 SSH_MSG_SERVICE_REQUEST 699 string service name 701 Most server implementations will have a table of services that are 702 supported, specifying what to do for each service. 704 If the server rejects the service request, it either disconnects or 705 (preferably) sends a SSH_MSG_DISCONNECT message. 707 If the server supports the service (and permits the client to use it), 708 it responds with 710 vlint32 SSH_MSG_SERVICE_ACCEPT 712 The client is permitted to send further packets without waiting for the 713 this message; those packets will go the selected service if the server 714 accepts the service request. 716 8. Data Exchange 718 Once a service has been selected, data is transmitted in each direction 719 asynchronously. The data is packetized using the following format: 721 vlint32 SSH_MSG_DATA 722 string data 724 For stream-based services data is passed directly to the application. 725 Packet-based applications may have their own packet structure embedded 726 within each data packet. 728 When a service closes its output (i.e., will not send more data), the 729 following message is sent to the other side: 731 vlint32 SSH_MSG_EOF 733 When this message is received, the service will be notified of the end- 734 of-file status on input. Output from the service is still accepted, and 735 sent to the other side. 737 When the service on either side exits (i.e., will no longer accept 738 input, and will not generate more output), the following message is sent 739 after any other data sent by the application. After this message, the 740 connection will be closed. An EOF is not necessarily sent before this 741 message. 743 vlint32 SSH_MSG_CLOSE 745 9. Key Re-Exchange 747 Either side may request re-exchange of keys at any time after the 748 initial exchange (and outside other key exchanges). The re-exchange is 749 not visible to the service, and will take place using the same algorithm 750 that was used in the original key exchange. 752 Key re-exchange is started by sending a SSH_MSG_KEXINIT packet 753 (described in Section ``Sending Supported Algorithm Lists''). When this 754 message is received, a party must respond with its own SSH_MSG_KEXINIT 755 message. Either party may initiate the re-exchange, but roles are not 756 changed (i.e., the server remains the server, and the client remains the 757 client). 759 Key re-exchange is performed under whatever encryption was in effect 760 when the exchange was started. Encryption, compression, and MAC methods 761 are changed when the key exchange is complete (as in the initial key 762 exchange). Re-exchange is processed identically to the initial key 763 exchange, except that it is not necessary to validate that the host key 764 really belongs to the server. It is permissible to change the 765 encryption, compression, and MAC algorithms during the re-exchange. All 766 keys are recomputed after the exchange. Compression and encryption 767 contexts are reset. The packet sequence number is not reset. 769 It is recommended that keys be changed after each gigabyte of 770 transmitted data and after each hour of connection time, whichever comes 771 sooner. 773 It is also possible to use the key re-exchange mechanism to switch to 774 faster algorithms after authentication, or to avoid double processing 775 for pre-encrypted or pre-authenticated data. However, since the re- 776 exchange is a public key operation, it requires a fair amount of 777 processing power and should not be performed too often. 779 10. Additional Messages 781 Either party may send any of the following messages at any time. 783 10.1. Disconnection Message 785 vlint32 SSH_MSG_DISCONNECT 786 vlint32 error code 787 string description 789 This message causes immediate termination of the connection. The 790 description field gives the reason for disconnecting in human-readable 791 form. The error code gives the reason in a machine-readable format, and 792 can have the following values: 794 #define SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1 795 #define SSH_DISCONNECT_PROTOCOL_ERROR 2 796 #define SSH_DISCONNECT_INCOMPATIBLE_HOST_KEY 3 797 #define SSH_DISCONNECT_INCOMPATIBLE_PUBLIC_KEY_ALG 4 798 #define SSH_DISCONNECT_INCOMPATIBLE_CRYPTO_ALG 5 799 #define SSH_DISCONNECT_INCOMPATIBLE_MAC_ALG 6 800 #define SSH_DISCONNECT_INCOMPATIBLE_COMPRESSION_ALG 7 801 #define SSH_DISCONNECT_INCOMPATIBLE_HASH_ALG 8 802 #define SSH_DISCONNECT_KEY_EXCHANGE_FAILED 9 803 #define SSH_DISCONNECT_HOST_AUTHENTICATION_FAILED 10 804 #define SSH_DISCONNECT_MAC_ERROR 11 805 #define SSH_DISCONNECT_COMPRESSION_ERROR 12 806 #define SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 13 807 #define SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 14 808 #define SSH_DISCONNECT_OPERATION_PROHIBITED 15 810 10.2. Ignored Data Message 812 vlint32 SSH_MSG_IGNORE 813 string data 815 All implementations must understand (and ignore) this message. No 816 implementation is required to ever send them. 818 10.3. Reserved Messages 820 An implementation must respond to all unrecognized messages with an 821 SSH_MSG_UNIMPLEMENTED message. Later protocol versions may define other 822 meanings for these message types. 824 vlint32 SSH_MSG_UNIMPLEMENTED 825 uint32 packet sequence number of rejected message 827 Message numbers below 1000 are reserved for "official" extensions. 828 Other extensions and experimental code should use message numbers above 829 this. 831 11. Summary of Message Numbers 833 The following message numbers have been defined in this protocol. 835 #define SSH_MSG_DISCONNECT 1 836 #define SSH_MSG_IGNORE 2 837 #define SSH_MSG_UNIMPLEMENTED 3 838 #define SSH_MSG_KEXINIT 10 839 #define SSH_MSG_KEXRSA_HOSTKEY 11 840 #define SSH_MSG_KEXRSA_SESSIONKEY 12 841 #define SSH_MSG_HOSTAUTH 30 842 #define SSH_MSG_SERVICE_REQUEST 40 843 #define SSH_MSG_SERVICE_ACCEPT 41 844 #define SSH_MSG_DATA 42 845 #define SSH_MSG_EOF 43 846 #define SSH_MSG_CLOSE 44 848 12. Public Keys and Public Key Infrastructure 850 This protocol is intentionally open on public key formats, as well as 851 signature and encryption formats. There is currently no generally 852 accepted public key infrastructure on the Internet, and there are 853 several competing key formats, and more formats are likely to appear. 854 It will probably take several years until the situation is resolved. In 855 particular, it is not clear that X.509 would be the solution, although 856 that is also a possibility. 858 There are several aspects to a public key type: 860 o Key format: how is the key coded, and how are certificates 861 represented. The key blobs in this protocol may (but are not 862 required to) contain certificates in addition to keys. 864 o Signature and/or encryption algorithms. Some algorithms may not 865 support both encryption and decryption. 867 o Encoding for signatures and encrypted data. This includes but is not 868 limited to padding, byte order, and data formats. 870 o Computation of unique key id. 872 #define SSH_PK_SIMPLE_RSA_PKCS 1 874 Note that the key type is negotiated at the beginning of the key 875 exchange, and is not included in the key blob itself. 877 12.1. SSH_PK_SIMPLE_RSA_PKCS 879 This key type defines an RSA public key, with (mostly) PKCS compatible 880 signature and encryption formats. It supports both signatures and 881 encryption. 883 Public keys of this type are represented as follows: 885 byte[4] 0 (reserved) 886 uint32 number of bits in the modulus 887 uint16 number bits in the secret exponent 888 bytes[n] exponent, MSB first, n = floor((bits+7)/8) 889 uint16 number of bits in the modulus 890 bytes[n] modulus, MSB first, n = floor((bits+7)/8) 892 It is permissible that there be other data (e.g., certificates) 893 following this; however, such data is not yet defined. 895 Note that private key formats are not defined here, and are 896 implementation-specific. 898 The key id for this key type is of the format "SSH-PKCS-1-RSA-xxxxxxxx", 899 where the "xxxxxxxx" stands for an SHA-1 hash of the data listed above, 900 in hexadecimal (a total of 40 lowercase hex characters). Any data 901 following the above (e.g., certificates) is not included in the key id 902 calculation. 904 An encrypted message is formed as follows. 906 o The data to be encrypted is padded into a long integer of the same 907 number of bits as the modulus as follows: 909 MSB . . . LSB 911 0 2 RND(n bytes) 0 encrypted_data 913 The RND bytes represent non-zero random bytes. 915 o To encrypt, this integer is raised to the public exponent, modulo the 916 modulus. 918 o The result is converted to a byte string of floor((bits+7)/8) bytes 919 (where bits is the number of bits in the modulus), MSB first. This 920 byte string (without any length or terminating characters) is the 921 result of the encryption. 923 A signature is formed as follows. 925 o The data to be signed (typically a message digest, but not required 926 to be such) is padded into a long integer of the same number of bits 927 as the modulus as follows: 929 MSB . . . LSB 931 0 1 RND(n bytes) 0 signed_data 933 The RND bytes represent non-zero random bytes. Note that this differs 934 from the PKCS standard, where 0xFF bytes are specified for padding. 936 o To sign, this integer is raised to the private exponent, modulo the 937 modulus. 939 o The result is converted to a byte string of floor((bits+7)/8) bytes 940 (where bits is the number of bits in the modulus), MSB first. This 941 byte string (without any length or terminating characters) is the 942 signature. Applications may add other data outside this value.