idnits 2.17.1
draft-bider-ssh-quic-02.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 297 has weird spacing: '...ort-str clie...'
== Line 306 has weird spacing: '...ort-str trus...'
== Line 310 has weird spacing: '...ort-str clie...'
== Line 315 has weird spacing: '...ort-str quic...'
== Line 319 has weird spacing: '...ort-str ext-...'
== (6 more instances...)
-- The document date (7 July 2020) is 1360 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
== Unused Reference: 'RFC4250' is defined on line 1018, 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 (==), 1 comment (--).
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 7 July 2020
5 Expires: 8 January 2021
7 QUIC-based UDP Transport for Secure Shell (SSH)
8 draft-bider-ssh-quic-02
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 its transport to UDP-based QUIC [QUIC]. These include:
17 unauthenticated network intermediaries can trivially disconnect SSH
18 sessions; SSH connections are lost when mobile clients change IP
19 addresses; performance limitations in OS-based TCP stacks; and many
20 round-trips to establish the connection. This memo specifies SSH key
21 exchange over UDP and leverages QUIC to provide a UDP-based
22 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 8 January 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 . . . . . . . . . . . . . . . . . . . . . . . . 2
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 . . . . . . . . . . . . . . . . . . . . . . 3
62 2.3. Packet Limits . . . . . . . . . . . . . . . . . . . . . . 4
63 2.4. Required TLS Cipher Suites . . . . . . . . . . . . . . . 4
64 2.5. Random Elements . . . . . . . . . . . . . . . . . . . . . 4
65 2.6. Errors in Key Exchange . . . . . . . . . . . . . . . . . 6
66 2.6.1. "disc-reason" Extension Pair . . . . . . . . . . . . 6
67 2.6.2. "err-desc" Extension Pair . . . . . . . . . . . . . . 6
68 2.7. SSH_QUIC_INIT . . . . . . . . . . . . . . . . . . . . . . 6
69 2.7.1. Extensibility . . . . . . . . . . . . . . . . . . . . 9
70 2.8. SSH_QUIC_REPLY . . . . . . . . . . . . . . . . . . . . . 10
71 2.8.1. Error Reply . . . . . . . . . . . . . . . . . . . . . 12
72 2.8.2. Extensibility . . . . . . . . . . . . . . . . . . . . 13
73 2.9. SSH_QUIC_CANCEL . . . . . . . . . . . . . . . . . . . . . 14
74 2.9.1. Extensibility . . . . . . . . . . . . . . . . . . . . 15
75 3. Key Exchange Methods . . . . . . . . . . . . . . . . . . . . 15
76 3.1. Required Key Exchange Methods . . . . . . . . . . . . . . 17
77 3.2. Example: "curve25519-sha256" . . . . . . . . . . . . . . 17
78 4. SSH_MSG_EXT_INFO and the SSH Version String . . . . . . . . . 18
79 4.1. "ssh-version" Extension . . . . . . . . . . . . . . . . . 18
80 5. QUIC Session Setup . . . . . . . . . . . . . . . . . . . . . 19
81 5.1. Shared Secrets . . . . . . . . . . . . . . . . . . . . . 19
82 6. SSH/QUIC Packet Format . . . . . . . . . . . . . . . . . . . 20
83 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
84 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21
85 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
86 9.1. Normative References . . . . . . . . . . . . . . . . . . 21
87 9.2. Informative References . . . . . . . . . . . . . . . . . 22
88 Appendix A. Generating Random Lengths . . . . . . . . . . . . . 22
89 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 23
91 1. Introduction
93 THIS DOCUMENT IS AN EARLY VERSION AND IS A WORK IN PROGRESS.
95 NON-LATEST DRAFT VERSIONS MUST BE DISREGARDED.
97 IMPLEMENTATION AT THIS STAGE IS EXPERIMENTAL.
99 CONTACT THE AUTHOR IF YOU INTEND TO IMPLEMENT.
101 This memo specifies SSH key exchange over UDP, and then leverages
102 QUIC to provide a UDP-based transport for SSH. QUIC's use of the TLS
103 handshake is replaced with a 1-RTT SSH/QUIC key exchange. The SSH
104 Authentication Protocol [RFC4252] and the SSH Connection Protocol
105 [RFC4254] are then conducted over UDP stream 0 in the same way as
106 they would be over TCP.
108 1.1. Requirements Terminology
110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
112 "OPTIONAL" in this document are to be interpreted as described in
113 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
114 capitals, as shown here.
116 2. SSH/QUIC key exchange
118 2.1. Distinguishing SSH key exchange from QUIC datagrams
120 UDP datagrams which form the SSH/QUIC key exchange are sent between
121 the same client and server IP addresses and ports as QUIC datagrams.
122 It is therefore necessary for clients and servers to distinguish SSH
123 key exchange datagrams from QUIC datagrams.
125 A distinction is allowed by that SSH/QUIC only requires the sending
126 of QUIC Short Header Packets. Therefore, all UDP datagrams where the
127 first byte has its high bit set can be handled as part of an SSH/QUIC
128 key exchange.
130 2.2. Wire Encoding
132 This memo uses wire encoding types "byte", "uint32", "mpint" and
133 "string" with meanings as described in [RFC4251].
135 This memo defines a new wire encoding type "short-str", encoded as
136 follows:
138 byte n = short-str-len (unsigned, 0..255)
139 byte[n] short-str-value
141 Figure 1
143 2.3. Packet Limits
145 Clients and servers MUST accept SSH_QUIC_INIT, SSH_QUIC_REPLY and
146 SSH_QUIC_CANCEL packets of sizes at least up to 32768 bytes. This
147 corresponds to minimum SSH packet limits which implementations must
148 support as per [RFC4253], Section 6.1.
150 2.4. Required TLS Cipher Suites
152 Clients and servers are REQUIRED to implement the TLS cipher suites
153 TLS_AES_128_GCM_SHA256 and TLS_AES_256_GCM_SHA384 [RFC8446]. Other
154 cipher suites are optional.
156 Clients and servers MAY permit the user to disable a required cipher
157 suite. However, required suites MUST be enabled by default.
159 2.5. Random Elements
161 Unlike SSH over TCP, the packets SSH_QUIC_INIT and SSH_QUIC_REPLY do
162 not provide a "cookie" field for random data. Instead, clients and
163 servers MUST insert random data using the Extensibility mechanisms.
165 At the very minimum, clients and servers MUST insert at least 16
166 Random Bytes or at least one Random Name, in locations as described
167 in Section 2.7.1 and Section 2.8.2. If at all possible, the random
168 data MUST come from a cryptographically strong random source.
169 Implementations that are unable to meet this requirement MUST still
170 insert the minimum amount of random data, as unpredictably as they
171 are able. Compromising on this requirement reduces the security of
172 any sessions created on the basis of such SSH_QUIC_INIT and
173 SSH_QUIC_REPLY.
175 Lengths of Random Names and Random Bytes SHOULD be chosen at random
176 such that lengths in the shorter end of the range are significantly
177 more probable, but long lengths are still selected. See Appendix A.
179 Random Bytes
181 Random Bytes are generated with values 0..255, in a range of lengths
182 as specified for the particular usage context.
184 Random Name
186 A Random Name is generated in one of two forms: Assigned Form or
187 Private Form. One of the two forms is randomly chosen so that
188 Assigned Form, which is shorter, is more likely. The maximum length
189 of a Random Name is 64 bytes.
191 Assigned Form
193 A Random Name in Assigned Form is generated as a string of random
194 characters with ASCII values 33..126 (inclusive), except @ and the
195 comma (","). Other characters MUST NOT be included. To avoid
196 collisions as effectively as a random UUID, a Random Name in Assigned
197 Form MUST contain at least 20 random characters if using the complete
198 character set. A Random Name in Assigned Form MUST then be of length
199 20..64 bytes.
201 Implementations MAY remove up to 7 characters from the character set
202 -- reducing it to 85..91 characters -- without increasing the minimum
203 length. If the character set is further reduced to 69..84
204 characters, implementations MUST generate at least 21 random
205 characters instead.
207 Example Random Names in Assigned Form:
209 d`kbi>AGrj~r{3lo_Q4r
210 wNT)=/8C<(DB1|tr:>1f[xq>9bG
211 u7^dE'\EE_}N}^"J5syI?/8jIxup#s7BM:]>{IT_p3Z~wJDYIBX.4zzQ$@denisbider.com
225 ?`z4bb/}
&Wuf6O7CE?cA`$j"@bider.us
227 Figure 3
229 Alternately, implementations MAY generate a Random Name in Anonymous
230 Form with the format "(local)@(domain).example.com". In this case,
231 both "(local)" and "(domain)" are replaced by random ASCII characters
232 from the set A..Z, a..z, and 0..9. This is to ensure that the suffix
233 has valid domain name syntax.
235 To avoid collisions as effectively as a random UUID, a Random Name in
236 Anonymous Form MUST contain at least 22 random characters. A Random
237 Name in Anonymous Form MUST then be of length 35..64 bytes.
239 2.6. Errors in Key Exchange
241 To assist users, clients and servers SHOULD report key exchange
242 errors as follows:
244 1. If a server cannot send a successful SSH_QUIC_REPLY, it SHOULD
245 send an Error Reply. See Section 2.8.1.
247 2. If a client receives an invalid SSH_QUIC_REPLY, it SHOULD send an
248 SSH_QUIC_CANCEL. See Section 2.9.
250 Both packet types use the following extension pairs.
252 2.6.1. "disc-reason" Extension Pair
254 "ext-pair-name" contains "disc-reason".
256 "ext-pair-data" encodes a uint32 with the SSH disconnect reason code.
257 Reason codes are defined in the table "Disconnect Messages Reason
258 Codes and Descriptions" in the IANA registry "Secure Shell (SSH)
259 Protocol Parameters" [IANA-SSH].
261 2.6.2. "err-desc" Extension Pair
263 "ext-pair-name" contains "err-desc".
265 "ext-pair-data" encodes a human-readable error description in any
266 language intended to be relevant to the user, encoded as UTF-8.
268 Receivers that process error descriptions MUST validate that the
269 description is valid UTF-8. If a description is long, receivers
270 SHOULD truncate it to a reasonable length depending on the processing
271 context. For example, a debug log file can record a full 32 kB error
272 description, while a production log file SHOULD truncate it to a much
273 shorter length.
275 2.7. SSH_QUIC_INIT
277 A client begins an SSH/QUIC session by sending one or more copies of
278 SSH_QUIC_INIT. If multiple copies are sent, copies intended for the
279 same connection MUST be identical. A reasonable strategy is to send
280 one copy every 50 - 500 ms until the client receives a valid
281 SSH_QUIC_REPLY or times out. A server MUST remember recently
282 received SSH_QUIC_INIT packets and send identical SSH_QUIC_REPLY
283 responses. If different SSH_QUIC_INIT packets are received from the
284 same client IP address, the server MUST assume they are intended to
285 begin separate connections, even if they specify the same "client-
286 connection-id". A server MAY implement throttling of incoming
287 connections, by IP address or otherwise, where excessive
288 SSH_QUIC_INIT packets are disregarded. Once a server receives QUIC
289 data confirming that a client has processed an SSH_QUIC_REPLY, the
290 server MUST disregard any further identical copies of the same
291 SSH_QUIC_INIT, at least until the SSH/QUIC session started by such an
292 SSH_QUIC_INIT ends.
294 The SSH_QUIC_INIT packet is a UDP datagram with the following layout:
296 byte SSH_QUIC_INIT = 0x80 (see Extensibility)
297 short-str client-connection-id (MAY be empty)
299 byte v = nr-quic-versions (MUST NOT be zero)
300 uint32[v] client-quic-versions
302 string client-sig-algs (MUST NOT be empty)
304 byte f = nr-trusted-fingerprints (MAY be zero)
305 the following 1 field repeated f times:
306 short-str trusted-fingerprint (MUST NOT be empty)
308 byte k = nr-client-kex-algs (MUST NOT be zero)
309 the following 2 fields repeated k times:
310 short-str client-kex-alg-name (MUST NOT be empty)
311 string client-kex-alg-data (MUST NOT be empty)
313 byte c = nr-cipher-suites (MUST NOT be zero)
314 the following 1 field repeated c times:
315 short-str quic-tls-cipher-suite
317 byte e = nr-ext-pairs (see Extensibility)
318 the following 2 fields repeated e times:
319 short-str ext-pair-name (MUST NOT be empty)
320 string ext-pair-data (MAY be empty)
322 byte[0..] padding: all 0xFF to minimal packet size 1400
324 Figure 4
326 SSH_QUIC_INIT does not include an SSH version string. Instead,
327 clients MUST use SSH_MSG_EXT_INFO for this purpose. See Section 4.
329 SSH_QUIC_INIT does not include a "cookie" field for random data.
330 Clients MUST insert random data using Extensibility mechanisms. See
331 Section 2.7.1 and Section 2.5.
333 The field "client-connection-id" contains a QUIC Connection ID of
334 length 0..20 bytes. The server will use this as the QUIC Destination
335 Connection ID in QUIC packets sent to the client. Clients are not
336 required to use a Connection ID if they are using other means of
337 routing connections.
339 The fields "client-quic-versions" enumerate QUIC protocol versions
340 supported by the client. The client MUST send at least one version.
341 The client MUST send supported versions in the order it prefers the
342 server to use them.
344 The field "client-sig-algs" MUST contain at least one signature
345 algorithm supported by the client for server authentication. These
346 are the same algorithms as used in SSH_MSG_KEXINIT ([RFC4253],
347 Section 7.1) in the field "server_host_key_algorithms". The client
348 MUST send signature algorithms in the order it prefers the server to
349 use them.
351 There MAY be zero or more "trusted-fingerprint" fields. Each
352 "trusted-fingerprint" contains a binary fingerprint of a host key
353 that is trusted for this connection by the client. The fingerprint
354 algorithm is left unspecified. The server SHOULD try to match the
355 fingerprint using all algorithms it supports which produce the
356 provided fingerprint size. The current recommended fingerprint
357 algorithm is SHA-256, with fingerprint size 32 bytes. Servers MUST
358 tolerate the presence of unrecognized fingerprints of any size. The
359 preference order of trusted fingerprints is dominated by the
360 preference order in "client-sig-algs".
362 The packet MUST include at least one SSH key exchange algorithm,
363 encoded as a pair of "client-kex-alg-name" and "client-kex-alg-data"
364 fields. The field "client-kex-alg-name" MUST specify a key exchange
365 method which would be valid in the field "kex_algorithms" in
366 SSH_MSG_KEXINIT under [RFC4253], Section 7.1. In addition, the key
367 exchange method MUST meet criteria in Section 3.
369 If the client wishes to simply advertise its support for a particular
370 key exchange algorithm, but does not prefer to use it in this
371 connection, it MAY enumerate the algorithm with empty "client-kex-
372 alg-data". Otherwise, if the client wishes to allow the algorithm to
373 be used, it MUST include non-empty "client-kex-alg-data". In this
374 case, "client-kex-alg-data" contains the client's portion of key
375 exchange inputs as specified in Section 3. The client MAY send
376 multiple key exchange algorithms with filled-out "client-kex-alg-
377 data". The client MUST send these algorithms in the order it prefers
378 the server to use them.
380 There MUST be at least one "quic-tls-cipher-suite" field. Each of
381 these specifies a TLS cipher suite ([RFC8446], Appendix B.4) which is
382 supported by the client, and which can be used with a version of QUIC
383 ([QUIC], [QUIC-TLS]) supported by the client. The client MUST
384 enumerate supported cipher suites in the order it prefers the server
385 to use them.
387 The client MAY send any number of extensions, encoded as a pair of
388 "ext-pair-name" and "ext-pair-data" fields. This memo defines no
389 extensions, but see Section 2.7.1.
391 The "padding" field contains all 0xFF bytes to ensure SSH_QUIC_INIT
392 is at least 1400 bytes in length. Servers MUST ignore SSH_QUIC_INIT
393 packets with a UDP datagram size less than 1400 bytes. This is
394 REQUIRED to prevent abuse of SSH_QUIC_INIT for Amplified Reflection
395 DDoS. If the size of SSH_QUIC_INIT is already 1400 bytes or larger,
396 the padding MAY be omitted.
398 2.7.1. Extensibility
400 Implementations MUST allow room for future extensibility of
401 SSH_QUIC_INIT in the following manners:
403 1. By using a different packet type in the first byte -- this is, a
404 value other than 0x80 used by SSH_QUIC_INIT. Servers MUST NOT
405 penalize clients for sending unknown packet types unless there is
406 another reason to penalize the client, such as a blocked IP
407 address or the sheer volume of datagrams.
409 2. By including algorithms in "client-sig-algs" which are unknown to
410 or not supported by the server. Servers MUST tolerate the
411 presence of such algorithms.
413 3. By including fingerprints in "trusted-fingerprints" that use
414 algorithms or lengths that are unknown to or not supported by the
415 server. Servers MUST tolerate the presence of such fingerprints.
417 4. By including SSH key exchange algorithms which are unknown to or
418 not supported by the server, with algorithm data in a format
419 that's unknown to or not supported by the server. Servers MUST
420 tolerate the presence of such algorithms and their data.
422 5. By including QUIC TLS cipher suites which are unknown to or not
423 supported by the server. Servers MUST tolerate the presence of
424 such cipher suites.
426 6. By including extensions which are unknown to or not supported by
427 the server, with extension data in a format that's unknown to or
428 not supported by the server. Servers MUST tolerate the presence
429 of such extensions and their data.
431 Experience shows that any extensibility which is not actively
432 exercised is lost due to implementations that lock down expectations
433 incorrectly. Therefore, all clients MUST do at least one of the
434 following, in each SSH_QUIC_INIT packet, at random:
436 1. In the field "client-sig-algs", include in a random position at
437 least one Random Name (Section 2.5).
439 2. In the fields "client-quic-versions", include in a random
440 position a version number of the form 0x0A?A?A?A, where ?
441 indicates a random nibble. See [QUIC], section "Versions". Note
442 the difference from the random version pattern in the server's
443 SSH_QUIC_REPLY. Due to the minimal amount of entropy provided by
444 this rule, this MUST NOT be the only insertion of randomness made
445 in a packet.
447 3. Include in a random position at least one host key fingerprint
448 consisting of 16..255 Random Bytes (Section 2.5).
450 4. Include in a random position at least one SSH key exchange
451 algorithm where the field "client-kex-alg-name" contains a Random
452 Name, and the field "client-kex-alg-data" contains 0..1000 Random
453 Bytes.
455 5. In the fields "quic-tls-cipher-suite", include in a random
456 position at least one entry consisting of 16..255 Random Bytes.
458 6. In extension pairs, include in a random position at least one
459 extension where the field "ext-pair-name" contains a Random Name,
460 and the field "ext-pair-value" contains 0..1000 Random Bytes.
462 2.8. SSH_QUIC_REPLY
464 Implementations MUST take care to prevent abuse of the SSH/QUIC key
465 exchange for Amplified Reflection DDoS attacks. This means:
467 1. A server MUST NOT send more than one SSH_QUIC_REPLY in response
468 to any individual SSH_QUIC_INIT.
470 2. A server MUST NOT respond to any SSH_QUIC_INIT smaller than 1400
471 bytes.
473 3. Before sending an SSH_QUIC_REPLY, the server MUST verify that the
474 reply is shorter than the SSH_QUIC_INIT packet to which it is
475 replying. If this is not the case, the server MUST send an Error
476 Reply (Section 2.8.1). Such an Error Reply MUST be shorter than
477 the SSH_QUIC_INIT packet.
479 The SSH_QUIC_REPLY packet is a UDP datagram with the following
480 layout:
482 byte SSH_QUIC_REPLY = 0x81
483 short-str server-connection-id (Non-empty except on error)
485 byte v = nr-quic-versions (MUST NOT be zero)
486 uint32[v] server-quic-versions
488 string server-sig-algs (MUST NOT be empty)
489 string server-kex-algs (MUST NOT be empty)
491 byte c = nr-cipher-suites (MUST NOT be zero)
492 the following 1 field repeated c times:
493 short-str quic-tls-cipher-suite
495 byte e = nr-ext-pairs (see Extensibility)
496 the following 2 fields repeated e times:
497 short-str ext-pair-name (MUST NOT be empty)
498 string ext-pair-data (MAY be empty)
500 string server-kex-alg-data (Non-empty except on error)
502 Figure 5
504 SSH_QUIC_REPLY does not include an SSH version string. Instead,
505 servers MUST use SSH_MSG_EXT_INFO for this purpose. See Section 4.
507 SSH_QUIC_REPLY does not include a "cookie" field for random data.
508 Servers MUST insert random data using Extensibility mechanisms. See
509 Section 2.8.2 and Section 2.5.
511 The field "server-connection-id" contains a QUIC Connection ID of
512 length 0..20 bytes. The client will use this as the QUIC Destination
513 Connection ID in QUIC packets sent to the server.
515 The fields "server-quic-versions" enumerate QUIC protocol versions
516 supported by the server. The server MUST send at least one version.
517 The QUIC version used for the connection is the first version
518 enumerated in "client-quic-versions" which is also present in
519 "server-quic-versions". If there is no such version, see
520 Section 2.8.1.
522 The field "server-sig-algs" MUST contain at least one signature
523 algorithm supported by the server. The server SHOULD enumerate all
524 signature algorithms for which it has host keys. These are the same
525 algorithms as used in SSH_MSG_KEXINIT ([RFC4253], Section 7.1) in the
526 field "server_host_key_algorithms". In the SSH/QUIC key exchange,
527 the server MUST use a host key it possesses that (1) matches any
528 fingerprint enumerated in the "trusted-fingerprint" fields in
529 SSH_QUIC_INIT; and (2) can be used with the earliest possible
530 signature algorithm enumerated in "client-sig-algs". If there are
531 multiple such host keys, the client's preference order in "client-
532 sig-algs" dominates the preference order of "trusted-fingerprint".
533 If there is no such host key, the server MUST use any host key that
534 can be used with the earliest possible signature algorithm enumerated
535 in "client-sig-algs". If there is no such host key either, see
536 Section 2.8.1.
538 ...
540 ...
542 ...
544 ...
546 ...
548 ...
550 ...
552 The server MAY send any number of extensions, encoded as a pair of
553 "ext-pair-name" and "ext-pair-data" fields. This memo defines no
554 extensions, but see Section 2.8.2.
556 2.8.1. Error Reply
558 If a server encounters an error which is appropriate to communicate
559 to the client, the server MAY send an "Error Reply" version of
560 SSH_QUIC_REPLY. Such a reply is created as follows:
562 * The server includes and populates all fields of SSH_QUIC_REPLY as
563 it would normally, except that the fields "server-connection-id"
564 and "server-kex-alg-data" MUST remain empty.
566 * In the extension pair fields, a "disc-reason" Extension Pair MUST
567 be included. An "err-desc" Extension Pair MAY also be included.
568 See Section 2.6.
570 * Extensibility considerations in Section 2.8.2 also apply to an
571 Error Reply.
573 If the server does not support any of the QUIC protocol versions
574 enumerated by the client, the server SHOULD send an Error Reply with
575 the disconnect reason code
576 SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED.
578 In the following circumstances, the server SHOULD send an Error Reply
579 with the disconnect reason code SSH_DISCONNECT_KEY_EXCHANGE_FAILED:
581 * If the server could have sent a successful SSH_QUIC_REPLY, but it
582 would have been larger than the client's SSH_QUIC_INIT, even
583 though the SSH_QUIC_INIT met or exceeded the minimum length.
585 * If the server possesses no server host key that can be used with a
586 signature algorithm enumerated in the client's SSH_QUIC_INIT.
588 * If the server supports no key exchange algorithms matching the
589 ones for which the client sent "client-kex-alg-data" in its
590 SSH_QUIC_INIT.
592 * If the server supports no TLS cipher suites enumerated in the
593 client's SSH_QUIC_INIT.
595 Besides "disc-reason", an "err-desc" extension pair SHOULD be
596 included to describe the specific error.
598 2.8.2. Extensibility
600 Implementations MUST allow room for future extensibility of
601 SSH_QUIC_REPLY in the following manners:
603 1. By including algorithms in "server-sig-algs" which are unknown to
604 or not supported by the client. Clients MUST tolerate the
605 presence of such algorithms.
607 2. By including SSH key exchange algorithms which are unknown to or
608 not supported by the client, with algorithm data in a format
609 that's unknown to or not supported by the client. Clients MUST
610 tolerate the presence of such algorithms and their data.
612 3. By including QUIC TLS cipher suites which are unknown to or not
613 supported by the client. Clients MUST tolerate the presence of
614 such cipher suites.
616 4. By including extensions which are unknown to or not supported by
617 the client, with extension data in a format that's unknown to or
618 not supported by the client. Clients MUST tolerate the presence
619 of such extensions and their data.
621 Experience shows that any extensibility which is not actively
622 exercised is lost due to implementations that lock down expectations
623 incorrectly. Therefore, all servers MUST do at least one of the
624 following, in each SSH_QUIC_REPLY packet, at random:
626 1. In the fields "server-quic-versions", include in a random
627 position a version number of the form 0xFA?A?A?A, where ?
628 indicates a random nibble. See [QUIC], section "Versions". Note
629 the difference from the random version pattern in the client's
630 SSH_QUIC_INIT. Due to the minimal amount of entropy provided by
631 this rule, this MUST NOT be the only insertion of randomness made
632 in a packet.
634 2. In the field "server-sig-algs", include in a random position one
635 Random Name (Section 2.5).
637 3. In the field "server-kex-algs", include in a random position one
638 Random Name (Section 2.5).
640 4. In the fields "quic-tls-cipher-suite", include in a random
641 position one entry consisting of 16..64 Random Bytes.
643 5. In extension pairs, include in a random position one extension
644 pair where the field "ext-pair-name" contains a Random Name, and
645 the field "ext-pair-value" contains 0..100 Random Bytes.
647 2.9. SSH_QUIC_CANCEL
649 If a client cannot process the server's successful SSH_QUIC_REPLY,
650 the client SHOULD report the error to the server using
651 SSH_QUIC_CANCEL.
653 A client MUST NOT send an SSH_QUIC_CANCEL in response to an
654 SSH_QUIC_REPLY which is itself an Error Reply. A client MUST assume
655 that such a connection was already canceled by the server.
657 The SSH_QUIC_CANCEL packet is a UDP datagram with the following
658 layout:
660 byte SSH_QUIC_CANCEL = 0x82
661 short-str server-connection-id
663 byte e = nr-ext-pairs (see Extensibility)
664 the following 2 fields repeated e times:
665 short-str ext-pair-name (MUST NOT be empty)
666 string ext-pair-data (MAY be empty)
668 Figure 6
670 The "server-connection-id" field MUST equal the "server-connection-
671 id" field in the server's SSH_QUIC_REPLY.
673 In the extension pair fields, a "disc-reason" Extension Pair MUST be
674 included. An "err-desc" Extension Pair MAY also be included. See
675 Section 2.6.
677 2.9.1. Extensibility
679 Extensibility considerations also apply to SSH_QUIC_CANCEL:
681 * Clients MAY include extensions which are unknown to or not
682 supported by the server, with extension data in a format that's
683 unknown to or not supported by the server.
685 * Servers MUST tolerate the presence of such extensions and their
686 data.
688 * Clients SHOULD include, in a random position, at least one
689 extension pair where the field "ext-pair-name" contains a Random
690 Name, and the field "ext-pair-value" contains 0..300 Random Bytes.
692 3. Key Exchange Methods
694 Clients and servers MAY use any key exchange method which is defined
695 for SSH over TCP, whether it is assigned or private, as long as it
696 meets all of the following criteria:
698 1. The algorithm requires exactly one message from the client to the
699 server, for example SSH_MSG_KEX_ECDH_INIT. We call this message
700 KEXMSG_CLIENT.
702 2. The algorithm requires exactly one reply from the server to the
703 client, for example SSH_MSG_KEX_ECDH_REPLY. We call this message
704 KEXMSG_SERVER.
706 3. The algorithm specifies a hash function HASH, for example SHA-
707 256, SHA-384, or SHA-512.
709 4. The algorithm specifies calculation of an exchange hash H by
710 applying HASH to a concatenation of encoded fields.
712 5. The algorithm uses a server host key to sign H.
714 6. The algorithm includes the server's public host key, and the
715 signature of H, in its KEXMSG_SERVER message to the client.
717 7. The algorithm produces a shared secret K, represented as a signed
718 (positive or negative) multi-precision integer.
720 Any such algorithm is modified for use in SSH over QUIC as follows:
722 1. The field "client-kex-alg-data" in SSH_QUIC_INIT encodes the same
723 fields, in the same order, as KEXMSG_CLIENT, except that the
724 leading byte for the SSH packet type is replaced with 0xFA.
726 2. The field "server-kex-alg-data" in SSH_QUIC_REPLY encodes the
727 same fields, in the same order, as KEXMSG_SERVER, except that the
728 leading byte for the SSH packet type is replaced with 0xFB.
730 3. The calculation of H specified by the algorithm is not performed.
731 Instead, H is calculated by applying the hash function HASH to a
732 concatenation of the following:
734 string Content of SSH_QUIC_INIT
735 string Content of SSH_QUIC_REPLY, excluding "server-kex-alg-data"
736 The fields of "server-kex-alg-data", excluding signature
737 mpint K
739 Figure 7
741 When a field is excluded as above, the entire encoding of the field
742 is omitted: both the encoding of the content and the encoding of the
743 length.
745 When SSH packet type bytes are replaced with 0xFA and 0xFB instead of
746 being removed, this is to ensure that at least two fields remain in
747 the encoded content. If this were not the case, there would be
748 situations where an outer string (the field "client-kex-alg-data")
749 contains a single inner string (from KEXMSG_CLIENT). This is prone
750 to confusion and could lead implementers to incorrectly encode a
751 single string only.
753 3.1. Required Key Exchange Methods
755 Clients and servers are REQUIRED to implement the key exchange method
756 "curve25519-sha256" [RFC8731]. All other key exchange methods are
757 optional.
759 Clients and servers MAY permit the user to disable a required key
760 exchange method. However, required methods MUST be enabled by
761 default.
763 3.2. Example: "curve25519-sha256"
765 As an example, when using the SSH key exchange method
766 "curve25519-sha256", the SSH_QUIC_INIT field "client-kex-alg-data" is
767 derived from SSH_MSG_KEX_ECDH_INIT ([RFC5656], Section 4) and
768 contains the following:
770 byte 0xFA
771 string Q_C, client's ephemeral public key octet string
773 Figure 8
775 The SSH_QUIC_REPLY field "server-kex-alg-data" is derived from
776 SSH_MSG_KEX_ECDH_REPLY and contains the following:
778 byte 0xFB
779 string K_S, server's public host key
780 string Q_S, server's ephemeral public key octet string
781 string the signature on the exchange hash
783 Figure 9
785 The shared secret K is calculated as in [RFC8731]. Then the exchange
786 hash H is calculated by applying SHA-256 to a concatenation of the
787 following:
789 string Content of SSH_QUIC_INIT
790 string Content of SSH_QUIC_REPLY, except "server-kex-alg-data"
791 byte 0xFB
792 string K_S, server's public host key
793 string Q_S, server's ephemeral public key octet string
794 mpint K
796 Figure 10
798 This allows the server to sign H and send the signature in the
799 "server-kex-alg-data" field to the client.
801 4. SSH_MSG_EXT_INFO and the SSH Version String
803 A common user complaint to SSH application authors is that SSH over
804 TCP sends the application version in plain text. The application
805 version cannot be omitted, otherwise implementations cannot support a
806 number of behaviors which other software versions implement
807 incorrectly.
809 A prominent example is the order of arguments in the SFTP request
810 SSH_FXP_SYMLINK. To send a request that will have the desired
811 effects, the client MUST consult the server's version string to know
812 whether the server uses the standard order of fields, or a reverse
813 order used by OpenSSH.
815 SSH over QUIC removes the version string from the SSH key exchange.
816 Instead, all clients and servers are REQUIRED to send and accept
817 SSH_MSG_EXT_INFO [RFC8308], including the "ssh-version" extension
818 defined here.
820 Clients MUST send SSH_MSG_EXT_INFO as the very first SSH packet over
821 QUIC. The client MUST include the "ssh-version" extension in this
822 SSH_MSG_EXT_INFO.
824 Servers MUST send SSH_MSG_EXT_INFO either:
826 1. as the very first SSH packet over QUIC, and/or
828 2. immediately preceding the server's SSH_MSG_USERAUTH_SUCCESS.
830 A server MUST include the "ssh-version" extension in at least one of
831 its SSH_MSG_EXT_INFO. If the server sends SSH_MSG_EXT_INFO at both
832 opportunities, it MAY omit "ssh-version" at the first opportunity,
833 but only if it will send it in the second opportunity. The second
834 SSH_MSG_EXT_INFO sent by the server MAY change a previously sent
835 "ssh-version" extension value to include more specific detail. For
836 example, the server MAY include a more accurate server version when
837 the client has authenticated. The client MUST use the "ssh-version"
838 value which was most recently received from the server.
840 4.1. "ssh-version" Extension
842 The "ssh-version" extension is encoded in SSH_MSG_EXT_INFO as
843 follows:
845 string "ssh-version"
846 string ssh-version-string
848 Figure 11
850 The extension value, "ssh-version-string", contains the same SSH
851 version string as sent at the start of SSH over TCP ([RFC4253],
852 Section 4.2). Examples:
854 SSH-2.0-Product_1.2.00
855 SSH-2.0-0.12 Library: Application 1.23p1
857 Figure 12
859 5. QUIC Session Setup
861 When the server has sent its SSH_QUIC_REPLY, and when the client has
862 received it, they each initialize the QUIC session [QUIC] [QUIC-TLS]
863 as follows:
865 * The QUIC protocol version is set to the first version advertised
866 in the client's SSH_QUIC_INIT which is also present in the
867 server's SSH_QUIC_REPLY.
869 * Session state is set as if a TLS handshake had just completed.
871 * The TLS cipher suite is set to the first TLS cipher suite
872 advertised in SSH_QUIC_INIT which is also present in
873 SSH_QUIC_REPLY.
875 * The QUIC Key Phase bit is set to 0.
877 * The shared secrets that would have been obtained from the TLS
878 handshake are instead generated from the SSH key exchange
879 (Section 5.1).
881 Clients and servers MUST immediately begin to use QUIC Short Header
882 Packets. Implementations MUST NOT send QUIC Long Header Packets,
883 since they could be confused with the SSH/QUIC key exchange.
885 5.1. Shared Secrets
887 QUIC-TLS [QUIC-TLS] uses a client secret and a server secret from
888 which it generates an AEAD key, an IV, and a header protection key
889 for each sending direction.
891 An SSH key exchange produces a shared secret K, represented as an SSH
892 multi-precision integer, and an exchange digest H, represented as
893 binary data [RFC4253]. An SSH key exchange is parameterized with a
894 hash function we call HASH. Note that HASH can be a different hash
895 function, producing a different hash length, than the hash function
896 used by the negotiated TLS cipher suite.
898 To compute the initial QUIC client and server secrets, the client and
899 server encode the following binary data, which we call "secret_data":
901 mpint K
902 string H
904 Figure 13
906 The client and server secrets are then calculated as follows:
908 client_secret = HMAC-HASH("ssh/quic client", secret_data)
909 server_secret = HMAC-HASH("ssh/quic server", secret_data)
911 Figure 14
913 The HMAC construct is as specified in [RFC2104], instantiated using
914 the SSH key exchange hash function, HASH.
916 QUIC keys and IVs are derived from these secrets using the regular
917 QUIC-TLS key derivation process [QUIC-TLS]. Keys generated from
918 these secrets are considered 1-RTT keys.
920 Clients and servers MUST implement QUIC key updates using the regular
921 QUIC-TLS key update process [QUIC-TLS], respecting the QUIC-TLS
922 minimum key update frequencies.
924 6. SSH/QUIC Packet Format
926 All SSH/QUIC packets are sent on QUIC stream 0. No other QUIC
927 streams are used in SSH over QUIC.
929 Each side serializes its SSH packets for sending over QUIC as
930 follows:
932 uint32 n = payload-len
933 byte[n] payload
935 Figure 15
937 Since security is provided by QUIC-TLS [QUIC-TLS], MAC and random
938 padding are omitted at this stage.
940 Compression MAY be negotiated using the "delay-compression" extension
941 in [RFC8308]. If "delay-compression" is negotiated, and conditions
942 to enable compression are met, then the "payload" field is
943 compressed.
945 Otherwise, the "payload" field contains the same packet information
946 as the "payload" field in the Binary Packet Protocol defined in
947 [RFC4253].
949 7. IANA Considerations
951 This document requests no changes to IANA registries.
953 8. Security Considerations
955 Clients and servers MUST insert into SSH_QUIC_INIT and SSH_QUIC_REPLY
956 at least the minimum amount of cryptographically random data as
957 specified in the section Random Elements. Compromising on this
958 requirement reduces the security of any session created on the basis
959 of such an SSH_QUIC_INIT or SSH_QUIC_REPLY.
961 9. References
963 9.1. Normative References
965 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed
966 and Secure Transport", 2020, .
969 [QUIC-TLS] Thomson, M. and S. Turner, "Using TLS to Secure QUIC",
970 2020,
971 .
973 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
974 Hashing for Message Authentication", RFC 2104,
975 DOI 10.17487/RFC2104, February 1997,
976 .
978 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
979 Requirement Levels", BCP 14, RFC 2119,
980 DOI 10.17487/RFC2119, March 1997,
981 .
983 [RFC4251] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
984 Protocol Architecture", RFC 4251, DOI 10.17487/RFC4251,
985 January 2006, .
987 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
988 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253,
989 January 2006, .
991 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm
992 Integration in the Secure Shell Transport Layer",
993 RFC 5656, DOI 10.17487/RFC5656, December 2009,
994 .
996 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
997 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
998 May 2017, .
1000 [RFC8308] Bider, D., "Extension Negotiation in the Secure Shell
1001 (SSH) Protocol", RFC 8308, DOI 10.17487/RFC8308, March
1002 2018, .
1004 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
1005 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
1006 .
1008 [RFC8731] Adamantiadis, A., Josefsson, S., and M. Baushke, "Secure
1009 Shell (SSH) Key Exchange Method Using Curve25519 and
1010 Curve448", RFC 8731, DOI 10.17487/RFC8731, February 2020,
1011 .
1013 9.2. Informative References
1015 [IANA-SSH] IANA, "Secure Shell (SSH) Protocol Parameters",
1016 .
1018 [RFC4250] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell (SSH)
1019 Protocol Assigned Numbers", RFC 4250,
1020 DOI 10.17487/RFC4250, January 2006,
1021 .
1023 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
1024 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252,
1025 January 2006, .
1027 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
1028 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254,
1029 January 2006, .
1031 Appendix A. Generating Random Lengths
1033 The SSH/QUIC extensibility mechanism calls for generating random
1034 lengths such that values in the shorter end of the range are
1035 significantly more probable, but long lengths are still selected.
1036 The following C example shows a simple two-step process to prefer
1037 shorter lengths:
1039 int RandomIntBetweenZeroAnd(int maxValueInclusive);
1041 int RandomLen_PreferShort(int minLen, int maxLen)
1042 {
1043 int const SPAN_THRESHOLD = 7;
1044 int lenSpan = maxLen - minLen;
1046 if (lenSpan <= 0)
1047 return minLen;
1049 if (lenSpan > SPAN_THRESHOLD)
1050 if (0 != RandomIntBetweenZeroAnd(3))
1051 return minLen + RandomIntBetweenZeroAnd(SPAN_THRESHOLD);
1053 return minLen + RandomIntBetweenZeroAnd(lenSpan);
1054 }
1056 Figure 16
1058 Author's Address
1060 denis bider
1061 Bitvise Limited
1062 4105 Lombardy Ct
1063 Colleyville, TX 76034
1064 United States
1066 Email: ietf-draft@denisbider.com