idnits 2.17.1 draft-bider-ssh-quic-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. ** The abstract seems to contain references ([QUIC], [RFC4251]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 407 has weird spacing: '...ort-str clie...' == Line 408 has weird spacing: '...ort-str serv...' == Line 418 has weird spacing: '...ort-str trus...' == Line 422 has weird spacing: '...ort-str clie...' == Line 427 has weird spacing: '...ort-str quic...' == (21 more instances...) -- The document date (12 August 2020) is 1353 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '16' on line 190 -- Looks like a reference, but probably isn't: '8' on line 915 == Unused Reference: 'RFC4250' is defined on line 1513, but no explicit reference was found in the text == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-29 Summary: 2 errors (**), 0 flaws (~~), 9 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force d. bider 3 Internet-Draft Bitvise Limited 4 Intended status: Informational 12 August 2020 5 Expires: 13 February 2021 7 QUIC-based UDP Transport for Secure Shell (SSH) 8 draft-bider-ssh-quic-08 10 Abstract 12 The Secure Shell protocol (SSH) [RFC4251] is widely used for purposes 13 including secure remote administration, file transfer using SFTP and 14 SCP, and encrypted tunneling of TCP connections. Because it is based 15 on TCP, SSH suffers similar problems as motivate the HTTP protocol to 16 transition to UDP-based QUIC [QUIC]. These include: unauthenticated 17 network intermediaries can trivially disconnect SSH sessions; SSH 18 connections are lost when mobile clients change IP addresses; 19 performance limitations in OS-based TCP stacks; many round-trips to 20 establish a connection; duplicate flow control on the level of the 21 connection as well as channels. This memo specifies SSH key exchange 22 over UDP and leverages QUIC to provide a UDP-based transport. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on 13 February 2021. 41 Copyright Notice 43 Copyright (c) 2020 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 48 license-info) in effect on the date of publication of this document. 49 Please review these documents carefully, as they describe your rights 50 and restrictions with respect to this document. Code Components 51 extracted from this document must include Simplified BSD License text 52 as described in Section 4.e of the Trust Legal Provisions and are 53 provided without warranty as described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Requirements Terminology . . . . . . . . . . . . . . . . 3 59 2. SSH/QUIC key exchange . . . . . . . . . . . . . . . . . . . . 3 60 2.1. Distinguishing SSH key exchange from QUIC datagrams . . . 3 61 2.2. Wire Encoding . . . . . . . . . . . . . . . . . . . . . . 4 62 2.3. Obfuscated Envelope . . . . . . . . . . . . . . . . . . . 4 63 2.3.1. Obfuscation Keyword . . . . . . . . . . . . . . . . . 5 64 2.4. Packet Size Limits . . . . . . . . . . . . . . . . . . . 6 65 2.5. Required QUIC Versions and TLS Cipher Suites . . . . . . 6 66 2.6. Random Elements . . . . . . . . . . . . . . . . . . . . . 6 67 2.7. Errors in Key Exchange . . . . . . . . . . . . . . . . . 8 68 2.7.1. "disc-reason" Extension Pair . . . . . . . . . . . . 8 69 2.7.2. "err-desc" Extension Pair . . . . . . . . . . . . . . 8 70 2.8. SSH_QUIC_INIT . . . . . . . . . . . . . . . . . . . . . . 9 71 2.8.1. Extensibility . . . . . . . . . . . . . . . . . . . . 13 72 2.9. SSH_QUIC_REPLY . . . . . . . . . . . . . . . . . . . . . 14 73 2.9.1. Error Reply . . . . . . . . . . . . . . . . . . . . . 17 74 2.9.2. Extensibility . . . . . . . . . . . . . . . . . . . . 17 75 2.10. SSH_QUIC_CANCEL . . . . . . . . . . . . . . . . . . . . . 19 76 2.10.1. Extensibility . . . . . . . . . . . . . . . . . . . 19 77 3. Key Exchange Methods . . . . . . . . . . . . . . . . . . . . 20 78 3.1. Required Key Exchange Methods . . . . . . . . . . . . . . 21 79 3.2. Example 1: "curve25519-sha256" . . . . . . . . . . . . . 22 80 3.3. Example 2: "diffie-hellman-group14-sha256" . . . . . . . 22 81 4. SSH_MSG_EXT_INFO and the SSH Version String . . . . . . . . . 23 82 4.1. "ssh-version" . . . . . . . . . . . . . . . . . . . . . . 24 83 4.2. "no-flow-control" . . . . . . . . . . . . . . . . . . . . 24 84 4.3. "delay-compression" . . . . . . . . . . . . . . . . . . . 24 85 5. QUIC Session Setup . . . . . . . . . . . . . . . . . . . . . 25 86 5.1. Shared Secrets . . . . . . . . . . . . . . . . . . . . . 25 87 6. Adaptation of SSH to QUIC Streams . . . . . . . . . . . . . . 26 88 6.1. SSH/QUIC Packet Format . . . . . . . . . . . . . . . . . 26 89 6.1.1. Compression . . . . . . . . . . . . . . . . . . . . . 26 90 6.2. Use of QUIC Streams . . . . . . . . . . . . . . . . . . . 27 91 6.3. Packet Sequence Numbers . . . . . . . . . . . . . . . . . 27 92 6.4. Channel IDs . . . . . . . . . . . . . . . . . . . . . . . 27 93 6.5. Disconnection . . . . . . . . . . . . . . . . . . . . . . 28 94 6.6. Prohibited SSH Packets . . . . . . . . . . . . . . . . . 28 95 6.7. Global SSH Packets . . . . . . . . . . . . . . . . . . . 28 96 6.8. SSH Channel Packets . . . . . . . . . . . . . . . . . . . 29 97 6.9. Closing a Channel . . . . . . . . . . . . . . . . . . . . 31 98 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 31 99 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 100 9. Security Considerations . . . . . . . . . . . . . . . . . . . 32 101 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 32 102 10.1. Normative References . . . . . . . . . . . . . . . . . . 32 103 10.2. Informative References . . . . . . . . . . . . . . . . . 33 104 Appendix A. Generating Random Lengths . . . . . . . . . . . . . 34 105 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 34 107 1. Introduction 109 THIS DOCUMENT IS AN EARLY VERSION AND IS A WORK IN PROGRESS. 111 NON-LATEST DRAFT VERSIONS MUST BE DISREGARDED. 113 IMPLEMENTATION AT THIS STAGE IS EXPERIMENTAL. 115 CONTACT THE AUTHOR IF YOU INTEND TO IMPLEMENT. 117 This memo specifies SSH key exchange over UDP, and then leverages 118 QUIC to provide a UDP-based transport for SSH. QUIC's use of the TLS 119 handshake is replaced with a one-roundtrip SSH/QUIC key exchange. 120 The SSH Authentication Protocol [RFC4252] is then conducted over QUIC 121 stream 0, and the SSH Connection Protocol [RFC4254] is modified to 122 use QUIC streams. 124 1.1. Requirements Terminology 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 128 "OPTIONAL" in this document are to be interpreted as described in 129 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 130 capitals, as shown here. 132 2. SSH/QUIC key exchange 134 2.1. Distinguishing SSH key exchange from QUIC datagrams 136 UDP datagrams which form the SSH/QUIC key exchange are sent between 137 the same client and server IP addresses and ports as QUIC datagrams. 138 It is therefore necessary for clients and servers to distinguish SSH 139 key exchange datagrams from QUIC datagrams. 141 A distinction is allowed by that SSH/QUIC only requires the sending 142 of QUIC Short Header Packets. Therefore, all UDP datagrams where the 143 first byte has its high bit set MUST be handled as part of an SSH/ 144 QUIC key exchange. 146 2.2. Wire Encoding 148 This memo uses wire encoding types "byte", "uint32", "uint64", 149 "mpint" and "string" with meanings as described in [RFC4251]. 151 This memo defines the following new wire encoding type. 153 "short-str" is a shorter version of "string", encoded as follows: 155 byte n = short-str-len (unsigned, 0..255) 156 byte[n] short-str-value 158 Figure 1 160 2.3. Obfuscated Envelope 162 Since SSH servers are commonly used for remote administration, they 163 are a high-value target for password guessing. One of the most 164 common complaints from SSH server administrators is the high 165 frequency of password guessing connections from random clients. 167 Experience shows that obfuscating the SSH protocol with an 168 obfuscation keyword is a valuable measure which thwarts password 169 guessing. This increases practical security of the SSH ecosystem 170 even if obfuscation does not thwart narrowly targeted attacks. 172 Every SSH/QUIC connection is parameterized by an obfuscation keyword. 173 The obfuscation keyword is processed according to Section 2.3.1. 175 An SSH/QUIC server SHOULD allow the administrator to configure an 176 obfuscation keyword for each interface and port on which the server 177 is accepting SSH/QUIC connections. An SSH/QUIC client MUST allow the 178 user to configure an obfuscation keyword separately for outgoing 179 connections to each server address and port. 181 The obfuscation keyword MUST be optional for users to configure. If 182 a user does not configure it, the obfuscated envelope is applied as 183 if the obfuscation keyword was an empty character sequence. 185 All SSH/QUIC key exchange packets are sent as UDP datagrams in the 186 following obfuscated envelope: 188 byte[16] obfs-nonce - high bit of first byte MUST be set 189 byte[] obfs-payload 190 byte[16] obfs-tag 192 Figure 2 194 The field "obfs-nonce" contains random bytes generated by the sender 195 of the UDP datagram. The high bit of the first byte of "obfs-nonce" 196 MUST be set to distinguish the packet from QUIC datagrams. See 197 Section 2.1. 199 The field "obfs-payload" contains the SSH/QUIC key exchange packet 200 encrypted using AEAD_AES_256_GCM [RFC5116]. The AEAD is invoked as 201 follows: 203 * The secret key K is a SHA-256 digest of the obfuscation keyword, 204 processed according to Section 2.3.1. 206 * The nonce N is the field "obfs-nonce". 208 * The plaintext P is the unencrypted packet payload. 210 * Associated data A is empty. 212 * The ciphertext C is stored in "obfs-payload". 214 The length of encrypted "obfs-payload" is implied by the UDP datagram 215 length, and is calculated by subtracting the fixed lengths of "obfs- 216 nonce" and "obfs-tag". 218 The field "obfs-tag" stores the GCM tag. Receivers MUST check the 219 tag and MUST ignore datagrams where the GCM tag is invalid. 221 2.3.1. Obfuscation Keyword 223 The obfuscation keyword is a sequence of Unicode code points entered 224 by a user. Applications MUST permit users to enter any Unicode 225 string allowed by the FreeformClass string class defined in 226 [RFC8264]. 228 Before calculating the digest of the obfuscation keyword, 229 applications MUST process the obfuscation keyword as follows: 231 1. Process the input according to the OpaqueString profile defined 232 in [RFC8265]. 234 2. Remove any leading and trailing sequences consisting only of 235 characters CHARACTER TABULATION (U+0009), LINE FEED (U+000A), 236 CARRIAGE RETURN (U+000D) and/or SPACE (U+0020). This minimizes 237 user copy-and-paste errors, where the user is likely to copy 238 leading and trailing whitespace which is not part of the 239 obfuscation keyword. Note that the previous step, the 240 OpaqueString profile, already converted any non-ASCII whitespace 241 to SPACE (U+0020). 243 3. Encode the result as a sequence of bytes using UTF-8. 245 2.4. Packet Size Limits 247 Clients and servers MUST accept SSH_QUIC_INIT, SSH_QUIC_REPLY and 248 SSH_QUIC_CANCEL packets with unencrypted "obfs-payload" sizes at 249 least up to 32768 bytes. This corresponds to minimum SSH packet size 250 limits which implementations must support as per [RFC4253], 251 Section 6.1. 253 2.5. Required QUIC Versions and TLS Cipher Suites 255 Clients and servers are REQUIRED to implement QUIC protocol version 1 256 once it is standardized in [QUIC] and [QUIC-TLS]. 258 Clients and servers are REQUIRED to implement the TLS cipher suites 259 TLS_AES_128_GCM_SHA256 and TLS_AES_256_GCM_SHA384 [RFC8446]. Other 260 cipher suites are optional. 262 The requirement to implement any particular QUIC protocol version or 263 TLS cipher suite expires on the 5-year anniversary of the publishing 264 of this memo. At that point, implementers SHOULD consult any new 265 standards documents if available, or survey the practical use of SSH/ 266 QUIC for implementation guidance. 268 2.6. Random Elements 270 Unlike SSH over TCP, the packets SSH_QUIC_INIT and SSH_QUIC_REPLY do 271 not provide a "cookie" field for random data. Instead, clients and 272 servers MUST insert random data using the extensibility mechanisms 273 described for each SSH key exchange packet. 275 At the very minimum, clients and servers MUST insert at least 16 276 Random Bytes or at least one Random Name, in locations as described 277 for SSH_QUIC_INIT (Section 2.8.1) and SSH_QUIC_REPLY (Section 2.9.2). 278 If at all possible, the random data MUST come from a 279 cryptographically strong random source. Implementations that are 280 unable to meet this requirement MUST still insert the minimum amount 281 of random data, as unpredictably as they are able. Compromising on 282 this requirement reduces the security of any sessions created on the 283 basis of such SSH_QUIC_INIT and SSH_QUIC_REPLY. 285 Lengths of Random Names and Random Bytes SHOULD be chosen at random 286 such that lengths in the shorter end of the range are significantly 287 more probable, but long lengths are still selected. See Appendix A. 289 Random Bytes 291 Random Bytes are generated with values 0..255, in a range of lengths 292 as specified for the particular usage context. 294 Random Name 296 A Random Name is generated in one of two forms: Assigned Form or 297 Private Form. One of the two forms is randomly chosen so that 298 Assigned Form, which is shorter, is more likely. The maximum length 299 of a Random Name is 64 bytes. 301 Assigned Form 303 A Random Name in Assigned Form is generated as a string of random 304 characters with ASCII values 33..126 (inclusive), except @ and the 305 comma (","). Other characters MUST NOT be included. To avoid 306 collisions as effectively as a random UUID, a Random Name in Assigned 307 Form MUST contain at least 20 random characters if using the complete 308 character set. A Random Name in Assigned Form MUST then be of length 309 20..64 bytes. 311 Implementations MAY remove up to 7 characters from the character set 312 -- reducing it to 85..91 characters -- without increasing the minimum 313 length. If the character set is further reduced to 69..84 314 characters, implementations MUST generate at least 21 random 315 characters instead. 317 Example Random Names in Assigned Form: 319 d`kbi>AGrj~r{3lo_Q4r 320 wNT)=/8C<(DB1|tr:>1f[xq>9bG 321 u7^dE'\EE_}N}^"J5syI?/8jIxup#s7BM:]>{IT_p3Z~wJDYIBX.4zzQ$@denisbider.com 335 ?`z4bb/}&Wuf6O7CE?cA`$j"@bider.us 336 Figure 4 338 Alternately, implementations MAY generate a Random Name in Anonymous 339 Form with the format "(local)@(domain).example.com". In this case, 340 both "(local)" and "(domain)" are replaced by random ASCII characters 341 from the set A..Z, a..z, and 0..9. This is to ensure that the suffix 342 has valid domain name syntax. 344 To avoid collisions as effectively as a random UUID, a Random Name in 345 Anonymous Form MUST contain at least 22 random characters. A Random 346 Name in Anonymous Form MUST then be of length 35..64 bytes. 348 2.7. Errors in Key Exchange 350 To assist users, clients and servers SHOULD report key exchange 351 errors as follows: 353 1. If a server cannot send a successful SSH_QUIC_REPLY, it SHOULD 354 send an Error Reply. See Section 2.9.1. 356 2. If a client receives an invalid SSH_QUIC_REPLY, it SHOULD send an 357 SSH_QUIC_CANCEL. See Section 2.10. 359 Both packet types use the following extension pairs. 361 2.7.1. "disc-reason" Extension Pair 363 "ext-pair-name" contains "disc-reason". 365 "ext-pair-data" encodes a uint32 with the SSH disconnect reason code. 366 Reason codes are defined in the table "Disconnect Messages Reason 367 Codes and Descriptions" in the IANA registry "Secure Shell (SSH) 368 Protocol Parameters" [IANA-SSH]. 370 2.7.2. "err-desc" Extension Pair 372 "ext-pair-name" contains "err-desc". 374 "ext-pair-data" encodes a human-readable error description in any 375 language intended to be relevant to the user, encoded as UTF-8. 377 Receivers that process error descriptions MUST validate that the 378 description is valid UTF-8. If a description is long, receivers 379 SHOULD truncate it to a reasonable length depending on the processing 380 context. For example, a debug log file can record a full 32 kB error 381 description, while a production log file SHOULD truncate it to a much 382 shorter length. 384 2.8. SSH_QUIC_INIT 386 A client begins an SSH/QUIC session by sending one or more copies of 387 SSH_QUIC_INIT. If multiple copies are sent, copies intended for the 388 same connection MUST be identical. A reasonable strategy is to send 389 one copy every 50 - 500 ms until the client receives a valid 390 SSH_QUIC_REPLY or times out. A server MUST remember recently 391 received SSH_QUIC_INIT packets and send identical SSH_QUIC_REPLY 392 responses. If different SSH_QUIC_INIT packets are received from the 393 same client IP address, the server MUST assume they are intended to 394 begin separate connections, even if they specify the same "client- 395 connection-id". A server MAY implement throttling of incoming 396 connections, by IP address or otherwise, where excessive 397 SSH_QUIC_INIT packets are disregarded. Once a server receives QUIC 398 data confirming that a client has processed an SSH_QUIC_REPLY, the 399 server MUST disregard any further identical copies of the same 400 SSH_QUIC_INIT, at least until the SSH/QUIC session started by such an 401 SSH_QUIC_INIT ends. 403 SSH_QUIC_INIT is an obfuscated datagram (Section 2.3) where "obfs- 404 payload" encrypts the following: 406 byte SSH_QUIC_INIT = 1 (see Extensibility) 407 short-str client-connection-id (MAY be empty) 408 short-str server-name-indication (MAY be empty) 410 byte v = nr-quic-versions (MUST NOT be zero) 411 uint32[v] client-quic-versions 412 string client-quic-trnsp-params 414 string client-sig-algs (MUST NOT be empty) 416 byte f = nr-trusted-fingerprints (MAY be zero) 417 the following 1 field repeated f times: 418 short-str trusted-fingerprint (MUST NOT be empty) 420 byte k = nr-client-kex-algs (MUST NOT be zero) 421 the following 2 fields repeated k times: 422 short-str client-kex-alg-name (MUST NOT be empty) 423 string client-kex-alg-data (MUST NOT be empty) 425 byte c = nr-cipher-suites (MUST NOT be zero) 426 the following 1 field repeated c times: 427 short-str quic-tls-cipher-suite 429 byte e = nr-ext-pairs (see Extensibility) 430 the following 2 fields repeated e times: 431 short-str ext-pair-name (MUST NOT be empty) 432 string ext-pair-data (MAY be empty) 434 byte[0..] padding: all 0xFF to minimal obfs-payload size 1200 436 Figure 5 438 SSH_QUIC_INIT does not include an SSH version string or compression 439 negotiation. Instead, clients MUST use SSH_MSG_EXT_INFO for these 440 purposes. See Section 4. 442 SSH_QUIC_INIT does not include a "cookie" field for random data. 443 Clients MUST insert random data using the packet's extensibility 444 mechanisms. See Section 2.8.1 and Section 2.6. 446 The field "client-connection-id" contains a QUIC Connection ID of 447 length 0..20 bytes. The server will use this as the QUIC Destination 448 Connection ID in QUIC packets sent to the client. Clients MAY send 449 an empty Connection ID if they are using other means of routing 450 connections. 452 The field "server-name-indication" SHOULD contain the server DNS name 453 if a DNS name was entered by the user when configuring the 454 connection. This can be invaluable in hosting environments: it 455 allows servers to expose to clients multiple distinct identities on 456 the same network address and port. If non-empty, the field MUST 457 encode the DNS name entered by the user as a string consisting of 458 printable US-ASCII characters. Internationalized domain names MUST 459 be represented in their US-ASCII encoding. If the user connected 460 directly to an IP address, this field MUST be empty. This avoids 461 disclosing private information in case of port forwarded connections. 462 Example non-empty values: 464 localhost 465 server.example.com 466 xn--bcher-kva.example 468 Figure 6 470 The fields "client-quic-versions" enumerate QUIC protocol versions 471 supported by the client. The client MUST send at least one version. 472 The client MUST send supported versions in the order it prefers the 473 server to use them. 475 The field "client-quic-trnsp-params" encodes the client's QUIC 476 Transport Parameters as defined in [QUIC]. 478 The field "client-sig-algs" MUST contain at least one signature 479 algorithm supported by the client for server authentication. These 480 are the same algorithms as used in SSH_MSG_KEXINIT ([RFC4253], 481 Section 7.1) in the field "server_host_key_algorithms". The client 482 MUST send signature algorithms in the order it prefers the server to 483 use them. 485 The client SHOULD include algorithms in "client-sig-algs" as follows: 487 * If the client does not yet trust any host key for the server: 488 "client-sig-algs" SHOULD include all signature algorithms 489 supported and enabled by the client for use with any server. 491 * Otherwise, the client already trusts some host keys for the 492 server. In this case, if the client sends any "trusted- 493 fingerprint" fields, then "client-sig-algs" SHOULD include all 494 signature algorithms supported and enabled by the client for use 495 with any server. 497 * Otherwise, the client already trusts some host keys for the 498 server, but does not send any "trusted-fingerprint" fields. In 499 this case, "client-sig-algs" MUST include only signature 500 algorithms associated with the host keys the client already trusts 501 for this server. 503 There MAY be zero or more "trusted-fingerprint" fields. Each 504 "trusted-fingerprint" contains a binary fingerprint of a host key 505 that is trusted for this connection by the client. The fingerprint 506 algorithm is left unspecified. The server SHOULD try to match the 507 fingerprint using all algorithms it supports which produce the 508 provided fingerprint size. The current recommended fingerprint 509 algorithm is SHA-256, with fingerprint size 32 bytes. Servers MUST 510 tolerate the presence of unrecognized fingerprints of any size. The 511 preference order of trusted fingerprints is dominated by the 512 preference order of algorithms in "client-sig-algs". 514 The packet MUST include at least one SSH key exchange algorithm, 515 encoded as a pair of "client-kex-alg-name" and "client-kex-alg-data" 516 fields. The field "client-kex-alg-name" MUST specify a key exchange 517 method which would be valid in the field "kex_algorithms" in 518 SSH_MSG_KEXINIT under [RFC4253], Section 7.1. In addition, the key 519 exchange method MUST meet criteria in Section 3. 521 If the client wishes to simply advertise its support for a particular 522 key exchange algorithm, but does not prefer to use it in this 523 connection, it MAY enumerate the algorithm with empty "client-kex- 524 alg-data". Otherwise, if the client wishes to allow the algorithm to 525 be used, it MUST include non-empty "client-kex-alg-data". In this 526 case, "client-kex-alg-data" contains the client's portion of key 527 exchange inputs as specified in Section 3. The client MAY send 528 multiple key exchange algorithms with filled-out "client-kex-alg- 529 data". The client MUST send these algorithms in the order it prefers 530 the server to use them. 532 There MUST be at least one "quic-tls-cipher-suite" field. Each of 533 these specifies a TLS cipher suite ([RFC8446], Appendix B.4) which is 534 supported by the client, and which can be used with a version of QUIC 535 ([QUIC], [QUIC-TLS]) supported by the client. The client MUST 536 enumerate supported cipher suites in the order it prefers the server 537 to use them. 539 The client MAY send any number of extensions, encoded as a pair of 540 "ext-pair-name" and "ext-pair-data" fields. This memo defines no 541 extensions for SSH_QUIC_INIT, but see Section 2.8.1. 543 The "padding" field contains all 0xFF bytes to ensure that the 544 unencrypted "obfs-payload" for SSH_QUIC_INIT is at least 1200 bytes 545 in length. Servers MUST ignore smaller SSH_QUIC_INIT packets. This 546 is REQUIRED to prevent abuse of SSH_QUIC_INIT for Amplified 547 Reflection DDoS. If the unencrypted size of "obfs-payload" is 548 already 1200 bytes or larger, the padding MAY be omitted. 550 2.8.1. Extensibility 552 Implementations MUST allow room for future extensibility of 553 SSH_QUIC_INIT in the following manners: 555 1. By using a different packet type in the first byte -- this is, a 556 value other than 1 used by SSH_QUIC_INIT. Servers MUST NOT 557 penalize clients for sending unknown packet types unless there is 558 another reason to penalize the client, such as a blocked IP 559 address or the sheer volume of datagrams. 561 2. By including algorithms in "client-sig-algs" which are unknown to 562 or not supported by the server. Servers MUST tolerate the 563 presence of such algorithms. 565 3. By including fingerprints in "trusted-fingerprints" that use 566 algorithms or lengths that are unknown to or not supported by the 567 server. Servers MUST tolerate the presence of such fingerprints. 569 4. By including SSH key exchange algorithms which are unknown to or 570 not supported by the server, with algorithm data in a format 571 that's unknown to or not supported by the server. Servers MUST 572 tolerate the presence of such algorithms and their data. 574 5. By including QUIC TLS cipher suites which are unknown to or not 575 supported by the server. Servers MUST tolerate the presence of 576 such cipher suites. 578 6. By including extensions which are unknown to or not supported by 579 the server, with extension data in a format that's unknown to or 580 not supported by the server. Servers MUST tolerate the presence 581 of such extensions and their data. 583 Experience shows that any extensibility which is not actively 584 exercised is lost due to implementations that lock down expectations 585 incorrectly. Therefore, all clients MUST do at least one of the 586 following, in each SSH_QUIC_INIT packet, at random: 588 1. In the field "client-sig-algs", include in a random position at 589 least one Random Name (Section 2.6). 591 2. In the fields "client-quic-versions", include in a random 592 position a version number of the form 0x0A?A?A?A, where ? 593 indicates a random nibble. See [QUIC], section "Versions". Note 594 the difference from the random version pattern in the server's 595 SSH_QUIC_REPLY. Due to the minimal amount of entropy provided by 596 this rule, this MUST NOT be the only insertion of randomness made 597 in a packet. 599 3. Include in a random position at least one host key fingerprint 600 consisting of 16..255 Random Bytes (Section 2.6). 602 4. Include in a random position at least one SSH key exchange 603 algorithm where the field "client-kex-alg-name" contains a Random 604 Name, and the field "client-kex-alg-data" contains 0..1000 Random 605 Bytes. 607 5. In the fields "quic-tls-cipher-suite", include in a random 608 position at least one entry consisting of 16..255 Random Bytes. 610 6. In extension pairs, include in a random position at least one 611 extension where the field "ext-pair-name" contains a Random Name, 612 and the field "ext-pair-value" contains 0..1000 Random Bytes. 614 2.9. SSH_QUIC_REPLY 616 Implementations MUST take care to prevent abuse of the SSH/QUIC key 617 exchange for Amplified Reflection DDoS attacks. This means: 619 1. A server MUST NOT send more than one SSH_QUIC_REPLY in response 620 to any individual SSH_QUIC_INIT. 622 2. A server MUST NOT respond to any SSH_QUIC_INIT with unencrypted 623 "obfs-payload" smaller than 1200 bytes. 625 3. Before sending an SSH_QUIC_REPLY, the server MUST verify that the 626 reply is shorter than the SSH_QUIC_INIT packet to which it is 627 replying. If this is not the case, the server MUST send an Error 628 Reply (Section 2.9.1). Such an Error Reply MUST be shorter than 629 the SSH_QUIC_INIT packet. 631 SSH_QUIC_REPLY is an obfuscated datagram (Section 2.3) where "obfs- 632 payload" encrypts the following: 634 byte SSH_QUIC_REPLY = 2 635 short-str client-connection-id 636 short-str server-connection-id (Non-empty except on error) 638 byte v = nr-quic-versions (MUST NOT be zero) 639 uint32[v] server-quic-versions 640 string server-quic-trnsp-params 642 string server-sig-algs (MUST NOT be empty) 643 string server-kex-algs (MUST NOT be empty) 645 byte c = nr-cipher-suites (MUST NOT be zero) 646 the following 1 field repeated c times: 647 short-str quic-tls-cipher-suite 649 byte e = nr-ext-pairs (see Extensibility) 650 the following 2 fields repeated e times: 651 short-str ext-pair-name (MUST NOT be empty) 652 string ext-pair-data (MAY be empty) 654 string server-kex-alg-data (Non-empty except on error) 656 Figure 7 658 SSH_QUIC_REPLY does not include an SSH version string or compression 659 negotiation. Instead, servers MUST use SSH_MSG_EXT_INFO for these 660 purposes. See Section 4. 662 SSH_QUIC_REPLY does not include a "cookie" field for random data. 663 Servers MUST insert random data using the packet's extensibility 664 mechanisms. See Section 2.9.2 and Section 2.6. 666 The field "client-connection-id" encodes the "client-connection-id" 667 sent by the client in SSH_QUIC_INIT. 669 The field "server-connection-id" contains a QUIC Connection ID of 670 length 1..20 bytes. The client will use this as the QUIC Destination 671 Connection ID in QUIC packets sent to the server. This field MUST be 672 empty if sending an Error Reply (Section 2.9.1), and MUST NOT be 673 empty otherwise. 675 The fields "server-quic-versions" enumerate QUIC protocol versions 676 supported by the server. The server MUST send at least one version. 677 The QUIC version used for the connection is the first version 678 enumerated in "client-quic-versions" which is also present in 679 "server-quic-versions". If there is no such version, see 680 Section 2.9.1. 682 The field "server-quic-trnsp-params" encodes the server's QUIC 683 Transport Parameters as defined in [QUIC]. 685 The field "server-sig-algs" MUST contain at least one signature 686 algorithm supported by the server. The server SHOULD enumerate all 687 signature algorithms for which it has host keys. These are the same 688 algorithms as used in SSH_MSG_KEXINIT ([RFC4253], Section 7.1) in the 689 field "server_host_key_algorithms". In the SSH/QUIC key exchange, 690 the server MUST use a host key it possesses that (1) matches any 691 fingerprint enumerated in the "trusted-fingerprint" fields in 692 SSH_QUIC_INIT; and (2) can be used with the earliest possible 693 signature algorithm enumerated in "client-sig-algs". If there are 694 multiple such host keys, the client's preference order in "client- 695 sig-algs" dominates the preference order of "trusted-fingerprint". 696 If there is no such host key, the server MUST use any host key that 697 can be used with the earliest possible signature algorithm enumerated 698 in "client-sig-algs". If there is no such host key either, see 699 Section 2.9.1. 701 The field "server-kex-algs" MUST contain at least one SSH key 702 exchange algorithm supported by the server. The key exchange 703 algorithm which is used in the connection is the first algorithm sent 704 in client's SSH_QUIC_INIT where: (1) the field "client-kex-alg-data" 705 is non-empty, and (2) the algorithm is also present in "server-kex- 706 algs". If there is no such key exchange algorithm, see 707 Section 2.9.1. 709 There MUST be at least one "quic-tls-cipher-suite" field. Each of 710 these specifies a TLS cipher suite ([RFC8446], Appendix B.4) which is 711 supported by the server, and which can be used with a version of QUIC 712 ([QUIC], [QUIC-TLS]) supported by the server. The TLS cipher suite 713 which is used for the connection is the first suite sent in the 714 client's SSH_QUIC_INIT where: (1) the cipher suite is supported by 715 the negotiated QUIC protocol version, and (2) the cipher suite is 716 present in the server's SSH_QUIC_REPLY. If there is no such cipher 717 suite, see Section 2.9.1. 719 The server MAY send any number of extensions, encoded as a pair of 720 "ext-pair-name" and "ext-pair-data" fields. Some extensions are 721 defined for use with an Error Reply (see Section 2.9.1). Other 722 extensions MAY be defined in the future; see Section 2.9.2. 724 The field "server-kex-alg-data" MUST be empty if the packet is an 725 Error Reply. Otherwise, this field contains information for the SSH 726 key exchange method: see Section 3. Generally, this includes the 727 server's portion of key exchange inputs; the server's host key; and 728 the server's signature of the calculated exchange hash. 730 2.9.1. Error Reply 732 If a server encounters an error which it is useful and appropriate to 733 communicate to the client, the server MAY send an "Error Reply" 734 version of SSH_QUIC_REPLY. Such a reply is created as follows: 736 * The server includes and populates all fields of SSH_QUIC_REPLY as 737 it would normally, except that the fields "server-connection-id" 738 and "server-kex-alg-data" MUST remain empty. 740 * In the extension pair fields, a "disc-reason" Extension Pair MUST 741 be included. An "err-desc" Extension Pair MAY also be included. 742 See Section 2.7. 744 * Extensibility considerations for SSH_QUIC_REPLY in Section 2.9.2 745 also apply to an Error Reply. 747 If the server does not support any of the QUIC protocol versions 748 enumerated by the client, the server SHOULD send an Error Reply with 749 the disconnect reason code 750 SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED. 752 In the following circumstances, the server SHOULD send an Error Reply 753 with the disconnect reason code SSH_DISCONNECT_KEY_EXCHANGE_FAILED: 755 * If the server could have sent a successful SSH_QUIC_REPLY, but it 756 would have been larger than the client's SSH_QUIC_INIT, even 757 though the SSH_QUIC_INIT met or exceeded the minimum length. 759 * If the server possesses no server host key that can be used with a 760 signature algorithm enumerated in the client's SSH_QUIC_INIT. 762 * If the server supports no key exchange algorithms matching the 763 ones for which the client sent "client-kex-alg-data" in 764 SSH_QUIC_INIT. 766 * If the server supports no TLS cipher suites enumerated in the 767 client's SSH_QUIC_INIT. 769 Besides "disc-reason", an "err-desc" extension pair SHOULD be 770 included to describe the specific error. 772 2.9.2. Extensibility 774 Implementations MUST allow room for future extensibility of 775 SSH_QUIC_REPLY in the following manners: 777 1. By including algorithms in "server-sig-algs" which are unknown to 778 or not supported by the client. Clients MUST tolerate the 779 presence of such algorithms. 781 2. By including SSH key exchange algorithms which are unknown to or 782 not supported by the client, with algorithm data in a format 783 that's unknown to or not supported by the client. Clients MUST 784 tolerate the presence of such algorithms and their data. 786 3. By including QUIC TLS cipher suites which are unknown to or not 787 supported by the client. Clients MUST tolerate the presence of 788 such cipher suites. 790 4. By including extensions which are unknown to or not supported by 791 the client, with extension data in a format that's unknown to or 792 not supported by the client. Clients MUST tolerate the presence 793 of such extensions and their data. 795 Experience shows that any extensibility which is not actively 796 exercised is lost due to implementations that lock down expectations 797 incorrectly. Therefore, all servers MUST do at least one of the 798 following, in each SSH_QUIC_REPLY packet, at random: 800 1. In the fields "server-quic-versions", include in a random 801 position a version number of the form 0xFA?A?A?A, where ? 802 indicates a random nibble. See [QUIC], section "Versions". Note 803 the difference from the random version pattern in the client's 804 SSH_QUIC_INIT. Due to the minimal amount of entropy provided by 805 this rule, this MUST NOT be the only insertion of randomness made 806 in a packet. 808 2. In the field "server-sig-algs", include in a random position one 809 Random Name (Section 2.6). 811 3. In the field "server-kex-algs", include in a random position one 812 Random Name (Section 2.6). 814 4. In the fields "quic-tls-cipher-suite", include in a random 815 position one entry consisting of 16..64 Random Bytes. 817 5. In extension pairs, include in a random position one extension 818 pair where the field "ext-pair-name" contains a Random Name, and 819 the field "ext-pair-value" contains 0..100 Random Bytes. 821 2.10. SSH_QUIC_CANCEL 823 If a client cannot process the server's successful SSH_QUIC_REPLY, 824 the client SHOULD report the error to the server using 825 SSH_QUIC_CANCEL. 827 A client MUST NOT send an SSH_QUIC_CANCEL in response to an 828 SSH_QUIC_REPLY which is itself an Error Reply. A client MUST assume 829 that such a connection was already canceled by the server. 831 A client SHOULD send two or more copies of SSH_QUIC_CANCEL, in 832 transmissions separated by a fraction of a second, to increase the 833 likelihood of successful delivery. The server sends no 834 acknowledgment to SSH_QUIC_CANCEL. After the server has received 835 SSH_QUIC_CANCEL, it MUST ignore subsequent copies of SSH_QUIC_CANCEL 836 for the same connection. 838 SSH_QUIC_CANCEL is an obfuscated datagram (Section 2.3) where "obfs- 839 payload" encrypts the following: 841 byte SSH_QUIC_CANCEL = 3 842 short-str server-connection-id 844 byte e = nr-ext-pairs (see Extensibility) 845 the following 2 fields repeated e times: 846 short-str ext-pair-name (MUST NOT be empty) 847 string ext-pair-data (MAY be empty) 849 Figure 8 851 The "server-connection-id" field MUST equal the "server-connection- 852 id" field in the server's SSH_QUIC_REPLY. 854 In the extension pair fields, a "disc-reason" Extension Pair MUST be 855 included. An "err-desc" Extension Pair MAY also be included. See 856 Section 2.7. 858 2.10.1. Extensibility 860 Extensibility considerations also apply to SSH_QUIC_CANCEL: 862 * Clients MAY include extensions which are unknown to or not 863 supported by the server, with extension data in a format that's 864 unknown to or not supported by the server. 866 * Servers MUST tolerate the presence of such extensions and their 867 data. 869 * Clients SHOULD include, in a random position, at least one 870 extension pair where the field "ext-pair-name" contains a Random 871 Name, and the field "ext-pair-value" contains 0..300 Random Bytes. 873 3. Key Exchange Methods 875 Clients and servers MAY use any key exchange method which is defined 876 for SSH over TCP, whether it is assigned or private, as long as it 877 meets all of the following criteria: 879 1. The algorithm requires exactly one message from the client to the 880 server, for example SSH_MSG_KEX_ECDH_INIT. We call this message 881 KEXMSG_CLIENT. 883 2. The algorithm requires exactly one reply from the server to the 884 client, for example SSH_MSG_KEX_ECDH_REPLY. We call this message 885 KEXMSG_SERVER. 887 3. The algorithm specifies a hash function HASH, for example SHA- 888 256, SHA-384, or SHA-512. 890 4. The algorithm specifies calculation of an exchange hash H by 891 applying HASH to a concatenation of encoded fields. 893 5. The algorithm uses a server host key to sign H. 895 6. The algorithm includes the server's public host key, and the 896 signature of H, in its KEXMSG_SERVER message to the client. 898 7. The algorithm produces a shared secret K, represented as a signed 899 (positive or negative) multi-precision integer. 901 Any such algorithm is modified for use in SSH over QUIC as follows: 903 1. The field "client-kex-alg-data" in SSH_QUIC_INIT encodes the same 904 fields, in the same order, as KEXMSG_CLIENT, including the 905 leading byte for the SSH packet type. 907 2. The field "server-kex-alg-data" in SSH_QUIC_REPLY encodes the 908 same fields, in the same order, as KEXMSG_SERVER, including the 909 leading byte for the SSH packet type. 911 3. The calculation of H specified by the algorithm is not performed. 912 Instead, H is calculated by applying the hash function HASH to a 913 concatenation of the following: 915 byte[8] "SSH/QUIC" 917 string Unencrypted "obfs-payload" content of SSH_QUIC_INIT 919 string Unencrypted "obfs-payload" content of SSH_QUIC_REPLY, 920 excluding the entire field "server-kex-alg-data" 922 The fields of "server-kex-alg-data", excluding signature field 924 mpint K 926 Figure 9 928 When a field is excluded as above, the entire encoding of the field 929 is omitted: both the encoding of the content and the encoding of the 930 length. 932 The SSH packet type byte is included: 934 * To ensure there are at least two fields in the encoded content. 935 This avoids situations where an outer string (the field "client- 936 kex-alg-data") would contain a single inner string (from 937 KEXMSG_CLIENT). This could confuse implementers to incorrectly 938 encode a single string only. 940 * For future consistency. The packet type byte may be useful for 941 multiple-roundtrip key exchange methods, for example those using 942 GSS-API [RFC4462]. Such key exchange methods are not currently 943 defined for SSH/QUIC, but can be. 945 3.1. Required Key Exchange Methods 947 Clients and servers are REQUIRED to implement the key exchange method 948 "curve25519-sha256" [RFC8731]. All other key exchange methods are 949 optional. 951 Clients and servers MAY permit the user to disable a required key 952 exchange method. However, required methods MUST be enabled by 953 default. 955 The requirement to implement any particular key exchange method 956 expires on the 5-year anniversary of the publishing of this memo. At 957 that point, implementers SHOULD consult any new standards documents 958 if available, or survey the practical use of SSH/QUIC for 959 implementation guidance. 961 3.2. Example 1: "curve25519-sha256" 963 When using the SSH key exchange method "curve25519-sha256", the 964 SSH_QUIC_INIT field "client-kex-alg-data" is derived from 965 SSH_MSG_KEX_ECDH_INIT ([RFC5656], Section 4) and contains the 966 following: 968 byte SSH_MSG_KEX_ECDH_INIT = 30 969 string Q_C, client's ephemeral public key octet string 971 Figure 10 973 The SSH_QUIC_REPLY field "server-kex-alg-data" is derived from 974 SSH_MSG_KEX_ECDH_REPLY and contains the following: 976 byte SSH_MSG_KEX_ECDH_REPLY = 31 977 string K_S, server's public host key 978 string Q_S, server's ephemeral public key octet string 979 string the signature on the exchange hash 981 Figure 11 983 The shared secret K is calculated as in [RFC8731]. Then the exchange 984 hash H is calculated by applying SHA-256 to a concatenation of the 985 following: 987 string Content of SSH_QUIC_INIT 988 string Content of SSH_QUIC_REPLY, except "server-kex-alg-data" 989 byte SSH_MSG_KEX_ECDH_REPLY = 31 990 string K_S, server's public host key 991 string Q_S, server's ephemeral public key octet string 992 mpint K 994 Figure 12 996 3.3. Example 2: "diffie-hellman-group14-sha256" 998 When using the SSH key exchange method "diffie-hellman- 999 group14-sha256" [RFC8268], the SSH_QUIC_INIT field "client-kex-alg- 1000 data" is derived from SSH_MSG_KEXDH_INIT ([RFC4253], Section 8) and 1001 contains the following: 1003 byte SSH_MSG_KEXDH_INIT = 30 1004 mpint e 1006 Figure 13 1008 The SSH_QUIC_REPLY field "server-kex-alg-data" is derived from 1009 SSH_MSG_KEXDH_REPLY and contains the following: 1011 byte SSH_MSG_KEXDH_REPLY = 31 1012 string server public host key and certificates (K_S) 1013 mpint f 1014 string signature of H 1016 Figure 14 1018 The shared secret K is calculated as in [RFC4253]. Then the exchange 1019 hash H is calculated by applying SHA-256 to a concatenation of the 1020 following: 1022 string Content of SSH_QUIC_INIT 1023 string Content of SSH_QUIC_REPLY, except "server-kex-alg-data" 1024 byte SSH_MSG_KEXDH_REPLY = 31 1025 string server public host key and certificates (K_S) 1026 mpint f 1027 mpint K 1029 Figure 15 1031 4. SSH_MSG_EXT_INFO and the SSH Version String 1033 A common user complaint to SSH application authors is that SSH over 1034 TCP sends the application version in plain text. The application 1035 version cannot be omitted, otherwise implementations cannot support a 1036 number of behaviors which other software versions implement 1037 incorrectly. 1039 A prominent example is the order of arguments in the SFTP request 1040 SSH_FXP_SYMLINK. To send a request that will have the desired 1041 effects, the client MUST consult the server's version string to know 1042 whether the server uses the standard order of fields, or a reverse 1043 order used by OpenSSH. 1045 SSH over QUIC removes the version string from the SSH key exchange. 1046 Instead, all clients and servers are REQUIRED to send and accept 1047 SSH_MSG_EXT_INFO [RFC8308], and to include the "ssh-version" 1048 extension defined here. 1050 Clients MUST send SSH_MSG_EXT_INFO as the very first SSH packet over 1051 QUIC stream 0. The client MUST include the "ssh-version" extension 1052 in this SSH_MSG_EXT_INFO. 1054 Servers MUST send SSH_MSG_EXT_INFO either: 1056 1. as the very first SSH packet over QUIC stream 0, and/or 1058 2. immediately preceding the server's SSH_MSG_USERAUTH_SUCCESS. 1060 A server MUST include the "ssh-version" extension in at least one of 1061 its SSH_MSG_EXT_INFO. If the server sends SSH_MSG_EXT_INFO at both 1062 opportunities, it MAY omit "ssh-version" at the first opportunity, 1063 but only if it will send it in the second opportunity. The second 1064 SSH_MSG_EXT_INFO sent by the server MAY change a previously sent 1065 "ssh-version" extension value to include more specific detail. For 1066 example, the server MAY send a more accurate server software version 1067 when the client has authenticated. The client MUST use the "ssh- 1068 version" value which was most recently received from the server. 1070 4.1. "ssh-version" 1072 The "ssh-version" extension is encoded in SSH_MSG_EXT_INFO as 1073 follows: 1075 string "ssh-version" 1076 string ssh-version-string 1078 Figure 16 1080 The extension value, "ssh-version-string", contains the same SSH 1081 version string as sent at the start of SSH over TCP ([RFC4253], 1082 Section 4.2), but stripping the prefix "SSH-2.0-". Examples inspired 1083 by version strings used in practice: 1085 GenericSoftware 1086 Product_1.2.00 1087 0.12 Library: Application 1.23p1 1089 Figure 17 1091 4.2. "no-flow-control" 1093 The extension "no-flow-control" has no effect in SSH/QUIC. It SHOULD 1094 NOT be sent in SSH/QUIC and MUST be ignored by both parties. 1096 4.3. "delay-compression" 1098 Semantics of the "delay-compression" extension are modified as per 1099 Section 6.1.1. 1101 5. QUIC Session Setup 1103 When the server has sent its SSH_QUIC_REPLY, and when the client has 1104 received it, they each initialize the QUIC session [QUIC] [QUIC-TLS] 1105 as follows: 1107 * The QUIC protocol version is set to the first version advertised 1108 in the client's SSH_QUIC_INIT which is also present in the 1109 server's SSH_QUIC_REPLY. 1111 * Session state is set as if a TLS handshake had just completed. 1113 * The TLS cipher suite is set to the first TLS cipher suite 1114 advertised in SSH_QUIC_INIT which is also present in 1115 SSH_QUIC_REPLY. 1117 * The QUIC Key Phase bit is set to 0. 1119 * The shared secrets that would have been obtained from the TLS 1120 handshake are instead generated from the SSH key exchange 1121 (Section 5.1). 1123 Clients and servers MUST immediately begin to use QUIC Short Header 1124 Packets. Implementations MUST NOT send QUIC Long Header Packets, 1125 since they could be confused with the SSH/QUIC key exchange. 1127 5.1. Shared Secrets 1129 QUIC-TLS [QUIC-TLS] uses a client secret and a server secret from 1130 which it generates an AEAD key, an IV, and a header protection key 1131 for each sending direction. 1133 An SSH key exchange produces a shared secret K, represented as an SSH 1134 multi-precision integer, and an exchange digest H, represented as 1135 binary data [RFC4253]. An SSH key exchange is parameterized with a 1136 hash function we call HASH. Note that HASH can be a different hash 1137 function, producing a different hash length, than the hash function 1138 used by the negotiated TLS cipher suite. 1140 To compute the initial QUIC client and server secrets, the client and 1141 server encode the following binary data, which we call "secret_data": 1143 mpint K 1144 string H 1146 Figure 18 1148 The client and server secrets are then calculated as follows: 1150 client_secret = HMAC-HASH("ssh/quic client", secret_data) 1151 server_secret = HMAC-HASH("ssh/quic server", secret_data) 1153 Figure 19 1155 The HMAC construct is as specified in [RFC2104], instantiated using 1156 the SSH key exchange hash function, HASH. 1158 QUIC keys and IVs are derived from these secrets using the regular 1159 QUIC-TLS key derivation process [QUIC-TLS]. Keys generated from 1160 these secrets are considered 1-RTT keys. 1162 Clients and servers MUST implement QUIC key updates using the regular 1163 QUIC-TLS key update process [QUIC-TLS], respecting the QUIC-TLS 1164 minimum key update frequencies. 1166 6. Adaptation of SSH to QUIC Streams 1168 6.1. SSH/QUIC Packet Format 1170 Each side serializes its SSH packets for sending over QUIC as 1171 follows: 1173 uint32 n = payload-len, high bit set if compressed 1174 byte[n] payload (compressed or uncompressed) 1176 Figure 20 1178 Since security is provided by QUIC-TLS [QUIC-TLS], MAC and random 1179 padding are omitted at this stage. 1181 The "payload-len" field has its high bit set if the "payload" field 1182 is compressed. See Section 6.1.1. 1184 The "payload" field contains the same packet information as the 1185 "payload" field in the Binary Packet Protocol defined in [RFC4253]. 1187 6.1.1. Compression 1189 Compression MAY be negotiated using the "delay-compression" extension 1190 in [RFC8308]. If "delay-compression" was negotiated, then: 1192 * If compression is enabled for the server-to-client direction, the 1193 server MAY compress packets on any stream after it has sent 1194 SSH_MSG_USERAUTH_SUCCESS. 1196 * If compression is enabled for the client-to-server direction, the 1197 client MAY compress packets on any stream after it has received 1198 SSH_MSG_USERAUTH_SUCCESS. 1200 Due to multiple streams in SSH/QUIC, the packet SSH_MSG_NEWCOMPRESS 1201 is not an effective mechanism to signal the start of compression and 1202 MUST NOT be sent. It is replaced by the high bit in "payload-len". 1204 6.2. Use of QUIC Streams 1206 To avoid an unnecessary layer of flow control which has performance 1207 and complexity impacts in SSH over TCP, SSH/QUIC uses QUIC streams 1208 for SSH channels and dispenses with flow control on the level of SSH 1209 channels. This simplifies future SSH/QUIC implementations which 1210 might not implement SSH over TCP. 1212 Conducting SSH channels over QUIC streams requires modifications of 1213 the SSH Connection Protocol [RFC4254]. The following sections 1214 describe these modifications. 1216 6.3. Packet Sequence Numbers 1218 In SSH over TCP, every SSH packet has an implicit sequence number 1219 which is unique for the direction of sending (to server vs. to 1220 client). The packet type SSH_MSG_UNIMPLEMENTED makes reference to 1221 this sequence number. 1223 In SSH/QUIC, sequence numbers are separate for each sending 1224 direction, as well as each QUIC stream. This requires modification 1225 of SSH_MSG_UNIMPLEMENTED. This packet type is changed as follows: 1227 byte SSH_MSG_UNIMPLEMENTED 1228 uint64 QUIC stream ID on which the packet was received 1229 uint32 packet sequence number in stream, first packet = 0 1231 Figure 21 1233 6.4. Channel IDs 1235 SSH over TCP uses 32-bit channel IDs which can be reused in the same 1236 session and do not have to be used sequentially. Conflicts in 1237 channel IDs are avoided by identifying each channel with two separate 1238 channel IDs: one designated by the sender and one by the recipient. 1239 [RFC4254] 1240 QUIC streams use 62-bit channel IDs which cannot be reused and MUST 1241 be used sequentially. Both sides use the same stream ID. Conflicts 1242 in stream IDs are avoided by using the least significant bit to 1243 indicate whether the stream was opened by the client or by the 1244 server. [QUIC] 1246 SSH/QUIC uses QUIC stream IDs. This requires modification of SSH 1247 channel-related packets. See Section 6.8. 1249 6.5. Disconnection 1251 The SSH packet type SSH_MSG_DISCONNECT is replaced by sending the 1252 QUIC frame CONNECTION_CLOSE of type 0x1d. The "Error Code" field in 1253 CONNECTION_CLOSE contains the value that would have been sent in the 1254 "reason code" in SSH_MSG_DISCONNECT. The "Reason Phrase" field in 1255 CONNECTION_CLOSE contains the value that would have been sent in 1256 "description" in SSH_MSG_DISCONNECT. The "language tag" field of 1257 SSH_MSG_DISCONNECT is not sent. 1259 6.6. Prohibited SSH Packets 1261 In SSH/QUIC, the following SSH packet types MUST NOT be sent: 1263 SSH_MSG_DISCONNECT 1 1264 SSH_MSG_NEWCOMPRESS 8 1266 SSH_MSG_KEXINIT 20 1267 SSH_MSG_NEWKEYS 21 1268 key exchange packets 30-49 1270 SSH_MSG_CHANNEL_WINDOW_ADJUST 93 1271 SSH_MSG_CHANNEL_CLOSE 97 1273 Figure 22 1275 If they receive packets of these types, clients and servers MAY 1276 disconnect with SSH_DISCONNECT_PROTOCOL_ERROR (Section 6.5). 1277 Alternately, the receiver MAY send SSH_MSG_UNIMPLEMENTED 1278 (Section 6.3). 1280 6.7. Global SSH Packets 1282 In SSH/QUIC, the following SSH packet types MUST be sent on QUIC 1283 stream 0. With the exception of SSH_MSG_UNIMPLEMENTED (Section 6.3), 1284 these packets use the same encoded formats as in SSH over TCP: 1286 SSH_MSG_IGNORE 2 1287 SSH_MSG_UNIMPLEMENTED 3 (Changed format!) 1288 SSH_MSG_DEBUG 4 1289 SSH_MSG_SERVICE_REQUEST 5 1290 SSH_MSG_SERVICE_ACCEPT 6 1291 SSH_MSG_EXT_INFO 7 1293 SSH_MSG_USERAUTH_REQUEST 50 1294 SSH_MSG_USERAUTH_FAILURE 51 1295 SSH_MSG_USERAUTH_SUCCESS 52 1296 SSH_MSG_USERAUTH_BANNER 53 1297 SSH_MSG_USERAUTH_INFO_REQUEST 60 1298 SSH_MSG_USERAUTH_INFO_RESPONSE 61 1300 SSH_MSG_GLOBAL_REQUEST 80 1301 SSH_MSG_REQUEST_SUCCESS 81 1302 SSH_MSG_REQUEST_FAILURE 82 1304 Figure 23 1306 6.8. SSH Channel Packets 1308 All SSH/QUIC channels MUST be opened as bidirectional QUIC streams. 1309 This means QUIC stream IDs where the least significant bits are 10 or 1310 11 MUST NOT be used in SSH/QUIC. Implementations that receive such 1311 stream IDs MUST disconnect with SSH_DISCONNECT_PROTOCOL_ERROR 1312 (Section 6.5) 1314 A client MUST NOT open a non-zero QUIC stream before the server has 1315 sent SSH_MSG_USERAUTH_SUCCESS. If a client does so, the server MUST 1316 disconnect with SSH_DISCONNECT_PROTOCOL_ERROR. 1318 A server MUST NOT open a non-zero QUIC stream before it has sent 1319 SSH_MSG_USERAUTH_SUCCESS. However, a client MUST be prepared for the 1320 possibility that, due to network delays, a stream opened by the 1321 server can be received by the client before SSH_MSG_USERAUTH_SUCCESS. 1322 Therefore, if the client receives a server-initiated stream before 1323 SSH_MSG_USERAUTH_SUCCESS, it MUST assume that the server has also 1324 sent SSH_MSG_USERAUTH_SUCCESS. If the client then receives packets 1325 on QUIC stream 0 which invalidate this assumption, the client MUST 1326 disconnect with SSH_DISCONNECT_PROTOCOL_ERROR. 1328 The initiator of any non-zero QUIC stream MUST send 1329 SSH_MSG_CHANNEL_OPEN as the first packet. If the receiver refuses 1330 the channel, it replies with SSH_MSG_CHANNEL_OPEN_FAILURE. Both 1331 sides then MUST close the QUIC stream as per Section 6.9. In this 1332 case, even though a QUIC stream was opened, an SSH channel was not. 1333 Therefore, other SSH_MSG_CHANNEL_xxxx packets MUST NOT be sent. This 1334 includes SSH_MSG_CHANNEL_EOF. 1336 If the receiver accepts the channel, it replies with 1337 SSH_MSG_CHANNEL_OPEN_CONFIRMATION. Both sides then send SSH packets 1338 of types SSH_MSG_CHANNEL_xxxx. In SSH/QUIC, these packets have the 1339 following formats: 1341 byte SSH_MSG_CHANNEL_OPEN 1342 string channel type in US-ASCII only 1343 uint32 maximum packet size 1344 .... channel-type-specific data follows 1346 Figure 24 1348 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION 1349 uint32 maximum packet size 1350 .... channel-type-specific data follows 1352 Figure 25 1354 byte SSH_MSG_CHANNEL_OPEN_FAILURE 1355 uint32 reason code 1356 string description in UTF-8 1357 string language tag 1359 Figure 26 1361 byte SSH_MSG_CHANNEL_DATA 1362 string data 1364 Figure 27 1366 byte SSH_MSG_CHANNEL_EXTENDED_DATA 1367 uint32 data_type_code 1368 string data 1370 Figure 28 1372 byte SSH_MSG_CHANNEL_EOF 1374 Figure 29 1376 byte SSH_MSG_CHANNEL_REQUEST 1377 string request type in US-ASCII characters only 1378 boolean want reply 1379 .... type-specific data follows 1381 Figure 30 1383 byte SSH_MSG_CHANNEL_SUCCESS 1385 Figure 31 1387 byte SSH_MSG_CHANNEL_FAILURE 1389 Figure 32 1391 6.9. Closing a Channel 1393 The SSH packet type SSH_MSG_CHANNEL_CLOSE is replaced by QUIC stream 1394 state transitions [QUIC]. Each side considers a channel closed when 1395 the QUIC stream is both in a terminal sending state, and a terminal 1396 receiving state. This means: 1398 * The QUIC sending stream state has become "Data Recvd" or "Reset 1399 Recvd". 1401 * The QUIC receiving stream state has become "Data Read" or "Reset 1402 Read". 1404 The SSH packet type SSH_MSG_CHANNEL_EOF continues to be used. This 1405 packet often does NOT correspond with the end of the stream in its 1406 direction. As in SSH over TCP, SSH channel requests MAY be sent 1407 after SSH_MSG_CHANNEL_EOF, and MUST be handled gracefully by 1408 receivers. A common example is the request "exit-status", which is 1409 sent by a server to communicate a process exit code to the SSH 1410 client, and is commonly sent after the end of output. 1412 7. Acknowledgements 1414 Paul Ebermann for first review and the encouragement to use QUIC 1415 streams. 1417 Ilari Liusvaara for "server-name-indication" and value 1200 for 1418 SSH_QUIC_INIT padding target. 1420 Benjamin Kaduk for idea of additional cross-protocol protection in 1421 the calculation of H. 1423 Stephane Bortzmeyer for the PRECIS Framework to handle the 1424 obfuscation keyword. 1426 Yuki Goto for the QUIC Transport Parameters. 1428 8. IANA Considerations 1430 This document requests no changes to IANA registries. 1432 9. Security Considerations 1434 Clients and servers MUST insert into SSH_QUIC_INIT and SSH_QUIC_REPLY 1435 at least the minimum amount of cryptographically random data as 1436 specified in the section Random Elements. Compromising on this 1437 requirement reduces the security of any session created on the basis 1438 of such an SSH_QUIC_INIT or SSH_QUIC_REPLY. 1440 10. References 1442 10.1. Normative References 1444 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed 1445 and Secure Transport", 2020, . 1448 [QUIC-TLS] Thomson, M. and S. Turner, "Using TLS to Secure QUIC", 1449 2020, 1450 . 1452 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1453 Hashing for Message Authentication", RFC 2104, 1454 DOI 10.17487/RFC2104, February 1997, 1455 . 1457 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1458 Requirement Levels", BCP 14, RFC 2119, 1459 DOI 10.17487/RFC2119, March 1997, 1460 . 1462 [RFC4251] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1463 Protocol Architecture", RFC 4251, DOI 10.17487/RFC4251, 1464 January 2006, . 1466 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1467 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253, 1468 January 2006, . 1470 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1471 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 1472 . 1474 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm 1475 Integration in the Secure Shell Transport Layer", 1476 RFC 5656, DOI 10.17487/RFC5656, December 2009, 1477 . 1479 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1480 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1481 May 2017, . 1483 [RFC8264] Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 1484 Preparation, Enforcement, and Comparison of 1485 Internationalized Strings in Application Protocols", 1486 RFC 8264, DOI 10.17487/RFC8264, October 2017, 1487 . 1489 [RFC8265] Saint-Andre, P. and A. Melnikov, "Preparation, 1490 Enforcement, and Comparison of Internationalized Strings 1491 Representing Usernames and Passwords", RFC 8265, 1492 DOI 10.17487/RFC8265, October 2017, 1493 . 1495 [RFC8308] Bider, D., "Extension Negotiation in the Secure Shell 1496 (SSH) Protocol", RFC 8308, DOI 10.17487/RFC8308, March 1497 2018, . 1499 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1500 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1501 . 1503 [RFC8731] Adamantiadis, A., Josefsson, S., and M. Baushke, "Secure 1504 Shell (SSH) Key Exchange Method Using Curve25519 and 1505 Curve448", RFC 8731, DOI 10.17487/RFC8731, February 2020, 1506 . 1508 10.2. Informative References 1510 [IANA-SSH] IANA, "Secure Shell (SSH) Protocol Parameters", 1511 . 1513 [RFC4250] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell (SSH) 1514 Protocol Assigned Numbers", RFC 4250, 1515 DOI 10.17487/RFC4250, January 2006, 1516 . 1518 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1519 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252, 1520 January 2006, . 1522 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH) 1523 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254, 1524 January 2006, . 1526 [RFC4462] Hutzelman, J., Salowey, J., Galbraith, J., and V. Welch, 1527 "Generic Security Service Application Program Interface 1528 (GSS-API) Authentication and Key Exchange for the Secure 1529 Shell (SSH) Protocol", RFC 4462, DOI 10.17487/RFC4462, May 1530 2006, . 1532 [RFC8268] Baushke, M., "More Modular Exponentiation (MODP) Diffie- 1533 Hellman (DH) Key Exchange (KEX) Groups for Secure Shell 1534 (SSH)", RFC 8268, DOI 10.17487/RFC8268, December 2017, 1535 . 1537 Appendix A. Generating Random Lengths 1539 The SSH/QUIC extensibility mechanism calls for generating random 1540 lengths such that values in the shorter end of the range are 1541 significantly more probable, but long lengths are still selected. 1542 The following C example shows a simple two-step process to prefer 1543 shorter lengths: 1545 int RandomIntBetweenZeroAnd(int maxValueInclusive); 1547 int RandomLen_PreferShort(int minLen, int maxLen) 1548 { 1549 int const SPAN_THRESHOLD = 7; 1550 int lenSpan = maxLen - minLen; 1552 if (lenSpan <= 0) 1553 return minLen; 1555 if (lenSpan > SPAN_THRESHOLD) 1556 if (0 != RandomIntBetweenZeroAnd(3)) 1557 return minLen + RandomIntBetweenZeroAnd(SPAN_THRESHOLD); 1559 return minLen + RandomIntBetweenZeroAnd(lenSpan); 1560 } 1562 Figure 33 1564 Author's Address 1565 denis bider 1566 Bitvise Limited 1567 4105 Lombardy Ct 1568 Colleyville, TX 76034 1569 United States 1571 Email: ietf-draft@denisbider.com