idnits 2.17.1 draft-duke-quic-retry-offload-00.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 are 2 instances of too long lines in the document, the longest one being 6 characters in excess of 72. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 889 has weird spacing: '...-number uin...' == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (28 March 2022) is 731 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-19) exists of draft-ietf-quic-load-balancers-12 Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 QUIC M. Duke 3 Internet-Draft Google 4 Intended status: Standards Track N. Banks 5 Expires: 29 September 2022 Microsoft 6 28 March 2022 8 QUIC Retry Offload 9 draft-duke-quic-retry-offload-00 11 Abstract 13 QUIC uses Retry packets to reduce load on stressed servers, by 14 forcing the client to prove ownership of its address before the 15 server commits state. QUIC also has an anti-tampering mechanism to 16 prevent the unauthorized injection of Retry packets into a 17 connection. However, a server operator may want to offload 18 production of Retry packets to an anti-Denial-of-Service agent or 19 hardware accelerator. "Retry Offload" is a mechanism for 20 coordination between a server and an external generator of Retry 21 packets that can succeed despite the anti-tampering mechanism. 23 Note to Readers 25 Discussion of this document takes place on the QUIC Working Group 26 mailing list (quic@ietf.org), which is archived at 27 https://mailarchive.ietf.org/arch/browse/quic/ 28 (https://mailarchive.ietf.org/arch/browse/quic/). 30 Source for this draft and an issue tracker can be found at 31 https://github.com/quicwg/load-balancers (https://github.com/quicwg/ 32 load-balancers). 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on 29 September 2022. 50 Copyright Notice 52 Copyright (c) 2022 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 57 license-info) in effect on the date of publication of this document. 58 Please review these documents carefully, as they describe your rights 59 and restrictions with respect to this document. Code Components 60 extracted from this document must include Revised BSD License text as 61 described in Section 4.e of the Trust Legal Provisions and are 62 provided without warranty as described in the Revised BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 68 1.2. Notation . . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. Common Requirements . . . . . . . . . . . . . . . . . . . . . 5 70 2.1. Considerations for Non-Initial Packets . . . . . . . . . 6 71 3. No-Shared-State Retry Offload . . . . . . . . . . . . . . . . 7 72 3.1. Configuration Agent Actions . . . . . . . . . . . . . . . 7 73 3.2. Offload Requirements . . . . . . . . . . . . . . . . . . 7 74 3.3. Server Requirements . . . . . . . . . . . . . . . . . . . 9 75 4. Shared-State Retry Offload . . . . . . . . . . . . . . . . . 9 76 4.1. Token Protection with AEAD . . . . . . . . . . . . . . . 11 77 4.2. Configuration Agent Actions . . . . . . . . . . . . . . . 12 78 4.3. Offload Requirements . . . . . . . . . . . . . . . . . . 13 79 4.4. Server Requirements . . . . . . . . . . . . . . . . . . . 14 80 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 81 5.1. Shared-State Retry Keys . . . . . . . . . . . . . . . . . 14 82 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 83 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 84 7.1. Normative References . . . . . . . . . . . . . . . . . . 15 85 7.2. Informative References . . . . . . . . . . . . . . . . . 15 86 Appendix A. Retry Offload YANG Model . . . . . . . . . . . . . . 16 87 A.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 19 88 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 20 89 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 20 90 C.1. since draft-ietf-quic-load-balancers-12 . . . . . . . . . 20 91 C.2. since draft-ietf-quic-load-balancers-11 . . . . . . . . . 20 92 C.3. since draft-ietf-quic-load-balancers-10 . . . . . . . . . 20 93 C.4. since draft-ietf-quic-load-balancers-09 . . . . . . . . . 20 94 C.5. since draft-ietf-quic-load-balancers-08 . . . . . . . . . 21 95 C.6. since draft-ietf-quic-load-balancers-07 . . . . . . . . . 21 96 C.7. since draft-ietf-quic-load-balancers-06 . . . . . . . . . 21 97 C.8. since draft-ietf-quic-load-balancers-05 . . . . . . . . . 21 98 C.9. since draft-ietf-quic-load-balancers-04 . . . . . . . . . 22 99 C.10. since-draft-ietf-quic-load-balancers-03 . . . . . . . . . 22 100 C.11. since-draft-ietf-quic-load-balancers-02 . . . . . . . . . 22 101 C.12. since-draft-ietf-quic-load-balancers-01 . . . . . . . . . 22 102 C.13. since-draft-ietf-quic-load-balancers-00 . . . . . . . . . 23 103 C.14. Since draft-duke-quic-load-balancers-06 . . . . . . . . . 23 104 C.15. Since draft-duke-quic-load-balancers-05 . . . . . . . . . 23 105 C.16. Since draft-duke-quic-load-balancers-04 . . . . . . . . . 23 106 C.17. Since draft-duke-quic-load-balancers-03 . . . . . . . . . 23 107 C.18. Since draft-duke-quic-load-balancers-02 . . . . . . . . . 23 108 C.19. Since draft-duke-quic-load-balancers-01 . . . . . . . . . 24 109 C.20. Since draft-duke-quic-load-balancers-00 . . . . . . . . . 24 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 112 1. Introduction 114 QUIC [RFC9000] servers send Retry packets to avoid prematurely 115 allocating resources when under stress, such as during a Denial of 116 Service (DoS) attack. Because both Initial packets and Retry packets 117 have weak authentication properties, the Retry packet contains an 118 encrypted token that helps the client and server to validate, via 119 transport parameters, that an attacker did not inject or modify a 120 packet of either type for this connection attempt. 122 However, a server under stress is less inclined to process incoming 123 Initial packets and compute the Retry token in the first place. An 124 analogous mechanism for TCP is syncookies [RFC4987]. As TCP has 125 weaker authentication properties to QUIC, syncookie generation can 126 often be offloaded to a hardware device, or to a anti-Denial-of- 127 Service provider that is topologically far from the protected server. 128 As such an offload would behave exactly like an attacker, QUIC's 129 authentication methods make such a capability impossible. 131 This document seeks to enable offloading of Retry generation to QUIC 132 via explicit coordination between servers and the hardware or 133 provider offload, which this document refers to as a "Retry Offload." 134 It has two different modes, to conform to two different use cases. 136 The no-shared-state mode has minimal coordination and does not 137 require key sharing. While operationally easier to configure and 138 manage, it places severe constraints on the operational profile of 139 the offload. In particular, the offload must control all ingress to 140 the server and fail closed. 142 The shared-state mode removes the operational constraints, but also 143 requires more sophisticated key management. 145 Both modes specify a common format for encoding information in the 146 Retry token, so that the server can correctly populate the relevant 147 transport parameter fields. 149 1.1. Terminology 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 153 document are to be interpreted as described in RFC 2119 [RFC2119]. 155 In this document, these words will appear with that interpretation 156 only when in ALL CAPS. Lower case uses of these words are not to be 157 interpreted as carrying significance described in RFC 2119. 159 For brevity, "Connection ID" will often be abbreviated as "CID". 161 A "Retry Offload" is a hardware or software device that is 162 conceptually separate from a QUIC server that terminates QUIC 163 connections. This document assumes that the Retry Offload and the 164 server have an administrative relationship that allows them to accept 165 common configuation. 167 A "configuration agent" is some entity that determines the common 168 configuration to be distributed to the servers and the Retry Offload. 170 This document uses "QUIC" to refer to the protocol in QUIC version 1 171 [RFC9000]. Retry offloads can be applied to other versions of QUIC 172 that use Retry packets and have identical information requirements 173 for Retry validation. However, note that source and destination 174 connection IDs are the only relevant data fields that are invariant 175 across QUIC versions [RFC8999]. 177 1.2. Notation 179 All wire formats will be depicted using the notation defined in 180 Section 1.3 of [RFC9000]. 182 The example below illustrates the basic framework: 184 Example Structure { 185 One-bit Field (1), 186 7-bit Field with Fixed Value (7) = 61, 187 Field with Variable-Length Integer (i), 188 Arbitrary-Length Field (..), 189 Variable-Length Field (8..24), 190 Variable-Length Field with Dynamic Limit (8..24-len(Variable-Length Field)), 191 Field With Minimum Length (16..), 192 Field With Maximum Length (..128), 193 [Optional Field (64)], 194 Repeated Field (8) ..., 195 } 197 Figure 1: Example Format 199 2. Common Requirements 201 Regardless of mechanism, a Retry Offload has an active mode, where it 202 is generating Retry packets, and an inactive mode, where it is not, 203 based on its assessment of server load and the likelihood an attack 204 is underway. The choice of mode MAY be made on a per-packet or per- 205 connection basis, through a stochastic process or based on client 206 address. 208 A configuration agent MUST distribute a list of QUIC versions the 209 Retry Offload supports. It MAY also distribute either an "Allow- 210 List" or a "Deny-List" of other QUIC versions. It MUST NOT 211 distribute both an Allow-List and a Deny-List. 213 The Allow-List or Deny-List MUST NOT include any versions included 214 for Retry Offload support. 216 The Configuration Agent MUST provide a means for the entity that 217 controls the Retry Offload to report its supported version(s) to the 218 configuration Agent. If the entity has not reported this 219 information, it MUST NOT activate the Retry Offload and the 220 configuration agent MUST NOT distribute configuration that activates 221 it. 223 The configuration agent MAY delete versions from the final supported 224 version list if policy does not require the Retry Offload to operate 225 on those versions. 227 The configuration Agent MUST provide a means for the entities that 228 control servers behind the Retry Offload to report either an Allow- 229 List or a Deny-List. 231 If all entities supply Allow-Lists, the consolidated list MUST be the 232 union of these sets. If all entities supply Deny-Lists, the 233 consolidated list MUST be the intersection of these sets. 235 If entities provide a mixture of Allow-Lists and Deny-Lists, the 236 consolidated list MUST be a Deny-List that is the intersection of all 237 provided Deny-Lists and the inverses of all Allow-Lists. 239 If no entities that control servers have reported Allow-Lists or 240 Deny-Lists, the default is a Deny-List with the null set (i.e., all 241 unsupported versions will be admitted). This preserves the future 242 extensibilty of QUIC. 244 A Retry Offload MUST forward all packets for a QUIC version it does 245 not support that are not on a Deny-List or absent from an Allow-List. 246 Note that if servers support versions the Retry Offload does not, 247 this may increase load on the servers. 249 Note that future versions of QUIC might not have Retry packets, 250 require different information in Retry, or use different packet type 251 indicators. 253 2.1. Considerations for Non-Initial Packets 255 Initial Packets are especially effective at consuming server 256 resources because they cause the server to create connection state. 257 Even when mitigating this load with Retry Packets, the act of 258 validating an Initial Token and sending a Retry Packet is more 259 expensive than the response to a non-Initial packet with an unknown 260 Connection ID: simply dropping it and/or sending a Stateless Reset. 262 Nevertheless, a Retry Offload in Active Mode might desire to shield 263 servers from non-Initial packets that do not correspond to a 264 previously admitted Initial Packet. This has a number of 265 considerations. 267 * If a Retry Offload maintains no per-flow state, it cannot 268 distinguish between valid and invalid non-Initial packets and MUST 269 forward all non-Initial Packets to the server. 271 * For QUIC versions the Retry Offload does not support and are 272 present on the Allow-List (or absent from the Deny-List), the 273 Retry Offload cannot distinguish Initial Packets from other long 274 headers and therefore MUST admit all long headers. 276 * If a Retry Offload keeps per-flow state, it can identify 4-tuples 277 that have been previously approved, admit non-Initial packets from 278 those flows, and drop all others. However, dropping short headers 279 will effectively break Address Migration and NAT Rebinding when in 280 Active Mode, as post-migration packets will arrive with a 281 previously unknown 4-tuple. This policy will also break 282 connection attempts using any new QUIC versions that begin 283 connections with a short header. 285 * If a Retry Offload is integrated with a QUIC-LB routable load 286 balancer [I-D.ietf-quic-load-balancers], it can verify that the 287 Destination Connection ID is routable, and only admit non-Initial 288 packets with routable DCIDs. As the Connection ID encoding is 289 invariant across QUIC versions, the Retry Offload can do this for 290 all short headers. 292 Nothing in this section prevents Retry Offloads from making basic 293 syntax correctness checks on packets with QUIC versions that it 294 understands (e.g., enforcing the Initial Packet datagram size minimum 295 in version 1). 297 3. No-Shared-State Retry Offload 299 The no-shared-state Retry Offload requires no coordination, except 300 that the server must be configured to accept this offload and know 301 which QUIC versions the Retry Offload supports. The scheme uses the 302 first bit of the token to distinguish between tokens from Retry 303 packets (codepoint '0') and tokens from NEW_TOKEN frames (codepoint 304 '1'). 306 3.1. Configuration Agent Actions 308 See Section 2. 310 3.2. Offload Requirements 312 A no-shared-state Retry Offload MUST be present on all paths from 313 potential clients to the server. These paths MUST fail to pass QUIC 314 traffic should the offload fail for any reason. That is, if the 315 offload is not operational, the server MUST NOT be exposed to client 316 traffic. Otherwise, servers that have already disabled their Retry 317 capability would be vulnerable to attack. 319 The path between offload and server MUST be free of any potential 320 attackers. Note that this and other requirements above severely 321 restrict the operational conditions in which a no-shared-state Retry 322 Offload can safely operate. 324 Retry tokens generated by the offload MUST have the format below. 326 No-Shared-State Retry Offload Token { 327 Token Type (1) = 0, 328 ODCIL (7) = 8..20, 329 Original Destination Connection ID (64..160), 330 Opaque Data (..), 331 } 333 Figure 2: Format of non-shared-state Retry Offload tokens 335 The first bit of retry tokens generated by the offload MUST be zero. 336 The token has the following additional fields: 338 ODCIL: The length of the original destination connection ID from the 339 triggering Initial packet. This is in cleartext to be readable for 340 the server, but authenticated later in the token. The Retry Offload 341 SHOULD reject any token in which the value is less than 8. 343 Original Destination Connection ID: This also in cleartext and 344 authenticated later. 346 Opaque Data: This data contains the information necessary to 347 authenticate the Retry token in accordance with the QUIC 348 specification. A straightforward implementation would encode the 349 Retry Source Connection ID, client IP address, and a timestamp in the 350 Opaque Data. A more space-efficient implementation would use the 351 Retry Source Connection ID and Client IP as associated data in an 352 encryption operation, and encode only the timestamp and the 353 authentication tag in the Opaque Data. If the Initial Packet has 354 altered the Connection ID or source IP address, authentication of the 355 token will fail. 357 Upon receipt of an Initial packet with a token that begins with '0', 358 the Retry Offload MUST validate the token in accordance with the QUIC 359 specification. 361 In active mode, the offload MUST issue Retry packets for all Client 362 initial packets that contain no token, or a token that has the first 363 bit set to '1'. It MUST NOT forward the packet to the server. The 364 offload MUST validate all tokens with the first bit set to '0'. If 365 successful, the offload MUST forward the packet with the token 366 intact. If unsuccessful, it MUST drop the packet. The Retry Offload 367 MAY send an Initial Packet containing a CONNECTION_CLOSE frame with 368 the INVALID_TOKEN error code when dropping the packet. 370 Note that this scheme has a performance drawback. When the Retry 371 Offload is in active mode, clients with a token from a NEW_TOKEN 372 frame will suffer a 1-RTT penalty even though its token provides 373 proof of address. 375 In inactive mode, the offload MUST forward all packets that have no 376 token or a token with the first bit set to '1'. It MUST validate all 377 tokens with the first bit set to '0'. If successful, the offload 378 MUST forward the packet with the token intact. If unsuccessful, it 379 MUST either drop the packet or forward it with the token removed. 380 The latter requires decryption and re-encryption of the entire 381 Initial packet to avoid authentication failure. Forwarding the 382 packet causes the server to respond without the 383 original_destination_connection_id transport parameter, which 384 preserves the normal QUIC signal to the client that there is an on- 385 path attacker. 387 3.3. Server Requirements 389 A server behind a non-shared-state Retry Offload MUST NOT send Retry 390 packets for a QUIC version the Retry Offload understands. It MAY 391 send Retry for QUIC versions the Retry Offload does not understand. 393 Tokens sent in NEW_TOKEN frames MUST have the first bit set to '1'. 395 If a server receives an Initial Packet with the first bit in the 396 token set to '1', it could be from a server-generated NEW_TOKEN frame 397 and should be processed in accordance with the QUIC specification. 398 If a server receives an Initial Packet with the first bit to '0', it 399 is a Retry token and the server MUST NOT attempt to validate it. 400 Instead, it MUST assume the address is validated, MUST include the 401 packet's Destination Connection ID in a Retry Source Connection ID 402 transport parameter, and MUST extract the Original Destination 403 Connection ID from the token cleartext for use in the transport 404 parameter of the same name. 406 4. Shared-State Retry Offload 408 A shared-state Retry Offload uses a shared key, so that the server 409 can decode the offload's retry tokens. It does not require that all 410 traffic pass through the Retry Offload, so servers MAY send Retry 411 packets in response to Initial packets that don't include a valid 412 token. 414 Both server and offload MUST have time synchronized with respect to 415 one another to prevent tokens being incorrectly marked as expired, 416 though tight synchronization is unnecessary. 418 The tokens are protected using AES128-GCM AEAD, as explained in 419 Section 4.1. All tokens, generated by either the server or Retry 420 Offload, MUST use the following format, which includes: 422 * A 1 bit token type identifier. 424 * A 7 bit token key identifier. 426 * A 96 bit unique token number transmitted in clear text, but 427 protected as part of the AEAD associated data. 429 * A token body, encoding the Original Destination Connection ID and 430 the Timestamp, optionally followed by server specific Opaque Data. 432 The token protection uses an 128 bit representation of the source IP 433 address from the triggering Initial packet. The client IP address is 434 16 octets. If an IPv4 address, the last 12 octets are zeroes. It 435 also uses the Source Connection ID of the Retry packet, which will 436 cause an authentication failure if it differs from the Destination 437 Connection ID of the packet bearing the token. 439 If there is a Network Address Translator (NAT) in the server 440 infrastructure that changes the client IP, the Retry Offload MUST 441 either be positioned behind the NAT, or the NAT must have the token 442 key to rewrite the Retry token accordingly. Note also that a host 443 that obtains a token through a NAT and then attempts to connect over 444 a path that does not have an identically configured NAT will fail 445 address validation. 447 The 96 bit unique token number is set to a random value using a 448 cryptography-grade random number generator. 450 The token key identifier and the corresponding AEAD key and AEAD IV 451 are provisioned by the configuration agent. 453 The token body is encoded as follows: 455 Shared-State Retry Offload Token Body { 456 Timestamp (64), 457 [ODCIL (8) = 8..20], 458 [Original Destination Connection ID (64..160)], 459 [Port (16)], 460 Opaque Data (..), 461 } 463 Figure 3: Body of shared-state Retry Offload tokens 465 The token body has the following fields: 467 Timestamp: The Timestamp is a 64-bit integer, in network order, that 468 expresses the expiration time of the token as a number of seconds in 469 POSIX time (see Sec. 4.16 of [TIME_T]). 471 ODCIL: The original destination connection ID length. Tokens in 472 NEW_TOKEN frames do not have this field. 474 Original Destination Connection ID: The server or Retry Offload 475 copies this from the field in the client Initial packet. Tokens in 476 NEW_TOKEN frames do not have this field. 478 Port: The Source Port of the UDP datagram that triggered the Retry 479 packet. This field MUST be present if and only if the ODCIL is 480 greater than zero. This field is therefore always absent in tokens 481 in NEW_TOKEN frames. 483 Opaque Data: The server may use this field to encode additional 484 information, such as congestion window, RTT, or MTU. The Retry 485 Offload MUST have zero-length opaque data. 487 Some implementations of QUIC encode in the token the Initial Packet 488 Number used by the client, in order to verify that the client sends 489 the retried Initial with a PN larger that the triggering Initial. 490 Such implementations will encode the Initial Packet Number as part of 491 the opaque data. As tokens may be generated by the Service, servers 492 MUST NOT reject tokens because they lack opaque data and therefore 493 the packet number. 495 Shared-state Retry Offloads use the AES-128-ECB cipher. Future 496 standards could add new algorithms that use other ciphers to provide 497 cryptographic agility in accordance with [RFC7696]. Retry Offload 498 and server implementations SHOULD be extensible to support new 499 algorithms. 501 4.1. Token Protection with AEAD 503 On the wire, the token is presented as: 505 Shared-State Retry Offload Token { 506 Token Type (1), 507 Key Sequence (7), 508 Unique Token Number (96), 509 Encrypted Shared-State Retry Offload Token Body (64..), 510 AEAD Integrity Check Value (128), 511 } 513 Figure 4: Wire image of shared-state Retry Offload tokens 515 The tokens are protected using AES128-GCM as follows: 517 * The Key Sequence is the 7 bit identifier to retrieve the token key 518 and IV. 520 * The AEAD IV, is a 96 bit data which produced by implementer's 521 custom AEAD IV derivation function. 523 * The AEAD nonce, N, is formed by combining the AEAD IV with the 96 524 bit unique token number. The 96 bits of the unique token number 525 are left-padded with zeros to the size of the IV. The exclusive 526 OR of the padded unique token number and the AEAD IV forms the 527 AEAD nonce. 529 * The associated data is a formatted as a pseudo header by combining 530 the cleartext part of the token with the IP address of the client. 531 The format of the pseudoheader depends on whether the Token Type 532 bit is '1' (a NEW_TOKEN token) or '0' (a Retry token). 534 Shared-State Retry Offload Token Pseudoheader { 535 IP Address (128), 536 Token Type (1), 537 Key Sequence (7), 538 Unique Token Number (96), 539 [RSCIL (8)], 540 [Retry Source Connection ID (0..20)], 541 } 543 Figure 5: Psuedoheader for shared-state Retry Offload tokens 545 RSCIL: The Retry Source Connection ID Length in octets. This field 546 is only present when the Token Type is '0'. 548 Retry Source Connection ID: To create a Retry Token, populate this 549 field with the Source Connection ID the Retry packet will use. To 550 validate a Retry token, populate it with the Destination Connection 551 ID of the Initial packet that carries the token. This field is only 552 present when the Token Type is '0'. 554 * The input plaintext for the AEAD is the token body. The output 555 ciphertext of the AEAD is transmitted in place of the token body. 557 * The AEAD Integrity Check Value(ICV), defined in Section 6 of 558 [RFC4106], is computed as part of the AEAD encryption process, and 559 is verified during decryption. 561 4.2. Configuration Agent Actions 563 The configuration agent generates and distributes a "token key", a 564 "token IV", a key sequence, and the information described in 565 Section 2. 567 4.3. Offload Requirements 569 In inactive mode, the Retry Offload forwards all packets without 570 further inspection or processing. The rest of this section only 571 applies to a offload in active mode. 573 Retry Offloads MUST NOT issue Retry packets except where explicitly 574 allowed below, to avoid sending a Retry packet in response to a Retry 575 token. 577 The offload MUST generate Retry tokens with the format described 578 above when it receives a client Initial packet with no token. 580 If there is a token of either type, the offload MUST attempt to 581 decrypt it. 583 To decrypt a packet, the offload checks the Token Type and constructs 584 a pseudoheader with the appropriate format for that type, using the 585 bearing packet's Destination Connection ID to populate the Retry 586 Source Connection ID field, if any. 588 A token is invalid if: 590 * it uses unknown key sequence, 592 * the AEAD ICV does not match the expected value (By construction, 593 it will only match if the client IP Address, and any Retry Source 594 Connection ID, also matches), 596 * the ODCIL, if present, is invalid for a client-generated CID (less 597 than 8 or more than 20 in QUIC version 1), 599 * the Timestamp of a token points to time in the past (however, in 600 order to allow for clock skew, it SHOULD NOT consider tokens to be 601 expired if the Timestamp encodes a few seconds in the past), or 603 * the port number, if present, does not match the source port in the 604 encapsulating UDP header. 606 Packets with valid tokens MUST be forwarded to the server. 608 The offload MUST drop packets with invalid tokens. If the token is 609 of type '1' (NEW_TOKEN), it MUST respond with a Retry packet. If of 610 type '0', it MUST NOT respond with a Retry packet. 612 4.4. Server Requirements 614 The server MAY issue Retry or NEW_TOKEN tokens in accordance with 615 [RFC9000]. When doing so, it MUST follow the format above. 617 The server MUST validate all tokens that arrive in Initial packets, 618 as they may have bypassed the Retry Offload. It determines validity 619 using the procedure in Section 4.3. 621 If a valid Retry token, the server populates the 622 original_destination_connection_id transport parameter using the 623 corresponding token field. It populates the 624 retry_source_connection_id transport parameter with the Destination 625 Connection ID of the packet bearing the token. 627 In all other respects, the server processes both valid and invalid 628 tokens in accordance with [RFC9000]. 630 For QUIC versions the offload does not support, the server MAY use 631 any token format. 633 5. Security Considerations 635 5.1. Shared-State Retry Keys 637 The Shared-State Retry Offload defined in Section 4 describes the 638 format of retry tokens or new tokens protected and encrypted using 639 AES128-GCM. Each token includes a 96 bit randomly generated unique 640 token number, and an 8 bit identifier used to get the AES-GCM 641 encryption context. The AES-GCM encryption context contains a 128 642 bit key and an AEAD IV. There are three important security 643 considerations for these tokens: 645 * An attacker that obtains a copy of the encryption key will be able 646 to decrypt and forge tokens. 648 * Attackers may be able to retrieve the key if they capture a 649 sufficently large number of retry tokens encrypted with a given 650 key. 652 * Confidentiality of the token data will fail if separate tokens 653 reuse the same 96 bit unique token number and the same key. 655 To protect against disclosure of keys to attackers, offload and 656 servers MUST ensure that the keys are stored securely. To limit the 657 consequences of potential exposures, the time to live of any given 658 key should be limited. 660 Section 6.6 of [RFC9001] states that "Endpoints MUST count the number 661 of encrypted packets for each set of keys. If the total number of 662 encrypted packets with the same key exceeds the confidentiality limit 663 for the selected AEAD, the endpoint MUST stop using those keys." It 664 goes on with the specific limit: "For AEAD_AES_128_GCM and 665 AEAD_AES_256_GCM, the confidentiality limit is 2^23 encrypted 666 packets; see Appendix B.1." It is prudent to adopt the same limit 667 here, and configure the offload in such a way that no more than 2^23 668 tokens are generated with the same key. 670 In order to protect against collisions, the 96 bit unique token 671 numbers should be generated using a cryptographically secure 672 pseudorandom number generator (CSPRNG), as specified in Appendix C.1 673 of the TLS 1.3 specification [RFC8446]. With proper random numbers, 674 if fewer than 2^40 tokens are generated with a single key, the risk 675 of collisions is lower than 0.001%. 677 6. IANA Considerations 679 There are no IANA requirements. 681 7. References 683 7.1. Normative References 685 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 686 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 687 . 689 [RFC9000] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 690 Multiplexed and Secure Transport", RFC 9000, 691 DOI 10.17487/RFC9000, May 2021, 692 . 694 [TIME_T] "Open Group Standard: Vol. 1: Base Definitions, Issue 7", 695 IEEE Std 1003.1 , 2018, 696 . 699 7.2. Informative References 701 [I-D.ietf-quic-load-balancers] 702 Duke, M., Banks, N., and C. Huitema, "QUIC-LB: Generating 703 Routable QUIC Connection IDs", Work in Progress, Internet- 704 Draft, draft-ietf-quic-load-balancers-12, 11 February 705 2022, . 708 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 709 Requirement Levels", BCP 14, RFC 2119, 710 DOI 10.17487/RFC2119, March 1997, 711 . 713 [RFC4106] Viega, J. and D. McGrew, "The Use of Galois/Counter Mode 714 (GCM) in IPsec Encapsulating Security Payload (ESP)", 715 RFC 4106, DOI 10.17487/RFC4106, June 2005, 716 . 718 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 719 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 720 . 722 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 723 the Network Configuration Protocol (NETCONF)", RFC 6020, 724 DOI 10.17487/RFC6020, October 2010, 725 . 727 [RFC7696] Housley, R., "Guidelines for Cryptographic Algorithm 728 Agility and Selecting Mandatory-to-Implement Algorithms", 729 BCP 201, RFC 7696, DOI 10.17487/RFC7696, November 2015, 730 . 732 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 733 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 734 . 736 [RFC8999] Thomson, M., "Version-Independent Properties of QUIC", 737 RFC 8999, DOI 10.17487/RFC8999, May 2021, 738 . 740 [RFC9001] Thomson, M., Ed. and S. Turner, Ed., "Using TLS to Secure 741 QUIC", RFC 9001, DOI 10.17487/RFC9001, May 2021, 742 . 744 Appendix A. Retry Offload YANG Model 746 These YANG models conform to [RFC6020] and express a complete Retry 747 Offload configuration. 749 module ietf-retry-offload { 750 yang-version "1.1"; 751 namespace "urn:ietf:params:xml:ns:yang:ietf-quic-lb"; 752 prefix "quic-lb"; 754 import ietf-yang-types { 755 prefix yang; 756 reference 757 "RFC 6991: Common YANG Data Types."; 758 } 760 import ietf-inet-types { 761 prefix inet; 762 reference 763 "RFC 6991: Common YANG Data Types."; 764 } 766 organization 767 "IETF QUIC Working Group"; 769 contact 770 "WG Web: 771 WG List: 773 Authors: Martin Duke (martin.h.duke at gmail dot com) 774 Nick Banks (nibanks at microsoft dot com) 775 Christian Huitema (huitema at huitema.net)"; 777 description 778 "This module enables the explicit cooperation of QUIC servers 779 with offloads that generate Retry packets on their behalf. 781 Copyright (c) 2022 IETF Trust and the persons identified as 782 authors of the code. All rights reserved. 784 Redistribution and use in source and binary forms, with or 785 without modification, is permitted pursuant to, and subject to 786 the license terms contained in, the Simplified BSD License set 787 forth in Section 4.c of the IETF Trust's Legal Provisions 788 Relating to IETF Documents 789 (https://trustee.ietf.org/license-info). 791 This version of this YANG module is part of RFC XXXX 792 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 793 for full legal notices. 795 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 796 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 797 'MAY', and 'OPTIONAL' in this document are to be interpreted as 798 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 799 they appear in all capitals, as shown here."; 801 revision "2022-02-11" { 802 description 803 "Initial version"; 805 reference 806 "RFC XXXX, QUIC Retry Offloads"; 807 } 809 container retry-offload-config { 810 description 811 "Configuration of Retry Offload. If supported-versions is empty, 812 there is no Retry Offload. If token-keys is empty, it uses the 813 non-shared-state offload. If present, it uses shared-state 814 tokens."; 816 leaf-list supported-versions { 817 type uint32; 818 description 819 "QUIC versions that the Retry Offload supports. If empty, 820 there is no Retry Offload."; 821 } 823 leaf unsupported-version-default { 824 type enumeration { 825 enum allow { 826 description "Unsupported versions admitted by default"; 827 } 828 enum deny { 829 description "Unsupported versions denied by default"; 830 } 831 } 832 default allow; 833 description 834 "Are unsupported versions not in version-exceptions allowed 835 or denied?"; 836 } 838 leaf-list version-exceptions { 839 type uint32; 840 description 841 "Exceptions to the default-deny or default-allow rule."; 842 } 844 list token-keys { 845 key "key-sequence-number"; 846 description 847 "list of active keys, for key rotation purposes. Existence 848 implies shared-state format"; 850 leaf key-sequence-number { 851 type uint8 { 852 range "0..127"; 854 } 855 mandatory true; 856 description 857 "Identifies the key used to encrypt the token"; 858 } 860 leaf token-key { 861 type retry-offload-key; 862 mandatory true; 863 description 864 "16-byte key to encrypt the token"; 865 } 867 leaf token-iv { 868 type yang:hex-string { 869 length 23; 870 } 871 mandatory true; 872 description 873 "8-byte IV to encrypt the token, encoded in 23 bytes"; 874 } 875 } 876 } 877 } 879 A.1. Tree Diagram 881 This summary of the YANG models uses the notation in [RFC8340]. 883 module: retry-offload-config 884 +--rw retry-offload-config 885 +--rw supported-versions* uint32 886 +--rw unsupported-version-default? enumeration 887 +--rw version-exceptions* uint32 888 +--rw token-keys* [key-sequence-number] 889 +--rw key-sequence-number uint8 890 +--rw token-key quic-lb-key 891 +--rw token-iv yang:hex-string 893 ## Shared State Retry Token Test Vectors 895 In this case, the shared-state retry token is issued by Retry Offload, so the 896 opaque data of shared-state retry token body would be null 897 ({{shared-state-retry}}). 899 Configuration: key_seq 0x00 encrypt_key 900 0x30313233343536373839303132333435 AEAD_IV 0x313233343536373839303132 901 Shared-State Retry Offload Token Body: ODCIL 0x12 RSCIL 0x10 port 902 0x1a0a original_destination_connection_id 903 0x0c3817b544ca1c94313bba41757547eec937 retry_source_connection_id 904 0x0301e770d24b3b13070dd5c2a9264307 timestamp 0x0000000060c7bf4d 906 Shared-State Retry Offload Token: unique_token_number 907 0x59ef316b70575e793e1a8782 key_sequence 0x00 908 encrypted_shared_state_retry_offload_token_body 0x7d38b274aa4427c7a15 909 57c3fa666945931defc65da387a83855196a7cb73caac1e28e5346fd76868de94f8b6 910 2294 AEAD_ICV 0xf91174fdd711543a32d5e959867f9c22 912 AEAD related parameters: client_ip_addr 127.0.0.1 client_port 6666 913 AEAD_nonce 0x68dd025f45616941072ab6b0 AEAD_associated_data 914 0x7f00000100000000000000000000000059ef316b70575e793e1a878200 ~~~ 916 Appendix B. Acknowledgments 918 Christian Huitema, Ling Tao Nju, and William Zeng Ke all provided 919 useful input to this document. 921 Appendix C. Change Log 923 *RFC Editor's Note:* Please remove this section prior to 924 publication of a final version of this document. 926 C.1. since draft-ietf-quic-load-balancers-12 928 * Separated from the QUIC-LB draft 930 * Renamed "Retry Service" to "Retry Offload" 932 C.2. since draft-ietf-quic-load-balancers-11 934 * Fixed mistakes in test vectors 936 C.3. since draft-ietf-quic-load-balancers-10 938 * Refactored algorithm descriptions; made the 4-pass algorithm 939 easier to implement 941 * Revised test vectors 943 * Split YANG model into a server and middlebox version 945 C.4. since draft-ietf-quic-load-balancers-09 947 * Renamed "Stream Cipher" and "Block Cipher" to "Encrypted Short" 948 and "Encrypted Long" 950 * Added section on per-connection state 952 * Changed "Encrypted Short" to a 4-pass algorithm. 954 * Recommended a random initial nonce when incrementing. 956 * Clarified what SNI LBs should do with unknown QUIC versions. 958 C.5. since draft-ietf-quic-load-balancers-08 960 * Eliminate Dynamic SID allocation 962 * Eliminated server use bytes 964 C.6. since draft-ietf-quic-load-balancers-07 966 * Shortened SSCID nonce minimum length to 4 bytes 968 * Removed RSCID from Retry token body 970 * Simplified CID formats 972 * Shrunk size of SID table 974 C.7. since draft-ietf-quic-load-balancers-06 976 * Added interoperability with DTLS 978 * Changed "non-compliant" to "unroutable" 980 * Changed "arbitrary" algorithm to "fallback" 982 * Revised security considerations for mistrustful tenants 984 * Added Retry Offload considerations for non-Initial packets 986 C.8. since draft-ietf-quic-load-balancers-05 988 * Added low-config CID for further discussion 990 * Complete revision of shared-state Retry Token 992 * Added YANG model 994 * Updated configuration limits to ensure CID entropy 996 * Switched to notation from quic-transport 998 C.9. since draft-ietf-quic-load-balancers-04 1000 * Rearranged the shared-state retry token to simplify token 1001 processing 1003 * More compact timestamp in shared-state retry token 1005 * Revised server requirements for shared-state retries 1007 * Eliminated zero padding from the test vectors 1009 * Added server use bytes to the test vectors 1011 * Additional compliant DCID criteria 1013 C.10. since-draft-ietf-quic-load-balancers-03 1015 * Improved Config Rotation text 1017 * Added stream cipher test vectors 1019 * Deleted the Obfuscated CID algorithm 1021 C.11. since-draft-ietf-quic-load-balancers-02 1023 * Replaced stream cipher algorithm with three-pass version 1025 * Updated Retry format to encode info for required TPs 1027 * Added discussion of version invariance 1029 * Cleaned up text about config rotation 1031 * Added Reset Oracle and limited configuration considerations 1033 * Allow dropped long-header packets for known QUIC versions 1035 C.12. since-draft-ietf-quic-load-balancers-01 1037 * Test vectors for load balancer decoding 1039 * Deleted remnants of in-band protocol 1041 * Light edit of Retry Offloads section 1043 * Discussed load balancer chains 1045 C.13. since-draft-ietf-quic-load-balancers-00 1047 * Removed in-band protocol from the document 1049 C.14. Since draft-duke-quic-load-balancers-06 1051 * Switch to IETF WG draft. 1053 C.15. Since draft-duke-quic-load-balancers-05 1055 * Editorial changes 1057 * Made load balancer behavior independent of QUIC version 1059 * Got rid of token in stream cipher encoding, because server might 1060 not have it 1062 * Defined "non-compliant DCID" and specified rules for handling 1063 them. 1065 * Added psuedocode for config schema 1067 C.16. Since draft-duke-quic-load-balancers-04 1069 * Added standard for Retry Offloads 1071 C.17. Since draft-duke-quic-load-balancers-03 1073 * Renamed Plaintext CID algorithm as Obfuscated CID 1075 * Added new Plaintext CID algorithm 1077 * Updated to allow 20B CIDs 1079 * Added self-encoding of CID length 1081 C.18. Since draft-duke-quic-load-balancers-02 1083 * Added Config Rotation 1085 * Added failover mode 1087 * Tweaks to existing CID algorithms 1089 * Added Block Cipher CID algorithm 1091 * Reformatted QUIC-LB packets 1093 C.19. Since draft-duke-quic-load-balancers-01 1095 * Complete rewrite 1097 * Supports multiple security levels 1099 * Lightweight messages 1101 C.20. Since draft-duke-quic-load-balancers-00 1103 * Converted to markdown 1105 * Added variable length connection IDs 1107 Authors' Addresses 1109 Martin Duke 1110 Google 1111 Email: martin.h.duke@gmail.com 1113 Nick Banks 1114 Microsoft 1115 Email: nibanks@microsoft.com