idnits 2.17.1 draft-ietf-secsh-transport-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 425 has weird spacing: '... string cert...' == Line 490 has weird spacing: '... string kex...' == Line 491 has weird spacing: '... string ser...' == Line 492 has weird spacing: '... string enc...' == Line 493 has weird spacing: '... string enc...' == (20 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 (6 August 1998) is 9394 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 461, but not defined -- Looks like a reference, but probably isn't: '16' on line 489 == Unused Reference: 'RFC-1034' is defined on line 968, but no explicit reference was found in the text == Unused Reference: 'SSH-CONNECT' is defined on line 1001, 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-00 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-02 -- Possible downref: Non-RFC (?) normative reference: ref. 'PGP' -- Possible downref: Non-RFC (?) normative reference: ref. 'PKIX-Part1' Summary: 14 errors (**), 0 flaws (~~), 13 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-04.txt M. Saarinen 4 Expires in six months T. Rinne 5 S. Lehtinen 6 SSH 7 6 August 1998 9 SSH Transport Layer Protocol 11 Status of This memo 13 This document is an Internet-Draft. Internet-Drafts are working 14 documents of the Internet Engineering Task Force (IETF), its areas, 15 and its working groups. Note that other groups may also distribute 16 working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other documents 20 at any time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as ``work in progress.'' 23 To learn the current status of any Internet-Draft, please check 24 the ``1id-abstracts.txt'' listing contained in the Internet-Drafts 25 Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 26 munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), 27 or ftp.isi.edu (US West Coast). 29 Abstract 31 SSH is a protocol for secure remote login and other secure network ser- 32 vices over an insecure network. This document describes the SSH trans- 33 port layer protocol which typically runs on top of TCP/IP. The protocol 34 can be used as a basis for a number of secure network services. It pro- 35 vides strong encryption, server authentication, and integrity protec- 36 tion. It may also provide compression. Key exchange method, public key 37 algorithm, symmetric encryption algorithm, message authentication algo- 38 rithm, and hash algorithm are all negotiated. This document also 39 describes the Diffie-Hellman key exchange method and the minimal set of 40 algorithms that are needed to implement the SSH transport layer proto- 41 col. 43 Table of Contents 45 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 46 2. Conventions Used in This Document . . . . . . . . . . . . . . . 3 47 3. Connection Setup . . . . . . . . . . . . . . . . . . . . . . . . 3 48 3.1. Use over TCP/IP . . . . . . . . . . . . . . . . . . . . . . 3 49 3.2. Protocol Version Exchange . . . . . . . . . . . . . . . . . 3 50 3.3. Compatibility with Old SSH Versions . . . . . . . . . . . . 4 51 3.3.1. Old Client, New Server . . . . . . . . . . . . . . . . . 4 52 3.3.2. New Client, Old Server . . . . . . . . . . . . . . . . . 4 53 4. Binary Packet Protocol . . . . . . . . . . . . . . . . . . . . . 4 54 4.1. Maximum Packet Length . . . . . . . . . . . . . . . . . . . 5 55 4.2. Compression . . . . . . . . . . . . . . . . . . . . . . . . 5 56 4.3. Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 6 57 4.4. Data Integrity . . . . . . . . . . . . . . . . . . . . . . . 7 58 4.5. Key Exchange Methods . . . . . . . . . . . . . . . . . . . . 8 59 4.6. Public Key Algorithms . . . . . . . . . . . . . . . . . . . 8 60 5. Key Exchange . . . . . . . . . . . . . . . . . . . . . . . . . . 10 61 5.1. Algorithm Negotiation . . . . . . . . . . . . . . . . . . . 10 62 5.2. Output from Key Exchange . . . . . . . . . . . . . . . . . . 12 63 5.3. Taking Keys into Use . . . . . . . . . . . . . . . . . . . . 13 64 6. Diffie-Hellman Key Exchange . . . . . . . . . . . . . . . . . . 13 65 6.1. diffie-hellman-group1-sha1 . . . . . . . . . . . . . . . . . 15 66 7. Key Re-Exchange . . . . . . . . . . . . . . . . . . . . . . . . 15 67 8. Service Request . . . . . . . . . . . . . . . . . . . . . . . . 16 68 9. Additional Messages . . . . . . . . . . . . . . . . . . . . . . 17 69 9.1. Disconnection Message . . . . . . . . . . . . . . . . . . . 17 70 9.2. Ignored Data Message . . . . . . . . . . . . . . . . . . . . 17 71 9.3. Debug Message . . . . . . . . . . . . . . . . . . . . . . . 17 72 9.4. Reserved Messages . . . . . . . . . . . . . . . . . . . . . 18 73 10. Summary of Message Numbers . . . . . . . . . . . . . . . . . . 18 74 11. Security Considerations . . . . . . . . . . . . . . . . . . . . 18 75 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 76 13. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 20 78 1. Introduction 80 The SSH transport layer is a secure low level transport protocol. It 81 provides strong encryption, cryptographic host authentication, and 82 integrity protection. 84 Authentication in this protocol level is host-based; this protocol does 85 not perform user authentication. A higher level protocol for user 86 authentication can be designed on top of this protocol. 88 The protocol has been designed to be simple, flexible, to allow 89 parameter negotiation, and to minimize the number of round-trips. Key 90 exchange method, public key algorithm, symmetric encryption algorithm, 91 message authentication algorithm, and hash algorithm are all negotiated. 92 It is expected that in most environments, only 2 round-trips will be 93 needed for full key exchange, server authentication, service request, 94 and acceptance notification of service request. The worst case is 3 95 round-trips. 97 2. Conventions Used in This Document 99 The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", and 100 "MAY" that appear in this document are to be interpreted as described in 101 [RFC-2119]. 103 The used data types and terminology are specified in the architecture 104 document [SSH-ARCH]. 106 The architecture document also discusses the algorithm naming 107 conventions that MUST be used with the SSH protocols. 108 3. Connection Setup 110 SSH works over any 8-bit clean, binary-transparent transport. The 111 underlying transport SHOULD protect against transmission errors as such 112 errors cause the SSH connection to terminate. 114 The client initiates the connection. 116 3.1. Use over TCP/IP 118 When used over TCP/IP, the server normally listens for connections on 119 port 22. This port number has been registered with the IANA, and has 120 been officially assigned for SSH. 122 3.2. Protocol Version Exchange 124 When the connection has been established, both sides MUST send an 125 identification string of the form "SSH-protoversion-softwareversion 126 comments", followed by carriage return and newline characters (ascii 13 127 and 10, respectively). Both sides MUST be able to process 128 identification strings without carriage return character. No null 129 character is sent. The maximum length of the string is 255 characters, 130 including the carriage return and newline. 132 The part of the identification string preceding carriage return and 133 newline is used in the Diffie-Hellman key exchange (Section ``Diffie- 134 Hellman Key Exchange''). 136 The server MAY send other lines of data before sending the version 137 string. Each line SHOULD be terminated by a carriage return and 138 newline. Such lines MUST NOT begin with "SSH-", and SHOULD be encoded 139 in ISO-10646 UTF-8 [RFC-2044] (language is not specified). Clients MUST 140 be able to process such lines; they MAY be silently ignored, or MAY be 141 displayed to the client user; if they are displayed, control character 142 filtering discussed in [SSH-ARCH] SHOULD be used. The primary use of 143 this feature is to allow TCP-wrappers to display an error message before 144 disconnecting. 146 Version strings MUST consist of printable US-ASCII characters, not 147 including whitespaces or a minus sign (-). The version string is 148 primarily used to trigger compatibility extensions and to indicate the 149 capabilities of an implementation. The comment string should contain 150 additional information that might be useful in solving user problems. 152 The protocol version described in this document is 2.0. 154 Key exchange will begin immediately after sending this identifier. All 155 packets following the identification string SHALL use the binary packet 156 protocol, to be described below. 157 3.3. Compatibility with Old SSH Versions 159 During a transition period, it is important to be able to work 160 compatibly with installed SSH clients and servers using an older version 161 of the protocol. Information in this section is only relevant for 162 implementations supporting compatibility with SSH versions 1.x. 164 3.3.1. Old Client, New Server 166 Server implementations MAY support a configurable "compatibility" flag 167 that enables compatibility with old versions. When this flag is on, the 168 server SHOULD identify its protocol version as "1.99". Clients using 169 protocol 2.0 MUST be able to identify this as identical to "2.0". In 170 this mode the server SHOULD NOT send carriage return character (ascii 171 13) after the version identification string. 173 In the compatibility mode the server SHOULD NOT send any further data 174 after its initialization string until it has received an identification 175 string from the client. The server can then determine whether the 176 client is using an old protocol, and can revert to the old protocol if 177 desired. The server MUST NOT send additional data before the version 178 string, in the compatibility mode. 180 When compatibility with old clients is not needed, the server MAY send 181 its initial key exchange data immediately after the identification 182 string. 184 3.3.2. New Client, Old Server 186 Since the new client MAY immediately send additional data after its 187 identification string (before receiving server's identification), the 188 old protocol may already have been corrupted when the client learns that 189 the server is old. When this happens, the client SHOULD close the 190 connection to the server, and reconnect using the old protocol. 192 4. Binary Packet Protocol 194 Each packet is of the following format. 196 uint32 packet_length 197 byte padding_length 198 byte[n1] payload; n1 = packet_length - padding_length - 1 199 byte[n2] random padding; n2 = padding_length 200 byte[m] mac (message authentication code); m = mac_length 202 packet_length 203 The length of the packet (bytes), not including MAC or the 204 packet_length field itself. 206 padding_length 207 Length of padding (bytes). 209 payload 210 The useful contents of the packet. If compression has been 211 negotiated, this field is compressed. Initially, compression MUST 212 be "none". 214 Padding 215 Arbitrary-length padding, such that the total length of 216 (packet_length || padding_length || payload || padding) is a 217 multiple of the cipher block size or 8, whichever is larger. 218 There MUST be at least four bytes of padding. The padding SHOULD 219 consist of random bytes. The maximum amount of padding is 255 220 bytes. 222 MAC 223 Message authentication code. If message authentication has been 224 negotiated, this field contains the MAC bytes. Initially, the MAC 225 algorithm MUST be "none". 227 Note that length of the concatenation of packet length, padding length, 228 payload, and padding MUST be a multiple of the cipher block size or 8, 229 whichever is larger. This constraint MUST be enforced even when using 230 stream ciphers. Note that the packet length field is also encrypted, 231 and processing it requires special care when sending or receiving 232 packets. 234 The minimum size of a packet is 16 (or the cipher block size, whichever 235 is larger) bytes (plus MAC); implementations SHOULD decrypt the length 236 after receiving the first 8 (or cipher block size, whichever is larger) 237 bytes of a packet. 239 4.1. Maximum Packet Length 241 All implementations MUST be able to process packets with uncompressed 242 payload length of 32768 bytes or less and total packet size of 35000 243 bytes or less (including length, padding length, payload, padding, and 244 MAC). Implementations SHOULD support longer packets, where they might 245 be needed e.g. if an implementation wants to send a very large number of 246 certificates. Such packets MAY be sent if the version string indicates 247 that the other party is able to process them. However, implementations 248 SHOULD check that the packet length is reasonable for the implementation 249 to avoid denial-of-service and/or buffer overflow attacks. 251 4.2. Compression 252 If compression has been negotiated, the payload field (and only it) will 253 be compressed using the negotiated algorithm. The length field and MAC 254 will be computed from the compressed payload. 256 Compression MAY be stateful, depending on the method. Compression MUST 257 be independent for each direction, and implementations MUST allow 258 independently choosing the algorithm for each direction. 260 The following compression methods are currently defined: 262 none REQUIRED no compression 263 zlib OPTIONAL GNU ZLIB (LZ77) compression 265 The "zlib" compression is described in [RFC-1950] and in [RFC-1951]. The 266 compression context is initialized after each key exchange, and is 267 passed from one packet to the next with only a partial flush being 268 performed at the end of each packet. A partial flush means that all data 269 will be output, but the next packet will continue using compression 270 tables from the end of the previous packet. 272 Additional methods may be defined as specified in [SSH-ARCH]. 274 4.3. Encryption 276 An encryption algorithm and a key will be negotiated during the key 277 exchange. When encryption is in effect, the packet length, padding 278 length, payload and padding fields of each packet MUST be encrypted with 279 the given algorithm. 281 The encrypted data in all packets sent in one direction SHOULD be 282 considered a single data stream. For example, initialization vectors 283 SHOULD be passed from the end of one packet to the beginning of the next 284 packet. All ciphers SHOULD use keys with an effective key length of 128 285 bits or more. 287 The ciphers in each direction MUST run independently of each other, and 288 implementations MUST allow independently choosing the algorithm for each 289 direction (if multiple algorithms are allowed by local policy). 291 The following ciphers are currently defined: 293 3des-cbc REQUIRED three-key 3DES in CBC mode 294 blowfish-cbc RECOMMENDED Blowfish in CBC mode 295 arcfour OPTIONAL the ARCFOUR stream cipher 296 idea-cbc OPTIONAL IDEA in CBC mode 297 cast128-cbc OPTIONAL CAST-128 in CBC mode 298 none OPTIONAL no encryption; NOT RECOMMENDED 300 The "3des-cbc" cipher is three-key triple-DES (encrypt-decrypt-encrypt), 301 where the first 8 bytes of the key are used for the first encryption, 302 the next 8 bytes for the decryption, and the following 8 bytes for the 303 final encryption. This requires 24 bytes of key data (of which 168 bits 304 are actually used). To implement CBC mode, outer chaining MUST be used 305 (i.e., there is only one initialization vector). This is a block cipher 306 with 8 byte blocks. This algorithm is defined in [Schneier]. 308 The "blowfish-cbc" cipher is Blowfish in CBC mode, with 128 bit keys 309 [Schneier]. This is a block cipher with 8 byte blocks. 311 The "arcfour" is the Arcfour stream cipher with 128 bit keys. The 312 Arcfour cipher is believed to be compatible with the RC4 cipher 313 [Schneier]. RC4 is a registered trademark of RSA Data Security Inc. 315 The "idea-cbc" cipher is the IDEA cipher in CBC mode [Schneier]. IDEA is 316 patented by Ascom AG. 318 The "cast128-cbc" cipher is the CAST-128 cipher in CBC mode [RFC-2144]. 320 The "none" algorithm specifies that no encryption is to be done. Note 321 that this method provides no confidentiality protection, and it is not 322 recommended. Some functionality (e.g. password authentication) may be 323 disabled for security reasons if this cipher is chosen. 325 Additional methods may be defined as specified in [SSH-ARCH]. 327 4.4. Data Integrity 329 Data integrity is protected by including with each packet a message 330 authentication code (MAC) that is computed from a shared secret, packet 331 sequence number, and the contents of the packet. 333 The message authentication algorithm and key are negotiated during key 334 exchange. Initially, no MAC will be in effect, and its length MUST be 335 zero. After key exchange, the selected MAC will be computed before 336 encryption from the concatenation of packet data: 337 mac = MAC(key, sequence_number || unencrypted_packet) 339 where unencrypted_packet is the entire packet without MAC (the length 340 fields, payload and padding), and sequence_number is an implicit packet 341 sequence number represented as uint32. The sequence number is initial- 342 ized to zero for the first packet, and is incremented after every packet 343 (regardless of whether encryption or MAC is in use). It is never reset, 344 even if keys/algorithms are renegotiated later. It wraps around to zero 345 after every 2^32 packets. The packet sequence number itself is not 346 included in the packet sent over the wire. 348 The MAC algorithms for each direction MUST run independently, and 349 implementations MUST allow choosing the algorithm independently for both 350 directions. 352 The MAC bytes resulting from the MAC algorithm MUST be transmitted 353 without encryption as the last part of the packet. The number of MAC 354 bytes depends on the algorithm chosen. 356 The following MAC algorithms are currently defined: 358 hmac-sha1 REQUIRED HMAC-SHA1 (length = 20) 359 hmac-sha-96 RECOMMENDED first 96 bits of HMAC-SHA1 (length = 12) 360 hmac-md5 OPTIONAL HMAC-MD5 (length = 16) 361 hmac-md5-96 OPTIONAL first 96 bits of HMAC-MD5 (length = 12) 362 none OPTIONAL no MAC; NOT RECOMMENDED 364 The "hmac-*" algorithms are described in [RFC-2104]. The "*-n" MACs use 365 only the first n bits of the resulting value. 367 The hash algorithms are described in [Schneier]. 369 The "none" method is NOT RECOMMENDED. An active attacker may be able to 370 modify transmitted data if this is used. 372 Additional methods may be defined as specified in [SSH-ARCH]. 374 4.5. Key Exchange Methods 376 The key exchange method specifies how one-time session keys are 377 generated for encryption and for authentication, and how the server 378 authentication is done. 380 Only one REQUIRED key exchange method has been defined: 382 diffie-hellman-group1-sha1 REQUIRED 384 This method is described later in this document. 386 Additional methods may be defined as specified in [SSH-ARCH]. 388 4.6. Public Key Algorithms 390 This protocol has been designed to be able to operate with almost any 391 public key format, encoding, and algorithm (signature and/or 392 encryption). 394 There are several aspects that define a public key type: 396 o Key format: how is the key encoded and how are certificates 397 represented. The key blobs in this protocol MAY contain certificates 398 in addition to keys. 400 o Signature and/or encryption algorithms. Some key types may not 401 support both signing and encryption. Key usage may also be 402 restricted by policy statements in e.g. certificates. In this case, 403 different key types SHOULD be defined for the different policy 404 alternatives. 406 o Encoding of signatures and/or encrypted data. This includes but is 407 not limited to padding, byte order, and data formats. 409 The following public key and/or certificate formats are currently 410 defined: 412 ssh-dss REQUIRED sign Simple DSS 413 x509v3 RECOMMENDED sign X.509 certificates 414 spki OPTIONAL sign SPKI certificates 415 pgp OPTIONAL sign OpenPGP certificates 417 Additional key types may be defined as specified in [SSH-ARCH]. 419 The key type MUST always be explicitly known (from algorithm negotiation 420 or some other source). It is not normally included in the key blob. 422 Certificates and public keys are encoded as: 424 uint32 combined length of the format identifier and associated data 425 string certificate or public key format identifier 426 byte[n] key/certificate data 428 The certificate part may have be a zero length string, but a public key 429 is required. This is the public key that will be used for 430 authentication; the certificate sequence contained in the certificate 431 blob can be used to provide authorization. 433 The "ssh-dss" key format has the following specific encoding: 435 uint32 length 436 string "ssh-dss" 437 mpint p 438 mpint q 439 mpint g 440 mpint y 442 Here the "p", "q", "g", and "y" parameters form the signature key blob. 444 Signing and verifying using this key format are done according to the 445 Digital Signature Standard [FIPS-186] using the SHA-1 hash. A 446 description can also be found in [Schneier]. 448 The resulting signature is encoded as: 450 uint32 length 451 string "ssh-dss" 452 mpint r 453 mpint s 455 The "x509v3" method indicates that the certificates, the public key, and 456 the resulting signature are in X.509v3 compatible DER-encoded format. 457 The formats used in X.509v3 is described in [PKIX-Part1]. 459 The "spki" method indicates that the certificate blob contains a 460 sequence of SPKI certificates. The format of SPKI certificates is 461 described in [SPKI]. 463 The "pgp" method indicates the the certificates, the public key, and the 464 signature are in OpenPGP compatible binary format. [PGP] 465 5. Key Exchange 467 Key exchange begins by each side sending lists of supported algorithms. 468 Each side has a preferred algorithm in each category, and it is assumed 469 that most implementations at any given time will use the same preferred 470 algorithm. Each side MAY guess which algorithm the other side is using, 471 and MAY send an initial key exchange packet according to the algorithm 472 if appropriate for the preferred method. If all algorithms were guessed 473 right, the optimistically sent packet MUST be handled as the first key 474 exchange packet. However, if the guess was wrong, and a packet was 475 optimistically sent by one or both parties, such packets MUST be ignored 476 (even if the error in the guess would not affect the contents of the 477 initial packet(s)), and the appropriate side MUST send the correct 478 initial packet. 480 Server authentication in the key exchange MAY be implicit. After a key 481 exchange with implicit server authentication, the client MUST wait for 482 response to its service request message before sending any further data. 484 5.1. Algorithm Negotiation 486 Key exchange begins by each side sending the following packet: 488 byte SSH_MSG_KEXINIT 489 byte[16] cookie (random bytes) 490 string kex_algorithms 491 string server_host_key_algorithms 492 string encryption_algorithms_client_to_server 493 string encryption_algorithms_server_to_client 494 string mac_algorithms_client_to_server 495 string mac_algorithms_server_to_client 496 string compression_algorithms_client_to_server 497 string compression_algorithms_server_to_client 498 string languages_client_to_server 499 string languages_server_to_client 500 boolean first_kex_packet_follows 501 uint32 0 (reserved for future extension) 503 Each of the algorithm strings MUST be a comma-separated list of 504 algorithm names (see ``Algorithm Naming'' in [SSH-ARCH]). Each supported 505 (allowed) algorithm MUST be listed, in order of preference. 507 The first algorithm in each list MUST be the preferred (guessed) 508 algorithm. Each string MUST contain at least one algorithm name. 510 cookie 511 The cookie MUST be a random value generated by the sender. Its 512 purpose is to make it impossible for either side to fully 513 determine the keys and the session identifier. 515 kex_algorithms 516 Key exchange algorithms were defined above. The first algorithm 517 MUST be the preferred (and guessed) algorithm. If both sides make 518 the same guess, that algorithm MUST used. Otherwise, the 519 following algorithm MUST be used to choose a key exchange method: 520 iterate over client's kex algorithms, one at a time. Choose the 521 first algorithm that satisfies the following conditions: 523 o the server also supports the algorithm, 525 o if the algorithm requires an encryption-capable host key, there is 526 an encryption-capable algorithm on the server's 527 server_host_key_algorithms that is also supported by the client, 528 and 530 o if the algorithm requires a signature-capable host key, there is a 531 signature-capable algorithm on the server's 532 server_host_key_algorithms that is also supported by the client. 534 If no algorithm satisfying all these conditions can be found, the 535 connection fails, and both sides MUST disconnect. 537 server_host_key_algorithms 538 List of the algorithms supported for the server host key. The 539 server lists the algorithms for which it has host keys; the client 540 lists the algorithms that it is willing to accept. (There MAY be 541 multiple host keys for a host, possibly with different 542 algorithms.) 544 Some host keys may not support both signatures and encryption 545 (this can be determined from the algorithm), and thus not all host 546 keys are valid for all key exchange methods. 548 Algorithm selection depends on whether the chosen key exchange 549 algorithm requires a signature- or encryption capable host key. 550 It MUST be possible to determine this from the public key 551 algorithm name. The first algorithm on the client's list that 552 satisfies the requirements and is also supported by the server 553 MUST be chosen. If there is no such algorithm, both sides MUST 554 disconnect. 556 encryption_algorithms 557 Lists the acceptable symmetric encryption algorithms in order of 558 preference. The chosen encryption algorithm to each direction 559 MUST be the first algorithm on the client's list that is also on 560 the server's list. If there is no such algorithm, both sides MUST 561 disconnect. 563 Note that "none" must be explicitly listed if it is to be 564 acceptable. The defined algorithm names are listed in Section 565 ``Encryption''. 567 mac_algorithms 568 Lists the acceptable MAC algorithms in order of preference. The 569 chosen MAC algorithm MUST be the first algorithm on the client's 570 list that is also on the server's list. If there is no such 571 algorithm, both sides MUST disconnect. 573 Note that "none" must be explicitly listed if it is to be 574 acceptable. The MAC algorithm names are listed in Section ``Data 575 Integrity''. 577 compression_algorithms 578 Lists the acceptable compression algorithms in order of 579 preference. The chosen compression algorithm MUST be the first 580 algorithm on the client's list that is also on the server's list. 581 If there is no such algorithm, both sides MUST disconnect. 583 Note that "none" must be explicitly listed if it is to be 584 acceptable. The compression algorithm names are listed in Section 585 ``Compression''. 587 languages 588 This is a comma-separated list of language tags in order of 589 preference [RFC-1766]. Both parties MAY ignore this list. If there 590 are no language preferences, this list SHOULD be empty. 592 first_kex_packet_follows 593 Indicates whether a guessed key exchange packet follows. If a 594 guessed packet will be sent, this MUST be true. If no guessed 595 packet will be sent, this MUST be false. 597 After receiving the SSH_MSG_KEXINIT packet from the other side, 598 each party will know whether their guess was right. If the other 599 party's guess was wrong, and this field was true, the next packet 600 MUST be silently ignored, and both sides MUST then act as 601 determined by the negotiated key exchange method. If the guess 602 was right, key exchange MUST continue using the guessed packet. 604 After the KEXINIT packet exchange, the key exchange algorithm is run. 605 It may involve several packet exchanges, as specified by the key 606 exchange method. 608 5.2. Output from Key Exchange 610 The key exchange produces two values: a shared secret K, and an exchange 611 hash H. Encryption and authentication keys are derived from these. The 612 exchange hash H from the first key exchange is additionally used as the 613 session identifier, which is a unique identifier for this connection. 614 It is used by authentication methods as a part of the data that is 615 signed as a proof of possession of a private key. Once computed, the 616 session identifier is not changed, even if keys are later re-exchanged. 618 Each key exchange method specifies a hash function that is used in the 619 key exchange. The same hash algorithm MUST be used in key derivation. 620 Here, we'll call it HASH. 622 Encryption keys MUST be computed as HASH of a known value and K as 623 follows: 625 o Initial IV client to server: HASH(K || "A" || session_id) ("A" means 626 the single character A, ascii 65). 628 o Initial IV server to client: HASH(K || "B" || session_id) 630 o Encryption key client to server: HASH(K || "C" || session_id) 632 o Encryption key server to client: HASH(K || "D" || session_id) 634 o Integrity key client to server: HASH(K || "E" || session_id) 636 o Integrity key server to client: HASH(K || "F" || session_id) 638 Key data MUST be taken from the beginning of the hash output. 128 bits 639 (16 bytes) SHOULD be used for algorithms with variable-length keys. For 640 other algorithms, as many bytes as are needed are taken from the 641 beginning of the hash value. If the key length in longer than the output 642 of the HASH, the key is extended by computing HASH of the concatenation 643 of K and the entire key so far, and appending the resulting bytes (as 644 many as HASH generates) to the key. This process is repeated until 645 enough key material is available; the key is taken from the beginning of 646 this value. In other words, 648 K1 = HASH(K || X || session_id) (X is e.g. "A") 649 K2 = HASH(K || K1) 650 K3 = HASH(K || K1 || K2) 651 ... 652 key = K1 || K2 || K3 || ... 654 5.3. Taking Keys into Use 656 Key exchange ends by each side sending an SSH_MSG_NEWKEYS message. This 657 message is sent with the old keys and algorithms. All messages sent 658 after this message MUST use the new keys and algorithms. 660 When this message is received, the new keys and algorithms MUST be taken 661 into use for receiving. 663 This message is the only valid message after key exchange, in addition 664 to SSH_MSG_DEBUG, SSH_MSG_DISCONNECT and SSH_MSG_IGNORE messages. The 665 purpose of this message is to ensure that a party is able to respond 666 with a disconnect message that the other party can understand if 667 something goes wrong with the key exchange. Implementations MUST NOT 668 accept any other messages after key exchange before receiving 669 SSH_MSG_NEWKEYS. 671 byte SSH_MSG_NEWKEYS 673 6. Diffie-Hellman Key Exchange 675 The Diffie-Hellman key exchange provides a shared secret that can not be 676 determined by either party alone. The key exchange is combined with a 677 signature with the host key to provide host authentication. 679 In the following description (C is the client, S is the server; p is a 680 large safe prime, g is a generator for a subgroup of GF(p), and q is the 681 order of the subgroup; V_S is S's version string; V_C is C's version 682 string; K_S is S's public host key; I_C is C's KEXINIT message and I_S 683 S's KEXINIT message which have been exchanged before this part begins): 684 1. C generates a random number x (1 < x < q) and computes e = g^x mod p. 685 C sends "e" to S. 687 2. S generates a random number y (0 < y < q) and computes f = g^y mod p. 688 S receives "e". It computes K = e^y mod p, H = hash(V_C || V_S || 689 I_C || I_S || K_S || e || f || K), and signature s on H with its 690 private host key. S sends "K_S || f || s" to C. The signing 691 operation may involve a second hashing operation. 693 3. C verifies that K_S really is the host key for S (e.g. using 694 certificates or a local database). C is also allowed to accept the 695 key without verification; however, doing so will render the protocol 696 insecure against active attacks (but may be desirable for practical 697 reasons in the short term in many environments). C then computes K = 698 f^x mod p, H = hash(V_C || V_S || I_C || I_S || K_S || e || f || K), 699 and verifies the signature s on H. 701 Either side MUST NOT send or accept e or f values that are not in the 702 range [1, p-1]. If this condition is violated, the key exchange 703 fails. 705 This is implemented with the following messages. The hash algorithm for 706 computing the exchange hash is defined by the method name, and is called 707 HASH. The public key algorithm for signing is negotiated with the 708 KEXINIT messages. 710 First, the client sends: 712 byte SSH_MSG_KEXDH_INIT 713 mpint e 715 The server responds with: 717 byte SSH_MSG_KEXDH_REPLY 718 string server public host key and certificates (K_S) 719 mpint f 720 string signature of H 722 The hash H is computed as the HASH hash of the concatenation of the 723 following: 725 string V_C, the client's version string (CR and NL excluded) 726 string V_S, the server's version string (CR and NL excluded) 727 string I_C, the payload of the client's SSH_MSG_KEXINIT 728 string I_S, the payload of the server's SSH_MSG_KEXINIT 729 string K_S, the host key 730 mpint e, exchange value sent by the client 731 mpint f, exchange value sent by the server 732 mpint K, the shared secret 734 This value is called the exchange hash, and it is used to authenticate 735 the key exchange. 737 The signature algorithm MUST be applied over H, not the original data. 738 Most signature algorithms include hashing and additional padding. For 739 example, a "ssh-dss" specifies SHA-1 hashing; in that case, the data is 740 first hashed with HASH to compute H, and H is then hashed with SHA-1 as 741 part of the signing operation. 743 6.1. diffie-hellman-group1-sha1 745 The "diffie-hellman-group1-sha1" method specifies Diffie-Hellman key 746 exchange with SHA-1 as HASH, and the following group: 748 The prime p is equal to 2^1024 - 2^960 - 1 + 2^64 * floor( 2^894 Pi + 749 129093 ). Its hexadecimal value is 751 FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1 752 29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD 753 EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245 754 E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED 755 EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381 756 FFFFFFFF FFFFFFFF. 758 In decimal, this value is 760 179769313486231590770839156793787453197860296048756011706444 761 423684197180216158519368947833795864925541502180565485980503 762 646440548199239100050792877003355816639229553136239076508735 763 759914822574862575007425302077447712589550957937778424442426 764 617334727629299387668709205606050270810842907692932019128194 765 467627007. 767 The generator used with this prime is g = 2. The group order q is (p - 768 1) / 2. 770 This group was taken from the ISAKMP/Oakley specification, and was 771 originally generated by Richard Schroeppel at the University of Arizona. 772 Properties of this prime are described in [Orm96]. 774 7. Key Re-Exchange 776 Key re-exchange is started by sending a SSH_MSG_KEXINIT packet when not 777 already doing a key exchange (as described in Section ``Algorithm 778 Negotiation''). When this message is received, a party MUST respond 779 with its own SSH_MSG_KEXINIT message except when the received 780 SSH_MSG_KEXINIT already was a reply. Either party MAY initiate the re- 781 exchange, but roles MUST NOT be changed (i.e., the server remains the 782 server, and the client remains the client). 784 Key re-exchange is performed using whatever encryption was in effect 785 when the exchange was started. Encryption, compression, and MAC methods 786 are not changed before a new SSH_MSG_NEWKEYS is sent after the key 787 exchange (as in the initial key exchange). Re-exchange is processed 788 identically to the initial key exchange, except for the session 789 identifier that will remain unchanged. It is permissible to change some 790 or all of the algorithms during the re-exchange. Host keys can also 791 change. All keys and initialization vectors are recomputed after the 792 exchange. Compression and encryption contexts are reset. 794 It is recommended that the keys are changed after each gigabyte of 795 transmitted data or after each hour of connection time, whichever comes 796 sooner. However, since the re-exchange is a public key operation, it 797 requires a fair amount of processing power and should not be performed 798 too often. 800 More application data may be sent after the SSH_MSG_NEWKEYS packet has 801 been sent; key exchange does not affect the protocols that lie above the 802 SSH transport layer. 804 8. Service Request 806 After the key exchange, the client requests a service. The service is 807 identified by a name. The format of names and procedures for defining 808 new names are defined in [SSH-ARCH]. 810 Currently, the following names have been reserved: 812 ssh-userauth 813 ssh-connection 815 Similar local naming policy is applied to the service names that is 816 applied to the algorithm names; a local service should use the 817 servicename@domain syntax. 819 byte SSH_MSG_SERVICE_REQUEST 820 string service name 822 If the server rejects the service request, it SHOULD send an appropriate 823 SSH_MSG_DISCONNECT message and MUST disconnect. 825 When the service starts, it may have access to the session identifier 826 generated during the key exchange. 828 If the server supports the service (and permits the client to use it), 829 it MUST respond with 830 byte SSH_MSG_SERVICE_ACCEPT 831 string service name 833 Message numbers used by services should be in the area reserved for them 834 (see Section ``Summary of Message Numbers''). The transport level will 835 continue to process its own messages. 837 Note that after a key exchange with implicit server authentication, the 838 client MUST wait for response to its service request message before 839 sending any further data. 841 9. Additional Messages 843 Either party may send any of the following messages at any time. 845 9.1. Disconnection Message 847 byte SSH_MSG_DISCONNECT 848 uint32 reason code 849 string description [RFC-2044] 850 string language tag [RFC-1766] 852 This message causes immediate termination of the connection. All 853 implementations MUST be able to process this message; they SHOULD be 854 able to send this message. 856 The sender MUST NOT send or receive any data after this message, and the 857 recipient MUST NOT accept any data after receiving this message. The 858 description field gives a more specific explanation in a human-readable 859 form. The error code gives the reason in a more machine-readable format 860 (suitable for localization), and can have the following values: 862 #define SSH_DISCONNECT_HOST_NOT_ALLOWED_TO_CONNECT 1 863 #define SSH_DISCONNECT_PROTOCOL_ERROR 2 864 #define SSH_DISCONNECT_KEY_EXCHANGE_FAILED 3 865 #define SSH_DISCONNECT_HOST_AUTHENTICATION_FAILED 4 866 #define SSH_DISCONNECT_MAC_ERROR 5 867 #define SSH_DISCONNECT_COMPRESSION_ERROR 6 868 #define SSH_DISCONNECT_SERVICE_NOT_AVAILABLE 7 869 #define SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED 8 870 #define SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE 9 871 #define SSH_DISCONNECT_CONNECTION_LOST 10 872 #define SSH_DISCONNECT_BY_APPLICATION 11 874 If the description string is displayed, control character filtering 875 discussed in [SSH-ARCH] should be used to avoid attacks by sending 876 terminal control characters. 878 9.2. Ignored Data Message 880 byte SSH_MSG_IGNORE 881 string data 883 All implementations MUST understand (and ignore) this message at any 884 time (after receiving the protocol version). No implementation is 885 required to send them. This message can be used as an additional 886 protection measure against advanced traffic analysis techniques. 888 9.3. Debug Message 890 byte SSH_MSG_DEBUG 891 boolean always_display 892 string message [RFC-2044] 893 string language tag [RFC-1766] 895 All implementations MUST understand this message, but they are allowed 896 to ignore it. This message is used to pass information to the other 897 side that may help debugging. If always_display is true, the message 898 SHOULD be displayed. Otherwise, it SHOULD NOT be displayed unless 899 debugging information has been explicitly requested by the user. 901 The message doesn't need to contain a newline. It is, however, allowed 902 to consist of multiple lines separated by CRLF (carriage return - line 903 feed) pairs. 905 If the message string is displayed, terminal control character filtering 906 discussed in [SSH-ARCH] should be used to avoid attacks by sending 907 terminal control characters. 909 9.4. Reserved Messages 911 An implementation MUST respond to all unrecognized messages with an 912 SSH_MSG_UNIMPLEMENTED message in the order in which they were received. 913 Such messages MUST be otherwise ignored. Later protocol versions may 914 define other meanings for these message types. 916 byte SSH_MSG_UNIMPLEMENTED 917 uint32 packet sequence number of rejected message 919 10. Summary of Message Numbers 921 The following message numbers have been defined in this protocol. 923 #define SSH_MSG_DISCONNECT 1 924 #define SSH_MSG_IGNORE 2 925 #define SSH_MSG_UNIMPLEMENTED 3 926 #define SSH_MSG_DEBUG 4 927 #define SSH_MSG_SERVICE_REQUEST 5 928 #define SSH_MSG_SERVICE_ACCEPT 6 930 #define SSH_MSG_KEXINIT 20 931 #define SSH_MSG_NEWKEYS 21 933 /* Numbers 30-49 used for kex packets. 934 Different kex methods may reuse message numbers in 935 this range. */ 936 #define SSH_MSG_KEXDH_INIT 30 937 #define SSH_MSG_KEXDH_REPLY 31 939 11. Security Considerations 941 This protocol provides a secure encrypted channel over an unsecure 942 network. It performs server host authentication, key exchange, 943 encryption, and integrity protection. It also derives a unique session 944 id that may be used by higher-level protocols. 946 It is expected that this protocol will sometimes be used without 947 insisting on reliable association between the server host key and the 948 server host name. Such use is inherently insecure, but may be necessary 949 in non-security critical environments, and still provides protection 950 against passive attacks. However, implementors of protocols running on 951 top of this protocol should keep this possibility in mind. 953 This protocol is designed to be used over a reliable transport. If 954 transmission errors or message manipulation occur, the connection is 955 closed. The connection SHOULD be re-established if this occurs. Denial 956 of service attacks of this type ("wire cutter") are almost impossible to 957 avoid. 959 12. References 961 [FIPS-186] Federal Information Processing Standards Publication (FIPS 962 PUB) 186, Digital Signature Standard, 18 May 1994. 964 [Orm96] Orman, H., "The Oakley Key Determination Protocol", version 1, 965 TR97-92, Department of Computer Science Technical Report, University of 966 Arizona. 968 [RFC-1034] Mockapetris, P., "Domain Names - Concepts and Facilities", 969 November 1987. 971 [RFC-1766] Alvestrand, H., "Tags for the Identification of Languages", 972 March 1995. 974 [RFC-1950] Deutch, P. and Gailly, J-L., "ZLIB Compressed Data Format 975 Specification version 3.3", May 1996. 977 [RFC-1951] Deutch, P., "DEFLATE Compressed Data Format Specification 978 version 1.3", May 1996. 980 [RFC-2044] Yergeau, F., "UTF-8, a Transformation Format of Unicode and 981 ISO 10646", October 1996. 983 [RFC-2104] Krawczyk, H., Bellare, M., and Canetti, R., "HMAC: Keyed- 984 Hashing for Message Authentication", February 1997 986 [RFC-2119] Bradner, S., "Key words for use in RFCs to indicate 987 Requirement Levels", March 1997. 989 [RFC-2144] Adams, C., "The CAST-128 Encryption Algorithm", May 1997. 991 [Schneier] Schneier, B., "Applied Cryptography Second Edition: 992 protocols, algorithms, and source code in C", 2nd edition, John Wiley & 993 Sons, New York, NY, 1996. 995 [SSH-ARCH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Protocol 996 Architecture", Internet Draft, draft-ietf-secsh-architecture-00.txt 997 #91;SSH-USERAUTH] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH 998 Authentication Protocol", Internet Draft, draft-ietf-secsh- 999 userauth-02.txt 1001 [SSH-CONNECT] Ylonen, T., Kivinen, T, and Saarinen, M., "SSH Connection 1002 Protocol", Internet Draft, draft-ietf-secsh-connect-02.txt 1004 [PGP] (XXX n.a.) 1006 [PKIX-Part1] (XXX n.a.) 1008 13. Authors' Addresses 1010 Tatu Ylonen 1011 SSH Communications Security Ltd. 1012 Tekniikantie 12 1013 FIN-02150 ESPOO 1014 Finland 1015 E-mail: ylo@ssh.fi 1017 Tero Kivinen 1018 SSH Communications Security Ltd. 1019 Tekniikantie 12 1020 FIN-02150 ESPOO 1021 Finland 1022 E-mail: kivinen@ssh.fi 1024 Markku-Juhani O. Saarinen 1025 SSH Communications Security Ltd. 1026 Tekniikantie 12 1027 FIN-02150 ESPOO 1028 Finland 1029 E-mail: mjos@ssh.fi 1031 Timo J. Rinne 1032 SSH Communications Security Ltd. 1033 Tekniikantie 12 1034 FIN-02150 ESPOO 1035 Finland 1036 E-mail: tri@ssh.fi 1038 Sami Lehtinen 1039 SSH Communications Security Ltd. 1040 Tekniikantie 12 1041 FIN-02150 ESPOO 1042 Finland 1043 E-mail: sjl@ssh.fi