idnits 2.17.1
draft-bider-ssh-quic-07.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 417 has weird spacing: '...ort-str trus...'
== Line 421 has weird spacing: '...ort-str clie...'
== Line 426 has weird spacing: '...ort-str quic...'
== (21 more instances...)
-- The document date (5 August 2020) is 1361 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 907
== Unused Reference: 'RFC4250' is defined on line 1503, 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 5 August 2020
5 Expires: 6 February 2021
7 QUIC-based UDP Transport for Secure Shell (SSH)
8 draft-bider-ssh-quic-07
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 6 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 . . . . . . . . . . . . . . . . . . . . 12
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
413 string client-sig-algs (MUST NOT be empty)
415 byte f = nr-trusted-fingerprints (MAY be zero)
416 the following 1 field repeated f times:
417 short-str trusted-fingerprint (MUST NOT be empty)
419 byte k = nr-client-kex-algs (MUST NOT be zero)
420 the following 2 fields repeated k times:
421 short-str client-kex-alg-name (MUST NOT be empty)
422 string client-kex-alg-data (MUST NOT be empty)
424 byte c = nr-cipher-suites (MUST NOT be zero)
425 the following 1 field repeated c times:
426 short-str quic-tls-cipher-suite
428 byte e = nr-ext-pairs (see Extensibility)
429 the following 2 fields repeated e times:
430 short-str ext-pair-name (MUST NOT be empty)
431 string ext-pair-data (MAY be empty)
433 byte[0..] padding: all 0xFF to minimal obfs-payload size 1200
435 Figure 5
437 SSH_QUIC_INIT does not include an SSH version string or compression
438 negotiation. Instead, clients MUST use SSH_MSG_EXT_INFO for these
439 purposes. See Section 4.
441 SSH_QUIC_INIT does not include a "cookie" field for random data.
442 Clients MUST insert random data using the packet's extensibility
443 mechanisms. See Section 2.8.1 and Section 2.6.
445 The field "client-connection-id" contains a QUIC Connection ID of
446 length 0..20 bytes. The server will use this as the QUIC Destination
447 Connection ID in QUIC packets sent to the client. Clients MAY send
448 an empty Connection ID if they are using other means of routing
449 connections.
451 The field "server-name-indication" SHOULD contain the server DNS name
452 if a DNS name was entered by the user when configuring the
453 connection. This can be invaluable in hosting environments: it
454 allows servers to expose to clients multiple distinct identities on
455 the same network address and port. If non-empty, the field MUST
456 encode the DNS name entered by the user as a string consisting of
457 printable US-ASCII characters. Internationalized domain names MUST
458 be represented in their US-ASCII encoding. If the user connected
459 directly to an IP address, this field MUST be empty. This avoids
460 disclosing private information in case of port forwarded connections.
461 Example non-empty values:
463 localhost
464 server.example.com
465 xn--bcher-kva.example
467 Figure 6
469 The fields "client-quic-versions" enumerate QUIC protocol versions
470 supported by the client. The client MUST send at least one version.
471 The client MUST send supported versions in the order it prefers the
472 server to use them.
474 The field "client-sig-algs" MUST contain at least one signature
475 algorithm supported by the client for server authentication. These
476 are the same algorithms as used in SSH_MSG_KEXINIT ([RFC4253],
477 Section 7.1) in the field "server_host_key_algorithms". The client
478 MUST send signature algorithms in the order it prefers the server to
479 use them.
481 The client SHOULD include algorithms in "client-sig-algs" as follows:
483 * If the client does not yet trust any host key for the server:
484 "client-sig-algs" SHOULD include all signature algorithms
485 supported and enabled by the client for use with any server.
487 * Otherwise, the client already trusts some host keys for the
488 server. In this case, if the client sends any "trusted-
489 fingerprint" fields, then "client-sig-algs" SHOULD include all
490 signature algorithms supported and enabled by the client for use
491 with any server.
493 * Otherwise, the client already trusts some host keys for the
494 server, but does not send any "trusted-fingerprint" fields. In
495 this case, "client-sig-algs" MUST include only signature
496 algorithms associated with the host keys the client already trusts
497 for this server.
499 There MAY be zero or more "trusted-fingerprint" fields. Each
500 "trusted-fingerprint" contains a binary fingerprint of a host key
501 that is trusted for this connection by the client. The fingerprint
502 algorithm is left unspecified. The server SHOULD try to match the
503 fingerprint using all algorithms it supports which produce the
504 provided fingerprint size. The current recommended fingerprint
505 algorithm is SHA-256, with fingerprint size 32 bytes. Servers MUST
506 tolerate the presence of unrecognized fingerprints of any size. The
507 preference order of trusted fingerprints is dominated by the
508 preference order of algorithms in "client-sig-algs".
510 The packet MUST include at least one SSH key exchange algorithm,
511 encoded as a pair of "client-kex-alg-name" and "client-kex-alg-data"
512 fields. The field "client-kex-alg-name" MUST specify a key exchange
513 method which would be valid in the field "kex_algorithms" in
514 SSH_MSG_KEXINIT under [RFC4253], Section 7.1. In addition, the key
515 exchange method MUST meet criteria in Section 3.
517 If the client wishes to simply advertise its support for a particular
518 key exchange algorithm, but does not prefer to use it in this
519 connection, it MAY enumerate the algorithm with empty "client-kex-
520 alg-data". Otherwise, if the client wishes to allow the algorithm to
521 be used, it MUST include non-empty "client-kex-alg-data". In this
522 case, "client-kex-alg-data" contains the client's portion of key
523 exchange inputs as specified in Section 3. The client MAY send
524 multiple key exchange algorithms with filled-out "client-kex-alg-
525 data". The client MUST send these algorithms in the order it prefers
526 the server to use them.
528 There MUST be at least one "quic-tls-cipher-suite" field. Each of
529 these specifies a TLS cipher suite ([RFC8446], Appendix B.4) which is
530 supported by the client, and which can be used with a version of QUIC
531 ([QUIC], [QUIC-TLS]) supported by the client. The client MUST
532 enumerate supported cipher suites in the order it prefers the server
533 to use them.
535 The client MAY send any number of extensions, encoded as a pair of
536 "ext-pair-name" and "ext-pair-data" fields. This memo defines no
537 extensions for SSH_QUIC_INIT, but see Section 2.8.1.
539 The "padding" field contains all 0xFF bytes to ensure that the
540 unencrypted "obfs-payload" for SSH_QUIC_INIT is at least 1200 bytes
541 in length. Servers MUST ignore smaller SSH_QUIC_INIT packets. This
542 is REQUIRED to prevent abuse of SSH_QUIC_INIT for Amplified
543 Reflection DDoS. If the unencrypted size of "obfs-payload" is
544 already 1200 bytes or larger, the padding MAY be omitted.
546 2.8.1. Extensibility
548 Implementations MUST allow room for future extensibility of
549 SSH_QUIC_INIT in the following manners:
551 1. By using a different packet type in the first byte -- this is, a
552 value other than 1 used by SSH_QUIC_INIT. Servers MUST NOT
553 penalize clients for sending unknown packet types unless there is
554 another reason to penalize the client, such as a blocked IP
555 address or the sheer volume of datagrams.
557 2. By including algorithms in "client-sig-algs" which are unknown to
558 or not supported by the server. Servers MUST tolerate the
559 presence of such algorithms.
561 3. By including fingerprints in "trusted-fingerprints" that use
562 algorithms or lengths that are unknown to or not supported by the
563 server. Servers MUST tolerate the presence of such fingerprints.
565 4. By including SSH key exchange algorithms which are unknown to or
566 not supported by the server, with algorithm data in a format
567 that's unknown to or not supported by the server. Servers MUST
568 tolerate the presence of such algorithms and their data.
570 5. By including QUIC TLS cipher suites which are unknown to or not
571 supported by the server. Servers MUST tolerate the presence of
572 such cipher suites.
574 6. By including extensions which are unknown to or not supported by
575 the server, with extension data in a format that's unknown to or
576 not supported by the server. Servers MUST tolerate the presence
577 of such extensions and their data.
579 Experience shows that any extensibility which is not actively
580 exercised is lost due to implementations that lock down expectations
581 incorrectly. Therefore, all clients MUST do at least one of the
582 following, in each SSH_QUIC_INIT packet, at random:
584 1. In the field "client-sig-algs", include in a random position at
585 least one Random Name (Section 2.6).
587 2. In the fields "client-quic-versions", include in a random
588 position a version number of the form 0x0A?A?A?A, where ?
589 indicates a random nibble. See [QUIC], section "Versions". Note
590 the difference from the random version pattern in the server's
591 SSH_QUIC_REPLY. Due to the minimal amount of entropy provided by
592 this rule, this MUST NOT be the only insertion of randomness made
593 in a packet.
595 3. Include in a random position at least one host key fingerprint
596 consisting of 16..255 Random Bytes (Section 2.6).
598 4. Include in a random position at least one SSH key exchange
599 algorithm where the field "client-kex-alg-name" contains a Random
600 Name, and the field "client-kex-alg-data" contains 0..1000 Random
601 Bytes.
603 5. In the fields "quic-tls-cipher-suite", include in a random
604 position at least one entry consisting of 16..255 Random Bytes.
606 6. In extension pairs, include in a random position at least one
607 extension where the field "ext-pair-name" contains a Random Name,
608 and the field "ext-pair-value" contains 0..1000 Random Bytes.
610 2.9. SSH_QUIC_REPLY
612 Implementations MUST take care to prevent abuse of the SSH/QUIC key
613 exchange for Amplified Reflection DDoS attacks. This means:
615 1. A server MUST NOT send more than one SSH_QUIC_REPLY in response
616 to any individual SSH_QUIC_INIT.
618 2. A server MUST NOT respond to any SSH_QUIC_INIT with unencrypted
619 "obfs-payload" smaller than 1200 bytes.
621 3. Before sending an SSH_QUIC_REPLY, the server MUST verify that the
622 reply is shorter than the SSH_QUIC_INIT packet to which it is
623 replying. If this is not the case, the server MUST send an Error
624 Reply (Section 2.9.1). Such an Error Reply MUST be shorter than
625 the SSH_QUIC_INIT packet.
627 SSH_QUIC_REPLY is an obfuscated datagram (Section 2.3) where "obfs-
628 payload" encrypts the following:
630 byte SSH_QUIC_REPLY = 2
631 short-str client-connection-id
632 short-str server-connection-id (Non-empty except on error)
634 byte v = nr-quic-versions (MUST NOT be zero)
635 uint32[v] server-quic-versions
637 string server-sig-algs (MUST NOT be empty)
638 string server-kex-algs (MUST NOT be empty)
640 byte c = nr-cipher-suites (MUST NOT be zero)
641 the following 1 field repeated c times:
642 short-str quic-tls-cipher-suite
644 byte e = nr-ext-pairs (see Extensibility)
645 the following 2 fields repeated e times:
646 short-str ext-pair-name (MUST NOT be empty)
647 string ext-pair-data (MAY be empty)
649 string server-kex-alg-data (Non-empty except on error)
651 Figure 7
653 SSH_QUIC_REPLY does not include an SSH version string or compression
654 negotiation. Instead, servers MUST use SSH_MSG_EXT_INFO for these
655 purposes. See Section 4.
657 SSH_QUIC_REPLY does not include a "cookie" field for random data.
658 Servers MUST insert random data using the packet's extensibility
659 mechanisms. See Section 2.9.2 and Section 2.6.
661 The field "client-connection-id" encodes the "client-connection-id"
662 sent by the client in SSH_QUIC_INIT.
664 The field "server-connection-id" contains a QUIC Connection ID of
665 length 1..20 bytes. The client will use this as the QUIC Destination
666 Connection ID in QUIC packets sent to the server. This field MUST be
667 empty if sending an Error Reply (Section 2.9.1), and MUST NOT be
668 empty otherwise.
670 The fields "server-quic-versions" enumerate QUIC protocol versions
671 supported by the server. The server MUST send at least one version.
672 The QUIC version used for the connection is the first version
673 enumerated in "client-quic-versions" which is also present in
674 "server-quic-versions". If there is no such version, see
675 Section 2.9.1.
677 The field "server-sig-algs" MUST contain at least one signature
678 algorithm supported by the server. The server SHOULD enumerate all
679 signature algorithms for which it has host keys. These are the same
680 algorithms as used in SSH_MSG_KEXINIT ([RFC4253], Section 7.1) in the
681 field "server_host_key_algorithms". In the SSH/QUIC key exchange,
682 the server MUST use a host key it possesses that (1) matches any
683 fingerprint enumerated in the "trusted-fingerprint" fields in
684 SSH_QUIC_INIT; and (2) can be used with the earliest possible
685 signature algorithm enumerated in "client-sig-algs". If there are
686 multiple such host keys, the client's preference order in "client-
687 sig-algs" dominates the preference order of "trusted-fingerprint".
688 If there is no such host key, the server MUST use any host key that
689 can be used with the earliest possible signature algorithm enumerated
690 in "client-sig-algs". If there is no such host key either, see
691 Section 2.9.1.
693 The field "server-kex-algs" MUST contain at least one SSH key
694 exchange algorithm supported by the server. The key exchange
695 algorithm which is used in the connection is the first algorithm sent
696 in client's SSH_QUIC_INIT where: (1) the field "client-kex-alg-data"
697 is non-empty, and (2) the algorithm is also present in "server-kex-
698 algs". If there is no such key exchange algorithm, see
699 Section 2.9.1.
701 There MUST be at least one "quic-tls-cipher-suite" field. Each of
702 these specifies a TLS cipher suite ([RFC8446], Appendix B.4) which is
703 supported by the server, and which can be used with a version of QUIC
704 ([QUIC], [QUIC-TLS]) supported by the server. The TLS cipher suite
705 which is used for the connection is the first suite sent in the
706 client's SSH_QUIC_INIT where: (1) the cipher suite is supported by
707 the negotiated QUIC protocol version, and (2) the cipher suite is
708 present in the server's SSH_QUIC_REPLY. If there is no such cipher
709 suite, see Section 2.9.1.
711 The server MAY send any number of extensions, encoded as a pair of
712 "ext-pair-name" and "ext-pair-data" fields. Some extensions are
713 defined for use with an Error Reply (see Section 2.9.1). Other
714 extensions MAY be defined in the future; see Section 2.9.2.
716 The field "server-kex-alg-data" MUST be empty if the packet is an
717 Error Reply. Otherwise, this field contains information for the SSH
718 key exchange method: see Section 3. Generally, this includes the
719 server's portion of key exchange inputs; the server's host key; and
720 the server's signature of the calculated exchange hash.
722 2.9.1. Error Reply
724 If a server encounters an error which it is useful and appropriate to
725 communicate to the client, the server MAY send an "Error Reply"
726 version of SSH_QUIC_REPLY. Such a reply is created as follows:
728 * The server includes and populates all fields of SSH_QUIC_REPLY as
729 it would normally, except that the fields "server-connection-id"
730 and "server-kex-alg-data" MUST remain empty.
732 * In the extension pair fields, a "disc-reason" Extension Pair MUST
733 be included. An "err-desc" Extension Pair MAY also be included.
734 See Section 2.7.
736 * Extensibility considerations for SSH_QUIC_REPLY in Section 2.9.2
737 also apply to an Error Reply.
739 If the server does not support any of the QUIC protocol versions
740 enumerated by the client, the server SHOULD send an Error Reply with
741 the disconnect reason code
742 SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED.
744 In the following circumstances, the server SHOULD send an Error Reply
745 with the disconnect reason code SSH_DISCONNECT_KEY_EXCHANGE_FAILED:
747 * If the server could have sent a successful SSH_QUIC_REPLY, but it
748 would have been larger than the client's SSH_QUIC_INIT, even
749 though the SSH_QUIC_INIT met or exceeded the minimum length.
751 * If the server possesses no server host key that can be used with a
752 signature algorithm enumerated in the client's SSH_QUIC_INIT.
754 * If the server supports no key exchange algorithms matching the
755 ones for which the client sent "client-kex-alg-data" in
756 SSH_QUIC_INIT.
758 * If the server supports no TLS cipher suites enumerated in the
759 client's SSH_QUIC_INIT.
761 Besides "disc-reason", an "err-desc" extension pair SHOULD be
762 included to describe the specific error.
764 2.9.2. Extensibility
766 Implementations MUST allow room for future extensibility of
767 SSH_QUIC_REPLY in the following manners:
769 1. By including algorithms in "server-sig-algs" which are unknown to
770 or not supported by the client. Clients MUST tolerate the
771 presence of such algorithms.
773 2. By including SSH key exchange algorithms which are unknown to or
774 not supported by the client, with algorithm data in a format
775 that's unknown to or not supported by the client. Clients MUST
776 tolerate the presence of such algorithms and their data.
778 3. By including QUIC TLS cipher suites which are unknown to or not
779 supported by the client. Clients MUST tolerate the presence of
780 such cipher suites.
782 4. By including extensions which are unknown to or not supported by
783 the client, with extension data in a format that's unknown to or
784 not supported by the client. Clients MUST tolerate the presence
785 of such extensions and their data.
787 Experience shows that any extensibility which is not actively
788 exercised is lost due to implementations that lock down expectations
789 incorrectly. Therefore, all servers MUST do at least one of the
790 following, in each SSH_QUIC_REPLY packet, at random:
792 1. In the fields "server-quic-versions", include in a random
793 position a version number of the form 0xFA?A?A?A, where ?
794 indicates a random nibble. See [QUIC], section "Versions". Note
795 the difference from the random version pattern in the client's
796 SSH_QUIC_INIT. Due to the minimal amount of entropy provided by
797 this rule, this MUST NOT be the only insertion of randomness made
798 in a packet.
800 2. In the field "server-sig-algs", include in a random position one
801 Random Name (Section 2.6).
803 3. In the field "server-kex-algs", include in a random position one
804 Random Name (Section 2.6).
806 4. In the fields "quic-tls-cipher-suite", include in a random
807 position one entry consisting of 16..64 Random Bytes.
809 5. In extension pairs, include in a random position one extension
810 pair where the field "ext-pair-name" contains a Random Name, and
811 the field "ext-pair-value" contains 0..100 Random Bytes.
813 2.10. SSH_QUIC_CANCEL
815 If a client cannot process the server's successful SSH_QUIC_REPLY,
816 the client SHOULD report the error to the server using
817 SSH_QUIC_CANCEL.
819 A client MUST NOT send an SSH_QUIC_CANCEL in response to an
820 SSH_QUIC_REPLY which is itself an Error Reply. A client MUST assume
821 that such a connection was already canceled by the server.
823 A client SHOULD send two or more copies of SSH_QUIC_CANCEL, in
824 transmissions separated by a fraction of a second, to increase the
825 likelihood of successful delivery. The server sends no
826 acknowledgment to SSH_QUIC_CANCEL. After the server has received
827 SSH_QUIC_CANCEL, it MUST ignore subsequent copies of SSH_QUIC_CANCEL
828 for the same connection.
830 SSH_QUIC_CANCEL is an obfuscated datagram (Section 2.3) where "obfs-
831 payload" encrypts the following:
833 byte SSH_QUIC_CANCEL = 3
834 short-str server-connection-id
836 byte e = nr-ext-pairs (see Extensibility)
837 the following 2 fields repeated e times:
838 short-str ext-pair-name (MUST NOT be empty)
839 string ext-pair-data (MAY be empty)
841 Figure 8
843 The "server-connection-id" field MUST equal the "server-connection-
844 id" field in the server's SSH_QUIC_REPLY.
846 In the extension pair fields, a "disc-reason" Extension Pair MUST be
847 included. An "err-desc" Extension Pair MAY also be included. See
848 Section 2.7.
850 2.10.1. Extensibility
852 Extensibility considerations also apply to SSH_QUIC_CANCEL:
854 * Clients MAY include extensions which are unknown to or not
855 supported by the server, with extension data in a format that's
856 unknown to or not supported by the server.
858 * Servers MUST tolerate the presence of such extensions and their
859 data.
861 * Clients SHOULD include, in a random position, at least one
862 extension pair where the field "ext-pair-name" contains a Random
863 Name, and the field "ext-pair-value" contains 0..300 Random Bytes.
865 3. Key Exchange Methods
867 Clients and servers MAY use any key exchange method which is defined
868 for SSH over TCP, whether it is assigned or private, as long as it
869 meets all of the following criteria:
871 1. The algorithm requires exactly one message from the client to the
872 server, for example SSH_MSG_KEX_ECDH_INIT. We call this message
873 KEXMSG_CLIENT.
875 2. The algorithm requires exactly one reply from the server to the
876 client, for example SSH_MSG_KEX_ECDH_REPLY. We call this message
877 KEXMSG_SERVER.
879 3. The algorithm specifies a hash function HASH, for example SHA-
880 256, SHA-384, or SHA-512.
882 4. The algorithm specifies calculation of an exchange hash H by
883 applying HASH to a concatenation of encoded fields.
885 5. The algorithm uses a server host key to sign H.
887 6. The algorithm includes the server's public host key, and the
888 signature of H, in its KEXMSG_SERVER message to the client.
890 7. The algorithm produces a shared secret K, represented as a signed
891 (positive or negative) multi-precision integer.
893 Any such algorithm is modified for use in SSH over QUIC as follows:
895 1. The field "client-kex-alg-data" in SSH_QUIC_INIT encodes the same
896 fields, in the same order, as KEXMSG_CLIENT, including the
897 leading byte for the SSH packet type.
899 2. The field "server-kex-alg-data" in SSH_QUIC_REPLY encodes the
900 same fields, in the same order, as KEXMSG_SERVER, including the
901 leading byte for the SSH packet type.
903 3. The calculation of H specified by the algorithm is not performed.
904 Instead, H is calculated by applying the hash function HASH to a
905 concatenation of the following:
907 byte[8] "SSH/QUIC"
909 string Unencrypted "obfs-payload" content of SSH_QUIC_INIT
911 string Unencrypted "obfs-payload" content of SSH_QUIC_REPLY,
912 excluding the entire field "server-kex-alg-data"
914 The fields of "server-kex-alg-data", excluding signature field
916 mpint K
918 Figure 9
920 When a field is excluded as above, the entire encoding of the field
921 is omitted: both the encoding of the content and the encoding of the
922 length.
924 The SSH packet type byte is included:
926 * To ensure there are at least two fields in the encoded content.
927 This avoids situations where an outer string (the field "client-
928 kex-alg-data") would contain a single inner string (from
929 KEXMSG_CLIENT). This could confuse implementers to incorrectly
930 encode a single string only.
932 * For future consistency. The packet type byte may be useful for
933 multiple-roundtrip key exchange methods, for example those using
934 GSS-API [RFC4462]. Such key exchange methods are not currently
935 defined for SSH/QUIC, but can be.
937 3.1. Required Key Exchange Methods
939 Clients and servers are REQUIRED to implement the key exchange method
940 "curve25519-sha256" [RFC8731]. All other key exchange methods are
941 optional.
943 Clients and servers MAY permit the user to disable a required key
944 exchange method. However, required methods MUST be enabled by
945 default.
947 The requirement to implement any particular key exchange method
948 expires on the 5-year anniversary of the publishing of this memo. At
949 that point, implementers SHOULD consult any new standards documents
950 if available, or survey the practical use of SSH/QUIC for
951 implementation guidance.
953 3.2. Example 1: "curve25519-sha256"
955 When using the SSH key exchange method "curve25519-sha256", the
956 SSH_QUIC_INIT field "client-kex-alg-data" is derived from
957 SSH_MSG_KEX_ECDH_INIT ([RFC5656], Section 4) and contains the
958 following:
960 byte SSH_MSG_KEX_ECDH_INIT = 30
961 string Q_C, client's ephemeral public key octet string
963 Figure 10
965 The SSH_QUIC_REPLY field "server-kex-alg-data" is derived from
966 SSH_MSG_KEX_ECDH_REPLY and contains the following:
968 byte SSH_MSG_KEX_ECDH_REPLY = 31
969 string K_S, server's public host key
970 string Q_S, server's ephemeral public key octet string
971 string the signature on the exchange hash
973 Figure 11
975 The shared secret K is calculated as in [RFC8731]. Then the exchange
976 hash H is calculated by applying SHA-256 to a concatenation of the
977 following:
979 string Content of SSH_QUIC_INIT
980 string Content of SSH_QUIC_REPLY, except "server-kex-alg-data"
981 byte SSH_MSG_KEX_ECDH_REPLY = 31
982 string K_S, server's public host key
983 string Q_S, server's ephemeral public key octet string
984 mpint K
986 Figure 12
988 3.3. Example 2: "diffie-hellman-group14-sha256"
990 When using the SSH key exchange method "diffie-hellman-
991 group14-sha256" [RFC8268], the SSH_QUIC_INIT field "client-kex-alg-
992 data" is derived from SSH_MSG_KEXDH_INIT ([RFC4253], Section 8) and
993 contains the following:
995 byte SSH_MSG_KEXDH_INIT = 30
996 mpint e
998 Figure 13
1000 The SSH_QUIC_REPLY field "server-kex-alg-data" is derived from
1001 SSH_MSG_KEXDH_REPLY and contains the following:
1003 byte SSH_MSG_KEXDH_REPLY = 31
1004 string server public host key and certificates (K_S)
1005 mpint f
1006 string signature of H
1008 Figure 14
1010 The shared secret K is calculated as in [RFC4253]. Then the exchange
1011 hash H is calculated by applying SHA-256 to a concatenation of the
1012 following:
1014 string Content of SSH_QUIC_INIT
1015 string Content of SSH_QUIC_REPLY, except "server-kex-alg-data"
1016 byte SSH_MSG_KEXDH_REPLY = 31
1017 string server public host key and certificates (K_S)
1018 mpint f
1019 mpint K
1021 Figure 15
1023 4. SSH_MSG_EXT_INFO and the SSH Version String
1025 A common user complaint to SSH application authors is that SSH over
1026 TCP sends the application version in plain text. The application
1027 version cannot be omitted, otherwise implementations cannot support a
1028 number of behaviors which other software versions implement
1029 incorrectly.
1031 A prominent example is the order of arguments in the SFTP request
1032 SSH_FXP_SYMLINK. To send a request that will have the desired
1033 effects, the client MUST consult the server's version string to know
1034 whether the server uses the standard order of fields, or a reverse
1035 order used by OpenSSH.
1037 SSH over QUIC removes the version string from the SSH key exchange.
1038 Instead, all clients and servers are REQUIRED to send and accept
1039 SSH_MSG_EXT_INFO [RFC8308], and to include the "ssh-version"
1040 extension defined here.
1042 Clients MUST send SSH_MSG_EXT_INFO as the very first SSH packet over
1043 QUIC stream 0. The client MUST include the "ssh-version" extension
1044 in this SSH_MSG_EXT_INFO.
1046 Servers MUST send SSH_MSG_EXT_INFO either:
1048 1. as the very first SSH packet over QUIC stream 0, and/or
1050 2. immediately preceding the server's SSH_MSG_USERAUTH_SUCCESS.
1052 A server MUST include the "ssh-version" extension in at least one of
1053 its SSH_MSG_EXT_INFO. If the server sends SSH_MSG_EXT_INFO at both
1054 opportunities, it MAY omit "ssh-version" at the first opportunity,
1055 but only if it will send it in the second opportunity. The second
1056 SSH_MSG_EXT_INFO sent by the server MAY change a previously sent
1057 "ssh-version" extension value to include more specific detail. For
1058 example, the server MAY send a more accurate server software version
1059 when the client has authenticated. The client MUST use the "ssh-
1060 version" value which was most recently received from the server.
1062 4.1. "ssh-version"
1064 The "ssh-version" extension is encoded in SSH_MSG_EXT_INFO as
1065 follows:
1067 string "ssh-version"
1068 string ssh-version-string
1070 Figure 16
1072 The extension value, "ssh-version-string", contains the same SSH
1073 version string as sent at the start of SSH over TCP ([RFC4253],
1074 Section 4.2), but stripping the prefix "SSH-2.0-". Examples inspired
1075 by version strings used in practice:
1077 GenericSoftware
1078 Product_1.2.00
1079 0.12 Library: Application 1.23p1
1081 Figure 17
1083 4.2. "no-flow-control"
1085 The extension "no-flow-control" has no effect in SSH/QUIC. It SHOULD
1086 NOT be sent in SSH/QUIC and MUST be ignored by both parties.
1088 4.3. "delay-compression"
1090 Semantics of the "delay-compression" extension are modified as per
1091 Section 6.1.1.
1093 5. QUIC Session Setup
1095 When the server has sent its SSH_QUIC_REPLY, and when the client has
1096 received it, they each initialize the QUIC session [QUIC] [QUIC-TLS]
1097 as follows:
1099 * The QUIC protocol version is set to the first version advertised
1100 in the client's SSH_QUIC_INIT which is also present in the
1101 server's SSH_QUIC_REPLY.
1103 * Session state is set as if a TLS handshake had just completed.
1105 * The TLS cipher suite is set to the first TLS cipher suite
1106 advertised in SSH_QUIC_INIT which is also present in
1107 SSH_QUIC_REPLY.
1109 * The QUIC Key Phase bit is set to 0.
1111 * The shared secrets that would have been obtained from the TLS
1112 handshake are instead generated from the SSH key exchange
1113 (Section 5.1).
1115 Clients and servers MUST immediately begin to use QUIC Short Header
1116 Packets. Implementations MUST NOT send QUIC Long Header Packets,
1117 since they could be confused with the SSH/QUIC key exchange.
1119 5.1. Shared Secrets
1121 QUIC-TLS [QUIC-TLS] uses a client secret and a server secret from
1122 which it generates an AEAD key, an IV, and a header protection key
1123 for each sending direction.
1125 An SSH key exchange produces a shared secret K, represented as an SSH
1126 multi-precision integer, and an exchange digest H, represented as
1127 binary data [RFC4253]. An SSH key exchange is parameterized with a
1128 hash function we call HASH. Note that HASH can be a different hash
1129 function, producing a different hash length, than the hash function
1130 used by the negotiated TLS cipher suite.
1132 To compute the initial QUIC client and server secrets, the client and
1133 server encode the following binary data, which we call "secret_data":
1135 mpint K
1136 string H
1138 Figure 18
1140 The client and server secrets are then calculated as follows:
1142 client_secret = HMAC-HASH("ssh/quic client", secret_data)
1143 server_secret = HMAC-HASH("ssh/quic server", secret_data)
1145 Figure 19
1147 The HMAC construct is as specified in [RFC2104], instantiated using
1148 the SSH key exchange hash function, HASH.
1150 QUIC keys and IVs are derived from these secrets using the regular
1151 QUIC-TLS key derivation process [QUIC-TLS]. Keys generated from
1152 these secrets are considered 1-RTT keys.
1154 Clients and servers MUST implement QUIC key updates using the regular
1155 QUIC-TLS key update process [QUIC-TLS], respecting the QUIC-TLS
1156 minimum key update frequencies.
1158 6. Adaptation of SSH to QUIC Streams
1160 6.1. SSH/QUIC Packet Format
1162 Each side serializes its SSH packets for sending over QUIC as
1163 follows:
1165 uint32 n = payload-len, high bit set if compressed
1166 byte[n] payload (compressed or uncompressed)
1168 Figure 20
1170 Since security is provided by QUIC-TLS [QUIC-TLS], MAC and random
1171 padding are omitted at this stage.
1173 The "payload-len" field has its high bit set if the "payload" field
1174 is compressed. See Section 6.1.1.
1176 The "payload" field contains the same packet information as the
1177 "payload" field in the Binary Packet Protocol defined in [RFC4253].
1179 6.1.1. Compression
1181 Compression MAY be negotiated using the "delay-compression" extension
1182 in [RFC8308]. If "delay-compression" was negotiated, then:
1184 * If compression is enabled for the server-to-client direction, the
1185 server MAY compress packets on any stream after it has sent
1186 SSH_MSG_USERAUTH_SUCCESS.
1188 * If compression is enabled for the client-to-server direction, the
1189 client MAY compress packets on any stream after it has received
1190 SSH_MSG_USERAUTH_SUCCESS.
1192 Due to multiple streams in SSH/QUIC, the packet SSH_MSG_NEWCOMPRESS
1193 is not an effective mechanism to signal the start of compression and
1194 MUST NOT be sent. It is replaced by the high bit in "payload-len".
1196 6.2. Use of QUIC Streams
1198 To avoid an unnecessary layer of flow control which has performance
1199 and complexity impacts in SSH over TCP, SSH/QUIC uses QUIC streams
1200 for SSH channels and dispenses with flow control on the level of SSH
1201 channels. This simplifies future SSH/QUIC implementations which
1202 might not implement SSH over TCP.
1204 Conducting SSH channels over QUIC streams requires modifications of
1205 the SSH Connection Protocol [RFC4254]. The following sections
1206 describe these modifications.
1208 6.3. Packet Sequence Numbers
1210 In SSH over TCP, every SSH packet has an implicit sequence number
1211 which is unique for the direction of sending (to server vs. to
1212 client). The packet type SSH_MSG_UNIMPLEMENTED makes reference to
1213 this sequence number.
1215 In SSH/QUIC, sequence numbers are separate for each sending
1216 direction, as well as each QUIC stream. This requires modification
1217 of SSH_MSG_UNIMPLEMENTED. This packet type is changed as follows:
1219 byte SSH_MSG_UNIMPLEMENTED
1220 uint64 QUIC stream ID on which the packet was received
1221 uint32 packet sequence number in stream, first packet = 0
1223 Figure 21
1225 6.4. Channel IDs
1227 SSH over TCP uses 32-bit channel IDs which can be reused in the same
1228 session and do not have to be used sequentially. Conflicts in
1229 channel IDs are avoided by identifying each channel with two separate
1230 channel IDs: one designated by the sender and one by the recipient.
1231 [RFC4254]
1232 QUIC streams use 62-bit channel IDs which cannot be reused and MUST
1233 be used sequentially. Both sides use the same stream ID. Conflicts
1234 in stream IDs are avoided by using the least significant bit to
1235 indicate whether the stream was opened by the client or by the
1236 server. [QUIC]
1238 SSH/QUIC uses QUIC stream IDs. This requires modification of SSH
1239 channel-related packets. See Section 6.8.
1241 6.5. Disconnection
1243 The SSH packet type SSH_MSG_DISCONNECT is replaced by sending the
1244 QUIC frame CONNECTION_CLOSE of type 0x1d. The "Error Code" field in
1245 CONNECTION_CLOSE contains the value that would have been sent in the
1246 "reason code" in SSH_MSG_DISCONNECT. The "Reason Phrase" field in
1247 CONNECTION_CLOSE contains the value that would have been sent in
1248 "description" in SSH_MSG_DISCONNECT. The "language tag" field of
1249 SSH_MSG_DISCONNECT is not sent.
1251 6.6. Prohibited SSH Packets
1253 In SSH/QUIC, the following SSH packet types MUST NOT be sent:
1255 SSH_MSG_DISCONNECT 1
1256 SSH_MSG_NEWCOMPRESS 8
1258 SSH_MSG_KEXINIT 20
1259 SSH_MSG_NEWKEYS 21
1260 key exchange packets 30-49
1262 SSH_MSG_CHANNEL_WINDOW_ADJUST 93
1263 SSH_MSG_CHANNEL_CLOSE 97
1265 Figure 22
1267 If they receive packets of these types, clients and servers MAY
1268 disconnect with SSH_DISCONNECT_PROTOCOL_ERROR (Section 6.5).
1269 Alternately, the receiver MAY send SSH_MSG_UNIMPLEMENTED
1270 (Section 6.3).
1272 6.7. Global SSH Packets
1274 In SSH/QUIC, the following SSH packet types MUST be sent on QUIC
1275 stream 0. With the exception of SSH_MSG_UNIMPLEMENTED (Section 6.3),
1276 these packets use the same encoded formats as in SSH over TCP:
1278 SSH_MSG_IGNORE 2
1279 SSH_MSG_UNIMPLEMENTED 3 (Changed format!)
1280 SSH_MSG_DEBUG 4
1281 SSH_MSG_SERVICE_REQUEST 5
1282 SSH_MSG_SERVICE_ACCEPT 6
1283 SSH_MSG_EXT_INFO 7
1285 SSH_MSG_USERAUTH_REQUEST 50
1286 SSH_MSG_USERAUTH_FAILURE 51
1287 SSH_MSG_USERAUTH_SUCCESS 52
1288 SSH_MSG_USERAUTH_BANNER 53
1289 SSH_MSG_USERAUTH_INFO_REQUEST 60
1290 SSH_MSG_USERAUTH_INFO_RESPONSE 61
1292 SSH_MSG_GLOBAL_REQUEST 80
1293 SSH_MSG_REQUEST_SUCCESS 81
1294 SSH_MSG_REQUEST_FAILURE 82
1296 Figure 23
1298 6.8. SSH Channel Packets
1300 All SSH/QUIC channels MUST be opened as bidirectional QUIC streams.
1301 This means QUIC stream IDs where the least significant bits are 10 or
1302 11 MUST NOT be used in SSH/QUIC. Implementations that receive such
1303 stream IDs MUST disconnect with SSH_DISCONNECT_PROTOCOL_ERROR
1304 (Section 6.5)
1306 A client MUST NOT open a non-zero QUIC stream before the server has
1307 sent SSH_MSG_USERAUTH_SUCCESS. If a client does so, the server MUST
1308 disconnect with SSH_DISCONNECT_PROTOCOL_ERROR.
1310 A server MUST NOT open a non-zero QUIC stream before it has sent
1311 SSH_MSG_USERAUTH_SUCCESS. However, a client MUST be prepared for the
1312 possibility that, due to network delays, a stream opened by the
1313 server can be received by the client before SSH_MSG_USERAUTH_SUCCESS.
1314 Therefore, if the client receives a server-initiated stream before
1315 SSH_MSG_USERAUTH_SUCCESS, it MUST assume that the server has also
1316 sent SSH_MSG_USERAUTH_SUCCESS. If the client then receives packets
1317 on QUIC stream 0 which invalidate this assumption, the client MUST
1318 disconnect with SSH_DISCONNECT_PROTOCOL_ERROR.
1320 The initiator of any non-zero QUIC stream MUST send
1321 SSH_MSG_CHANNEL_OPEN as the first packet. If the receiver refuses
1322 the channel, it replies with SSH_MSG_CHANNEL_OPEN_FAILURE. Both
1323 sides then MUST close the QUIC stream as per Section 6.9. In this
1324 case, even though a QUIC stream was opened, an SSH channel was not.
1325 Therefore, other SSH_MSG_CHANNEL_xxxx packets MUST NOT be sent. This
1326 includes SSH_MSG_CHANNEL_EOF.
1328 If the receiver accepts the channel, it replies with
1329 SSH_MSG_CHANNEL_OPEN_CONFIRMATION. Both sides then send SSH packets
1330 of types SSH_MSG_CHANNEL_xxxx. In SSH/QUIC, these packets have the
1331 following formats:
1333 byte SSH_MSG_CHANNEL_OPEN
1334 string channel type in US-ASCII only
1335 uint32 maximum packet size
1336 .... channel-type-specific data follows
1338 Figure 24
1340 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION
1341 uint32 maximum packet size
1342 .... channel-type-specific data follows
1344 Figure 25
1346 byte SSH_MSG_CHANNEL_OPEN_FAILURE
1347 uint32 reason code
1348 string description in UTF-8
1349 string language tag
1351 Figure 26
1353 byte SSH_MSG_CHANNEL_DATA
1354 string data
1356 Figure 27
1358 byte SSH_MSG_CHANNEL_EXTENDED_DATA
1359 uint32 data_type_code
1360 string data
1362 Figure 28
1364 byte SSH_MSG_CHANNEL_EOF
1366 Figure 29
1368 byte SSH_MSG_CHANNEL_REQUEST
1369 string request type in US-ASCII characters only
1370 boolean want reply
1371 .... type-specific data follows
1373 Figure 30
1375 byte SSH_MSG_CHANNEL_SUCCESS
1377 Figure 31
1379 byte SSH_MSG_CHANNEL_FAILURE
1381 Figure 32
1383 6.9. Closing a Channel
1385 The SSH packet type SSH_MSG_CHANNEL_CLOSE is replaced by QUIC stream
1386 state transitions [QUIC]. Each side considers a channel closed when
1387 the QUIC stream is both in a terminal sending state, and a terminal
1388 receiving state. This means:
1390 * The QUIC sending stream state has become "Data Recvd" or "Reset
1391 Recvd".
1393 * The QUIC receiving stream state has become "Data Read" or "Reset
1394 Read".
1396 The SSH packet type SSH_MSG_CHANNEL_EOF continues to be used. This
1397 packet often does NOT correspond with the end of the stream in its
1398 direction. As in SSH over TCP, SSH channel requests MAY be sent
1399 after SSH_MSG_CHANNEL_EOF, and MUST be handled gracefully by
1400 receivers. A common example is the request "exit-status", which is
1401 sent by a server to communicate a process exit code to the SSH
1402 client, and is commonly sent after the end of output.
1404 7. Acknowledgements
1406 Paul Ebermann for first review and the encouragement to use QUIC
1407 streams.
1409 Ilari Liusvaara for "server-name-indication" and value 1200 for
1410 SSH_QUIC_INIT padding target.
1412 Benjamin Kaduk for idea of additional cross-protocol protection in
1413 the calculation of H.
1415 Stephane Bortzmeyer for the PRECIS Framework to handle the
1416 obfuscation keyword.
1418 8. IANA Considerations
1420 This document requests no changes to IANA registries.
1422 9. Security Considerations
1424 Clients and servers MUST insert into SSH_QUIC_INIT and SSH_QUIC_REPLY
1425 at least the minimum amount of cryptographically random data as
1426 specified in the section Random Elements. Compromising on this
1427 requirement reduces the security of any session created on the basis
1428 of such an SSH_QUIC_INIT or SSH_QUIC_REPLY.
1430 10. References
1432 10.1. Normative References
1434 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed
1435 and Secure Transport", 2020, .
1438 [QUIC-TLS] Thomson, M. and S. Turner, "Using TLS to Secure QUIC",
1439 2020,
1440 .
1442 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
1443 Hashing for Message Authentication", RFC 2104,
1444 DOI 10.17487/RFC2104, February 1997,
1445 .
1447 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1448 Requirement Levels", BCP 14, RFC 2119,
1449 DOI 10.17487/RFC2119, March 1997,
1450 .
1452 [RFC4251] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
1453 Protocol Architecture", RFC 4251, DOI 10.17487/RFC4251,
1454 January 2006, .
1456 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
1457 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253,
1458 January 2006, .
1460 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
1461 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008,
1462 .
1464 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm
1465 Integration in the Secure Shell Transport Layer",
1466 RFC 5656, DOI 10.17487/RFC5656, December 2009,
1467 .
1469 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
1470 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
1471 May 2017, .
1473 [RFC8264] Saint-Andre, P. and M. Blanchet, "PRECIS Framework:
1474 Preparation, Enforcement, and Comparison of
1475 Internationalized Strings in Application Protocols",
1476 RFC 8264, DOI 10.17487/RFC8264, October 2017,
1477 .
1479 [RFC8265] Saint-Andre, P. and A. Melnikov, "Preparation,
1480 Enforcement, and Comparison of Internationalized Strings
1481 Representing Usernames and Passwords", RFC 8265,
1482 DOI 10.17487/RFC8265, October 2017,
1483 .
1485 [RFC8308] Bider, D., "Extension Negotiation in the Secure Shell
1486 (SSH) Protocol", RFC 8308, DOI 10.17487/RFC8308, March
1487 2018, .
1489 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
1490 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
1491 .
1493 [RFC8731] Adamantiadis, A., Josefsson, S., and M. Baushke, "Secure
1494 Shell (SSH) Key Exchange Method Using Curve25519 and
1495 Curve448", RFC 8731, DOI 10.17487/RFC8731, February 2020,
1496 .
1498 10.2. Informative References
1500 [IANA-SSH] IANA, "Secure Shell (SSH) Protocol Parameters",
1501 .
1503 [RFC4250] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell (SSH)
1504 Protocol Assigned Numbers", RFC 4250,
1505 DOI 10.17487/RFC4250, January 2006,
1506 .
1508 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
1509 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252,
1510 January 2006, .
1512 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
1513 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254,
1514 January 2006, .
1516 [RFC4462] Hutzelman, J., Salowey, J., Galbraith, J., and V. Welch,
1517 "Generic Security Service Application Program Interface
1518 (GSS-API) Authentication and Key Exchange for the Secure
1519 Shell (SSH) Protocol", RFC 4462, DOI 10.17487/RFC4462, May
1520 2006, .
1522 [RFC8268] Baushke, M., "More Modular Exponentiation (MODP) Diffie-
1523 Hellman (DH) Key Exchange (KEX) Groups for Secure Shell
1524 (SSH)", RFC 8268, DOI 10.17487/RFC8268, December 2017,
1525 .
1527 Appendix A. Generating Random Lengths
1529 The SSH/QUIC extensibility mechanism calls for generating random
1530 lengths such that values in the shorter end of the range are
1531 significantly more probable, but long lengths are still selected.
1532 The following C example shows a simple two-step process to prefer
1533 shorter lengths:
1535 int RandomIntBetweenZeroAnd(int maxValueInclusive);
1537 int RandomLen_PreferShort(int minLen, int maxLen)
1538 {
1539 int const SPAN_THRESHOLD = 7;
1540 int lenSpan = maxLen - minLen;
1542 if (lenSpan <= 0)
1543 return minLen;
1545 if (lenSpan > SPAN_THRESHOLD)
1546 if (0 != RandomIntBetweenZeroAnd(3))
1547 return minLen + RandomIntBetweenZeroAnd(SPAN_THRESHOLD);
1549 return minLen + RandomIntBetweenZeroAnd(lenSpan);
1550 }
1552 Figure 33
1554 Author's Address
1555 denis bider
1556 Bitvise Limited
1557 4105 Lombardy Ct
1558 Colleyville, TX 76034
1559 United States
1561 Email: ietf-draft@denisbider.com