idnits 2.17.1
draft-bider-ssh-quic-03.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 384 has weird spacing: '...ort-str clie...'
== Line 393 has weird spacing: '...ort-str trus...'
== Line 397 has weird spacing: '...ort-str clie...'
== Line 402 has weird spacing: '...ort-str quic...'
== Line 406 has weird spacing: '...ort-str ext-...'
== (19 more instances...)
-- The document date (11 July 2020) is 1356 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
-- Looks like a reference, but probably isn't: '16' on line 191
== Unused Reference: 'RFC4250' is defined on line 1406, 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 (==), 2 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 11 July 2020
5 Expires: 12 January 2021
7 QUIC-based UDP Transport for Secure Shell (SSH)
8 draft-bider-ssh-quic-03
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 12 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 . . . . . . . . . . . . . . . . . . . . . . . . 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.4. Packet Size Limits . . . . . . . . . . . . . . . . . . . 5
64 2.5. Required QUIC Versions and TLS Cipher Suites . . . . . . 5
65 2.6. Random Elements . . . . . . . . . . . . . . . . . . . . . 6
66 2.7. Errors in Key Exchange . . . . . . . . . . . . . . . . . 7
67 2.7.1. "disc-reason" Extension Pair . . . . . . . . . . . . 8
68 2.7.2. "err-desc" Extension Pair . . . . . . . . . . . . . . 8
69 2.8. SSH_QUIC_INIT . . . . . . . . . . . . . . . . . . . . . . 8
70 2.8.1. Extensibility . . . . . . . . . . . . . . . . . . . . 11
71 2.9. SSH_QUIC_REPLY . . . . . . . . . . . . . . . . . . . . . 12
72 2.9.1. Error Reply . . . . . . . . . . . . . . . . . . . . . 15
73 2.9.2. Extensibility . . . . . . . . . . . . . . . . . . . . 16
74 2.10. SSH_QUIC_CANCEL . . . . . . . . . . . . . . . . . . . . . 17
75 2.10.1. Extensibility . . . . . . . . . . . . . . . . . . . 17
76 3. Key Exchange Methods . . . . . . . . . . . . . . . . . . . . 18
77 3.1. Required Key Exchange Methods . . . . . . . . . . . . . . 19
78 3.2. Example 1: "curve25519-sha256" . . . . . . . . . . . . . 19
79 3.3. Example 2: "diffie-hellman-group14-sha256" . . . . . . . 20
80 4. SSH_MSG_EXT_INFO and the SSH Version String . . . . . . . . . 21
81 4.1. "ssh-version" . . . . . . . . . . . . . . . . . . . . . . 22
82 4.2. "no-flow-control" . . . . . . . . . . . . . . . . . . . . 22
83 4.3. "delay-compression" . . . . . . . . . . . . . . . . . . . 22
84 5. QUIC Session Setup . . . . . . . . . . . . . . . . . . . . . 22
85 5.1. Shared Secrets . . . . . . . . . . . . . . . . . . . . . 23
86 6. Adaptation of SSH to QUIC Streams . . . . . . . . . . . . . . 24
87 6.1. SSH/QUIC Packet Format . . . . . . . . . . . . . . . . . 24
88 6.1.1. Compression . . . . . . . . . . . . . . . . . . . . . 24
89 6.2. Use of QUIC Streams . . . . . . . . . . . . . . . . . . . 25
90 6.3. Packet Sequence Numbers . . . . . . . . . . . . . . . . . 25
91 6.4. Channel IDs . . . . . . . . . . . . . . . . . . . . . . . 25
92 6.5. Disconnection . . . . . . . . . . . . . . . . . . . . . . 26
93 6.6. Prohibited SSH Packets . . . . . . . . . . . . . . . . . 26
94 6.7. Global SSH Packets . . . . . . . . . . . . . . . . . . . 26
95 6.8. SSH Channel Packets . . . . . . . . . . . . . . . . . . . 27
96 6.9. Closing a Channel . . . . . . . . . . . . . . . . . . . . 29
98 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29
99 8. Security Considerations . . . . . . . . . . . . . . . . . . . 29
100 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 29
101 9.1. Normative References . . . . . . . . . . . . . . . . . . 29
102 9.2. Informative References . . . . . . . . . . . . . . . . . 31
103 Appendix A. Generating Random Lengths . . . . . . . . . . . . . 31
104 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 31
106 1. Introduction
108 THIS DOCUMENT IS AN EARLY VERSION AND IS A WORK IN PROGRESS.
110 NON-LATEST DRAFT VERSIONS MUST BE DISREGARDED.
112 IMPLEMENTATION AT THIS STAGE IS EXPERIMENTAL.
114 CONTACT THE AUTHOR IF YOU INTEND TO IMPLEMENT.
116 This memo specifies SSH key exchange over UDP, and then leverages
117 QUIC to provide a UDP-based transport for SSH. QUIC's use of the TLS
118 handshake is replaced with a one-roundtrip SSH/QUIC key exchange.
119 The SSH Authentication Protocol [RFC4252] is then conducted over QUIC
120 stream 0, and the SSH Connection Protocol [RFC4254] is modified to
121 use QUIC streams.
123 1.1. Requirements Terminology
125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
127 "OPTIONAL" in this document are to be interpreted as described in
128 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
129 capitals, as shown here.
131 2. SSH/QUIC key exchange
133 2.1. Distinguishing SSH key exchange from QUIC datagrams
135 UDP datagrams which form the SSH/QUIC key exchange are sent between
136 the same client and server IP addresses and ports as QUIC datagrams.
137 It is therefore necessary for clients and servers to distinguish SSH
138 key exchange datagrams from QUIC datagrams.
140 A distinction is allowed by that SSH/QUIC only requires the sending
141 of QUIC Short Header Packets. Therefore, all UDP datagrams where the
142 first byte has its high bit set MUST be handled as part of an SSH/
143 QUIC key exchange.
145 2.2. Wire Encoding
147 This memo uses wire encoding types "byte", "uint32", "uint64",
148 "mpint" and "string" with meanings as described in [RFC4251].
150 This memo defines the following new wire encoding type. "short-str"
151 is a shorter version of "string", encoded as follows:
153 byte n = short-str-len (unsigned, 0..255)
154 byte[n] short-str-value
156 Figure 1
158 2.3. Obfuscated Envelope
160 Since SSH servers are commonly used for remote administration, they
161 are a high-value target for password guessing. One of the most
162 common complaints from SSH server administrators is the high
163 frequency of password guessing connections from random clients.
165 Experience shows that obfuscating the SSH protocol with an
166 obfuscation keyword is a valuable measure which thwarts password
167 guessing. This increases practical security of the SSH ecosystem
168 even if obfuscation does not thwart narrowly targeted attacks.
170 Every SSH/QUIC connection is parameterized by an obfuscation keyword.
171 The obfuscation keyword is a sequence of Unicode characters entered
172 by a user. Applications MUST permit the user to enter any Unicode
173 characters except code points in the Unicode category "Cc" (Control).
174 These are decimal code points 0..31 and 127..159, inclusive.
176 An SSH/QUIC server SHOULD allow the administrator to configure an
177 obfuscation keyword for each interface and port on which the server
178 is accepting SSH/QUIC connections. An SSH/QUIC client MUST allow the
179 user to configure an obfuscation keyword separately for outgoing
180 connections to each server address and port.
182 The obfuscation keyword MUST be optional for users to configure. If
183 a user does not configure it, the obfuscated envelope is applied as
184 if the obfuscation keyword was an empty character sequence.
186 All SSH/QUIC key exchange packets are sent as UDP datagrams in the
187 following obfuscated envelope:
189 byte[16] obfs-nonce - high bit of first byte MUST be set
190 byte[] obfs-payload
191 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 in
204 UTF-8 encoding.
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.4. Packet Size Limits
223 Clients and servers MUST accept SSH_QUIC_INIT, SSH_QUIC_REPLY and
224 SSH_QUIC_CANCEL packets with unencrypted "obfs-payload" sizes at
225 least up to 32768 bytes. This corresponds to minimum SSH packet size
226 limits which implementations must support as per [RFC4253],
227 Section 6.1.
229 2.5. Required QUIC Versions and TLS Cipher Suites
231 Clients and servers are REQUIRED to implement QUIC protocol version 1
232 once it is standardized in [QUIC] and [QUIC-TLS].
234 Clients and servers are REQUIRED to implement the TLS cipher suites
235 TLS_AES_128_GCM_SHA256 and TLS_AES_256_GCM_SHA384 [RFC8446]. Other
236 cipher suites are optional.
238 The requirement to implement any particular QUIC protocol version or
239 TLS cipher suite expires on the 5-year anniversary of the publishing
240 of this memo. At that point, implementers SHOULD consult any new
241 standards documents if available, or survey the practical use of SSH/
242 QUIC for implementation guidance.
244 2.6. Random Elements
246 Unlike SSH over TCP, the packets SSH_QUIC_INIT and SSH_QUIC_REPLY do
247 not provide a "cookie" field for random data. Instead, clients and
248 servers MUST insert random data using the extensibility mechanisms
249 described for each SSH key exchange packet.
251 At the very minimum, clients and servers MUST insert at least 16
252 Random Bytes or at least one Random Name, in locations as described
253 for SSH_QUIC_INIT (Section 2.8.1) and SSH_QUIC_REPLY (Section 2.9.2).
254 If at all possible, the random data MUST come from a
255 cryptographically strong random source. Implementations that are
256 unable to meet this requirement MUST still insert the minimum amount
257 of random data, as unpredictably as they are able. Compromising on
258 this requirement reduces the security of any sessions created on the
259 basis of such SSH_QUIC_INIT and SSH_QUIC_REPLY.
261 Lengths of Random Names and Random Bytes SHOULD be chosen at random
262 such that lengths in the shorter end of the range are significantly
263 more probable, but long lengths are still selected. See Appendix A.
265 Random Bytes
267 Random Bytes are generated with values 0..255, in a range of lengths
268 as specified for the particular usage context.
270 Random Name
272 A Random Name is generated in one of two forms: Assigned Form or
273 Private Form. One of the two forms is randomly chosen so that
274 Assigned Form, which is shorter, is more likely. The maximum length
275 of a Random Name is 64 bytes.
277 Assigned Form
279 A Random Name in Assigned Form is generated as a string of random
280 characters with ASCII values 33..126 (inclusive), except @ and the
281 comma (","). Other characters MUST NOT be included. To avoid
282 collisions as effectively as a random UUID, a Random Name in Assigned
283 Form MUST contain at least 20 random characters if using the complete
284 character set. A Random Name in Assigned Form MUST then be of length
285 20..64 bytes.
287 Implementations MAY remove up to 7 characters from the character set
288 -- reducing it to 85..91 characters -- without increasing the minimum
289 length. If the character set is further reduced to 69..84
290 characters, implementations MUST generate at least 21 random
291 characters instead.
293 Example Random Names in Assigned Form:
295 d`kbi>AGrj~r{3lo_Q4r
296 wNT)=/8C<(DB1|tr:>1f[xq>9bG
297 u7^dE'\EE_}N}^"J5syI?/8jIxup#s7BM:]>{IT_p3Z~wJDYIBX.4zzQ$@denisbider.com
311 ?`z4bb/}
&Wuf6O7CE?cA`$j"@bider.us
313 Figure 4
315 Alternately, implementations MAY generate a Random Name in Anonymous
316 Form with the format "(local)@(domain).example.com". In this case,
317 both "(local)" and "(domain)" are replaced by random ASCII characters
318 from the set A..Z, a..z, and 0..9. This is to ensure that the suffix
319 has valid domain name syntax.
321 To avoid collisions as effectively as a random UUID, a Random Name in
322 Anonymous Form MUST contain at least 22 random characters. A Random
323 Name in Anonymous Form MUST then be of length 35..64 bytes.
325 2.7. Errors in Key Exchange
327 To assist users, clients and servers SHOULD report key exchange
328 errors as follows:
330 1. If a server cannot send a successful SSH_QUIC_REPLY, it SHOULD
331 send an Error Reply. See Section 2.9.1.
333 2. If a client receives an invalid SSH_QUIC_REPLY, it SHOULD send an
334 SSH_QUIC_CANCEL. See Section 2.10.
336 Both packet types use the following extension pairs.
338 2.7.1. "disc-reason" Extension Pair
340 "ext-pair-name" contains "disc-reason".
342 "ext-pair-data" encodes a uint32 with the SSH disconnect reason code.
343 Reason codes are defined in the table "Disconnect Messages Reason
344 Codes and Descriptions" in the IANA registry "Secure Shell (SSH)
345 Protocol Parameters" [IANA-SSH].
347 2.7.2. "err-desc" Extension Pair
349 "ext-pair-name" contains "err-desc".
351 "ext-pair-data" encodes a human-readable error description in any
352 language intended to be relevant to the user, encoded as UTF-8.
354 Receivers that process error descriptions MUST validate that the
355 description is valid UTF-8. If a description is long, receivers
356 SHOULD truncate it to a reasonable length depending on the processing
357 context. For example, a debug log file can record a full 32 kB error
358 description, while a production log file SHOULD truncate it to a much
359 shorter length.
361 2.8. SSH_QUIC_INIT
363 A client begins an SSH/QUIC session by sending one or more copies of
364 SSH_QUIC_INIT. If multiple copies are sent, copies intended for the
365 same connection MUST be identical. A reasonable strategy is to send
366 one copy every 50 - 500 ms until the client receives a valid
367 SSH_QUIC_REPLY or times out. A server MUST remember recently
368 received SSH_QUIC_INIT packets and send identical SSH_QUIC_REPLY
369 responses. If different SSH_QUIC_INIT packets are received from the
370 same client IP address, the server MUST assume they are intended to
371 begin separate connections, even if they specify the same "client-
372 connection-id". A server MAY implement throttling of incoming
373 connections, by IP address or otherwise, where excessive
374 SSH_QUIC_INIT packets are disregarded. Once a server receives QUIC
375 data confirming that a client has processed an SSH_QUIC_REPLY, the
376 server MUST disregard any further identical copies of the same
377 SSH_QUIC_INIT, at least until the SSH/QUIC session started by such an
378 SSH_QUIC_INIT ends.
380 SSH_QUIC_INIT is an obfuscated datagram (Section 2.3) where "obfs-
381 payload" encrypts the following:
383 byte SSH_QUIC_INIT = 1 (see Extensibility)
384 short-str client-connection-id (MAY be empty)
386 byte v = nr-quic-versions (MUST NOT be zero)
387 uint32[v] client-quic-versions
389 string client-sig-algs (MUST NOT be empty)
391 byte f = nr-trusted-fingerprints (MAY be zero)
392 the following 1 field repeated f times:
393 short-str trusted-fingerprint (MUST NOT be empty)
395 byte k = nr-client-kex-algs (MUST NOT be zero)
396 the following 2 fields repeated k times:
397 short-str client-kex-alg-name (MUST NOT be empty)
398 string client-kex-alg-data (MUST NOT be empty)
400 byte c = nr-cipher-suites (MUST NOT be zero)
401 the following 1 field repeated c times:
402 short-str quic-tls-cipher-suite
404 byte e = nr-ext-pairs (see Extensibility)
405 the following 2 fields repeated e times:
406 short-str ext-pair-name (MUST NOT be empty)
407 string ext-pair-data (MAY be empty)
409 byte[0..] padding: all 0xFF to minimal obfs-payload size 1400
411 Figure 5
413 SSH_QUIC_INIT does not include an SSH version string or compression
414 negotiation. Instead, clients MUST use SSH_MSG_EXT_INFO for these
415 purposes. See Section 4.
417 SSH_QUIC_INIT does not include a "cookie" field for random data.
418 Clients MUST insert random data using the packet's extensibility
419 mechanisms. See Section 2.8.1 and Section 2.6.
421 The field "client-connection-id" contains a QUIC Connection ID of
422 length 0..20 bytes. The server will use this as the QUIC Destination
423 Connection ID in QUIC packets sent to the client. Clients MAY send
424 an empty Connection ID if they are using other means of routing
425 connections.
427 The fields "client-quic-versions" enumerate QUIC protocol versions
428 supported by the client. The client MUST send at least one version.
429 The client MUST send supported versions in the order it prefers the
430 server to use them.
432 The field "client-sig-algs" MUST contain at least one signature
433 algorithm supported by the client for server authentication. These
434 are the same algorithms as used in SSH_MSG_KEXINIT ([RFC4253],
435 Section 7.1) in the field "server_host_key_algorithms". The client
436 MUST send signature algorithms in the order it prefers the server to
437 use them.
439 The client SHOULD include algorithms in "client-sig-algs" as follows:
441 * If the client does not yet trust any host key for the server:
442 "client-sig-algs" SHOULD include all signature algorithms
443 supported and enabled by the client for use with any server.
445 * Otherwise, the client already trusts some host keys for the
446 server. In this case, if the client sends any "trusted-
447 fingerprint" fields, then "client-sig-algs" SHOULD include all
448 signature algorithms supported and enabled by the client for use
449 with any server.
451 * Otherwise, the client already trusts some host keys for the
452 server, but does not send any "trusted-fingerprint" fields. In
453 this case, "client-sig-algs" MUST include only signature
454 algorithms associated with the host keys the client already trusts
455 for this server.
457 There MAY be zero or more "trusted-fingerprint" fields. Each
458 "trusted-fingerprint" contains a binary fingerprint of a host key
459 that is trusted for this connection by the client. The fingerprint
460 algorithm is left unspecified. The server SHOULD try to match the
461 fingerprint using all algorithms it supports which produce the
462 provided fingerprint size. The current recommended fingerprint
463 algorithm is SHA-256, with fingerprint size 32 bytes. Servers MUST
464 tolerate the presence of unrecognized fingerprints of any size. The
465 preference order of trusted fingerprints is dominated by the
466 preference order of algorithms in "client-sig-algs".
468 The packet MUST include at least one SSH key exchange algorithm,
469 encoded as a pair of "client-kex-alg-name" and "client-kex-alg-data"
470 fields. The field "client-kex-alg-name" MUST specify a key exchange
471 method which would be valid in the field "kex_algorithms" in
472 SSH_MSG_KEXINIT under [RFC4253], Section 7.1. In addition, the key
473 exchange method MUST meet criteria in Section 3.
475 If the client wishes to simply advertise its support for a particular
476 key exchange algorithm, but does not prefer to use it in this
477 connection, it MAY enumerate the algorithm with empty "client-kex-
478 alg-data". Otherwise, if the client wishes to allow the algorithm to
479 be used, it MUST include non-empty "client-kex-alg-data". In this
480 case, "client-kex-alg-data" contains the client's portion of key
481 exchange inputs as specified in Section 3. The client MAY send
482 multiple key exchange algorithms with filled-out "client-kex-alg-
483 data". The client MUST send these algorithms in the order it prefers
484 the server to use them.
486 There MUST be at least one "quic-tls-cipher-suite" field. Each of
487 these specifies a TLS cipher suite ([RFC8446], Appendix B.4) which is
488 supported by the client, and which can be used with a version of QUIC
489 ([QUIC], [QUIC-TLS]) supported by the client. The client MUST
490 enumerate supported cipher suites in the order it prefers the server
491 to use them.
493 The client MAY send any number of extensions, encoded as a pair of
494 "ext-pair-name" and "ext-pair-data" fields. This memo defines no
495 extensions for SSH_QUIC_INIT, but see Section 2.8.1.
497 The "padding" field contains all 0xFF bytes to ensure that the
498 unencrypted "obfs-payload" for SSH_QUIC_INIT is at least 1400 bytes
499 in length. Servers MUST ignore smaller SSH_QUIC_INIT packets. This
500 is REQUIRED to prevent abuse of SSH_QUIC_INIT for Amplified
501 Reflection DDoS. If the unencrypted size of "obfs-payload" is
502 already 1400 bytes or larger, the padding MAY be omitted.
504 2.8.1. Extensibility
506 Implementations MUST allow room for future extensibility of
507 SSH_QUIC_INIT in the following manners:
509 1. By using a different packet type in the first byte -- this is, a
510 value other than 1 used by SSH_QUIC_INIT. Servers MUST NOT
511 penalize clients for sending unknown packet types unless there is
512 another reason to penalize the client, such as a blocked IP
513 address or the sheer volume of datagrams.
515 2. By including algorithms in "client-sig-algs" which are unknown to
516 or not supported by the server. Servers MUST tolerate the
517 presence of such algorithms.
519 3. By including fingerprints in "trusted-fingerprints" that use
520 algorithms or lengths that are unknown to or not supported by the
521 server. Servers MUST tolerate the presence of such fingerprints.
523 4. By including SSH key exchange algorithms which are unknown to or
524 not supported by the server, with algorithm data in a format
525 that's unknown to or not supported by the server. Servers MUST
526 tolerate the presence of such algorithms and their data.
528 5. By including QUIC TLS cipher suites which are unknown to or not
529 supported by the server. Servers MUST tolerate the presence of
530 such cipher suites.
532 6. By including extensions which are unknown to or not supported by
533 the server, with extension data in a format that's unknown to or
534 not supported by the server. Servers MUST tolerate the presence
535 of such extensions and their data.
537 Experience shows that any extensibility which is not actively
538 exercised is lost due to implementations that lock down expectations
539 incorrectly. Therefore, all clients MUST do at least one of the
540 following, in each SSH_QUIC_INIT packet, at random:
542 1. In the field "client-sig-algs", include in a random position at
543 least one Random Name (Section 2.6).
545 2. In the fields "client-quic-versions", include in a random
546 position a version number of the form 0x0A?A?A?A, where ?
547 indicates a random nibble. See [QUIC], section "Versions". Note
548 the difference from the random version pattern in the server's
549 SSH_QUIC_REPLY. Due to the minimal amount of entropy provided by
550 this rule, this MUST NOT be the only insertion of randomness made
551 in a packet.
553 3. Include in a random position at least one host key fingerprint
554 consisting of 16..255 Random Bytes (Section 2.6).
556 4. Include in a random position at least one SSH key exchange
557 algorithm where the field "client-kex-alg-name" contains a Random
558 Name, and the field "client-kex-alg-data" contains 0..1000 Random
559 Bytes.
561 5. In the fields "quic-tls-cipher-suite", include in a random
562 position at least one entry consisting of 16..255 Random Bytes.
564 6. In extension pairs, include in a random position at least one
565 extension where the field "ext-pair-name" contains a Random Name,
566 and the field "ext-pair-value" contains 0..1000 Random Bytes.
568 2.9. SSH_QUIC_REPLY
570 Implementations MUST take care to prevent abuse of the SSH/QUIC key
571 exchange for Amplified Reflection DDoS attacks. This means:
573 1. A server MUST NOT send more than one SSH_QUIC_REPLY in response
574 to any individual SSH_QUIC_INIT.
576 2. A server MUST NOT respond to any SSH_QUIC_INIT with unencrypted
577 "obfs-payload" smaller than 1400 bytes.
579 3. Before sending an SSH_QUIC_REPLY, the server MUST verify that the
580 reply is shorter than the SSH_QUIC_INIT packet to which it is
581 replying. If this is not the case, the server MUST send an Error
582 Reply (Section 2.9.1). Such an Error Reply MUST be shorter than
583 the SSH_QUIC_INIT packet.
585 SSH_QUIC_REPLY is an obfuscated datagram (Section 2.3) where "obfs-
586 payload" encrypts the following:
588 byte SSH_QUIC_REPLY = 2
589 short-str server-connection-id (Non-empty except on error)
591 byte v = nr-quic-versions (MUST NOT be zero)
592 uint32[v] server-quic-versions
594 string server-sig-algs (MUST NOT be empty)
595 string server-kex-algs (MUST NOT be empty)
597 byte c = nr-cipher-suites (MUST NOT be zero)
598 the following 1 field repeated c times:
599 short-str quic-tls-cipher-suite
601 byte e = nr-ext-pairs (see Extensibility)
602 the following 2 fields repeated e times:
603 short-str ext-pair-name (MUST NOT be empty)
604 string ext-pair-data (MAY be empty)
606 string server-kex-alg-data (Non-empty except on error)
608 Figure 6
610 SSH_QUIC_REPLY does not include an SSH version string or compression
611 negotiation. Instead, servers MUST use SSH_MSG_EXT_INFO for these
612 purposes. See Section 4.
614 SSH_QUIC_REPLY does not include a "cookie" field for random data.
615 Servers MUST insert random data using the packet's extensibility
616 mechanisms. See Section 2.9.2 and Section 2.6.
618 The field "server-connection-id" contains a QUIC Connection ID of
619 length 0..20 bytes. The client will use this as the QUIC Destination
620 Connection ID in QUIC packets sent to the server.
622 The fields "server-quic-versions" enumerate QUIC protocol versions
623 supported by the server. The server MUST send at least one version.
624 The QUIC version used for the connection is the first version
625 enumerated in "client-quic-versions" which is also present in
626 "server-quic-versions". If there is no such version, see
627 Section 2.9.1.
629 The field "server-sig-algs" MUST contain at least one signature
630 algorithm supported by the server. The server SHOULD enumerate all
631 signature algorithms for which it has host keys. These are the same
632 algorithms as used in SSH_MSG_KEXINIT ([RFC4253], Section 7.1) in the
633 field "server_host_key_algorithms". In the SSH/QUIC key exchange,
634 the server MUST use a host key it possesses that (1) matches any
635 fingerprint enumerated in the "trusted-fingerprint" fields in
636 SSH_QUIC_INIT; and (2) can be used with the earliest possible
637 signature algorithm enumerated in "client-sig-algs". If there are
638 multiple such host keys, the client's preference order in "client-
639 sig-algs" dominates the preference order of "trusted-fingerprint".
640 If there is no such host key, the server MUST use any host key that
641 can be used with the earliest possible signature algorithm enumerated
642 in "client-sig-algs". If there is no such host key either, see
643 Section 2.9.1.
645 The field "server-kex-algs" MUST contain at least one SSH key
646 exchange algorithm supported by the server. The key exchange
647 algorithm which is used in the connection is the first algorithm sent
648 in client's SSH_QUIC_INIT where: (1) the field "client-kex-alg-data"
649 is non-empty, and (2) the algorithm is also present in "server-kex-
650 algs". If there is no such key exchange algorithm, see
651 Section 2.9.1.
653 There MUST be at least one "quic-tls-cipher-suite" field. Each of
654 these specifies a TLS cipher suite ([RFC8446], Appendix B.4) which is
655 supported by the server, and which can be used with a version of QUIC
656 ([QUIC], [QUIC-TLS]) supported by the server. The TLS cipher suite
657 which is used for the connection is the first suite sent in the
658 client's SSH_QUIC_INIT where: (1) the cipher suite is supported by
659 the negotiated QUIC protocol version, and (2) the cipher suite is
660 present in the server's SSH_QUIC_REPLY. If there is no such cipher
661 suite, see Section 2.9.1.
663 The server MAY send any number of extensions, encoded as a pair of
664 "ext-pair-name" and "ext-pair-data" fields. Some extensions are
665 defined for use with an Error Reply (see Section 2.9.1). Other
666 extensions MAY be defined in the future; see Section 2.9.2.
668 The field "server-kex-alg-data" MUST be empty if the packet is an
669 Error Reply. Otherwise, this field contains information for the SSH
670 key exchange method: see Section 3. Generally, this includes the
671 server's portion of key exchange inputs; the server's host key; and
672 the server's signature of the calculated exchange hash.
674 2.9.1. Error Reply
676 If a server encounters an error which it is useful and appropriate to
677 communicate to the client, the server MAY send an "Error Reply"
678 version of SSH_QUIC_REPLY. Such a reply is created as follows:
680 * The server includes and populates all fields of SSH_QUIC_REPLY as
681 it would normally, except that the fields "server-connection-id"
682 and "server-kex-alg-data" MUST remain empty.
684 * In the extension pair fields, a "disc-reason" Extension Pair MUST
685 be included. An "err-desc" Extension Pair MAY also be included.
686 See Section 2.7.
688 * Extensibility considerations for SSH_QUIC_REPLY in Section 2.9.2
689 also apply to an Error Reply.
691 If the server does not support any of the QUIC protocol versions
692 enumerated by the client, the server SHOULD send an Error Reply with
693 the disconnect reason code
694 SSH_DISCONNECT_PROTOCOL_VERSION_NOT_SUPPORTED.
696 In the following circumstances, the server SHOULD send an Error Reply
697 with the disconnect reason code SSH_DISCONNECT_KEY_EXCHANGE_FAILED:
699 * If the server could have sent a successful SSH_QUIC_REPLY, but it
700 would have been larger than the client's SSH_QUIC_INIT, even
701 though the SSH_QUIC_INIT met or exceeded the minimum length.
703 * If the server possesses no server host key that can be used with a
704 signature algorithm enumerated in the client's SSH_QUIC_INIT.
706 * If the server supports no key exchange algorithms matching the
707 ones for which the client sent "client-kex-alg-data" in
708 SSH_QUIC_INIT.
710 * If the server supports no TLS cipher suites enumerated in the
711 client's SSH_QUIC_INIT.
713 Besides "disc-reason", an "err-desc" extension pair SHOULD be
714 included to describe the specific error.
716 2.9.2. Extensibility
718 Implementations MUST allow room for future extensibility of
719 SSH_QUIC_REPLY in the following manners:
721 1. By including algorithms in "server-sig-algs" which are unknown to
722 or not supported by the client. Clients MUST tolerate the
723 presence of such algorithms.
725 2. By including SSH key exchange algorithms which are unknown to or
726 not supported by the client, with algorithm data in a format
727 that's unknown to or not supported by the client. Clients MUST
728 tolerate the presence of such algorithms and their data.
730 3. By including QUIC TLS cipher suites which are unknown to or not
731 supported by the client. Clients MUST tolerate the presence of
732 such cipher suites.
734 4. By including extensions which are unknown to or not supported by
735 the client, with extension data in a format that's unknown to or
736 not supported by the client. Clients MUST tolerate the presence
737 of such extensions and their data.
739 Experience shows that any extensibility which is not actively
740 exercised is lost due to implementations that lock down expectations
741 incorrectly. Therefore, all servers MUST do at least one of the
742 following, in each SSH_QUIC_REPLY packet, at random:
744 1. In the fields "server-quic-versions", include in a random
745 position a version number of the form 0xFA?A?A?A, where ?
746 indicates a random nibble. See [QUIC], section "Versions". Note
747 the difference from the random version pattern in the client's
748 SSH_QUIC_INIT. Due to the minimal amount of entropy provided by
749 this rule, this MUST NOT be the only insertion of randomness made
750 in a packet.
752 2. In the field "server-sig-algs", include in a random position one
753 Random Name (Section 2.6).
755 3. In the field "server-kex-algs", include in a random position one
756 Random Name (Section 2.6).
758 4. In the fields "quic-tls-cipher-suite", include in a random
759 position one entry consisting of 16..64 Random Bytes.
761 5. In extension pairs, include in a random position one extension
762 pair where the field "ext-pair-name" contains a Random Name, and
763 the field "ext-pair-value" contains 0..100 Random Bytes.
765 2.10. SSH_QUIC_CANCEL
767 If a client cannot process the server's successful SSH_QUIC_REPLY,
768 the client SHOULD report the error to the server using
769 SSH_QUIC_CANCEL.
771 A client MUST NOT send an SSH_QUIC_CANCEL in response to an
772 SSH_QUIC_REPLY which is itself an Error Reply. A client MUST assume
773 that such a connection was already canceled by the server.
775 SSH_QUIC_CANCEL is an obfuscated datagram (Section 2.3) where "obfs-
776 payload" encrypts the following:
778 byte SSH_QUIC_CANCEL = 3
779 short-str server-connection-id
781 byte e = nr-ext-pairs (see Extensibility)
782 the following 2 fields repeated e times:
783 short-str ext-pair-name (MUST NOT be empty)
784 string ext-pair-data (MAY be empty)
786 Figure 7
788 The "server-connection-id" field MUST equal the "server-connection-
789 id" field in the server's SSH_QUIC_REPLY.
791 In the extension pair fields, a "disc-reason" Extension Pair MUST be
792 included. An "err-desc" Extension Pair MAY also be included. See
793 Section 2.7.
795 2.10.1. Extensibility
797 Extensibility considerations also apply to SSH_QUIC_CANCEL:
799 * Clients MAY include extensions which are unknown to or not
800 supported by the server, with extension data in a format that's
801 unknown to or not supported by the server.
803 * Servers MUST tolerate the presence of such extensions and their
804 data.
806 * Clients SHOULD include, in a random position, at least one
807 extension pair where the field "ext-pair-name" contains a Random
808 Name, and the field "ext-pair-value" contains 0..300 Random Bytes.
810 3. Key Exchange Methods
812 Clients and servers MAY use any key exchange method which is defined
813 for SSH over TCP, whether it is assigned or private, as long as it
814 meets all of the following criteria:
816 1. The algorithm requires exactly one message from the client to the
817 server, for example SSH_MSG_KEX_ECDH_INIT. We call this message
818 KEXMSG_CLIENT.
820 2. The algorithm requires exactly one reply from the server to the
821 client, for example SSH_MSG_KEX_ECDH_REPLY. We call this message
822 KEXMSG_SERVER.
824 3. The algorithm specifies a hash function HASH, for example SHA-
825 256, SHA-384, or SHA-512.
827 4. The algorithm specifies calculation of an exchange hash H by
828 applying HASH to a concatenation of encoded fields.
830 5. The algorithm uses a server host key to sign H.
832 6. The algorithm includes the server's public host key, and the
833 signature of H, in its KEXMSG_SERVER message to the client.
835 7. The algorithm produces a shared secret K, represented as a signed
836 (positive or negative) multi-precision integer.
838 Any such algorithm is modified for use in SSH over QUIC as follows:
840 1. The field "client-kex-alg-data" in SSH_QUIC_INIT encodes the same
841 fields, in the same order, as KEXMSG_CLIENT, except that the
842 leading byte for the SSH packet type is replaced with 0xFA.
844 2. The field "server-kex-alg-data" in SSH_QUIC_REPLY encodes the
845 same fields, in the same order, as KEXMSG_SERVER, except that the
846 leading byte for the SSH packet type is replaced with 0xFB.
848 3. The calculation of H specified by the algorithm is not performed.
849 Instead, H is calculated by applying the hash function HASH to a
850 concatenation of the following:
852 string Unencrypted "obfs-payload" content of SSH_QUIC_INIT
854 string Unencrypted "obfs-payload" content of SSH_QUIC_REPLY,
855 excluding the entire field "server-kex-alg-data"
857 The fields of "server-kex-alg-data", excluding signature field
859 mpint K
861 Figure 8
863 When a field is excluded as above, the entire encoding of the field
864 is omitted: both the encoding of the content and the encoding of the
865 length.
867 When SSH packet type bytes are replaced with 0xFA and 0xFB instead of
868 being removed, this is to ensure that at least two fields remain in
869 the encoded content. If this were not the case, there would be
870 situations where an outer string (the field "client-kex-alg-data")
871 contains a single inner string (from KEXMSG_CLIENT). This could
872 confuse implementers to incorrectly encode a single string only.
874 3.1. Required Key Exchange Methods
876 Clients and servers are REQUIRED to implement the key exchange method
877 "curve25519-sha256" [RFC8731]. All other key exchange methods are
878 optional.
880 Clients and servers MAY permit the user to disable a required key
881 exchange method. However, required methods MUST be enabled by
882 default.
884 The requirement to implement any particular key exchange method
885 expires on the 5-year anniversary of the publishing of this memo. At
886 that point, implementers SHOULD consult any new standards documents
887 if available, or survey the practical use of SSH/QUIC for
888 implementation guidance.
890 3.2. Example 1: "curve25519-sha256"
892 When using the SSH key exchange method "curve25519-sha256", the
893 SSH_QUIC_INIT field "client-kex-alg-data" is derived from
894 SSH_MSG_KEX_ECDH_INIT ([RFC5656], Section 4) and contains the
895 following:
897 byte 0xFA
898 string Q_C, client's ephemeral public key octet string
899 Figure 9
901 The SSH_QUIC_REPLY field "server-kex-alg-data" is derived from
902 SSH_MSG_KEX_ECDH_REPLY and contains the following:
904 byte 0xFB
905 string K_S, server's public host key
906 string Q_S, server's ephemeral public key octet string
907 string the signature on the exchange hash
909 Figure 10
911 The shared secret K is calculated as in [RFC8731]. Then the exchange
912 hash H is calculated by applying SHA-256 to a concatenation of the
913 following:
915 string Content of SSH_QUIC_INIT
916 string Content of SSH_QUIC_REPLY, except "server-kex-alg-data"
917 byte 0xFB
918 string K_S, server's public host key
919 string Q_S, server's ephemeral public key octet string
920 mpint K
922 Figure 11
924 3.3. Example 2: "diffie-hellman-group14-sha256"
926 When using the SSH key exchange method "diffie-hellman-
927 group14-sha256", the SSH_QUIC_INIT field "client-kex-alg-data" is
928 derived from SSH_MSG_KEXDH_INIT ([RFC4253], Section 8) and contains
929 the following:
931 byte 0xFA
932 mpint e
934 Figure 12
936 The SSH_QUIC_REPLY field "server-kex-alg-data" is derived from
937 SSH_MSG_KEXDH_REPLY and contains the following:
939 byte 0xFB
940 string server public host key and certificates (K_S)
941 mpint f
942 string signature of H
944 Figure 13
946 The shared secret K is calculated as in [RFC4253]. Then the exchange
947 hash H is calculated by applying SHA-256 to a concatenation of the
948 following:
950 string Content of SSH_QUIC_INIT
951 string Content of SSH_QUIC_REPLY, except "server-kex-alg-data"
952 byte 0xFB
953 string server public host key and certificates (K_S)
954 mpint f
955 mpint K
957 Figure 14
959 4. SSH_MSG_EXT_INFO and the SSH Version String
961 A common user complaint to SSH application authors is that SSH over
962 TCP sends the application version in plain text. The application
963 version cannot be omitted, otherwise implementations cannot support a
964 number of behaviors which other software versions implement
965 incorrectly.
967 A prominent example is the order of arguments in the SFTP request
968 SSH_FXP_SYMLINK. To send a request that will have the desired
969 effects, the client MUST consult the server's version string to know
970 whether the server uses the standard order of fields, or a reverse
971 order used by OpenSSH.
973 SSH over QUIC removes the version string from the SSH key exchange.
974 Instead, all clients and servers are REQUIRED to send and accept
975 SSH_MSG_EXT_INFO [RFC8308], and to include the "ssh-version"
976 extension defined here.
978 Clients MUST send SSH_MSG_EXT_INFO as the very first SSH packet over
979 QUIC stream 0. The client MUST include the "ssh-version" extension
980 in this SSH_MSG_EXT_INFO.
982 Servers MUST send SSH_MSG_EXT_INFO either:
984 1. as the very first SSH packet over QUIC stream 0, and/or
986 2. immediately preceding the server's SSH_MSG_USERAUTH_SUCCESS.
988 A server MUST include the "ssh-version" extension in at least one of
989 its SSH_MSG_EXT_INFO. If the server sends SSH_MSG_EXT_INFO at both
990 opportunities, it MAY omit "ssh-version" at the first opportunity,
991 but only if it will send it in the second opportunity. The second
992 SSH_MSG_EXT_INFO sent by the server MAY change a previously sent
993 "ssh-version" extension value to include more specific detail. For
994 example, the server MAY send a more accurate server software version
995 when the client has authenticated. The client MUST use the "ssh-
996 version" value which was most recently received from the server.
998 4.1. "ssh-version"
1000 The "ssh-version" extension is encoded in SSH_MSG_EXT_INFO as
1001 follows:
1003 string "ssh-version"
1004 string ssh-version-string
1006 Figure 15
1008 The extension value, "ssh-version-string", contains the same SSH
1009 version string as sent at the start of SSH over TCP ([RFC4253],
1010 Section 4.2), but stripping the prefix "SSH-2.0-". Examples inspired
1011 by version strings used in practice:
1013 GenericSoftware
1014 Product_1.2.00
1015 0.12 Library: Application 1.23p1
1017 Figure 16
1019 4.2. "no-flow-control"
1021 The extension "no-flow-control" has no effect in SSH/QUIC. It SHOULD
1022 NOT be sent in SSH/QUIC and MUST be ignored by both parties.
1024 4.3. "delay-compression"
1026 Semantics of the "delay-compression" extension are modified as per
1027 Section 6.1.1.
1029 5. QUIC Session Setup
1031 When the server has sent its SSH_QUIC_REPLY, and when the client has
1032 received it, they each initialize the QUIC session [QUIC] [QUIC-TLS]
1033 as follows:
1035 * The QUIC protocol version is set to the first version advertised
1036 in the client's SSH_QUIC_INIT which is also present in the
1037 server's SSH_QUIC_REPLY.
1039 * Session state is set as if a TLS handshake had just completed.
1041 * The TLS cipher suite is set to the first TLS cipher suite
1042 advertised in SSH_QUIC_INIT which is also present in
1043 SSH_QUIC_REPLY.
1045 * The QUIC Key Phase bit is set to 0.
1047 * The shared secrets that would have been obtained from the TLS
1048 handshake are instead generated from the SSH key exchange
1049 (Section 5.1).
1051 Clients and servers MUST immediately begin to use QUIC Short Header
1052 Packets. Implementations MUST NOT send QUIC Long Header Packets,
1053 since they could be confused with the SSH/QUIC key exchange.
1055 5.1. Shared Secrets
1057 QUIC-TLS [QUIC-TLS] uses a client secret and a server secret from
1058 which it generates an AEAD key, an IV, and a header protection key
1059 for each sending direction.
1061 An SSH key exchange produces a shared secret K, represented as an SSH
1062 multi-precision integer, and an exchange digest H, represented as
1063 binary data [RFC4253]. An SSH key exchange is parameterized with a
1064 hash function we call HASH. Note that HASH can be a different hash
1065 function, producing a different hash length, than the hash function
1066 used by the negotiated TLS cipher suite.
1068 To compute the initial QUIC client and server secrets, the client and
1069 server encode the following binary data, which we call "secret_data":
1071 mpint K
1072 string H
1074 Figure 17
1076 The client and server secrets are then calculated as follows:
1078 client_secret = HMAC-HASH("ssh/quic client", secret_data)
1079 server_secret = HMAC-HASH("ssh/quic server", secret_data)
1081 Figure 18
1083 The HMAC construct is as specified in [RFC2104], instantiated using
1084 the SSH key exchange hash function, HASH.
1086 QUIC keys and IVs are derived from these secrets using the regular
1087 QUIC-TLS key derivation process [QUIC-TLS]. Keys generated from
1088 these secrets are considered 1-RTT keys.
1090 Clients and servers MUST implement QUIC key updates using the regular
1091 QUIC-TLS key update process [QUIC-TLS], respecting the QUIC-TLS
1092 minimum key update frequencies.
1094 6. Adaptation of SSH to QUIC Streams
1096 6.1. SSH/QUIC Packet Format
1098 Each side serializes its SSH packets for sending over QUIC as
1099 follows:
1101 uint32 n = payload-len, high bit set if compressed
1102 byte[n] payload (compressed or uncompressed)
1104 Figure 19
1106 Since security is provided by QUIC-TLS [QUIC-TLS], MAC and random
1107 padding are omitted at this stage.
1109 The "payload-len" field has its high bit set if the "payload" field
1110 is compressed. See Section 6.1.1.
1112 The "payload" field contains the same packet information as the
1113 "payload" field in the Binary Packet Protocol defined in [RFC4253].
1115 6.1.1. Compression
1117 Compression MAY be negotiated using the "delay-compression" extension
1118 in [RFC8308]. If "delay-compression" was negotiated, then:
1120 * If compression is enabled for the server-to-client direction, the
1121 server MAY compress packets on any stream after it has sent
1122 SSH_MSG_USERAUTH_SUCCESS.
1124 * If compression is enabled for the client-to-server direction, the
1125 client MAY compress packets on any stream after it has received
1126 SSH_MSG_USERAUTH_SUCCESS.
1128 Due to multiple streams in SSH/QUIC, the packet SSH_MSG_NEWCOMPRESS
1129 is not an effective mechanism to signal the start of compression and
1130 MUST NOT be sent. It is replaced by the high bit in "payload-len".
1132 6.2. Use of QUIC Streams
1134 To avoid an unnecessary layer of flow control which has performance
1135 and complexity impacts in SSH over TCP, SSH/QUIC uses QUIC streams
1136 for SSH channels and dispenses with flow control on the level of SSH
1137 channels. This simplifies future SSH/QUIC implementations which
1138 might not implement SSH over TCP.
1140 Conducting SSH channels over QUIC streams requires modifications of
1141 the SSH Connection Protocol [RFC4254]. The following sections
1142 describe these modifications.
1144 6.3. Packet Sequence Numbers
1146 In SSH over TCP, every SSH packet has an implicit sequence number
1147 which is unique for the direction of sending (to server vs. to
1148 client). The packet type SSH_MSG_UNIMPLEMENTED makes reference to
1149 this sequence number.
1151 In SSH/QUIC, sequence numbers are separate for each sending
1152 direction, as well as each QUIC stream. This requires modification
1153 of SSH_MSG_UNIMPLEMENTED. This packet type is changed as follows:
1155 byte SSH_MSG_UNIMPLEMENTED
1156 uint64 QUIC stream ID on which the packet was received
1157 uint32 packet sequence number in stream, first packet = 0
1159 Figure 20
1161 6.4. Channel IDs
1163 SSH over TCP uses 32-bit channel IDs which can be reused in the same
1164 session and do not have to be used sequentially. Conflicts in
1165 channel IDs are avoided by identifying each channel with two separate
1166 channel IDs: one designated by the sender and one by the recipient.
1167 [RFC4254]
1169 QUIC streams use 62-bit channel IDs which cannot be reused and MUST
1170 be used sequentially. Both sides use the same stream ID. Conflicts
1171 in stream IDs are avoided by using the least significant bit to
1172 indicate whether the stream was opened by the client or by the
1173 server. [QUIC]
1175 SSH/QUIC uses QUIC stream IDs. This requires modification of SSH
1176 channel-related packets. See Section 6.8.
1178 6.5. Disconnection
1180 The SSH packet type SSH_MSG_DISCONNECT is replaced by sending the
1181 QUIC frame CONNECTION_CLOSE of type 0x1d. The "Error Code" field in
1182 CONNECTION_CLOSE contains the value that would have been sent in the
1183 "reason code" in SSH_MSG_DISCONNECT. The "Reason Phrase" field in
1184 CONNECTION_CLOSE contains the value that would have been sent in
1185 "description" in SSH_MSG_DISCONNECT. The "language tag" field of
1186 SSH_MSG_DISCONNECT is not sent.
1188 6.6. Prohibited SSH Packets
1190 In SSH/QUIC, the following SSH packet types MUST NOT be sent:
1192 SSH_MSG_DISCONNECT 1
1193 SSH_MSG_NEWCOMPRESS 8
1195 SSH_MSG_KEXINIT 20
1196 SSH_MSG_NEWKEYS 21
1197 key exchange packets 30-49
1199 SSH_MSG_CHANNEL_WINDOW_ADJUST 93
1200 SSH_MSG_CHANNEL_CLOSE 97
1202 Figure 21
1204 If they receive packets of these types, clients and servers MAY
1205 disconnect with SSH_DISCONNECT_PROTOCOL_ERROR (Section 6.5).
1206 Alternately, the receiver MAY send SSH_MSG_UNIMPLEMENTED
1207 (Section 6.3).
1209 6.7. Global SSH Packets
1211 In SSH/QUIC, the following SSH packet types MUST be sent on QUIC
1212 stream 0. With the exception of SSH_MSG_UNIMPLEMENTED (Section 6.3),
1213 these packets use the same encoded formats as in SSH over TCP:
1215 SSH_MSG_IGNORE 2
1216 SSH_MSG_UNIMPLEMENTED 3 (Changed format!)
1217 SSH_MSG_DEBUG 4
1218 SSH_MSG_SERVICE_REQUEST 5
1219 SSH_MSG_SERVICE_ACCEPT 6
1220 SSH_MSG_EXT_INFO 7
1222 SSH_MSG_USERAUTH_REQUEST 50
1223 SSH_MSG_USERAUTH_FAILURE 51
1224 SSH_MSG_USERAUTH_SUCCESS 52
1225 SSH_MSG_USERAUTH_BANNER 53
1226 SSH_MSG_USERAUTH_INFO_REQUEST 60
1227 SSH_MSG_USERAUTH_INFO_RESPONSE 61
1229 SSH_MSG_GLOBAL_REQUEST 80
1230 SSH_MSG_REQUEST_SUCCESS 81
1231 SSH_MSG_REQUEST_FAILURE 82
1233 Figure 22
1235 6.8. SSH Channel Packets
1237 All SSH/QUIC channels MUST be opened as bidirectional QUIC streams.
1238 This means QUIC stream IDs where the least significant bits are 10 or
1239 11 MUST NOT be used in SSH/QUIC. Implementations that receive such
1240 stream IDs MUST disconnect with SSH_DISCONNECT_PROTOCOL_ERROR
1241 (Section 6.5)
1243 A client MUST NOT open a non-zero QUIC stream before the server has
1244 sent SSH_MSG_USERAUTH_SUCCESS. If a client does so, the server MUST
1245 disconnect with SSH_DISCONNECT_PROTOCOL_ERROR.
1247 A server MUST NOT open a non-zero QUIC stream before it has sent
1248 SSH_MSG_USERAUTH_SUCCESS. However, a client MUST be prepared for the
1249 possibility that, due to network delays, a stream opened by the
1250 server can be received by the client before SSH_MSG_USERAUTH_SUCCESS.
1251 Therefore, if the client receives a server-initiated stream before
1252 SSH_MSG_USERAUTH_SUCCESS, it MUST assume that the server has also
1253 sent SSH_MSG_USERAUTH_SUCCESS. If the client then receives packets
1254 on QUIC stream 0 which invalidate this assumption, the client MUST
1255 disconnect with SSH_DISCONNECT_PROTOCOL_ERROR.
1257 The initiator of any non-zero QUIC stream MUST send
1258 SSH_MSG_CHANNEL_OPEN as the first packet. If the receiver refuses
1259 the channel, it replies with SSH_MSG_CHANNEL_OPEN_FAILURE. Both
1260 sides then MUST close the QUIC stream as per Section 6.9. In this
1261 case, even though a QUIC stream was opened, an SSH channel was not.
1262 Therefore, other SSH_MSG_CHANNEL_xxxx packets MUST NOT be sent. This
1263 includes SSH_MSG_CHANNEL_EOF.
1265 If the receiver accepts the channel, it replies with
1266 SSH_MSG_CHANNEL_OPEN_CONFIRMATION. Both sides then send SSH packets
1267 of types SSH_MSG_CHANNEL_xxxx. In SSH/QUIC, these packets have the
1268 following formats:
1270 byte SSH_MSG_CHANNEL_OPEN
1271 string channel type in US-ASCII only
1272 uint32 maximum packet size
1273 .... channel-type-specific data follows
1275 Figure 23
1277 byte SSH_MSG_CHANNEL_OPEN_CONFIRMATION
1278 uint32 maximum packet size
1279 .... channel-type-specific data follows
1281 Figure 24
1283 byte SSH_MSG_CHANNEL_OPEN_FAILURE
1284 uint32 reason code
1285 string description in UTF-8
1286 string language tag
1288 Figure 25
1290 byte SSH_MSG_CHANNEL_DATA
1291 string data
1293 Figure 26
1295 byte SSH_MSG_CHANNEL_EXTENDED_DATA
1296 uint32 data_type_code
1297 string data
1299 Figure 27
1301 byte SSH_MSG_CHANNEL_EOF
1303 Figure 28
1305 byte SSH_MSG_CHANNEL_REQUEST
1306 string request type in US-ASCII characters only
1307 boolean want reply
1308 .... type-specific data follows
1310 Figure 29
1312 byte SSH_MSG_CHANNEL_SUCCESS
1314 Figure 30
1316 byte SSH_MSG_CHANNEL_FAILURE
1318 Figure 31
1320 6.9. Closing a Channel
1322 The SSH packet type SSH_MSG_CHANNEL_CLOSE is replaced by sending the
1323 QUIC frame STREAM with the FIN bit set. Each side considers a
1324 channel closed when all stream data has been received and sent, and
1325 signaled using the QUIC stream FIN bit.
1327 SSH/QUIC continues to use the SSH packet type SSH_MSG_CHANNEL_EOF.
1328 This packet often does NOT correspond with the end of the QUIC
1329 stream. As in SSH over TCP, SSH channel requests, such as "exit-
1330 status", MAY be sent after SSH_MSG_CHANNEL_EOF, and MUST be handled
1331 gracefully by receivers.
1333 7. IANA Considerations
1335 This document requests no changes to IANA registries.
1337 8. Security Considerations
1339 Clients and servers MUST insert into SSH_QUIC_INIT and SSH_QUIC_REPLY
1340 at least the minimum amount of cryptographically random data as
1341 specified in the section Random Elements. Compromising on this
1342 requirement reduces the security of any session created on the basis
1343 of such an SSH_QUIC_INIT or SSH_QUIC_REPLY.
1345 9. References
1347 9.1. Normative References
1349 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed
1350 and Secure Transport", 2020, .
1353 [QUIC-TLS] Thomson, M. and S. Turner, "Using TLS to Secure QUIC",
1354 2020,
1355 .
1357 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
1358 Hashing for Message Authentication", RFC 2104,
1359 DOI 10.17487/RFC2104, February 1997,
1360 .
1362 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1363 Requirement Levels", BCP 14, RFC 2119,
1364 DOI 10.17487/RFC2119, March 1997,
1365 .
1367 [RFC4251] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
1368 Protocol Architecture", RFC 4251, DOI 10.17487/RFC4251,
1369 January 2006, .
1371 [RFC4253] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
1372 Transport Layer Protocol", RFC 4253, DOI 10.17487/RFC4253,
1373 January 2006, .
1375 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated
1376 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008,
1377 .
1379 [RFC5656] Stebila, D. and J. Green, "Elliptic Curve Algorithm
1380 Integration in the Secure Shell Transport Layer",
1381 RFC 5656, DOI 10.17487/RFC5656, December 2009,
1382 .
1384 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
1385 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
1386 May 2017, .
1388 [RFC8308] Bider, D., "Extension Negotiation in the Secure Shell
1389 (SSH) Protocol", RFC 8308, DOI 10.17487/RFC8308, March
1390 2018, .
1392 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
1393 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
1394 .
1396 [RFC8731] Adamantiadis, A., Josefsson, S., and M. Baushke, "Secure
1397 Shell (SSH) Key Exchange Method Using Curve25519 and
1398 Curve448", RFC 8731, DOI 10.17487/RFC8731, February 2020,
1399 .
1401 9.2. Informative References
1403 [IANA-SSH] IANA, "Secure Shell (SSH) Protocol Parameters",
1404 .
1406 [RFC4250] Lehtinen, S. and C. Lonvick, Ed., "The Secure Shell (SSH)
1407 Protocol Assigned Numbers", RFC 4250,
1408 DOI 10.17487/RFC4250, January 2006,
1409 .
1411 [RFC4252] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
1412 Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252,
1413 January 2006, .
1415 [RFC4254] Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
1416 Connection Protocol", RFC 4254, DOI 10.17487/RFC4254,
1417 January 2006, .
1419 Appendix A. Generating Random Lengths
1421 The SSH/QUIC extensibility mechanism calls for generating random
1422 lengths such that values in the shorter end of the range are
1423 significantly more probable, but long lengths are still selected.
1424 The following C example shows a simple two-step process to prefer
1425 shorter lengths:
1427 int RandomIntBetweenZeroAnd(int maxValueInclusive);
1429 int RandomLen_PreferShort(int minLen, int maxLen)
1430 {
1431 int const SPAN_THRESHOLD = 7;
1432 int lenSpan = maxLen - minLen;
1434 if (lenSpan <= 0)
1435 return minLen;
1437 if (lenSpan > SPAN_THRESHOLD)
1438 if (0 != RandomIntBetweenZeroAnd(3))
1439 return minLen + RandomIntBetweenZeroAnd(SPAN_THRESHOLD);
1441 return minLen + RandomIntBetweenZeroAnd(lenSpan);
1442 }
1444 Figure 32
1446 Author's Address
1447 denis bider
1448 Bitvise Limited
1449 4105 Lombardy Ct
1450 Colleyville, TX 76034
1451 United States
1453 Email: ietf-draft@denisbider.com