idnits 2.17.1 draft-ietf-quic-http-29.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 (9 June 2020) is 1417 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-08 -- Possible downref: Normative reference to a draft: ref. 'CACHING' == Outdated reference: A later version (-21) exists of draft-ietf-quic-qpack-16 == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-28 ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Downref: Normative reference to an Historic RFC: RFC 8164 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-08 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-08 -- Obsolete informational reference (is this intentional?): RFC 7540 (ref. 'HTTP2') (Obsoleted by RFC 9113) -- Duplicate reference: RFC3986, mentioned in 'URI', was also mentioned in 'RFC3986'. Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 6 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 9 June 2020 5 Expires: 11 December 2020 7 Hypertext Transfer Protocol Version 3 (HTTP/3) 8 draft-ietf-quic-http-29 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 (mailto:quic@ietf.org)), which is 23 archived at https://mailarchive.ietf.org/arch/ 24 search/?email_list=quic. 26 Working Group information can be found at https://github.com/quicwg; 27 source code and issues list for this draft can be found at 28 https://github.com/quicwg/base-drafts/labels/-http. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on 11 December 2020. 47 Copyright Notice 49 Copyright (c) 2020 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 54 license-info) in effect on the date of publication of this document. 55 Please review these documents carefully, as they describe your rights 56 and restrictions with respect to this document. Code Components 57 extracted from this document must include Simplified BSD License text 58 as described in Section 4.e of the Trust Legal Provisions and are 59 provided without warranty as described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 64 1.1. Prior versions of HTTP . . . . . . . . . . . . . . . . . 5 65 1.2. Delegation to QUIC . . . . . . . . . . . . . . . . . . . 5 66 2. HTTP/3 Protocol Overview . . . . . . . . . . . . . . . . . . 5 67 2.1. Document Organization . . . . . . . . . . . . . . . . . . 6 68 2.2. Conventions and Terminology . . . . . . . . . . . . . . . 7 69 3. Connection Setup and Management . . . . . . . . . . . . . . . 8 70 3.1. Draft Version Identification . . . . . . . . . . . . . . 8 71 3.2. Discovering an HTTP/3 Endpoint . . . . . . . . . . . . . 9 72 3.2.1. HTTP Alternative Services . . . . . . . . . . . . . . 10 73 3.2.2. Other Schemes . . . . . . . . . . . . . . . . . . . . 10 74 3.3. Connection Establishment . . . . . . . . . . . . . . . . 10 75 3.4. Connection Reuse . . . . . . . . . . . . . . . . . . . . 11 76 4. HTTP Request Lifecycle . . . . . . . . . . . . . . . . . . . 12 77 4.1. HTTP Message Exchanges . . . . . . . . . . . . . . . . . 12 78 4.1.1. Field Formatting and Compression . . . . . . . . . . 14 79 4.1.2. Request Cancellation and Rejection . . . . . . . . . 17 80 4.1.3. Malformed Requests and Responses . . . . . . . . . . 18 81 4.2. The CONNECT Method . . . . . . . . . . . . . . . . . . . 19 82 4.3. HTTP Upgrade . . . . . . . . . . . . . . . . . . . . . . 20 83 4.4. Server Push . . . . . . . . . . . . . . . . . . . . . . . 21 84 5. Connection Closure . . . . . . . . . . . . . . . . . . . . . 23 85 5.1. Idle Connections . . . . . . . . . . . . . . . . . . . . 23 86 5.2. Connection Shutdown . . . . . . . . . . . . . . . . . . . 23 87 5.3. Immediate Application Closure . . . . . . . . . . . . . . 25 88 5.4. Transport Closure . . . . . . . . . . . . . . . . . . . . 26 89 6. Stream Mapping and Usage . . . . . . . . . . . . . . . . . . 26 90 6.1. Bidirectional Streams . . . . . . . . . . . . . . . . . . 26 91 6.2. Unidirectional Streams . . . . . . . . . . . . . . . . . 27 92 6.2.1. Control Streams . . . . . . . . . . . . . . . . . . . 28 93 6.2.2. Push Streams . . . . . . . . . . . . . . . . . . . . 29 94 6.2.3. Reserved Stream Types . . . . . . . . . . . . . . . . 29 96 7. HTTP Framing Layer . . . . . . . . . . . . . . . . . . . . . 30 97 7.1. Frame Layout . . . . . . . . . . . . . . . . . . . . . . 31 98 7.2. Frame Definitions . . . . . . . . . . . . . . . . . . . . 31 99 7.2.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . 31 100 7.2.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . 32 101 7.2.3. CANCEL_PUSH . . . . . . . . . . . . . . . . . . . . . 32 102 7.2.4. SETTINGS . . . . . . . . . . . . . . . . . . . . . . 33 103 7.2.5. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . 36 104 7.2.6. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . 38 105 7.2.7. MAX_PUSH_ID . . . . . . . . . . . . . . . . . . . . . 38 106 7.2.8. Reserved Frame Types . . . . . . . . . . . . . . . . 39 107 8. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 39 108 8.1. HTTP/3 Error Codes . . . . . . . . . . . . . . . . . . . 40 109 9. Extensions to HTTP/3 . . . . . . . . . . . . . . . . . . . . 41 110 10. Security Considerations . . . . . . . . . . . . . . . . . . . 42 111 10.1. Server Authority . . . . . . . . . . . . . . . . . . . . 42 112 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 42 113 10.3. Intermediary Encapsulation Attacks . . . . . . . . . . . 43 114 10.4. Cacheability of Pushed Responses . . . . . . . . . . . . 43 115 10.5. Denial-of-Service Considerations . . . . . . . . . . . . 43 116 10.5.1. Limits on Field Section Size . . . . . . . . . . . . 44 117 10.5.2. CONNECT Issues . . . . . . . . . . . . . . . . . . . 45 118 10.6. Use of Compression . . . . . . . . . . . . . . . . . . . 45 119 10.7. Padding and Traffic Analysis . . . . . . . . . . . . . . 46 120 10.8. Frame Parsing . . . . . . . . . . . . . . . . . . . . . 46 121 10.9. Early Data . . . . . . . . . . . . . . . . . . . . . . . 46 122 10.10. Migration . . . . . . . . . . . . . . . . . . . . . . . 47 123 10.11. Privacy Considerations . . . . . . . . . . . . . . . . . 47 124 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 125 11.1. Registration of HTTP/3 Identification String . . . . . . 47 126 11.2. New Registries . . . . . . . . . . . . . . . . . . . . . 48 127 11.2.1. Frame Types . . . . . . . . . . . . . . . . . . . . 48 128 11.2.2. Settings Parameters . . . . . . . . . . . . . . . . 49 129 11.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . 50 130 11.2.4. Stream Types . . . . . . . . . . . . . . . . . . . . 53 131 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 132 12.1. Normative References . . . . . . . . . . . . . . . . . . 53 133 12.2. Informative References . . . . . . . . . . . . . . . . . 55 134 Appendix A. Considerations for Transitioning from HTTP/2 . . . . 56 135 A.1. Streams . . . . . . . . . . . . . . . . . . . . . . . . . 57 136 A.2. HTTP Frame Types . . . . . . . . . . . . . . . . . . . . 57 137 A.2.1. Prioritization Differences . . . . . . . . . . . . . 58 138 A.2.2. Field Compression Differences . . . . . . . . . . . . 58 139 A.2.3. Guidance for New Frame Type Definitions . . . . . . . 58 140 A.2.4. 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 145 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 62 146 B.1. Since draft-ietf-quic-http-28 . . . . . . . . . . . . . . 63 147 B.2. Since draft-ietf-quic-http-27 . . . . . . . . . . . . . . 63 148 B.3. Since draft-ietf-quic-http-26 . . . . . . . . . . . . . . 63 149 B.4. Since draft-ietf-quic-http-25 . . . . . . . . . . . . . . 63 150 B.5. Since draft-ietf-quic-http-24 . . . . . . . . . . . . . . 63 151 B.6. Since draft-ietf-quic-http-23 . . . . . . . . . . . . . . 63 152 B.7. Since draft-ietf-quic-http-22 . . . . . . . . . . . . . . 64 153 B.8. Since draft-ietf-quic-http-21 . . . . . . . . . . . . . . 64 154 B.9. Since draft-ietf-quic-http-20 . . . . . . . . . . . . . . 65 155 B.10. Since draft-ietf-quic-http-19 . . . . . . . . . . . . . . 65 156 B.11. Since draft-ietf-quic-http-18 . . . . . . . . . . . . . . 66 157 B.12. Since draft-ietf-quic-http-17 . . . . . . . . . . . . . . 66 158 B.13. Since draft-ietf-quic-http-16 . . . . . . . . . . . . . . 66 159 B.14. Since draft-ietf-quic-http-15 . . . . . . . . . . . . . . 67 160 B.15. Since draft-ietf-quic-http-14 . . . . . . . . . . . . . . 67 161 B.16. Since draft-ietf-quic-http-13 . . . . . . . . . . . . . . 67 162 B.17. Since draft-ietf-quic-http-12 . . . . . . . . . . . . . . 67 163 B.18. Since draft-ietf-quic-http-11 . . . . . . . . . . . . . . 68 164 B.19. Since draft-ietf-quic-http-10 . . . . . . . . . . . . . . 68 165 B.20. Since draft-ietf-quic-http-09 . . . . . . . . . . . . . . 68 166 B.21. Since draft-ietf-quic-http-08 . . . . . . . . . . . . . . 68 167 B.22. Since draft-ietf-quic-http-07 . . . . . . . . . . . . . . 68 168 B.23. Since draft-ietf-quic-http-06 . . . . . . . . . . . . . . 68 169 B.24. Since draft-ietf-quic-http-05 . . . . . . . . . . . . . . 68 170 B.25. Since draft-ietf-quic-http-04 . . . . . . . . . . . . . . 69 171 B.26. Since draft-ietf-quic-http-03 . . . . . . . . . . . . . . 69 172 B.27. Since draft-ietf-quic-http-02 . . . . . . . . . . . . . . 69 173 B.28. Since draft-ietf-quic-http-01 . . . . . . . . . . . . . . 69 174 B.29. Since draft-ietf-quic-http-00 . . . . . . . . . . . . . . 70 175 B.30. Since draft-shade-quic-http2-mapping-00 . . . . . . . . . 70 176 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 70 177 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 72 179 1. Introduction 181 HTTP semantics [SEMANTICS] are used for a broad range of services on 182 the Internet. These semantics have most commonly been used with two 183 different TCP mappings, HTTP/1.1 and HTTP/2. HTTP/3 supports the 184 same semantics over a new transport protocol, QUIC. 186 1.1. Prior versions of HTTP 188 HTTP/1.1 [HTTP11] is a TCP mapping which uses whitespace-delimited 189 text fields to convey HTTP messages. While these exchanges are 190 human-readable, using whitespace for message formatting leads to 191 parsing complexity and motivates tolerance of variant behavior. 192 Because each connection can transfer only a single HTTP request or 193 response at a time in each direction, multiple parallel TCP 194 connections are often used, reducing the ability of the congestion 195 controller to effectively manage traffic between endpoints. 197 HTTP/2 [HTTP2] introduced a binary framing and multiplexing layer to 198 improve latency without modifying the transport layer. However, 199 because the parallel nature of HTTP/2's multiplexing is not visible 200 to TCP's loss recovery mechanisms, a lost or reordered packet causes 201 all active transactions to experience a stall regardless of whether 202 that transaction was directly impacted by the lost packet. 204 1.2. Delegation to QUIC 206 The QUIC transport protocol incorporates stream multiplexing and per- 207 stream flow control, similar to that provided by the HTTP/2 framing 208 layer. By providing reliability at the stream level and congestion 209 control across the entire connection, it has the capability to 210 improve the performance of HTTP compared to a TCP mapping. QUIC also 211 incorporates TLS 1.3 [TLS13] at the transport layer, offering 212 comparable security to running TLS over TCP, with the improved 213 connection setup latency of TCP Fast Open [TFO]. 215 This document defines a mapping of HTTP semantics over the QUIC 216 transport protocol, drawing heavily on the design of HTTP/2. While 217 delegating stream lifetime and flow control issues to QUIC, a similar 218 binary framing is used on each stream. Some HTTP/2 features are 219 subsumed by QUIC, while other features are implemented atop QUIC. 221 QUIC is described in [QUIC-TRANSPORT]. For a full description of 222 HTTP/2, see [HTTP2]. 224 2. HTTP/3 Protocol Overview 226 HTTP/3 provides a transport for HTTP semantics using the QUIC 227 transport protocol and an internal framing layer similar to HTTP/2. 229 Once a client knows that an HTTP/3 server exists at a certain 230 endpoint, it opens a QUIC connection. QUIC provides protocol 231 negotiation, stream-based multiplexing, and flow control. Discovery 232 of an HTTP/3 endpoint is described in Section 3.2. 234 Within each stream, the basic unit of HTTP/3 communication is a frame 235 (Section 7.2). Each frame type serves a different purpose. For 236 example, HEADERS and DATA frames form the basis of HTTP requests and 237 responses (Section 4.1). 239 Multiplexing of requests is performed using the QUIC stream 240 abstraction, described in Section 2 of [QUIC-TRANSPORT]. Each 241 request-response pair consumes a single QUIC stream. Streams are 242 independent of each other, so one stream that is blocked or suffers 243 packet loss does not prevent progress on other streams. 245 Server push is an interaction mode introduced in HTTP/2 [HTTP2] which 246 permits a server to push a request-response exchange to a client in 247 anticipation of the client making the indicated request. This trades 248 off network usage against a potential latency gain. Several HTTP/3 249 frames are used to manage server push, such as PUSH_PROMISE, 250 MAX_PUSH_ID, and CANCEL_PUSH. 252 As in HTTP/2, request and response fields are compressed for 253 transmission. Because HPACK [HPACK] relies on in-order transmission 254 of compressed field sections (a guarantee not provided by QUIC), 255 HTTP/3 replaces HPACK with QPACK [QPACK]. QPACK uses separate 256 unidirectional streams to modify and track field table state, while 257 encoded field sections refer to the state of the table without 258 modifying it. 260 2.1. Document Organization 262 The following sections provide a detailed overview of the connection 263 lifecycle and key concepts: 265 * Connection Setup and Management (Section 3) covers how an HTTP/3 266 endpoint is discovered and a connection is established. 268 * HTTP Request Lifecycle (Section 4) describes how HTTP semantics 269 are expressed using frames. 271 * Connection Closure (Section 5) describes how connections are 272 terminated, either gracefully or abruptly. 274 The details of the wire protocol and interactions with the transport 275 are described in subsequent sections: 277 * Stream Mapping and Usage (Section 6) describes the way QUIC 278 streams are used. 280 * HTTP Framing Layer (Section 7) describes the frames used on most 281 streams. 283 * Error Handling (Section 8) describes how error conditions are 284 handled and expressed, either on a particular stream or for the 285 connection as a whole. 287 Additional resources are provided in the final sections: 289 * Extensions to HTTP/3 (Section 9) describes how new capabilities 290 can be added in future documents. 292 * A more detailed comparison between HTTP/2 and HTTP/3 can be found 293 in Appendix A. 295 2.2. Conventions and Terminology 297 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 298 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 299 "OPTIONAL" in this document are to be interpreted as described in 300 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 301 capitals, as shown here. 303 Field definitions are given in Augmented Backus-Naur Form (ABNF), as 304 defined in [RFC5234]. 306 This document uses the variable-length integer encoding from 307 [QUIC-TRANSPORT]. 309 The following terms are used: 311 abort: An abrupt termination of a connection or stream, possibly due 312 to an error condition. 314 client: The endpoint that initiates an HTTP/3 connection. Clients 315 send HTTP requests and receive HTTP responses. 317 connection: A transport-layer connection between two endpoints, 318 using QUIC as the transport protocol. 320 connection error: An error that affects the entire HTTP/3 321 connection. 323 endpoint: Either the client or server of the connection. 325 frame: The smallest unit of communication on a stream in HTTP/3, 326 consisting of a header and a variable-length sequence of bytes 327 structured according to the frame type. Protocol elements called 328 "frames" exist in both this document and [QUIC-TRANSPORT]. Where 329 frames from [QUIC-TRANSPORT] are referenced, the frame name will 330 be prefaced with "QUIC." For example, "QUIC CONNECTION_CLOSE 331 frames." References without this preface refer to frames defined 332 in Section 7.2. 334 peer: An endpoint. When discussing a particular endpoint, "peer" 335 refers to the endpoint that is remote to the primary subject of 336 discussion. 338 receiver: An endpoint that is receiving frames. 340 sender: An endpoint that is transmitting frames. 342 server: The endpoint that accepts an HTTP/3 connection. Servers 343 receive HTTP requests and send HTTP responses. 345 stream: A bidirectional or unidirectional bytestream provided by the 346 QUIC transport. 348 stream error: An error on the individual HTTP/3 stream. 350 The term "payload body" is defined in Section 6.3.3 of [SEMANTICS]. 352 Finally, the terms "gateway", "intermediary", "proxy", and "tunnel" 353 are defined in Section 2.2 of [SEMANTICS]. Intermediaries act as 354 both client and server at different times. 356 3. Connection Setup and Management 358 3.1. Draft Version Identification 360 *RFC Editor's Note:* Please remove this section prior to 361 publication of a final version of this document. 363 HTTP/3 uses the token "h3" to identify itself in ALPN and Alt-Svc. 364 Only implementations of the final, published RFC can identify 365 themselves as "h3". Until such an RFC exists, implementations MUST 366 NOT identify themselves using this string. 368 Implementations of draft versions of the protocol MUST add the string 369 "-" and the corresponding draft number to the identifier. For 370 example, draft-ietf-quic-http-01 is identified using the string 371 "h3-01". 373 Draft versions MUST use the corresponding draft transport version as 374 their transport. For example, the application protocol defined in 375 draft-ietf-quic-http-25 uses the transport defined in draft-ietf- 376 quic-transport-25. 378 Non-compatible experiments that are based on these draft versions 379 MUST append the string "-" and an experiment name to the identifier. 380 For example, an experimental implementation based on draft-ietf-quic- 381 http-09 which reserves an extra stream for unsolicited transmission 382 of 1980s pop music might identify itself as "h3-09-rickroll". Note 383 that any label MUST conform to the "token" syntax defined in 384 Section 4.4.1.1 of [SEMANTICS]. Experimenters are encouraged to 385 coordinate their experiments on the quic@ietf.org 386 (mailto:quic@ietf.org) mailing list. 388 3.2. Discovering an HTTP/3 Endpoint 390 HTTP relies on the notion of an authoritative response: a response 391 that has been determined to be the most appropriate response for that 392 request given the state of the target resource at the time of 393 response message origination by (or at the direction of) the origin 394 server identified within the target URI. Locating an authoritative 395 server for an HTTP URL is discussed in Section 5.4 of [SEMANTICS]. 397 The "https" scheme associates authority with possession of a 398 certificate that the client considers to be trustworthy for the host 399 identified by the authority component of the URL. If a server 400 presents a certificate and proof that it controls the corresponding 401 private key, then a client will accept a secured connection to that 402 server as being authoritative for all origins with the "https" scheme 403 and a host identified in the certificate. 405 A client MAY attempt access to a resource with an "https" URI by 406 resolving the host identifier to an IP address, establishing a QUIC 407 connection to that address on the indicated port, and sending an 408 HTTP/3 request message targeting the URI to the server over that 409 secured connection. 411 Connectivity problems (e.g., blocking UDP) can result in QUIC 412 connection establishment failure; clients SHOULD attempt to use TCP- 413 based versions of HTTP in this case. 415 Servers MAY serve HTTP/3 on any UDP port; an alternative service 416 advertisement always includes an explicit port, and URLs contain 417 either an explicit port or a default port associated with the scheme. 419 3.2.1. HTTP Alternative Services 421 An HTTP origin advertises the availability of an equivalent HTTP/3 422 endpoint via the Alt-Svc HTTP response header field or the HTTP/2 423 ALTSVC frame ([ALTSVC]), using the ALPN token defined in Section 3.3. 425 For example, an origin could indicate in an HTTP response that HTTP/3 426 was available on UDP port 50781 at the same hostname by including the 427 following header field: 429 Alt-Svc: h3=":50781" 431 On receipt of an Alt-Svc record indicating HTTP/3 support, a client 432 MAY attempt to establish a QUIC connection to the indicated host and 433 port and, if successful, send HTTP requests using the mapping 434 described in this document. 436 3.2.2. Other Schemes 438 Although HTTP is independent of the transport protocol, the "http" 439 scheme associates authority with the ability to receive TCP 440 connections on the indicated port of whatever host is identified 441 within the authority component. Because HTTP/3 does not use TCP, 442 HTTP/3 cannot be used for direct access to the authoritative server 443 for a resource identified by an "http" URI. However, protocol 444 extensions such as [ALTSVC] permit the authoritative server to 445 identify other services which are also authoritative and which might 446 be reachable over HTTP/3. 448 Prior to making requests for an origin whose scheme is not "https", 449 the client MUST ensure the server is willing to serve that scheme. 450 If the client intends to make requests for an origin whose scheme is 451 "http", this means that it MUST obtain a valid "http-opportunistic" 452 response for the origin as described in [RFC8164] prior to making any 453 such requests. Other schemes might define other mechanisms. 455 3.3. Connection Establishment 457 HTTP/3 relies on QUIC version 1 as the underlying transport. The use 458 of other QUIC transport versions with HTTP/3 MAY be defined by future 459 specifications. 461 QUIC version 1 uses TLS version 1.3 or greater as its handshake 462 protocol. HTTP/3 clients MUST support a mechanism to indicate the 463 target host to the server during the TLS handshake. If the server is 464 identified by a DNS name, clients MUST send the Server Name 465 Indication (SNI) [RFC6066] TLS extension unless an alternative 466 mechanism to indicate the target host is used. 468 QUIC connections are established as described in [QUIC-TRANSPORT]. 469 During connection establishment, HTTP/3 support is indicated by 470 selecting the ALPN token "h3" in the TLS handshake. Support for 471 other application-layer protocols MAY be offered in the same 472 handshake. 474 While connection-level options pertaining to the core QUIC protocol 475 are set in the initial crypto handshake, HTTP/3-specific settings are 476 conveyed in the SETTINGS frame. After the QUIC connection is 477 established, a SETTINGS frame (Section 7.2.4) MUST be sent by each 478 endpoint as the initial frame of their respective HTTP control 479 stream; see Section 6.2.1. 481 3.4. Connection Reuse 483 HTTP/3 connections are persistent across multiple requests. For best 484 performance, it is expected that clients will not close connections 485 until it is determined that no further communication with a server is 486 necessary (for example, when a user navigates away from a particular 487 web page) or until the server closes the connection. 489 Once a connection exists to a server endpoint, this connection MAY be 490 reused for requests with multiple different URI authority components. 491 In general, a server is considered authoritative for all URIs with 492 the "https" scheme for which the hostname in the URI is present in 493 the authenticated certificate provided by the server, either as the 494 CN field of the certificate subject or as a dNSName in the 495 subjectAltName field of the certificate; see [RFC6125]. For a host 496 that is an IP address, the client MUST verify that the address 497 appears as an iPAddress in the subjectAltName field of the 498 certificate. If the hostname or address is not present in the 499 certificate, the client MUST NOT consider the server authoritative 500 for origins containing that hostname or address. See Section 5.4 of 501 [SEMANTICS] for more detail on authoritative access. 503 Clients SHOULD NOT open more than one HTTP/3 connection to a given 504 host and port pair, where the host is derived from a URI, a selected 505 alternative service [ALTSVC], or a configured proxy. A client MAY 506 open multiple connections to the same IP address and UDP port using 507 different transport or TLS configurations but SHOULD avoid creating 508 multiple connections with the same configuration. 510 Servers are encouraged to maintain open connections for as long as 511 possible but are permitted to terminate idle connections if 512 necessary. When either endpoint chooses to close the HTTP/3 session, 513 the terminating endpoint SHOULD first send a GOAWAY frame 514 (Section 5.2) so that both endpoints can reliably determine whether 515 previously sent frames have been processed and gracefully complete or 516 terminate any necessary remaining tasks. 518 A server that does not wish clients to reuse connections for a 519 particular origin can indicate that it is not authoritative for a 520 request by sending a 421 (Misdirected Request) status code in 521 response to the request; see Section 9.1.2 of [HTTP2]. 523 4. HTTP Request Lifecycle 525 4.1. HTTP Message Exchanges 527 A client sends an HTTP request on a client-initiated bidirectional 528 QUIC stream. A client MUST send only a single request on a given 529 stream. A server sends zero or more interim HTTP responses on the 530 same stream as the request, followed by a single final HTTP response, 531 as detailed below. 533 Pushed responses are sent on a server-initiated unidirectional QUIC 534 stream; see Section 6.2.2. A server sends zero or more interim HTTP 535 responses, followed by a single final HTTP response, in the same 536 manner as a standard response. Push is described in more detail in 537 Section 4.4. 539 On a given stream, receipt of multiple requests or receipt of an 540 additional HTTP response following a final HTTP response MUST be 541 treated as malformed (Section 4.1.3). 543 An HTTP message (request or response) consists of: 545 1. the header field section (see Section 4 of [SEMANTICS]), sent as 546 a single HEADERS frame (see Section 7.2.2), 548 2. optionally, the payload body, if present (see Section 6.3.3 of 549 [SEMANTICS]), sent as a series of DATA frames (see 550 Section 7.2.1), 552 3. optionally, the trailer field section, if present (see 553 Section 4.6 of [SEMANTICS]), sent as a single HEADERS frame. 555 Receipt of an invalid sequence of frames MUST be treated as a 556 connection error of type H3_FRAME_UNEXPECTED (Section 8). In 557 particular, a DATA frame before any HEADERS frame, or a HEADERS or 558 DATA frame after the trailing HEADERS frame is considered invalid. 560 A server MAY send one or more PUSH_PROMISE frames (see Section 7.2.5) 561 before, after, or interleaved with the frames of a response message. 562 These PUSH_PROMISE frames are not part of the response; see 563 Section 4.4 for more details. These frames are not permitted in 564 pushed responses; a pushed response which includes PUSH_PROMISE 565 frames MUST be treated as a connection error of type 566 H3_FRAME_UNEXPECTED. 568 Frames of unknown types (Section 9), including reserved frames 569 (Section 7.2.8) MAY be sent on a request or push stream before, 570 after, or interleaved with other frames described in this section. 572 The HEADERS and PUSH_PROMISE frames might reference updates to the 573 QPACK dynamic table. While these updates are not directly part of 574 the message exchange, they must be received and processed before the 575 message can be consumed. See Section 4.1.1 for more details. 577 The "chunked" transfer encoding defined in Section 7.1 of [HTTP11] 578 MUST NOT be used. 580 A response MAY consist of multiple messages when and only when one or 581 more informational responses (1xx; see Section 9.2 of [SEMANTICS]) 582 precede a final response to the same request. Interim responses do 583 not contain a payload body or trailers. 585 An HTTP request/response exchange fully consumes a client-initiated 586 bidirectional QUIC stream. After sending a request, a client MUST 587 close the stream for sending. Unless using the CONNECT method (see 588 Section 4.2), clients MUST NOT make stream closure dependent on 589 receiving a response to their request. After sending a final 590 response, the server MUST close the stream for sending. At this 591 point, the QUIC stream is fully closed. 593 When a stream is closed, this indicates the end of an HTTP message. 594 Because some messages are large or unbounded, endpoints SHOULD begin 595 processing partial HTTP messages once enough of the message has been 596 received to make progress. If a client stream terminates without 597 enough of the HTTP message to provide a complete response, the server 598 SHOULD abort its response with the error code H3_REQUEST_INCOMPLETE. 600 A server can send a complete response prior to the client sending an 601 entire request if the response does not depend on any portion of the 602 request that has not been sent and received. When the server does 603 not need to receive the remainder of the request, it MAY abort 604 reading the request stream, send a complete response, and cleanly 605 close the sending part of the stream. The error code H3_NO_ERROR 606 SHOULD be used when requesting that the client stop sending on the 607 request stream. Clients MUST NOT discard complete responses as a 608 result of having their request terminated abruptly, though clients 609 can always discard responses at their discretion for other reasons. 610 If the server sends a partial or complete response but does not abort 611 reading, clients SHOULD continue sending the body of the request and 612 close the stream normally. 614 4.1.1. Field Formatting and Compression 616 HTTP messages carry metadata as a series of key-value pairs, called 617 HTTP fields. For a listing of registered HTTP fields, see the 618 "Hypertext Transfer Protocol (HTTP) Field Name Registry" maintained 619 at https://www.iana.org/assignments/http-fields/. 621 As in previous versions of HTTP, field names are strings containing a 622 subset of ASCII characters that are compared in a case-insensitive 623 fashion. Properties of HTTP field names and values are discussed in 624 more detail in Section 4.3 of [SEMANTICS]. As in HTTP/2, characters 625 in field names MUST be converted to lowercase prior to their 626 encoding. A request or response containing uppercase characters in 627 field names MUST be treated as malformed (Section 4.1.3). 629 Like HTTP/2, HTTP/3 does not use the Connection header field to 630 indicate connection-specific fields; in this protocol, connection- 631 specific metadata is conveyed by other means. An endpoint MUST NOT 632 generate an HTTP/3 field section containing connection-specific 633 fields; any message containing connection-specific fields MUST be 634 treated as malformed (Section 4.1.3). 636 The only exception to this is the TE header field, which MAY be 637 present in an HTTP/3 request header; when it is, it MUST NOT contain 638 any value other than "trailers". 640 This means that an intermediary transforming an HTTP/1.x message to 641 HTTP/3 will need to remove any fields nominated by the Connection 642 field, along with the Connection field itself. Such intermediaries 643 SHOULD also remove other connection-specific fields, such as Keep- 644 Alive, Proxy-Connection, Transfer-Encoding, and Upgrade, even if they 645 are not nominated by the Connection field. 647 4.1.1.1. Pseudo-Header Fields 649 Like HTTP/2, HTTP/3 employs a series of pseudo-header fields where 650 the field name begins with the ':' character (ASCII 0x3a). These 651 pseudo-header fields convey the target URI, the method of the 652 request, and the status code for the response. 654 Pseudo-header fields are not HTTP fields. Endpoints MUST NOT 655 generate pseudo-header fields other than those defined in this 656 document, except as negotiated via an extension; see Section 9. 658 Pseudo-header fields are only valid in the context in which they are 659 defined. Pseudo-header fields defined for requests MUST NOT appear 660 in responses; pseudo-header fields defined for responses MUST NOT 661 appear in requests. Pseudo-header fields MUST NOT appear in 662 trailers. Endpoints MUST treat a request or response that contains 663 undefined or invalid pseudo-header fields as malformed 664 (Section 4.1.3). 666 All pseudo-header fields MUST appear in the header field section 667 before regular header fields. Any request or response that contains 668 a pseudo-header field that appears in a header field section after a 669 regular header field MUST be treated as malformed (Section 4.1.3). 671 The following pseudo-header fields are defined for requests: 673 ":method": Contains the HTTP method (Section 7 of [SEMANTICS]) 675 ":scheme": Contains the scheme portion of the target URI 676 (Section 3.1 of [RFC3986]) 678 ":scheme" is not restricted to "http" and "https" schemed URIs. A 679 proxy or gateway can translate requests for non-HTTP schemes, 680 enabling the use of HTTP to interact with non-HTTP services. 682 ":authority": Contains the authority portion of the target URI 683 (Section 3.2 of [RFC3986]). The authority MUST NOT include the 684 deprecated "userinfo" subcomponent for "http" or "https" schemed 685 URIs. 687 To ensure that the HTTP/1.1 request line can be reproduced 688 accurately, this pseudo-header field MUST be omitted when 689 translating from an HTTP/1.1 request that has a request target in 690 origin or asterisk form; see Section 3.2 of [HTTP11]. Clients 691 that generate HTTP/3 requests directly SHOULD use the ":authority" 692 pseudo-header field instead of the Host field. An intermediary 693 that converts an HTTP/3 request to HTTP/1.1 MUST create a Host 694 field if one is not present in a request by copying the value of 695 the ":authority" pseudo-header field. 697 ":path": Contains the path and query parts of the target URI (the 698 "path-absolute" production and optionally a '?' character followed 699 by the "query" production; see Sections 3.3 and 3.4 of [URI]. A 700 request in asterisk form includes the value '*' for the ":path" 701 pseudo-header field. 703 This pseudo-header field MUST NOT be empty for "http" or "https" 704 URIs; "http" or "https" URIs that do not contain a path component 705 MUST include a value of '/'. The exception to this rule is an 706 OPTIONS request for an "http" or "https" URI that does not include 707 a path component; these MUST include a ":path" pseudo-header field 708 with a value of '*'; see Section 3.2.4 of [HTTP11]. 710 All HTTP/3 requests MUST include exactly one value for the ":method", 711 ":scheme", and ":path" pseudo-header fields, unless it is a CONNECT 712 request; see Section 4.2. 714 If the ":scheme" pseudo-header field identifies a scheme which has a 715 mandatory authority component (including "http" and "https"), the 716 request MUST contain either an ":authority" pseudo-header field or a 717 "Host" header field. If these fields are present, they MUST NOT be 718 empty. If both fields are present, they MUST contain the same value. 719 If the scheme does not have a mandatory authority component and none 720 is provided in the request target, the request MUST NOT contain the 721 ":authority" pseudo-header and "Host" header fields. 723 An HTTP request that omits mandatory pseudo-header fields or contains 724 invalid values for those pseudo-header fields is malformed 725 (Section 4.1.3). 727 HTTP/3 does not define a way to carry the version identifier that is 728 included in the HTTP/1.1 request line. 730 For responses, a single ":status" pseudo-header field is defined that 731 carries the HTTP status code; see Section 9 of [SEMANTICS]. This 732 pseudo-header field MUST be included in all responses; otherwise, the 733 response is malformed (Section 4.1.3). 735 HTTP/3 does not define a way to carry the version or reason phrase 736 that is included in an HTTP/1.1 status line. 738 4.1.1.2. Field Compression 740 HTTP/3 uses QPACK field compression as described in [QPACK], a 741 variation of HPACK which allows the flexibility to avoid compression- 742 induced head-of-line blocking. See that document for additional 743 details. 745 To allow for better compression efficiency, the "Cookie" field 746 [RFC6265] MAY be split into separate field lines, each with one or 747 more cookie-pairs, before compression. If a decompressed field 748 section contains multiple cookie field lines, these MUST be 749 concatenated into a single octet string using the two-octet delimiter 750 of 0x3B, 0x20 (the ASCII string "; ") before being passed into a 751 context other than HTTP/2 or HTTP/3, such as an HTTP/1.1 connection, 752 or a generic HTTP server application. 754 4.1.1.3. Header Size Constraints 756 An HTTP/3 implementation MAY impose a limit on the maximum size of 757 the message header it will accept on an individual HTTP message. A 758 server that receives a larger header section than it is willing to 759 handle can send an HTTP 431 (Request Header Fields Too Large) status 760 code ([RFC6585]). A client can discard responses that it cannot 761 process. The size of a field list is calculated based on the 762 uncompressed size of fields, including the length of the name and 763 value in bytes plus an overhead of 32 bytes for each field. 765 If an implementation wishes to advise its peer of this limit, it can 766 be conveyed as a number of bytes in the 767 SETTINGS_MAX_FIELD_SECTION_SIZE parameter. An implementation which 768 has received this parameter SHOULD NOT send an HTTP message header 769 which exceeds the indicated size, as the peer will likely refuse to 770 process it. However, because this limit is applied at each hop, 771 messages below this limit are not guaranteed to be accepted. 773 4.1.2. Request Cancellation and Rejection 775 Clients can cancel requests by resetting and aborting the request 776 stream with an error code of H3_REQUEST_CANCELLED (Section 8.1). 777 When the client aborts reading a response, it indicates that this 778 response is no longer of interest. Implementations SHOULD cancel 779 requests by abruptly terminating any directions of a stream that are 780 still open. 782 When the server rejects a request without performing any application 783 processing, it SHOULD abort its response stream with the error code 784 H3_REQUEST_REJECTED. In this context, "processed" means that some 785 data from the stream was passed to some higher layer of software that 786 might have taken some action as a result. The client can treat 787 requests rejected by the server as though they had never been sent at 788 all, thereby allowing them to be retried later on a new connection. 789 Servers MUST NOT use the H3_REQUEST_REJECTED error code for requests 790 which were partially or fully processed. When a server abandons a 791 response after partial processing, it SHOULD abort its response 792 stream with the error code H3_REQUEST_CANCELLED. 794 When a client resets a request with the error code 795 H3_REQUEST_CANCELLED, a server MAY abruptly terminate the response 796 using the error code H3_REQUEST_REJECTED if no processing was 797 performed. Clients MUST NOT use the H3_REQUEST_REJECTED error code, 798 except when a server has requested closure of the request stream with 799 this error code. 801 If a stream is cancelled after receiving a complete response, the 802 client MAY ignore the cancellation and use the response. However, if 803 a stream is cancelled after receiving a partial response, the 804 response SHOULD NOT be used. Automatically retrying such requests is 805 not possible, unless this is otherwise permitted (e.g., idempotent 806 actions like GET, PUT, or DELETE). 808 4.1.3. Malformed Requests and Responses 810 A malformed request or response is one that is an otherwise valid 811 sequence of frames but is invalid due to: 813 * the presence of prohibited fields or pseudo-header fields, 815 * the absence of mandatory pseudo-header fields, 817 * invalid values for pseudo-header fields, 819 * pseudo-header fields after fields, 821 * an invalid sequence of HTTP messages, 823 * the inclusion of uppercase field names, or 825 * the inclusion of invalid characters in field names or values 827 A request or response that includes a payload body can include a 828 Content-Length header field. A request or response is also malformed 829 if the value of a content-length header field does not equal the sum 830 of the DATA frame payload lengths that form the body. A response 831 that is defined to have no payload, as described in Section 6.3.3 of 832 [SEMANTICS] can have a non-zero content-length field, even though no 833 content is included in DATA frames. 835 Intermediaries that process HTTP requests or responses (i.e., any 836 intermediary not acting as a tunnel) MUST NOT forward a malformed 837 request or response. Malformed requests or responses that are 838 detected MUST be treated as a stream error (Section 8) of type 839 H3_GENERAL_PROTOCOL_ERROR. 841 For malformed requests, a server MAY send an HTTP response prior to 842 closing or resetting the stream. Clients MUST NOT accept a malformed 843 response. Note that these requirements are intended to protect 844 against several types of common attacks against HTTP; they are 845 deliberately strict because being permissive can expose 846 implementations to these vulnerabilities. 848 4.2. The CONNECT Method 850 The CONNECT method requests that the recipient establish a tunnel to 851 the destination origin server identified by the request-target 852 (Section 3.2 of [HTTP11]). It is primarily used with HTTP proxies to 853 establish a TLS session with an origin server for the purposes of 854 interacting with "https" resources. 856 In HTTP/1.x, CONNECT is used to convert an entire HTTP connection 857 into a tunnel to a remote host. In HTTP/2 and HTTP/3, the CONNECT 858 method is used to establish a tunnel over a single stream. 860 A CONNECT request MUST be constructed as follows: 862 * The ":method" pseudo-header field is set to "CONNECT" 864 * The ":scheme" and ":path" pseudo-header fields are omitted 866 * The ":authority" pseudo-header field contains the host and port to 867 connect to (equivalent to the authority-form of the request-target 868 of CONNECT requests; see Section 3.2.3 of [HTTP11]) 870 The request stream remains open at the end of the request to carry 871 the data to be transferred. A CONNECT request that does not conform 872 to these restrictions is malformed; see Section 4.1.3. 874 A proxy that supports CONNECT establishes a TCP connection 875 ([RFC0793]) to the server identified in the ":authority" pseudo- 876 header field. Once this connection is successfully established, the 877 proxy sends a HEADERS frame containing a 2xx series status code to 878 the client, as defined in Section 9.3 of [SEMANTICS]. 880 All DATA frames on the stream correspond to data sent or received on 881 the TCP connection. Any DATA frame sent by the client is transmitted 882 by the proxy to the TCP server; data received from the TCP server is 883 packaged into DATA frames by the proxy. Note that the size and 884 number of TCP segments is not guaranteed to map predictably to the 885 size and number of HTTP DATA or QUIC STREAM frames. 887 Once the CONNECT method has completed, only DATA frames are permitted 888 to be sent on the stream. Extension frames MAY be used if 889 specifically permitted by the definition of the extension. Receipt 890 of any other frame type MUST be treated as a connection error of type 891 H3_FRAME_UNEXPECTED. 893 The TCP connection can be closed by either peer. When the client 894 ends the request stream (that is, the receive stream at the proxy 895 enters the "Data Recvd" state), the proxy will set the FIN bit on its 896 connection to the TCP server. When the proxy receives a packet with 897 the FIN bit set, it will terminate the send stream that it sends to 898 the client. TCP connections which remain half-closed in a single 899 direction are not invalid, but are often handled poorly by servers, 900 so clients SHOULD NOT close a stream for sending while they still 901 expect to receive data from the target of the CONNECT. 903 A TCP connection error is signaled by abruptly terminating the 904 stream. A proxy treats any error in the TCP connection, which 905 includes receiving a TCP segment with the RST bit set, as a stream 906 error of type H3_CONNECT_ERROR (Section 8.1). Correspondingly, if a 907 proxy detects an error with the stream or the QUIC connection, it 908 MUST close the TCP connection. If the underlying TCP implementation 909 permits it, the proxy SHOULD send a TCP segment with the RST bit set. 911 4.3. HTTP Upgrade 913 HTTP/3 does not support the HTTP Upgrade mechanism (Section 9.9 of 914 [HTTP11]) or 101 (Switching Protocols) informational status code 915 (Section 9.2.2 of [SEMANTICS]). 917 4.4. Server Push 919 Server push is an interaction mode which permits a server to push a 920 request-response exchange to a client in anticipation of the client 921 making the indicated request. This trades off network usage against 922 a potential latency gain. HTTP/3 server push is similar to what is 923 described in HTTP/2 [HTTP2], but uses different mechanisms. 925 Each server push is identified by a unique Push ID. This Push ID is 926 used in one or more PUSH_PROMISE frames (see Section 7.2.5) that 927 carry the request fields, then included with the push stream which 928 ultimately fulfills those promises. When the same Push ID is 929 promised on multiple request streams, the decompressed request field 930 sections MUST contain the same fields in the same order, and both the 931 name and the value in each field MUST be exact matches. 933 Server push is only enabled on a connection when a client sends a 934 MAX_PUSH_ID frame; see Section 7.2.7. A server cannot use server 935 push until it receives a MAX_PUSH_ID frame. A client sends 936 additional MAX_PUSH_ID frames to control the number of pushes that a 937 server can promise. A server SHOULD use Push IDs sequentially, 938 starting at 0. A client MUST treat receipt of a push stream with a 939 Push ID that is greater than the maximum Push ID as a connection 940 error of type H3_ID_ERROR. 942 The header section of the request message is carried by a 943 PUSH_PROMISE frame (see Section 7.2.5) on the request stream which 944 generated the push. This allows the server push to be associated 945 with a client request. 947 Not all requests can be pushed. A server MAY push requests which 948 have the following properties: 950 * cacheable; see Section 7.2.3 of [SEMANTICS] 952 * safe; see Section 7.2.1 of [SEMANTICS] 954 * does not include a request body or trailer section 956 The server MUST include a value in the ":authority" pseudo-header 957 field for which the server is authoritative; see Section 3.4. 959 Clients SHOULD send a CANCEL_PUSH frame upon receipt of a 960 PUSH_PROMISE frame carrying a request which is not cacheable, is not 961 known to be safe, that indicates the presence of a request body, or 962 for which it does not consider the server authoritative. 964 Each pushed response is associated with one or more client requests. 965 The push is associated with the request stream on which the 966 PUSH_PROMISE frame was received. The same server push can be 967 associated with additional client requests using a PUSH_PROMISE frame 968 with the same Push ID on multiple request streams. These 969 associations do not affect the operation of the protocol, but MAY be 970 considered by user agents when deciding how to use pushed resources. 972 Ordering of a PUSH_PROMISE in relation to certain parts of the 973 response is important. The server SHOULD send PUSH_PROMISE frames 974 prior to sending HEADERS or DATA frames that reference the promised 975 responses. This reduces the chance that a client requests a resource 976 that will be pushed by the server. 978 When a server later fulfills a promise, the server push response is 979 conveyed on a push stream; see Section 6.2.2. The push stream 980 identifies the Push ID of the promise that it fulfills, then contains 981 a response to the promised request using the same format described 982 for responses in Section 4.1. 984 Due to reordering, push stream data can arrive before the 985 corresponding PUSH_PROMISE frame. When a client receives a new push 986 stream with an as-yet-unknown Push ID, both the associated client 987 request and the pushed request header fields are unknown. The client 988 can buffer the stream data in expectation of the matching 989 PUSH_PROMISE. The client can use stream flow control (see section 990 4.1 of [QUIC-TRANSPORT]) to limit the amount of data a server may 991 commit to the pushed stream. 993 If a promised server push is not needed by the client, the client 994 SHOULD send a CANCEL_PUSH frame. If the push stream is already open 995 or opens after sending the CANCEL_PUSH frame, the client can abort 996 reading the stream with an error code of H3_REQUEST_CANCELLED. This 997 asks the server not to transfer additional data and indicates that it 998 will be discarded upon receipt. 1000 Pushed responses that are cacheable (see Section 3 of [CACHING]) can 1001 be stored by the client, if it implements an HTTP cache. Pushed 1002 responses are considered successfully validated on the origin server 1003 (e.g., if the "no-cache" cache response directive is present 1004 (Section 5.2.2.3 of [CACHING])) at the time the pushed response is 1005 received. 1007 Pushed responses that are not cacheable MUST NOT be stored by any 1008 HTTP cache. They MAY be made available to the application 1009 separately. 1011 5. Connection Closure 1013 Once established, an HTTP/3 connection can be used for many requests 1014 and responses over time until the connection is closed. Connection 1015 closure can happen in any of several different ways. 1017 5.1. Idle Connections 1019 Each QUIC endpoint declares an idle timeout during the handshake. If 1020 the connection remains idle (no packets received) for longer than 1021 this duration, the peer will assume that the connection has been 1022 closed. HTTP/3 implementations will need to open a new connection 1023 for new requests if the existing connection has been idle for longer 1024 than the server's advertised idle timeout, and SHOULD do so if 1025 approaching the idle timeout. 1027 HTTP clients are expected to request that the transport keep 1028 connections open while there are responses outstanding for requests 1029 or server pushes, as described in Section 10.2.2 of [QUIC-TRANSPORT]. 1030 If the client is not expecting a response from the server, allowing 1031 an idle connection to time out is preferred over expending effort 1032 maintaining a connection that might not be needed. A gateway MAY 1033 maintain connections in anticipation of need rather than incur the 1034 latency cost of connection establishment to servers. Servers SHOULD 1035 NOT actively keep connections open. 1037 5.2. Connection Shutdown 1039 Even when a connection is not idle, either endpoint can decide to 1040 stop using the connection and initiate a graceful connection close. 1041 Endpoints initiate the graceful shutdown of a connection by sending a 1042 GOAWAY frame (Section 7.2.6). The GOAWAY frame contains an 1043 identifier that indicates to the receiver the range of requests or 1044 pushes that were or might be processed in this connection. The 1045 server sends a client-initiated bidirectional Stream ID; the client 1046 sends a Push ID. Requests or pushes with the indicated identifier or 1047 greater are rejected by the sender of the GOAWAY. This identifier 1048 MAY be zero if no requests or pushes were processed. 1050 The information in the GOAWAY frame enables a client and server to 1051 agree on which requests or pushes were accepted prior to the 1052 connection shutdown. Upon sending a GOAWAY frame, the endpoint 1053 SHOULD explicitly cancel (see Section 4.1.2 and Section 7.2.3) any 1054 requests or pushes that have identifiers greater than or equal to 1055 that indicated, in order to clean up transport state for the affected 1056 streams. The endpoint SHOULD continue to do so as more requests or 1057 pushes arrive. 1059 Endpoints MUST NOT initiate new requests or promise new pushes on the 1060 connection after receipt of a GOAWAY frame from the peer. Clients 1061 MAY establish a new connection to send additional requests. 1063 Some requests or pushes might already be in transit: 1065 * Upon receipt of a GOAWAY frame, if the client has already sent 1066 requests with a Stream ID greater than or equal to the identifier 1067 received in a GOAWAY frame, those requests will not be processed. 1068 Clients can safely retry unprocessed requests on a different 1069 connection. 1071 Requests on Stream IDs less than the Stream ID in a GOAWAY frame 1072 from the server might have been processed; their status cannot be 1073 known until a response is received, the stream is reset 1074 individually, another GOAWAY is received, or the connection 1075 terminates. 1077 Servers MAY reject individual requests on streams below the 1078 indicated ID if these requests were not processed. 1080 * If a server receives a GOAWAY frame after having promised pushes 1081 with a Push ID greater than or equal to the identifier received in 1082 a GOAWAY frame, those pushes will not be accepted. 1084 Servers SHOULD send a GOAWAY frame when the closing of a connection 1085 is known in advance, even if the advance notice is small, so that the 1086 remote peer can know whether a request has been partially processed 1087 or not. For example, if an HTTP client sends a POST at the same time 1088 that a server closes a QUIC connection, the client cannot know if the 1089 server started to process that POST request if the server does not 1090 send a GOAWAY frame to indicate what streams it might have acted on. 1092 A client that is unable to retry requests loses all requests that are 1093 in flight when the server closes the connection. An endpoint MAY 1094 send multiple GOAWAY frames indicating different identifiers, but the 1095 identifier in each frame MUST NOT be greater than the identifier in 1096 any previous frame, since clients might already have retried 1097 unprocessed requests on another connection. Receiving a GOAWAY 1098 containing a larger identifier than previously received MUST be 1099 treated as a connection error of type H3_ID_ERROR. 1101 An endpoint that is attempting to gracefully shut down a connection 1102 can send a GOAWAY frame with a value set to the maximum possible 1103 value (2^62-4 for servers, 2^62-1 for clients). This ensures that 1104 the peer stops creating new requests or pushes. After allowing time 1105 for any in-flight requests or pushes to arrive, the endpoint can send 1106 another GOAWAY frame indicating which requests or pushes it might 1107 accept before the end of the connection. This ensures that a 1108 connection can be cleanly shut down without losing requests. 1110 A client has more flexibility in the value it chooses for the Push ID 1111 in a GOAWAY that it sends. A value of 2^62 - 1 indicates that the 1112 server can continue fulfilling pushes which have already been 1113 promised, and the client can continue granting push credit as needed; 1114 see Section 7.2.7. A smaller value indicates the client will reject 1115 pushes with Push IDs greater than or equal to this value. Like the 1116 server, the client MAY send subsequent GOAWAY frames so long as the 1117 specified Push ID is strictly smaller than all previously sent 1118 values. 1120 Even when a GOAWAY indicates that a given request or push will not be 1121 processed or accepted upon receipt, the underlying transport 1122 resources still exist. The endpoint that initiated these requests 1123 can cancel them to clean up transport state. 1125 Once all accepted requests and pushes have been processed, the 1126 endpoint can permit the connection to become idle, or MAY initiate an 1127 immediate closure of the connection. An endpoint that completes a 1128 graceful shutdown SHOULD use the H3_NO_ERROR code when closing the 1129 connection. 1131 If a client has consumed all available bidirectional stream IDs with 1132 requests, the server need not send a GOAWAY frame, since the client 1133 is unable to make further requests. 1135 5.3. Immediate Application Closure 1137 An HTTP/3 implementation can immediately close the QUIC connection at 1138 any time. This results in sending a QUIC CONNECTION_CLOSE frame to 1139 the peer indicating that the application layer has terminated the 1140 connection. The application error code in this frame indicates to 1141 the peer why the connection is being closed. See Section 8 for error 1142 codes which can be used when closing a connection in HTTP/3. 1144 Before closing the connection, a GOAWAY frame MAY be sent to allow 1145 the client to retry some requests. Including the GOAWAY frame in the 1146 same packet as the QUIC CONNECTION_CLOSE frame improves the chances 1147 of the frame being received by clients. 1149 5.4. Transport Closure 1151 For various reasons, the QUIC transport could indicate to the 1152 application layer that the connection has terminated. This might be 1153 due to an explicit closure by the peer, a transport-level error, or a 1154 change in network topology which interrupts connectivity. 1156 If a connection terminates without a GOAWAY frame, clients MUST 1157 assume that any request which was sent, whether in whole or in part, 1158 might have been processed. 1160 6. Stream Mapping and Usage 1162 A QUIC stream provides reliable in-order delivery of bytes, but makes 1163 no guarantees about order of delivery with regard to bytes on other 1164 streams. On the wire, data is framed into QUIC STREAM frames, but 1165 this framing is invisible to the HTTP framing layer. The transport 1166 layer buffers and orders received QUIC STREAM frames, exposing the 1167 data contained within as a reliable byte stream to the application. 1168 Although QUIC permits out-of-order delivery within a stream, HTTP/3 1169 does not make use of this feature. 1171 QUIC streams can be either unidirectional, carrying data only from 1172 initiator to receiver, or bidirectional. Streams can be initiated by 1173 either the client or the server. For more detail on QUIC streams, 1174 see Section 2 of [QUIC-TRANSPORT]. 1176 When HTTP fields and data are sent over QUIC, the QUIC layer handles 1177 most of the stream management. HTTP does not need to do any separate 1178 multiplexing when using QUIC - data sent over a QUIC stream always 1179 maps to a particular HTTP transaction or connection context. 1181 6.1. Bidirectional Streams 1183 All client-initiated bidirectional streams are used for HTTP requests 1184 and responses. A bidirectional stream ensures that the response can 1185 be readily correlated with the request. This means that the client's 1186 first request occurs on QUIC stream 0, with subsequent requests on 1187 stream 4, 8, and so on. In order to permit these streams to open, an 1188 HTTP/3 server SHOULD configure non-zero minimum values for the number 1189 of permitted streams and the initial stream flow control window. So 1190 as to not unnecessarily limit parallelism, at least 100 requests 1191 SHOULD be permitted at a time. 1193 HTTP/3 does not use server-initiated bidirectional streams, though an 1194 extension could define a use for these streams. Clients MUST treat 1195 receipt of a server-initiated bidirectional stream as a connection 1196 error of type H3_STREAM_CREATION_ERROR unless such an extension has 1197 been negotiated. 1199 6.2. Unidirectional Streams 1201 Unidirectional streams, in either direction, are used for a range of 1202 purposes. The purpose is indicated by a stream type, which is sent 1203 as a variable-length integer at the start of the stream. The format 1204 and structure of data that follows this integer is determined by the 1205 stream type. 1207 Unidirectional Stream Header { 1208 Stream Type (i), 1209 } 1211 Figure 1: Unidirectional Stream Header 1213 Some stream types are reserved (Section 6.2.3). Two stream types are 1214 defined in this document: control streams (Section 6.2.1) and push 1215 streams (Section 6.2.2). [QPACK] defines two additional stream 1216 types. Other stream types can be defined by extensions to HTTP/3; 1217 see Section 9 for more details. 1219 The performance of HTTP/3 connections in the early phase of their 1220 lifetime is sensitive to the creation and exchange of data on 1221 unidirectional streams. Endpoints that excessively restrict the 1222 number of streams or the flow control window of these streams will 1223 increase the chance that the remote peer reaches the limit early and 1224 becomes blocked. In particular, implementations should consider that 1225 remote peers may wish to exercise reserved stream behavior 1226 (Section 6.2.3) with some of the unidirectional streams they are 1227 permitted to use. To avoid blocking, the transport parameters sent 1228 by both clients and servers MUST allow the peer to create at least 1229 one unidirectional stream for the HTTP control stream plus the number 1230 of unidirectional streams required by mandatory extensions (three 1231 being the minimum number required for the base HTTP/3 protocol and 1232 QPACK), and SHOULD provide at least 1,024 bytes of flow control 1233 credit to each stream. 1235 Note that an endpoint is not required to grant additional credits to 1236 create more unidirectional streams if its peer consumes all the 1237 initial credits before creating the critical unidirectional streams. 1238 Endpoints SHOULD create the HTTP control stream as well as the 1239 unidirectional streams required by mandatory extensions (such as the 1240 QPACK encoder and decoder streams) first, and then create additional 1241 streams as allowed by their peer. 1243 If the stream header indicates a stream type which is not supported 1244 by the recipient, the remainder of the stream cannot be consumed as 1245 the semantics are unknown. Recipients of unknown stream types MAY 1246 abort reading of the stream with an error code of 1247 H3_STREAM_CREATION_ERROR, but MUST NOT consider such streams to be a 1248 connection error of any kind. 1250 Implementations MAY send stream types before knowing whether the peer 1251 supports them. However, stream types which could modify the state or 1252 semantics of existing protocol components, including QPACK or other 1253 extensions, MUST NOT be sent until the peer is known to support them. 1255 A sender can close or reset a unidirectional stream unless otherwise 1256 specified. A receiver MUST tolerate unidirectional streams being 1257 closed or reset prior to the reception of the unidirectional stream 1258 header. 1260 6.2.1. Control Streams 1262 A control stream is indicated by a stream type of 0x00. Data on this 1263 stream consists of HTTP/3 frames, as defined in Section 7.2. 1265 Each side MUST initiate a single control stream at the beginning of 1266 the connection and send its SETTINGS frame as the first frame on this 1267 stream. If the first frame of the control stream is any other frame 1268 type, this MUST be treated as a connection error of type 1269 H3_MISSING_SETTINGS. Only one control stream per peer is permitted; 1270 receipt of a second stream which claims to be a control stream MUST 1271 be treated as a connection error of type H3_STREAM_CREATION_ERROR. 1272 The sender MUST NOT close the control stream, and the receiver MUST 1273 NOT request that the sender close the control stream. If either 1274 control stream is closed at any point, this MUST be treated as a 1275 connection error of type H3_CLOSED_CRITICAL_STREAM. 1277 A pair of unidirectional streams is used rather than a single 1278 bidirectional stream. This allows either peer to send data as soon 1279 as it is able. Depending on whether 0-RTT is enabled on the 1280 connection, either client or server might be able to send stream data 1281 first after the cryptographic handshake completes. 1283 6.2.2. Push Streams 1285 Server push is an optional feature introduced in HTTP/2 that allows a 1286 server to initiate a response before a request has been made. See 1287 Section 4.4 for more details. 1289 A push stream is indicated by a stream type of 0x01, followed by the 1290 Push ID of the promise that it fulfills, encoded as a variable-length 1291 integer. The remaining data on this stream consists of HTTP/3 1292 frames, as defined in Section 7.2, and fulfills a promised server 1293 push by zero or more interim HTTP responses followed by a single 1294 final HTTP response, as defined in Section 4.1. Server push and Push 1295 IDs are described in Section 4.4. 1297 Only servers can push; if a server receives a client-initiated push 1298 stream, this MUST be treated as a connection error of type 1299 H3_STREAM_CREATION_ERROR. 1301 Push Stream Header { 1302 Stream Type (i) = 0x01, 1303 Push ID (i), 1304 } 1306 Figure 2: Push Stream Header 1308 Each Push ID MUST only be used once in a push stream header. If a 1309 push stream header includes a Push ID that was used in another push 1310 stream header, the client MUST treat this as a connection error of 1311 type H3_ID_ERROR. 1313 6.2.3. Reserved Stream Types 1315 Stream types of the format "0x1f * N + 0x21" for non-negative integer 1316 values of N are reserved to exercise the requirement that unknown 1317 types be ignored. These streams have no semantics, and can be sent 1318 when application-layer padding is desired. They MAY also be sent on 1319 connections where no data is currently being transferred. Endpoints 1320 MUST NOT consider these streams to have any meaning upon receipt. 1322 The payload and length of the stream are selected in any manner the 1323 implementation chooses. Implementations MAY terminate these streams 1324 cleanly, or MAY abruptly terminate them. When terminating abruptly, 1325 the error code H3_NO_ERROR or a reserved error code (Section 8.1) 1326 SHOULD be used. 1328 7. HTTP Framing Layer 1330 HTTP frames are carried on QUIC streams, as described in Section 6. 1331 HTTP/3 defines three stream types: control stream, request stream, 1332 and push stream. This section describes HTTP/3 frame formats and the 1333 streams types on which they are permitted; see Table 1 for an 1334 overview. A comparison between HTTP/2 and HTTP/3 frames is provided 1335 in Appendix A.2. 1337 +--------------+----------------+----------------+--------+---------+ 1338 | Frame | Control Stream | Request | Push | Section | 1339 | | | Stream | Stream | | 1340 +==============+================+================+========+=========+ 1341 | DATA | No | Yes | Yes | Section | 1342 | | | | | 7.2.1 | 1343 +--------------+----------------+----------------+--------+---------+ 1344 | HEADERS | No | Yes | Yes | Section | 1345 | | | | | 7.2.2 | 1346 +--------------+----------------+----------------+--------+---------+ 1347 | CANCEL_PUSH | Yes | No | No | Section | 1348 | | | | | 7.2.3 | 1349 +--------------+----------------+----------------+--------+---------+ 1350 | SETTINGS | Yes (1) | No | No | Section | 1351 | | | | | 7.2.4 | 1352 +--------------+----------------+----------------+--------+---------+ 1353 | PUSH_PROMISE | No | Yes | No | Section | 1354 | | | | | 7.2.5 | 1355 +--------------+----------------+----------------+--------+---------+ 1356 | GOAWAY | Yes | No | No | Section | 1357 | | | | | 7.2.6 | 1358 +--------------+----------------+----------------+--------+---------+ 1359 | MAX_PUSH_ID | Yes | No | No | Section | 1360 | | | | | 7.2.7 | 1361 +--------------+----------------+----------------+--------+---------+ 1362 | Reserved | Yes | Yes | Yes | Section | 1363 | | | | | 7.2.8 | 1364 +--------------+----------------+----------------+--------+---------+ 1366 Table 1: HTTP/3 Frames and Stream Type Overview 1368 Certain frames can only occur as the first frame of a particular 1369 stream type; these are indicated in Table 1 with a (1). Specific 1370 guidance is provided in the relevant section. 1372 Note that, unlike QUIC frames, HTTP/3 frames can span multiple 1373 packets. 1375 7.1. Frame Layout 1377 All frames have the following format: 1379 HTTP/3 Frame Format { 1380 Type (i), 1381 Length (i), 1382 Frame Payload (..), 1383 } 1385 Figure 3: HTTP/3 Frame Format 1387 A frame includes the following fields: 1389 Type: A variable-length integer that identifies the frame type. 1391 Length: A variable-length integer that describes the length in bytes 1392 of the Frame Payload. 1394 Frame Payload: A payload, the semantics of which are determined by 1395 the Type field. 1397 Each frame's payload MUST contain exactly the fields identified in 1398 its description. A frame payload that contains additional bytes 1399 after the identified fields or a frame payload that terminates before 1400 the end of the identified fields MUST be treated as a connection 1401 error of type H3_FRAME_ERROR. 1403 When a stream terminates cleanly, if the last frame on the stream was 1404 truncated, this MUST be treated as a connection error (Section 8) of 1405 type H3_FRAME_ERROR. Streams which terminate abruptly may be reset 1406 at any point in a frame. 1408 7.2. Frame Definitions 1410 7.2.1. DATA 1412 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 1413 bytes associated with an HTTP request or response payload. 1415 DATA frames MUST be associated with an HTTP request or response. If 1416 a DATA frame is received on a control stream, the recipient MUST 1417 respond with a connection error (Section 8) of type 1418 H3_FRAME_UNEXPECTED. 1420 DATA Frame { 1421 Type (i) = 0x0, 1422 Length (i), 1423 Data (..), 1424 } 1426 Figure 4: DATA Frame 1428 7.2.2. HEADERS 1430 The HEADERS frame (type=0x1) is used to carry an HTTP field section, 1431 encoded using QPACK. See [QPACK] for more details. 1433 HEADERS Frame { 1434 Type (i) = 0x1, 1435 Length (i), 1436 Encoded Field Section (..), 1437 } 1439 Figure 5: HEADERS Frame 1441 HEADERS frames can only be sent on request / push streams. If a 1442 HEADERS frame is received on a control stream, the recipient MUST 1443 respond with a connection error (Section 8) of type 1444 H3_FRAME_UNEXPECTED. 1446 7.2.3. CANCEL_PUSH 1448 The CANCEL_PUSH frame (type=0x3) is used to request cancellation of a 1449 server push prior to the push stream being received. The CANCEL_PUSH 1450 frame identifies a server push by Push ID (see Section 7.2.5), 1451 encoded as a variable-length integer. 1453 When a client sends CANCEL_PUSH, it is indicating that it does not 1454 wish to receive the promised resource. The server SHOULD abort 1455 sending the resource, but the mechanism to do so depends on the state 1456 of the corresponding push stream. If the server has not yet created 1457 a push stream, it does not create one. If the push stream is open, 1458 the server SHOULD abruptly terminate that stream. If the push stream 1459 has already ended, the server MAY still abruptly terminate the stream 1460 or MAY take no action. 1462 When a server sends CANCEL_PUSH, it is indicating that it will not be 1463 fulfilling a promise. The client cannot expect the corresponding 1464 promise to be fulfilled, unless it has already received and processed 1465 the promised response. A server SHOULD send a CANCEL_PUSH even if it 1466 has opened the corresponding stream. 1468 Sending CANCEL_PUSH has no direct effect on the state of existing 1469 push streams. A client SHOULD NOT send a CANCEL_PUSH when it has 1470 already received a corresponding push stream. A push stream could 1471 arrive after a client has sent CANCEL_PUSH, because a server might 1472 not have processed the CANCEL_PUSH. The client SHOULD abort reading 1473 the stream with an error code of H3_REQUEST_CANCELLED. 1475 A CANCEL_PUSH frame is sent on the control stream. Receiving a 1476 CANCEL_PUSH frame on a stream other than the control stream MUST be 1477 treated as a connection error of type H3_FRAME_UNEXPECTED. 1479 CANCEL_PUSH Frame { 1480 Type (i) = 0x3, 1481 Length (i), 1482 Push ID (..), 1483 } 1485 Figure 6: CANCEL_PUSH Frame 1487 The CANCEL_PUSH frame carries a Push ID encoded as a variable-length 1488 integer. The Push ID identifies the server push that is being 1489 cancelled; see Section 7.2.5. If a CANCEL_PUSH frame is received 1490 which references a Push ID greater than currently allowed on the 1491 connection, this MUST be treated as a connection error of type 1492 H3_ID_ERROR. 1494 If the client receives a CANCEL_PUSH frame, that frame might identify 1495 a Push ID that has not yet been mentioned by a PUSH_PROMISE frame due 1496 to reordering. If a server receives a CANCEL_PUSH frame for a Push 1497 ID that has not yet been mentioned by a PUSH_PROMISE frame, this MUST 1498 be treated as a connection error of type H3_ID_ERROR. 1500 7.2.4. SETTINGS 1502 The SETTINGS frame (type=0x4) conveys configuration parameters that 1503 affect how endpoints communicate, such as preferences and constraints 1504 on peer behavior. Individually, a SETTINGS parameter can also be 1505 referred to as a "setting"; the identifier and value of each setting 1506 parameter can be referred to as a "setting identifier" and a "setting 1507 value". 1509 SETTINGS frames always apply to a connection, never a single stream. 1510 A SETTINGS frame MUST be sent as the first frame of each control 1511 stream (see Section 6.2.1) by each peer, and MUST NOT be sent 1512 subsequently. If an endpoint receives a second SETTINGS frame on the 1513 control stream, the endpoint MUST respond with a connection error of 1514 type H3_FRAME_UNEXPECTED. 1516 SETTINGS frames MUST NOT be sent on any stream other than the control 1517 stream. If an endpoint receives a SETTINGS frame on a different 1518 stream, the endpoint MUST respond with a connection error of type 1519 H3_FRAME_UNEXPECTED. 1521 SETTINGS parameters are not negotiated; they describe characteristics 1522 of the sending peer, which can be used by the receiving peer. 1523 However, a negotiation can be implied by the use of SETTINGS - each 1524 peer uses SETTINGS to advertise a set of supported values. The 1525 definition of the setting would describe how each peer combines the 1526 two sets to conclude which choice will be used. SETTINGS does not 1527 provide a mechanism to identify when the choice takes effect. 1529 Different values for the same parameter can be advertised by each 1530 peer. For example, a client might be willing to consume a very large 1531 response field section, while servers are more cautious about request 1532 size. 1534 The same setting identifier MUST NOT occur more than once in the 1535 SETTINGS frame. A receiver MAY treat the presence of duplicate 1536 setting identifiers as a connection error of type H3_SETTINGS_ERROR. 1538 The payload of a SETTINGS frame consists of zero or more parameters. 1539 Each parameter consists of a setting identifier and a value, both 1540 encoded as QUIC variable-length integers. 1542 Setting { 1543 Identifier (i), 1544 Value (i), 1545 } 1547 SETTINGS Frame { 1548 Type (i) = 0x4, 1549 Length (i), 1550 Setting (..) ..., 1551 } 1553 Figure 7: SETTINGS Frame 1555 An implementation MUST ignore the contents for any SETTINGS 1556 identifier it does not understand. 1558 7.2.4.1. Defined SETTINGS Parameters 1560 The following settings are defined in HTTP/3: 1562 SETTINGS_MAX_FIELD_SECTION_SIZE (0x6): The default value is 1563 unlimited. See Section 4.1.1 for usage. 1565 Setting identifiers of the format "0x1f * N + 0x21" for non-negative 1566 integer values of N are reserved to exercise the requirement that 1567 unknown identifiers be ignored. Such settings have no defined 1568 meaning. Endpoints SHOULD include at least one such setting in their 1569 SETTINGS frame. Endpoints MUST NOT consider such settings to have 1570 any meaning upon receipt. 1572 Because the setting has no defined meaning, the value of the setting 1573 can be any value the implementation selects. 1575 Additional settings can be defined by extensions to HTTP/3; see 1576 Section 9 for more details. 1578 7.2.4.2. Initialization 1580 An HTTP implementation MUST NOT send frames or requests which would 1581 be invalid based on its current understanding of the peer's settings. 1583 All settings begin at an initial value. Each endpoint SHOULD use 1584 these initial values to send messages before the peer's SETTINGS 1585 frame has arrived, as packets carrying the settings can be lost or 1586 delayed. When the SETTINGS frame arrives, any settings are changed 1587 to their new values. 1589 This removes the need to wait for the SETTINGS frame before sending 1590 messages. Endpoints MUST NOT require any data to be received from 1591 the peer prior to sending the SETTINGS frame; settings MUST be sent 1592 as soon as the transport is ready to send data. 1594 For servers, the initial value of each client setting is the default 1595 value. 1597 For clients using a 1-RTT QUIC connection, the initial value of each 1598 server setting is the default value. 1-RTT keys will always become 1599 available prior to SETTINGS arriving, even if the server sends 1600 SETTINGS immediately. Clients SHOULD NOT wait indefinitely for 1601 SETTINGS to arrive before sending requests, but SHOULD process 1602 received datagrams in order to increase the likelihood of processing 1603 SETTINGS before sending the first request. 1605 When a 0-RTT QUIC connection is being used, the initial value of each 1606 server setting is the value used in the previous session. Clients 1607 SHOULD store the settings the server provided in the connection where 1608 resumption information was provided, but MAY opt not to store 1609 settings in certain cases (e.g., if the session ticket is received 1610 before the SETTINGS frame). A client MUST comply with stored 1611 settings - or default values, if no values are stored - when 1612 attempting 0-RTT. Once a server has provided new settings, clients 1613 MUST comply with those values. 1615 A server can remember the settings that it advertised, or store an 1616 integrity-protected copy of the values in the ticket and recover the 1617 information when accepting 0-RTT data. A server uses the HTTP/3 1618 settings values in determining whether to accept 0-RTT data. If the 1619 server cannot determine that the settings remembered by a client are 1620 compatible with its current settings, it MUST NOT accept 0-RTT data. 1621 Remembered settings are compatible if a client complying with those 1622 settings would not violate the server's current settings. 1624 A server MAY accept 0-RTT and subsequently provide different settings 1625 in its SETTINGS frame. If 0-RTT data is accepted by the server, its 1626 SETTINGS frame MUST NOT reduce any limits or alter any values that 1627 might be violated by the client with its 0-RTT data. The server MUST 1628 include all settings which differ from their default values. If a 1629 server accepts 0-RTT but then sends settings that are not compatible 1630 with the previously specified settings, this MUST be treated as a 1631 connection error of type H3_SETTINGS_ERROR. If a server accepts 1632 0-RTT but then sends a SETTINGS frame that omits a setting value that 1633 the client understands (apart from reserved setting identifiers) that 1634 was previously specified to have a non-default value, this MUST be 1635 treated as a connection error of type H3_SETTINGS_ERROR. 1637 7.2.5. PUSH_PROMISE 1639 The PUSH_PROMISE frame (type=0x5) is used to carry a promised request 1640 header field section from server to client on a request stream, as in 1641 HTTP/2. 1643 PUSH_PROMISE Frame { 1644 Type (i) = 0x5, 1645 Length (i), 1646 Push ID (i), 1647 Encoded Field Section (..), 1648 } 1650 Figure 8: PUSH_PROMISE Frame 1652 The payload consists of: 1654 Push ID: A variable-length integer that identifies the server push 1655 operation. A Push ID is used in push stream headers 1656 (Section 4.4), CANCEL_PUSH frames (Section 7.2.3). 1658 Encoded Field Section: QPACK-encoded request header fields for the 1659 promised response. See [QPACK] for more details. 1661 A server MUST NOT use a Push ID that is larger than the client has 1662 provided in a MAX_PUSH_ID frame (Section 7.2.7). A client MUST treat 1663 receipt of a PUSH_PROMISE frame that contains a larger Push ID than 1664 the client has advertised as a connection error of H3_ID_ERROR. 1666 A server MAY use the same Push ID in multiple PUSH_PROMISE frames. 1667 If so, the decompressed request header sets MUST contain the same 1668 fields in the same order, and both the name and the value in each 1669 field MUST be exact matches. Clients SHOULD compare the request 1670 header sections for resources promised multiple times. If a client 1671 receives a Push ID that has already been promised and detects a 1672 mismatch, it MUST respond with a connection error of type 1673 H3_GENERAL_PROTOCOL_ERROR. If the decompressed field sections match 1674 exactly, the client SHOULD associate the pushed content with each 1675 stream on which a PUSH_PROMISE was received. 1677 Allowing duplicate references to the same Push ID is primarily to 1678 reduce duplication caused by concurrent requests. A server SHOULD 1679 avoid reusing a Push ID over a long period. Clients are likely to 1680 consume server push responses and not retain them for reuse over 1681 time. Clients that see a PUSH_PROMISE that uses a Push ID that they 1682 have already consumed and discarded are forced to ignore the 1683 PUSH_PROMISE. 1685 If a PUSH_PROMISE frame is received on the control stream, the client 1686 MUST respond with a connection error (Section 8) of type 1687 H3_FRAME_UNEXPECTED. 1689 A client MUST NOT send a PUSH_PROMISE frame. A server MUST treat the 1690 receipt of a PUSH_PROMISE frame as a connection error of type 1691 H3_FRAME_UNEXPECTED. 1693 See Section 4.4 for a description of the overall server push 1694 mechanism. 1696 7.2.6. GOAWAY 1698 The GOAWAY frame (type=0x7) is used to initiate graceful shutdown of 1699 a connection by either endpoint. GOAWAY allows an endpoint to stop 1700 accepting new requests or pushes while still finishing processing of 1701 previously received requests and pushes. This enables administrative 1702 actions, like server maintenance. GOAWAY by itself does not close a 1703 connection. 1705 GOAWAY Frame { 1706 Type (i) = 0x7, 1707 Length (i), 1708 Stream ID/Push ID (..), 1709 } 1711 Figure 9: GOAWAY Frame 1713 The GOAWAY frame is always sent on the control stream. In the server 1714 to client direction, it carries a QUIC Stream ID for a client- 1715 initiated bidirectional stream encoded as a variable-length integer. 1716 A client MUST treat receipt of a GOAWAY frame containing a Stream ID 1717 of any other type as a connection error of type H3_ID_ERROR. 1719 In the client to server direction, the GOAWAY frame carries a Push ID 1720 encoded as a variable-length integer. 1722 The GOAWAY frame applies to the connection, not a specific stream. A 1723 client MUST treat a GOAWAY frame on a stream other than the control 1724 stream as a connection error (Section 8) of type H3_FRAME_UNEXPECTED. 1726 See Section 5.2 for more information on the use of the GOAWAY frame. 1728 7.2.7. MAX_PUSH_ID 1730 The MAX_PUSH_ID frame (type=0xD) is used by clients to control the 1731 number of server pushes that the server can initiate. This sets the 1732 maximum value for a Push ID that the server can use in PUSH_PROMISE 1733 and CANCEL_PUSH frames. Consequently, this also limits the number of 1734 push streams that the server can initiate in addition to the limit 1735 maintained by the QUIC transport. 1737 The MAX_PUSH_ID frame is always sent on the control stream. Receipt 1738 of a MAX_PUSH_ID frame on any other stream MUST be treated as a 1739 connection error of type H3_FRAME_UNEXPECTED. 1741 A server MUST NOT send a MAX_PUSH_ID frame. A client MUST treat the 1742 receipt of a MAX_PUSH_ID frame as a connection error of type 1743 H3_FRAME_UNEXPECTED. 1745 The maximum Push ID is unset when a connection is created, meaning 1746 that a server cannot push until it receives a MAX_PUSH_ID frame. A 1747 client that wishes to manage the number of promised server pushes can 1748 increase the maximum Push ID by sending MAX_PUSH_ID frames as the 1749 server fulfills or cancels server pushes. 1751 MAX_PUSH_ID Frame { 1752 Type (i) = 0x1, 1753 Length (i), 1754 Push ID (..), 1755 } 1757 Figure 10: MAX_PUSH_ID Frame Payload 1759 The MAX_PUSH_ID frame carries a single variable-length integer that 1760 identifies the maximum value for a Push ID that the server can use; 1761 see Section 7.2.5. A MAX_PUSH_ID frame cannot reduce the maximum 1762 Push ID; receipt of a MAX_PUSH_ID that contains a smaller value than 1763 previously received MUST be treated as a connection error of type 1764 H3_ID_ERROR. 1766 7.2.8. Reserved Frame Types 1768 Frame types of the format "0x1f * N + 0x21" for non-negative integer 1769 values of N are reserved to exercise the requirement that unknown 1770 types be ignored (Section 9). These frames have no semantics, and 1771 can be sent on any open stream when application-layer padding is 1772 desired. They MAY also be sent on connections where no data is 1773 currently being transferred. Endpoints MUST NOT consider these 1774 frames to have any meaning upon receipt. 1776 The payload and length of the frames are selected in any manner the 1777 implementation chooses. 1779 Frame types which were used in HTTP/2 where there is no corresponding 1780 HTTP/3 frame have also been reserved (Section 11.2.1). These frame 1781 types MUST NOT be sent, and receipt MAY be treated as an error of 1782 type H3_FRAME_UNEXPECTED. 1784 8. Error Handling 1786 QUIC allows the application to abruptly terminate (reset) individual 1787 streams or the entire connection when an error is encountered. These 1788 are referred to as "stream errors" or "connection errors" and are 1789 described in more detail in [QUIC-TRANSPORT]. 1791 An endpoint MAY choose to treat a stream error as a connection error 1792 under certain circumstances. Implementations need to consider the 1793 impact on outstanding requests before making this choice. 1795 Because new error codes can be defined without negotiation (see 1796 Section 9), use of an error code in an unexpected context or receipt 1797 of an unknown error code MUST be treated as equivalent to 1798 H3_NO_ERROR. However, closing a stream can have other effects 1799 regardless of the error code; see Section 4.1. 1801 This section describes HTTP/3-specific error codes which can be used 1802 to express the cause of a connection or stream error. 1804 8.1. HTTP/3 Error Codes 1806 The following error codes are defined for use when abruptly 1807 terminating streams, aborting reading of streams, or immediately 1808 closing connections. 1810 H3_NO_ERROR (0x100): No error. This is used when the connection or 1811 stream needs to be closed, but there is no error to signal. 1813 H3_GENERAL_PROTOCOL_ERROR (0x101): Peer violated protocol 1814 requirements in a way which doesn't match a more specific error 1815 code, or endpoint declines to use the more specific error code. 1817 H3_INTERNAL_ERROR (0x102): An internal error has occurred in the 1818 HTTP stack. 1820 H3_STREAM_CREATION_ERROR (0x103): The endpoint detected that its 1821 peer created a stream that it will not accept. 1823 H3_CLOSED_CRITICAL_STREAM (0x104): A stream required by the 1824 connection was closed or reset. 1826 H3_FRAME_UNEXPECTED (0x105): A frame was received which was not 1827 permitted in the current state or on the current stream. 1829 H3_FRAME_ERROR (0x106): A frame that fails to satisfy layout 1830 requirements or with an invalid size was received. 1832 H3_EXCESSIVE_LOAD (0x107): The endpoint detected that its peer is 1833 exhibiting a behavior that might be generating excessive load. 1835 H3_ID_ERROR (0x108): A Stream ID or Push ID was used incorrectly, 1836 such as exceeding a limit, reducing a limit, or being reused. 1838 H3_SETTINGS_ERROR (0x109): An endpoint detected an error in the 1839 payload of a SETTINGS frame. 1841 H3_MISSING_SETTINGS (0x10A): No SETTINGS frame was received at the 1842 beginning of the control stream. 1844 H3_REQUEST_REJECTED (0x10B): A server rejected a request without 1845 performing any application processing. 1847 H3_REQUEST_CANCELLED (0x10C): The request or its response (including 1848 pushed response) is cancelled. 1850 H3_REQUEST_INCOMPLETE (0x10D): The client's stream terminated 1851 without containing a fully-formed request. 1853 H3_CONNECT_ERROR (0x10F): The connection established in response to 1854 a CONNECT request was reset or abnormally closed. 1856 H3_VERSION_FALLBACK (0x110): The requested operation cannot be 1857 served over HTTP/3. The peer should retry over HTTP/1.1. 1859 Error codes of the format "0x1f * N + 0x21" for non-negative integer 1860 values of N are reserved to exercise the requirement that unknown 1861 error codes be treated as equivalent to H3_NO_ERROR (Section 9). 1862 Implementations SHOULD select an error code from this space with some 1863 probability when they would have sent H3_NO_ERROR. 1865 9. Extensions to HTTP/3 1867 HTTP/3 permits extension of the protocol. Within the limitations 1868 described in this section, protocol extensions can be used to provide 1869 additional services or alter any aspect of the protocol. Extensions 1870 are effective only within the scope of a single HTTP/3 connection. 1872 This applies to the protocol elements defined in this document. This 1873 does not affect the existing options for extending HTTP, such as 1874 defining new methods, status codes, or fields. 1876 Extensions are permitted to use new frame types (Section 7.2), new 1877 settings (Section 7.2.4.1), new error codes (Section 8), or new 1878 unidirectional stream types (Section 6.2). Registries are 1879 established for managing these extension points: frame types 1880 (Section 11.2.1), settings (Section 11.2.2), error codes 1881 (Section 11.2.3), and stream types (Section 11.2.4). 1883 Implementations MUST ignore unknown or unsupported values in all 1884 extensible protocol elements. Implementations MUST discard frames 1885 and unidirectional streams that have unknown or unsupported types. 1886 This means that any of these extension points can be safely used by 1887 extensions without prior arrangement or negotiation. However, where 1888 a known frame type is required to be in a specific location, such as 1889 the SETTINGS frame as the first frame of the control stream (see 1890 Section 6.2.1), an unknown frame type does not satisfy that 1891 requirement and SHOULD be treated as an error. 1893 Extensions that could change the semantics of existing protocol 1894 components MUST be negotiated before being used. For example, an 1895 extension that changes the layout of the HEADERS frame cannot be used 1896 until the peer has given a positive signal that this is acceptable. 1897 Coordinating when such a revised layout comes into effect could prove 1898 complex. As such, allocating new identifiers for new definitions of 1899 existing protocol elements is likely to be more effective. 1901 This document doesn't mandate a specific method for negotiating the 1902 use of an extension but notes that a setting (Section 7.2.4.1) could 1903 be used for that purpose. If both peers set a value that indicates 1904 willingness to use the extension, then the extension can be used. If 1905 a setting is used for extension negotiation, the default value MUST 1906 be defined in such a fashion that the extension is disabled if the 1907 setting is omitted. 1909 10. Security Considerations 1911 The security considerations of HTTP/3 should be comparable to those 1912 of HTTP/2 with TLS. However, many of the considerations from 1913 Section 10 of [HTTP2] apply to [QUIC-TRANSPORT] and are discussed in 1914 that document. 1916 10.1. Server Authority 1918 HTTP/3 relies on the HTTP definition of authority. The security 1919 considerations of establishing authority are discussed in 1920 Section 11.1 of [SEMANTICS]. 1922 10.2. Cross-Protocol Attacks 1924 The use of ALPN in the TLS and QUIC handshakes establishes the target 1925 application protocol before application-layer bytes are processed. 1926 Because all QUIC packets are encrypted, it is difficult for an 1927 attacker to control the plaintext bytes of an HTTP/3 connection which 1928 could be used in a cross-protocol attack on a plaintext protocol. 1930 10.3. Intermediary Encapsulation Attacks 1932 The HTTP/3 field encoding allows the expression of names that are not 1933 valid field names in the syntax used by HTTP (Section 4.3 of 1934 [SEMANTICS]). Requests or responses containing invalid field names 1935 MUST be treated as malformed (Section 4.1.3). An intermediary 1936 therefore cannot translate an HTTP/3 request or response containing 1937 an invalid field name into an HTTP/1.1 message. 1939 Similarly, HTTP/3 allows field values that are not valid. While most 1940 of the values that can be encoded will not alter field parsing, 1941 carriage return (CR, ASCII 0xd), line feed (LF, ASCII 0xa), and the 1942 zero character (NUL, ASCII 0x0) might be exploited by an attacker if 1943 they are translated verbatim. Any request or response that contains 1944 a character not permitted in a field value MUST be treated as 1945 malformed (Section 4.1.3). Valid characters are defined by the 1946 "field-content" ABNF rule in Section 4.4 of [SEMANTICS]. 1948 10.4. Cacheability of Pushed Responses 1950 Pushed responses do not have an explicit request from the client; the 1951 request is provided by the server in the PUSH_PROMISE frame. 1953 Caching responses that are pushed is possible based on the guidance 1954 provided by the origin server in the Cache-Control header field. 1955 However, this can cause issues if a single server hosts more than one 1956 tenant. For example, a server might offer multiple users each a 1957 small portion of its URI space. 1959 Where multiple tenants share space on the same server, that server 1960 MUST ensure that tenants are not able to push representations of 1961 resources that they do not have authority over. Failure to enforce 1962 this would allow a tenant to provide a representation that would be 1963 served out of cache, overriding the actual representation that the 1964 authoritative tenant provides. 1966 Pushed responses for which an origin server is not authoritative (see 1967 Section 3.4) MUST NOT be used or cached. 1969 10.5. Denial-of-Service Considerations 1971 An HTTP/3 connection can demand a greater commitment of resources to 1972 operate than an HTTP/1.1 or HTTP/2 connection. The use of field 1973 compression and flow control depend on a commitment of resources for 1974 storing a greater amount of state. Settings for these features 1975 ensure that memory commitments for these features are strictly 1976 bounded. 1978 The number of PUSH_PROMISE frames is constrained in a similar 1979 fashion. A client that accepts server push SHOULD limit the number 1980 of Push IDs it issues at a time. 1982 Processing capacity cannot be guarded as effectively as state 1983 capacity. 1985 The ability to send undefined protocol elements which the peer is 1986 required to ignore can be abused to cause a peer to expend additional 1987 processing time. This might be done by setting multiple undefined 1988 SETTINGS parameters, unknown frame types, or unknown stream types. 1989 Note, however, that some uses are entirely legitimate, such as 1990 optional-to-understand extensions and padding to increase resistance 1991 to traffic analysis. 1993 Compression of field sections also offers some opportunities to waste 1994 processing resources; see Section 7 of [QPACK] for more details on 1995 potential abuses. 1997 All these features - i.e., server push, unknown protocol elements, 1998 field compression - have legitimate uses. These features become a 1999 burden only when they are used unnecessarily or to excess. 2001 An endpoint that doesn't monitor this behavior exposes itself to a 2002 risk of denial-of-service attack. Implementations SHOULD track the 2003 use of these features and set limits on their use. An endpoint MAY 2004 treat activity that is suspicious as a connection error (Section 8) 2005 of type H3_EXCESSIVE_LOAD, but false positives will result in 2006 disrupting valid connections and requests. 2008 10.5.1. Limits on Field Section Size 2010 A large field section (Section 4.1) can cause an implementation to 2011 commit a large amount of state. Header fields that are critical for 2012 routing can appear toward the end of a header field section, which 2013 prevents streaming of the header field section to its ultimate 2014 destination. This ordering and other reasons, such as ensuring cache 2015 correctness, mean that an endpoint likely needs to buffer the entire 2016 header field section. Since there is no hard limit to the size of a 2017 field section, some endpoints could be forced to commit a large 2018 amount of available memory for header fields. 2020 An endpoint can use the SETTINGS_MAX_HEADER_LIST_SIZE 2021 (Section 7.2.4.1) setting to advise peers of limits that might apply 2022 on the size of field sections. This setting is only advisory, so 2023 endpoints MAY choose to send field sections that exceed this limit 2024 and risk having the request or response being treated as malformed. 2025 This setting is specific to a connection, so any request or response 2026 could encounter a hop with a lower, unknown limit. An intermediary 2027 can attempt to avoid this problem by passing on values presented by 2028 different peers, but they are not obligated to do so. 2030 A server that receives a larger field section than it is willing to 2031 handle can send an HTTP 431 (Request Header Fields Too Large) status 2032 code [RFC6585]. A client can discard responses that it cannot 2033 process. 2035 10.5.2. CONNECT Issues 2037 The CONNECT method can be used to create disproportionate load on an 2038 proxy, since stream creation is relatively inexpensive when compared 2039 to the creation and maintenance of a TCP connection. A proxy might 2040 also maintain some resources for a TCP connection beyond the closing 2041 of the stream that carries the CONNECT request, since the outgoing 2042 TCP connection remains in the TIME_WAIT state. Therefore, a proxy 2043 cannot rely on QUIC stream limits alone to control the resources 2044 consumed by CONNECT requests. 2046 10.6. Use of Compression 2048 Compression can allow an attacker to recover secret data when it is 2049 compressed in the same context as data under attacker control. 2050 HTTP/3 enables compression of fields (Section 4.1.1); the following 2051 concerns also apply to the use of HTTP compressed content-codings; 2052 see Section 6.1.2 of [SEMANTICS]. 2054 There are demonstrable attacks on compression that exploit the 2055 characteristics of the web (e.g., [BREACH]). The attacker induces 2056 multiple requests containing varying plaintext, observing the length 2057 of the resulting ciphertext in each, which reveals a shorter length 2058 when a guess about the secret is correct. 2060 Implementations communicating on a secure channel MUST NOT compress 2061 content that includes both confidential and attacker-controlled data 2062 unless separate compression dictionaries are used for each source of 2063 data. Compression MUST NOT be used if the source of data cannot be 2064 reliably determined. 2066 Further considerations regarding the compression of fields sections 2067 are described in [QPACK]. 2069 10.7. Padding and Traffic Analysis 2071 Padding can be used to obscure the exact size of frame content and is 2072 provided to mitigate specific attacks within HTTP, for example, 2073 attacks where compressed content includes both attacker-controlled 2074 plaintext and secret data (e.g., [BREACH]). 2076 Where HTTP/2 employs PADDING frames and Padding fields in other 2077 frames to make a connection more resistant to traffic analysis, 2078 HTTP/3 can either rely on transport-layer padding or employ the 2079 reserved frame and stream types discussed in Section 7.2.8 and 2080 Section 6.2.3. These methods of padding produce different results in 2081 terms of the granularity of padding, how padding is arranged in 2082 relation to the information that is being protected, whether padding 2083 is applied in the case of packet loss, and how an implementation 2084 might control padding. Redundant padding could even be 2085 counterproductive. 2087 To mitigate attacks that rely on compression, disabling or limiting 2088 compression might be preferable to padding as a countermeasure. 2090 Use of padding can result in less protection than might seem 2091 immediately obvious. At best, padding only makes it more difficult 2092 for an attacker to infer length information by increasing the number 2093 of frames an attacker has to observe. Incorrectly implemented 2094 padding schemes can be easily defeated. In particular, randomized 2095 padding with a predictable distribution provides very little 2096 protection; similarly, padding payloads to a fixed size exposes 2097 information as payload sizes cross the fixed-sized boundary, which 2098 could be possible if an attacker can control plaintext. 2100 10.8. Frame Parsing 2102 Several protocol elements contain nested length elements, typically 2103 in the form of frames with an explicit length containing variable- 2104 length integers. This could pose a security risk to an incautious 2105 implementer. An implementation MUST ensure that the length of a 2106 frame exactly matches the length of the fields it contains. 2108 10.9. Early Data 2110 The use of 0-RTT with HTTP/3 creates an exposure to replay attack. 2111 The anti-replay mitigations in [HTTP-REPLAY] MUST be applied when 2112 using HTTP/3 with 0-RTT. 2114 10.10. Migration 2116 Certain HTTP implementations use the client address for logging or 2117 access-control purposes. Since a QUIC client's address might change 2118 during a connection (and future versions might support simultaneous 2119 use of multiple addresses), such implementations will need to either 2120 actively retrieve the client's current address or addresses when they 2121 are relevant or explicitly accept that the original address might 2122 change. 2124 10.11. Privacy Considerations 2126 Several characteristics of HTTP/3 provide an observer an opportunity 2127 to correlate actions of a single client or server over time. These 2128 include the value of settings, the timing of reactions to stimulus, 2129 and the handling of any features that are controlled by settings. 2131 As far as these create observable differences in behavior, they could 2132 be used as a basis for fingerprinting a specific client. 2134 HTTP/3's preference for using a single QUIC connection allows 2135 correlation of a user's activity on a site. Reusing connections for 2136 different origins allows for correlation of activity across those 2137 origins. 2139 Several features of QUIC solicit immediate responses and can be used 2140 by an endpoint to measure latency to their peer; this might have 2141 privacy implications in certain scenarios. 2143 11. IANA Considerations 2145 This document registers a new ALPN protocol ID (Section 11.1) and 2146 creates new registries that manage the assignment of codepoints in 2147 HTTP/3. 2149 11.1. Registration of HTTP/3 Identification String 2151 This document creates a new registration for the identification of 2152 HTTP/3 in the "Application Layer Protocol Negotiation (ALPN) Protocol 2153 IDs" registry established in [RFC7301]. 2155 The "h3" string identifies HTTP/3: 2157 Protocol: HTTP/3 2159 Identification Sequence: 0x68 0x33 ("h3") 2161 Specification: This document 2163 11.2. New Registries 2165 New registries created in this document operate under the QUIC 2166 registration policy documented in Section 22.1 of [QUIC-TRANSPORT]. 2167 These registries all include the common set of fields listed in 2168 Section 22.1.1 of [QUIC-TRANSPORT]. 2170 The initial allocations in these registries created in this document 2171 are all assigned permanent status and list as contact both the IESG 2172 (iesg@ietf.org) and the HTTP working group (ietf-http-wg@w3.org). 2174 11.2.1. Frame Types 2176 This document establishes a registry for HTTP/3 frame type codes. 2177 The "HTTP/3 Frame Type" registry governs a 62-bit space. This 2178 registry follows the QUIC registry policy; see Section 11.2. 2179 Permanent registrations in this registry are assigned using the 2180 Specification Required policy [RFC8126], except for values between 2181 0x00 and 0x3f (in hexadecimal; inclusive), which are assigned using 2182 Standards Action or IESG Approval as defined in Section 4.9 and 4.10 2183 of [RFC8126]. 2185 While this registry is separate from the "HTTP/2 Frame Type" registry 2186 defined in [HTTP2], it is preferable that the assignments parallel 2187 each other where the code spaces overlap. If an entry is present in 2188 only one registry, every effort SHOULD be made to avoid assigning the 2189 corresponding value to an unrelated operation. 2191 In addition to common fields as described in Section 11.2, permanent 2192 registrations in this registry MUST include the following field: 2194 Frame Type: A name or label for the frame type. 2196 Specifications of frame types MUST include a description of the frame 2197 layout and its semantics, including any parts of the frame that are 2198 conditionally present. 2200 The entries in Table 2 are registered by this document. 2202 +--------------+-------+---------------+ 2203 | Frame Type | Value | Specification | 2204 +==============+=======+===============+ 2205 | DATA | 0x0 | Section 7.2.1 | 2206 +--------------+-------+---------------+ 2207 | HEADERS | 0x1 | Section 7.2.2 | 2208 +--------------+-------+---------------+ 2209 | Reserved | 0x2 | N/A | 2210 +--------------+-------+---------------+ 2211 | CANCEL_PUSH | 0x3 | Section 7.2.3 | 2212 +--------------+-------+---------------+ 2213 | SETTINGS | 0x4 | Section 7.2.4 | 2214 +--------------+-------+---------------+ 2215 | PUSH_PROMISE | 0x5 | Section 7.2.5 | 2216 +--------------+-------+---------------+ 2217 | Reserved | 0x6 | N/A | 2218 +--------------+-------+---------------+ 2219 | GOAWAY | 0x7 | Section 7.2.6 | 2220 +--------------+-------+---------------+ 2221 | Reserved | 0x8 | N/A | 2222 +--------------+-------+---------------+ 2223 | Reserved | 0x9 | N/A | 2224 +--------------+-------+---------------+ 2225 | MAX_PUSH_ID | 0xD | Section 7.2.7 | 2226 +--------------+-------+---------------+ 2228 Table 2: Initial HTTP/3 Frame Types 2230 Additionally, each code of the format "0x1f * N + 0x21" for non- 2231 negative integer values of N (that is, 0x21, 0x40, ..., through 2232 0x3FFFFFFFFFFFFFFE) MUST NOT be assigned by IANA. 2234 11.2.2. Settings Parameters 2236 This document establishes a registry for HTTP/3 settings. The 2237 "HTTP/3 Settings" registry governs a 62-bit space. This registry 2238 follows the QUIC registry policy; see Section 11.2. Permanent 2239 registrations in this registry are assigned using the Specification 2240 Required policy [RFC8126], except for values between 0x00 and 0x3f 2241 (in hexadecimal; inclusive), which are assigned using Standards 2242 Action or IESG Approval as defined in Section 4.9 and 4.10 of 2243 [RFC8126]. 2245 While this registry is separate from the "HTTP/2 Settings" registry 2246 defined in [HTTP2], it is preferable that the assignments parallel 2247 each other. If an entry is present in only one registry, every 2248 effort SHOULD be made to avoid assigning the corresponding value to 2249 an unrelated operation. 2251 In addition to common fields as described in Section 11.2, permanent 2252 registrations in this registry MUST include the following fields: 2254 Setting Name: A symbolic name for the setting. Specifying a setting 2255 name is optional. 2257 Default: The value of the setting unless otherwise indicated. A 2258 default SHOULD be the most restrictive possible value. 2260 The entries in Table 3 are registered by this document. 2262 +------------------------+-------+-----------------+-----------+ 2263 | Setting Name | Value | Specification | Default | 2264 +========================+=======+=================+===========+ 2265 | Reserved | 0x2 | N/A | N/A | 2266 +------------------------+-------+-----------------+-----------+ 2267 | Reserved | 0x3 | N/A | N/A | 2268 +------------------------+-------+-----------------+-----------+ 2269 | Reserved | 0x4 | N/A | N/A | 2270 +------------------------+-------+-----------------+-----------+ 2271 | Reserved | 0x5 | N/A | N/A | 2272 +------------------------+-------+-----------------+-----------+ 2273 | MAX_FIELD_SECTION_SIZE | 0x6 | Section 7.2.4.1 | Unlimited | 2274 +------------------------+-------+-----------------+-----------+ 2276 Table 3: Initial HTTP/3 Settings 2278 Additionally, each code of the format "0x1f * N + 0x21" for non- 2279 negative integer values of N (that is, 0x21, 0x40, ..., through 2280 0x3FFFFFFFFFFFFFFE) MUST NOT be assigned by IANA. 2282 11.2.3. Error Codes 2284 This document establishes a registry for HTTP/3 error codes. The 2285 "HTTP/3 Error Code" registry manages a 62-bit space. This registry 2286 follows the QUIC registry policy; see Section 11.2. Permanent 2287 registrations in this registry are assigned using the Specification 2288 Required policy [RFC8126], except for values between 0x00 and 0x3f 2289 (in hexadecimal; inclusive), which are assigned using Standards 2290 Action or IESG Approval as defined in Section 4.9 and 4.10 of 2291 [RFC8126]. 2293 Registrations for error codes are required to include a description 2294 of the error code. An expert reviewer is advised to examine new 2295 registrations for possible duplication with existing error codes. 2296 Use of existing registrations is to be encouraged, but not mandated. 2298 In addition to common fields as described in Section 11.2, permanent 2299 registrations in this registry MUST include the following fields: 2301 Name: A name for the error code. Specifying an error code name is 2302 optional. 2304 Description: A brief description of the error code semantics. 2306 The entries in the Table 4 are registered by this document. 2308 +---------------------------+--------+--------------+---------------+ 2309 | Name | Value | Description | Specification | 2310 +===========================+========+==============+===============+ 2311 | H3_NO_ERROR | 0x0100 | No error | Section 8.1 | 2312 +---------------------------+--------+--------------+---------------+ 2313 | H3_GENERAL_PROTOCOL_ERROR | 0x0101 | General | Section 8.1 | 2314 | | | protocol | | 2315 | | | error | | 2316 +---------------------------+--------+--------------+---------------+ 2317 | H3_INTERNAL_ERROR | 0x0102 | Internal | Section 8.1 | 2318 | | | error | | 2319 +---------------------------+--------+--------------+---------------+ 2320 | H3_STREAM_CREATION_ERROR | 0x0103 | Stream | Section 8.1 | 2321 | | | creation | | 2322 | | | error | | 2323 +---------------------------+--------+--------------+---------------+ 2324 | H3_CLOSED_CRITICAL_STREAM | 0x0104 | Critical | Section 8.1 | 2325 | | | stream was | | 2326 | | | closed | | 2327 +---------------------------+--------+--------------+---------------+ 2328 | H3_FRAME_UNEXPECTED | 0x0105 | Frame not | Section 8.1 | 2329 | | | permitted | | 2330 | | | in the | | 2331 | | | current | | 2332 | | | state | | 2333 +---------------------------+--------+--------------+---------------+ 2334 | H3_FRAME_ERROR | 0x0106 | Frame | Section 8.1 | 2335 | | | violated | | 2336 | | | layout or | | 2337 | | | size rules | | 2338 +---------------------------+--------+--------------+---------------+ 2339 | H3_EXCESSIVE_LOAD | 0x0107 | Peer | Section 8.1 | 2340 | | | generating | | 2341 | | | excessive | | 2342 | | | load | | 2343 +---------------------------+--------+--------------+---------------+ 2344 | H3_ID_ERROR | 0x0108 | An | Section 8.1 | 2345 | | | identifier | | 2346 | | | was used | | 2347 | | | incorrectly | | 2348 +---------------------------+--------+--------------+---------------+ 2349 | H3_SETTINGS_ERROR | 0x0109 | SETTINGS | Section 8.1 | 2350 | | | frame | | 2351 | | | contained | | 2352 | | | invalid | | 2353 | | | values | | 2354 +---------------------------+--------+--------------+---------------+ 2355 | H3_MISSING_SETTINGS | 0x010A | No SETTINGS | Section 8.1 | 2356 | | | frame | | 2357 | | | received | | 2358 +---------------------------+--------+--------------+---------------+ 2359 | H3_REQUEST_REJECTED | 0x010B | Request not | Section 8.1 | 2360 | | | processed | | 2361 +---------------------------+--------+--------------+---------------+ 2362 | H3_REQUEST_CANCELLED | 0x010C | Data no | Section 8.1 | 2363 | | | longer | | 2364 | | | needed | | 2365 +---------------------------+--------+--------------+---------------+ 2366 | H3_REQUEST_INCOMPLETE | 0x010D | Stream | Section 8.1 | 2367 | | | terminated | | 2368 | | | early | | 2369 +---------------------------+--------+--------------+---------------+ 2370 | H3_CONNECT_ERROR | 0x010F | TCP reset | Section 8.1 | 2371 | | | or error on | | 2372 | | | CONNECT | | 2373 | | | request | | 2374 +---------------------------+--------+--------------+---------------+ 2375 | H3_VERSION_FALLBACK | 0x0110 | Retry over | Section 8.1 | 2376 | | | HTTP/1.1 | | 2377 +---------------------------+--------+--------------+---------------+ 2379 Table 4: Initial HTTP/3 Error Codes 2381 Additionally, each code of the format "0x1f * N + 0x21" for non- 2382 negative integer values of N (that is, 0x21, 0x40, ..., through 2383 0x3FFFFFFFFFFFFFFE) MUST NOT be assigned by IANA. 2385 11.2.4. Stream Types 2387 This document establishes a registry for HTTP/3 unidirectional stream 2388 types. The "HTTP/3 Stream Type" registry governs a 62-bit space. 2389 This registry follows the QUIC registry policy; see Section 11.2. 2390 Permanent registrations in this registry are assigned using the 2391 Specification Required policy [RFC8126], except for values between 2392 0x00 and 0x3f (in hexadecimal; inclusive), which are assigned using 2393 Standards Action or IESG Approval as defined in Section 4.9 and 4.10 2394 of [RFC8126]. 2396 In addition to common fields as described in Section 11.2, permanent 2397 registrations in this registry MUST include the following fields: 2399 Stream Type: A name or label for the stream type. 2401 Sender: Which endpoint on a connection may initiate a stream of this 2402 type. Values are "Client", "Server", or "Both". 2404 Specifications for permanent registrations MUST include a description 2405 of the stream type, including the layout semantics of the stream 2406 contents. 2408 The entries in the following table are registered by this document. 2410 +----------------+-------+---------------+--------+ 2411 | Stream Type | Value | Specification | Sender | 2412 +================+=======+===============+========+ 2413 | Control Stream | 0x00 | Section 6.2.1 | Both | 2414 +----------------+-------+---------------+--------+ 2415 | Push Stream | 0x01 | Section 4.4 | Server | 2416 +----------------+-------+---------------+--------+ 2418 Table 5 2420 Additionally, each code of the format "0x1f * N + 0x21" for non- 2421 negative integer values of N (that is, 0x21, 0x40, ..., through 2422 0x3FFFFFFFFFFFFFFE) MUST NOT be assigned by IANA. 2424 12. References 2426 12.1. Normative References 2428 [ALTSVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP 2429 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 2430 April 2016, . 2432 [CACHING] Fielding, R., Nottingham, M., and J. Reschke, "HTTP 2433 Caching", Work in Progress, Internet-Draft, draft-ietf- 2434 httpbis-cache-08, 26 May 2020, . 2437 [HTTP-REPLAY] 2438 Thomson, M., Nottingham, M., and W. Tarreau, "Using Early 2439 Data in HTTP", RFC 8470, DOI 10.17487/RFC8470, September 2440 2018, . 2442 [QPACK] Krasic, C., Bishop, M., and A. Frindell, Ed., "QPACK: 2443 Header Compression for HTTP over QUIC", Work in Progress, 2444 Internet-Draft, draft-ietf-quic-qpack-16, 9 June 2020, 2445 . 2447 [QUIC-TRANSPORT] 2448 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 2449 Multiplexed and Secure Transport", Work in Progress, 2450 Internet-Draft, draft-ietf-quic-transport-28, 9 June 2020, 2451 . 2454 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2455 RFC 793, DOI 10.17487/RFC0793, September 1981, 2456 . 2458 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2459 Requirement Levels", BCP 14, RFC 2119, 2460 DOI 10.17487/RFC2119, March 1997, 2461 . 2463 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2464 Resource Identifier (URI): Generic Syntax", STD 66, 2465 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2466 . 2468 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2469 Specifications: ABNF", STD 68, RFC 5234, 2470 DOI 10.17487/RFC5234, January 2008, 2471 . 2473 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 2474 Extensions: Extension Definitions", RFC 6066, 2475 DOI 10.17487/RFC6066, January 2011, 2476 . 2478 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2479 Verification of Domain-Based Application Service Identity 2480 within Internet Public Key Infrastructure Using X.509 2481 (PKIX) Certificates in the Context of Transport Layer 2482 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2483 2011, . 2485 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2486 DOI 10.17487/RFC6265, April 2011, 2487 . 2489 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2490 Writing an IANA Considerations Section in RFCs", BCP 26, 2491 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2492 . 2494 [RFC8164] Nottingham, M. and M. Thomson, "Opportunistic Security for 2495 HTTP/2", RFC 8164, DOI 10.17487/RFC8164, May 2017, 2496 . 2498 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2499 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2500 May 2017, . 2502 [SEMANTICS] 2503 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 2504 Semantics", Work in Progress, Internet-Draft, draft-ietf- 2505 httpbis-semantics-08, 26 May 2020, . 2508 12.2. Informative References 2510 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 2511 CRIME Attack", July 2013, 2512 . 2515 [HPACK] Peon, R. and H. Ruellan, "HPACK: Header Compression for 2516 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 2517 . 2519 [HTTP11] Fielding, R., Nottingham, M., and J. Reschke, "HTTP/1.1 2520 Messaging", Work in Progress, Internet-Draft, draft-ietf- 2521 httpbis-messaging-08, 26 May 2020, . 2524 [HTTP2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 2525 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 2526 DOI 10.17487/RFC7540, May 2015, 2527 . 2529 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 2530 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 2531 . 2533 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 2534 "Transport Layer Security (TLS) Application-Layer Protocol 2535 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 2536 July 2014, . 2538 [TFO] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 2539 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 2540 . 2542 [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2543 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2544 . 2546 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2547 Resource Identifier (URI): Generic Syntax", STD 66, 2548 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2549 . 2551 Appendix A. Considerations for Transitioning from HTTP/2 2553 HTTP/3 is strongly informed by HTTP/2, and bears many similarities. 2554 This section describes the approach taken to design HTTP/3, points 2555 out important differences from HTTP/2, and describes how to map 2556 HTTP/2 extensions into HTTP/3. 2558 HTTP/3 begins from the premise that similarity to HTTP/2 is 2559 preferable, but not a hard requirement. HTTP/3 departs from HTTP/2 2560 where QUIC differs from TCP, either to take advantage of QUIC 2561 features (like streams) or to accommodate important shortcomings 2562 (such as a lack of total ordering). These differences make HTTP/3 2563 similar to HTTP/2 in key aspects, such as the relationship of 2564 requests and responses to streams. However, the details of the 2565 HTTP/3 design are substantially different than HTTP/2. 2567 These departures are noted in this section. 2569 A.1. Streams 2571 HTTP/3 permits use of a larger number of streams (2^62-1) than 2572 HTTP/2. The considerations about exhaustion of stream identifier 2573 space apply, though the space is significantly larger such that it is 2574 likely that other limits in QUIC are reached first, such as the limit 2575 on the connection flow control window. 2577 In contrast to HTTP/2, stream concurrency in HTTP/3 is managed by 2578 QUIC. QUIC considers a stream closed when all data has been received 2579 and sent data has been acknowledged by the peer. HTTP/2 considers a 2580 stream closed when the frame containing the END_STREAM bit has been 2581 committed to the transport. As a result, the stream for an 2582 equivalent exchange could remain "active" for a longer period of 2583 time. HTTP/3 servers might choose to permit a larger number of 2584 concurrent client-initiated bidirectional streams to achieve 2585 equivalent concurrency to HTTP/2, depending on the expected usage 2586 patterns. 2588 Due to the presence of other unidirectional stream types, HTTP/3 does 2589 not rely exclusively on the number of concurrent unidirectional 2590 streams to control the number of concurrent in-flight pushes. 2591 Instead, HTTP/3 clients use the MAX_PUSH_ID frame to control the 2592 number of pushes received from an HTTP/3 server. 2594 A.2. HTTP Frame Types 2596 Many framing concepts from HTTP/2 can be elided on QUIC, because the 2597 transport deals with them. Because frames are already on a stream, 2598 they can omit the stream number. Because frames do not block 2599 multiplexing (QUIC's multiplexing occurs below this layer), the 2600 support for variable-maximum-length packets can be removed. Because 2601 stream termination is handled by QUIC, an END_STREAM flag is not 2602 required. This permits the removal of the Flags field from the 2603 generic frame layout. 2605 Frame payloads are largely drawn from [HTTP2]. However, QUIC 2606 includes many features (e.g., flow control) which are also present in 2607 HTTP/2. In these cases, the HTTP mapping does not re-implement them. 2608 As a result, several HTTP/2 frame types are not required in HTTP/3. 2609 Where an HTTP/2-defined frame is no longer used, the frame ID has 2610 been reserved in order to maximize portability between HTTP/2 and 2611 HTTP/3 implementations. However, even equivalent frames between the 2612 two mappings are not identical. 2614 Many of the differences arise from the fact that HTTP/2 provides an 2615 absolute ordering between frames across all streams, while QUIC 2616 provides this guarantee on each stream only. As a result, if a frame 2617 type makes assumptions that frames from different streams will still 2618 be received in the order sent, HTTP/3 will break them. 2620 Some examples of feature adaptations are described below, as well as 2621 general guidance to extension frame implementors converting an HTTP/2 2622 extension to HTTP/3. 2624 A.2.1. Prioritization Differences 2626 HTTP/2 specifies priority assignments in PRIORITY frames and 2627 (optionally) in HEADERS frames. HTTP/3 does not provide a means of 2628 signaling priority. 2630 Note that while there is no explicit signaling for priority, this 2631 does not mean that prioritization is not important for achieving good 2632 performance. 2634 A.2.2. Field Compression Differences 2636 HPACK was designed with the assumption of in-order delivery. A 2637 sequence of encoded field sections must arrive (and be decoded) at an 2638 endpoint in the same order in which they were encoded. This ensures 2639 that the dynamic state at the two endpoints remains in sync. 2641 Because this total ordering is not provided by QUIC, HTTP/3 uses a 2642 modified version of HPACK, called QPACK. QPACK uses a single 2643 unidirectional stream to make all modifications to the dynamic table, 2644 ensuring a total order of updates. All frames which contain encoded 2645 fields merely reference the table state at a given time without 2646 modifying it. 2648 [QPACK] provides additional details. 2650 A.2.3. Guidance for New Frame Type Definitions 2652 Frame type definitions in HTTP/3 often use the QUIC variable-length 2653 integer encoding. In particular, Stream IDs use this encoding, which 2654 allows for a larger range of possible values than the encoding used 2655 in HTTP/2. Some frames in HTTP/3 use an identifier rather than a 2656 Stream ID (e.g., Push IDs). Redefinition of the encoding of 2657 extension frame types might be necessary if the encoding includes a 2658 Stream ID. 2660 Because the Flags field is not present in generic HTTP/3 frames, 2661 those frames which depend on the presence of flags need to allocate 2662 space for flags as part of their frame payload. 2664 Other than this issue, frame type HTTP/2 extensions are typically 2665 portable to QUIC simply by replacing Stream 0 in HTTP/2 with a 2666 control stream in HTTP/3. HTTP/3 extensions will not assume 2667 ordering, but would not be harmed by ordering, and would be portable 2668 to HTTP/2 in the same manner. 2670 A.2.4. Mapping Between HTTP/2 and HTTP/3 Frame Types 2672 DATA (0x0): Padding is not defined in HTTP/3 frames. See 2673 Section 7.2.1. 2675 HEADERS (0x1): The PRIORITY region of HEADERS is not defined in 2676 HTTP/3 frames. Padding is not defined in HTTP/3 frames. See 2677 Section 7.2.2. 2679 PRIORITY (0x2): As described in Appendix A.2.1, HTTP/3 does not 2680 provide a means of signaling priority. 2682 RST_STREAM (0x3): RST_STREAM frames do not exist, since QUIC 2683 provides stream lifecycle management. The same code point is used 2684 for the CANCEL_PUSH frame (Section 7.2.3). 2686 SETTINGS (0x4): SETTINGS frames are sent only at the beginning of 2687 the connection. See Section 7.2.4 and Appendix A.3. 2689 PUSH_PROMISE (0x5): The PUSH_PROMISE does not reference a stream; 2690 instead the push stream references the PUSH_PROMISE frame using a 2691 Push ID. See Section 7.2.5. 2693 PING (0x6): PING frames do not exist, since QUIC provides equivalent 2694 functionality. 2696 GOAWAY (0x7): GOAWAY does not contain an error code. In the client 2697 to server direction, it carries a Push ID instead of a server 2698 initiated stream ID. See Section 7.2.6. 2700 WINDOW_UPDATE (0x8): WINDOW_UPDATE frames do not exist, since QUIC 2701 provides flow control. 2703 CONTINUATION (0x9): CONTINUATION frames do not exist; instead, 2704 larger HEADERS/PUSH_PROMISE frames than HTTP/2 are permitted. 2706 Frame types defined by extensions to HTTP/2 need to be separately 2707 registered for HTTP/3 if still applicable. The IDs of frames defined 2708 in [HTTP2] have been reserved for simplicity. Note that the frame 2709 type space in HTTP/3 is substantially larger (62 bits versus 8 bits), 2710 so many HTTP/3 frame types have no equivalent HTTP/2 code points. 2711 See Section 11.2.1. 2713 A.3. HTTP/2 SETTINGS Parameters 2715 An important difference from HTTP/2 is that settings are sent once, 2716 as the first frame of the control stream, and thereafter cannot 2717 change. This eliminates many corner cases around synchronization of 2718 changes. 2720 Some transport-level options that HTTP/2 specifies via the SETTINGS 2721 frame are superseded by QUIC transport parameters in HTTP/3. The 2722 HTTP-level options that are retained in HTTP/3 have the same value as 2723 in HTTP/2. 2725 Below is a listing of how each HTTP/2 SETTINGS parameter is mapped: 2727 SETTINGS_HEADER_TABLE_SIZE: See [QPACK]. 2729 SETTINGS_ENABLE_PUSH: This is removed in favor of the MAX_PUSH_ID 2730 which provides a more granular control over server push. 2732 SETTINGS_MAX_CONCURRENT_STREAMS: QUIC controls the largest open 2733 Stream ID as part of its flow control logic. Specifying 2734 SETTINGS_MAX_CONCURRENT_STREAMS in the SETTINGS frame is an error. 2736 SETTINGS_INITIAL_WINDOW_SIZE: QUIC requires both stream and 2737 connection flow control window sizes to be specified in the 2738 initial transport handshake. Specifying 2739 SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS frame is an error. 2741 SETTINGS_MAX_FRAME_SIZE: This setting has no equivalent in HTTP/3. 2742 Specifying it in the SETTINGS frame is an error. 2744 SETTINGS_MAX_FIELD_SECTION_SIZE: See Section 7.2.4.1. 2746 In HTTP/3, setting values are variable-length integers (6, 14, 30, or 2747 62 bits long) rather than fixed-length 32-bit fields as in HTTP/2. 2748 This will often produce a shorter encoding, but can produce a longer 2749 encoding for settings which use the full 32-bit space. Settings 2750 ported from HTTP/2 might choose to redefine their value to limit it 2751 to 30 bits for more efficient encoding, or to make use of the 62-bit 2752 space if more than 30 bits are required. 2754 Settings need to be defined separately for HTTP/2 and HTTP/3. The 2755 IDs of settings defined in [HTTP2] have been reserved for simplicity. 2756 Note that the settings identifier space in HTTP/3 is substantially 2757 larger (62 bits versus 16 bits), so many HTTP/3 settings have no 2758 equivalent HTTP/2 code point. See Section 11.2.2. 2760 As QUIC streams might arrive out-of-order, endpoints are advised to 2761 not wait for the peers' settings to arrive before responding to other 2762 streams. See Section 7.2.4.2. 2764 A.4. HTTP/2 Error Codes 2766 QUIC has the same concepts of "stream" and "connection" errors that 2767 HTTP/2 provides. However, the differences between HTTP/2 and HTTP/3 2768 mean that error codes are not directly portable between versions. 2770 The HTTP/2 error codes defined in Section 7 of [HTTP2] logically map 2771 to the HTTP/3 error codes as follows: 2773 NO_ERROR (0x0): H3_NO_ERROR in Section 8.1. 2775 PROTOCOL_ERROR (0x1): This is mapped to H3_GENERAL_PROTOCOL_ERROR 2776 except in cases where more specific error codes have been defined. 2777 This includes H3_FRAME_UNEXPECTED and H3_CLOSED_CRITICAL_STREAM 2778 defined in Section 8.1. 2780 INTERNAL_ERROR (0x2): H3_INTERNAL_ERROR in Section 8.1. 2782 FLOW_CONTROL_ERROR (0x3): Not applicable, since QUIC handles flow 2783 control. 2785 SETTINGS_TIMEOUT (0x4): Not applicable, since no acknowledgement of 2786 SETTINGS is defined. 2788 STREAM_CLOSED (0x5): Not applicable, since QUIC handles stream 2789 management. 2791 FRAME_SIZE_ERROR (0x6): H3_FRAME_ERROR error code defined in 2792 Section 8.1. 2794 REFUSED_STREAM (0x7): H3_REQUEST_REJECTED (in Section 8.1) is used 2795 to indicate that a request was not processed. Otherwise, not 2796 applicable because QUIC handles stream management. 2798 CANCEL (0x8): H3_REQUEST_CANCELLED in Section 8.1. 2800 COMPRESSION_ERROR (0x9): Multiple error codes are defined in 2801 [QPACK]. 2803 CONNECT_ERROR (0xa): H3_CONNECT_ERROR in Section 8.1. 2805 ENHANCE_YOUR_CALM (0xb): H3_EXCESSIVE_LOAD in Section 8.1. 2807 INADEQUATE_SECURITY (0xc): Not applicable, since QUIC is assumed to 2808 provide sufficient security on all connections. 2810 H3_1_1_REQUIRED (0xd): H3_VERSION_FALLBACK in Section 8.1. 2812 Error codes need to be defined for HTTP/2 and HTTP/3 separately. See 2813 Section 11.2.3. 2815 A.4.1. Mapping Between HTTP/2 and HTTP/3 Errors 2817 An intermediary that converts between HTTP/2 and HTTP/3 may encounter 2818 error conditions from either upstream. It is useful to communicate 2819 the occurrence of error to the downstream but error codes largely 2820 reflect connection-local problems that generally do not make sense to 2821 propagate. 2823 An intermediary that encounters an error from an upstream origin can 2824 indicate this by sending an HTTP status code such as 502, which is 2825 suitable for a broad class of errors. 2827 There are some rare cases where it is beneficial to propagate the 2828 error by mapping it to the closest matching error type to the 2829 receiver. For example, an intermediary that receives an HTTP/2 2830 stream error of type REFUSED_STREAM from the origin has a clear 2831 signal that the request was not processed and that the request is 2832 safe to retry. Propagating this error condition to the client as an 2833 HTTP/3 stream error of type H3_REQUEST_REJECTED allows the client to 2834 take the action it deems most appropriate. In the reverse direction 2835 the intermediary might deem it beneficial to pass on client request 2836 cancellations that are indicated by terminating a stream with 2837 H3_REQUEST_CANCELLED. 2839 Conversion between errors is described in the logical mapping. The 2840 error codes are defined in non-overlapping spaces in order to protect 2841 against accidental conversion that could result in the use of 2842 inappropriate or unknown error codes for the target version. An 2843 intermediary is permitted to promote stream errors to connection 2844 errors but they should be aware of the cost to the connection for 2845 what might be a temporary or intermittent error. 2847 Appendix B. Change Log 2849 *RFC Editor's Note:* Please remove this section prior to 2850 publication of a final version of this document. 2852 B.1. Since draft-ietf-quic-http-28 2854 * CANCEL_PUSH is recommended even when the stream is reset (#3698, 2855 #3700) 2857 * Use H3_ID_ERROR when GOAWAY contains a larger identifier (#3631, 2858 #3634) 2860 B.2. Since draft-ietf-quic-http-27 2862 * Updated text to refer to latest HTTP revisions 2864 * Use the HTTP definition of authority for establishing and 2865 coalescing connections (#253, #2223, #3558) 2867 * Define use of GOAWAY from both endpoints (#2632, #3129) 2869 * Require either :authority or Host if the URI scheme has a 2870 mandatory authority component (#3408, #3475) 2872 B.3. Since draft-ietf-quic-http-26 2874 * No changes 2876 B.4. Since draft-ietf-quic-http-25 2878 * Require QUICv1 for HTTP/3 (#3117, #3323) 2880 * Remove DUPLICATE_PUSH and allow duplicate PUSH_PROMISE (#3275, 2881 #3309) 2883 * Clarify the definition of "malformed" (#3352, #3345) 2885 B.5. Since draft-ietf-quic-http-24 2887 * Removed H3_EARLY_RESPONSE error code; H3_NO_ERROR is recommended 2888 instead (#3130,#3208) 2890 * Unknown error codes are equivalent to H3_NO_ERROR (#3276,#3331) 2892 * Some error codes are reserved for greasing (#3325,#3360) 2894 B.6. Since draft-ietf-quic-http-23 2896 * Removed "quic" Alt-Svc parameter (#3061,#3118) 2898 * Clients need not persist unknown settings for use in 0-RTT 2899 (#3110,#3113) 2901 * Clarify error cases around CANCEL_PUSH (#2819,#3083) 2903 B.7. Since draft-ietf-quic-http-22 2905 * Removed priority signaling (#2922,#2924) 2907 * Further changes to error codes (#2662,#2551): 2909 - Error codes renumbered 2911 - HTTP_MALFORMED_FRAME replaced by HTTP_FRAME_ERROR, 2912 HTTP_ID_ERROR, and others 2914 * Clarify how unknown frame types interact with required frame 2915 sequence (#2867,#2858) 2917 * Describe interactions with the transport in terms of defined 2918 interface terms (#2857,#2805) 2920 * Require the use of the "http-opportunistic" resource (RFC 8164) 2921 when scheme is "http" (#2439,#2973) 2923 * Settings identifiers cannot be duplicated (#2979) 2925 * Changes to SETTINGS frames in 0-RTT (#2972,#2790,#2945): 2927 - Servers must send all settings with non-default values in their 2928 SETTINGS frame, even when resuming 2930 - If a client doesn't have settings associated with a 0-RTT 2931 ticket, it uses the defaults 2933 - Servers can't accept early data if they cannot recover the 2934 settings the client will have remembered 2936 * Clarify that Upgrade and the 101 status code are prohibited 2937 (#2898,#2889) 2939 * Clarify that frame types reserved for greasing can occur on any 2940 stream, but frame types reserved due to HTTP/2 correspondence are 2941 prohibited (#2997,#2692,#2693) 2943 * Unknown error codes cannot be treated as errors (#2998,#2816) 2945 B.8. Since draft-ietf-quic-http-21 2947 No changes 2949 B.9. Since draft-ietf-quic-http-20 2951 * Prohibit closing the control stream (#2509, #2666) 2953 * Change default priority to use an orphan node (#2502, #2690) 2955 * Exclusive priorities are restored (#2754, #2781) 2957 * Restrict use of frames when using CONNECT (#2229, #2702) 2959 * Close and maybe reset streams if a connection error occurs for 2960 CONNECT (#2228, #2703) 2962 * Encourage provision of sufficient unidirectional streams for QPACK 2963 (#2100, #2529, #2762) 2965 * Allow extensions to use server-initiated bidirectional streams 2966 (#2711, #2773) 2968 * Clarify use of maximum header list size setting (#2516, #2774) 2970 * Extensive changes to error codes and conditions of their sending 2972 - Require connection errors for more error conditions (#2511, 2973 #2510) 2975 - Updated the error codes for illegal GOAWAY frames (#2714, 2976 #2707) 2978 - Specified error code for HEADERS on control stream (#2708) 2980 - Specified error code for servers receiving PUSH_PROMISE (#2709) 2982 - Specified error code for receiving DATA before HEADERS (#2715) 2984 - Describe malformed messages and their handling (#2410, #2764) 2986 - Remove HTTP_PUSH_ALREADY_IN_CACHE error (#2812, #2813) 2988 - Refactor Push ID related errors (#2818, #2820) 2990 - Rationalize HTTP/3 stream creation errors (#2821, #2822) 2992 B.10. Since draft-ietf-quic-http-19 2994 * SETTINGS_NUM_PLACEHOLDERS is 0x9 (#2443,#2530) 2995 * Non-zero bits in the Empty field of the PRIORITY frame MAY be 2996 treated as an error (#2501) 2998 B.11. Since draft-ietf-quic-http-18 3000 * Resetting streams following a GOAWAY is recommended, but not 3001 required (#2256,#2457) 3003 * Use variable-length integers throughout (#2437,#2233,#2253,#2275) 3005 - Variable-length frame types, stream types, and settings 3006 identifiers 3008 - Renumbered stream type assignments 3010 - Modified associated reserved values 3012 * Frame layout switched from Length-Type-Value to Type-Length-Value 3013 (#2395,#2235) 3015 * Specified error code for servers receiving DUPLICATE_PUSH (#2497) 3017 * Use connection error for invalid PRIORITY (#2507, #2508) 3019 B.12. Since draft-ietf-quic-http-17 3021 * HTTP_REQUEST_REJECTED is used to indicate a request can be retried 3022 (#2106, #2325) 3024 * Changed error code for GOAWAY on the wrong stream (#2231, #2343) 3026 B.13. Since draft-ietf-quic-http-16 3028 * Rename "HTTP/QUIC" to "HTTP/3" (#1973) 3030 * Changes to PRIORITY frame (#1865, #2075) 3032 - Permitted as first frame of request streams 3034 - Remove exclusive reprioritization 3036 - Changes to Prioritized Element Type bits 3038 * Define DUPLICATE_PUSH frame to refer to another PUSH_PROMISE 3039 (#2072) 3041 * Set defaults for settings, allow request before receiving SETTINGS 3042 (#1809, #1846, #2038) 3044 * Clarify message processing rules for streams that aren't closed 3045 (#1972, #2003) 3047 * Removed reservation of error code 0 and moved HTTP_NO_ERROR to 3048 this value (#1922) 3050 * Removed prohibition of zero-length DATA frames (#2098) 3052 B.14. Since draft-ietf-quic-http-15 3054 Substantial editorial reorganization; no technical changes. 3056 B.15. Since draft-ietf-quic-http-14 3058 * Recommend sensible values for QUIC transport parameters 3059 (#1720,#1806) 3061 * Define error for missing SETTINGS frame (#1697,#1808) 3063 * Setting values are variable-length integers (#1556,#1807) and do 3064 not have separate maximum values (#1820) 3066 * Expanded discussion of connection closure (#1599,#1717,#1712) 3068 * HTTP_VERSION_FALLBACK falls back to HTTP/1.1 (#1677,#1685) 3070 B.16. Since draft-ietf-quic-http-13 3072 * Reserved some frame types for grease (#1333, #1446) 3074 * Unknown unidirectional stream types are tolerated, not errors; 3075 some reserved for grease (#1490, #1525) 3077 * Require settings to be remembered for 0-RTT, prohibit reductions 3078 (#1541, #1641) 3080 * Specify behavior for truncated requests (#1596, #1643) 3082 B.17. Since draft-ietf-quic-http-12 3084 * TLS SNI extension isn't mandatory if an alternative method is used 3085 (#1459, #1462, #1466) 3087 * Removed flags from HTTP/3 frames (#1388, #1398) 3089 * Reserved frame types and settings for use in preserving 3090 extensibility (#1333, #1446) 3092 * Added general error code (#1391, #1397) 3094 * Unidirectional streams carry a type byte and are extensible 3095 (#910,#1359) 3097 * Priority mechanism now uses explicit placeholders to enable 3098 persistent structure in the tree (#441,#1421,#1422) 3100 B.18. Since draft-ietf-quic-http-11 3102 * Moved QPACK table updates and acknowledgments to dedicated streams 3103 (#1121, #1122, #1238) 3105 B.19. Since draft-ietf-quic-http-10 3107 * Settings need to be remembered when attempting and accepting 0-RTT 3108 (#1157, #1207) 3110 B.20. Since draft-ietf-quic-http-09 3112 * Selected QCRAM for header compression (#228, #1117) 3114 * The server_name TLS extension is now mandatory (#296, #495) 3116 * Specified handling of unsupported versions in Alt-Svc (#1093, 3117 #1097) 3119 B.21. Since draft-ietf-quic-http-08 3121 * Clarified connection coalescing rules (#940, #1024) 3123 B.22. Since draft-ietf-quic-http-07 3125 * Changes for integer encodings in QUIC (#595,#905) 3127 * Use unidirectional streams as appropriate (#515, #240, #281, #886) 3129 * Improvement to the description of GOAWAY (#604, #898) 3131 * Improve description of server push usage (#947, #950, #957) 3133 B.23. Since draft-ietf-quic-http-06 3135 * Track changes in QUIC error code usage (#485) 3137 B.24. Since draft-ietf-quic-http-05 3138 * Made push ID sequential, add MAX_PUSH_ID, remove 3139 SETTINGS_ENABLE_PUSH (#709) 3141 * Guidance about keep-alive and QUIC PINGs (#729) 3143 * Expanded text on GOAWAY and cancellation (#757) 3145 B.25. Since draft-ietf-quic-http-04 3147 * Cite RFC 5234 (#404) 3149 * Return to a single stream per request (#245,#557) 3151 * Use separate frame type and settings registries from HTTP/2 (#81) 3153 * SETTINGS_ENABLE_PUSH instead of SETTINGS_DISABLE_PUSH (#477) 3155 * Restored GOAWAY (#696) 3157 * Identify server push using Push ID rather than a stream ID 3158 (#702,#281) 3160 * DATA frames cannot be empty (#700) 3162 B.26. Since draft-ietf-quic-http-03 3164 None. 3166 B.27. Since draft-ietf-quic-http-02 3168 * Track changes in transport draft 3170 B.28. Since draft-ietf-quic-http-01 3172 * SETTINGS changes (#181): 3174 - SETTINGS can be sent only once at the start of a connection; no 3175 changes thereafter 3177 - SETTINGS_ACK removed 3179 - Settings can only occur in the SETTINGS frame a single time 3181 - Boolean format updated 3183 * Alt-Svc parameter changed from "v" to "quic"; format updated 3184 (#229) 3186 * Closing the connection control stream or any message control 3187 stream is a fatal error (#176) 3189 * HPACK Sequence counter can wrap (#173) 3191 * 0-RTT guidance added 3193 * Guide to differences from HTTP/2 and porting HTTP/2 extensions 3194 added (#127,#242) 3196 B.29. Since draft-ietf-quic-http-00 3198 * Changed "HTTP/2-over-QUIC" to "HTTP/QUIC" throughout (#11,#29) 3200 * Changed from using HTTP/2 framing within Stream 3 to new framing 3201 format and two-stream-per-request model (#71,#72,#73) 3203 * Adopted SETTINGS format from draft-bishop-httpbis-extended- 3204 settings-01 3206 * Reworked SETTINGS_ACK to account for indeterminate inter-stream 3207 order (#75) 3209 * Described CONNECT pseudo-method (#95) 3211 * Updated ALPN token and Alt-Svc guidance (#13,#87) 3213 * Application-layer-defined error codes (#19,#74) 3215 B.30. Since draft-shade-quic-http2-mapping-00 3217 * Adopted as base for draft-ietf-quic-http 3219 * Updated authors/editors list 3221 Acknowledgements 3223 The original authors of this specification were Robbie Shade and Mike 3224 Warres. 3226 The IETF QUIC Working Group received an enormous amount of support 3227 from many people. Among others, the following people provided 3228 substantial contributions to this document: 3230 * Bence Beky 3232 * Daan De Meyer 3233 * Martin Duke 3235 * Roy Fielding 3237 * Alan Frindell 3239 * Alessandro Ghedini 3241 * Nick Harper 3243 * Ryan Hamilton 3245 * Christian Huitema 3247 * Subodh Iyengar 3249 * Robin Marx 3251 * Patrick McManus 3253 * Luca Nicco 3255 * 奥 一穂 (Kazuho Oku) 3257 * Lucas Pardue 3259 * Roberto Peon 3261 * Julian Reschke 3263 * Eric Rescorla 3265 * Martin Seemann 3267 * Ben Schwartz 3269 * Ian Swett 3271 * Willy Taureau 3273 * Martin Thomson 3275 * Dmitri Tikhonov 3277 * Tatsuhiro Tsujikawa 3279 A portion of Mike's contribution was supported by Microsoft during 3280 his employment there. 3282 Author's Address 3284 Mike Bishop (editor) 3285 Akamai 3287 Email: mbishop@evequefou.be