idnits 2.17.1 draft-ietf-secsh-transport-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 434 has weird spacing: '... string cert...' == Line 461 has weird spacing: '... string dss...' == Line 499 has weird spacing: '... string kex...' == Line 500 has weird spacing: '... string ser...' == Line 501 has weird spacing: '... string enc...' == (21 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (22 February 1999) is 9195 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: 'SPKI' is mentioned on line 469, but not defined -- Looks like a reference, but probably isn't: '16' on line 498 == Unused Reference: 'RFC-1034' is defined on line 984, but no explicit reference was found in the text == Unused Reference: 'SSH-USERAUTH' is defined on line 1014, but no explicit reference was found in the text == Unused Reference: 'SSH-CONNECT' is defined on line 1017, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS-186' -- Possible downref: Non-RFC (?) normative reference: ref. 'Orm96' ** Obsolete normative reference: RFC 1766 (Obsoleted by RFC 3066, RFC 3282) ** Downref: Normative reference to an Informational RFC: RFC 1950 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 2044 (Obsoleted by RFC 2279) ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Downref: Normative reference to an Informational RFC: RFC 2144 -- Possible downref: Non-RFC (?) normative reference: ref. 'Schneier' == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-03 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-05 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-05 -- Possible downref: Non-RFC (?) normative reference: ref. 'PGP' -- Possible downref: Non-RFC (?) normative reference: ref. 'PKIX-Part1' Summary: 10 errors (**), 0 flaws (~~), 15 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group T. Ylonen 2 INTERNET-DRAFT T. Kivinen 3 draft-ietf-secsh-transport-05.txt M. Saarinen 4 Expires in six months T. Rinne 5 S. Lehtinen 6 SSH 7 22 February 1999 9 SSH Transport Layer Protocol 11 Status of This memo 13 This document is an Internet-Draft and is in full conformance 14 with all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as 19 Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six 22 months and may be updated, replaced, or obsoleted by other 23 documents at any time. It is inappropriate to use Internet- 24 Drafts as reference material or to cite them other than as 25 "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 Abstract 35 SSH is a protocol for secure remote login and other secure network ser- 36 vices over an insecure network. This document describes the SSH trans- 37 port layer protocol which typically runs on top of TCP/IP. The protocol 38 can be used as a basis for a number of secure network services. It pro- 39 vides strong encryption, server authentication, and integrity protec- 40 tion. It may also provide compression. Key exchange method, public key 41 algorithm, symmetric encryption algorithm, message authentication algo- 42 rithm, and hash algorithm are all negotiated. This document also 43 describes the Diffie-Hellman key exchange method and the minimal set of 44 algorithms that are needed to implement the SSH transport layer proto- 45 col. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 50 2. Conventions Used in This Document . . . . . . . . . . . . . . . 3 51 3. Connection Setup . . . . . . . . . . . . . . . . . . . . . . . . 3 52 3.1. Use over TCP/IP . . . . . . . . . . . . . . . . . . . . . . 3 53 3.2. Protocol Version Exchange . . . . . . . . . . . . . . . . . 3 54 3.3. Compatibility with Old SSH Versions . . . . . . . . . . . . 4 55 3.3.1. Old Client, New Server . . . . . . . . . . . . . . . . . 4 56 3.3.2. New Client, Old Server . . . . . . . . . . . . . . . . . 4 57 4. Binary Packet Protocol . . . . . . . . . . . . . . . . . . . . . 4 58 4.1. Maximum Packet Length . . . . . . . . . . . . . . . . . . . 5 59 4.2. Compression . . . . . . . . . . . . . . . . . . . . . . . . 5 60 4.3. Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 4.4. Data Integrity . . . . . . . . . . . . . . . . . . . . . . . 7 62 4.5. Key Exchange Methods . . . . . . . . . . . . . . . . . . . . 8 63 4.6. Public Key Algorithms . . . . . . . . . . . . . . . . . . . 8 64 5. Key Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . 10 65 5.1. Algorithm Negotiation . . . . . . . . . . . . . . . . . . . 10 66 5.2. Output from Key Exchange . . . . . . . . . . . . . . . . . . 12 67 5.3. Taking Keys into Use . . . . . . . . . . . . . . . . . . . . 13 68 6. Diffie-Hellman Key Exchange . . . . . . . . . . . . . . . . . . 14 69 6.1. diffie-hellman-group1-sha1 . . . . . . . . . . . . . . . . . 15 70 7. Key Re-Exchange . . . . . . . . . . . . . . . . . . . . . . . . 15 71 8. Service Request . . . . . . . . . . . . . . . . . . . . . . . . 16 72 9. Additional Messages . . . . . . . . . . . . . . . . . . . . . . 17 73 9.1. Disconnection Message . . . . . . . . . . . . . . . . . . . 17 74 9.2. Ignored Data Message . . . . . . . . . . . . . . . . . . . . 17 75 9.3. Debug Message . . . . . . . . . . . . . . . . . . . . . . . 18 76 9.4. Reserved Messages . . . . . . . . . . . . . . . . . . . . . 18 77 10. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 18 78 11. Security Considerations . . . . . . . . . . . . . . . . . . . . 19 79 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 80 13. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 20 82 1. Introduction 84 The SSH transport layer is a secure low level transport protocol. It 85 provides strong encryption, cryptographic host authentication, and 86 integrity protection. 88 Authentication in this protocol level is host-based; this protocol does 89 not perform user authentication. A higher level protocol for user 90 authentication can be designed on top of this protocol. 92 The protocol has been designed to be simple, flexible, to allow 93 parameter negotiation, and to minimize the number of round-trips. Key 94 exchange method, public key algorithm, symmetric encryption algorithm, 95 message authentication algorithm, and hash algorithm are all negotiated. 96 It is expected that in most environments, only 2 round-trips will be 97 needed for full key exchange, server authentication, service request, 98 and acceptance notification of service request. The worst case is 3 99 round-trips. 101 2. Conventions Used in This Document 103 The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", and 104 "MAY" that appear in this document are to be interpreted as described in 105 [RFC-2119]. 107 The used data types and terminology are specified in the architecture 108 document [SSH-ARCH]. 110 The architecture document also discusses the algorithm naming 111 conventions that MUST be used with the SSH protocols. 112 3. Connection Setup 114 SSH works over any 8-bit clean, binary-transparent transport. The 115 underlying transport SHOULD protect against transmission errors as such 116 errors cause the SSH connection to terminate. 118 The client initiates the connection. 120 3.1. Use over TCP/IP 122 When used over TCP/IP, the server normally listens for connections on 123 port 22. This port number has been registered with the IANA, and has 124 been officially assigned for SSH. 126 3.2. Protocol Version Exchange 128 When the connection has been established, both sides MUST send an 129 identification string of the form "SSH-protoversion-softwareversion 130 comments", followed by carriage return and newline characters (ascii 13 131 and 10, respectively). Both sides MUST be able to process 132 identification strings without carriage return character. No null 133 character is sent. The maximum length of the string is 255 characters, 134 including the carriage return and newline. 136 The part of the identification string preceding carriage return and 137 newline is used in the Diffie-Hellman key exchange (Section ``Diffie- 138 Hellman Key Exchange''). 140 The server MAY send other lines of data before sending the version 141 string. Each line SHOULD be terminated by a carriage return and 142 newline. Such lines MUST NOT begin with "SSH-", and SHOULD be encoded 143 in ISO-10646 UTF-8 [RFC-2044] (language is not specified). Clients MUST 144 be able to process such lines; they MAY be silently ignored, or MAY be 145 displayed to the client user; if they are displayed, control character 146 filtering discussed in [SSH-ARCH] SHOULD be used. The primary use of 147 this feature is to allow TCP-wrappers to display an error message before 148 disconnecting. 150 Version strings MUST consist of printable US-ASCII characters, not 151 including whitespaces or a minus sign (-). The version string is 152 primarily used to trigger compatibility extensions and to indicate the 153 capabilities of an implementation. The comment string should contain 154 additional information that might be useful in solving user problems. 156 The protocol version described in this document is 2.0. 158 Key exchange will begin immediately after sending this identifier. All 159 packets following the identification string SHALL use the binary packet 160 protocol, to be described below. 161 3.3. Compatibility with Old SSH Versions 163 During a transition period, it is important to be able to work 164 compatibly with installed SSH clients and servers using an older version 165 of the protocol. Information in this section is only relevant for 166 implementations supporting compatibility with SSH versions 1.x. 168 3.3.1. Old Client, New Server 170 Server implementations MAY support a configurable "compatibility" flag 171 that enables compatibility with old versions. When this flag is on, the 172 server SHOULD identify its protocol version as "1.99". Clients using 173 protocol 2.0 MUST be able to identify this as identical to "2.0". In 174 this mode the server SHOULD NOT send carriage return character (ascii 175 13) after the version identification string. 177 In the compatibility mode the server SHOULD NOT send any further data 178 after its initialization string until it has received an identification 179 string from the client. The server can then determine whether the 180 client is using an old protocol, and can revert to the old protocol if 181 desired. The server MUST NOT send additional data before the version 182 string, in the compatibility mode. 184 When compatibility with old clients is not needed, the server MAY send 185 its initial key exchange data immediately after the identification 186 string. 188 3.3.2. New Client, Old Server 190 Since the new client MAY immediately send additional data after its 191 identification string (before receiving server's identification), the 192 old protocol may already have been corrupted when the client learns that 193 the server is old. When this happens, the client SHOULD close the 194 connection to the server, and reconnect using the old protocol. 196 4. Binary Packet Protocol 198 Each packet is of the following format. 200 uint32 packet_length 201 byte padding_length 202 byte[n1] payload; n1 = packet_length - padding_length - 1 203 byte[n2] random padding; n2 = padding_length 204 byte[m] mac (message authentication code); m = mac_length 206 packet_length 207 The length of the packet (bytes), not including MAC or the 208 packet_length field itself. 210 padding_length 211 Length of padding (bytes). 213 payload 214 The useful contents of the packet. If compression has been 215 negotiated, this field is compressed. Initially, compression MUST 216 be "none". 218 Padding 219 Arbitrary-length padding, such that the total length of 220 (packet_length || padding_length || payload || padding) is a 221 multiple of the cipher block size or 8, whichever is larger. 222 There MUST be at least four bytes of padding. The padding SHOULD 223 consist of random bytes. The maximum amount of padding is 255 224 bytes. 226 MAC 227 Message authentication code. If message authentication has been 228 negotiated, this field contains the MAC bytes. Initially, the MAC 229 algorithm MUST be "none". 231 Note that length of the concatenation of packet length, padding length, 232 payload, and padding MUST be a multiple of the cipher block size or 8, 233 whichever is larger. This constraint MUST be enforced even when using 234 stream ciphers. Note that the packet length field is also encrypted, 235 and processing it requires special care when sending or receiving 236 packets. 238 The minimum size of a packet is 16 (or the cipher block size, whichever 239 is larger) bytes (plus MAC); implementations SHOULD decrypt the length 240 after receiving the first 8 (or cipher block size, whichever is larger) 241 bytes of a packet. 243 4.1. Maximum Packet Length 245 All implementations MUST be able to process packets with uncompressed 246 payload length of 32768 bytes or less and total packet size of 35000 247 bytes or less (including length, padding length, payload, padding, and 248 MAC). Implementations SHOULD support longer packets, where they might 249 be needed e.g. if an implementation wants to send a very large number of 250 certificates. Such packets MAY be sent if the version string indicates 251 that the other party is able to process them. However, implementations 252 SHOULD check that the packet length is reasonable for the implementation 253 to avoid denial-of-service and/or buffer overflow attacks. 255 4.2. Compression 256 If compression has been negotiated, the payload field (and only it) will 257 be compressed using the negotiated algorithm. The length field and MAC 258 will be computed from the compressed payload. 260 Compression MAY be stateful, depending on the method. Compression MUST 261 be independent for each direction, and implementations MUST allow 262 independently choosing the algorithm for each direction. 264 The following compression methods are currently defined: 266 none REQUIRED no compression 267 zlib OPTIONAL GNU ZLIB (LZ77) compression 269 The "zlib" compression is described in [RFC-1950] and in [RFC-1951]. The 270 compression context is initialized after each key exchange, and is 271 passed from one packet to the next with only a partial flush being 272 performed at the end of each packet. A partial flush means that all data 273 will be output, but the next packet will continue using compression 274 tables from the end of the previous packet. 276 Additional methods may be defined as specified in [SSH-ARCH]. 278 4.3. Encryption 280 An encryption algorithm and a key will be negotiated during the key 281 exchange. When encryption is in effect, the packet length, padding 282 length, payload and padding fields of each packet MUST be encrypted with 283 the given algorithm. 285 The encrypted data in all packets sent in one direction SHOULD be 286 considered a single data stream. For example, initialization vectors 287 SHOULD be passed from the end of one packet to the beginning of the next 288 packet. All ciphers SHOULD use keys with an effective key length of 128 289 bits or more. 291 The ciphers in each direction MUST run independently of each other, and 292 implementations MUST allow independently choosing the algorithm for each 293 direction (if multiple algorithms are allowed by local policy). 295 The following ciphers are currently defined: 297 3des-cbc REQUIRED three-key 3DES in CBC mode 298 blowfish-cbc RECOMMENDED Blowfish in CBC mode 299 twofish-cbc RECOMMENDED Twofish in CBC mode 300 arcfour OPTIONAL the ARCFOUR stream cipher 301 idea-cbc OPTIONAL IDEA in CBC mode 302 cast128-cbc OPTIONAL CAST-128 in CBC mode 303 none OPTIONAL no encryption; NOT RECOMMENDED 305 The "3des-cbc" cipher is three-key triple-DES (encrypt-decrypt-encrypt), 306 where the first 8 bytes of the key are used for the first encryption, 307 the next 8 bytes for the decryption, and the following 8 bytes for the 308 final encryption. This requires 24 bytes of key data (of which 168 bits 309 are actually used). To implement CBC mode, outer chaining MUST be used 310 (i.e., there is only one initialization vector). This is a block cipher 311 with 8 byte blocks. This algorithm is defined in [Schneier]. 313 The "blowfish-cbc" cipher is Blowfish in CBC mode, with 128 bit keys 314 [Schneier]. This is a block cipher with 8 byte blocks. 316 The "twofish-cbc" cipher is Twofish in CBC mode, with 256 bit keys as 317 described in Twofish AES submission. This is a block cipher with 16 byte 318 blocks. 320 The "arcfour" is the Arcfour stream cipher with 128 bit keys. The 321 Arcfour cipher is believed to be compatible with the RC4 cipher 322 [Schneier]. RC4 is a registered trademark of RSA Data Security Inc. 324 The "idea-cbc" cipher is the IDEA cipher in CBC mode [Schneier]. IDEA is 325 patented by Ascom AG. 327 The "cast128-cbc" cipher is the CAST-128 cipher in CBC mode [RFC-2144]. 329 The "none" algorithm specifies that no encryption is to be done. Note 330 that this method provides no confidentiality protection, and it is not 331 recommended. Some functionality (e.g. password authentication) may be 332 disabled for security reasons if this cipher is chosen. 334 Additional methods may be defined as specified in [SSH-ARCH]. 336 4.4. Data Integrity 338 Data integrity is protected by including with each packet a message 339 authentication code (MAC) that is computed from a shared secret, packet 340 sequence number, and the contents of the packet. 341 The message authentication algorithm and key are negotiated during key 342 exchange. Initially, no MAC will be in effect, and its length MUST be 343 zero. After key exchange, the selected MAC will be computed before 344 encryption from the concatenation of packet data: 346 mac = MAC(key, sequence_number || unencrypted_packet) 348 where unencrypted_packet is the entire packet without MAC (the length 349 fields, payload and padding), and sequence_number is an implicit packet 350 sequence number represented as uint32. The sequence number is initial- 351 ized to zero for the first packet, and is incremented after every packet 352 (regardless of whether encryption or MAC is in use). It is never reset, 353 even if keys/algorithms are renegotiated later. It wraps around to zero 354 after every 2^32 packets. The packet sequence number itself is not 355 included in the packet sent over the wire. 357 The MAC algorithms for each direction MUST run independently, and 358 implementations MUST allow choosing the algorithm independently for both 359 directions. 361 The MAC bytes resulting from the MAC algorithm MUST be transmitted 362 without encryption as the last part of the packet. The number of MAC 363 bytes depends on the algorithm chosen. 365 The following MAC algorithms are currently defined: 367 hmac-sha1 REQUIRED HMAC-SHA1 (length = 20) 368 hmac-sha-96 RECOMMENDED first 96 bits of HMAC-SHA1 (length = 12) 369 hmac-md5 OPTIONAL HMAC-MD5 (length = 16) 370 hmac-md5-96 OPTIONAL first 96 bits of HMAC-MD5 (length = 12) 371 none OPTIONAL no MAC; NOT RECOMMENDED 373 The "hmac-*" algorithms are described in [RFC-2104]. The "*-n" MACs use 374 only the first n bits of the resulting value. 376 The hash algorithms are described in [Schneier]. 378 The "none" method is NOT RECOMMENDED. An active attacker may be able to 379 modify transmitted data if this is used. 381 Additional methods may be defined as specified in [SSH-ARCH]. 383 4.5. Key Exchange Methods 385 The key exchange method specifies how one-time session keys are 386 generated for encryption and for authentication, and how the server 387 authentication is done. 389 Only one REQUIRED key exchange method has been defined: 391 diffie-hellman-group1-sha1 REQUIRED 393 This method is described later in this document. 395 Additional methods may be defined as specified in [SSH-ARCH]. 397 4.6. Public Key Algorithms 399 This protocol has been designed to be able to operate with almost any 400 public key format, encoding, and algorithm (signature and/or 401 encryption). 403 There are several aspects that define a public key type: 405 o Key format: how is the key encoded and how are certificates 406 represented. The key blobs in this protocol MAY contain certificates 407 in addition to keys. 409 o Signature and/or encryption algorithms. Some key types may not 410 support both signing and encryption. Key usage may also be 411 restricted by policy statements in e.g. certificates. In this case, 412 different key types SHOULD be defined for the different policy 413 alternatives. 415 o Encoding of signatures and/or encrypted data. This includes but is 416 not limited to padding, byte order, and data formats. 418 The following public key and/or certificate formats are currently 419 defined: 421 ssh-dss REQUIRED sign Simple DSS 422 x509v3 RECOMMENDED sign X.509 certificates 423 spki OPTIONAL sign SPKI certificates 424 pgp OPTIONAL sign OpenPGP certificates 426 Additional key types may be defined as specified in [SSH-ARCH]. 428 The key type MUST always be explicitly known (from algorithm negotiation 429 or some other source). It is not normally included in the key blob. 431 Certificates and public keys are encoded as: 433 uint32 combined length of the format identifier and associated data 434 string certificate or public key format identifier 435 byte[n] key/certificate data 437 The certificate part may have be a zero length string, but a public key 438 is required. This is the public key that will be used for 439 authentication; the certificate sequence contained in the certificate 440 blob can be used to provide authorization. 442 The "ssh-dss" key format has the following specific encoding: 444 uint32 length 445 string "ssh-dss" 446 mpint p 447 mpint q 448 mpint g 449 mpint y 451 Here the "p", "q", "g", and "y" parameters form the signature key blob. 453 Signing and verifying using this key format are done according to the 454 Digital Signature Standard [FIPS-186] using the SHA-1 hash. A 455 description can also be found in [Schneier]. 457 The resulting signature is encoded as: 459 uint32 length 460 string "ssh-dss" 461 string dss_signature_blob 463 The "x509v3" method indicates that the certificates, the public key, and 464 the resulting signature are in X.509v3 compatible DER-encoded format. 465 The formats used in X.509v3 is described in [PKIX-Part1]. 467 The "spki" method indicates that the certificate blob contains a 468 sequence of SPKI certificates. The format of SPKI certificates is 469 described in [SPKI]. 471 The "pgp" method indicates the the certificates, the public key, and the 472 signature are in OpenPGP compatible binary format. [PGP] 474 5. Key Exchange 476 Key exchange begins by each side sending lists of supported algorithms. 477 Each side has a preferred algorithm in each category, and it is assumed 478 that most implementations at any given time will use the same preferred 479 algorithm. Each side MAY guess which algorithm the other side is using, 480 and MAY send an initial key exchange packet according to the algorithm 481 if appropriate for the preferred method. If all algorithms were guessed 482 right, the optimistically sent packet MUST be handled as the first key 483 exchange packet. However, if the guess was wrong, and a packet was 484 optimistically sent by one or both parties, such packets MUST be ignored 485 (even if the error in the guess would not affect the contents of the 486 initial packet(s)), and the appropriate side MUST send the correct 487 initial packet. 489 Server authentication in the key exchange MAY be implicit. After a key 490 exchange with implicit server authentication, the client MUST wait for 491 response to its service request message before sending any further data. 493 5.1. Algorithm Negotiation 495 Key exchange begins by each side sending the following packet: 497 byte SSH_MSG_KEXINIT 498 byte[16] cookie (random bytes) 499 string kex_algorithms 500 string server_host_key_algorithms 501 string encryption_algorithms_client_to_server 502 string encryption_algorithms_server_to_client 503 string mac_algorithms_client_to_server 504 string mac_algorithms_server_to_client 505 string compression_algorithms_client_to_server 506 string compression_algorithms_server_to_client 507 string languages_client_to_server 508 string languages_server_to_client 509 boolean first_kex_packet_follows 510 uint32 0 (reserved for future extension) 512 Each of the algorithm strings MUST be a comma-separated list of 513 algorithm names (see ``Algorithm Naming'' in [SSH-ARCH]). Each supported 514 (allowed) algorithm MUST be listed, in order of preference. 516 The first algorithm in each list MUST be the preferred (guessed) 517 algorithm. Each string MUST contain at least one algorithm name. 519 cookie 520 The cookie MUST be a random value generated by the sender. Its 521 purpose is to make it impossible for either side to fully 522 determine the keys and the session identifier. 524 kex_algorithms 525 Key exchange algorithms were defined above. The first algorithm 526 MUST be the preferred (and guessed) algorithm. If both sides make 527 the same guess, that algorithm MUST used. Otherwise, the 528 following algorithm MUST be used to choose a key exchange method: 529 iterate over client's kex algorithms, one at a time. Choose the 530 first algorithm that satisfies the following conditions: 532 o the server also supports the algorithm, 534 o if the algorithm requires an encryption-capable host key, there is 535 an encryption-capable algorithm on the server's 536 server_host_key_algorithms that is also supported by the client, 537 and 539 o if the algorithm requires a signature-capable host key, there is a 540 signature-capable algorithm on the server's 541 server_host_key_algorithms that is also supported by the client. 543 If no algorithm satisfying all these conditions can be found, the 544 connection fails, and both sides MUST disconnect. 546 server_host_key_algorithms 547 List of the algorithms supported for the server host key. The 548 server lists the algorithms for which it has host keys; the client 549 lists the algorithms that it is willing to accept. (There MAY be 550 multiple host keys for a host, possibly with different 551 algorithms.) 553 Some host keys may not support both signatures and encryption 554 (this can be determined from the algorithm), and thus not all host 555 keys are valid for all key exchange methods. 557 Algorithm selection depends on whether the chosen key exchange 558 algorithm requires a signature- or encryption capable host key. 559 It MUST be possible to determine this from the public key 560 algorithm name. The first algorithm on the client's list that 561 satisfies the requirements and is also supported by the server 562 MUST be chosen. If there is no such algorithm, both sides MUST 563 disconnect. 565 encryption_algorithms 566 Lists the acceptable symmetric encryption algorithms in order of 567 preference. The chosen encryption algorithm to each direction 568 MUST be the first algorithm on the client's list that is also on 569 the server's list. If there is no such algorithm, both sides MUST 570 disconnect. 572 Note that "none" must be explicitly listed if it is to be 573 acceptable. The defined algorithm names are listed in Section 574 ``Encryption''. 576 mac_algorithms 577 Lists the acceptable MAC algorithms in order of preference. The 578 chosen MAC algorithm MUST be the first algorithm on the client's 579 list that is also on the server's list. If there is no such 580 algorithm, both sides MUST disconnect. 582 Note that "none" must be explicitly listed if it is to be 583 acceptable. The MAC algorithm names are listed in Section ``Data 584 Integrity''. 586 compression_algorithms 587 Lists the acceptable compression algorithms in order of 588 preference. The chosen compression algorithm MUST be the first 589 algorithm on the client's list that is also on the server's list. 590 If there is no such algorithm, both sides MUST disconnect. 592 Note that "none" must be explicitly listed if it is to be 593 acceptable. The compression algorithm names are listed in Section 594 ``Compression''. 596 languages 597 This is a comma-separated list of language tags in order of 598 preference [RFC-1766]. Both parties MAY ignore this list. If there 599 are no language preferences, this list SHOULD be empty. 601 first_kex_packet_follows 602 Indicates whether a guessed key exchange packet follows. If a 603 guessed packet will be sent, this MUST be true. If no guessed 604 packet will be sent, this MUST be false. 606 After receiving the SSH_MSG_KEXINIT packet from the other side, 607 each party will know whether their guess was right. If the other 608 party's guess was wrong, and this field was true, the next packet 609 MUST be silently ignored, and both sides MUST then act as 610 determined by the negotiated key exchange method. If the guess 611 was right, key exchange MUST continue using the guessed packet. 613 After the KEXINIT packet exchange, the key exchange algorithm is run. 614 It may involve several packet exchanges, as specified by the key 615 exchange method. 617 5.2. Output from Key Exchange 619 The key exchange produces two values: a shared secret K, and an exchange 620 hash H. Encryption and authentication keys are derived from these. The 621 exchange hash H from the first key exchange is additionally used as the 622 session identifier, which is a unique identifier for this connection. 623 It is used by authentication methods as a part of the data that is 624 signed as a proof of possession of a private key. Once computed, the 625 session identifier is not changed, even if keys are later re-exchanged. 627 Each key exchange method specifies a hash function that is used in the 628 key exchange. The same hash algorithm MUST be used in key derivation. 629 Here, we'll call it HASH. 631 Encryption keys MUST be computed as HASH of a known value and K as 632 follows: 634 o Initial IV client to server: HASH(K || H || "A" || session_id) ("A" 635 means the single character A, ascii 65). 637 o Initial IV server to client: HASH(K || H || "B" || session_id) 639 o Encryption key client to server: HASH(K || H || "C" || session_id) 641 o Encryption key server to client: HASH(K || H || "D" || session_id) 643 o Integrity key client to server: HASH(K || H || "E" || session_id) 645 o Integrity key server to client: HASH(K || H || "F" || session_id) 647 Key data MUST be taken from the beginning of the hash output. 128 bits 648 (16 bytes) SHOULD be used for algorithms with variable-length keys. For 649 other algorithms, as many bytes as are needed are taken from the 650 beginning of the hash value. If the key length in longer than the output 651 of the HASH, the key is extended by computing HASH of the concatenation 652 of K and H and the entire key so far, and appending the resulting bytes 653 (as many as HASH generates) to the key. This process is repeated until 654 enough key material is available; the key is taken from the beginning of 655 this value. In other words, 657 K1 = HASH(K || H || X || session_id) (X is e.g. "A") 658 K2 = HASH(K || H || K1) 659 K3 = HASH(K || H || K1 || K2) 660 ... 661 key = K1 || K2 || K3 || ... 663 5.3. Taking Keys into Use 665 Key exchange ends by each side sending an SSH_MSG_NEWKEYS message. This 666 message is sent with the old keys and algorithms. All messages sent 667 after this message MUST use the new keys and algorithms. 669 When this message is received, the new keys and algorithms MUST be taken 670 into use for receiving. 672 This message is the only valid message after key exchange, in addition 673 to SSH_MSG_DEBUG, SSH_MSG_DISCONNECT and SSH_MSG_IGNORE messages. The 674 purpose of this message is to ensure that a party is able to respond 675 with a disconnect message that the other party can understand if 676 something goes wrong with the key exchange. Implementations MUST NOT 677 accept any other messages after key exchange before receiving 678 SSH_MSG_NEWKEYS. 680 byte SSH_MSG_NEWKEYS 682 6. Diffie-Hellman Key Exchange 684 The Diffie-Hellman key exchange provides a shared secret that can not be 685 determined by either party alone. The key exchange is combined with a 686 signature with the host key to provide host authentication. 687 In the following description (C is the client, S is the server; p is a 688 large safe prime, g is a generator for a subgroup of GF(p), and q is the 689 order of the subgroup; V_S is S's version string; V_C is C's version 690 string; K_S is S's public host key; I_C is C's KEXINIT message and I_S 691 S's KEXINIT message which have been exchanged before this part begins): 693 1. C generates a random number x (1 < x < q) and computes e = g^x mod p. 694 C sends "e" to S. 696 2. S generates a random number y (0 < y < q) and computes f = g^y mod p. 697 S receives "e". It computes K = e^y mod p, H = hash(V_C || V_S || 698 I_C || I_S || K_S || e || f || K), and signature s on H with its 699 private host key. S sends "K_S || f || s" to C. The signing 700 operation may involve a second hashing operation. 702 3. C verifies that K_S really is the host key for S (e.g. using 703 certificates or a local database). C is also allowed to accept the 704 key without verification; however, doing so will render the protocol 705 insecure against active attacks (but may be desirable for practical 706 reasons in the short term in many environments). C then computes K = 707 f^x mod p, H = hash(V_C || V_S || I_C || I_S || K_S || e || f || K), 708 and verifies the signature s on H. 710 Either side MUST NOT send or accept e or f values that are not in the 711 range [1, p-1]. If this condition is violated, the key exchange 712 fails. 714 This is implemented with the following messages. The hash algorithm for 715 computing the exchange hash is defined by the method name, and is called 716 HASH. The public key algorithm for signing is negotiated with the 717 KEXINIT messages. 719 First, the client sends: 721 byte SSH_MSG_KEXDH_INIT 722 mpint e 724 The server responds with: 726 byte SSH_MSG_KEXDH_REPLY 727 string server public host key and certificates (K_S) 728 mpint f 729 string signature of H 731 The hash H is computed as the HASH hash of the concatenation of the 732 following: 734 string V_C, the client's version string (CR and NL excluded) 735 string V_S, the server's version string (CR and NL excluded) 736 string I_C, the payload of the client's SSH_MSG_KEXINIT 737 string I_S, the payload of the server's SSH_MSG_KEXINIT 738 string K_S, the host key 739 mpint e, exchange value sent by the client 740 mpint f, exchange value sent by the server 741 mpint K, the shared secret 743 This value is called the exchange hash, and it is used to authenticate 744 the key exchange. 746 The signature algorithm MUST be applied over H, not the original data. 747 Most signature algorithms include hashing and additional padding. For 748 example, a "ssh-dss" specifies SHA-1 hashing; in that case, the data is 749 first hashed with HASH to compute H, and H is then hashed with SHA-1 as 750 part of the signing operation. 752 6.1. diffie-hellman-group1-sha1 754 The "diffie-hellman-group1-sha1" method specifies Diffie-Hellman key 755 exchange with SHA-1 as HASH, and the following group: 757 The prime p is equal to 2^1024 - 2^960 - 1 + 2^64 * floor( 2^894 Pi + 758 129093 ). Its hexadecimal value is 760 FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 761 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD 762 EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 763 E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED 764 EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381 765 FFFFFFFF FFFFFFFF. 767 In decimal, this value is 769 179769313486231590770839156793787453197860296048756011706444 770 423684197180216158519368947833795864925541502180565485980503 771 646440548199239100050792877003355816639229553136239076508735 772 759914822574862575007425302077447712589550957937778424442426 773 617334727629299387668709205606050270810842907692932019128194 774 467627007. 776 The generator used with this prime is g = 2. The group order q is (p - 777 1) / 2. 779 This group was taken from the ISAKMP/Oakley specification, and was 780 originally generated by Richard Schroeppel at the University of Arizona. 781 Properties of this prime are described in [Orm96]. 783 7. Key Re-Exchange 785 Key re-exchange is started by sending a SSH_MSG_KEXINIT packet when not 786 already doing a key exchange (as described in Section ``Algorithm 787 Negotiation''). When this message is received, a party MUST respond 788 with its own SSH_MSG_KEXINIT message except when the received 789 SSH_MSG_KEXINIT already was a reply. Either party MAY initiate the re- 790 exchange, but roles MUST NOT be changed (i.e., the server remains the 791 server, and the client remains the client). 793 Key re-exchange is performed using whatever encryption was in effect 794 when the exchange was started. Encryption, compression, and MAC methods 795 are not changed before a new SSH_MSG_NEWKEYS is sent after the key 796 exchange (as in the initial key exchange). Re-exchange is processed 797 identically to the initial key exchange, except for the session 798 identifier that will remain unchanged. It is permissible to change some 799 or all of the algorithms during the re-exchange. Host keys can also 800 change. All keys and initialization vectors are recomputed after the 801 exchange. Compression and encryption contexts are reset. 803 It is recommended that the keys are changed after each gigabyte of 804 transmitted data or after each hour of connection time, whichever comes 805 sooner. However, since the re-exchange is a public key operation, it 806 requires a fair amount of processing power and should not be performed 807 too often. 809 More application data may be sent after the SSH_MSG_NEWKEYS packet has 810 been sent; key exchange does not affect the protocols that lie above the 811 SSH transport layer. 813 8. Service Request 815 After the key exchange, the client requests a service. The service is 816 identified by a name. The format of names and procedures for defining 817 new names are defined in [SSH-ARCH]. 819 Currently, the following names have been reserved: 821 ssh-userauth 822 ssh-connection 824 Similar local naming policy is applied to the service names that is 825 applied to the algorithm names; a local service should use the 826 servicename@domain syntax. 828 byte SSH_MSG_SERVICE_REQUEST 829 string service name 831 If the server rejects the service request, it SHOULD send an appropriate 832 SSH_MSG_DISCONNECT message and MUST disconnect. 834 When the service starts, it may have access to the session identifier 835 generated during the key exchange. 837 If the server supports the service (and permits the client to use it), 838 it MUST respond with 839 byte SSH_MSG_SERVICE_ACCEPT 840 string service name 842 Message numbers used by services should be in the area reserved for them 843 (see Section ``Summary of Message Numbers''). The transport level will 844 continue to process its own messages. 846 Note that after a key exchange with implicit server authentication, the 847 client MUST wait for response to its service request message before 848 sending any further data. 850 9. Additional Messages 852 Either party may send any of the following messages at any time. 854 9.1. Disconnection Message 856 byte SSH_MSG_DISCONNECT 857 uint32 reason code 858 string description [RFC-2044] 859 string language tag [RFC-1766] 861 This message causes immediate termination of the connection. All 862 implementations MUST be able to process this message; they SHOULD be 863 able to send this message. 865 The sender MUST NOT send or receive any data after this message, and the 866 recipient MUST NOT accept any data after receiving this message. The 867 description field gives a more specific explanation in a human-readable 868 form. The error code gives the reason in a more machine-readable format 869 (suitable for localization), and can have the following values: 871 #define SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1 872 #define SSH_DISCONNECT_PROTOCOL_ERROR 2 873 #define SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3 874 #define SSH_DISCONNECT_HOST_AUTHENTICATION_FAILED 4 875 #define SSH_DISCONNECT_MAC_ERROR 5 876 #define SSH_DISCONNECT_COMPRESSION_ERROR 6 877 #define SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7 878 #define SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8 879 #define SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9 880 #define SSH_DISCONNECT_CONNECTION_LOST 10 881 #define SSH_DISCONNECT_BY_APPLICATION 11 883 If the description string is displayed, control character filtering 884 discussed in [SSH-ARCH] should be used to avoid attacks by sending 885 terminal control characters. 887 9.2. Ignored Data Message 889 byte SSH_MSG_IGNORE 890 string data 892 All implementations MUST understand (and ignore) this message at any 893 time (after receiving the protocol version). No implementation is 894 required to send them. This message can be used as an additional 895 protection measure against advanced traffic analysis techniques. 897 9.3. Debug Message 899 byte SSH_MSG_DEBUG 900 boolean always_display 901 string message [RFC-2044] 902 string language tag [RFC-1766] 904 All implementations MUST understand this message, but they are allowed 905 to ignore it. This message is used to pass information to the other 906 side that may help debugging. If always_display is true, the message 907 SHOULD be displayed. Otherwise, it SHOULD NOT be displayed unless 908 debugging information has been explicitly requested by the user. 910 The message doesn't need to contain a newline. It is, however, allowed 911 to consist of multiple lines separated by CRLF (carriage return - line 912 feed) pairs. 914 If the message string is displayed, terminal control character filtering 915 discussed in [SSH-ARCH] should be used to avoid attacks by sending 916 terminal control characters. 918 9.4. Reserved Messages 920 An implementation MUST respond to all unrecognized messages with an 921 SSH_MSG_UNIMPLEMENTED message in the order in which they were received. 922 Such messages MUST be otherwise ignored. Later protocol versions may 923 define other meanings for these message types. 925 byte SSH_MSG_UNIMPLEMENTED 926 uint32 packet sequence number of rejected message 928 10. Summary of Message Numbers 930 The following message numbers have been defined in this protocol. 932 #define SSH_MSG_DISCONNECT 1 933 #define SSH_MSG_IGNORE 2 934 #define SSH_MSG_UNIMPLEMENTED 3 935 #define SSH_MSG_DEBUG 4 936 #define SSH_MSG_SERVICE_REQUEST 5 937 #define SSH_MSG_SERVICE_ACCEPT 6 939 #define SSH_MSG_KEXINIT 20 940 #define SSH_MSG_NEWKEYS 21 942 /* Numbers 30-49 used for kex packets. 943 Different kex methods may reuse message numbers in 944 this range. */ 946 #define SSH_MSG_KEXDH_INIT 30 947 #define SSH_MSG_KEXDH_REPLY 31 949 11. Security Considerations 951 This protocol provides a secure encrypted channel over an unsecure 952 network. It performs server host authentication, key exchange, 953 encryption, and integrity protection. It also derives a unique session 954 id that may be used by higher-level protocols. 956 It is expected that this protocol will sometimes be used without 957 insisting on reliable association between the server host key and the 958 server host name. Such use is inherently insecure, but may be necessary 959 in non-security critical environments, and still provides protection 960 against passive attacks. However, implementors of protocols running on 961 top of this protocol should keep this possibility in mind. 963 This protocol is designed to be used over a reliable transport. If 964 transmission errors or message manipulation occur, the connection is 965 closed. The connection SHOULD be re-established if this occurs. Denial 966 of service attacks of this type ("wire cutter") are almost impossible to 967 avoid. 969 The protocol was not designed to eliminate covert channels. For 970 example, the padding, SSH_MSG_IGNORE messages, and several other places 971 in the protocol can be used to pass covert information, and the 972 recipient has no reliable way to verify whether such information is 973 being sent. 975 12. References 977 [FIPS-186] Federal Information Processing Standards Publication (FIPS 978 PUB) 186, Digital Signature Standard, 18 May 1994. 980 [Orm96] Orman, H., "The Oakley Key Determination Protocol", version 1, 981 TR97-92, Department of Computer Science Technical Report, University of 982 Arizona. 984 [RFC-1034] Mockapetris, P., "Domain Names - Concepts and Facilities", 985 November 1987. 987 [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages", 988 March 1995. 990 [RFC-1950] Deutch, P. and Gailly, J-L., "ZLIB Compressed Data Format 991 Specification version 3.3", May 1996. 993 [RFC-1951] Deutch, P., "DEFLATE Compressed Data Format Specification 994 version 1.3", May 1996. 996 [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and 997 ISO 10646", October 1996. 999 [RFC-2104] Krawczyk, H., Bellare, M., and Canetti, R., "HMAC: Keyed- 1000 Hashing for Message Authentication", February 1997 1002 [RFC-2119] Bradner, S., "Key words for use in RFCs to indicate 1003 Requirement Levels", March 1997. 1005 [RFC-2144] Adams, C., "The CAST-128 Encryption Algorithm", May 1997. 1007 [Schneier] Schneier, B., "Applied Cryptography Second Edition: 1008 protocols, algorithms, and source code in C", 2nd edition, John Wiley & 1009 Sons, New York, NY, 1996. 1011 [SSH-ARCH] Ylonen, T., et al, "SSH Protocol Architecture", Internet 1012 Draft, draft-ietf-secsh-architecture-03.txt 1014 [SSH-USERAUTH] Ylonen, T., et al, "SSH Authentication Protocol", 1015 Internet Draft, draft-ietf-secsh-userauth-05.txt 1017 [SSH-CONNECT] Ylonen, T., et al, "SSH Connection Protocol", Internet 1018 Draft, draft-ietf-secsh-connect-05.txt 1020 [PGP] (XXX n.a.) 1022 [PKIX-Part1] (XXX n.a.) 1024 13. Authors' Addresses 1026 Tatu Ylonen 1027 SSH Communications Security Ltd. 1028 Tekniikantie 12 1029 FIN-02150 ESPOO 1030 Finland 1031 E-mail: ylo@ssh.fi 1033 Tero Kivinen 1034 SSH Communications Security Ltd. 1035 Tekniikantie 12 1036 FIN-02150 ESPOO 1037 Finland 1038 E-mail: kivinen@ssh.fi 1040 Markku-Juhani O. Saarinen 1041 SSH Communications Security Ltd. 1042 Tekniikantie 12 1043 FIN-02150 ESPOO 1044 Finland 1045 E-mail: mjos@ssh.fi 1046 Timo J. Rinne 1047 SSH Communications Security Ltd. 1048 Tekniikantie 12 1049 FIN-02150 ESPOO 1050 Finland 1051 E-mail: tri@ssh.fi 1053 Sami Lehtinen 1054 SSH Communications Security Ltd. 1055 Tekniikantie 12 1056 FIN-02150 ESPOO 1057 Finland 1058 E-mail: sjl@ssh.fi