idnits 2.17.00 (12 Aug 2021) /tmp/idnits19805/draft-ietf-quic-http-30.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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 10, 2020) is 617 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-httpbis-cache-11 -- Possible downref: Normative reference to a draft: ref. 'CACHING' == Outdated reference: A later version (-21) exists of draft-ietf-quic-qpack-17 == Outdated reference: draft-ietf-quic-transport has been published as RFC 9000 ** Downref: Normative reference to an Historic RFC: RFC 8164 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-11 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-11 -- Duplicate reference: RFC3986, mentioned in 'URI', was also mentioned in 'RFC3986'. Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 QUIC M. Bishop, Ed. 3 Internet-Draft Akamai 4 Intended status: Standards Track September 10, 2020 5 Expires: March 14, 2021 7 Hypertext Transfer Protocol Version 3 (HTTP/3) 8 draft-ietf-quic-http-30 10 Abstract 12 The QUIC transport protocol has several features that are desirable 13 in a transport for HTTP, such as stream multiplexing, per-stream flow 14 control, and low-latency connection establishment. This document 15 describes a mapping of HTTP semantics over QUIC. This document also 16 identifies HTTP/2 features that are subsumed by QUIC, and describes 17 how HTTP/2 extensions can be ported to HTTP/3. 19 Note to Readers 21 Discussion of this draft takes place on the QUIC working group 22 mailing list (quic@ietf.org), which is archived at 23 https://mailarchive.ietf.org/arch/search/?email_list=quic. 25 Working Group information can be found at https://github.com/quicwg; 26 source code and issues list for this draft can be found at 27 https://github.com/quicwg/base-drafts/labels/-http. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on March 14, 2021. 46 Copyright Notice 48 Copyright (c) 2020 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 63 1.1. Prior versions of HTTP . . . . . . . . . . . . . . . . . 5 64 1.2. Delegation to QUIC . . . . . . . . . . . . . . . . . . . 5 65 2. HTTP/3 Protocol Overview . . . . . . . . . . . . . . . . . . 5 66 2.1. Document Organization . . . . . . . . . . . . . . . . . . 6 67 2.2. Conventions and Terminology . . . . . . . . . . . . . . . 7 68 3. Connection Setup and Management . . . . . . . . . . . . . . . 8 69 3.1. Draft Version Identification . . . . . . . . . . . . . . 8 70 3.2. Discovering an HTTP/3 Endpoint . . . . . . . . . . . . . 9 71 3.2.1. HTTP Alternative Services . . . . . . . . . . . . . . 9 72 3.2.2. Other Schemes . . . . . . . . . . . . . . . . . . . . 10 73 3.3. Connection Establishment . . . . . . . . . . . . . . . . 10 74 3.4. Connection Reuse . . . . . . . . . . . . . . . . . . . . 11 75 4. HTTP Request Lifecycle . . . . . . . . . . . . . . . . . . . 12 76 4.1. HTTP Message Exchanges . . . . . . . . . . . . . . . . . 12 77 4.1.1. Field Formatting and Compression . . . . . . . . . . 14 78 4.1.2. Request Cancellation and Rejection . . . . . . . . . 17 79 4.1.3. Malformed Requests and Responses . . . . . . . . . . 18 80 4.2. The CONNECT Method . . . . . . . . . . . . . . . . . . . 19 81 4.3. HTTP Upgrade . . . . . . . . . . . . . . . . . . . . . . 20 82 4.4. Server Push . . . . . . . . . . . . . . . . . . . . . . . 20 83 5. Connection Closure . . . . . . . . . . . . . . . . . . . . . 22 84 5.1. Idle Connections . . . . . . . . . . . . . . . . . . . . 22 85 5.2. Connection Shutdown . . . . . . . . . . . . . . . . . . . 23 86 5.3. Immediate Application Closure . . . . . . . . . . . . . . 25 87 5.4. Transport Closure . . . . . . . . . . . . . . . . . . . . 25 88 6. Stream Mapping and Usage . . . . . . . . . . . . . . . . . . 25 89 6.1. Bidirectional Streams . . . . . . . . . . . . . . . . . . 26 90 6.2. Unidirectional Streams . . . . . . . . . . . . . . . . . 26 91 6.2.1. Control Streams . . . . . . . . . . . . . . . . . . . 28 92 6.2.2. Push Streams . . . . . . . . . . . . . . . . . . . . 28 93 6.2.3. Reserved Stream Types . . . . . . . . . . . . . . . . 29 95 7. HTTP Framing Layer . . . . . . . . . . . . . . . . . . . . . 29 96 7.1. Frame Layout . . . . . . . . . . . . . . . . . . . . . . 30 97 7.2. Frame Definitions . . . . . . . . . . . . . . . . . . . . 31 98 7.2.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . 31 99 7.2.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . 31 100 7.2.3. CANCEL_PUSH . . . . . . . . . . . . . . . . . . . . . 32 101 7.2.4. SETTINGS . . . . . . . . . . . . . . . . . . . . . . 33 102 7.2.5. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . 36 103 7.2.6. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . 38 104 7.2.7. MAX_PUSH_ID . . . . . . . . . . . . . . . . . . . . . 38 105 7.2.8. Reserved Frame Types . . . . . . . . . . . . . . . . 39 106 8. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 39 107 8.1. HTTP/3 Error Codes . . . . . . . . . . . . . . . . . . . 40 108 9. Extensions to HTTP/3 . . . . . . . . . . . . . . . . . . . . 41 109 10. Security Considerations . . . . . . . . . . . . . . . . . . . 42 110 10.1. Server Authority . . . . . . . . . . . . . . . . . . . . 42 111 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 42 112 10.3. Intermediary Encapsulation Attacks . . . . . . . . . . . 43 113 10.4. Cacheability of Pushed Responses . . . . . . . . . . . . 43 114 10.5. Denial-of-Service Considerations . . . . . . . . . . . . 43 115 10.5.1. Limits on Field Section Size . . . . . . . . . . . . 44 116 10.5.2. CONNECT Issues . . . . . . . . . . . . . . . . . . . 45 117 10.6. Use of Compression . . . . . . . . . . . . . . . . . . . 45 118 10.7. Padding and Traffic Analysis . . . . . . . . . . . . . . 46 119 10.8. Frame Parsing . . . . . . . . . . . . . . . . . . . . . 46 120 10.9. Early Data . . . . . . . . . . . . . . . . . . . . . . . 46 121 10.10. Migration . . . . . . . . . . . . . . . . . . . . . . . 47 122 10.11. Privacy Considerations . . . . . . . . . . . . . . . . . 47 123 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 124 11.1. Registration of HTTP/3 Identification String . . . . . . 47 125 11.2. New Registries . . . . . . . . . . . . . . . . . . . . . 48 126 11.2.1. Frame Types . . . . . . . . . . . . . . . . . . . . 48 127 11.2.2. Settings Parameters . . . . . . . . . . . . . . . . 49 128 11.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . 50 129 11.2.4. Stream Types . . . . . . . . . . . . . . . . . . . . 53 130 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 131 12.1. Normative References . . . . . . . . . . . . . . . . . . 53 132 12.2. Informative References . . . . . . . . . . . . . . . . . 55 133 Appendix A. Considerations for Transitioning from HTTP/2 . . . . 56 134 A.1. Streams . . . . . . . . . . . . . . . . . . . . . . . . . 56 135 A.2. HTTP Frame Types . . . . . . . . . . . . . . . . . . . . 57 136 A.2.1. Prioritization Differences . . . . . . . . . . . . . 58 137 A.2.2. Field Compression Differences . . . . . . . . . . . . 58 138 A.2.3. Flow Control Differences . . . . . . . . . . . . . . 58 139 A.2.4. Guidance for New Frame Type Definitions . . . . . . . 58 140 A.2.5. Mapping Between HTTP/2 and HTTP/3 Frame Types . . . . 59 141 A.3. HTTP/2 SETTINGS Parameters . . . . . . . . . . . . . . . 60 142 A.4. HTTP/2 Error Codes . . . . . . . . . . . . . . . . . . . 61 143 A.4.1. Mapping Between HTTP/2 and HTTP/3 Errors . . . . . . 62 144 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 63 145 B.1. Since draft-ietf-quic-http-29 . . . . . . . . . . . . . . 63 146 B.2. Since draft-ietf-quic-http-28 . . . . . . . . . . . . . . 63 147 B.3. Since draft-ietf-quic-http-27 . . . . . . . . . . . . . . 63 148 B.4. Since draft-ietf-quic-http-26 . . . . . . . . . . . . . . 63 149 B.5. Since draft-ietf-quic-http-25 . . . . . . . . . . . . . . 64 150 B.6. Since draft-ietf-quic-http-24 . . . . . . . . . . . . . . 64 151 B.7. Since draft-ietf-quic-http-23 . . . . . . . . . . . . . . 64 152 B.8. Since draft-ietf-quic-http-22 . . . . . . . . . . . . . . 64 153 B.9. Since draft-ietf-quic-http-21 . . . . . . . . . . . . . . 65 154 B.10. Since draft-ietf-quic-http-20 . . . . . . . . . . . . . . 65 155 B.11. Since draft-ietf-quic-http-19 . . . . . . . . . . . . . . 66 156 B.12. Since draft-ietf-quic-http-18 . . . . . . . . . . . . . . 66 157 B.13. Since draft-ietf-quic-http-17 . . . . . . . . . . . . . . 67 158 B.14. Since draft-ietf-quic-http-16 . . . . . . . . . . . . . . 67 159 B.15. Since draft-ietf-quic-http-15 . . . . . . . . . . . . . . 67 160 B.16. Since draft-ietf-quic-http-14 . . . . . . . . . . . . . . 67 161 B.17. Since draft-ietf-quic-http-13 . . . . . . . . . . . . . . 68 162 B.18. Since draft-ietf-quic-http-12 . . . . . . . . . . . . . . 68 163 B.19. Since draft-ietf-quic-http-11 . . . . . . . . . . . . . . 68 164 B.20. Since draft-ietf-quic-http-10 . . . . . . . . . . . . . . 68 165 B.21. Since draft-ietf-quic-http-09 . . . . . . . . . . . . . . 68 166 B.22. Since draft-ietf-quic-http-08 . . . . . . . . . . . . . . 69 167 B.23. Since draft-ietf-quic-http-07 . . . . . . . . . . . . . . 69 168 B.24. Since draft-ietf-quic-http-06 . . . . . . . . . . . . . . 69 169 B.25. Since draft-ietf-quic-http-05 . . . . . . . . . . . . . . 69 170 B.26. Since draft-ietf-quic-http-04 . . . . . . . . . . . . . . 69 171 B.27. Since draft-ietf-quic-http-03 . . . . . . . . . . . . . . 70 172 B.28. Since draft-ietf-quic-http-02 . . . . . . . . . . . . . . 70 173 B.29. Since draft-ietf-quic-http-01 . . . . . . . . . . . . . . 70 174 B.30. Since draft-ietf-quic-http-00 . . . . . . . . . . . . . . 70 175 B.31. Since draft-shade-quic-http2-mapping-00 . . . . . . . . . 71 176 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 71 177 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 72 179 1. Introduction 181 HTTP semantics ([SEMANTICS]) are used for a broad range of services 182 on the Internet. These semantics have most commonly been used with 183 HTTP/1.1, over a variety of transport and session layers, and with 184 HTTP/2 over TLS. HTTP/3 supports the same semantics over a new 185 transport protocol, QUIC. 187 1.1. Prior versions of HTTP 189 HTTP/1.1 ([HTTP11]) uses whitespace-delimited text fields to convey 190 HTTP messages. While these exchanges are human-readable, using 191 whitespace for message formatting leads to parsing complexity and 192 excessive tolerance of variant behavior. Because HTTP/1.x does not 193 include a multiplexing layer, multiple TCP connections are often used 194 to service requests in parallel. However, that has a negative impact 195 on congestion control and network efficiency, since TCP does not 196 share congestion control across multiple connections. 198 HTTP/2 ([HTTP2]) introduced a binary framing and multiplexing layer 199 to improve latency without modifying the transport layer. However, 200 because the parallel nature of HTTP/2's multiplexing is not visible 201 to TCP's loss recovery mechanisms, a lost or reordered packet causes 202 all active transactions to experience a stall regardless of whether 203 that transaction was directly impacted by the lost packet. 205 1.2. Delegation to QUIC 207 The QUIC transport protocol incorporates stream multiplexing and per- 208 stream flow control, similar to that provided by the HTTP/2 framing 209 layer. By providing reliability at the stream level and congestion 210 control across the entire connection, it has the capability to 211 improve the performance of HTTP compared to a TCP mapping. QUIC also 212 incorporates TLS 1.3 ([TLS13]) at the transport layer, offering 213 comparable security to running TLS over TCP, with the improved 214 connection setup latency of TCP Fast Open ([TFO]). 216 This document defines a mapping of HTTP semantics over the QUIC 217 transport protocol, drawing heavily on the design of HTTP/2. While 218 delegating stream lifetime and flow control issues to QUIC, a similar 219 binary framing is used on each stream. Some HTTP/2 features are 220 subsumed by QUIC, while other features are implemented atop QUIC. 222 QUIC is described in [QUIC-TRANSPORT]. For a full description of 223 HTTP/2, see [HTTP2]. 225 2. HTTP/3 Protocol Overview 227 HTTP/3 provides a transport for HTTP semantics using the QUIC 228 transport protocol and an internal framing layer similar to HTTP/2. 230 Once a client knows that an HTTP/3 server exists at a certain 231 endpoint, it opens a QUIC connection. QUIC provides protocol 232 negotiation, stream-based multiplexing, and flow control. Discovery 233 of an HTTP/3 endpoint is described in Section 3.2. 235 Within each stream, the basic unit of HTTP/3 communication is a frame 236 (Section 7.2). Each frame type serves a different purpose. For 237 example, HEADERS and DATA frames form the basis of HTTP requests and 238 responses (Section 4.1). 240 Multiplexing of requests is performed using the QUIC stream 241 abstraction, described in Section 2 of [QUIC-TRANSPORT]. Each 242 request-response pair consumes a single QUIC stream. Streams are 243 independent of each other, so one stream that is blocked or suffers 244 packet loss does not prevent progress on other streams. 246 Server push is an interaction mode introduced in HTTP/2 ([HTTP2]) 247 that permits a server to push a request-response exchange to a client 248 in anticipation of the client making the indicated request. This 249 trades off network usage against a potential latency gain. Several 250 HTTP/3 frames are used to manage server push, such as PUSH_PROMISE, 251 MAX_PUSH_ID, and CANCEL_PUSH. 253 As in HTTP/2, request and response fields are compressed for 254 transmission. Because HPACK ([HPACK]) relies on in-order 255 transmission of compressed field sections (a guarantee not provided 256 by QUIC), HTTP/3 replaces HPACK with QPACK ([QPACK]). QPACK uses 257 separate unidirectional streams to modify and track field table 258 state, while encoded field sections refer to the state of the table 259 without modifying it. 261 2.1. Document Organization 263 The following sections provide a detailed overview of the connection 264 lifecycle and key concepts: 266 * Connection Setup and Management (Section 3) covers how an HTTP/3 267 endpoint is discovered and a connection is established. 269 * HTTP Request Lifecycle (Section 4) describes how HTTP semantics 270 are expressed using frames. 272 * Connection Closure (Section 5) describes how connections are 273 terminated, either gracefully or abruptly. 275 The details of the wire protocol and interactions with the transport 276 are described in subsequent sections: 278 * Stream Mapping and Usage (Section 6) describes the way QUIC 279 streams are used. 281 * HTTP Framing Layer (Section 7) describes the frames used on most 282 streams. 284 * Error Handling (Section 8) describes how error conditions are 285 handled and expressed, either on a particular stream or for the 286 connection as a whole. 288 Additional resources are provided in the final sections: 290 * Extensions to HTTP/3 (Section 9) describes how new capabilities 291 can be added in future documents. 293 * A more detailed comparison between HTTP/2 and HTTP/3 can be found 294 in Appendix A. 296 2.2. Conventions and Terminology 298 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 299 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 300 "OPTIONAL" in this document are to be interpreted as described in 301 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 302 capitals, as shown here. 304 This document uses the variable-length integer encoding from 305 [QUIC-TRANSPORT]. 307 The following terms are used: 309 abort: An abrupt termination of a connection or stream, possibly due 310 to an error condition. 312 client: The endpoint that initiates an HTTP/3 connection. Clients 313 send HTTP requests and receive HTTP responses. 315 connection: A transport-layer connection between two endpoints, 316 using QUIC as the transport protocol. 318 connection error: An error that affects the entire HTTP/3 319 connection. 321 endpoint: Either the client or server of the connection. 323 frame: The smallest unit of communication on a stream in HTTP/3, 324 consisting of a header and a variable-length sequence of bytes 325 structured according to the frame type. Protocol elements called 326 "frames" exist in both this document and [QUIC-TRANSPORT]. Where 327 frames from [QUIC-TRANSPORT] are referenced, the frame name will 328 be prefaced with "QUIC." For example, "QUIC CONNECTION_CLOSE 329 frames." References without this preface refer to frames defined 330 in Section 7.2. 332 peer: An endpoint. When discussing a particular endpoint, "peer" 333 refers to the endpoint that is remote to the primary subject of 334 discussion. 336 receiver: An endpoint that is receiving frames. 338 sender: An endpoint that is transmitting frames. 340 server: The endpoint that accepts an HTTP/3 connection. Servers 341 receive HTTP requests and send HTTP responses. 343 stream: A bidirectional or unidirectional bytestream provided by the 344 QUIC transport. 346 stream error: An error on the individual HTTP/3 stream. 348 The term "payload body" is defined in Section 7.3.3 of [SEMANTICS]. 350 Finally, the terms "gateway", "intermediary", "proxy", and "tunnel" 351 are defined in Section 2.2 of [SEMANTICS]. Intermediaries act as 352 both client and server at different times. 354 Packet diagrams in this document use the format defined in 355 Section 1.3 of [QUIC-TRANSPORT] to illustrate the order and size of 356 fields. 358 3. Connection Setup and Management 360 3.1. Draft Version Identification 362 *RFC Editor's Note:* Please remove this section prior to 363 publication of a final version of this document. 365 HTTP/3 uses the token "h3" to identify itself in ALPN and Alt-Svc. 366 Only implementations of the final, published RFC can identify 367 themselves as "h3". Until such an RFC exists, implementations MUST 368 NOT identify themselves using this string. 370 Implementations of draft versions of the protocol MUST add the string 371 "-" and the corresponding draft number to the identifier. For 372 example, draft-ietf-quic-http-01 is identified using the string 373 "h3-01". 375 Draft versions MUST use the corresponding draft transport version as 376 their transport. For example, the application protocol defined in 377 draft-ietf-quic-http-25 uses the transport defined in draft-ietf- 378 quic-transport-25. 380 Non-compatible experiments that are based on these draft versions 381 MUST append the string "-" and an experiment name to the identifier. 382 For example, an experimental implementation based on draft-ietf-quic- 383 http-09 that reserves an extra stream for unsolicited transmission of 384 1980s pop music might identify itself as "h3-09-rickroll". Note that 385 any label MUST conform to the "token" syntax defined in 386 Section 5.4.1.1 of [SEMANTICS]. Experimenters are encouraged to 387 coordinate their experiments on the quic@ietf.org mailing list. 389 3.2. Discovering an HTTP/3 Endpoint 391 HTTP relies on the notion of an authoritative response: a response 392 that has been determined to be the most appropriate response for that 393 request given the state of the target resource at the time of 394 response message origination by (or at the direction of) the origin 395 server identified within the target URI. Locating an authoritative 396 server for an HTTP URL is discussed in Section 6.4 of [SEMANTICS]. 398 The "https" scheme associates authority with possession of a 399 certificate that the client considers to be trustworthy for the host 400 identified by the authority component of the URL. If a server 401 presents a certificate and proof that it controls the corresponding 402 private key, then a client will accept a secured connection to that 403 server as being authoritative for all origins with the "https" scheme 404 and a host identified in the certificate. 406 A client MAY attempt access to a resource with an "https" URI by 407 resolving the host identifier to an IP address, establishing a QUIC 408 connection to that address on the indicated port, and sending an 409 HTTP/3 request message targeting the URI to the server over that 410 secured connection. 412 Connectivity problems (e.g., blocking UDP) can result in QUIC 413 connection establishment failure; clients SHOULD attempt to use TCP- 414 based versions of HTTP in this case. 416 Servers MAY serve HTTP/3 on any UDP port; an alternative service 417 advertisement always includes an explicit port, and URLs contain 418 either an explicit port or a default port associated with the scheme. 420 3.2.1. HTTP Alternative Services 422 An HTTP origin advertises the availability of an equivalent HTTP/3 423 endpoint via the Alt-Svc HTTP response header field or the HTTP/2 424 ALTSVC frame ([ALTSVC]), using the Application Layer Protocol 425 Negotiation (ALPN; see [RFC7301]) token defined in Section 3.3. 427 For example, an origin could indicate in an HTTP response that HTTP/3 428 was available on UDP port 50781 at the same hostname by including the 429 following header field: 431 Alt-Svc: h3=":50781" 433 On receipt of an Alt-Svc record indicating HTTP/3 support, a client 434 MAY attempt to establish a QUIC connection to the indicated host and 435 port; if this connection is successful, the client can send HTTP 436 requests using the mapping described in this document. 438 3.2.2. Other Schemes 440 Although HTTP is independent of the transport protocol, the "http" 441 scheme associates authority with the ability to receive TCP 442 connections on the indicated port of whatever host is identified 443 within the authority component. Because HTTP/3 does not use TCP, 444 HTTP/3 cannot be used for direct access to the authoritative server 445 for a resource identified by an "http" URI. However, protocol 446 extensions such as [ALTSVC] permit the authoritative server to 447 identify other services that are also authoritative and that might be 448 reachable over HTTP/3. 450 Prior to making requests for an origin whose scheme is not "https", 451 the client MUST ensure the server is willing to serve that scheme. 452 If the client intends to make requests for an origin whose scheme is 453 "http", this means that it MUST obtain a valid "http-opportunistic" 454 response for the origin as described in [RFC8164] prior to making any 455 such requests. Other schemes might define other mechanisms. 457 3.3. Connection Establishment 459 HTTP/3 relies on QUIC version 1 as the underlying transport. The use 460 of other QUIC transport versions with HTTP/3 MAY be defined by future 461 specifications. 463 QUIC version 1 uses TLS version 1.3 or greater as its handshake 464 protocol. HTTP/3 clients MUST support a mechanism to indicate the 465 target host to the server during the TLS handshake. If the server is 466 identified by a DNS name, clients MUST send the Server Name 467 Indication (SNI; [RFC6066]) TLS extension unless an alternative 468 mechanism to indicate the target host is used. 470 QUIC connections are established as described in [QUIC-TRANSPORT]. 471 During connection establishment, HTTP/3 support is indicated by 472 selecting the ALPN token "h3" in the TLS handshake. Support for 473 other application-layer protocols MAY be offered in the same 474 handshake. 476 While connection-level options pertaining to the core QUIC protocol 477 are set in the initial crypto handshake, HTTP/3-specific settings are 478 conveyed in the SETTINGS frame. After the QUIC connection is 479 established, a SETTINGS frame (Section 7.2.4) MUST be sent by each 480 endpoint as the initial frame of their respective HTTP control 481 stream; see Section 6.2.1. 483 3.4. Connection Reuse 485 HTTP/3 connections are persistent across multiple requests. For best 486 performance, it is expected that clients will not close connections 487 until it is determined that no further communication with a server is 488 necessary (for example, when a user navigates away from a particular 489 web page) or until the server closes the connection. 491 Once a connection exists to a server endpoint, this connection MAY be 492 reused for requests with multiple different URI authority components. 493 In general, a server is considered authoritative for all URIs with 494 the "https" scheme for which the hostname in the URI is present in 495 the authenticated certificate provided by the server, either as the 496 CN field of the certificate subject or as a dNSName in the 497 subjectAltName field of the certificate; see [RFC6125]. For a host 498 that is an IP address, the client MUST verify that the address 499 appears as an iPAddress in the subjectAltName field of the 500 certificate. If the hostname or address is not present in the 501 certificate, the client MUST NOT consider the server authoritative 502 for origins containing that hostname or address. See Section 6.4 of 503 [SEMANTICS] for more detail on authoritative access. 505 Clients SHOULD NOT open more than one HTTP/3 connection to a given 506 host and port pair, where the host is derived from a URI, a selected 507 alternative service ([ALTSVC]), or a configured proxy. A client MAY 508 open multiple connections to the same IP address and UDP port using 509 different transport or TLS configurations but SHOULD avoid creating 510 multiple connections with the same configuration. 512 Servers are encouraged to maintain open connections for as long as 513 possible but are permitted to terminate idle connections if 514 necessary. When either endpoint chooses to close the HTTP/3 515 connection, the terminating endpoint SHOULD first send a GOAWAY frame 516 (Section 5.2) so that both endpoints can reliably determine whether 517 previously sent frames have been processed and gracefully complete or 518 terminate any necessary remaining tasks. 520 A server that does not wish clients to reuse connections for a 521 particular origin can indicate that it is not authoritative for a 522 request by sending a 421 (Misdirected Request) status code in 523 response to the request; see Section 9.1.2 of [HTTP2]. 525 4. HTTP Request Lifecycle 527 4.1. HTTP Message Exchanges 529 A client sends an HTTP request on a client-initiated bidirectional 530 QUIC stream. A client MUST send only a single request on a given 531 stream. A server sends zero or more interim HTTP responses on the 532 same stream as the request, followed by a single final HTTP response, 533 as detailed below. See Section 10 of [SEMANTICS] for a description 534 of interim and final HTTP responses. 536 Pushed responses are sent on a server-initiated unidirectional QUIC 537 stream; see Section 6.2.2. A server sends zero or more interim HTTP 538 responses, followed by a single final HTTP response, in the same 539 manner as a standard response. Push is described in more detail in 540 Section 4.4. 542 On a given stream, receipt of multiple requests or receipt of an 543 additional HTTP response following a final HTTP response MUST be 544 treated as malformed (Section 4.1.3). 546 An HTTP message (request or response) consists of: 548 1. the header field section, sent as a single HEADERS frame (see 549 Section 7.2.2), 551 2. optionally, the payload body, if present, sent as a series of 552 DATA frames (see Section 7.2.1), and 554 3. optionally, the trailer field section, if present, sent as a 555 single HEADERS frame. 557 Header and trailer field sections are described in Section 5 of 558 [SEMANTICS]; the payload body is described in Section 7.3.3 of 559 [SEMANTICS]. 561 Receipt of an invalid sequence of frames MUST be treated as a 562 connection error of type H3_FRAME_UNEXPECTED (Section 8). In 563 particular, a DATA frame before any HEADERS frame, or a HEADERS or 564 DATA frame after the trailing HEADERS frame is considered invalid. 566 A server MAY send one or more PUSH_PROMISE frames (Section 7.2.5) 567 before, after, or interleaved with the frames of a response message. 568 These PUSH_PROMISE frames are not part of the response; see 569 Section 4.4 for more details. These frames are not permitted in 570 pushed responses; a pushed response that includes PUSH_PROMISE frames 571 MUST be treated as a connection error of type H3_FRAME_UNEXPECTED. 573 Frames of unknown types (Section 9), including reserved frames 574 (Section 7.2.8) MAY be sent on a request or push stream before, 575 after, or interleaved with other frames described in this section. 577 The HEADERS and PUSH_PROMISE frames might reference updates to the 578 QPACK dynamic table. While these updates are not directly part of 579 the message exchange, they must be received and processed before the 580 message can be consumed. See Section 4.1.1 for more details. 582 The "chunked" transfer encoding defined in Section 7.1 of [HTTP11] 583 MUST NOT be used. 585 A response MAY consist of multiple messages when and only when one or 586 more interim responses (1xx; see Section 10.2 of [SEMANTICS]) precede 587 a final response to the same request. Interim responses do not 588 contain a payload body or trailers. 590 An HTTP request/response exchange fully consumes a client-initiated 591 bidirectional QUIC stream. After sending a request, a client MUST 592 close the stream for sending. Unless using the CONNECT method (see 593 Section 4.2), clients MUST NOT make stream closure dependent on 594 receiving a response to their request. After sending a final 595 response, the server MUST close the stream for sending. At this 596 point, the QUIC stream is fully closed. 598 When a stream is closed, this indicates the end of the final HTTP 599 message. Because some messages are large or unbounded, endpoints 600 SHOULD begin processing partial HTTP messages once enough of the 601 message has been received to make progress. If a client-initiated 602 stream terminates without enough of the HTTP message to provide a 603 complete response, the server SHOULD abort its response with the 604 error code H3_REQUEST_INCOMPLETE. 606 A server can send a complete response prior to the client sending an 607 entire request if the response does not depend on any portion of the 608 request that has not been sent and received. When the server does 609 not need to receive the remainder of the request, it MAY abort 610 reading the request stream, send a complete response, and cleanly 611 close the sending part of the stream. The error code H3_NO_ERROR 612 SHOULD be used when requesting that the client stop sending on the 613 request stream. Clients MUST NOT discard complete responses as a 614 result of having their request terminated abruptly, though clients 615 can always discard responses at their discretion for other reasons. 616 If the server sends a partial or complete response but does not abort 617 reading the request, clients SHOULD continue sending the body of the 618 request and close the stream normally. 620 4.1.1. Field Formatting and Compression 622 HTTP messages carry metadata as a series of key-value pairs, called 623 HTTP fields. For a listing of registered HTTP fields, see the 624 "Hypertext Transfer Protocol (HTTP) Field Name Registry" maintained 625 at https://www.iana.org/assignments/http-fields/. 627 As in previous versions of HTTP, field names are strings containing a 628 subset of ASCII characters that are compared in a case-insensitive 629 fashion. Properties of HTTP field names and values are discussed in 630 more detail in Section 5.3 of [SEMANTICS]. As in HTTP/2, characters 631 in field names MUST be converted to lowercase prior to their 632 encoding. A request or response containing uppercase characters in 633 field names MUST be treated as malformed (Section 4.1.3). 635 Like HTTP/2, HTTP/3 does not use the Connection header field to 636 indicate connection-specific fields; in this protocol, connection- 637 specific metadata is conveyed by other means. An endpoint MUST NOT 638 generate an HTTP/3 field section containing connection-specific 639 fields; any message containing connection-specific fields MUST be 640 treated as malformed (Section 4.1.3). 642 The only exception to this is the TE header field, which MAY be 643 present in an HTTP/3 request header; when it is, it MUST NOT contain 644 any value other than "trailers". 646 This means that an intermediary transforming an HTTP/1.x message to 647 HTTP/3 will need to remove any fields nominated by the Connection 648 field, along with the Connection field itself. Such intermediaries 649 SHOULD also remove other connection-specific fields, such as Keep- 650 Alive, Proxy-Connection, Transfer-Encoding, and Upgrade, even if they 651 are not nominated by the Connection field. 653 4.1.1.1. Pseudo-Header Fields 655 Like HTTP/2, HTTP/3 employs a series of pseudo-header fields where 656 the field name begins with the ':' character (ASCII 0x3a). These 657 pseudo-header fields convey the target URI, the method of the 658 request, and the status code for the response. 660 Pseudo-header fields are not HTTP fields. Endpoints MUST NOT 661 generate pseudo-header fields other than those defined in this 662 document, except as negotiated via an extension; see Section 9. 664 Pseudo-header fields are only valid in the context in which they are 665 defined. Pseudo-header fields defined for requests MUST NOT appear 666 in responses; pseudo-header fields defined for responses MUST NOT 667 appear in requests. Pseudo-header fields MUST NOT appear in 668 trailers. Endpoints MUST treat a request or response that contains 669 undefined or invalid pseudo-header fields as malformed 670 (Section 4.1.3). 672 All pseudo-header fields MUST appear in the header field section 673 before regular header fields. Any request or response that contains 674 a pseudo-header field that appears in a header field section after a 675 regular header field MUST be treated as malformed (Section 4.1.3). 677 The following pseudo-header fields are defined for requests: 679 ":method": Contains the HTTP method (Section 8 of [SEMANTICS]) 681 ":scheme": Contains the scheme portion of the target URI 682 (Section 3.1 of [RFC3986]) 684 ":scheme" is not restricted to "http" and "https" schemed URIs. A 685 proxy or gateway can translate requests for non-HTTP schemes, 686 enabling the use of HTTP to interact with non-HTTP services. 688 ":authority": Contains the authority portion of the target URI 689 (Section 3.2 of [RFC3986]). The authority MUST NOT include the 690 deprecated "userinfo" subcomponent for "http" or "https" schemed 691 URIs. 693 To ensure that the HTTP/1.1 request line can be reproduced 694 accurately, this pseudo-header field MUST be omitted when 695 translating from an HTTP/1.1 request that has a request target in 696 origin or asterisk form; see Section 3.2 of [HTTP11]. Clients 697 that generate HTTP/3 requests directly SHOULD use the ":authority" 698 pseudo-header field instead of the Host field. An intermediary 699 that converts an HTTP/3 request to HTTP/1.1 MUST create a Host 700 field if one is not present in a request by copying the value of 701 the ":authority" pseudo-header field. 703 ":path": Contains the path and query parts of the target URI (the 704 "path-absolute" production and optionally a '?' character followed 705 by the "query" production; see Sections 3.3 and 3.4 of [URI]. A 706 request in asterisk form includes the value '*' for the ":path" 707 pseudo-header field. 709 This pseudo-header field MUST NOT be empty for "http" or "https" 710 URIs; "http" or "https" URIs that do not contain a path component 711 MUST include a value of '/'. The exception to this rule is an 712 OPTIONS request for an "http" or "https" URI that does not include 713 a path component; these MUST include a ":path" pseudo-header field 714 with a value of '*'; see Section 3.2.4 of [HTTP11]. 716 All HTTP/3 requests MUST include exactly one value for the ":method", 717 ":scheme", and ":path" pseudo-header fields, unless it is a CONNECT 718 request; see Section 4.2. 720 If the ":scheme" pseudo-header field identifies a scheme that has a 721 mandatory authority component (including "http" and "https"), the 722 request MUST contain either an ":authority" pseudo-header field or a 723 "Host" header field. If these fields are present, they MUST NOT be 724 empty. If both fields are present, they MUST contain the same value. 725 If the scheme does not have a mandatory authority component and none 726 is provided in the request target, the request MUST NOT contain the 727 ":authority" pseudo-header or "Host" header fields. 729 An HTTP request that omits mandatory pseudo-header fields or contains 730 invalid values for those pseudo-header fields is malformed 731 (Section 4.1.3). 733 HTTP/3 does not define a way to carry the version identifier that is 734 included in the HTTP/1.1 request line. 736 For responses, a single ":status" pseudo-header field is defined that 737 carries the HTTP status code; see Section 10 of [SEMANTICS]. This 738 pseudo-header field MUST be included in all responses; otherwise, the 739 response is malformed (Section 4.1.3). 741 HTTP/3 does not define a way to carry the version or reason phrase 742 that is included in an HTTP/1.1 status line. 744 4.1.1.2. Field Compression 746 HTTP/3 uses QPACK field compression as described in [QPACK], a 747 variation of HPACK that allows the flexibility to avoid compression- 748 induced head-of-line blocking. See that document for additional 749 details. 751 To allow for better compression efficiency, the "Cookie" field 752 ([RFC6265]) MAY be split into separate field lines, each with one or 753 more cookie-pairs, before compression. If a decompressed field 754 section contains multiple cookie field lines, these MUST be 755 concatenated into a single octet string using the two-octet delimiter 756 of 0x3b, 0x20 (the ASCII string "; ") before being passed into a 757 context other than HTTP/2 or HTTP/3, such as an HTTP/1.1 connection, 758 or a generic HTTP server application. 760 4.1.1.3. Header Size Constraints 762 An HTTP/3 implementation MAY impose a limit on the maximum size of 763 the message header it will accept on an individual HTTP message. A 764 server that receives a larger header section than it is willing to 765 handle can send an HTTP 431 (Request Header Fields Too Large) status 766 code ([RFC6585]). A client can discard responses that it cannot 767 process. The size of a field list is calculated based on the 768 uncompressed size of fields, including the length of the name and 769 value in bytes plus an overhead of 32 bytes for each field. 771 If an implementation wishes to advise its peer of this limit, it can 772 be conveyed as a number of bytes in the 773 SETTINGS_MAX_FIELD_SECTION_SIZE parameter. An implementation that 774 has received this parameter SHOULD NOT send an HTTP message header 775 that exceeds the indicated size, as the peer will likely refuse to 776 process it. However, because this limit is applied at each hop, 777 messages below this limit are not guaranteed to be accepted. 779 4.1.2. Request Cancellation and Rejection 781 Once a request stream has been opened, the request MAY be cancelled 782 by either endpoint. Clients cancel requests if the response is no 783 longer of interest; servers cancel requests if they are unable to or 784 choose not to respond. When possible, it is RECOMMENDED that servers 785 send an HTTP response with an appropriate status code rather than 786 canceling a request it has already begun processing. 788 Implementations SHOULD cancel requests by abruptly terminating any 789 directions of a stream that are still open. This means resetting the 790 sending parts of streams and aborting reading on receiving parts of 791 streams; see Section 2.4 of [QUIC-TRANSPORT]. 793 When the server cancels a request without performing any application 794 processing, the request is considered "rejected." The server SHOULD 795 abort its response stream with the error code H3_REQUEST_REJECTED. 796 In this context, "processed" means that some data from the stream was 797 passed to some higher layer of software that might have taken some 798 action as a result. The client can treat requests rejected by the 799 server as though they had never been sent at all, thereby allowing 800 them to be retried later. 802 Servers MUST NOT use the H3_REQUEST_REJECTED error code for requests 803 that were partially or fully processed. When a server abandons a 804 response after partial processing, it SHOULD abort its response 805 stream with the error code H3_REQUEST_CANCELLED. 807 Client SHOULD use the error code H3_REQUEST_CANCELLED to cancel 808 requests. Upon receipt of this error code, a server MAY abruptly 809 terminate the response using the error code H3_REQUEST_REJECTED if no 810 processing was performed. Clients MUST NOT use the 811 H3_REQUEST_REJECTED error code, except when a server has requested 812 closure of the request stream with this error code. 814 If a stream is canceled after receiving a complete response, the 815 client MAY ignore the cancellation and use the response. However, if 816 a stream is cancelled after receiving a partial response, the 817 response SHOULD NOT be used. Automatically retrying such requests is 818 not possible, unless this is otherwise permitted (e.g., idempotent 819 actions like GET, PUT, or DELETE). 821 4.1.3. Malformed Requests and Responses 823 A malformed request or response is one that is an otherwise valid 824 sequence of frames but is invalid due to: 826 * the presence of prohibited fields or pseudo-header fields, 828 * the absence of mandatory pseudo-header fields, 830 * invalid values for pseudo-header fields, 832 * pseudo-header fields after fields, 834 * an invalid sequence of HTTP messages, 836 * the inclusion of uppercase field names, or 838 * the inclusion of invalid characters in field names or values 840 A request or response that includes a payload body can include a 841 Content-Length header field. A request or response is also malformed 842 if the value of a content-length header field does not equal the sum 843 of the DATA frame payload lengths that form the body. A response 844 that is defined to have no payload, as described in Section 7.3.3 of 845 [SEMANTICS] can have a non-zero content-length field, even though no 846 content is included in DATA frames. 848 Intermediaries that process HTTP requests or responses (i.e., any 849 intermediary not acting as a tunnel) MUST NOT forward a malformed 850 request or response. Malformed requests or responses that are 851 detected MUST be treated as a stream error (Section 8) of type 852 H3_GENERAL_PROTOCOL_ERROR. 854 For malformed requests, a server MAY send an HTTP response indicating 855 the error prior to closing or resetting the stream. Clients MUST NOT 856 accept a malformed response. Note that these requirements are 857 intended to protect against several types of common attacks against 858 HTTP; they are deliberately strict because being permissive can 859 expose implementations to these vulnerabilities. 861 4.2. The CONNECT Method 863 The CONNECT method requests that the recipient establish a tunnel to 864 the destination origin server identified by the request-target 865 (Section 3.2 of [HTTP11]). It is primarily used with HTTP proxies to 866 establish a TLS session with an origin server for the purposes of 867 interacting with "https" resources. 869 In HTTP/1.x, CONNECT is used to convert an entire HTTP connection 870 into a tunnel to a remote host. In HTTP/2 and HTTP/3, the CONNECT 871 method is used to establish a tunnel over a single stream. 873 A CONNECT request MUST be constructed as follows: 875 * The ":method" pseudo-header field is set to "CONNECT" 877 * The ":scheme" and ":path" pseudo-header fields are omitted 879 * The ":authority" pseudo-header field contains the host and port to 880 connect to (equivalent to the authority-form of the request-target 881 of CONNECT requests; see Section 3.2.3 of [HTTP11]) 883 The request stream remains open at the end of the request to carry 884 the data to be transferred. A CONNECT request that does not conform 885 to these restrictions is malformed; see Section 4.1.3. 887 A proxy that supports CONNECT establishes a TCP connection 888 ([RFC0793]) to the server identified in the ":authority" pseudo- 889 header field. Once this connection is successfully established, the 890 proxy sends a HEADERS frame containing a 2xx series status code to 891 the client, as defined in Section 10.3 of [SEMANTICS]. 893 All DATA frames on the stream correspond to data sent or received on 894 the TCP connection. The payload of any DATA frame sent by the client 895 is transmitted by the proxy to the TCP server; data received from the 896 TCP server is packaged into DATA frames by the proxy. Note that the 897 size and number of TCP segments is not guaranteed to map predictably 898 to the size and number of HTTP DATA or QUIC STREAM frames. 900 Once the CONNECT method has completed, only DATA frames are permitted 901 to be sent on the stream. Extension frames MAY be used if 902 specifically permitted by the definition of the extension. Receipt 903 of any other known frame type MUST be treated as a connection error 904 of type H3_FRAME_UNEXPECTED. 906 The TCP connection can be closed by either peer. When the client 907 ends the request stream (that is, the receive stream at the proxy 908 enters the "Data Recvd" state), the proxy will set the FIN bit on its 909 connection to the TCP server. When the proxy receives a packet with 910 the FIN bit set, it will close the send stream that it sends to the 911 client. TCP connections that remain half-closed in a single 912 direction are not invalid, but are often handled poorly by servers, 913 so clients SHOULD NOT close a stream for sending while they still 914 expect to receive data from the target of the CONNECT. 916 A TCP connection error is signaled by abruptly terminating the 917 stream. A proxy treats any error in the TCP connection, which 918 includes receiving a TCP segment with the RST bit set, as a stream 919 error of type H3_CONNECT_ERROR (Section 8.1). Correspondingly, if a 920 proxy detects an error with the stream or the QUIC connection, it 921 MUST close the TCP connection. If the underlying TCP implementation 922 permits it, the proxy SHOULD send a TCP segment with the RST bit set. 924 4.3. HTTP Upgrade 926 HTTP/3 does not support the HTTP Upgrade mechanism (Section 6.7 of 927 {{!SEMANTICS}) or 101 (Switching Protocols) informational status code 928 (Section 10.2.2 of [SEMANTICS]). 930 4.4. Server Push 932 Server push is an interaction mode that permits a server to push a 933 request-response exchange to a client in anticipation of the client 934 making the indicated request. This trades off network usage against 935 a potential latency gain. HTTP/3 server push is similar to what is 936 described in Section 8.2 of [HTTP2], but uses different mechanisms. 938 Each server push is assigned a unique Push ID by the server. The 939 Push ID is used to refer to the push in various contexts throughout 940 the lifetime of the connection. 942 The Push ID space begins at zero, and ends at a maximum value set by 943 the MAX_PUSH_ID frame; see Section 7.2.7. In particular, a server is 944 not able to push until after the client sends a MAX_PUSH_ID frame. A 945 client sends MAX_PUSH_ID frames to control the number of pushes that 946 a server can promise. A server SHOULD use Push IDs sequentially, 947 beginning from zero. A client MUST treat receipt of a push stream as 948 a connection error of type H3_ID_ERROR when no MAX_PUSH_ID frame has 949 been sent or when the stream references a Push ID that is greater 950 than the maximum Push ID. 952 The Push ID is used in one or more PUSH_PROMISE frames 953 (Section 7.2.5) that carry the header section of the request message. 954 These frames are sent on the request stream that generated the push. 955 This allows the server push to be associated with a client request. 956 When the same Push ID is promised on multiple request streams, the 957 decompressed request field sections MUST contain the same fields in 958 the same order, and both the name and the value in each field MUST be 959 identical. 961 The Push ID is then included with the push stream that ultimately 962 fulfills those promises; see Section 6.2.2. The push stream 963 identifies the Push ID of the promise that it fulfills, then contains 964 a response to the promised request as described in Section 4.1. 966 Finally, the Push ID can be used in CANCEL_PUSH frames; see 967 Section 7.2.3. Clients use this frame to indicate they do not wish 968 to receive a promised resource. Servers use this frame to indicate 969 they will not be fulfilling a previous promise. 971 Not all requests can be pushed. A server MAY push requests that have 972 the following properties: 974 * cacheable; see Section 8.2.3 of [SEMANTICS] 976 * safe; see Section 8.2.1 of [SEMANTICS] 978 * does not include a request body or trailer section 980 The server MUST include a value in the ":authority" pseudo-header 981 field for which the server is authoritative; see Section 3.4. 983 Clients SHOULD send a CANCEL_PUSH frame upon receipt of a 984 PUSH_PROMISE frame carrying a request that is not cacheable, is not 985 known to be safe, that indicates the presence of a request body, or 986 for which it does not consider the server authoritative. 988 Each pushed response is associated with one or more client requests. 989 The push is associated with the request stream on which the 990 PUSH_PROMISE frame was received. The same server push can be 991 associated with additional client requests using a PUSH_PROMISE frame 992 with the same Push ID on multiple request streams. These 993 associations do not affect the operation of the protocol, but MAY be 994 considered by user agents when deciding how to use pushed resources. 996 Ordering of a PUSH_PROMISE frame in relation to certain parts of the 997 response is important. The server SHOULD send PUSH_PROMISE frames 998 prior to sending HEADERS or DATA frames that reference the promised 999 responses. This reduces the chance that a client requests a resource 1000 that will be pushed by the server. 1002 Due to reordering, push stream data can arrive before the 1003 corresponding PUSH_PROMISE frame. When a client receives a new push 1004 stream with an as-yet-unknown Push ID, both the associated client 1005 request and the pushed request header fields are unknown. The client 1006 can buffer the stream data in expectation of the matching 1007 PUSH_PROMISE. The client can use stream flow control (see section 1008 4.1 of [QUIC-TRANSPORT]) to limit the amount of data a server may 1009 commit to the pushed stream. 1011 Push stream data can also arrive after a client has canceled a push. 1012 In this case, the client can abort reading the stream with an error 1013 code of H3_REQUEST_CANCELLED. This asks the server not to transfer 1014 additional data and indicates that it will be discarded upon receipt. 1016 Pushed responses that are cacheable (see Section 3 of [CACHING]) can 1017 be stored by the client, if it implements an HTTP cache. Pushed 1018 responses are considered successfully validated on the origin server 1019 (e.g., if the "no-cache" cache response directive is present; see 1020 Section 5.2.2.3 of [CACHING]) at the time the pushed response is 1021 received. 1023 Pushed responses that are not cacheable MUST NOT be stored by any 1024 HTTP cache. They MAY be made available to the application 1025 separately. 1027 5. Connection Closure 1029 Once established, an HTTP/3 connection can be used for many requests 1030 and responses over time until the connection is closed. Connection 1031 closure can happen in any of several different ways. 1033 5.1. Idle Connections 1035 Each QUIC endpoint declares an idle timeout during the handshake. If 1036 the connection remains idle (no packets received) for longer than 1037 this duration, the peer will assume that the connection has been 1038 closed. HTTP/3 implementations will need to open a new connection 1039 for new requests if the existing connection has been idle for longer 1040 than the server's advertised idle timeout, and SHOULD do so if 1041 approaching the idle timeout. 1043 HTTP clients are expected to request that the transport keep 1044 connections open while there are responses outstanding for requests 1045 or server pushes, as described in Section 10.1.2 of [QUIC-TRANSPORT]. 1046 If the client is not expecting a response from the server, allowing 1047 an idle connection to time out is preferred over expending effort 1048 maintaining a connection that might not be needed. A gateway MAY 1049 maintain connections in anticipation of need rather than incur the 1050 latency cost of connection establishment to servers. Servers SHOULD 1051 NOT actively keep connections open. 1053 5.2. Connection Shutdown 1055 Even when a connection is not idle, either endpoint can decide to 1056 stop using the connection and initiate a graceful connection close. 1057 Endpoints initiate the graceful shutdown of a connection by sending a 1058 GOAWAY frame (Section 7.2.6). The GOAWAY frame contains an 1059 identifier that indicates to the receiver the range of requests or 1060 pushes that were or might be processed in this connection. The 1061 server sends a client-initiated bidirectional Stream ID; the client 1062 sends a Push ID (Section 4.4). Requests or pushes with the indicated 1063 identifier or greater are rejected (Section 4.1.2) by the sender of 1064 the GOAWAY. This identifier MAY be zero if no requests or pushes 1065 were processed. 1067 The information in the GOAWAY frame enables a client and server to 1068 agree on which requests or pushes were accepted prior to the 1069 connection shutdown. Upon sending a GOAWAY frame, the endpoint 1070 SHOULD explicitly cancel (see Section 4.1.2 and Section 7.2.3) any 1071 requests or pushes that have identifiers greater than or equal to 1072 that indicated, in order to clean up transport state for the affected 1073 streams. The endpoint SHOULD continue to do so as more requests or 1074 pushes arrive. 1076 Endpoints MUST NOT initiate new requests or promise new pushes on the 1077 connection after receipt of a GOAWAY frame from the peer. Clients 1078 MAY establish a new connection to send additional requests. 1080 Some requests or pushes might already be in transit: 1082 * Upon receipt of a GOAWAY frame, if the client has already sent 1083 requests with a Stream ID greater than or equal to the identifier 1084 contained in the GOAWAY frame, those requests will not be 1085 processed. Clients can safely retry unprocessed requests on a 1086 different connection. A client that is unable to retry requests 1087 loses all requests that are in flight when the server closes the 1088 connection. 1090 Requests on Stream IDs less than the Stream ID in a GOAWAY frame 1091 from the server might have been processed; their status cannot be 1092 known until a response is received, the stream is reset 1093 individually, another GOAWAY is received, or the connection 1094 terminates. 1096 Servers MAY reject individual requests on streams below the 1097 indicated ID if these requests were not processed. 1099 * If a server receives a GOAWAY frame after having promised pushes 1100 with a Push ID greater than or equal to the identifier contained 1101 in the GOAWAY frame, those pushes will not be accepted. 1103 Servers SHOULD send a GOAWAY frame when the closing of a connection 1104 is known in advance, even if the advance notice is small, so that the 1105 remote peer can know whether a request has been partially processed 1106 or not. For example, if an HTTP client sends a POST at the same time 1107 that a server closes a QUIC connection, the client cannot know if the 1108 server started to process that POST request if the server does not 1109 send a GOAWAY frame to indicate what streams it might have acted on. 1111 An endpoint MAY send multiple GOAWAY frames indicating different 1112 identifiers, but the identifier in each frame MUST NOT be greater 1113 than the identifier in any previous frame, since clients might 1114 already have retried unprocessed requests on another connection. 1115 Receiving a GOAWAY containing a larger identifier than previously 1116 received MUST be treated as a connection error of type H3_ID_ERROR. 1118 An endpoint that is attempting to gracefully shut down a connection 1119 can send a GOAWAY frame with a value set to the maximum possible 1120 value (2^62-4 for servers, 2^62-1 for clients). This ensures that 1121 the peer stops creating new requests or pushes. After allowing time 1122 for any in-flight requests or pushes to arrive, the endpoint can send 1123 another GOAWAY frame indicating which requests or pushes it might 1124 accept before the end of the connection. This ensures that a 1125 connection can be cleanly shut down without losing requests. 1127 A client has more flexibility in the value it chooses for the Push ID 1128 in a GOAWAY that it sends. A value of 2^62 - 1 indicates that the 1129 server can continue fulfilling pushes that have already been 1130 promised. A smaller value indicates the client will reject pushes 1131 with Push IDs greater than or equal to this value. Like the server, 1132 the client MAY send subsequent GOAWAY frames so long as the specified 1133 Push ID is no greater than any previously sent value. 1135 Even when a GOAWAY indicates that a given request or push will not be 1136 processed or accepted upon receipt, the underlying transport 1137 resources still exist. The endpoint that initiated these requests 1138 can cancel them to clean up transport state. 1140 Once all accepted requests and pushes have been processed, the 1141 endpoint can permit the connection to become idle, or MAY initiate an 1142 immediate closure of the connection. An endpoint that completes a 1143 graceful shutdown SHOULD use the H3_NO_ERROR error code when closing 1144 the connection. 1146 If a client has consumed all available bidirectional stream IDs with 1147 requests, the server need not send a GOAWAY frame, since the client 1148 is unable to make further requests. 1150 5.3. Immediate Application Closure 1152 An HTTP/3 implementation can immediately close the QUIC connection at 1153 any time. This results in sending a QUIC CONNECTION_CLOSE frame to 1154 the peer indicating that the application layer has terminated the 1155 connection. The application error code in this frame indicates to 1156 the peer why the connection is being closed. See Section 8 for error 1157 codes that can be used when closing a connection in HTTP/3. 1159 Before closing the connection, a GOAWAY frame MAY be sent to allow 1160 the client to retry some requests. Including the GOAWAY frame in the 1161 same packet as the QUIC CONNECTION_CLOSE frame improves the chances 1162 of the frame being received by clients. 1164 5.4. Transport Closure 1166 For various reasons, the QUIC transport could indicate to the 1167 application layer that the connection has terminated. This might be 1168 due to an explicit closure by the peer, a transport-level error, or a 1169 change in network topology that interrupts connectivity. 1171 If a connection terminates without a GOAWAY frame, clients MUST 1172 assume that any request that was sent, whether in whole or in part, 1173 might have been processed. 1175 6. Stream Mapping and Usage 1177 A QUIC stream provides reliable in-order delivery of bytes, but makes 1178 no guarantees about order of delivery with regard to bytes on other 1179 streams. On the wire, data is framed into QUIC STREAM frames, but 1180 this framing is invisible to the HTTP framing layer. The transport 1181 layer buffers and orders received QUIC STREAM frames, exposing the 1182 data contained within as a reliable byte stream to the application. 1184 Although QUIC permits out-of-order delivery within a stream, HTTP/3 1185 does not make use of this feature. 1187 QUIC streams can be either unidirectional, carrying data only from 1188 initiator to receiver, or bidirectional. Streams can be initiated by 1189 either the client or the server. For more detail on QUIC streams, 1190 see Section 2 of [QUIC-TRANSPORT]. 1192 When HTTP fields and data are sent over QUIC, the QUIC layer handles 1193 most of the stream management. HTTP does not need to do any separate 1194 multiplexing when using QUIC - data sent over a QUIC stream always 1195 maps to a particular HTTP transaction or connection context. 1197 6.1. Bidirectional Streams 1199 All client-initiated bidirectional streams are used for HTTP requests 1200 and responses. A bidirectional stream ensures that the response can 1201 be readily correlated with the request. This means that the client's 1202 first request occurs on QUIC stream 0, with subsequent requests on 1203 stream 4, 8, and so on. In order to permit these streams to open, an 1204 HTTP/3 server SHOULD configure non-zero minimum values for the number 1205 of permitted streams and the initial stream flow control window. So 1206 as to not unnecessarily limit parallelism, at least 100 requests 1207 SHOULD be permitted at a time. 1209 HTTP/3 does not use server-initiated bidirectional streams, though an 1210 extension could define a use for these streams. Clients MUST treat 1211 receipt of a server-initiated bidirectional stream as a connection 1212 error of type H3_STREAM_CREATION_ERROR unless such an extension has 1213 been negotiated. 1215 6.2. Unidirectional Streams 1217 Unidirectional streams, in either direction, are used for a range of 1218 purposes. The purpose is indicated by a stream type, which is sent 1219 as a variable-length integer at the start of the stream. The format 1220 and structure of data that follows this integer is determined by the 1221 stream type. 1223 Unidirectional Stream Header { 1224 Stream Type (i), 1225 } 1227 Figure 1: Unidirectional Stream Header 1229 Two stream types are defined in this document: control streams 1230 (Section 6.2.1) and push streams (Section 6.2.2). [QPACK] defines 1231 two additional stream types. Other stream types can be defined by 1232 extensions to HTTP/3; see Section 9 for more details. Some stream 1233 types are reserved (Section 6.2.3). 1235 The performance of HTTP/3 connections in the early phase of their 1236 lifetime is sensitive to the creation and exchange of data on 1237 unidirectional streams. Endpoints that excessively restrict the 1238 number of streams or the flow control window of these streams will 1239 increase the chance that the remote peer reaches the limit early and 1240 becomes blocked. In particular, implementations should consider that 1241 remote peers may wish to exercise reserved stream behavior 1242 (Section 6.2.3) with some of the unidirectional streams they are 1243 permitted to use. To avoid blocking, the transport parameters sent 1244 by both clients and servers MUST allow the peer to create at least 1245 one unidirectional stream for the HTTP control stream plus the number 1246 of unidirectional streams required by mandatory extensions (three 1247 being the minimum number required for the base HTTP/3 protocol and 1248 QPACK), and SHOULD provide at least 1,024 bytes of flow control 1249 credit to each stream. 1251 Note that an endpoint is not required to grant additional credits to 1252 create more unidirectional streams if its peer consumes all the 1253 initial credits before creating the critical unidirectional streams. 1254 Endpoints SHOULD create the HTTP control stream as well as the 1255 unidirectional streams required by mandatory extensions (such as the 1256 QPACK encoder and decoder streams) first, and then create additional 1257 streams as allowed by their peer. 1259 If the stream header indicates a stream type that is not supported by 1260 the recipient, the remainder of the stream cannot be consumed as the 1261 semantics are unknown. Recipients of unknown stream types MAY abort 1262 reading of the stream with an error code of H3_STREAM_CREATION_ERROR 1263 or a reserved error code (Section 8.1), but MUST NOT consider such 1264 streams to be a connection error of any kind. 1266 Implementations MAY send stream types before knowing whether the peer 1267 supports them. However, stream types that could modify the state or 1268 semantics of existing protocol components, including QPACK or other 1269 extensions, MUST NOT be sent until the peer is known to support them. 1271 A sender can close or reset a unidirectional stream unless otherwise 1272 specified. A receiver MUST tolerate unidirectional streams being 1273 closed or reset prior to the reception of the unidirectional stream 1274 header. 1276 6.2.1. Control Streams 1278 A control stream is indicated by a stream type of 0x00. Data on this 1279 stream consists of HTTP/3 frames, as defined in Section 7.2. 1281 Each side MUST initiate a single control stream at the beginning of 1282 the connection and send its SETTINGS frame as the first frame on this 1283 stream. If the first frame of the control stream is any other frame 1284 type, this MUST be treated as a connection error of type 1285 H3_MISSING_SETTINGS. Only one control stream per peer is permitted; 1286 receipt of a second stream claiming to be a control stream MUST be 1287 treated as a connection error of type H3_STREAM_CREATION_ERROR. The 1288 sender MUST NOT close the control stream, and the receiver MUST NOT 1289 request that the sender close the control stream. If either control 1290 stream is closed at any point, this MUST be treated as a connection 1291 error of type H3_CLOSED_CRITICAL_STREAM. 1293 A pair of unidirectional streams is used rather than a single 1294 bidirectional stream. This allows either peer to send data as soon 1295 as it is able. Depending on whether 0-RTT is enabled on the 1296 connection, either client or server might be able to send stream data 1297 first after the cryptographic handshake completes. 1299 6.2.2. Push Streams 1301 Server push is an optional feature introduced in HTTP/2 that allows a 1302 server to initiate a response before a request has been made. See 1303 Section 4.4 for more details. 1305 A push stream is indicated by a stream type of 0x01, followed by the 1306 Push ID of the promise that it fulfills, encoded as a variable-length 1307 integer. The remaining data on this stream consists of HTTP/3 1308 frames, as defined in Section 7.2, and fulfills a promised server 1309 push by zero or more interim HTTP responses followed by a single 1310 final HTTP response, as defined in Section 4.1. Server push and Push 1311 IDs are described in Section 4.4. 1313 Only servers can push; if a server receives a client-initiated push 1314 stream, this MUST be treated as a connection error of type 1315 H3_STREAM_CREATION_ERROR. 1317 Push Stream Header { 1318 Stream Type (i) = 0x01, 1319 Push ID (i), 1320 } 1322 Figure 2: Push Stream Header 1324 Each Push ID MUST only be used once in a push stream header. If a 1325 push stream header includes a Push ID that was used in another push 1326 stream header, the client MUST treat this as a connection error of 1327 type H3_ID_ERROR. 1329 6.2.3. Reserved Stream Types 1331 Stream types of the format "0x1f * N + 0x21" for non-negative integer 1332 values of N are reserved to exercise the requirement that unknown 1333 types be ignored. These streams have no semantics, and can be sent 1334 when application-layer padding is desired. They MAY also be sent on 1335 connections where no data is currently being transferred. Endpoints 1336 MUST NOT consider these streams to have any meaning upon receipt. 1338 The payload and length of the stream are selected in any manner the 1339 sending implementation chooses. When sending a reserved stream type, 1340 the implementation MAY either terminate the stream cleanly or reset 1341 it. When resetting the stream, either the H3_NO_ERROR error code or 1342 a reserved error code (Section 8.1) SHOULD be used. 1344 7. HTTP Framing Layer 1346 HTTP frames are carried on QUIC streams, as described in Section 6. 1347 HTTP/3 defines three stream types: control stream, request stream, 1348 and push stream. This section describes HTTP/3 frame formats and 1349 their permitted stream types; see Table 1 for an overview. A 1350 comparison between HTTP/2 and HTTP/3 frames is provided in 1351 Appendix A.2. 1353 +==============+================+================+========+=========+ 1354 | Frame | Control Stream | Request | Push | Section | 1355 | | | Stream | Stream | | 1356 +==============+================+================+========+=========+ 1357 | DATA | No | Yes | Yes | Section | 1358 | | | | | 7.2.1 | 1359 +--------------+----------------+----------------+--------+---------+ 1360 | HEADERS | No | Yes | Yes | Section | 1361 | | | | | 7.2.2 | 1362 +--------------+----------------+----------------+--------+---------+ 1363 | CANCEL_PUSH | Yes | No | No | Section | 1364 | | | | | 7.2.3 | 1365 +--------------+----------------+----------------+--------+---------+ 1366 | SETTINGS | Yes (1) | No | No | Section | 1367 | | | | | 7.2.4 | 1368 +--------------+----------------+----------------+--------+---------+ 1369 | PUSH_PROMISE | No | Yes | No | Section | 1370 | | | | | 7.2.5 | 1371 +--------------+----------------+----------------+--------+---------+ 1372 | GOAWAY | Yes | No | No | Section | 1373 | | | | | 7.2.6 | 1374 +--------------+----------------+----------------+--------+---------+ 1375 | MAX_PUSH_ID | Yes | No | No | Section | 1376 | | | | | 7.2.7 | 1377 +--------------+----------------+----------------+--------+---------+ 1378 | Reserved | Yes | Yes | Yes | Section | 1379 | | | | | 7.2.8 | 1380 +--------------+----------------+----------------+--------+---------+ 1382 Table 1: HTTP/3 Frames and Stream Type Overview 1384 Certain frames can only occur as the first frame of a particular 1385 stream type; these are indicated in Table 1 with a (1). Specific 1386 guidance is provided in the relevant section. 1388 Note that, unlike QUIC frames, HTTP/3 frames can span multiple 1389 packets. 1391 7.1. Frame Layout 1393 All frames have the following format: 1395 HTTP/3 Frame Format { 1396 Type (i), 1397 Length (i), 1398 Frame Payload (..), 1399 } 1400 Figure 3: HTTP/3 Frame Format 1402 A frame includes the following fields: 1404 Type: A variable-length integer that identifies the frame type. 1406 Length: A variable-length integer that describes the length in bytes 1407 of the Frame Payload. 1409 Frame Payload: A payload, the semantics of which are determined by 1410 the Type field. 1412 Each frame's payload MUST contain exactly the fields identified in 1413 its description. A frame payload that contains additional bytes 1414 after the identified fields or a frame payload that terminates before 1415 the end of the identified fields MUST be treated as a connection 1416 error (Section 8) of type H3_FRAME_ERROR. 1418 When a stream terminates cleanly, if the last frame on the stream was 1419 truncated, this MUST be treated as a connection error (Section 8) of 1420 type H3_FRAME_ERROR. Streams that terminate abruptly may be reset at 1421 any point in a frame. 1423 7.2. Frame Definitions 1425 7.2.1. DATA 1427 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 1428 bytes associated with an HTTP request or response payload body. 1430 DATA frames MUST be associated with an HTTP request or response. If 1431 a DATA frame is received on a control stream, the recipient MUST 1432 respond with a connection error (Section 8) of type 1433 H3_FRAME_UNEXPECTED. 1435 DATA Frame { 1436 Type (i) = 0x0, 1437 Length (i), 1438 Data (..), 1439 } 1441 Figure 4: DATA Frame 1443 7.2.2. HEADERS 1445 The HEADERS frame (type=0x1) is used to carry an HTTP field section, 1446 encoded using QPACK. See [QPACK] for more details. 1448 HEADERS Frame { 1449 Type (i) = 0x1, 1450 Length (i), 1451 Encoded Field Section (..), 1452 } 1454 Figure 5: HEADERS Frame 1456 HEADERS frames can only be sent on request or push streams. If a 1457 HEADERS frame is received on a control stream, the recipient MUST 1458 respond with a connection error (Section 8) of type 1459 H3_FRAME_UNEXPECTED. 1461 7.2.3. CANCEL_PUSH 1463 The CANCEL_PUSH frame (type=0x3) is used to request cancellation of a 1464 server push prior to the push stream being received. The CANCEL_PUSH 1465 frame identifies a server push by Push ID (see Section 4.4), encoded 1466 as a variable-length integer. 1468 When a client sends CANCEL_PUSH, it is indicating that it does not 1469 wish to receive the promised resource. The server SHOULD abort 1470 sending the resource, but the mechanism to do so depends on the state 1471 of the corresponding push stream. If the server has not yet created 1472 a push stream, it does not create one. If the push stream is open, 1473 the server SHOULD abruptly terminate that stream. If the push stream 1474 has already ended, the server MAY still abruptly terminate the stream 1475 or MAY take no action. 1477 When a server sends CANCEL_PUSH, it is indicating that it will not be 1478 fulfilling a promise. The client cannot expect the corresponding 1479 promise to be fulfilled, unless it has already received and processed 1480 the promised response. A server SHOULD send a CANCEL_PUSH frame even 1481 if it has opened the corresponding stream. 1483 Sending a CANCEL_PUSH frame has no direct effect on the state of 1484 existing push streams. A client SHOULD NOT send a CANCEL_PUSH frame 1485 when it has already received a corresponding push stream. A push 1486 stream could arrive after a client has sent a CANCEL_PUSH frame, 1487 because a server might not have processed the CANCEL_PUSH. The 1488 client SHOULD abort reading the stream with an error code of 1489 H3_REQUEST_CANCELLED. 1491 A CANCEL_PUSH frame is sent on the control stream. Receiving a 1492 CANCEL_PUSH frame on a stream other than the control stream MUST be 1493 treated as a connection error of type H3_FRAME_UNEXPECTED. 1495 CANCEL_PUSH Frame { 1496 Type (i) = 0x3, 1497 Length (i), 1498 Push ID (..), 1499 } 1501 Figure 6: CANCEL_PUSH Frame 1503 The CANCEL_PUSH frame carries a Push ID encoded as a variable-length 1504 integer. The Push ID identifies the server push that is being 1505 cancelled; see Section 4.4. If a CANCEL_PUSH frame is received that 1506 references a Push ID greater than currently allowed on the 1507 connection, this MUST be treated as a connection error of type 1508 H3_ID_ERROR. 1510 If the client receives a CANCEL_PUSH frame, that frame might identify 1511 a Push ID that has not yet been mentioned by a PUSH_PROMISE frame due 1512 to reordering. If a server receives a CANCEL_PUSH frame for a Push 1513 ID that has not yet been mentioned by a PUSH_PROMISE frame, this MUST 1514 be treated as a connection error of type H3_ID_ERROR. 1516 7.2.4. SETTINGS 1518 The SETTINGS frame (type=0x4) conveys configuration parameters that 1519 affect how endpoints communicate, such as preferences and constraints 1520 on peer behavior. Individually, a SETTINGS parameter can also be 1521 referred to as a "setting"; the identifier and value of each setting 1522 parameter can be referred to as a "setting identifier" and a "setting 1523 value". 1525 SETTINGS frames always apply to a connection, never a single stream. 1526 A SETTINGS frame MUST be sent as the first frame of each control 1527 stream (see Section 6.2.1) by each peer, and MUST NOT be sent 1528 subsequently. If an endpoint receives a second SETTINGS frame on the 1529 control stream, the endpoint MUST respond with a connection error of 1530 type H3_FRAME_UNEXPECTED. 1532 SETTINGS frames MUST NOT be sent on any stream other than the control 1533 stream. If an endpoint receives a SETTINGS frame on a different 1534 stream, the endpoint MUST respond with a connection error of type 1535 H3_FRAME_UNEXPECTED. 1537 SETTINGS parameters are not negotiated; they describe characteristics 1538 of the sending peer that can be used by the receiving peer. However, 1539 a negotiation can be implied by the use of SETTINGS - each peer uses 1540 SETTINGS to advertise a set of supported values. The definition of 1541 the setting would describe how each peer combines the two sets to 1542 conclude which choice will be used. SETTINGS does not provide a 1543 mechanism to identify when the choice takes effect. 1545 Different values for the same parameter can be advertised by each 1546 peer. For example, a client might be willing to consume a very large 1547 response field section, while servers are more cautious about request 1548 size. 1550 The same setting identifier MUST NOT occur more than once in the 1551 SETTINGS frame. A receiver MAY treat the presence of duplicate 1552 setting identifiers as a connection error of type H3_SETTINGS_ERROR. 1554 The payload of a SETTINGS frame consists of zero or more parameters. 1555 Each parameter consists of a setting identifier and a value, both 1556 encoded as QUIC variable-length integers. 1558 Setting { 1559 Identifier (i), 1560 Value (i), 1561 } 1563 SETTINGS Frame { 1564 Type (i) = 0x4, 1565 Length (i), 1566 Setting (..) ..., 1567 } 1569 Figure 7: SETTINGS Frame 1571 An implementation MUST ignore the contents for any SETTINGS 1572 identifier it does not understand. 1574 7.2.4.1. Defined SETTINGS Parameters 1576 The following settings are defined in HTTP/3: 1578 SETTINGS_MAX_FIELD_SECTION_SIZE (0x6): The default value is 1579 unlimited. See Section 4.1.1 for usage. 1581 Setting identifiers of the format "0x1f * N + 0x21" for non-negative 1582 integer values of N are reserved to exercise the requirement that 1583 unknown identifiers be ignored. Such settings have no defined 1584 meaning. Endpoints SHOULD include at least one such setting in their 1585 SETTINGS frame. Endpoints MUST NOT consider such settings to have 1586 any meaning upon receipt. 1588 Because the setting has no defined meaning, the value of the setting 1589 can be any value the implementation selects. 1591 Setting identifiers which were used in HTTP/2 where there is no 1592 corresponding HTTP/3 setting have also been reserved 1593 (Section 11.2.2). These settings MUST NOT be sent, and their receipt 1594 MUST be treated as a connection error of type H3_SETTINGS_ERROR. 1596 Additional settings can be defined by extensions to HTTP/3; see 1597 Section 9 for more details. 1599 7.2.4.2. Initialization 1601 An HTTP implementation MUST NOT send frames or requests that would be 1602 invalid based on its current understanding of the peer's settings. 1604 All settings begin at an initial value. Each endpoint SHOULD use 1605 these initial values to send messages before the peer's SETTINGS 1606 frame has arrived, as packets carrying the settings can be lost or 1607 delayed. When the SETTINGS frame arrives, any settings are changed 1608 to their new values. 1610 This removes the need to wait for the SETTINGS frame before sending 1611 messages. Endpoints MUST NOT require any data to be received from 1612 the peer prior to sending the SETTINGS frame; settings MUST be sent 1613 as soon as the transport is ready to send data. 1615 For servers, the initial value of each client setting is the default 1616 value. 1618 For clients using a 1-RTT QUIC connection, the initial value of each 1619 server setting is the default value. 1-RTT keys will always become 1620 available prior to the packet containing SETTINGS being processed by 1621 QUIC, even if the server sends SETTINGS immediately. Clients SHOULD 1622 NOT wait indefinitely for SETTINGS to arrive before sending requests, 1623 but SHOULD process received datagrams in order to increase the 1624 likelihood of processing SETTINGS before sending the first request. 1626 When a 0-RTT QUIC connection is being used, the initial value of each 1627 server setting is the value used in the previous session. Clients 1628 SHOULD store the settings the server provided in the connection where 1629 resumption information was provided, but MAY opt not to store 1630 settings in certain cases (e.g., if the session ticket is received 1631 before the SETTINGS frame). A client MUST comply with stored 1632 settings - or default values, if no values are stored - when 1633 attempting 0-RTT. Once a server has provided new settings, clients 1634 MUST comply with those values. 1636 A server can remember the settings that it advertised, or store an 1637 integrity-protected copy of the values in the ticket and recover the 1638 information when accepting 0-RTT data. A server uses the HTTP/3 1639 settings values in determining whether to accept 0-RTT data. If the 1640 server cannot determine that the settings remembered by a client are 1641 compatible with its current settings, it MUST NOT accept 0-RTT data. 1642 Remembered settings are compatible if a client complying with those 1643 settings would not violate the server's current settings. 1645 A server MAY accept 0-RTT and subsequently provide different settings 1646 in its SETTINGS frame. If 0-RTT data is accepted by the server, its 1647 SETTINGS frame MUST NOT reduce any limits or alter any values that 1648 might be violated by the client with its 0-RTT data. The server MUST 1649 include all settings that differ from their default values. If a 1650 server accepts 0-RTT but then sends settings that are not compatible 1651 with the previously specified settings, this MUST be treated as a 1652 connection error of type H3_SETTINGS_ERROR. If a server accepts 1653 0-RTT but then sends a SETTINGS frame that omits a setting value that 1654 the client understands (apart from reserved setting identifiers) that 1655 was previously specified to have a non-default value, this MUST be 1656 treated as a connection error of type H3_SETTINGS_ERROR. 1658 7.2.5. PUSH_PROMISE 1660 The PUSH_PROMISE frame (type=0x5) is used to carry a promised request 1661 header field section from server to client on a request stream, as in 1662 HTTP/2. 1664 PUSH_PROMISE Frame { 1665 Type (i) = 0x5, 1666 Length (i), 1667 Push ID (i), 1668 Encoded Field Section (..), 1669 } 1671 Figure 8: PUSH_PROMISE Frame 1673 The payload consists of: 1675 Push ID: A variable-length integer that identifies the server push 1676 operation. A Push ID is used in push stream headers (Section 4.4) 1677 and CANCEL_PUSH frames (Section 7.2.3). 1679 Encoded Field Section: QPACK-encoded request header fields for the 1680 promised response. See [QPACK] for more details. 1682 A server MUST NOT use a Push ID that is larger than the client has 1683 provided in a MAX_PUSH_ID frame (Section 7.2.7). A client MUST treat 1684 receipt of a PUSH_PROMISE frame that contains a larger Push ID than 1685 the client has advertised as a connection error of H3_ID_ERROR. 1687 A server MAY use the same Push ID in multiple PUSH_PROMISE frames. 1688 If so, the decompressed request header sets MUST contain the same 1689 fields in the same order, and both the name and the value in each 1690 field MUST be exact matches. Clients SHOULD compare the request 1691 header sections for resources promised multiple times. If a client 1692 receives a Push ID that has already been promised and detects a 1693 mismatch, it MUST respond with a connection error of type 1694 H3_GENERAL_PROTOCOL_ERROR. If the decompressed field sections match 1695 exactly, the client SHOULD associate the pushed content with each 1696 stream on which a PUSH_PROMISE frame was received. 1698 Allowing duplicate references to the same Push ID is primarily to 1699 reduce duplication caused by concurrent requests. A server SHOULD 1700 avoid reusing a Push ID over a long period. Clients are likely to 1701 consume server push responses and not retain them for reuse over 1702 time. Clients that see a PUSH_PROMISE frame that uses a Push ID that 1703 they have already consumed and discarded are forced to ignore the 1704 promise. 1706 If a PUSH_PROMISE frame is received on the control stream, the client 1707 MUST respond with a connection error (Section 8) of type 1708 H3_FRAME_UNEXPECTED. 1710 A client MUST NOT send a PUSH_PROMISE frame. A server MUST treat the 1711 receipt of a PUSH_PROMISE frame as a connection error of type 1712 H3_FRAME_UNEXPECTED. 1714 See Section 4.4 for a description of the overall server push 1715 mechanism. 1717 7.2.6. GOAWAY 1719 The GOAWAY frame (type=0x7) is used to initiate graceful shutdown of 1720 a connection by either endpoint. GOAWAY allows an endpoint to stop 1721 accepting new requests or pushes while still finishing processing of 1722 previously received requests and pushes. This enables administrative 1723 actions, like server maintenance. GOAWAY by itself does not close a 1724 connection. 1726 GOAWAY Frame { 1727 Type (i) = 0x7, 1728 Length (i), 1729 Stream ID/Push ID (..), 1730 } 1732 Figure 9: GOAWAY Frame 1734 The GOAWAY frame is always sent on the control stream. In the server 1735 to client direction, it carries a QUIC Stream ID for a client- 1736 initiated bidirectional stream encoded as a variable-length integer. 1737 A client MUST treat receipt of a GOAWAY frame containing a Stream ID 1738 of any other type as a connection error of type H3_ID_ERROR. 1740 In the client to server direction, the GOAWAY frame carries a Push ID 1741 encoded as a variable-length integer. 1743 The GOAWAY frame applies to the connection, not a specific stream. A 1744 client MUST treat a GOAWAY frame on a stream other than the control 1745 stream as a connection error (Section 8) of type H3_FRAME_UNEXPECTED. 1747 See Section 5.2 for more information on the use of the GOAWAY frame. 1749 7.2.7. MAX_PUSH_ID 1751 The MAX_PUSH_ID frame (type=0xd) is used by clients to control the 1752 number of server pushes that the server can initiate. This sets the 1753 maximum value for a Push ID that the server can use in PUSH_PROMISE 1754 and CANCEL_PUSH frames. Consequently, this also limits the number of 1755 push streams that the server can initiate in addition to the limit 1756 maintained by the QUIC transport. 1758 The MAX_PUSH_ID frame is always sent on the control stream. Receipt 1759 of a MAX_PUSH_ID frame on any other stream MUST be treated as a 1760 connection error of type H3_FRAME_UNEXPECTED. 1762 A server MUST NOT send a MAX_PUSH_ID frame. A client MUST treat the 1763 receipt of a MAX_PUSH_ID frame as a connection error of type 1764 H3_FRAME_UNEXPECTED. 1766 The maximum Push ID is unset when a connection is created, meaning 1767 that a server cannot push until it receives a MAX_PUSH_ID frame. A 1768 client that wishes to manage the number of promised server pushes can 1769 increase the maximum Push ID by sending MAX_PUSH_ID frames as the 1770 server fulfills or cancels server pushes. 1772 MAX_PUSH_ID Frame { 1773 Type (i) = 0xd, 1774 Length (i), 1775 Push ID (i), 1776 } 1778 Figure 10: MAX_PUSH_ID Frame 1780 The MAX_PUSH_ID frame carries a single variable-length integer that 1781 identifies the maximum value for a Push ID that the server can use; 1782 see Section 4.4. A MAX_PUSH_ID frame cannot reduce the maximum Push 1783 ID; receipt of a MAX_PUSH_ID frame that contains a smaller value than 1784 previously received MUST be treated as a connection error of type 1785 H3_ID_ERROR. 1787 7.2.8. Reserved Frame Types 1789 Frame types of the format "0x1f * N + 0x21" for non-negative integer 1790 values of N are reserved to exercise the requirement that unknown 1791 types be ignored (Section 9). These frames have no semantics, and 1792 can be sent on any open stream when application-layer padding is 1793 desired. They MAY also be sent on connections where no data is 1794 currently being transferred. Endpoints MUST NOT consider these 1795 frames to have any meaning upon receipt. 1797 The payload and length of the frames are selected in any manner the 1798 implementation chooses. 1800 Frame types that were used in HTTP/2 where there is no corresponding 1801 HTTP/3 frame have also been reserved (Section 11.2.1). These frame 1802 types MUST NOT be sent, and their receipt MUST be treated as a 1803 connection error of type H3_FRAME_UNEXPECTED. 1805 8. Error Handling 1807 QUIC allows the application to abruptly terminate (reset) individual 1808 streams or the entire connection; see Sections 2.4 and 5.3 of 1809 [QUIC-TRANSPORT]. These are referred to as "stream errors" or 1810 "connection errors" (see Section 11 of [QUIC-TRANSPORT]) and have 1811 associated error codes, but do not necessarily indicate a problem 1812 with the connection or either implementation. For example, a stream 1813 can be reset if the requested resource is no longer needed. 1815 An endpoint MAY choose to treat a stream error as a connection error 1816 under certain circumstances. Implementations need to consider the 1817 impact on outstanding requests before making this choice. 1819 Because new error codes can be defined without negotiation (see 1820 Section 9), use of an error code in an unexpected context or receipt 1821 of an unknown error code MUST be treated as equivalent to 1822 H3_NO_ERROR. However, closing a stream can have other effects 1823 regardless of the error code; for example, see Section 4.1. 1825 This section describes HTTP/3-specific error codes that can be used 1826 to express the cause of a connection or stream error. 1828 8.1. HTTP/3 Error Codes 1830 The following error codes are defined for use when abruptly 1831 terminating streams, aborting reading of streams, or immediately 1832 closing connections. 1834 H3_NO_ERROR (0x100): No error. This is used when the connection or 1835 stream needs to be closed, but there is no error to signal. 1837 H3_GENERAL_PROTOCOL_ERROR (0x101): Peer violated protocol 1838 requirements in a way that does not match a more specific error 1839 code, or endpoint declines to use the more specific error code. 1841 H3_INTERNAL_ERROR (0x102): An internal error has occurred in the 1842 HTTP stack. 1844 H3_STREAM_CREATION_ERROR (0x103): The endpoint detected that its 1845 peer created a stream that it will not accept. 1847 H3_CLOSED_CRITICAL_STREAM (0x104): A stream required by the 1848 connection was closed or reset. 1850 H3_FRAME_UNEXPECTED (0x105): A frame was received that was not 1851 permitted in the current state or on the current stream. 1853 H3_FRAME_ERROR (0x106): A frame that fails to satisfy layout 1854 requirements or with an invalid size was received. 1856 H3_EXCESSIVE_LOAD (0x107): The endpoint detected that its peer is 1857 exhibiting a behavior that might be generating excessive load. 1859 H3_ID_ERROR (0x108): A Stream ID or Push ID was used incorrectly, 1860 such as exceeding a limit, reducing a limit, or being reused. 1862 H3_SETTINGS_ERROR (0x109): An endpoint detected an error in the 1863 payload of a SETTINGS frame. 1865 H3_MISSING_SETTINGS (0x10a): No SETTINGS frame was received at the 1866 beginning of the control stream. 1868 H3_REQUEST_REJECTED (0x10b): A server rejected a request without 1869 performing any application processing. 1871 H3_REQUEST_CANCELLED (0x10c): The request or its response (including 1872 pushed response) is cancelled. 1874 H3_REQUEST_INCOMPLETE (0x10d): The client's stream terminated 1875 without containing a fully-formed request. 1877 H3_CONNECT_ERROR (0x10f): The connection established in response to 1878 a CONNECT request was reset or abnormally closed. 1880 H3_VERSION_FALLBACK (0x110): The requested operation cannot be 1881 served over HTTP/3. The peer should retry over HTTP/1.1. 1883 Error codes of the format "0x1f * N + 0x21" for non-negative integer 1884 values of N are reserved to exercise the requirement that unknown 1885 error codes be treated as equivalent to H3_NO_ERROR (Section 9). 1886 Implementations SHOULD select an error code from this space with some 1887 probability when they would have sent H3_NO_ERROR. 1889 9. Extensions to HTTP/3 1891 HTTP/3 permits extension of the protocol. Within the limitations 1892 described in this section, protocol extensions can be used to provide 1893 additional services or alter any aspect of the protocol. Extensions 1894 are effective only within the scope of a single HTTP/3 connection. 1896 This applies to the protocol elements defined in this document. This 1897 does not affect the existing options for extending HTTP, such as 1898 defining new methods, status codes, or fields. 1900 Extensions are permitted to use new frame types (Section 7.2), new 1901 settings (Section 7.2.4.1), new error codes (Section 8), or new 1902 unidirectional stream types (Section 6.2). Registries are 1903 established for managing these extension points: frame types 1904 (Section 11.2.1), settings (Section 11.2.2), error codes 1905 (Section 11.2.3), and stream types (Section 11.2.4). 1907 Implementations MUST ignore unknown or unsupported values in all 1908 extensible protocol elements. Implementations MUST discard frames 1909 and unidirectional streams that have unknown or unsupported types. 1910 This means that any of these extension points can be safely used by 1911 extensions without prior arrangement or negotiation. However, where 1912 a known frame type is required to be in a specific location, such as 1913 the SETTINGS frame as the first frame of the control stream (see 1914 Section 6.2.1), an unknown frame type does not satisfy that 1915 requirement and SHOULD be treated as an error. 1917 Extensions that could change the semantics of existing protocol 1918 components MUST be negotiated before being used. For example, an 1919 extension that changes the layout of the HEADERS frame cannot be used 1920 until the peer has given a positive signal that this is acceptable. 1921 Coordinating when such a revised layout comes into effect could prove 1922 complex. As such, allocating new identifiers for new definitions of 1923 existing protocol elements is likely to be more effective. 1925 This document does not mandate a specific method for negotiating the 1926 use of an extension but notes that a setting (Section 7.2.4.1) could 1927 be used for that purpose. If both peers set a value that indicates 1928 willingness to use the extension, then the extension can be used. If 1929 a setting is used for extension negotiation, the default value MUST 1930 be defined in such a fashion that the extension is disabled if the 1931 setting is omitted. 1933 10. Security Considerations 1935 The security considerations of HTTP/3 should be comparable to those 1936 of HTTP/2 with TLS. However, many of the considerations from 1937 Section 10 of [HTTP2] apply to [QUIC-TRANSPORT] and are discussed in 1938 that document. 1940 10.1. Server Authority 1942 HTTP/3 relies on the HTTP definition of authority. The security 1943 considerations of establishing authority are discussed in 1944 Section 12.1 of [SEMANTICS]. 1946 10.2. Cross-Protocol Attacks 1948 The use of ALPN in the TLS and QUIC handshakes establishes the target 1949 application protocol before application-layer bytes are processed. 1950 Because all QUIC packets are encrypted, it is difficult for an 1951 attacker to control the plaintext bytes of an HTTP/3 connection, 1952 which could be used in a cross-protocol attack on a plaintext 1953 protocol. 1955 10.3. Intermediary Encapsulation Attacks 1957 The HTTP/3 field encoding allows the expression of names that are not 1958 valid field names in the syntax used by HTTP (Section 5.3 of 1959 [SEMANTICS]). Requests or responses containing invalid field names 1960 MUST be treated as malformed (Section 4.1.3). An intermediary 1961 therefore cannot translate an HTTP/3 request or response containing 1962 an invalid field name into an HTTP/1.1 message. 1964 Similarly, HTTP/3 can transport field values that are not valid. 1965 While most values that can be encoded will not alter field parsing, 1966 carriage return (CR, ASCII 0xd), line feed (LF, ASCII 0xa), and the 1967 zero character (NUL, ASCII 0x0) might be exploited by an attacker if 1968 they are translated verbatim. Any request or response that contains 1969 a character not permitted in a field value MUST be treated as 1970 malformed (Section 4.1.3). Valid characters are defined by the 1971 "field-content" ABNF rule in Section 5.4 of [SEMANTICS]. 1973 10.4. Cacheability of Pushed Responses 1975 Pushed responses do not have an explicit request from the client; the 1976 request is provided by the server in the PUSH_PROMISE frame. 1978 Caching responses that are pushed is possible based on the guidance 1979 provided by the origin server in the Cache-Control header field. 1980 However, this can cause issues if a single server hosts more than one 1981 tenant. For example, a server might offer multiple users each a 1982 small portion of its URI space. 1984 Where multiple tenants share space on the same server, that server 1985 MUST ensure that tenants are not able to push representations of 1986 resources that they do not have authority over. Failure to enforce 1987 this would allow a tenant to provide a representation that would be 1988 served out of cache, overriding the actual representation that the 1989 authoritative tenant provides. 1991 Pushed responses for which an origin server is not authoritative (see 1992 Section 3.4) MUST NOT be used or cached. 1994 10.5. Denial-of-Service Considerations 1996 An HTTP/3 connection can demand a greater commitment of resources to 1997 operate than an HTTP/1.1 or HTTP/2 connection. The use of field 1998 compression and flow control depend on a commitment of resources for 1999 storing a greater amount of state. Settings for these features 2000 ensure that memory commitments for these features are strictly 2001 bounded. 2003 The number of PUSH_PROMISE frames is constrained in a similar 2004 fashion. A client that accepts server push SHOULD limit the number 2005 of Push IDs it issues at a time. 2007 Processing capacity cannot be guarded as effectively as state 2008 capacity. 2010 The ability to send undefined protocol elements that the peer is 2011 required to ignore can be abused to cause a peer to expend additional 2012 processing time. This might be done by setting multiple undefined 2013 SETTINGS parameters, unknown frame types, or unknown stream types. 2014 Note, however, that some uses are entirely legitimate, such as 2015 optional-to-understand extensions and padding to increase resistance 2016 to traffic analysis. 2018 Compression of field sections also offers some opportunities to waste 2019 processing resources; see Section 7 of [QPACK] for more details on 2020 potential abuses. 2022 All these features - i.e., server push, unknown protocol elements, 2023 field compression - have legitimate uses. These features become a 2024 burden only when they are used unnecessarily or to excess. 2026 An endpoint that does not monitor this behavior exposes itself to a 2027 risk of denial-of-service attack. Implementations SHOULD track the 2028 use of these features and set limits on their use. An endpoint MAY 2029 treat activity that is suspicious as a connection error (Section 8) 2030 of type H3_EXCESSIVE_LOAD, but false positives will result in 2031 disrupting valid connections and requests. 2033 10.5.1. Limits on Field Section Size 2035 A large field section (Section 4.1) can cause an implementation to 2036 commit a large amount of state. Header fields that are critical for 2037 routing can appear toward the end of a header field section, which 2038 prevents streaming of the header field section to its ultimate 2039 destination. This ordering and other reasons, such as ensuring cache 2040 correctness, mean that an endpoint likely needs to buffer the entire 2041 header field section. Since there is no hard limit to the size of a 2042 field section, some endpoints could be forced to commit a large 2043 amount of available memory for header fields. 2045 An endpoint can use the SETTINGS_MAX_FIELD_SECTION_SIZE 2046 (Section 4.1.1.3) setting to advise peers of limits that might apply 2047 on the size of field sections. This setting is only advisory, so 2048 endpoints MAY choose to send field sections that exceed this limit 2049 and risk having the request or response being treated as malformed. 2050 This setting is specific to a connection, so any request or response 2051 could encounter a hop with a lower, unknown limit. An intermediary 2052 can attempt to avoid this problem by passing on values presented by 2053 different peers, but they are not obligated to do so. 2055 A server that receives a larger field section than it is willing to 2056 handle can send an HTTP 431 (Request Header Fields Too Large) status 2057 code ([RFC6585]). A client can discard responses that it cannot 2058 process. 2060 10.5.2. CONNECT Issues 2062 The CONNECT method can be used to create disproportionate load on a 2063 proxy, since stream creation is relatively inexpensive when compared 2064 to the creation and maintenance of a TCP connection. A proxy might 2065 also maintain some resources for a TCP connection beyond the closing 2066 of the stream that carries the CONNECT request, since the outgoing 2067 TCP connection remains in the TIME_WAIT state. Therefore, a proxy 2068 cannot rely on QUIC stream limits alone to control the resources 2069 consumed by CONNECT requests. 2071 10.6. Use of Compression 2073 Compression can allow an attacker to recover secret data when it is 2074 compressed in the same context as data under attacker control. 2075 HTTP/3 enables compression of fields (Section 4.1.1); the following 2076 concerns also apply to the use of HTTP compressed content-codings; 2077 see Section 7.1.2 of [SEMANTICS]. 2079 There are demonstrable attacks on compression that exploit the 2080 characteristics of the web (e.g., [BREACH]). The attacker induces 2081 multiple requests containing varying plaintext, observing the length 2082 of the resulting ciphertext in each, which reveals a shorter length 2083 when a guess about the secret is correct. 2085 Implementations communicating on a secure channel MUST NOT compress 2086 content that includes both confidential and attacker-controlled data 2087 unless separate compression contexts are used for each source of 2088 data. Compression MUST NOT be used if the source of data cannot be 2089 reliably determined. 2091 Further considerations regarding the compression of fields sections 2092 are described in [QPACK]. 2094 10.7. Padding and Traffic Analysis 2096 Padding can be used to obscure the exact size of frame content and is 2097 provided to mitigate specific attacks within HTTP, for example, 2098 attacks where compressed content includes both attacker-controlled 2099 plaintext and secret data (e.g., [BREACH]). 2101 Where HTTP/2 employs PADDING frames and Padding fields in other 2102 frames to make a connection more resistant to traffic analysis, 2103 HTTP/3 can either rely on transport-layer padding or employ the 2104 reserved frame and stream types discussed in Section 7.2.8 and 2105 Section 6.2.3. These methods of padding produce different results in 2106 terms of the granularity of padding, how padding is arranged in 2107 relation to the information that is being protected, whether padding 2108 is applied in the case of packet loss, and how an implementation 2109 might control padding. Redundant padding could even be 2110 counterproductive. 2112 To mitigate attacks that rely on compression, disabling or limiting 2113 compression might be preferable to padding as a countermeasure. 2115 Use of padding can result in less protection than might seem 2116 immediately obvious. At best, padding only makes it more difficult 2117 for an attacker to infer length information by increasing the number 2118 of frames an attacker has to observe. Incorrectly implemented 2119 padding schemes can be easily defeated. In particular, randomized 2120 padding with a predictable distribution provides very little 2121 protection; similarly, padding payloads to a fixed size exposes 2122 information as payload sizes cross the fixed-sized boundary, which 2123 could be possible if an attacker can control plaintext. 2125 10.8. Frame Parsing 2127 Several protocol elements contain nested length elements, typically 2128 in the form of frames with an explicit length containing variable- 2129 length integers. This could pose a security risk to an incautious 2130 implementer. An implementation MUST ensure that the length of a 2131 frame exactly matches the length of the fields it contains. 2133 10.9. Early Data 2135 The use of 0-RTT with HTTP/3 creates an exposure to replay attack. 2136 The anti-replay mitigations in [HTTP-REPLAY] MUST be applied when 2137 using HTTP/3 with 0-RTT. 2139 10.10. Migration 2141 Certain HTTP implementations use the client address for logging or 2142 access-control purposes. Since a QUIC client's address might change 2143 during a connection (and future versions might support simultaneous 2144 use of multiple addresses), such implementations will need to either 2145 actively retrieve the client's current address or addresses when they 2146 are relevant or explicitly accept that the original address might 2147 change. 2149 10.11. Privacy Considerations 2151 Several characteristics of HTTP/3 provide an observer an opportunity 2152 to correlate actions of a single client or server over time. These 2153 include the value of settings, the timing of reactions to stimulus, 2154 and the handling of any features that are controlled by settings. 2156 As far as these create observable differences in behavior, they could 2157 be used as a basis for fingerprinting a specific client. 2159 HTTP/3's preference for using a single QUIC connection allows 2160 correlation of a user's activity on a site. Reusing connections for 2161 different origins allows for correlation of activity across those 2162 origins. 2164 Several features of QUIC solicit immediate responses and can be used 2165 by an endpoint to measure latency to their peer; this might have 2166 privacy implications in certain scenarios. 2168 11. IANA Considerations 2170 This document registers a new ALPN protocol ID (Section 11.1) and 2171 creates new registries that manage the assignment of codepoints in 2172 HTTP/3. 2174 11.1. Registration of HTTP/3 Identification String 2176 This document creates a new registration for the identification of 2177 HTTP/3 in the "Application Layer Protocol Negotiation (ALPN) Protocol 2178 IDs" registry established in [RFC7301]. 2180 The "h3" string identifies HTTP/3: 2182 Protocol: HTTP/3 2184 Identification Sequence: 0x68 0x33 ("h3") 2186 Specification: This document 2188 11.2. New Registries 2190 New registries created in this document operate under the QUIC 2191 registration policy documented in Section 22.1 of [QUIC-TRANSPORT]. 2192 These registries all include the common set of fields listed in 2193 Section 22.1.1 of [QUIC-TRANSPORT]. 2195 The initial allocations in these registries created in this document 2196 are all assigned permanent status and list as contact both the IESG 2197 (iesg@ietf.org) and the HTTP working group (ietf-http-wg@w3.org). 2199 11.2.1. Frame Types 2201 This document establishes a registry for HTTP/3 frame type codes. 2202 The "HTTP/3 Frame Type" registry governs a 62-bit space. This 2203 registry follows the QUIC registry policy; see Section 11.2. 2204 Permanent registrations in this registry are assigned using the 2205 Specification Required policy ([RFC8126]), except for values between 2206 0x00 and 0x3f (in hexadecimal; inclusive), which are assigned using 2207 Standards Action or IESG Approval as defined in Section 4.9 and 4.10 2208 of [RFC8126]. 2210 While this registry is separate from the "HTTP/2 Frame Type" registry 2211 defined in [HTTP2], it is preferable that the assignments parallel 2212 each other where the code spaces overlap. If an entry is present in 2213 only one registry, every effort SHOULD be made to avoid assigning the 2214 corresponding value to an unrelated operation. 2216 In addition to common fields as described in Section 11.2, permanent 2217 registrations in this registry MUST include the following field: 2219 Frame Type: A name or label for the frame type. 2221 Specifications of frame types MUST include a description of the frame 2222 layout and its semantics, including any parts of the frame that are 2223 conditionally present. 2225 The entries in Table 2 are registered by this document. 2227 +==============+=======+===============+ 2228 | Frame Type | Value | Specification | 2229 +==============+=======+===============+ 2230 | DATA | 0x0 | Section 7.2.1 | 2231 +--------------+-------+---------------+ 2232 | HEADERS | 0x1 | Section 7.2.2 | 2233 +--------------+-------+---------------+ 2234 | Reserved | 0x2 | N/A | 2235 +--------------+-------+---------------+ 2236 | CANCEL_PUSH | 0x3 | Section 7.2.3 | 2237 +--------------+-------+---------------+ 2238 | SETTINGS | 0x4 | Section 7.2.4 | 2239 +--------------+-------+---------------+ 2240 | PUSH_PROMISE | 0x5 | Section 7.2.5 | 2241 +--------------+-------+---------------+ 2242 | Reserved | 0x6 | N/A | 2243 +--------------+-------+---------------+ 2244 | GOAWAY | 0x7 | Section 7.2.6 | 2245 +--------------+-------+---------------+ 2246 | Reserved | 0x8 | N/A | 2247 +--------------+-------+---------------+ 2248 | Reserved | 0x9 | N/A | 2249 +--------------+-------+---------------+ 2250 | MAX_PUSH_ID | 0xd | Section 7.2.7 | 2251 +--------------+-------+---------------+ 2253 Table 2: Initial HTTP/3 Frame Types 2255 Additionally, each code of the format "0x1f * N + 0x21" for non- 2256 negative integer values of N (that is, 0x21, 0x40, ..., through 2257 0x3FFFFFFFFFFFFFFE) MUST NOT be assigned by IANA. 2259 11.2.2. Settings Parameters 2261 This document establishes a registry for HTTP/3 settings. The 2262 "HTTP/3 Settings" registry governs a 62-bit space. This registry 2263 follows the QUIC registry policy; see Section 11.2. Permanent 2264 registrations in this registry are assigned using the Specification 2265 Required policy ([RFC8126]), except for values between 0x00 and 0x3f 2266 (in hexadecimal; inclusive), which are assigned using Standards 2267 Action or IESG Approval as defined in Section 4.9 and 4.10 of 2268 [RFC8126]. 2270 While this registry is separate from the "HTTP/2 Settings" registry 2271 defined in [HTTP2], it is preferable that the assignments parallel 2272 each other. If an entry is present in only one registry, every 2273 effort SHOULD be made to avoid assigning the corresponding value to 2274 an unrelated operation. 2276 In addition to common fields as described in Section 11.2, permanent 2277 registrations in this registry MUST include the following fields: 2279 Setting Name: A symbolic name for the setting. Specifying a setting 2280 name is optional. 2282 Default: The value of the setting unless otherwise indicated. A 2283 default SHOULD be the most restrictive possible value. 2285 The entries in Table 3 are registered by this document. 2287 +========================+=======+=================+===========+ 2288 | Setting Name | Value | Specification | Default | 2289 +========================+=======+=================+===========+ 2290 | Reserved | 0x2 | N/A | N/A | 2291 +------------------------+-------+-----------------+-----------+ 2292 | Reserved | 0x3 | N/A | N/A | 2293 +------------------------+-------+-----------------+-----------+ 2294 | Reserved | 0x4 | N/A | N/A | 2295 +------------------------+-------+-----------------+-----------+ 2296 | Reserved | 0x5 | N/A | N/A | 2297 +------------------------+-------+-----------------+-----------+ 2298 | MAX_FIELD_SECTION_SIZE | 0x6 | Section 7.2.4.1 | Unlimited | 2299 +------------------------+-------+-----------------+-----------+ 2301 Table 3: Initial HTTP/3 Settings 2303 Additionally, each code of the format "0x1f * N + 0x21" for non- 2304 negative integer values of N (that is, 0x21, 0x40, ..., through 2305 0x3ffffffffffffffe) MUST NOT be assigned by IANA. 2307 11.2.3. Error Codes 2309 This document establishes a registry for HTTP/3 error codes. The 2310 "HTTP/3 Error Code" registry manages a 62-bit space. This registry 2311 follows the QUIC registry policy; see Section 11.2. Permanent 2312 registrations in this registry are assigned using the Specification 2313 Required policy ([RFC8126]), except for values between 0x00 and 0x3f 2314 (in hexadecimal; inclusive), which are assigned using Standards 2315 Action or IESG Approval as defined in Section 4.9 and 4.10 of 2316 [RFC8126]. 2318 Registrations for error codes are required to include a description 2319 of the error code. An expert reviewer is advised to examine new 2320 registrations for possible duplication with existing error codes. 2321 Use of existing registrations is to be encouraged, but not mandated. 2323 In addition to common fields as described in Section 11.2, this 2324 registry includes two additional fields. Permanent registrations in 2325 this registry MUST include the following field: 2327 Name: A name for the error code. 2329 Description: A brief description of the error code semantics. 2331 The entries in Table 4 are registered by this document. 2333 +===========================+========+==============+===============+ 2334 | Name | Value | Description | Specification | 2335 +===========================+========+==============+===============+ 2336 | H3_NO_ERROR | 0x0100 | No error | Section 8.1 | 2337 +---------------------------+--------+--------------+---------------+ 2338 | H3_GENERAL_PROTOCOL_ERROR | 0x0101 | General | Section 8.1 | 2339 | | | protocol | | 2340 | | | error | | 2341 +---------------------------+--------+--------------+---------------+ 2342 | H3_INTERNAL_ERROR | 0x0102 | Internal | Section 8.1 | 2343 | | | error | | 2344 +---------------------------+--------+--------------+---------------+ 2345 | H3_STREAM_CREATION_ERROR | 0x0103 | Stream | Section 8.1 | 2346 | | | creation | | 2347 | | | error | | 2348 +---------------------------+--------+--------------+---------------+ 2349 | H3_CLOSED_CRITICAL_STREAM | 0x0104 | Critical | Section 8.1 | 2350 | | | stream was | | 2351 | | | closed | | 2352 +---------------------------+--------+--------------+---------------+ 2353 | H3_FRAME_UNEXPECTED | 0x0105 | Frame not | Section 8.1 | 2354 | | | permitted | | 2355 | | | in the | | 2356 | | | current | | 2357 | | | state | | 2358 +---------------------------+--------+--------------+---------------+ 2359 | H3_FRAME_ERROR | 0x0106 | Frame | Section 8.1 | 2360 | | | violated | | 2361 | | | layout or | | 2362 | | | size rules | | 2363 +---------------------------+--------+--------------+---------------+ 2364 | H3_EXCESSIVE_LOAD | 0x0107 | Peer | Section 8.1 | 2365 | | | generating | | 2366 | | | excessive | | 2367 | | | load | | 2368 +---------------------------+--------+--------------+---------------+ 2369 | H3_ID_ERROR | 0x0108 | An | Section 8.1 | 2370 | | | identifier | | 2371 | | | was used | | 2372 | | | incorrectly | | 2373 +---------------------------+--------+--------------+---------------+ 2374 | H3_SETTINGS_ERROR | 0x0109 | SETTINGS | Section 8.1 | 2375 | | | frame | | 2376 | | | contained | | 2377 | | | invalid | | 2378 | | | values | | 2379 +---------------------------+--------+--------------+---------------+ 2380 | H3_MISSING_SETTINGS | 0x010a | No SETTINGS | Section 8.1 | 2381 | | | frame | | 2382 | | | received | | 2383 +---------------------------+--------+--------------+---------------+ 2384 | H3_REQUEST_REJECTED | 0x010b | Request not | Section 8.1 | 2385 | | | processed | | 2386 +---------------------------+--------+--------------+---------------+ 2387 | H3_REQUEST_CANCELLED | 0x010c | Data no | Section 8.1 | 2388 | | | longer | | 2389 | | | needed | | 2390 +---------------------------+--------+--------------+---------------+ 2391 | H3_REQUEST_INCOMPLETE | 0x010d | Stream | Section 8.1 | 2392 | | | terminated | | 2393 | | | early | | 2394 +---------------------------+--------+--------------+---------------+ 2395 | H3_CONNECT_ERROR | 0x010f | TCP reset | Section 8.1 | 2396 | | | or error on | | 2397 | | | CONNECT | | 2398 | | | request | | 2399 +---------------------------+--------+--------------+---------------+ 2400 | H3_VERSION_FALLBACK | 0x0110 | Retry over | Section 8.1 | 2401 | | | HTTP/1.1 | | 2402 +---------------------------+--------+--------------+---------------+ 2404 Table 4: Initial HTTP/3 Error Codes 2406 Additionally, each code of the format "0x1f * N + 0x21" for non- 2407 negative integer values of N (that is, 0x21, 0x40, ..., through 2408 0x3ffffffffffffffe) MUST NOT be assigned by IANA. 2410 11.2.4. Stream Types 2412 This document establishes a registry for HTTP/3 unidirectional stream 2413 types. The "HTTP/3 Stream Type" registry governs a 62-bit space. 2414 This registry follows the QUIC registry policy; see Section 11.2. 2415 Permanent registrations in this registry are assigned using the 2416 Specification Required policy ([RFC8126]), except for values between 2417 0x00 and 0x3f (in hexadecimal; inclusive), which are assigned using 2418 Standards Action or IESG Approval as defined in Section 4.9 and 4.10 2419 of [RFC8126]. 2421 In addition to common fields as described in Section 11.2, permanent 2422 registrations in this registry MUST include the following fields: 2424 Stream Type: A name or label for the stream type. 2426 Sender: Which endpoint on a connection may initiate a stream of this 2427 type. Values are "Client", "Server", or "Both". 2429 Specifications for permanent registrations MUST include a description 2430 of the stream type, including the layout and semantics of the stream 2431 contents. 2433 The entries in the following table are registered by this document. 2435 +================+=======+===============+========+ 2436 | Stream Type | Value | Specification | Sender | 2437 +================+=======+===============+========+ 2438 | Control Stream | 0x00 | Section 6.2.1 | Both | 2439 +----------------+-------+---------------+--------+ 2440 | Push Stream | 0x01 | Section 4.4 | Server | 2441 +----------------+-------+---------------+--------+ 2443 Table 5 2445 Additionally, each code of the format "0x1f * N + 0x21" for non- 2446 negative integer values of N (that is, 0x21, 0x40, ..., through 2447 0x3ffffffffffffffe) MUST NOT be assigned by IANA. 2449 12. References 2451 12.1. Normative References 2453 [ALTSVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP 2454 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 2455 April 2016, . 2457 [CACHING] Fielding, R., Nottingham, M., and J. Reschke, "HTTP 2458 Caching", Work in Progress, Internet-Draft, draft-ietf- 2459 httpbis-cache-11, August 27, 2020, . 2462 [HTTP-REPLAY] 2463 Thomson, M., Nottingham, M., and W. Tarreau, "Using Early 2464 Data in HTTP", RFC 8470, DOI 10.17487/RFC8470, September 2465 2018, . 2467 [QPACK] Krasic, C., Bishop, M., and A. Frindell, Ed., "QPACK: 2468 Header Compression for HTTP over QUIC", Work in Progress, 2469 Internet-Draft, draft-ietf-quic-qpack-17, September 10, 2470 2020, 2471 . 2473 [QUIC-TRANSPORT] 2474 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 2475 Multiplexed and Secure Transport", Work in Progress, 2476 Internet-Draft, draft-ietf-quic-transport-29, September 2477 10, 2020, . 2480 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2481 RFC 793, DOI 10.17487/RFC0793, September 1981, 2482 . 2484 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2485 Requirement Levels", BCP 14, RFC 2119, 2486 DOI 10.17487/RFC2119, March 1997, 2487 . 2489 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2490 Resource Identifier (URI): Generic Syntax", STD 66, 2491 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2492 . 2494 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 2495 Extensions: Extension Definitions", RFC 6066, 2496 DOI 10.17487/RFC6066, January 2011, 2497 . 2499 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2500 Verification of Domain-Based Application Service Identity 2501 within Internet Public Key Infrastructure Using X.509 2502 (PKIX) Certificates in the Context of Transport Layer 2503 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2504 2011, . 2506 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2507 DOI 10.17487/RFC6265, April 2011, 2508 . 2510 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 2511 "Transport Layer Security (TLS) Application-Layer Protocol 2512 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 2513 July 2014, . 2515 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2516 Writing an IANA Considerations Section in RFCs", BCP 26, 2517 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2518 . 2520 [RFC8164] Nottingham, M. and M. Thomson, "Opportunistic Security for 2521 HTTP/2", RFC 8164, DOI 10.17487/RFC8164, May 2017, 2522 . 2524 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2525 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2526 May 2017, . 2528 [SEMANTICS] 2529 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 2530 Semantics", Work in Progress, Internet-Draft, draft-ietf- 2531 httpbis-semantics-11, August 27, 2020, 2532 . 2535 12.2. Informative References 2537 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 2538 CRIME Attack", July 2013, 2539 . 2542 [HPACK] Peon, R. and H. Ruellan, "HPACK: Header Compression for 2543 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 2544 . 2546 [HTTP11] Fielding, R., Nottingham, M., and J. Reschke, "HTTP/1.1 2547 Messaging", Work in Progress, Internet-Draft, draft-ietf- 2548 httpbis-messaging-11, August 27, 2020, 2549 . 2552 [HTTP2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 2553 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 2554 DOI 10.17487/RFC7540, May 2015, 2555 . 2557 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 2558 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 2559 . 2561 [TFO] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 2562 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 2563 . 2565 [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2566 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2567 . 2569 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2570 Resource Identifier (URI): Generic Syntax", STD 66, 2571 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2572 . 2574 Appendix A. Considerations for Transitioning from HTTP/2 2576 HTTP/3 is strongly informed by HTTP/2, and bears many similarities. 2577 This section describes the approach taken to design HTTP/3, points 2578 out important differences from HTTP/2, and describes how to map 2579 HTTP/2 extensions into HTTP/3. 2581 HTTP/3 begins from the premise that similarity to HTTP/2 is 2582 preferable, but not a hard requirement. HTTP/3 departs from HTTP/2 2583 where QUIC differs from TCP, either to take advantage of QUIC 2584 features (like streams) or to accommodate important shortcomings 2585 (such as a lack of total ordering). These differences make HTTP/3 2586 similar to HTTP/2 in key aspects, such as the relationship of 2587 requests and responses to streams. However, the details of the 2588 HTTP/3 design are substantially different from HTTP/2. 2590 These departures are noted in this section. 2592 A.1. Streams 2594 HTTP/3 permits use of a larger number of streams (2^62-1) than 2595 HTTP/2. The same considerations about exhaustion of stream 2596 identifier space apply, though the space is significantly larger such 2597 that it is likely that other limits in QUIC are reached first, such 2598 as the limit on the connection flow control window. 2600 In contrast to HTTP/2, stream concurrency in HTTP/3 is managed by 2601 QUIC. QUIC considers a stream closed when all data has been received 2602 and sent data has been acknowledged by the peer. HTTP/2 considers a 2603 stream closed when the frame containing the END_STREAM bit has been 2604 committed to the transport. As a result, the stream for an 2605 equivalent exchange could remain "active" for a longer period of 2606 time. HTTP/3 servers might choose to permit a larger number of 2607 concurrent client-initiated bidirectional streams to achieve 2608 equivalent concurrency to HTTP/2, depending on the expected usage 2609 patterns. 2611 Due to the presence of other unidirectional stream types, HTTP/3 does 2612 not rely exclusively on the number of concurrent unidirectional 2613 streams to control the number of concurrent in-flight pushes. 2614 Instead, HTTP/3 clients use the MAX_PUSH_ID frame to control the 2615 number of pushes received from an HTTP/3 server. 2617 A.2. HTTP Frame Types 2619 Many framing concepts from HTTP/2 can be elided on QUIC, because the 2620 transport deals with them. Because frames are already on a stream, 2621 they can omit the stream number. Because frames do not block 2622 multiplexing (QUIC's multiplexing occurs below this layer), the 2623 support for variable-maximum-length packets can be removed. Because 2624 stream termination is handled by QUIC, an END_STREAM flag is not 2625 required. This permits the removal of the Flags field from the 2626 generic frame layout. 2628 Frame payloads are largely drawn from [HTTP2]. However, QUIC 2629 includes many features (e.g., flow control) that are also present in 2630 HTTP/2. In these cases, the HTTP mapping does not re-implement them. 2631 As a result, several HTTP/2 frame types are not required in HTTP/3. 2632 Where an HTTP/2-defined frame is no longer used, the frame ID has 2633 been reserved in order to maximize portability between HTTP/2 and 2634 HTTP/3 implementations. However, even equivalent frames between the 2635 two mappings are not identical. 2637 Many of the differences arise from the fact that HTTP/2 provides an 2638 absolute ordering between frames across all streams, while QUIC 2639 provides this guarantee on each stream only. As a result, if a frame 2640 type makes assumptions that frames from different streams will still 2641 be received in the order sent, HTTP/3 will break them. 2643 Some examples of feature adaptations are described below, as well as 2644 general guidance to extension frame implementors converting an HTTP/2 2645 extension to HTTP/3. 2647 A.2.1. Prioritization Differences 2649 HTTP/2 specifies priority assignments in PRIORITY frames and 2650 (optionally) in HEADERS frames. HTTP/3 does not provide a means of 2651 signaling priority. 2653 Note that while there is no explicit signaling for priority, this 2654 does not mean that prioritization is not important for achieving good 2655 performance. 2657 A.2.2. Field Compression Differences 2659 HPACK was designed with the assumption of in-order delivery. A 2660 sequence of encoded field sections must arrive (and be decoded) at an 2661 endpoint in the same order in which they were encoded. This ensures 2662 that the dynamic state at the two endpoints remains in sync. 2664 Because this total ordering is not provided by QUIC, HTTP/3 uses a 2665 modified version of HPACK, called QPACK. QPACK uses a single 2666 unidirectional stream to make all modifications to the dynamic table, 2667 ensuring a total order of updates. All frames that contain encoded 2668 fields merely reference the table state at a given time without 2669 modifying it. 2671 [QPACK] provides additional details. 2673 A.2.3. Flow Control Differences 2675 HTTP/2 specifies a stream flow control mechanism. Although all 2676 HTTP/2 frames are delivered on streams, only the DATA frame payload 2677 is subject to flow control. QUIC provides flow control for stream 2678 data and all HTTP/3 frame types defined in this document are sent on 2679 streams. Therefore, all frame headers and payload are subject to 2680 flow control. 2682 A.2.4. Guidance for New Frame Type Definitions 2684 Frame type definitions in HTTP/3 often use the QUIC variable-length 2685 integer encoding. In particular, Stream IDs use this encoding, which 2686 allows for a larger range of possible values than the encoding used 2687 in HTTP/2. Some frames in HTTP/3 use an identifier rather than a 2688 Stream ID (e.g., Push IDs). Redefinition of the encoding of 2689 extension frame types might be necessary if the encoding includes a 2690 Stream ID. 2692 Because the Flags field is not present in generic HTTP/3 frames, 2693 those frames that depend on the presence of flags need to allocate 2694 space for flags as part of their frame payload. 2696 Other than these issues, frame type HTTP/2 extensions are typically 2697 portable to QUIC simply by replacing Stream 0 in HTTP/2 with a 2698 control stream in HTTP/3. HTTP/3 extensions will not assume 2699 ordering, but would not be harmed by ordering, and would be portable 2700 to HTTP/2 in the same manner. 2702 A.2.5. Mapping Between HTTP/2 and HTTP/3 Frame Types 2704 DATA (0x0): Padding is not defined in HTTP/3 frames. See 2705 Section 7.2.1. 2707 HEADERS (0x1): The PRIORITY region of HEADERS is not defined in 2708 HTTP/3 frames. Padding is not defined in HTTP/3 frames. See 2709 Section 7.2.2. 2711 PRIORITY (0x2): As described in Appendix A.2.1, HTTP/3 does not 2712 provide a means of signaling priority. 2714 RST_STREAM (0x3): RST_STREAM frames do not exist in HTTP/3, since 2715 QUIC provides stream lifecycle management. The same code point is 2716 used for the CANCEL_PUSH frame (Section 7.2.3). 2718 SETTINGS (0x4): SETTINGS frames are sent only at the beginning of 2719 the connection. See Section 7.2.4 and Appendix A.3. 2721 PUSH_PROMISE (0x5): The PUSH_PROMISE frame does not reference a 2722 stream; instead the push stream references the PUSH_PROMISE frame 2723 using a Push ID. See Section 7.2.5. 2725 PING (0x6): PING frames do not exist in HTTP/3, as QUIC provides 2726 equivalent functionality. 2728 GOAWAY (0x7): GOAWAY does not contain an error code. In the client 2729 to server direction, it carries a Push ID instead of a server 2730 initiated stream ID. See Section 7.2.6. 2732 WINDOW_UPDATE (0x8): WINDOW_UPDATE frames do not exist in HTTP/3, 2733 since QUIC provides flow control. 2735 CONTINUATION (0x9): CONTINUATION frames do not exist in HTTP/3; 2736 instead, larger HEADERS/PUSH_PROMISE frames than HTTP/2 are 2737 permitted. 2739 Frame types defined by extensions to HTTP/2 need to be separately 2740 registered for HTTP/3 if still applicable. The IDs of frames defined 2741 in [HTTP2] have been reserved for simplicity. Note that the frame 2742 type space in HTTP/3 is substantially larger (62 bits versus 8 bits), 2743 so many HTTP/3 frame types have no equivalent HTTP/2 code points. 2744 See Section 11.2.1. 2746 A.3. HTTP/2 SETTINGS Parameters 2748 An important difference from HTTP/2 is that settings are sent once, 2749 as the first frame of the control stream, and thereafter cannot 2750 change. This eliminates many corner cases around synchronization of 2751 changes. 2753 Some transport-level options that HTTP/2 specifies via the SETTINGS 2754 frame are superseded by QUIC transport parameters in HTTP/3. The 2755 HTTP-level options that are retained in HTTP/3 have the same value as 2756 in HTTP/2. The superseded settings are reserved, and their receipt 2757 is an error. See Section 7.2.4.1 for discussion of both the retained 2758 and reserved values. 2760 Below is a listing of how each HTTP/2 SETTINGS parameter is mapped: 2762 SETTINGS_HEADER_TABLE_SIZE: See [QPACK]. 2764 SETTINGS_ENABLE_PUSH: This is removed in favor of the MAX_PUSH_ID 2765 frame, which provides a more granular control over server push. 2766 Specifying a setting with the identifier 0x2 (corresponding to the 2767 SETTINGS_ENABLE_PUSH parameter) in the HTTP/3 SETTINGS frame is an 2768 error. 2770 SETTINGS_MAX_CONCURRENT_STREAMS: QUIC controls the largest open 2771 Stream ID as part of its flow control logic. Specifying a setting 2772 with the identifier 0x3 (corresponding to the 2773 SETTINGS_MAX_CONCURRENT_STREAMS parameter) in the HTTP/3 SETTINGS 2774 frame is an error. 2776 SETTINGS_INITIAL_WINDOW_SIZE: QUIC requires both stream and 2777 connection flow control window sizes to be specified in the 2778 initial transport handshake. Specifying a setting with the 2779 identifier 0x4 (corresponding to the SETTINGS_INITIAL_WINDOW_SIZE 2780 parameter) in the HTTP/3 SETTINGS frame is an error. 2782 SETTINGS_MAX_FRAME_SIZE: This setting has no equivalent in HTTP/3. 2783 Specifying a setting with the identifier 0x5 (corresponding to the 2784 SETTINGS_MAX_FRAME_SIZE parameter) in the HTTP/3 SETTINGS frame is 2785 an error. 2787 SETTINGS_MAX_HEADER_LIST_SIZE: This setting identifier has been 2788 renamed SETTINGS_MAX_FIELD_SECTION_SIZE. 2790 In HTTP/3, setting values are variable-length integers (6, 14, 30, or 2791 62 bits long) rather than fixed-length 32-bit fields as in HTTP/2. 2792 This will often produce a shorter encoding, but can produce a longer 2793 encoding for settings that use the full 32-bit space. Settings 2794 ported from HTTP/2 might choose to redefine their value to limit it 2795 to 30 bits for more efficient encoding, or to make use of the 62-bit 2796 space if more than 30 bits are required. 2798 Settings need to be defined separately for HTTP/2 and HTTP/3. The 2799 IDs of settings defined in [HTTP2] have been reserved for simplicity. 2800 Note that the settings identifier space in HTTP/3 is substantially 2801 larger (62 bits versus 16 bits), so many HTTP/3 settings have no 2802 equivalent HTTP/2 code point. See Section 11.2.2. 2804 As QUIC streams might arrive out of order, endpoints are advised not 2805 to wait for the peers' settings to arrive before responding to other 2806 streams. See Section 7.2.4.2. 2808 A.4. HTTP/2 Error Codes 2810 QUIC has the same concepts of "stream" and "connection" errors that 2811 HTTP/2 provides. However, the differences between HTTP/2 and HTTP/3 2812 mean that error codes are not directly portable between versions. 2814 The HTTP/2 error codes defined in Section 7 of [HTTP2] logically map 2815 to the HTTP/3 error codes as follows: 2817 NO_ERROR (0x0): H3_NO_ERROR in Section 8.1. 2819 PROTOCOL_ERROR (0x1): This is mapped to H3_GENERAL_PROTOCOL_ERROR 2820 except in cases where more specific error codes have been defined. 2821 Such cases include H3_FRAME_UNEXPECTED and 2822 H3_CLOSED_CRITICAL_STREAM defined in Section 8.1. 2824 INTERNAL_ERROR (0x2): H3_INTERNAL_ERROR in Section 8.1. 2826 FLOW_CONTROL_ERROR (0x3): Not applicable, since QUIC handles flow 2827 control. 2829 SETTINGS_TIMEOUT (0x4): Not applicable, since no acknowledgement of 2830 SETTINGS is defined. 2832 STREAM_CLOSED (0x5): Not applicable, since QUIC handles stream 2833 management. 2835 FRAME_SIZE_ERROR (0x6): H3_FRAME_ERROR error code defined in 2836 Section 8.1. 2838 REFUSED_STREAM (0x7): H3_REQUEST_REJECTED (in Section 8.1) is used 2839 to indicate that a request was not processed. Otherwise, not 2840 applicable because QUIC handles stream management. 2842 CANCEL (0x8): H3_REQUEST_CANCELLED in Section 8.1. 2844 COMPRESSION_ERROR (0x9): Multiple error codes are defined in 2845 [QPACK]. 2847 CONNECT_ERROR (0xa): H3_CONNECT_ERROR in Section 8.1. 2849 ENHANCE_YOUR_CALM (0xb): H3_EXCESSIVE_LOAD in Section 8.1. 2851 INADEQUATE_SECURITY (0xc): Not applicable, since QUIC is assumed to 2852 provide sufficient security on all connections. 2854 HTTP_1_1_REQUIRED (0xd): H3_VERSION_FALLBACK in Section 8.1. 2856 Error codes need to be defined for HTTP/2 and HTTP/3 separately. See 2857 Section 11.2.3. 2859 A.4.1. Mapping Between HTTP/2 and HTTP/3 Errors 2861 An intermediary that converts between HTTP/2 and HTTP/3 may encounter 2862 error conditions from either upstream. It is useful to communicate 2863 the occurrence of error to the downstream but error codes largely 2864 reflect connection-local problems that generally do not make sense to 2865 propagate. 2867 An intermediary that encounters an error from an upstream origin can 2868 indicate this by sending an HTTP status code such as 502, which is 2869 suitable for a broad class of errors. 2871 There are some rare cases where it is beneficial to propagate the 2872 error by mapping it to the closest matching error type to the 2873 receiver. For example, an intermediary that receives an HTTP/2 2874 stream error of type REFUSED_STREAM from the origin has a clear 2875 signal that the request was not processed and that the request is 2876 safe to retry. Propagating this error condition to the client as an 2877 HTTP/3 stream error of type H3_REQUEST_REJECTED allows the client to 2878 take the action it deems most appropriate. In the reverse direction, 2879 the intermediary might deem it beneficial to pass on client request 2880 cancellations that are indicated by terminating a stream with 2881 H3_REQUEST_CANCELLED; see Section 4.1.2. 2883 Conversion between errors is described in the logical mapping. The 2884 error codes are defined in non-overlapping spaces in order to protect 2885 against accidental conversion that could result in the use of 2886 inappropriate or unknown error codes for the target version. An 2887 intermediary is permitted to promote stream errors to connection 2888 errors but they should be aware of the cost to the connection for 2889 what might be a temporary or intermittent error. 2891 Appendix B. Change Log 2893 *RFC Editor's Note:* Please remove this section prior to 2894 publication of a final version of this document. 2896 B.1. Since draft-ietf-quic-http-29 2898 * Require a connection error if a reserved frame type that 2899 corresponds to a frame in HTTP/2 is received (#3991, #3993) 2901 * Require a connection error if a reserved setting that corresponds 2902 to a setting in HTTP/2 is received (#3954, #3955) 2904 B.2. Since draft-ietf-quic-http-28 2906 * CANCEL_PUSH is recommended even when the stream is reset (#3698, 2907 #3700) 2909 * Use H3_ID_ERROR when GOAWAY contains a larger identifier (#3631, 2910 #3634) 2912 B.3. Since draft-ietf-quic-http-27 2914 * Updated text to refer to latest HTTP revisions 2916 * Use the HTTP definition of authority for establishing and 2917 coalescing connections (#253, #2223, #3558) 2919 * Define use of GOAWAY from both endpoints (#2632, #3129) 2921 * Require either :authority or Host if the URI scheme has a 2922 mandatory authority component (#3408, #3475) 2924 B.4. Since draft-ietf-quic-http-26 2926 * No changes 2928 B.5. Since draft-ietf-quic-http-25 2930 * Require QUICv1 for HTTP/3 (#3117, #3323) 2932 * Remove DUPLICATE_PUSH and allow duplicate PUSH_PROMISE (#3275, 2933 #3309) 2935 * Clarify the definition of "malformed" (#3352, #3345) 2937 B.6. Since draft-ietf-quic-http-24 2939 * Removed H3_EARLY_RESPONSE error code; H3_NO_ERROR is recommended 2940 instead (#3130,#3208) 2942 * Unknown error codes are equivalent to H3_NO_ERROR (#3276,#3331) 2944 * Some error codes are reserved for greasing (#3325,#3360) 2946 B.7. Since draft-ietf-quic-http-23 2948 * Removed "quic" Alt-Svc parameter (#3061,#3118) 2950 * Clients need not persist unknown settings for use in 0-RTT 2951 (#3110,#3113) 2953 * Clarify error cases around CANCEL_PUSH (#2819,#3083) 2955 B.8. Since draft-ietf-quic-http-22 2957 * Removed priority signaling (#2922,#2924) 2959 * Further changes to error codes (#2662,#2551): 2961 - Error codes renumbered 2963 - HTTP_MALFORMED_FRAME replaced by HTTP_FRAME_ERROR, 2964 HTTP_ID_ERROR, and others 2966 * Clarify how unknown frame types interact with required frame 2967 sequence (#2867,#2858) 2969 * Describe interactions with the transport in terms of defined 2970 interface terms (#2857,#2805) 2972 * Require the use of the "http-opportunistic" resource (RFC 8164) 2973 when scheme is "http" (#2439,#2973) 2975 * Settings identifiers cannot be duplicated (#2979) 2976 * Changes to SETTINGS frames in 0-RTT (#2972,#2790,#2945): 2978 - Servers must send all settings with non-default values in their 2979 SETTINGS frame, even when resuming 2981 - If a client doesn't have settings associated with a 0-RTT 2982 ticket, it uses the defaults 2984 - Servers can't accept early data if they cannot recover the 2985 settings the client will have remembered 2987 * Clarify that Upgrade and the 101 status code are prohibited 2988 (#2898,#2889) 2990 * Clarify that frame types reserved for greasing can occur on any 2991 stream, but frame types reserved due to HTTP/2 correspondence are 2992 prohibited (#2997,#2692,#2693) 2994 * Unknown error codes cannot be treated as errors (#2998,#2816) 2996 B.9. Since draft-ietf-quic-http-21 2998 No changes 3000 B.10. Since draft-ietf-quic-http-20 3002 * Prohibit closing the control stream (#2509, #2666) 3004 * Change default priority to use an orphan node (#2502, #2690) 3006 * Exclusive priorities are restored (#2754, #2781) 3008 * Restrict use of frames when using CONNECT (#2229, #2702) 3010 * Close and maybe reset streams if a connection error occurs for 3011 CONNECT (#2228, #2703) 3013 * Encourage provision of sufficient unidirectional streams for QPACK 3014 (#2100, #2529, #2762) 3016 * Allow extensions to use server-initiated bidirectional streams 3017 (#2711, #2773) 3019 * Clarify use of maximum header list size setting (#2516, #2774) 3021 * Extensive changes to error codes and conditions of their sending 3022 - Require connection errors for more error conditions (#2511, 3023 #2510) 3025 - Updated the error codes for illegal GOAWAY frames (#2714, 3026 #2707) 3028 - Specified error code for HEADERS on control stream (#2708) 3030 - Specified error code for servers receiving PUSH_PROMISE (#2709) 3032 - Specified error code for receiving DATA before HEADERS (#2715) 3034 - Describe malformed messages and their handling (#2410, #2764) 3036 - Remove HTTP_PUSH_ALREADY_IN_CACHE error (#2812, #2813) 3038 - Refactor Push ID related errors (#2818, #2820) 3040 - Rationalize HTTP/3 stream creation errors (#2821, #2822) 3042 B.11. Since draft-ietf-quic-http-19 3044 * SETTINGS_NUM_PLACEHOLDERS is 0x9 (#2443,#2530) 3046 * Non-zero bits in the Empty field of the PRIORITY frame MAY be 3047 treated as an error (#2501) 3049 B.12. Since draft-ietf-quic-http-18 3051 * Resetting streams following a GOAWAY is recommended, but not 3052 required (#2256,#2457) 3054 * Use variable-length integers throughout (#2437,#2233,#2253,#2275) 3056 - Variable-length frame types, stream types, and settings 3057 identifiers 3059 - Renumbered stream type assignments 3061 - Modified associated reserved values 3063 * Frame layout switched from Length-Type-Value to Type-Length-Value 3064 (#2395,#2235) 3066 * Specified error code for servers receiving DUPLICATE_PUSH (#2497) 3068 * Use connection error for invalid PRIORITY (#2507, #2508) 3070 B.13. Since draft-ietf-quic-http-17 3072 * HTTP_REQUEST_REJECTED is used to indicate a request can be retried 3073 (#2106, #2325) 3075 * Changed error code for GOAWAY on the wrong stream (#2231, #2343) 3077 B.14. Since draft-ietf-quic-http-16 3079 * Rename "HTTP/QUIC" to "HTTP/3" (#1973) 3081 * Changes to PRIORITY frame (#1865, #2075) 3083 - Permitted as first frame of request streams 3085 - Remove exclusive reprioritization 3087 - Changes to Prioritized Element Type bits 3089 * Define DUPLICATE_PUSH frame to refer to another PUSH_PROMISE 3090 (#2072) 3092 * Set defaults for settings, allow request before receiving SETTINGS 3093 (#1809, #1846, #2038) 3095 * Clarify message processing rules for streams that aren't closed 3096 (#1972, #2003) 3098 * Removed reservation of error code 0 and moved HTTP_NO_ERROR to 3099 this value (#1922) 3101 * Removed prohibition of zero-length DATA frames (#2098) 3103 B.15. Since draft-ietf-quic-http-15 3105 Substantial editorial reorganization; no technical changes. 3107 B.16. Since draft-ietf-quic-http-14 3109 * Recommend sensible values for QUIC transport parameters 3110 (#1720,#1806) 3112 * Define error for missing SETTINGS frame (#1697,#1808) 3114 * Setting values are variable-length integers (#1556,#1807) and do 3115 not have separate maximum values (#1820) 3117 * Expanded discussion of connection closure (#1599,#1717,#1712) 3118 * HTTP_VERSION_FALLBACK falls back to HTTP/1.1 (#1677,#1685) 3120 B.17. Since draft-ietf-quic-http-13 3122 * Reserved some frame types for grease (#1333, #1446) 3124 * Unknown unidirectional stream types are tolerated, not errors; 3125 some reserved for grease (#1490, #1525) 3127 * Require settings to be remembered for 0-RTT, prohibit reductions 3128 (#1541, #1641) 3130 * Specify behavior for truncated requests (#1596, #1643) 3132 B.18. Since draft-ietf-quic-http-12 3134 * TLS SNI extension isn't mandatory if an alternative method is used 3135 (#1459, #1462, #1466) 3137 * Removed flags from HTTP/3 frames (#1388, #1398) 3139 * Reserved frame types and settings for use in preserving 3140 extensibility (#1333, #1446) 3142 * Added general error code (#1391, #1397) 3144 * Unidirectional streams carry a type byte and are extensible 3145 (#910,#1359) 3147 * Priority mechanism now uses explicit placeholders to enable 3148 persistent structure in the tree (#441,#1421,#1422) 3150 B.19. Since draft-ietf-quic-http-11 3152 * Moved QPACK table updates and acknowledgments to dedicated streams 3153 (#1121, #1122, #1238) 3155 B.20. Since draft-ietf-quic-http-10 3157 * Settings need to be remembered when attempting and accepting 0-RTT 3158 (#1157, #1207) 3160 B.21. Since draft-ietf-quic-http-09 3162 * Selected QCRAM for header compression (#228, #1117) 3164 * The server_name TLS extension is now mandatory (#296, #495) 3165 * Specified handling of unsupported versions in Alt-Svc (#1093, 3166 #1097) 3168 B.22. Since draft-ietf-quic-http-08 3170 * Clarified connection coalescing rules (#940, #1024) 3172 B.23. Since draft-ietf-quic-http-07 3174 * Changes for integer encodings in QUIC (#595,#905) 3176 * Use unidirectional streams as appropriate (#515, #240, #281, #886) 3178 * Improvement to the description of GOAWAY (#604, #898) 3180 * Improve description of server push usage (#947, #950, #957) 3182 B.24. Since draft-ietf-quic-http-06 3184 * Track changes in QUIC error code usage (#485) 3186 B.25. Since draft-ietf-quic-http-05 3188 * Made push ID sequential, add MAX_PUSH_ID, remove 3189 SETTINGS_ENABLE_PUSH (#709) 3191 * Guidance about keep-alive and QUIC PINGs (#729) 3193 * Expanded text on GOAWAY and cancellation (#757) 3195 B.26. Since draft-ietf-quic-http-04 3197 * Cite RFC 5234 (#404) 3199 * Return to a single stream per request (#245,#557) 3201 * Use separate frame type and settings registries from HTTP/2 (#81) 3203 * SETTINGS_ENABLE_PUSH instead of SETTINGS_DISABLE_PUSH (#477) 3205 * Restored GOAWAY (#696) 3207 * Identify server push using Push ID rather than a stream ID 3208 (#702,#281) 3210 * DATA frames cannot be empty (#700) 3212 B.27. Since draft-ietf-quic-http-03 3214 None. 3216 B.28. Since draft-ietf-quic-http-02 3218 * Track changes in transport draft 3220 B.29. Since draft-ietf-quic-http-01 3222 * SETTINGS changes (#181): 3224 - SETTINGS can be sent only once at the start of a connection; no 3225 changes thereafter 3227 - SETTINGS_ACK removed 3229 - Settings can only occur in the SETTINGS frame a single time 3231 - Boolean format updated 3233 * Alt-Svc parameter changed from "v" to "quic"; format updated 3234 (#229) 3236 * Closing the connection control stream or any message control 3237 stream is a fatal error (#176) 3239 * HPACK Sequence counter can wrap (#173) 3241 * 0-RTT guidance added 3243 * Guide to differences from HTTP/2 and porting HTTP/2 extensions 3244 added (#127,#242) 3246 B.30. Since draft-ietf-quic-http-00 3248 * Changed "HTTP/2-over-QUIC" to "HTTP/QUIC" throughout (#11,#29) 3250 * Changed from using HTTP/2 framing within Stream 3 to new framing 3251 format and two-stream-per-request model (#71,#72,#73) 3253 * Adopted SETTINGS format from draft-bishop-httpbis-extended- 3254 settings-01 3256 * Reworked SETTINGS_ACK to account for indeterminate inter-stream 3257 order (#75) 3259 * Described CONNECT pseudo-method (#95) 3260 * Updated ALPN token and Alt-Svc guidance (#13,#87) 3262 * Application-layer-defined error codes (#19,#74) 3264 B.31. Since draft-shade-quic-http2-mapping-00 3266 * Adopted as base for draft-ietf-quic-http 3268 * Updated authors/editors list 3270 Acknowledgements 3272 The original authors of this specification were Robbie Shade and Mike 3273 Warres. 3275 The IETF QUIC Working Group received an enormous amount of support 3276 from many people. Among others, the following people provided 3277 substantial contributions to this document: 3279 * Bence Beky 3281 * Daan De Meyer 3283 * Martin Duke 3285 * Roy Fielding 3287 * Alan Frindell 3289 * Alessandro Ghedini 3291 * Nick Harper 3293 * Ryan Hamilton 3295 * Christian Huitema 3297 * Subodh Iyengar 3299 * Robin Marx 3301 * Patrick McManus 3303 * Luca Nicco 3305 * 奥 一穂 (Kazuho Oku) 3307 * Lucas Pardue 3308 * Roberto Peon 3310 * Julian Reschke 3312 * Eric Rescorla 3314 * Martin Seemann 3316 * Ben Schwartz 3318 * Ian Swett 3320 * Willy Taureau 3322 * Martin Thomson 3324 * Dmitri Tikhonov 3326 * Tatsuhiro Tsujikawa 3328 A portion of Mike's contribution was supported by Microsoft during 3329 his employment there. 3331 Author's Address 3333 Mike Bishop (editor) 3334 Akamai 3336 Email: mbishop@evequefou.be