idnits 2.17.1 draft-ietf-quic-http-28.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 (20 May 2020) is 1435 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-07 -- Possible downref: Normative reference to a draft: ref. 'CACHING' == Outdated reference: A later version (-21) exists of draft-ietf-quic-qpack-15 == 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-07 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-07 -- 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 20 May 2020 5 Expires: 21 November 2020 7 Hypertext Transfer Protocol Version 3 (HTTP/3) 8 draft-ietf-quic-http-28 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 21 November 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 . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . 9 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 . . . . . . . . . . 13 79 4.1.2. Request Cancellation and Rejection . . . . . . . . . 17 80 4.1.3. Malformed Requests and Responses . . . . . . . . . . 18 81 4.2. The CONNECT Method . . . . . . . . . . . . . . . . . . . 18 82 4.3. HTTP Upgrade . . . . . . . . . . . . . . . . . . . . . . 20 83 4.4. Server Push . . . . . . . . . . . . . . . . . . . . . . . 20 84 5. Connection Closure . . . . . . . . . . . . . . . . . . . . . 22 85 5.1. Idle Connections . . . . . . . . . . . . . . . . . . . . 22 86 5.2. Connection Shutdown . . . . . . . . . . . . . . . . . . . 23 87 5.3. Immediate Application Closure . . . . . . . . . . . . . . 25 88 5.4. Transport Closure . . . . . . . . . . . . . . . . . . . . 25 89 6. Stream Mapping and Usage . . . . . . . . . . . . . . . . . . 25 90 6.1. Bidirectional Streams . . . . . . . . . . . . . . . . . . 26 91 6.2. Unidirectional Streams . . . . . . . . . . . . . . . . . 26 92 6.2.1. Control Streams . . . . . . . . . . . . . . . . . . . 27 93 6.2.2. Push Streams . . . . . . . . . . . . . . . . . . . . 28 94 6.2.3. Reserved Stream Types . . . . . . . . . . . . . . . . 28 96 7. HTTP Framing Layer . . . . . . . . . . . . . . . . . . . . . 29 97 7.1. Frame Layout . . . . . . . . . . . . . . . . . . . . . . 30 98 7.2. Frame Definitions . . . . . . . . . . . . . . . . . . . . 30 99 7.2.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . 30 100 7.2.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . 31 101 7.2.3. CANCEL_PUSH . . . . . . . . . . . . . . . . . . . . . 31 102 7.2.4. SETTINGS . . . . . . . . . . . . . . . . . . . . . . 32 103 7.2.5. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . 35 104 7.2.6. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . 37 105 7.2.7. MAX_PUSH_ID . . . . . . . . . . . . . . . . . . . . . 37 106 7.2.8. Reserved Frame Types . . . . . . . . . . . . . . . . 38 107 8. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 38 108 8.1. HTTP/3 Error Codes . . . . . . . . . . . . . . . . . . . 39 109 9. Extensions to HTTP/3 . . . . . . . . . . . . . . . . . . . . 40 110 10. Security Considerations . . . . . . . . . . . . . . . . . . . 41 111 10.1. Server Authority . . . . . . . . . . . . . . . . . . . . 41 112 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 41 113 10.3. Intermediary Encapsulation Attacks . . . . . . . . . . . 42 114 10.4. Cacheability of Pushed Responses . . . . . . . . . . . . 42 115 10.5. Denial-of-Service Considerations . . . . . . . . . . . . 42 116 10.5.1. Limits on Field Section Size . . . . . . . . . . . . 43 117 10.5.2. CONNECT Issues . . . . . . . . . . . . . . . . . . . 44 118 10.6. Use of Compression . . . . . . . . . . . . . . . . . . . 44 119 10.7. Padding and Traffic Analysis . . . . . . . . . . . . . . 45 120 10.8. Frame Parsing . . . . . . . . . . . . . . . . . . . . . 45 121 10.9. Early Data . . . . . . . . . . . . . . . . . . . . . . . 45 122 10.10. Migration . . . . . . . . . . . . . . . . . . . . . . . 46 123 10.11. Privacy Considerations . . . . . . . . . . . . . . . . . 46 124 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 125 11.1. Registration of HTTP/3 Identification String . . . . . . 46 126 11.2. New Registries . . . . . . . . . . . . . . . . . . . . . 47 127 11.2.1. Frame Types . . . . . . . . . . . . . . . . . . . . 47 128 11.2.2. Settings Parameters . . . . . . . . . . . . . . . . 48 129 11.2.3. Error Codes . . . . . . . . . . . . . . . . . . . . 49 130 11.2.4. Stream Types . . . . . . . . . . . . . . . . . . . . 52 131 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 52 132 12.1. Normative References . . . . . . . . . . . . . . . . . . 52 133 12.2. Informative References . . . . . . . . . . . . . . . . . 54 134 Appendix A. Considerations for Transitioning from HTTP/2 . . . . 55 135 A.1. Streams . . . . . . . . . . . . . . . . . . . . . . . . . 56 136 A.2. HTTP Frame Types . . . . . . . . . . . . . . . . . . . . 56 137 A.2.1. Prioritization Differences . . . . . . . . . . . . . 57 138 A.2.2. Field Compression Differences . . . . . . . . . . . . 57 139 A.2.3. Guidance for New Frame Type Definitions . . . . . . . 57 140 A.2.4. Mapping Between HTTP/2 and HTTP/3 Frame Types . . . . 58 141 A.3. HTTP/2 SETTINGS Parameters . . . . . . . . . . . . . . . 59 142 A.4. HTTP/2 Error Codes . . . . . . . . . . . . . . . . . . . 60 143 A.4.1. Mapping Between HTTP/2 and HTTP/3 Errors . . . . . . 61 145 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 61 146 B.1. Since draft-ietf-quic-http-27 . . . . . . . . . . . . . . 62 147 B.2. Since draft-ietf-quic-http-26 . . . . . . . . . . . . . . 62 148 B.3. Since draft-ietf-quic-http-25 . . . . . . . . . . . . . . 62 149 B.4. Since draft-ietf-quic-http-24 . . . . . . . . . . . . . . 62 150 B.5. Since draft-ietf-quic-http-23 . . . . . . . . . . . . . . 62 151 B.6. Since draft-ietf-quic-http-22 . . . . . . . . . . . . . . 62 152 B.7. Since draft-ietf-quic-http-21 . . . . . . . . . . . . . . 63 153 B.8. Since draft-ietf-quic-http-20 . . . . . . . . . . . . . . 63 154 B.9. Since draft-ietf-quic-http-19 . . . . . . . . . . . . . . 64 155 B.10. Since draft-ietf-quic-http-18 . . . . . . . . . . . . . . 64 156 B.11. Since draft-ietf-quic-http-17 . . . . . . . . . . . . . . 65 157 B.12. Since draft-ietf-quic-http-16 . . . . . . . . . . . . . . 65 158 B.13. Since draft-ietf-quic-http-15 . . . . . . . . . . . . . . 66 159 B.14. Since draft-ietf-quic-http-14 . . . . . . . . . . . . . . 66 160 B.15. Since draft-ietf-quic-http-13 . . . . . . . . . . . . . . 66 161 B.16. Since draft-ietf-quic-http-12 . . . . . . . . . . . . . . 66 162 B.17. Since draft-ietf-quic-http-11 . . . . . . . . . . . . . . 67 163 B.18. Since draft-ietf-quic-http-10 . . . . . . . . . . . . . . 67 164 B.19. Since draft-ietf-quic-http-09 . . . . . . . . . . . . . . 67 165 B.20. Since draft-ietf-quic-http-08 . . . . . . . . . . . . . . 67 166 B.21. Since draft-ietf-quic-http-07 . . . . . . . . . . . . . . 67 167 B.22. Since draft-ietf-quic-http-06 . . . . . . . . . . . . . . 67 168 B.23. Since draft-ietf-quic-http-05 . . . . . . . . . . . . . . 67 169 B.24. Since draft-ietf-quic-http-04 . . . . . . . . . . . . . . 67 170 B.25. Since draft-ietf-quic-http-03 . . . . . . . . . . . . . . 68 171 B.26. Since draft-ietf-quic-http-02 . . . . . . . . . . . . . . 68 172 B.27. Since draft-ietf-quic-http-01 . . . . . . . . . . . . . . 68 173 B.28. Since draft-ietf-quic-http-00 . . . . . . . . . . . . . . 69 174 B.29. Since draft-shade-quic-http2-mapping-00 . . . . . . . . . 69 175 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 69 176 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 70 178 1. Introduction 180 HTTP semantics [SEMANTICS] are used for a broad range of services on 181 the Internet. These semantics have most commonly been used with two 182 different TCP mappings, HTTP/1.1 and HTTP/2. HTTP/3 supports the 183 same semantics over a new transport protocol, QUIC. 185 1.1. Prior versions of HTTP 187 HTTP/1.1 [HTTP11] is a TCP mapping which uses whitespace-delimited 188 text fields to convey HTTP messages. While these exchanges are 189 human-readable, using whitespace for message formatting leads to 190 parsing complexity and motivates tolerance of variant behavior. 191 Because each connection can transfer only a single HTTP request or 192 response at a time in each direction, multiple parallel TCP 193 connections are often used, reducing the ability of the congestion 194 controller to effectively manage traffic between endpoints. 196 HTTP/2 [HTTP2] introduced a binary framing and multiplexing layer to 197 improve latency without modifying the transport layer. However, 198 because the parallel nature of HTTP/2's multiplexing is not visible 199 to TCP's loss recovery mechanisms, a lost or reordered packet causes 200 all active transactions to experience a stall regardless of whether 201 that transaction was directly impacted by the lost packet. 203 1.2. Delegation to QUIC 205 The QUIC transport protocol incorporates stream multiplexing and per- 206 stream flow control, similar to that provided by the HTTP/2 framing 207 layer. By providing reliability at the stream level and congestion 208 control across the entire connection, it has the capability to 209 improve the performance of HTTP compared to a TCP mapping. QUIC also 210 incorporates TLS 1.3 [TLS13] at the transport layer, offering 211 comparable security to running TLS over TCP, with the improved 212 connection setup latency of TCP Fast Open [TFO]. 214 This document defines a mapping of HTTP semantics over the QUIC 215 transport protocol, drawing heavily on the design of HTTP/2. While 216 delegating stream lifetime and flow control issues to QUIC, a similar 217 binary framing is used on each stream. Some HTTP/2 features are 218 subsumed by QUIC, while other features are implemented atop QUIC. 220 QUIC is described in [QUIC-TRANSPORT]. For a full description of 221 HTTP/2, see [HTTP2]. 223 2. HTTP/3 Protocol Overview 225 HTTP/3 provides a transport for HTTP semantics using the QUIC 226 transport protocol and an internal framing layer similar to HTTP/2. 228 Once a client knows that an HTTP/3 server exists at a certain 229 endpoint, it opens a QUIC connection. QUIC provides protocol 230 negotiation, stream-based multiplexing, and flow control. Discovery 231 of an HTTP/3 endpoint is described in Section 3.2. 233 Within each stream, the basic unit of HTTP/3 communication is a frame 234 (Section 7.2). Each frame type serves a different purpose. For 235 example, HEADERS and DATA frames form the basis of HTTP requests and 236 responses (Section 4.1). 238 Multiplexing of requests is performed using the QUIC stream 239 abstraction, described in Section 2 of [QUIC-TRANSPORT]. Each 240 request-response pair consumes a single QUIC stream. Streams are 241 independent of each other, so one stream that is blocked or suffers 242 packet loss does not prevent progress on other streams. 244 Server push is an interaction mode introduced in HTTP/2 [HTTP2] which 245 permits a server to push a request-response exchange to a client in 246 anticipation of the client making the indicated request. This trades 247 off network usage against a potential latency gain. Several HTTP/3 248 frames are used to manage server push, such as PUSH_PROMISE, 249 MAX_PUSH_ID, and CANCEL_PUSH. 251 As in HTTP/2, request and response fields are compressed for 252 transmission. Because HPACK [HPACK] relies on in-order transmission 253 of compressed field sections (a guarantee not provided by QUIC), 254 HTTP/3 replaces HPACK with QPACK [QPACK]. QPACK uses separate 255 unidirectional streams to modify and track field table state, while 256 encoded field sections refer to the state of the table without 257 modifying it. 259 2.1. Document Organization 261 The following sections provide a detailed overview of the connection 262 lifecycle and key concepts: 264 * Connection Setup and Management (Section 3) covers how an HTTP/3 265 endpoint is discovered and a connection is established. 267 * HTTP Request Lifecycle (Section 4) describes how HTTP semantics 268 are expressed using frames. 270 * Connection Closure (Section 5) describes how connections are 271 terminated, either gracefully or abruptly. 273 The details of the wire protocol and interactions with the transport 274 are described in subsequent sections: 276 * Stream Mapping and Usage (Section 6) describes the way QUIC 277 streams are used. 279 * HTTP Framing Layer (Section 7) describes the frames used on most 280 streams. 282 * Error Handling (Section 8) describes how error conditions are 283 handled and expressed, either on a particular stream or for the 284 connection as a whole. 286 Additional resources are provided in the final sections: 288 * Extensions to HTTP/3 (Section 9) describes how new capabilities 289 can be added in future documents. 291 * A more detailed comparison between HTTP/2 and HTTP/3 can be found 292 in Appendix A. 294 2.2. Conventions and Terminology 296 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 297 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 298 "OPTIONAL" in this document are to be interpreted as described in 299 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 300 capitals, as shown here. 302 Field definitions are given in Augmented Backus-Naur Form (ABNF), as 303 defined in [RFC5234]. 305 This document uses the variable-length integer encoding from 306 [QUIC-TRANSPORT]. 308 The following terms are used: 310 abort: An abrupt termination of a connection or stream, possibly due 311 to an error condition. 313 client: The endpoint that initiates an HTTP/3 connection. Clients 314 send HTTP requests and receive HTTP responses. 316 connection: A transport-layer connection between two endpoints, 317 using QUIC as the transport protocol. 319 connection error: An error that affects the entire HTTP/3 320 connection. 322 endpoint: Either the client or server of the connection. 324 frame: The smallest unit of communication on a stream in HTTP/3, 325 consisting of a header and a variable-length sequence of bytes 326 structured according to the frame type. Protocol elements called 327 "frames" exist in both this document and [QUIC-TRANSPORT]. Where 328 frames from [QUIC-TRANSPORT] are referenced, the frame name will 329 be prefaced with "QUIC." For example, "QUIC CONNECTION_CLOSE 330 frames." References without this preface refer to frames defined 331 in Section 7.2. 333 peer: An endpoint. When discussing a particular endpoint, "peer" 334 refers to the endpoint that is remote to the primary subject of 335 discussion. 337 receiver: An endpoint that is receiving frames. 339 sender: An endpoint that is transmitting frames. 341 server: The endpoint that accepts an HTTP/3 connection. Servers 342 receive HTTP requests and send HTTP responses. 344 stream: A bidirectional or unidirectional bytestream provided by the 345 QUIC transport. 347 stream error: An error on the individual HTTP/3 stream. 349 The term "payload body" is defined in Section 6.3.3 of [SEMANTICS]. 351 Finally, the terms "gateway", "intermediary", "proxy", and "tunnel" 352 are defined in Section 2.2 of [SEMANTICS]. Intermediaries act as 353 both client and server at different times. 355 3. Connection Setup and Management 357 3.1. Draft Version Identification 359 *RFC Editor's Note:* Please remove this section prior to 360 publication of a final version of this document. 362 HTTP/3 uses the token "h3" to identify itself in ALPN and Alt-Svc. 363 Only implementations of the final, published RFC can identify 364 themselves as "h3". Until such an RFC exists, implementations MUST 365 NOT identify themselves using this string. 367 Implementations of draft versions of the protocol MUST add the string 368 "-" and the corresponding draft number to the identifier. For 369 example, draft-ietf-quic-http-01 is identified using the string 370 "h3-01". 372 Draft versions MUST use the corresponding draft transport version as 373 their transport. For example, the application protocol defined in 374 draft-ietf-quic-http-25 uses the transport defined in draft-ietf- 375 quic-transport-25. 377 Non-compatible experiments that are based on these draft versions 378 MUST append the string "-" and an experiment name to the identifier. 379 For example, an experimental implementation based on draft-ietf-quic- 380 http-09 which reserves an extra stream for unsolicited transmission 381 of 1980s pop music might identify itself as "h3-09-rickroll". Note 382 that any label MUST conform to the "token" syntax defined in 383 Section 4.4.1.1 of [SEMANTICS]. Experimenters are encouraged to 384 coordinate their experiments on the quic@ietf.org 385 (mailto:quic@ietf.org) mailing list. 387 3.2. Discovering an HTTP/3 Endpoint 389 HTTP relies on the notion of an authoritative response: a response 390 that has been determined to be the most appropriate response for that 391 request given the state of the target resource at the time of 392 response message origination by (or at the direction of) the origin 393 server identified within the target URI. Locating an authoritative 394 server for an HTTP URL is discussed in Section 5.4 of [SEMANTICS]. 396 The "https" scheme associates authority with possession of a 397 certificate that the client considers to be trustworthy for the host 398 identified by the authority component of the URL. If a server 399 presents a certificate and proof that it controls the corresponding 400 private key, then a client will accept a secured connection to that 401 server as being authoritative for all origins with the "https" scheme 402 and a host identified in the certificate. 404 A client MAY attempt access to a resource with an "https" URI by 405 resolving the host identifier to an IP address, establishing a QUIC 406 connection to that address on the indicated port, and sending an 407 HTTP/3 request message targeting the URI to the server over that 408 secured connection. 410 Connectivity problems (e.g., blocking UDP) can result in QUIC 411 connection establishment failure; clients SHOULD attempt to use TCP- 412 based versions of HTTP in this case. 414 Servers MAY serve HTTP/3 on any UDP port; an alternative service 415 advertisement always includes an explicit port, and URLs contain 416 either an explicit port or a default port associated with the scheme. 418 3.2.1. HTTP Alternative Services 420 An HTTP origin advertises the availability of an equivalent HTTP/3 421 endpoint via the Alt-Svc HTTP response header field or the HTTP/2 422 ALTSVC frame ([ALTSVC]), using the ALPN token defined in Section 3.3. 424 For example, an origin could indicate in an HTTP response that HTTP/3 425 was available on UDP port 50781 at the same hostname by including the 426 following header field: 428 Alt-Svc: h3=":50781" 429 On receipt of an Alt-Svc record indicating HTTP/3 support, a client 430 MAY attempt to establish a QUIC connection to the indicated host and 431 port and, if successful, send HTTP requests using the mapping 432 described in this document. 434 3.2.2. Other Schemes 436 Although HTTP is independent of the transport protocol, the "http" 437 scheme associates authority with the ability to receive TCP 438 connections on the indicated port of whatever host is identified 439 within the authority component. Because HTTP/3 does not use TCP, 440 HTTP/3 cannot be used for direct access to the authoritative server 441 for a resource identified by an "http" URI. However, protocol 442 extensions such as [ALTSVC] permit the authoritative server to 443 identify other services which are also authoritative and which might 444 be reachable over HTTP/3. 446 Prior to making requests for an origin whose scheme is not "https", 447 the client MUST ensure the server is willing to serve that scheme. 448 If the client intends to make requests for an origin whose scheme is 449 "http", this means that it MUST obtain a valid "http-opportunistic" 450 response for the origin as described in [RFC8164] prior to making any 451 such requests. Other schemes might define other mechanisms. 453 3.3. Connection Establishment 455 HTTP/3 relies on QUIC version 1 as the underlying transport. The use 456 of other QUIC transport versions with HTTP/3 MAY be defined by future 457 specifications. 459 QUIC version 1 uses TLS version 1.3 or greater as its handshake 460 protocol. HTTP/3 clients MUST support a mechanism to indicate the 461 target host to the server during the TLS handshake. If the server is 462 identified by a DNS name, clients MUST send the Server Name 463 Indication (SNI) [RFC6066] TLS extension unless an alternative 464 mechanism to indicate the target host is used. 466 QUIC connections are established as described in [QUIC-TRANSPORT]. 467 During connection establishment, HTTP/3 support is indicated by 468 selecting the ALPN token "h3" in the TLS handshake. Support for 469 other application-layer protocols MAY be offered in the same 470 handshake. 472 While connection-level options pertaining to the core QUIC protocol 473 are set in the initial crypto handshake, HTTP/3-specific settings are 474 conveyed in the SETTINGS frame. After the QUIC connection is 475 established, a SETTINGS frame (Section 7.2.4) MUST be sent by each 476 endpoint as the initial frame of their respective HTTP control 477 stream; see Section 6.2.1. 479 3.4. Connection Reuse 481 HTTP/3 connections are persistent across multiple requests. For best 482 performance, it is expected that clients will not close connections 483 until it is determined that no further communication with a server is 484 necessary (for example, when a user navigates away from a particular 485 web page) or until the server closes the connection. 487 Once a connection exists to a server endpoint, this connection MAY be 488 reused for requests with multiple different URI authority components. 489 In general, a server is considered authoritative for all URIs with 490 the "https" scheme for which the hostname in the URI is present in 491 the authenticated certificate provided by the server, either as the 492 CN field of the certificate subject or as a dNSName in the 493 subjectAltName field of the certificate; see [RFC6125]. For a host 494 that is an IP address, the client MUST verify that the address 495 appears as an iPAddress in the subjectAltName field of the 496 certificate. If the hostname or address is not present in the 497 certificate, the client MUST NOT consider the server authoritative 498 for origins containing that hostname or address. See Section 5.4 of 499 [SEMANTICS] for more detail on authoritative access. 501 Clients SHOULD NOT open more than one HTTP/3 connection to a given 502 host and port pair, where the host is derived from a URI, a selected 503 alternative service [ALTSVC], or a configured proxy. A client MAY 504 open multiple connections to the same IP address and UDP port using 505 different transport or TLS configurations but SHOULD avoid creating 506 multiple connections with the same configuration. 508 Servers are encouraged to maintain open connections for as long as 509 possible but are permitted to terminate idle connections if 510 necessary. When either endpoint chooses to close the HTTP/3 session, 511 the terminating endpoint SHOULD first send a GOAWAY frame 512 (Section 5.2) so that both endpoints can reliably determine whether 513 previously sent frames have been processed and gracefully complete or 514 terminate any necessary remaining tasks. 516 A server that does not wish clients to reuse connections for a 517 particular origin can indicate that it is not authoritative for a 518 request by sending a 421 (Misdirected Request) status code in 519 response to the request; see Section 9.1.2 of [HTTP2]. 521 4. HTTP Request Lifecycle 523 4.1. HTTP Message Exchanges 525 A client sends an HTTP request on a client-initiated bidirectional 526 QUIC stream. A client MUST send only a single request on a given 527 stream. A server sends zero or more interim HTTP responses on the 528 same stream as the request, followed by a single final HTTP response, 529 as detailed below. 531 Pushed responses are sent on a server-initiated unidirectional QUIC 532 stream; see Section 6.2.2. A server sends zero or more interim HTTP 533 responses, followed by a single final HTTP response, in the same 534 manner as a standard response. Push is described in more detail in 535 Section 4.4. 537 On a given stream, receipt of multiple requests or receipt of an 538 additional HTTP response following a final HTTP response MUST be 539 treated as malformed (Section 4.1.3). 541 An HTTP message (request or response) consists of: 543 1. the header field section (see Section 4 of [SEMANTICS]), sent as 544 a single HEADERS frame (see Section 7.2.2), 546 2. optionally, the payload body, if present (see Section 6.3.3 of 547 [SEMANTICS]), sent as a series of DATA frames (see 548 Section 7.2.1), 550 3. optionally, the trailer field section, if present (see 551 Section 4.6 of [SEMANTICS]), sent as a single HEADERS frame. 553 Receipt of an invalid sequence of frames MUST be treated as a 554 connection error of type H3_FRAME_UNEXPECTED (Section 8). In 555 particular, a DATA frame before any HEADERS frame, or a HEADERS or 556 DATA frame after the trailing HEADERS frame is considered invalid. 558 A server MAY send one or more PUSH_PROMISE frames (see Section 7.2.5) 559 before, after, or interleaved with the frames of a response message. 560 These PUSH_PROMISE frames are not part of the response; see 561 Section 4.4 for more details. These frames are not permitted in 562 pushed responses; a pushed response which includes PUSH_PROMISE 563 frames MUST be treated as a connection error of type 564 H3_FRAME_UNEXPECTED. 566 Frames of unknown types (Section 9), including reserved frames 567 (Section 7.2.8) MAY be sent on a request or push stream before, 568 after, or interleaved with other frames described in this section. 570 The HEADERS and PUSH_PROMISE frames might reference updates to the 571 QPACK dynamic table. While these updates are not directly part of 572 the message exchange, they must be received and processed before the 573 message can be consumed. See Section 4.1.1 for more details. 575 The "chunked" transfer encoding defined in Section 7.1 of [HTTP11] 576 MUST NOT be used. 578 A response MAY consist of multiple messages when and only when one or 579 more informational responses (1xx; see Section 9.2 of [SEMANTICS]) 580 precede a final response to the same request. Interim responses do 581 not contain a payload body or trailers. 583 An HTTP request/response exchange fully consumes a client-initiated 584 bidirectional QUIC stream. After sending a request, a client MUST 585 close the stream for sending. Unless using the CONNECT method (see 586 Section 4.2), clients MUST NOT make stream closure dependent on 587 receiving a response to their request. After sending a final 588 response, the server MUST close the stream for sending. At this 589 point, the QUIC stream is fully closed. 591 When a stream is closed, this indicates the end of an HTTP message. 592 Because some messages are large or unbounded, endpoints SHOULD begin 593 processing partial HTTP messages once enough of the message has been 594 received to make progress. If a client stream terminates without 595 enough of the HTTP message to provide a complete response, the server 596 SHOULD abort its response with the error code H3_REQUEST_INCOMPLETE. 598 A server can send a complete response prior to the client sending an 599 entire request if the response does not depend on any portion of the 600 request that has not been sent and received. When the server does 601 not need to receive the remainder of the request, it MAY abort 602 reading the request stream, send a complete response, and cleanly 603 close the sending part of the stream. The error code H3_NO_ERROR 604 SHOULD be used when requesting that the client stop sending on the 605 request stream. Clients MUST NOT discard complete responses as a 606 result of having their request terminated abruptly, though clients 607 can always discard responses at their discretion for other reasons. 608 If the server sends a partial or complete response but does not abort 609 reading, clients SHOULD continue sending the body of the request and 610 close the stream normally. 612 4.1.1. Field Formatting and Compression 614 HTTP messages carry metadata as a series of key-value pairs, called 615 HTTP fields. For a listing of registered HTTP fields, see the 616 "Hypertext Transfer Protocol (HTTP) Field Name Registry" maintained 617 at https://www.iana.org/assignments/http-fields/. 619 As in previous versions of HTTP, field names are strings containing a 620 subset of ASCII characters that are compared in a case-insensitive 621 fashion. Properties of HTTP field names and values are discussed in 622 more detail in Section 4.3 of [SEMANTICS]. As in HTTP/2, characters 623 in field names MUST be converted to lowercase prior to their 624 encoding. A request or response containing uppercase characters in 625 field names MUST be treated as malformed (Section 4.1.3). 627 Like HTTP/2, HTTP/3 does not use the Connection header field to 628 indicate connection-specific fields; in this protocol, connection- 629 specific metadata is conveyed by other means. An endpoint MUST NOT 630 generate an HTTP/3 field section containing connection-specific 631 fields; any message containing connection-specific fields MUST be 632 treated as malformed (Section 4.1.3). 634 The only exception to this is the TE header field, which MAY be 635 present in an HTTP/3 request header; when it is, it MUST NOT contain 636 any value other than "trailers". 638 This means that an intermediary transforming an HTTP/1.x message to 639 HTTP/3 will need to remove any fields nominated by the Connection 640 field, along with the Connection field itself. Such intermediaries 641 SHOULD also remove other connection-specific fields, such as Keep- 642 Alive, Proxy-Connection, Transfer-Encoding, and Upgrade, even if they 643 are not nominated by the Connection field. 645 4.1.1.1. Pseudo-Header Fields 647 Like HTTP/2, HTTP/3 employs a series of pseudo-header fields where 648 the field name begins with the ':' character (ASCII 0x3a). These 649 pseudo-header fields convey the target URI, the method of the 650 request, and the status code for the response. 652 Pseudo-header fields are not HTTP fields. Endpoints MUST NOT 653 generate pseudo-header fields other than those defined in this 654 document, except as negotiated via an extension; see Section 9. 656 Pseudo-header fields are only valid in the context in which they are 657 defined. Pseudo-header fields defined for requests MUST NOT appear 658 in responses; pseudo-header fields defined for responses MUST NOT 659 appear in requests. Pseudo-header fields MUST NOT appear in 660 trailers. Endpoints MUST treat a request or response that contains 661 undefined or invalid pseudo-header fields as malformed 662 (Section 4.1.3). 664 All pseudo-header fields MUST appear in the header field section 665 before regular header fields. Any request or response that contains 666 a pseudo-header field that appears in a header field section after a 667 regular header field MUST be treated as malformed (Section 4.1.3). 669 The following pseudo-header fields are defined for requests: 671 ":method": Contains the HTTP method (Section 7 of [SEMANTICS]) 673 ":scheme": Contains the scheme portion of the target URI 674 (Section 3.1 of [RFC3986]) 676 ":scheme" is not restricted to "http" and "https" schemed URIs. A 677 proxy or gateway can translate requests for non-HTTP schemes, 678 enabling the use of HTTP to interact with non-HTTP services. 680 ":authority": Contains the authority portion of the target URI 681 (Section 3.2 of [RFC3986]). The authority MUST NOT include the 682 deprecated "userinfo" subcomponent for "http" or "https" schemed 683 URIs. 685 To ensure that the HTTP/1.1 request line can be reproduced 686 accurately, this pseudo-header field MUST be omitted when 687 translating from an HTTP/1.1 request that has a request target in 688 origin or asterisk form; see Section 3.2 of [HTTP11]. Clients 689 that generate HTTP/3 requests directly SHOULD use the ":authority" 690 pseudo-header field instead of the Host field. An intermediary 691 that converts an HTTP/3 request to HTTP/1.1 MUST create a Host 692 field if one is not present in a request by copying the value of 693 the ":authority" pseudo-header field. 695 ":path": Contains the path and query parts of the target URI (the 696 "path-absolute" production and optionally a '?' character followed 697 by the "query" production; see Sections 3.3 and 3.4 of [URI]. A 698 request in asterisk form includes the value '*' for the ":path" 699 pseudo-header field. 701 This pseudo-header field MUST NOT be empty for "http" or "https" 702 URIs; "http" or "https" URIs that do not contain a path component 703 MUST include a value of '/'. The exception to this rule is an 704 OPTIONS request for an "http" or "https" URI that does not include 705 a path component; these MUST include a ":path" pseudo-header field 706 with a value of '*'; see Section 3.2.4 of [HTTP11]. 708 All HTTP/3 requests MUST include exactly one value for the ":method", 709 ":scheme", and ":path" pseudo-header fields, unless it is a CONNECT 710 request; see Section 4.2. 712 If the ":scheme" pseudo-header field identifies a scheme which has a 713 mandatory authority component (including "http" and "https"), the 714 request MUST contain either an ":authority" pseudo-header field or a 715 "Host" header field. If these fields are present, they MUST NOT be 716 empty. If both fields are present, they MUST contain the same value. 717 If the scheme does not have a mandatory authority component and none 718 is provided in the request target, the request MUST NOT contain the 719 ":authority" pseudo-header and "Host" header fields. 721 An HTTP request that omits mandatory pseudo-header fields or contains 722 invalid values for those pseudo-header fields is malformed 723 (Section 4.1.3). 725 HTTP/3 does not define a way to carry the version identifier that is 726 included in the HTTP/1.1 request line. 728 For responses, a single ":status" pseudo-header field is defined that 729 carries the HTTP status code; see Section 9 of [SEMANTICS]. This 730 pseudo-header field MUST be included in all responses; otherwise, the 731 response is malformed (Section 4.1.3). 733 HTTP/3 does not define a way to carry the version or reason phrase 734 that is included in an HTTP/1.1 status line. 736 4.1.1.2. Field Compression 738 HTTP/3 uses QPACK field compression as described in [QPACK], a 739 variation of HPACK which allows the flexibility to avoid compression- 740 induced head-of-line blocking. See that document for additional 741 details. 743 To allow for better compression efficiency, the "Cookie" field 744 [RFC6265] MAY be split into separate field lines, each with one or 745 more cookie-pairs, before compression. If a decompressed field 746 section contains multiple cookie field lines, these MUST be 747 concatenated into a single octet string using the two-octet delimiter 748 of 0x3B, 0x20 (the ASCII string "; ") before being passed into a 749 context other than HTTP/2 or HTTP/3, such as an HTTP/1.1 connection, 750 or a generic HTTP server application. 752 4.1.1.3. Header Size Constraints 754 An HTTP/3 implementation MAY impose a limit on the maximum size of 755 the message header it will accept on an individual HTTP message. A 756 server that receives a larger header section than it is willing to 757 handle can send an HTTP 431 (Request Header Fields Too Large) status 758 code ([RFC6585]). A client can discard responses that it cannot 759 process. The size of a field list is calculated based on the 760 uncompressed size of fields, including the length of the name and 761 value in bytes plus an overhead of 32 bytes for each field. 763 If an implementation wishes to advise its peer of this limit, it can 764 be conveyed as a number of bytes in the 765 SETTINGS_MAX_FIELD_SECTION_SIZE parameter. An implementation which 766 has received this parameter SHOULD NOT send an HTTP message header 767 which exceeds the indicated size, as the peer will likely refuse to 768 process it. However, because this limit is applied at each hop, 769 messages below this limit are not guaranteed to be accepted. 771 4.1.2. Request Cancellation and Rejection 773 Clients can cancel requests by resetting and aborting the request 774 stream with an error code of H3_REQUEST_CANCELLED (Section 8.1). 775 When the client aborts reading a response, it indicates that this 776 response is no longer of interest. Implementations SHOULD cancel 777 requests by abruptly terminating any directions of a stream that are 778 still open. 780 When the server rejects a request without performing any application 781 processing, it SHOULD abort its response stream with the error code 782 H3_REQUEST_REJECTED. In this context, "processed" means that some 783 data from the stream was passed to some higher layer of software that 784 might have taken some action as a result. The client can treat 785 requests rejected by the server as though they had never been sent at 786 all, thereby allowing them to be retried later on a new connection. 787 Servers MUST NOT use the H3_REQUEST_REJECTED error code for requests 788 which were partially or fully processed. When a server abandons a 789 response after partial processing, it SHOULD abort its response 790 stream with the error code H3_REQUEST_CANCELLED. 792 When a client resets a request with the error code 793 H3_REQUEST_CANCELLED, a server MAY abruptly terminate the response 794 using the error code H3_REQUEST_REJECTED if no processing was 795 performed. Clients MUST NOT use the H3_REQUEST_REJECTED error code, 796 except when a server has requested closure of the request stream with 797 this error code. 799 If a stream is cancelled after receiving a complete response, the 800 client MAY ignore the cancellation and use the response. However, if 801 a stream is cancelled after receiving a partial response, the 802 response SHOULD NOT be used. Automatically retrying such requests is 803 not possible, unless this is otherwise permitted (e.g., idempotent 804 actions like GET, PUT, or DELETE). 806 4.1.3. Malformed Requests and Responses 808 A malformed request or response is one that is an otherwise valid 809 sequence of frames but is invalid due to: 811 * the presence of prohibited fields or pseudo-header fields, 813 * the absence of mandatory pseudo-header fields, 815 * invalid values for pseudo-header fields, 817 * pseudo-header fields after fields, 819 * an invalid sequence of HTTP messages, 821 * the inclusion of uppercase field names, or 823 * the inclusion of invalid characters in field names or values 825 A request or response that includes a payload body can include a 826 Content-Length header field. A request or response is also malformed 827 if the value of a content-length header field does not equal the sum 828 of the DATA frame payload lengths that form the body. A response 829 that is defined to have no payload, as described in Section 6.3.3 of 830 [SEMANTICS] can have a non-zero content-length field, even though no 831 content is included in DATA frames. 833 Intermediaries that process HTTP requests or responses (i.e., any 834 intermediary not acting as a tunnel) MUST NOT forward a malformed 835 request or response. Malformed requests or responses that are 836 detected MUST be treated as a stream error (Section 8) of type 837 H3_GENERAL_PROTOCOL_ERROR. 839 For malformed requests, a server MAY send an HTTP response prior to 840 closing or resetting the stream. Clients MUST NOT accept a malformed 841 response. Note that these requirements are intended to protect 842 against several types of common attacks against HTTP; they are 843 deliberately strict because being permissive can expose 844 implementations to these vulnerabilities. 846 4.2. The CONNECT Method 848 The CONNECT method requests that the recipient establish a tunnel to 849 the destination origin server identified by the request-target 850 (Section 3.2 of [HTTP11]). It is primarily used with HTTP proxies to 851 establish a TLS session with an origin server for the purposes of 852 interacting with "https" resources. 854 In HTTP/1.x, CONNECT is used to convert an entire HTTP connection 855 into a tunnel to a remote host. In HTTP/2 and HTTP/3, the CONNECT 856 method is used to establish a tunnel over a single stream. 858 A CONNECT request MUST be constructed as follows: 860 * The ":method" pseudo-header field is set to "CONNECT" 862 * The ":scheme" and ":path" pseudo-header fields are omitted 864 * The ":authority" pseudo-header field contains the host and port to 865 connect to (equivalent to the authority-form of the request-target 866 of CONNECT requests; see Section 5.3 of [HTTP11]) 868 The request stream remains open at the end of the request to carry 869 the data to be transferred. A CONNECT request that does not conform 870 to these restrictions is malformed; see Section 4.1.3. 872 A proxy that supports CONNECT establishes a TCP connection 873 ([RFC0793]) to the server identified in the ":authority" pseudo- 874 header field. Once this connection is successfully established, the 875 proxy sends a HEADERS frame containing a 2xx series status code to 876 the client, as defined in Section 9.3 of [SEMANTICS]. 878 All DATA frames on the stream correspond to data sent or received on 879 the TCP connection. Any DATA frame sent by the client is transmitted 880 by the proxy to the TCP server; data received from the TCP server is 881 packaged into DATA frames by the proxy. Note that the size and 882 number of TCP segments is not guaranteed to map predictably to the 883 size and number of HTTP DATA or QUIC STREAM frames. 885 Once the CONNECT method has completed, only DATA frames are permitted 886 to be sent on the stream. Extension frames MAY be used if 887 specifically permitted by the definition of the extension. Receipt 888 of any other frame type MUST be treated as a connection error of type 889 H3_FRAME_UNEXPECTED. 891 The TCP connection can be closed by either peer. When the client 892 ends the request stream (that is, the receive stream at the proxy 893 enters the "Data Recvd" state), the proxy will set the FIN bit on its 894 connection to the TCP server. When the proxy receives a packet with 895 the FIN bit set, it will terminate the send stream that it sends to 896 the client. TCP connections which remain half-closed in a single 897 direction are not invalid, but are often handled poorly by servers, 898 so clients SHOULD NOT close a stream for sending while they still 899 expect to receive data from the target of the CONNECT. 901 A TCP connection error is signaled by abruptly terminating the 902 stream. A proxy treats any error in the TCP connection, which 903 includes receiving a TCP segment with the RST bit set, as a stream 904 error of type H3_CONNECT_ERROR (Section 8.1). Correspondingly, if a 905 proxy detects an error with the stream or the QUIC connection, it 906 MUST close the TCP connection. If the underlying TCP implementation 907 permits it, the proxy SHOULD send a TCP segment with the RST bit set. 909 4.3. HTTP Upgrade 911 HTTP/3 does not support the HTTP Upgrade mechanism (Section 9.9 of 912 [HTTP11]) or 101 (Switching Protocols) informational status code 913 (Section 9.2.2 of [SEMANTICS]). 915 4.4. Server Push 917 Server push is an interaction mode which permits a server to push a 918 request-response exchange to a client in anticipation of the client 919 making the indicated request. This trades off network usage against 920 a potential latency gain. HTTP/3 server push is similar to what is 921 described in HTTP/2 [HTTP2], but uses different mechanisms. 923 Each server push is identified by a unique Push ID. This Push ID is 924 used in one or more PUSH_PROMISE frames (see Section 7.2.5) that 925 carry the request fields, then included with the push stream which 926 ultimately fulfills those promises. When the same Push ID is 927 promised on multiple request streams, the decompressed request field 928 sections MUST contain the same fields in the same order, and both the 929 name and the value in each field MUST be exact matches. 931 Server push is only enabled on a connection when a client sends a 932 MAX_PUSH_ID frame; see Section 7.2.7. A server cannot use server 933 push until it receives a MAX_PUSH_ID frame. A client sends 934 additional MAX_PUSH_ID frames to control the number of pushes that a 935 server can promise. A server SHOULD use Push IDs sequentially, 936 starting at 0. A client MUST treat receipt of a push stream with a 937 Push ID that is greater than the maximum Push ID as a connection 938 error of type H3_ID_ERROR. 940 The header section of the request message is carried by a 941 PUSH_PROMISE frame (see Section 7.2.5) on the request stream which 942 generated the push. This allows the server push to be associated 943 with a client request. 945 Not all requests can be pushed. A server MAY push requests which 946 have the following properties: 948 * cacheable; see Section 7.2.3 of [SEMANTICS] 949 * safe; see Section 7.2.1 of [SEMANTICS] 951 * does not include a request body or trailer section 953 The server MUST include a value in the ":authority" pseudo-header 954 field for which the server is authoritative; see Section 3.4. 956 Clients SHOULD send a CANCEL_PUSH frame upon receipt of a 957 PUSH_PROMISE frame carrying a request which is not cacheable, is not 958 known to be safe, that indicates the presence of a request body, or 959 for which it does not consider the server authoritative. 961 Each pushed response is associated with one or more client requests. 962 The push is associated with the request stream on which the 963 PUSH_PROMISE frame was received. The same server push can be 964 associated with additional client requests using a PUSH_PROMISE frame 965 with the same Push ID on multiple request streams. These 966 associations do not affect the operation of the protocol, but MAY be 967 considered by user agents when deciding how to use pushed resources. 969 Ordering of a PUSH_PROMISE in relation to certain parts of the 970 response is important. The server SHOULD send PUSH_PROMISE frames 971 prior to sending HEADERS or DATA frames that reference the promised 972 responses. This reduces the chance that a client requests a resource 973 that will be pushed by the server. 975 When a server later fulfills a promise, the server push response is 976 conveyed on a push stream; see Section 6.2.2. The push stream 977 identifies the Push ID of the promise that it fulfills, then contains 978 a response to the promised request using the same format described 979 for responses in Section 4.1. 981 Due to reordering, push stream data can arrive before the 982 corresponding PUSH_PROMISE frame. When a client receives a new push 983 stream with an as-yet-unknown Push ID, both the associated client 984 request and the pushed request header fields are unknown. The client 985 can buffer the stream data in expectation of the matching 986 PUSH_PROMISE. The client can use stream flow control (see section 987 4.1 of [QUIC-TRANSPORT]) to limit the amount of data a server may 988 commit to the pushed stream. 990 If a promised server push is not needed by the client, the client 991 SHOULD send a CANCEL_PUSH frame. If the push stream is already open 992 or opens after sending the CANCEL_PUSH frame, the client can abort 993 reading the stream with an error code of H3_REQUEST_CANCELLED. This 994 asks the server not to transfer additional data and indicates that it 995 will be discarded upon receipt. 997 Pushed responses that are cacheable (see Section 3 of [CACHING]) can 998 be stored by the client, if it implements an HTTP cache. Pushed 999 responses are considered successfully validated on the origin server 1000 (e.g., if the "no-cache" cache response directive is present 1001 (Section 5.2.2.3 of [CACHING])) at the time the pushed response is 1002 received. 1004 Pushed responses that are not cacheable MUST NOT be stored by any 1005 HTTP cache. They MAY be made available to the application 1006 separately. 1008 5. Connection Closure 1010 Once established, an HTTP/3 connection can be used for many requests 1011 and responses over time until the connection is closed. Connection 1012 closure can happen in any of several different ways. 1014 5.1. Idle Connections 1016 Each QUIC endpoint declares an idle timeout during the handshake. If 1017 the connection remains idle (no packets received) for longer than 1018 this duration, the peer will assume that the connection has been 1019 closed. HTTP/3 implementations will need to open a new connection 1020 for new requests if the existing connection has been idle for longer 1021 than the server's advertised idle timeout, and SHOULD do so if 1022 approaching the idle timeout. 1024 HTTP clients are expected to request that the transport keep 1025 connections open while there are responses outstanding for requests 1026 or server pushes, as described in Section 19.2 of [QUIC-TRANSPORT]. 1027 If the client is not expecting a response from the server, allowing 1028 an idle connection to time out is preferred over expending effort 1029 maintaining a connection that might not be needed. A gateway MAY 1030 maintain connections in anticipation of need rather than incur the 1031 latency cost of connection establishment to servers. Servers SHOULD 1032 NOT actively keep connections open. 1034 5.2. Connection Shutdown 1036 Even when a connection is not idle, either endpoint can decide to 1037 stop using the connection and initiate a graceful connection close. 1038 Endpoints initiate the graceful shutdown of a connection by sending a 1039 GOAWAY frame (Section 7.2.6). The GOAWAY frame contains an 1040 identifier that indicates to the receiver the range of requests or 1041 pushes that were or might be processed in this connection. The 1042 server sends a client-initiated bidirectional Stream ID; the client 1043 sends a Push ID. Requests or pushes with the indicated identifier or 1044 greater are rejected by the sender of the GOAWAY. This identifier 1045 MAY be zero if no requests or pushes were processed. 1047 The information in the GOAWAY frame enables a client and server to 1048 agree on which requests or pushes were accepted prior to the 1049 connection shutdown. Upon sending a GOAWAY frame, the endpoint 1050 SHOULD explicitly cancel (see Section 4.1.2 and Section 7.2.3) any 1051 requests or pushes that have identifiers greater than or equal to 1052 that indicated, in order to clean up transport state for the affected 1053 streams. The endpoint SHOULD continue to do so as more requests or 1054 pushes arrive. 1056 Endpoints MUST NOT initiate new requests or promise new pushes on the 1057 connection after receipt of a GOAWAY frame from the peer. Clients 1058 MAY establish a new connection to send additional requests. 1060 Some requests or pushes might already be in transit: 1062 * Upon receipt of a GOAWAY frame, if the client has already sent 1063 requests with a Stream ID greater than or equal to the identifier 1064 received in a GOAWAY frame, those requests will not be processed. 1065 Clients can safely retry unprocessed requests on a different 1066 connection. 1068 Requests on Stream IDs less than the Stream ID in a GOAWAY frame 1069 from the server might have been processed; their status cannot be 1070 known until a response is received, the stream is reset 1071 individually, another GOAWAY is received, or the connection 1072 terminates. 1074 Servers MAY reject individual requests on streams below the 1075 indicated ID if these requests were not processed. 1077 * If a server receives a GOAWAY frame after having promised pushes 1078 with a Push ID greater than or equal to the identifier received in 1079 a GOAWAY frame, those pushes will not be accepted. 1081 Servers SHOULD send a GOAWAY frame when the closing of a connection 1082 is known in advance, even if the advance notice is small, so that the 1083 remote peer can know whether a request has been partially processed 1084 or not. For example, if an HTTP client sends a POST at the same time 1085 that a server closes a QUIC connection, the client cannot know if the 1086 server started to process that POST request if the server does not 1087 send a GOAWAY frame to indicate what streams it might have acted on. 1089 A client that is unable to retry requests loses all requests that are 1090 in flight when the server closes the connection. An endpoint MAY 1091 send multiple GOAWAY frames indicating different identifiers, but 1092 MUST NOT increase the identifier value they send, since clients might 1093 already have retried unprocessed requests on another connection. 1095 An endpoint that is attempting to gracefully shut down a connection 1096 can send a GOAWAY frame with a value set to the maximum possible 1097 value (2^62-4 for servers, 2^62-1 for clients). This ensures that 1098 the peer stops creating new requests or pushes. After allowing time 1099 for any in-flight requests or pushes to arrive, the endpoint can send 1100 another GOAWAY frame indicating which requests or pushes it might 1101 accept before the end of the connection. This ensures that a 1102 connection can be cleanly shut down without losing requests. 1104 A client has more flexibility in the value it chooses for the Push ID 1105 in a GOAWAY that it sends. A value of 2^62 - 1 indicates that the 1106 server can continue fulfilling pushes which have already been 1107 promised, and the client can continue granting push credit as needed; 1108 see Section 7.2.7. A smaller value indicates the client will reject 1109 pushes with Push IDs greater than or equal to this value. Like the 1110 server, the client MAY send subsequent GOAWAY frames so long as the 1111 specified Push ID is strictly smaller than all previously sent 1112 values. 1114 Even when a GOAWAY indicates that a given request or push will not be 1115 processed or accepted upon receipt, the underlying transport 1116 resources still exist. The endpoint that initiated these requests 1117 can cancel them to clean up transport state. 1119 Once all accepted requests and pushes have been processed, the 1120 endpoint can permit the connection to become idle, or MAY initiate an 1121 immediate closure of the connection. An endpoint that completes a 1122 graceful shutdown SHOULD use the H3_NO_ERROR code when closing the 1123 connection. 1125 If a client has consumed all available bidirectional stream IDs with 1126 requests, the server need not send a GOAWAY frame, since the client 1127 is unable to make further requests. 1129 5.3. Immediate Application Closure 1131 An HTTP/3 implementation can immediately close the QUIC connection at 1132 any time. This results in sending a QUIC CONNECTION_CLOSE frame to 1133 the peer indicating that the application layer has terminated the 1134 connection. The application error code in this frame indicates to 1135 the peer why the connection is being closed. See Section 8 for error 1136 codes which can be used when closing a connection in HTTP/3. 1138 Before closing the connection, a GOAWAY frame MAY be sent to allow 1139 the client to retry some requests. Including the GOAWAY frame in the 1140 same packet as the QUIC CONNECTION_CLOSE frame improves the chances 1141 of the frame being received by clients. 1143 5.4. Transport Closure 1145 For various reasons, the QUIC transport could indicate to the 1146 application layer that the connection has terminated. This might be 1147 due to an explicit closure by the peer, a transport-level error, or a 1148 change in network topology which interrupts connectivity. 1150 If a connection terminates without a GOAWAY frame, clients MUST 1151 assume that any request which was sent, whether in whole or in part, 1152 might have been processed. 1154 6. Stream Mapping and Usage 1156 A QUIC stream provides reliable in-order delivery of bytes, but makes 1157 no guarantees about order of delivery with regard to bytes on other 1158 streams. On the wire, data is framed into QUIC STREAM frames, but 1159 this framing is invisible to the HTTP framing layer. The transport 1160 layer buffers and orders received QUIC STREAM frames, exposing the 1161 data contained within as a reliable byte stream to the application. 1162 Although QUIC permits out-of-order delivery within a stream, HTTP/3 1163 does not make use of this feature. 1165 QUIC streams can be either unidirectional, carrying data only from 1166 initiator to receiver, or bidirectional. Streams can be initiated by 1167 either the client or the server. For more detail on QUIC streams, 1168 see Section 2 of [QUIC-TRANSPORT]. 1170 When HTTP fields and data are sent over QUIC, the QUIC layer handles 1171 most of the stream management. HTTP does not need to do any separate 1172 multiplexing when using QUIC - data sent over a QUIC stream always 1173 maps to a particular HTTP transaction or connection context. 1175 6.1. Bidirectional Streams 1177 All client-initiated bidirectional streams are used for HTTP requests 1178 and responses. A bidirectional stream ensures that the response can 1179 be readily correlated with the request. This means that the client's 1180 first request occurs on QUIC stream 0, with subsequent requests on 1181 stream 4, 8, and so on. In order to permit these streams to open, an 1182 HTTP/3 server SHOULD configure non-zero minimum values for the number 1183 of permitted streams and the initial stream flow control window. So 1184 as to not unnecessarily limit parallelism, at least 100 requests 1185 SHOULD be permitted at a time. 1187 HTTP/3 does not use server-initiated bidirectional streams, though an 1188 extension could define a use for these streams. Clients MUST treat 1189 receipt of a server-initiated bidirectional stream as a connection 1190 error of type H3_STREAM_CREATION_ERROR unless such an extension has 1191 been negotiated. 1193 6.2. Unidirectional Streams 1195 Unidirectional streams, in either direction, are used for a range of 1196 purposes. The purpose is indicated by a stream type, which is sent 1197 as a variable-length integer at the start of the stream. The format 1198 and structure of data that follows this integer is determined by the 1199 stream type. 1201 Unidirectional Stream Header { 1202 Stream Type (i), 1203 } 1205 Figure 1: Unidirectional Stream Header 1207 Some stream types are reserved (Section 6.2.3). Two stream types are 1208 defined in this document: control streams (Section 6.2.1) and push 1209 streams (Section 6.2.2). [QPACK] defines two additional stream 1210 types. Other stream types can be defined by extensions to HTTP/3; 1211 see Section 9 for more details. 1213 The performance of HTTP/3 connections in the early phase of their 1214 lifetime is sensitive to the creation and exchange of data on 1215 unidirectional streams. Endpoints that excessively restrict the 1216 number of streams or the flow control window of these streams will 1217 increase the chance that the remote peer reaches the limit early and 1218 becomes blocked. In particular, implementations should consider that 1219 remote peers may wish to exercise reserved stream behavior 1220 (Section 6.2.3) with some of the unidirectional streams they are 1221 permitted to use. To avoid blocking, the transport parameters sent 1222 by both clients and servers MUST allow the peer to create at least 1223 one unidirectional stream for the HTTP control stream plus the number 1224 of unidirectional streams required by mandatory extensions (three 1225 being the minimum number required for the base HTTP/3 protocol and 1226 QPACK), and SHOULD provide at least 1,024 bytes of flow control 1227 credit to each stream. 1229 Note that an endpoint is not required to grant additional credits to 1230 create more unidirectional streams if its peer consumes all the 1231 initial credits before creating the critical unidirectional streams. 1232 Endpoints SHOULD create the HTTP control stream as well as the 1233 unidirectional streams required by mandatory extensions (such as the 1234 QPACK encoder and decoder streams) first, and then create additional 1235 streams as allowed by their peer. 1237 If the stream header indicates a stream type which is not supported 1238 by the recipient, the remainder of the stream cannot be consumed as 1239 the semantics are unknown. Recipients of unknown stream types MAY 1240 abort reading of the stream with an error code of 1241 H3_STREAM_CREATION_ERROR, but MUST NOT consider such streams to be a 1242 connection error of any kind. 1244 Implementations MAY send stream types before knowing whether the peer 1245 supports them. However, stream types which could modify the state or 1246 semantics of existing protocol components, including QPACK or other 1247 extensions, MUST NOT be sent until the peer is known to support them. 1249 A sender can close or reset a unidirectional stream unless otherwise 1250 specified. A receiver MUST tolerate unidirectional streams being 1251 closed or reset prior to the reception of the unidirectional stream 1252 header. 1254 6.2.1. Control Streams 1256 A control stream is indicated by a stream type of 0x00. Data on this 1257 stream consists of HTTP/3 frames, as defined in Section 7.2. 1259 Each side MUST initiate a single control stream at the beginning of 1260 the connection and send its SETTINGS frame as the first frame on this 1261 stream. If the first frame of the control stream is any other frame 1262 type, this MUST be treated as a connection error of type 1263 H3_MISSING_SETTINGS. Only one control stream per peer is permitted; 1264 receipt of a second stream which claims to be a control stream MUST 1265 be treated as a connection error of type H3_STREAM_CREATION_ERROR. 1266 The sender MUST NOT close the control stream, and the receiver MUST 1267 NOT request that the sender close the control stream. If either 1268 control stream is closed at any point, this MUST be treated as a 1269 connection error of type H3_CLOSED_CRITICAL_STREAM. 1271 A pair of unidirectional streams is used rather than a single 1272 bidirectional stream. This allows either peer to send data as soon 1273 as it is able. Depending on whether 0-RTT is enabled on the 1274 connection, either client or server might be able to send stream data 1275 first after the cryptographic handshake completes. 1277 6.2.2. Push Streams 1279 Server push is an optional feature introduced in HTTP/2 that allows a 1280 server to initiate a response before a request has been made. See 1281 Section 4.4 for more details. 1283 A push stream is indicated by a stream type of 0x01, followed by the 1284 Push ID of the promise that it fulfills, encoded as a variable-length 1285 integer. The remaining data on this stream consists of HTTP/3 1286 frames, as defined in Section 7.2, and fulfills a promised server 1287 push by zero or more interim HTTP responses followed by a single 1288 final HTTP response, as defined in Section 4.1. Server push and Push 1289 IDs are described in Section 4.4. 1291 Only servers can push; if a server receives a client-initiated push 1292 stream, this MUST be treated as a connection error of type 1293 H3_STREAM_CREATION_ERROR. 1295 Push Stream Header { 1296 Stream Type (i) = 0x01, 1297 Push ID (i), 1298 } 1300 Figure 2: Push Stream Header 1302 Each Push ID MUST only be used once in a push stream header. If a 1303 push stream header includes a Push ID that was used in another push 1304 stream header, the client MUST treat this as a connection error of 1305 type H3_ID_ERROR. 1307 6.2.3. Reserved Stream Types 1309 Stream types of the format "0x1f * N + 0x21" for non-negative integer 1310 values of N are reserved to exercise the requirement that unknown 1311 types be ignored. These streams have no semantics, and can be sent 1312 when application-layer padding is desired. They MAY also be sent on 1313 connections where no data is currently being transferred. Endpoints 1314 MUST NOT consider these streams to have any meaning upon receipt. 1316 The payload and length of the stream are selected in any manner the 1317 implementation chooses. Implementations MAY terminate these streams 1318 cleanly, or MAY abruptly terminate them. When terminating abruptly, 1319 the error code H3_NO_ERROR or a reserved error code (Section 8.1) 1320 SHOULD be used. 1322 7. HTTP Framing Layer 1324 HTTP frames are carried on QUIC streams, as described in Section 6. 1325 HTTP/3 defines three stream types: control stream, request stream, 1326 and push stream. This section describes HTTP/3 frame formats and the 1327 streams types on which they are permitted; see Table 1 for an 1328 overview. A comparison between HTTP/2 and HTTP/3 frames is provided 1329 in Appendix A.2. 1331 +--------------+----------------+----------------+--------+---------+ 1332 | Frame | Control Stream | Request | Push | Section | 1333 | | | Stream | Stream | | 1334 +==============+================+================+========+=========+ 1335 | DATA | No | Yes | Yes | Section | 1336 | | | | | 7.2.1 | 1337 +--------------+----------------+----------------+--------+---------+ 1338 | HEADERS | No | Yes | Yes | Section | 1339 | | | | | 7.2.2 | 1340 +--------------+----------------+----------------+--------+---------+ 1341 | CANCEL_PUSH | Yes | No | No | Section | 1342 | | | | | 7.2.3 | 1343 +--------------+----------------+----------------+--------+---------+ 1344 | SETTINGS | Yes (1) | No | No | Section | 1345 | | | | | 7.2.4 | 1346 +--------------+----------------+----------------+--------+---------+ 1347 | PUSH_PROMISE | No | Yes | No | Section | 1348 | | | | | 7.2.5 | 1349 +--------------+----------------+----------------+--------+---------+ 1350 | GOAWAY | Yes | No | No | Section | 1351 | | | | | 7.2.6 | 1352 +--------------+----------------+----------------+--------+---------+ 1353 | MAX_PUSH_ID | Yes | No | No | Section | 1354 | | | | | 7.2.7 | 1355 +--------------+----------------+----------------+--------+---------+ 1356 | Reserved | Yes | Yes | Yes | Section | 1357 | | | | | 7.2.8 | 1358 +--------------+----------------+----------------+--------+---------+ 1360 Table 1: HTTP/3 Frames and Stream Type Overview 1362 Certain frames can only occur as the first frame of a particular 1363 stream type; these are indicated in Table 1 with a (1). Specific 1364 guidance is provided in the relevant section. 1366 Note that, unlike QUIC frames, HTTP/3 frames can span multiple 1367 packets. 1369 7.1. Frame Layout 1371 All frames have the following format: 1373 HTTP/3 Frame Format { 1374 Type (i), 1375 Length (i), 1376 Frame Payload (..), 1377 } 1379 Figure 3: HTTP/3 Frame Format 1381 A frame includes the following fields: 1383 Type: A variable-length integer that identifies the frame type. 1385 Length: A variable-length integer that describes the length in bytes 1386 of the Frame Payload. 1388 Frame Payload: A payload, the semantics of which are determined by 1389 the Type field. 1391 Each frame's payload MUST contain exactly the fields identified in 1392 its description. A frame payload that contains additional bytes 1393 after the identified fields or a frame payload that terminates before 1394 the end of the identified fields MUST be treated as a connection 1395 error of type H3_FRAME_ERROR. 1397 When a stream terminates cleanly, if the last frame on the stream was 1398 truncated, this MUST be treated as a connection error (Section 8) of 1399 type H3_FRAME_ERROR. Streams which terminate abruptly may be reset 1400 at any point in a frame. 1402 7.2. Frame Definitions 1404 7.2.1. DATA 1406 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 1407 bytes associated with an HTTP request or response payload. 1409 DATA frames MUST be associated with an HTTP request or response. If 1410 a DATA frame is received on a control stream, the recipient MUST 1411 respond with a connection error (Section 8) of type 1412 H3_FRAME_UNEXPECTED. 1414 DATA Frame { 1415 Type (i) = 0x0, 1416 Length (i), 1417 Data (..), 1418 } 1420 Figure 4: DATA Frame 1422 7.2.2. HEADERS 1424 The HEADERS frame (type=0x1) is used to carry an HTTP field section, 1425 encoded using QPACK. See [QPACK] for more details. 1427 HEADERS Frame { 1428 Type (i) = 0x1, 1429 Length (i), 1430 Encoded Field Section (..), 1431 } 1433 Figure 5: HEADERS Frame 1435 HEADERS frames can only be sent on request / push streams. If a 1436 HEADERS frame is received on a control stream, the recipient MUST 1437 respond with a connection error (Section 8) of type 1438 H3_FRAME_UNEXPECTED. 1440 7.2.3. CANCEL_PUSH 1442 The CANCEL_PUSH frame (type=0x3) is used to request cancellation of a 1443 server push prior to the push stream being received. The CANCEL_PUSH 1444 frame identifies a server push by Push ID (see Section 7.2.5), 1445 encoded as a variable-length integer. 1447 When a client sends CANCEL_PUSH, it is indicating that it does not 1448 wish to receive the promised resource. The server SHOULD abort 1449 sending the resource, but the mechanism to do so depends on the state 1450 of the corresponding push stream. If the server has not yet created 1451 a push stream, it does not create one. If the push stream is open, 1452 the server SHOULD abruptly terminate that stream. If the push stream 1453 has already ended, the server MAY still abruptly terminate the stream 1454 or MAY take no action. 1456 When a server sends CANCEL_PUSH, it is indicating that it will not be 1457 fulfilling a promise and has not created a push stream. The client 1458 should not expect the corresponding promise to be fulfilled. 1460 Sending CANCEL_PUSH has no direct effect on the state of existing 1461 push streams. A server SHOULD NOT send a CANCEL_PUSH when it has 1462 already created a corresponding push stream, and a client SHOULD NOT 1463 send a CANCEL_PUSH when it has already received a corresponding push 1464 stream. If a push stream arrives after a client has sent 1465 CANCEL_PUSH, this MAY be treated as a stream error of type 1466 H3_STREAM_CREATION_ERROR. 1468 A CANCEL_PUSH frame is sent on the control stream. Receiving a 1469 CANCEL_PUSH frame on a stream other than the control stream MUST be 1470 treated as a connection error of type H3_FRAME_UNEXPECTED. 1472 CANCEL_PUSH Frame { 1473 Type (i) = 0x3, 1474 Length (i), 1475 Push ID (..), 1476 } 1478 Figure 6: CANCEL_PUSH Frame 1480 The CANCEL_PUSH frame carries a Push ID encoded as a variable-length 1481 integer. The Push ID identifies the server push that is being 1482 cancelled; see Section 7.2.5. If a CANCEL_PUSH frame is received 1483 which references a Push ID greater than currently allowed on the 1484 connection, this MUST be treated as a connection error of type 1485 H3_ID_ERROR. 1487 If the client receives a CANCEL_PUSH frame, that frame might identify 1488 a Push ID that has not yet been mentioned by a PUSH_PROMISE frame due 1489 to reordering. If a server receives a CANCEL_PUSH frame for a Push 1490 ID that has not yet been mentioned by a PUSH_PROMISE frame, this MUST 1491 be treated as a connection error of type H3_ID_ERROR. 1493 7.2.4. SETTINGS 1495 The SETTINGS frame (type=0x4) conveys configuration parameters that 1496 affect how endpoints communicate, such as preferences and constraints 1497 on peer behavior. Individually, a SETTINGS parameter can also be 1498 referred to as a "setting"; the identifier and value of each setting 1499 parameter can be referred to as a "setting identifier" and a "setting 1500 value". 1502 SETTINGS frames always apply to a connection, never a single stream. 1503 A SETTINGS frame MUST be sent as the first frame of each control 1504 stream (see Section 6.2.1) by each peer, and MUST NOT be sent 1505 subsequently. If an endpoint receives a second SETTINGS frame on the 1506 control stream, the endpoint MUST respond with a connection error of 1507 type H3_FRAME_UNEXPECTED. 1509 SETTINGS frames MUST NOT be sent on any stream other than the control 1510 stream. If an endpoint receives a SETTINGS frame on a different 1511 stream, the endpoint MUST respond with a connection error of type 1512 H3_FRAME_UNEXPECTED. 1514 SETTINGS parameters are not negotiated; they describe characteristics 1515 of the sending peer, which can be used by the receiving peer. 1516 However, a negotiation can be implied by the use of SETTINGS - each 1517 peer uses SETTINGS to advertise a set of supported values. The 1518 definition of the setting would describe how each peer combines the 1519 two sets to conclude which choice will be used. SETTINGS does not 1520 provide a mechanism to identify when the choice takes effect. 1522 Different values for the same parameter can be advertised by each 1523 peer. For example, a client might be willing to consume a very large 1524 response field section, while servers are more cautious about request 1525 size. 1527 The same setting identifier MUST NOT occur more than once in the 1528 SETTINGS frame. A receiver MAY treat the presence of duplicate 1529 setting identifiers as a connection error of type H3_SETTINGS_ERROR. 1531 The payload of a SETTINGS frame consists of zero or more parameters. 1532 Each parameter consists of a setting identifier and a value, both 1533 encoded as QUIC variable-length integers. 1535 Setting { 1536 Identifier (i), 1537 Value (i), 1538 } 1540 SETTINGS Frame { 1541 Type (i) = 0x4, 1542 Length (i), 1543 Setting (..) ..., 1544 } 1546 Figure 7: SETTINGS Frame 1548 An implementation MUST ignore the contents for any SETTINGS 1549 identifier it does not understand. 1551 7.2.4.1. Defined SETTINGS Parameters 1553 The following settings are defined in HTTP/3: 1555 SETTINGS_MAX_FIELD_SECTION_SIZE (0x6): The default value is 1556 unlimited. See Section 4.1.1 for usage. 1558 Setting identifiers of the format "0x1f * N + 0x21" for non-negative 1559 integer values of N are reserved to exercise the requirement that 1560 unknown identifiers be ignored. Such settings have no defined 1561 meaning. Endpoints SHOULD include at least one such setting in their 1562 SETTINGS frame. Endpoints MUST NOT consider such settings to have 1563 any meaning upon receipt. 1565 Because the setting has no defined meaning, the value of the setting 1566 can be any value the implementation selects. 1568 Additional settings can be defined by extensions to HTTP/3; see 1569 Section 9 for more details. 1571 7.2.4.2. Initialization 1573 An HTTP implementation MUST NOT send frames or requests which would 1574 be invalid based on its current understanding of the peer's settings. 1576 All settings begin at an initial value. Each endpoint SHOULD use 1577 these initial values to send messages before the peer's SETTINGS 1578 frame has arrived, as packets carrying the settings can be lost or 1579 delayed. When the SETTINGS frame arrives, any settings are changed 1580 to their new values. 1582 This removes the need to wait for the SETTINGS frame before sending 1583 messages. Endpoints MUST NOT require any data to be received from 1584 the peer prior to sending the SETTINGS frame; settings MUST be sent 1585 as soon as the transport is ready to send data. 1587 For servers, the initial value of each client setting is the default 1588 value. 1590 For clients using a 1-RTT QUIC connection, the initial value of each 1591 server setting is the default value. 1-RTT keys will always become 1592 available prior to SETTINGS arriving, even if the server sends 1593 SETTINGS immediately. Clients SHOULD NOT wait indefinitely for 1594 SETTINGS to arrive before sending requests, but SHOULD process 1595 received datagrams in order to increase the likelihood of processing 1596 SETTINGS before sending the first request. 1598 When a 0-RTT QUIC connection is being used, the initial value of each 1599 server setting is the value used in the previous session. Clients 1600 SHOULD store the settings the server provided in the connection where 1601 resumption information was provided, but MAY opt not to store 1602 settings in certain cases (e.g., if the session ticket is received 1603 before the SETTINGS frame). A client MUST comply with stored 1604 settings - or default values, if no values are stored - when 1605 attempting 0-RTT. Once a server has provided new settings, clients 1606 MUST comply with those values. 1608 A server can remember the settings that it advertised, or store an 1609 integrity-protected copy of the values in the ticket and recover the 1610 information when accepting 0-RTT data. A server uses the HTTP/3 1611 settings values in determining whether to accept 0-RTT data. If the 1612 server cannot determine that the settings remembered by a client are 1613 compatible with its current settings, it MUST NOT accept 0-RTT data. 1614 Remembered settings are compatible if a client complying with those 1615 settings would not violate the server's current settings. 1617 A server MAY accept 0-RTT and subsequently provide different settings 1618 in its SETTINGS frame. If 0-RTT data is accepted by the server, its 1619 SETTINGS frame MUST NOT reduce any limits or alter any values that 1620 might be violated by the client with its 0-RTT data. The server MUST 1621 include all settings which differ from their default values. If a 1622 server accepts 0-RTT but then sends settings that are not compatible 1623 with the previously specified settings, this MUST be treated as a 1624 connection error of type H3_SETTINGS_ERROR. If a server accepts 1625 0-RTT but then sends a SETTINGS frame that omits a setting value that 1626 the client understands (apart from reserved setting identifiers) that 1627 was previously specified to have a non-default value, this MUST be 1628 treated as a connection error of type H3_SETTINGS_ERROR. 1630 7.2.5. PUSH_PROMISE 1632 The PUSH_PROMISE frame (type=0x5) is used to carry a promised request 1633 header field section from server to client on a request stream, as in 1634 HTTP/2. 1636 PUSH_PROMISE Frame { 1637 Type (i) = 0x5, 1638 Length (i), 1639 Push ID (i), 1640 Encoded Field Section (..), 1641 } 1643 Figure 8: PUSH_PROMISE Frame 1645 The payload consists of: 1647 Push ID: A variable-length integer that identifies the server push 1648 operation. A Push ID is used in push stream headers 1649 (Section 4.4), CANCEL_PUSH frames (Section 7.2.3). 1651 Encoded Field Section: QPACK-encoded request header fields for the 1652 promised response. See [QPACK] for more details. 1654 A server MUST NOT use a Push ID that is larger than the client has 1655 provided in a MAX_PUSH_ID frame (Section 7.2.7). A client MUST treat 1656 receipt of a PUSH_PROMISE frame that contains a larger Push ID than 1657 the client has advertised as a connection error of H3_ID_ERROR. 1659 A server MAY use the same Push ID in multiple PUSH_PROMISE frames. 1660 If so, the decompressed request header sets MUST contain the same 1661 fields in the same order, and both the name and the value in each 1662 field MUST be exact matches. Clients SHOULD compare the request 1663 header sections for resources promised multiple times. If a client 1664 receives a Push ID that has already been promised and detects a 1665 mismatch, it MUST respond with a connection error of type 1666 H3_GENERAL_PROTOCOL_ERROR. If the decompressed field sections match 1667 exactly, the client SHOULD associate the pushed content with each 1668 stream on which a PUSH_PROMISE was received. 1670 Allowing duplicate references to the same Push ID is primarily to 1671 reduce duplication caused by concurrent requests. A server SHOULD 1672 avoid reusing a Push ID over a long period. Clients are likely to 1673 consume server push responses and not retain them for reuse over 1674 time. Clients that see a PUSH_PROMISE that uses a Push ID that they 1675 have already consumed and discarded are forced to ignore the 1676 PUSH_PROMISE. 1678 If a PUSH_PROMISE frame is received on the control stream, the client 1679 MUST respond with a connection error (Section 8) of type 1680 H3_FRAME_UNEXPECTED. 1682 A client MUST NOT send a PUSH_PROMISE frame. A server MUST treat the 1683 receipt of a PUSH_PROMISE frame as a connection error of type 1684 H3_FRAME_UNEXPECTED. 1686 See Section 4.4 for a description of the overall server push 1687 mechanism. 1689 7.2.6. GOAWAY 1691 The GOAWAY frame (type=0x7) is used to initiate graceful shutdown of 1692 a connection by either endpoint. GOAWAY allows an endpoint to stop 1693 accepting new requests or pushes while still finishing processing of 1694 previously received requests and pushes. This enables administrative 1695 actions, like server maintenance. GOAWAY by itself does not close a 1696 connection. 1698 GOAWAY Frame { 1699 Type (i) = 0x7, 1700 Length (i), 1701 Stream ID/Push ID (..), 1702 } 1704 Figure 9: GOAWAY Frame 1706 The GOAWAY frame is always sent on the control stream. In the server 1707 to client direction, it carries a QUIC Stream ID for a client- 1708 initiated bidirectional stream encoded as a variable-length integer. 1709 A client MUST treat receipt of a GOAWAY frame containing a Stream ID 1710 of any other type as a connection error of type H3_ID_ERROR. 1712 In the client to server direction, the GOAWAY frame carries a Push ID 1713 encoded as a variable-length integer. 1715 The GOAWAY frame applies to the connection, not a specific stream. A 1716 client MUST treat a GOAWAY frame on a stream other than the control 1717 stream as a connection error (Section 8) of type H3_FRAME_UNEXPECTED. 1719 See Section 5.2 for more information on the use of the GOAWAY frame. 1721 7.2.7. MAX_PUSH_ID 1723 The MAX_PUSH_ID frame (type=0xD) is used by clients to control the 1724 number of server pushes that the server can initiate. This sets the 1725 maximum value for a Push ID that the server can use in PUSH_PROMISE 1726 and CANCEL_PUSH frames. Consequently, this also limits the number of 1727 push streams that the server can initiate in addition to the limit 1728 maintained by the QUIC transport. 1730 The MAX_PUSH_ID frame is always sent on the control stream. Receipt 1731 of a MAX_PUSH_ID frame on any other stream MUST be treated as a 1732 connection error of type H3_FRAME_UNEXPECTED. 1734 A server MUST NOT send a MAX_PUSH_ID frame. A client MUST treat the 1735 receipt of a MAX_PUSH_ID frame as a connection error of type 1736 H3_FRAME_UNEXPECTED. 1738 The maximum Push ID is unset when a connection is created, meaning 1739 that a server cannot push until it receives a MAX_PUSH_ID frame. A 1740 client that wishes to manage the number of promised server pushes can 1741 increase the maximum Push ID by sending MAX_PUSH_ID frames as the 1742 server fulfills or cancels server pushes. 1744 MAX_PUSH_ID Frame { 1745 Type (i) = 0x1, 1746 Length (i), 1747 Push ID (..), 1748 } 1750 Figure 10: MAX_PUSH_ID Frame Payload 1752 The MAX_PUSH_ID frame carries a single variable-length integer that 1753 identifies the maximum value for a Push ID that the server can use; 1754 see Section 7.2.5. A MAX_PUSH_ID frame cannot reduce the maximum 1755 Push ID; receipt of a MAX_PUSH_ID that contains a smaller value than 1756 previously received MUST be treated as a connection error of type 1757 H3_ID_ERROR. 1759 7.2.8. Reserved Frame Types 1761 Frame types of the format "0x1f * N + 0x21" for non-negative integer 1762 values of N are reserved to exercise the requirement that unknown 1763 types be ignored (Section 9). These frames have no semantics, and 1764 can be sent on any open stream when application-layer padding is 1765 desired. They MAY also be sent on connections where no data is 1766 currently being transferred. Endpoints MUST NOT consider these 1767 frames to have any meaning upon receipt. 1769 The payload and length of the frames are selected in any manner the 1770 implementation chooses. 1772 Frame types which were used in HTTP/2 where there is no corresponding 1773 HTTP/3 frame have also been reserved (Section 11.2.1). These frame 1774 types MUST NOT be sent, and receipt MAY be treated as an error of 1775 type H3_FRAME_UNEXPECTED. 1777 8. Error Handling 1779 QUIC allows the application to abruptly terminate (reset) individual 1780 streams or the entire connection when an error is encountered. These 1781 are referred to as "stream errors" or "connection errors" and are 1782 described in more detail in [QUIC-TRANSPORT]. 1784 An endpoint MAY choose to treat a stream error as a connection error 1785 under certain circumstances. Implementations need to consider the 1786 impact on outstanding requests before making this choice. 1788 Because new error codes can be defined without negotiation (see 1789 Section 9), use of an error code in an unexpected context or receipt 1790 of an unknown error code MUST be treated as equivalent to 1791 H3_NO_ERROR. However, closing a stream can have other effects 1792 regardless of the error code; see Section 4.1. 1794 This section describes HTTP/3-specific error codes which can be used 1795 to express the cause of a connection or stream error. 1797 8.1. HTTP/3 Error Codes 1799 The following error codes are defined for use when abruptly 1800 terminating streams, aborting reading of streams, or immediately 1801 closing connections. 1803 H3_NO_ERROR (0x100): No error. This is used when the connection or 1804 stream needs to be closed, but there is no error to signal. 1806 H3_GENERAL_PROTOCOL_ERROR (0x101): Peer violated protocol 1807 requirements in a way which doesn't match a more specific error 1808 code, or endpoint declines to use the more specific error code. 1810 H3_INTERNAL_ERROR (0x102): An internal error has occurred in the 1811 HTTP stack. 1813 H3_STREAM_CREATION_ERROR (0x103): The endpoint detected that its 1814 peer created a stream that it will not accept. 1816 H3_CLOSED_CRITICAL_STREAM (0x104): A stream required by the 1817 connection was closed or reset. 1819 H3_FRAME_UNEXPECTED (0x105): A frame was received which was not 1820 permitted in the current state or on the current stream. 1822 H3_FRAME_ERROR (0x106): A frame that fails to satisfy layout 1823 requirements or with an invalid size was received. 1825 H3_EXCESSIVE_LOAD (0x107): The endpoint detected that its peer is 1826 exhibiting a behavior that might be generating excessive load. 1828 H3_ID_ERROR (0x108): A Stream ID or Push ID was used incorrectly, 1829 such as exceeding a limit, reducing a limit, or being reused. 1831 H3_SETTINGS_ERROR (0x109): An endpoint detected an error in the 1832 payload of a SETTINGS frame. 1834 H3_MISSING_SETTINGS (0x10A): No SETTINGS frame was received at the 1835 beginning of the control stream. 1837 H3_REQUEST_REJECTED (0x10B): A server rejected a request without 1838 performing any application processing. 1840 H3_REQUEST_CANCELLED (0x10C): The request or its response (including 1841 pushed response) is cancelled. 1843 H3_REQUEST_INCOMPLETE (0x10D): The client's stream terminated 1844 without containing a fully-formed request. 1846 H3_CONNECT_ERROR (0x10F): The connection established in response to 1847 a CONNECT request was reset or abnormally closed. 1849 H3_VERSION_FALLBACK (0x110): The requested operation cannot be 1850 served over HTTP/3. The peer should retry over HTTP/1.1. 1852 Error codes of the format "0x1f * N + 0x21" for non-negative integer 1853 values of N are reserved to exercise the requirement that unknown 1854 error codes be treated as equivalent to H3_NO_ERROR (Section 9). 1855 Implementations SHOULD select an error code from this space with some 1856 probability when they would have sent H3_NO_ERROR. 1858 9. Extensions to HTTP/3 1860 HTTP/3 permits extension of the protocol. Within the limitations 1861 described in this section, protocol extensions can be used to provide 1862 additional services or alter any aspect of the protocol. Extensions 1863 are effective only within the scope of a single HTTP/3 connection. 1865 This applies to the protocol elements defined in this document. This 1866 does not affect the existing options for extending HTTP, such as 1867 defining new methods, status codes, or fields. 1869 Extensions are permitted to use new frame types (Section 7.2), new 1870 settings (Section 7.2.4.1), new error codes (Section 8), or new 1871 unidirectional stream types (Section 6.2). Registries are 1872 established for managing these extension points: frame types 1873 (Section 11.2.1), settings (Section 11.2.2), error codes 1874 (Section 11.2.3), and stream types (Section 11.2.4). 1876 Implementations MUST ignore unknown or unsupported values in all 1877 extensible protocol elements. Implementations MUST discard frames 1878 and unidirectional streams that have unknown or unsupported types. 1880 This means that any of these extension points can be safely used by 1881 extensions without prior arrangement or negotiation. However, where 1882 a known frame type is required to be in a specific location, such as 1883 the SETTINGS frame as the first frame of the control stream (see 1884 Section 6.2.1), an unknown frame type does not satisfy that 1885 requirement and SHOULD be treated as an error. 1887 Extensions that could change the semantics of existing protocol 1888 components MUST be negotiated before being used. For example, an 1889 extension that changes the layout of the HEADERS frame cannot be used 1890 until the peer has given a positive signal that this is acceptable. 1891 Coordinating when such a revised layout comes into effect could prove 1892 complex. As such, allocating new identifiers for new definitions of 1893 existing protocol elements is likely to be more effective. 1895 This document doesn't mandate a specific method for negotiating the 1896 use of an extension but notes that a setting (Section 7.2.4.1) could 1897 be used for that purpose. If both peers set a value that indicates 1898 willingness to use the extension, then the extension can be used. If 1899 a setting is used for extension negotiation, the default value MUST 1900 be defined in such a fashion that the extension is disabled if the 1901 setting is omitted. 1903 10. Security Considerations 1905 The security considerations of HTTP/3 should be comparable to those 1906 of HTTP/2 with TLS. However, many of the considerations from 1907 Section 10 of [HTTP2] apply to [QUIC-TRANSPORT] and are discussed in 1908 that document. 1910 10.1. Server Authority 1912 HTTP/3 relies on the HTTP definition of authority. The security 1913 considerations of establishing authority are discussed in 1914 Section 11.1 of [SEMANTICS]. 1916 10.2. Cross-Protocol Attacks 1918 The use of ALPN in the TLS and QUIC handshakes establishes the target 1919 application protocol before application-layer bytes are processed. 1920 Because all QUIC packets are encrypted, it is difficult for an 1921 attacker to control the plaintext bytes of an HTTP/3 connection which 1922 could be used in a cross-protocol attack on a plaintext protocol. 1924 10.3. Intermediary Encapsulation Attacks 1926 The HTTP/3 field encoding allows the expression of names that are not 1927 valid field names in the syntax used by HTTP (Section 4.3 of 1928 [SEMANTICS]). Requests or responses containing invalid field names 1929 MUST be treated as malformed (Section 4.1.3). An intermediary 1930 therefore cannot translate an HTTP/3 request or response containing 1931 an invalid field name into an HTTP/1.1 message. 1933 Similarly, HTTP/3 allows field values that are not valid. While most 1934 of the values that can be encoded will not alter field parsing, 1935 carriage return (CR, ASCII 0xd), line feed (LF, ASCII 0xa), and the 1936 zero character (NUL, ASCII 0x0) might be exploited by an attacker if 1937 they are translated verbatim. Any request or response that contains 1938 a character not permitted in a field value MUST be treated as 1939 malformed (Section 4.1.3). Valid characters are defined by the 1940 "field-content" ABNF rule in Section 4.4 of [SEMANTICS]. 1942 10.4. Cacheability of Pushed Responses 1944 Pushed responses do not have an explicit request from the client; the 1945 request is provided by the server in the PUSH_PROMISE frame. 1947 Caching responses that are pushed is possible based on the guidance 1948 provided by the origin server in the Cache-Control header field. 1949 However, this can cause issues if a single server hosts more than one 1950 tenant. For example, a server might offer multiple users each a 1951 small portion of its URI space. 1953 Where multiple tenants share space on the same server, that server 1954 MUST ensure that tenants are not able to push representations of 1955 resources that they do not have authority over. Failure to enforce 1956 this would allow a tenant to provide a representation that would be 1957 served out of cache, overriding the actual representation that the 1958 authoritative tenant provides. 1960 Pushed responses for which an origin server is not authoritative (see 1961 Section 3.4) MUST NOT be used or cached. 1963 10.5. Denial-of-Service Considerations 1965 An HTTP/3 connection can demand a greater commitment of resources to 1966 operate than an HTTP/1.1 or HTTP/2 connection. The use of field 1967 compression and flow control depend on a commitment of resources for 1968 storing a greater amount of state. Settings for these features 1969 ensure that memory commitments for these features are strictly 1970 bounded. 1972 The number of PUSH_PROMISE frames is constrained in a similar 1973 fashion. A client that accepts server push SHOULD limit the number 1974 of Push IDs it issues at a time. 1976 Processing capacity cannot be guarded as effectively as state 1977 capacity. 1979 The ability to send undefined protocol elements which the peer is 1980 required to ignore can be abused to cause a peer to expend additional 1981 processing time. This might be done by setting multiple undefined 1982 SETTINGS parameters, unknown frame types, or unknown stream types. 1983 Note, however, that some uses are entirely legitimate, such as 1984 optional-to-understand extensions and padding to increase resistance 1985 to traffic analysis. 1987 Compression of field sections also offers some opportunities to waste 1988 processing resources; see Section 7 of [QPACK] for more details on 1989 potential abuses. 1991 All these features - i.e., server push, unknown protocol elements, 1992 field compression - have legitimate uses. These features become a 1993 burden only when they are used unnecessarily or to excess. 1995 An endpoint that doesn't monitor this behavior exposes itself to a 1996 risk of denial-of-service attack. Implementations SHOULD track the 1997 use of these features and set limits on their use. An endpoint MAY 1998 treat activity that is suspicious as a connection error (Section 8) 1999 of type H3_EXCESSIVE_LOAD, but false positives will result in 2000 disrupting valid connections and requests. 2002 10.5.1. Limits on Field Section Size 2004 A large field section (Section 4.1) can cause an implementation to 2005 commit a large amount of state. Header fields that are critical for 2006 routing can appear toward the end of a header field section, which 2007 prevents streaming of the header field section to its ultimate 2008 destination. This ordering and other reasons, such as ensuring cache 2009 correctness, mean that an endpoint likely needs to buffer the entire 2010 header field section. Since there is no hard limit to the size of a 2011 field section, some endpoints could be forced to commit a large 2012 amount of available memory for header fields. 2014 An endpoint can use the SETTINGS_MAX_HEADER_LIST_SIZE 2015 (Section 7.2.4.1) setting to advise peers of limits that might apply 2016 on the size of field sections. This setting is only advisory, so 2017 endpoints MAY choose to send field sections that exceed this limit 2018 and risk having the request or response being treated as malformed. 2019 This setting is specific to a connection, so any request or response 2020 could encounter a hop with a lower, unknown limit. An intermediary 2021 can attempt to avoid this problem by passing on values presented by 2022 different peers, but they are not obligated to do so. 2024 A server that receives a larger field section than it is willing to 2025 handle can send an HTTP 431 (Request Header Fields Too Large) status 2026 code [RFC6585]. A client can discard responses that it cannot 2027 process. 2029 10.5.2. CONNECT Issues 2031 The CONNECT method can be used to create disproportionate load on an 2032 proxy, since stream creation is relatively inexpensive when compared 2033 to the creation and maintenance of a TCP connection. A proxy might 2034 also maintain some resources for a TCP connection beyond the closing 2035 of the stream that carries the CONNECT request, since the outgoing 2036 TCP connection remains in the TIME_WAIT state. Therefore, a proxy 2037 cannot rely on QUIC stream limits alone to control the resources 2038 consumed by CONNECT requests. 2040 10.6. Use of Compression 2042 Compression can allow an attacker to recover secret data when it is 2043 compressed in the same context as data under attacker control. 2044 HTTP/3 enables compression of fields (Section 4.1.1); the following 2045 concerns also apply to the use of HTTP compressed content-codings; 2046 see Section 6.1.2 of [SEMANTICS]. 2048 There are demonstrable attacks on compression that exploit the 2049 characteristics of the web (e.g., [BREACH]). The attacker induces 2050 multiple requests containing varying plaintext, observing the length 2051 of the resulting ciphertext in each, which reveals a shorter length 2052 when a guess about the secret is correct. 2054 Implementations communicating on a secure channel MUST NOT compress 2055 content that includes both confidential and attacker-controlled data 2056 unless separate compression dictionaries are used for each source of 2057 data. Compression MUST NOT be used if the source of data cannot be 2058 reliably determined. 2060 Further considerations regarding the compression of fields sections 2061 are described in [QPACK]. 2063 10.7. Padding and Traffic Analysis 2065 Padding can be used to obscure the exact size of frame content and is 2066 provided to mitigate specific attacks within HTTP, for example, 2067 attacks where compressed content includes both attacker-controlled 2068 plaintext and secret data (e.g., [BREACH]). 2070 Where HTTP/2 employs PADDING frames and Padding fields in other 2071 frames to make a connection more resistant to traffic analysis, 2072 HTTP/3 can either rely on transport-layer padding or employ the 2073 reserved frame and stream types discussed in Section 7.2.8 and 2074 Section 6.2.3. These methods of padding produce different results in 2075 terms of the granularity of padding, how padding is arranged in 2076 relation to the information that is being protected, whether padding 2077 is applied in the case of packet loss, and how an implementation 2078 might control padding. Redundant padding could even be 2079 counterproductive. 2081 To mitigate attacks that rely on compression, disabling or limiting 2082 compression might be preferable to padding as a countermeasure. 2084 Use of padding can result in less protection than might seem 2085 immediately obvious. At best, padding only makes it more difficult 2086 for an attacker to infer length information by increasing the number 2087 of frames an attacker has to observe. Incorrectly implemented 2088 padding schemes can be easily defeated. In particular, randomized 2089 padding with a predictable distribution provides very little 2090 protection; similarly, padding payloads to a fixed size exposes 2091 information as payload sizes cross the fixed-sized boundary, which 2092 could be possible if an attacker can control plaintext. 2094 10.8. Frame Parsing 2096 Several protocol elements contain nested length elements, typically 2097 in the form of frames with an explicit length containing variable- 2098 length integers. This could pose a security risk to an incautious 2099 implementer. An implementation MUST ensure that the length of a 2100 frame exactly matches the length of the fields it contains. 2102 10.9. Early Data 2104 The use of 0-RTT with HTTP/3 creates an exposure to replay attack. 2105 The anti-replay mitigations in [HTTP-REPLAY] MUST be applied when 2106 using HTTP/3 with 0-RTT. 2108 10.10. Migration 2110 Certain HTTP implementations use the client address for logging or 2111 access-control purposes. Since a QUIC client's address might change 2112 during a connection (and future versions might support simultaneous 2113 use of multiple addresses), such implementations will need to either 2114 actively retrieve the client's current address or addresses when they 2115 are relevant or explicitly accept that the original address might 2116 change. 2118 10.11. Privacy Considerations 2120 Several characteristics of HTTP/3 provide an observer an opportunity 2121 to correlate actions of a single client or server over time. These 2122 include the value of settings, the timing of reactions to stimulus, 2123 and the handling of any features that are controlled by settings. 2125 As far as these create observable differences in behavior, they could 2126 be used as a basis for fingerprinting a specific client. 2128 HTTP/3's preference for using a single QUIC connection allows 2129 correlation of a user's activity on a site. Reusing connections for 2130 different origins allows for correlation of activity across those 2131 origins. 2133 Several features of QUIC solicit immediate responses and can be used 2134 by an endpoint to measure latency to their peer; this might have 2135 privacy implications in certain scenarios. 2137 11. IANA Considerations 2139 This document registers a new ALPN protocol ID (Section 11.1) and 2140 creates new registries that manage the assignment of codepoints in 2141 HTTP/3. 2143 11.1. Registration of HTTP/3 Identification String 2145 This document creates a new registration for the identification of 2146 HTTP/3 in the "Application Layer Protocol Negotiation (ALPN) Protocol 2147 IDs" registry established in [RFC7301]. 2149 The "h3" string identifies HTTP/3: 2151 Protocol: HTTP/3 2153 Identification Sequence: 0x68 0x33 ("h3") 2155 Specification: This document 2157 11.2. New Registries 2159 New registries created in this document operate under the QUIC 2160 registration policy documented in Section 22.1 of [QUIC-TRANSPORT]. 2161 These registries all include the common set of fields listed in 2162 Section 22.1.1 of [QUIC-TRANSPORT]. 2164 The initial allocations in these registries created in this document 2165 are all assigned permanent status and list as contact both the IESG 2166 (iesg@ietf.org) and the HTTP working group (ietf-http-wg@w3.org). 2168 11.2.1. Frame Types 2170 This document establishes a registry for HTTP/3 frame type codes. 2171 The "HTTP/3 Frame Type" registry governs a 62-bit space. This 2172 registry follows the QUIC registry policy; see Section 11.2. 2173 Permanent registrations in this registry are assigned using the 2174 Specification Required policy [RFC8126], except for values between 2175 0x00 and 0x3f (in hexadecimal; inclusive), which are assigned using 2176 Standards Action or IESG Approval as defined in Section 4.9 and 4.10 2177 of [RFC8126]. 2179 While this registry is separate from the "HTTP/2 Frame Type" registry 2180 defined in [HTTP2], it is preferable that the assignments parallel 2181 each other where the code spaces overlap. If an entry is present in 2182 only one registry, every effort SHOULD be made to avoid assigning the 2183 corresponding value to an unrelated operation. 2185 In addition to common fields as described in Section 11.2, permanent 2186 registrations in this registry MUST include the following field: 2188 Frame Type: A name or label for the frame type. 2190 Specifications of frame types MUST include a description of the frame 2191 layout and its semantics, including any parts of the frame that are 2192 conditionally present. 2194 The entries in Table 2 are registered by this document. 2196 +--------------+-------+---------------+ 2197 | Frame Type | Value | Specification | 2198 +==============+=======+===============+ 2199 | DATA | 0x0 | Section 7.2.1 | 2200 +--------------+-------+---------------+ 2201 | HEADERS | 0x1 | Section 7.2.2 | 2202 +--------------+-------+---------------+ 2203 | Reserved | 0x2 | N/A | 2204 +--------------+-------+---------------+ 2205 | CANCEL_PUSH | 0x3 | Section 7.2.3 | 2206 +--------------+-------+---------------+ 2207 | SETTINGS | 0x4 | Section 7.2.4 | 2208 +--------------+-------+---------------+ 2209 | PUSH_PROMISE | 0x5 | Section 7.2.5 | 2210 +--------------+-------+---------------+ 2211 | Reserved | 0x6 | N/A | 2212 +--------------+-------+---------------+ 2213 | GOAWAY | 0x7 | Section 7.2.6 | 2214 +--------------+-------+---------------+ 2215 | Reserved | 0x8 | N/A | 2216 +--------------+-------+---------------+ 2217 | Reserved | 0x9 | N/A | 2218 +--------------+-------+---------------+ 2219 | MAX_PUSH_ID | 0xD | Section 7.2.7 | 2220 +--------------+-------+---------------+ 2222 Table 2: Initial HTTP/3 Frame Types 2224 Additionally, each code of the format "0x1f * N + 0x21" for non- 2225 negative integer values of N (that is, 0x21, 0x40, ..., through 2226 0x3FFFFFFFFFFFFFFE) MUST NOT be assigned by IANA. 2228 11.2.2. Settings Parameters 2230 This document establishes a registry for HTTP/3 settings. The 2231 "HTTP/3 Settings" registry governs a 62-bit space. This registry 2232 follows the QUIC registry policy; see Section 11.2. Permanent 2233 registrations in this registry are assigned using the Specification 2234 Required policy [RFC8126], except for values between 0x00 and 0x3f 2235 (in hexadecimal; inclusive), which are assigned using Standards 2236 Action or IESG Approval as defined in Section 4.9 and 4.10 of 2237 [RFC8126]. 2239 While this registry is separate from the "HTTP/2 Settings" registry 2240 defined in [HTTP2], it is preferable that the assignments parallel 2241 each other. If an entry is present in only one registry, every 2242 effort SHOULD be made to avoid assigning the corresponding value to 2243 an unrelated operation. 2245 In addition to common fields as described in Section 11.2, permanent 2246 registrations in this registry MUST include the following fields: 2248 Setting Name: A symbolic name for the setting. Specifying a setting 2249 name is optional. 2251 Default: The value of the setting unless otherwise indicated. A 2252 default SHOULD be the most restrictive possible value. 2254 The entries in Table 3 are registered by this document. 2256 +------------------------+-------+-----------------+-----------+ 2257 | Setting Name | Value | Specification | Default | 2258 +========================+=======+=================+===========+ 2259 | Reserved | 0x2 | N/A | N/A | 2260 +------------------------+-------+-----------------+-----------+ 2261 | Reserved | 0x3 | N/A | N/A | 2262 +------------------------+-------+-----------------+-----------+ 2263 | Reserved | 0x4 | N/A | N/A | 2264 +------------------------+-------+-----------------+-----------+ 2265 | Reserved | 0x5 | N/A | N/A | 2266 +------------------------+-------+-----------------+-----------+ 2267 | MAX_FIELD_SECTION_SIZE | 0x6 | Section 7.2.4.1 | Unlimited | 2268 +------------------------+-------+-----------------+-----------+ 2270 Table 3: Initial HTTP/3 Settings 2272 Additionally, each code of the format "0x1f * N + 0x21" for non- 2273 negative integer values of N (that is, 0x21, 0x40, ..., through 2274 0x3FFFFFFFFFFFFFFE) MUST NOT be assigned by IANA. 2276 11.2.3. Error Codes 2278 This document establishes a registry for HTTP/3 error codes. The 2279 "HTTP/3 Error Code" registry manages a 62-bit space. This registry 2280 follows the QUIC registry policy; see Section 11.2. Permanent 2281 registrations in this registry are assigned using the Specification 2282 Required policy [RFC8126], except for values between 0x00 and 0x3f 2283 (in hexadecimal; inclusive), which are assigned using Standards 2284 Action or IESG Approval as defined in Section 4.9 and 4.10 of 2285 [RFC8126]. 2287 Registrations for error codes are required to include a description 2288 of the error code. An expert reviewer is advised to examine new 2289 registrations for possible duplication with existing error codes. 2290 Use of existing registrations is to be encouraged, but not mandated. 2292 In addition to common fields as described in Section 11.2, permanent 2293 registrations in this registry MUST include the following fields: 2295 Name: A name for the error code. Specifying an error code name is 2296 optional. 2298 Description: A brief description of the error code semantics. 2300 The entries in the Table 4 are registered by this document. 2302 +---------------------------+--------+--------------+---------------+ 2303 | Name | Value | Description | Specification | 2304 +===========================+========+==============+===============+ 2305 | H3_NO_ERROR | 0x0100 | No error | Section 8.1 | 2306 +---------------------------+--------+--------------+---------------+ 2307 | H3_GENERAL_PROTOCOL_ERROR | 0x0101 | General | Section 8.1 | 2308 | | | protocol | | 2309 | | | error | | 2310 +---------------------------+--------+--------------+---------------+ 2311 | H3_INTERNAL_ERROR | 0x0102 | Internal | Section 8.1 | 2312 | | | error | | 2313 +---------------------------+--------+--------------+---------------+ 2314 | H3_STREAM_CREATION_ERROR | 0x0103 | Stream | Section 8.1 | 2315 | | | creation | | 2316 | | | error | | 2317 +---------------------------+--------+--------------+---------------+ 2318 | H3_CLOSED_CRITICAL_STREAM | 0x0104 | Critical | Section 8.1 | 2319 | | | stream was | | 2320 | | | closed | | 2321 +---------------------------+--------+--------------+---------------+ 2322 | H3_FRAME_UNEXPECTED | 0x0105 | Frame not | Section 8.1 | 2323 | | | permitted | | 2324 | | | in the | | 2325 | | | current | | 2326 | | | state | | 2327 +---------------------------+--------+--------------+---------------+ 2328 | H3_FRAME_ERROR | 0x0106 | Frame | Section 8.1 | 2329 | | | violated | | 2330 | | | layout or | | 2331 | | | size rules | | 2332 +---------------------------+--------+--------------+---------------+ 2333 | H3_EXCESSIVE_LOAD | 0x0107 | Peer | Section 8.1 | 2334 | | | generating | | 2335 | | | excessive | | 2336 | | | load | | 2337 +---------------------------+--------+--------------+---------------+ 2338 | H3_ID_ERROR | 0x0108 | An | Section 8.1 | 2339 | | | identifier | | 2340 | | | was used | | 2341 | | | incorrectly | | 2342 +---------------------------+--------+--------------+---------------+ 2343 | H3_SETTINGS_ERROR | 0x0109 | SETTINGS | Section 8.1 | 2344 | | | frame | | 2345 | | | contained | | 2346 | | | invalid | | 2347 | | | values | | 2348 +---------------------------+--------+--------------+---------------+ 2349 | H3_MISSING_SETTINGS | 0x010A | No SETTINGS | Section 8.1 | 2350 | | | frame | | 2351 | | | received | | 2352 +---------------------------+--------+--------------+---------------+ 2353 | H3_REQUEST_REJECTED | 0x010B | Request not | Section 8.1 | 2354 | | | processed | | 2355 +---------------------------+--------+--------------+---------------+ 2356 | H3_REQUEST_CANCELLED | 0x010C | Data no | Section 8.1 | 2357 | | | longer | | 2358 | | | needed | | 2359 +---------------------------+--------+--------------+---------------+ 2360 | H3_REQUEST_INCOMPLETE | 0x010D | Stream | Section 8.1 | 2361 | | | terminated | | 2362 | | | early | | 2363 +---------------------------+--------+--------------+---------------+ 2364 | H3_CONNECT_ERROR | 0x010F | TCP reset | Section 8.1 | 2365 | | | or error on | | 2366 | | | CONNECT | | 2367 | | | request | | 2368 +---------------------------+--------+--------------+---------------+ 2369 | H3_VERSION_FALLBACK | 0x0110 | Retry over | Section 8.1 | 2370 | | | HTTP/1.1 | | 2371 +---------------------------+--------+--------------+---------------+ 2373 Table 4: Initial HTTP/3 Error Codes 2375 Additionally, each code of the format "0x1f * N + 0x21" for non- 2376 negative integer values of N (that is, 0x21, 0x40, ..., through 2377 0x3FFFFFFFFFFFFFFE) MUST NOT be assigned by IANA. 2379 11.2.4. Stream Types 2381 This document establishes a registry for HTTP/3 unidirectional stream 2382 types. The "HTTP/3 Stream Type" registry governs a 62-bit space. 2383 This registry follows the QUIC registry policy; see Section 11.2. 2384 Permanent registrations in this registry are assigned using the 2385 Specification Required policy [RFC8126], except for values between 2386 0x00 and 0x3f (in hexadecimal; inclusive), which are assigned using 2387 Standards Action or IESG Approval as defined in Section 4.9 and 4.10 2388 of [RFC8126]. 2390 In addition to common fields as described in Section 11.2, permanent 2391 registrations in this registry MUST include the following fields: 2393 Stream Type: A name or label for the stream type. 2395 Sender: Which endpoint on a connection may initiate a stream of this 2396 type. Values are "Client", "Server", or "Both". 2398 Specifications for permanent registrations MUST include a description 2399 of the stream type, including the layout semantics of the stream 2400 contents. 2402 The entries in the following table are registered by this document. 2404 +----------------+-------+---------------+--------+ 2405 | Stream Type | Value | Specification | Sender | 2406 +================+=======+===============+========+ 2407 | Control Stream | 0x00 | Section 6.2.1 | Both | 2408 +----------------+-------+---------------+--------+ 2409 | Push Stream | 0x01 | Section 4.4 | Server | 2410 +----------------+-------+---------------+--------+ 2412 Table 5 2414 Additionally, each code of the format "0x1f * N + 0x21" for non- 2415 negative integer values of N (that is, 0x21, 0x40, ..., through 2416 0x3FFFFFFFFFFFFFFE) MUST NOT be assigned by IANA. 2418 12. References 2420 12.1. Normative References 2422 [ALTSVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP 2423 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 2424 April 2016, . 2426 [CACHING] Fielding, R., Nottingham, M., and J. Reschke, "HTTP 2427 Caching", Work in Progress, Internet-Draft, draft-ietf- 2428 httpbis-cache-07, 7 March 2020, . 2431 [HTTP-REPLAY] 2432 Thomson, M., Nottingham, M., and W. Tarreau, "Using Early 2433 Data in HTTP", RFC 8470, DOI 10.17487/RFC8470, September 2434 2018, . 2436 [QPACK] Krasic, C., Bishop, M., and A. Frindell, Ed., "QPACK: 2437 Header Compression for HTTP over QUIC", Work in Progress, 2438 Internet-Draft, draft-ietf-quic-qpack-15, 20 May 2020, 2439 . 2441 [QUIC-TRANSPORT] 2442 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 2443 Multiplexed and Secure Transport", Work in Progress, 2444 Internet-Draft, draft-ietf-quic-transport-28, 20 May 2020, 2445 . 2448 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 2449 RFC 793, DOI 10.17487/RFC0793, September 1981, 2450 . 2452 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2453 Requirement Levels", BCP 14, RFC 2119, 2454 DOI 10.17487/RFC2119, March 1997, 2455 . 2457 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2458 Resource Identifier (URI): Generic Syntax", STD 66, 2459 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2460 . 2462 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 2463 Specifications: ABNF", STD 68, RFC 5234, 2464 DOI 10.17487/RFC5234, January 2008, 2465 . 2467 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 2468 Extensions: Extension Definitions", RFC 6066, 2469 DOI 10.17487/RFC6066, January 2011, 2470 . 2472 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2473 Verification of Domain-Based Application Service Identity 2474 within Internet Public Key Infrastructure Using X.509 2475 (PKIX) Certificates in the Context of Transport Layer 2476 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2477 2011, . 2479 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 2480 DOI 10.17487/RFC6265, April 2011, 2481 . 2483 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2484 Writing an IANA Considerations Section in RFCs", BCP 26, 2485 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2486 . 2488 [RFC8164] Nottingham, M. and M. Thomson, "Opportunistic Security for 2489 HTTP/2", RFC 8164, DOI 10.17487/RFC8164, May 2017, 2490 . 2492 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2493 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2494 May 2017, . 2496 [SEMANTICS] 2497 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 2498 Semantics", Work in Progress, Internet-Draft, draft-ietf- 2499 httpbis-semantics-07, 7 March 2020, . 2502 12.2. Informative References 2504 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 2505 CRIME Attack", July 2013, 2506 . 2509 [HPACK] Peon, R. and H. Ruellan, "HPACK: Header Compression for 2510 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 2511 . 2513 [HTTP11] Fielding, R., Nottingham, M., and J. Reschke, "HTTP/1.1 2514 Messaging", Work in Progress, Internet-Draft, draft-ietf- 2515 httpbis-messaging-07, 7 March 2020, . 2518 [HTTP2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 2519 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 2520 DOI 10.17487/RFC7540, May 2015, 2521 . 2523 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 2524 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 2525 . 2527 [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, 2528 "Transport Layer Security (TLS) Application-Layer Protocol 2529 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 2530 July 2014, . 2532 [TFO] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 2533 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 2534 . 2536 [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2537 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2538 . 2540 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2541 Resource Identifier (URI): Generic Syntax", STD 66, 2542 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2543 . 2545 Appendix A. Considerations for Transitioning from HTTP/2 2547 HTTP/3 is strongly informed by HTTP/2, and bears many similarities. 2548 This section describes the approach taken to design HTTP/3, points 2549 out important differences from HTTP/2, and describes how to map 2550 HTTP/2 extensions into HTTP/3. 2552 HTTP/3 begins from the premise that similarity to HTTP/2 is 2553 preferable, but not a hard requirement. HTTP/3 departs from HTTP/2 2554 where QUIC differs from TCP, either to take advantage of QUIC 2555 features (like streams) or to accommodate important shortcomings 2556 (such as a lack of total ordering). These differences make HTTP/3 2557 similar to HTTP/2 in key aspects, such as the relationship of 2558 requests and responses to streams. However, the details of the 2559 HTTP/3 design are substantially different than HTTP/2. 2561 These departures are noted in this section. 2563 A.1. Streams 2565 HTTP/3 permits use of a larger number of streams (2^62-1) than 2566 HTTP/2. The considerations about exhaustion of stream identifier 2567 space apply, though the space is significantly larger such that it is 2568 likely that other limits in QUIC are reached first, such as the limit 2569 on the connection flow control window. 2571 In contrast to HTTP/2, stream concurrency in HTTP/3 is managed by 2572 QUIC. QUIC considers a stream closed when all data has been received 2573 and sent data has been acknowledged by the peer. HTTP/2 considers a 2574 stream closed when the frame containing the END_STREAM bit has been 2575 committed to the transport. As a result, the stream for an 2576 equivalent exchange could remain "active" for a longer period of 2577 time. HTTP/3 servers might choose to permit a larger number of 2578 concurrent client-initiated bidirectional streams to achieve 2579 equivalent concurrency to HTTP/2, depending on the expected usage 2580 patterns. 2582 Due to the presence of other unidirectional stream types, HTTP/3 does 2583 not rely exclusively on the number of concurrent unidirectional 2584 streams to control the number of concurrent in-flight pushes. 2585 Instead, HTTP/3 clients use the MAX_PUSH_ID frame to control the 2586 number of pushes received from an HTTP/3 server. 2588 A.2. HTTP Frame Types 2590 Many framing concepts from HTTP/2 can be elided on QUIC, because the 2591 transport deals with them. Because frames are already on a stream, 2592 they can omit the stream number. Because frames do not block 2593 multiplexing (QUIC's multiplexing occurs below this layer), the 2594 support for variable-maximum-length packets can be removed. Because 2595 stream termination is handled by QUIC, an END_STREAM flag is not 2596 required. This permits the removal of the Flags field from the 2597 generic frame layout. 2599 Frame payloads are largely drawn from [HTTP2]. However, QUIC 2600 includes many features (e.g., flow control) which are also present in 2601 HTTP/2. In these cases, the HTTP mapping does not re-implement them. 2602 As a result, several HTTP/2 frame types are not required in HTTP/3. 2603 Where an HTTP/2-defined frame is no longer used, the frame ID has 2604 been reserved in order to maximize portability between HTTP/2 and 2605 HTTP/3 implementations. However, even equivalent frames between the 2606 two mappings are not identical. 2608 Many of the differences arise from the fact that HTTP/2 provides an 2609 absolute ordering between frames across all streams, while QUIC 2610 provides this guarantee on each stream only. As a result, if a frame 2611 type makes assumptions that frames from different streams will still 2612 be received in the order sent, HTTP/3 will break them. 2614 Some examples of feature adaptations are described below, as well as 2615 general guidance to extension frame implementors converting an HTTP/2 2616 extension to HTTP/3. 2618 A.2.1. Prioritization Differences 2620 HTTP/2 specifies priority assignments in PRIORITY frames and 2621 (optionally) in HEADERS frames. HTTP/3 does not provide a means of 2622 signaling priority. 2624 Note that while there is no explicit signaling for priority, this 2625 does not mean that prioritization is not important for achieving good 2626 performance. 2628 A.2.2. Field Compression Differences 2630 HPACK was designed with the assumption of in-order delivery. A 2631 sequence of encoded field sections must arrive (and be decoded) at an 2632 endpoint in the same order in which they were encoded. This ensures 2633 that the dynamic state at the two endpoints remains in sync. 2635 Because this total ordering is not provided by QUIC, HTTP/3 uses a 2636 modified version of HPACK, called QPACK. QPACK uses a single 2637 unidirectional stream to make all modifications to the dynamic table, 2638 ensuring a total order of updates. All frames which contain encoded 2639 fields merely reference the table state at a given time without 2640 modifying it. 2642 [QPACK] provides additional details. 2644 A.2.3. Guidance for New Frame Type Definitions 2646 Frame type definitions in HTTP/3 often use the QUIC variable-length 2647 integer encoding. In particular, Stream IDs use this encoding, which 2648 allows for a larger range of possible values than the encoding used 2649 in HTTP/2. Some frames in HTTP/3 use an identifier rather than a 2650 Stream ID (e.g., Push IDs). Redefinition of the encoding of 2651 extension frame types might be necessary if the encoding includes a 2652 Stream ID. 2654 Because the Flags field is not present in generic HTTP/3 frames, 2655 those frames which depend on the presence of flags need to allocate 2656 space for flags as part of their frame payload. 2658 Other than this issue, frame type HTTP/2 extensions are typically 2659 portable to QUIC simply by replacing Stream 0 in HTTP/2 with a 2660 control stream in HTTP/3. HTTP/3 extensions will not assume 2661 ordering, but would not be harmed by ordering, and would be portable 2662 to HTTP/2 in the same manner. 2664 A.2.4. Mapping Between HTTP/2 and HTTP/3 Frame Types 2666 DATA (0x0): Padding is not defined in HTTP/3 frames. See 2667 Section 7.2.1. 2669 HEADERS (0x1): The PRIORITY region of HEADERS is not defined in 2670 HTTP/3 frames. Padding is not defined in HTTP/3 frames. See 2671 Section 7.2.2. 2673 PRIORITY (0x2): As described in Appendix A.2.1, HTTP/3 does not 2674 provide a means of signaling priority. 2676 RST_STREAM (0x3): RST_STREAM frames do not exist, since QUIC 2677 provides stream lifecycle management. The same code point is used 2678 for the CANCEL_PUSH frame (Section 7.2.3). 2680 SETTINGS (0x4): SETTINGS frames are sent only at the beginning of 2681 the connection. See Section 7.2.4 and Appendix A.3. 2683 PUSH_PROMISE (0x5): The PUSH_PROMISE does not reference a stream; 2684 instead the push stream references the PUSH_PROMISE frame using a 2685 Push ID. See Section 7.2.5. 2687 PING (0x6): PING frames do not exist, since QUIC provides equivalent 2688 functionality. 2690 GOAWAY (0x7): GOAWAY does not contain an error code. In the client 2691 to server direction, it carries a Push ID instead of a server 2692 initiated stream ID. See Section 7.2.6. 2694 WINDOW_UPDATE (0x8): WINDOW_UPDATE frames do not exist, since QUIC 2695 provides flow control. 2697 CONTINUATION (0x9): CONTINUATION frames do not exist; instead, 2698 larger HEADERS/PUSH_PROMISE frames than HTTP/2 are permitted. 2700 Frame types defined by extensions to HTTP/2 need to be separately 2701 registered for HTTP/3 if still applicable. The IDs of frames defined 2702 in [HTTP2] have been reserved for simplicity. Note that the frame 2703 type space in HTTP/3 is substantially larger (62 bits versus 8 bits), 2704 so many HTTP/3 frame types have no equivalent HTTP/2 code points. 2705 See Section 11.2.1. 2707 A.3. HTTP/2 SETTINGS Parameters 2709 An important difference from HTTP/2 is that settings are sent once, 2710 as the first frame of the control stream, and thereafter cannot 2711 change. This eliminates many corner cases around synchronization of 2712 changes. 2714 Some transport-level options that HTTP/2 specifies via the SETTINGS 2715 frame are superseded by QUIC transport parameters in HTTP/3. The 2716 HTTP-level options that are retained in HTTP/3 have the same value as 2717 in HTTP/2. 2719 Below is a listing of how each HTTP/2 SETTINGS parameter is mapped: 2721 SETTINGS_HEADER_TABLE_SIZE: See [QPACK]. 2723 SETTINGS_ENABLE_PUSH: This is removed in favor of the MAX_PUSH_ID 2724 which provides a more granular control over server push. 2726 SETTINGS_MAX_CONCURRENT_STREAMS: QUIC controls the largest open 2727 Stream ID as part of its flow control logic. Specifying 2728 SETTINGS_MAX_CONCURRENT_STREAMS in the SETTINGS frame is an error. 2730 SETTINGS_INITIAL_WINDOW_SIZE: QUIC requires both stream and 2731 connection flow control window sizes to be specified in the 2732 initial transport handshake. Specifying 2733 SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS frame is an error. 2735 SETTINGS_MAX_FRAME_SIZE: This setting has no equivalent in HTTP/3. 2736 Specifying it in the SETTINGS frame is an error. 2738 SETTINGS_MAX_FIELD_SECTION_SIZE: See Section 7.2.4.1. 2740 In HTTP/3, setting values are variable-length integers (6, 14, 30, or 2741 62 bits long) rather than fixed-length 32-bit fields as in HTTP/2. 2742 This will often produce a shorter encoding, but can produce a longer 2743 encoding for settings which use the full 32-bit space. Settings 2744 ported from HTTP/2 might choose to redefine their value to limit it 2745 to 30 bits for more efficient encoding, or to make use of the 62-bit 2746 space if more than 30 bits are required. 2748 Settings need to be defined separately for HTTP/2 and HTTP/3. The 2749 IDs of settings defined in [HTTP2] have been reserved for simplicity. 2750 Note that the settings identifier space in HTTP/3 is substantially 2751 larger (62 bits versus 16 bits), so many HTTP/3 settings have no 2752 equivalent HTTP/2 code point. See Section 11.2.2. 2754 As QUIC streams might arrive out-of-order, endpoints are advised to 2755 not wait for the peers' settings to arrive before responding to other 2756 streams. See Section 7.2.4.2. 2758 A.4. HTTP/2 Error Codes 2760 QUIC has the same concepts of "stream" and "connection" errors that 2761 HTTP/2 provides. However, the differences between HTTP/2 and HTTP/3 2762 mean that error codes are not directly portable between versions. 2764 The HTTP/2 error codes defined in Section 7 of [HTTP2] logically map 2765 to the HTTP/3 error codes as follows: 2767 NO_ERROR (0x0): H3_NO_ERROR in Section 8.1. 2769 PROTOCOL_ERROR (0x1): This is mapped to H3_GENERAL_PROTOCOL_ERROR 2770 except in cases where more specific error codes have been defined. 2771 This includes H3_FRAME_UNEXPECTED and H3_CLOSED_CRITICAL_STREAM 2772 defined in Section 8.1. 2774 INTERNAL_ERROR (0x2): H3_INTERNAL_ERROR in Section 8.1. 2776 FLOW_CONTROL_ERROR (0x3): Not applicable, since QUIC handles flow 2777 control. 2779 SETTINGS_TIMEOUT (0x4): Not applicable, since no acknowledgement of 2780 SETTINGS is defined. 2782 STREAM_CLOSED (0x5): Not applicable, since QUIC handles stream 2783 management. 2785 FRAME_SIZE_ERROR (0x6): H3_FRAME_ERROR error code defined in 2786 Section 8.1. 2788 REFUSED_STREAM (0x7): H3_REQUEST_REJECTED (in Section 8.1) is used 2789 to indicate that a request was not processed. Otherwise, not 2790 applicable because QUIC handles stream management. 2792 CANCEL (0x8): H3_REQUEST_CANCELLED in Section 8.1. 2794 COMPRESSION_ERROR (0x9): Multiple error codes are defined in 2795 [QPACK]. 2797 CONNECT_ERROR (0xa): H3_CONNECT_ERROR in Section 8.1. 2799 ENHANCE_YOUR_CALM (0xb): H3_EXCESSIVE_LOAD in Section 8.1. 2801 INADEQUATE_SECURITY (0xc): Not applicable, since QUIC is assumed to 2802 provide sufficient security on all connections. 2804 H3_1_1_REQUIRED (0xd): H3_VERSION_FALLBACK in Section 8.1. 2806 Error codes need to be defined for HTTP/2 and HTTP/3 separately. See 2807 Section 11.2.3. 2809 A.4.1. Mapping Between HTTP/2 and HTTP/3 Errors 2811 An intermediary that converts between HTTP/2 and HTTP/3 may encounter 2812 error conditions from either upstream. It is useful to communicate 2813 the occurrence of error to the downstream but error codes largely 2814 reflect connection-local problems that generally do not make sense to 2815 propagate. 2817 An intermediary that encounters an error from an upstream origin can 2818 indicate this by sending an HTTP status code such as 502, which is 2819 suitable for a broad class of errors. 2821 There are some rare cases where it is beneficial to propagate the 2822 error by mapping it to the closest matching error type to the 2823 receiver. For example, an intermediary that receives an HTTP/2 2824 stream error of type REFUSED_STREAM from the origin has a clear 2825 signal that the request was not processed and that the request is 2826 safe to retry. Propagating this error condition to the client as an 2827 HTTP/3 stream error of type H3_REQUEST_REJECTED allows the client to 2828 take the action it deems most appropriate. In the reverse direction 2829 the intermediary might deem it beneficial to pass on client request 2830 cancellations that are indicated by terminating a stream with 2831 H3_REQUEST_CANCELLED. 2833 Conversion between errors is described in the logical mapping. The 2834 error codes are defined in non-overlapping spaces in order to protect 2835 against accidental conversion that could result in the use of 2836 inappropriate or unknown error codes for the target version. An 2837 intermediary is permitted to promote stream errors to connection 2838 errors but they should be aware of the cost to the connection for 2839 what might be a temporary or intermittent error. 2841 Appendix B. Change Log 2843 *RFC Editor's Note:* Please remove this section prior to 2844 publication of a final version of this document. 2846 B.1. Since draft-ietf-quic-http-27 2848 * Updated text to refer to latest HTTP revisions 2850 * Use the HTTP definition of authority for establishing and 2851 coalescing connections (#253, #2223, #3558) 2853 * Define use of GOAWAY from both endpoints (#2632, #3129) 2855 * Require either :authority or Host if the URI scheme has a 2856 mandatory authority component (#3408, #3475) 2858 B.2. Since draft-ietf-quic-http-26 2860 * No changes 2862 B.3. Since draft-ietf-quic-http-25 2864 * Require QUICv1 for HTTP/3 (#3117, #3323) 2866 * Remove DUPLICATE_PUSH and allow duplicate PUSH_PROMISE (#3275, 2867 #3309) 2869 * Clarify the definition of "malformed" (#3352, #3345) 2871 B.4. Since draft-ietf-quic-http-24 2873 * Removed H3_EARLY_RESPONSE error code; H3_NO_ERROR is recommended 2874 instead (#3130,#3208) 2876 * Unknown error codes are equivalent to H3_NO_ERROR (#3276,#3331) 2878 * Some error codes are reserved for greasing (#3325,#3360) 2880 B.5. Since draft-ietf-quic-http-23 2882 * Removed "quic" Alt-Svc parameter (#3061,#3118) 2884 * Clients need not persist unknown settings for use in 0-RTT 2885 (#3110,#3113) 2887 * Clarify error cases around CANCEL_PUSH (#2819,#3083) 2889 B.6. Since draft-ietf-quic-http-22 2891 * Removed priority signaling (#2922,#2924) 2893 * Further changes to error codes (#2662,#2551): 2895 - Error codes renumbered 2897 - HTTP_MALFORMED_FRAME replaced by HTTP_FRAME_ERROR, 2898 HTTP_ID_ERROR, and others 2900 * Clarify how unknown frame types interact with required frame 2901 sequence (#2867,#2858) 2903 * Describe interactions with the transport in terms of defined 2904 interface terms (#2857,#2805) 2906 * Require the use of the "http-opportunistic" resource (RFC 8164) 2907 when scheme is "http" (#2439,#2973) 2909 * Settings identifiers cannot be duplicated (#2979) 2911 * Changes to SETTINGS frames in 0-RTT (#2972,#2790,#2945): 2913 - Servers must send all settings with non-default values in their 2914 SETTINGS frame, even when resuming 2916 - If a client doesn't have settings associated with a 0-RTT 2917 ticket, it uses the defaults 2919 - Servers can't accept early data if they cannot recover the 2920 settings the client will have remembered 2922 * Clarify that Upgrade and the 101 status code are prohibited 2923 (#2898,#2889) 2925 * Clarify that frame types reserved for greasing can occur on any 2926 stream, but frame types reserved due to HTTP/2 correspondence are 2927 prohibited (#2997,#2692,#2693) 2929 * Unknown error codes cannot be treated as errors (#2998,#2816) 2931 B.7. Since draft-ietf-quic-http-21 2933 No changes 2935 B.8. Since draft-ietf-quic-http-20 2937 * Prohibit closing the control stream (#2509, #2666) 2939 * Change default priority to use an orphan node (#2502, #2690) 2941 * Exclusive priorities are restored (#2754, #2781) 2942 * Restrict use of frames when using CONNECT (#2229, #2702) 2944 * Close and maybe reset streams if a connection error occurs for 2945 CONNECT (#2228, #2703) 2947 * Encourage provision of sufficient unidirectional streams for QPACK 2948 (#2100, #2529, #2762) 2950 * Allow extensions to use server-initiated bidirectional streams 2951 (#2711, #2773) 2953 * Clarify use of maximum header list size setting (#2516, #2774) 2955 * Extensive changes to error codes and conditions of their sending 2957 - Require connection errors for more error conditions (#2511, 2958 #2510) 2960 - Updated the error codes for illegal GOAWAY frames (#2714, 2961 #2707) 2963 - Specified error code for HEADERS on control stream (#2708) 2965 - Specified error code for servers receiving PUSH_PROMISE (#2709) 2967 - Specified error code for receiving DATA before HEADERS (#2715) 2969 - Describe malformed messages and their handling (#2410, #2764) 2971 - Remove HTTP_PUSH_ALREADY_IN_CACHE error (#2812, #2813) 2973 - Refactor Push ID related errors (#2818, #2820) 2975 - Rationalize HTTP/3 stream creation errors (#2821, #2822) 2977 B.9. Since draft-ietf-quic-http-19 2979 * SETTINGS_NUM_PLACEHOLDERS is 0x9 (#2443,#2530) 2981 * Non-zero bits in the Empty field of the PRIORITY frame MAY be 2982 treated as an error (#2501) 2984 B.10. Since draft-ietf-quic-http-18 2986 * Resetting streams following a GOAWAY is recommended, but not 2987 required (#2256,#2457) 2989 * Use variable-length integers throughout (#2437,#2233,#2253,#2275) 2990 - Variable-length frame types, stream types, and settings 2991 identifiers 2993 - Renumbered stream type assignments 2995 - Modified associated reserved values 2997 * Frame layout switched from Length-Type-Value to Type-Length-Value 2998 (#2395,#2235) 3000 * Specified error code for servers receiving DUPLICATE_PUSH (#2497) 3002 * Use connection error for invalid PRIORITY (#2507, #2508) 3004 B.11. Since draft-ietf-quic-http-17 3006 * HTTP_REQUEST_REJECTED is used to indicate a request can be retried 3007 (#2106, #2325) 3009 * Changed error code for GOAWAY on the wrong stream (#2231, #2343) 3011 B.12. Since draft-ietf-quic-http-16 3013 * Rename "HTTP/QUIC" to "HTTP/3" (#1973) 3015 * Changes to PRIORITY frame (#1865, #2075) 3017 - Permitted as first frame of request streams 3019 - Remove exclusive reprioritization 3021 - Changes to Prioritized Element Type bits 3023 * Define DUPLICATE_PUSH frame to refer to another PUSH_PROMISE 3024 (#2072) 3026 * Set defaults for settings, allow request before receiving SETTINGS 3027 (#1809, #1846, #2038) 3029 * Clarify message processing rules for streams that aren't closed 3030 (#1972, #2003) 3032 * Removed reservation of error code 0 and moved HTTP_NO_ERROR to 3033 this value (#1922) 3035 * Removed prohibition of zero-length DATA frames (#2098) 3037 B.13. Since draft-ietf-quic-http-15 3039 Substantial editorial reorganization; no technical changes. 3041 B.14. Since draft-ietf-quic-http-14 3043 * Recommend sensible values for QUIC transport parameters 3044 (#1720,#1806) 3046 * Define error for missing SETTINGS frame (#1697,#1808) 3048 * Setting values are variable-length integers (#1556,#1807) and do 3049 not have separate maximum values (#1820) 3051 * Expanded discussion of connection closure (#1599,#1717,#1712) 3053 * HTTP_VERSION_FALLBACK falls back to HTTP/1.1 (#1677,#1685) 3055 B.15. Since draft-ietf-quic-http-13 3057 * Reserved some frame types for grease (#1333, #1446) 3059 * Unknown unidirectional stream types are tolerated, not errors; 3060 some reserved for grease (#1490, #1525) 3062 * Require settings to be remembered for 0-RTT, prohibit reductions 3063 (#1541, #1641) 3065 * Specify behavior for truncated requests (#1596, #1643) 3067 B.16. Since draft-ietf-quic-http-12 3069 * TLS SNI extension isn't mandatory if an alternative method is used 3070 (#1459, #1462, #1466) 3072 * Removed flags from HTTP/3 frames (#1388, #1398) 3074 * Reserved frame types and settings for use in preserving 3075 extensibility (#1333, #1446) 3077 * Added general error code (#1391, #1397) 3079 * Unidirectional streams carry a type byte and are extensible 3080 (#910,#1359) 3082 * Priority mechanism now uses explicit placeholders to enable 3083 persistent structure in the tree (#441,#1421,#1422) 3085 B.17. Since draft-ietf-quic-http-11 3087 * Moved QPACK table updates and acknowledgments to dedicated streams 3088 (#1121, #1122, #1238) 3090 B.18. Since draft-ietf-quic-http-10 3092 * Settings need to be remembered when attempting and accepting 0-RTT 3093 (#1157, #1207) 3095 B.19. Since draft-ietf-quic-http-09 3097 * Selected QCRAM for header compression (#228, #1117) 3099 * The server_name TLS extension is now mandatory (#296, #495) 3101 * Specified handling of unsupported versions in Alt-Svc (#1093, 3102 #1097) 3104 B.20. Since draft-ietf-quic-http-08 3106 * Clarified connection coalescing rules (#940, #1024) 3108 B.21. Since draft-ietf-quic-http-07 3110 * Changes for integer encodings in QUIC (#595,#905) 3112 * Use unidirectional streams as appropriate (#515, #240, #281, #886) 3114 * Improvement to the description of GOAWAY (#604, #898) 3116 * Improve description of server push usage (#947, #950, #957) 3118 B.22. Since draft-ietf-quic-http-06 3120 * Track changes in QUIC error code usage (#485) 3122 B.23. Since draft-ietf-quic-http-05 3124 * Made push ID sequential, add MAX_PUSH_ID, remove 3125 SETTINGS_ENABLE_PUSH (#709) 3127 * Guidance about keep-alive and QUIC PINGs (#729) 3129 * Expanded text on GOAWAY and cancellation (#757) 3131 B.24. Since draft-ietf-quic-http-04 3132 * Cite RFC 5234 (#404) 3134 * Return to a single stream per request (#245,#557) 3136 * Use separate frame type and settings registries from HTTP/2 (#81) 3138 * SETTINGS_ENABLE_PUSH instead of SETTINGS_DISABLE_PUSH (#477) 3140 * Restored GOAWAY (#696) 3142 * Identify server push using Push ID rather than a stream ID 3143 (#702,#281) 3145 * DATA frames cannot be empty (#700) 3147 B.25. Since draft-ietf-quic-http-03 3149 None. 3151 B.26. Since draft-ietf-quic-http-02 3153 * Track changes in transport draft 3155 B.27. Since draft-ietf-quic-http-01 3157 * SETTINGS changes (#181): 3159 - SETTINGS can be sent only once at the start of a connection; no 3160 changes thereafter 3162 - SETTINGS_ACK removed 3164 - Settings can only occur in the SETTINGS frame a single time 3166 - Boolean format updated 3168 * Alt-Svc parameter changed from "v" to "quic"; format updated 3169 (#229) 3171 * Closing the connection control stream or any message control 3172 stream is a fatal error (#176) 3174 * HPACK Sequence counter can wrap (#173) 3176 * 0-RTT guidance added 3178 * Guide to differences from HTTP/2 and porting HTTP/2 extensions 3179 added (#127,#242) 3181 B.28. Since draft-ietf-quic-http-00 3183 * Changed "HTTP/2-over-QUIC" to "HTTP/QUIC" throughout (#11,#29) 3185 * Changed from using HTTP/2 framing within Stream 3 to new framing 3186 format and two-stream-per-request model (#71,#72,#73) 3188 * Adopted SETTINGS format from draft-bishop-httpbis-extended- 3189 settings-01 3191 * Reworked SETTINGS_ACK to account for indeterminate inter-stream 3192 order (#75) 3194 * Described CONNECT pseudo-method (#95) 3196 * Updated ALPN token and Alt-Svc guidance (#13,#87) 3198 * Application-layer-defined error codes (#19,#74) 3200 B.29. Since draft-shade-quic-http2-mapping-00 3202 * Adopted as base for draft-ietf-quic-http 3204 * Updated authors/editors list 3206 Acknowledgements 3208 The original authors of this specification were Robbie Shade and Mike 3209 Warres. 3211 The IETF QUIC Working Group received an enormous amount of support 3212 from many people. Among others, the following people provided 3213 substantial contributions to this document: 3215 * Bence Beky 3217 * Daan De Meyer 3219 * Martin Duke 3221 * Roy Fielding 3223 * Alan Frindell 3225 * Alessandro Ghedini 3227 * Nick Harper 3228 * Ryan Hamilton 3230 * Christian Huitema 3232 * Subodh Iyengar 3234 * Robin Marx 3236 * Patrick McManus 3238 * Luca Nicco 3240 * 奥 一穂 (Kazuho Oku) 3242 * Lucas Pardue 3244 * Roberto Peon 3246 * Julian Reschke 3248 * Eric Rescorla 3250 * Martin Seemann 3252 * Ben Schwartz 3254 * Ian Swett 3256 * Willy Taureau 3258 * Martin Thomson 3260 * Dmitri Tikhonov 3262 * Tatsuhiro Tsujikawa 3264 A portion of Mike's contribution was supported by Microsoft during 3265 his employment there. 3267 Author's Address 3269 Mike Bishop (editor) 3270 Akamai 3272 Email: mbishop@evequefou.be