idnits 2.17.1 draft-ietf-httpbis-http2bis-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC8740, but the abstract doesn't seem to directly say this. It does mention RFC8740 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (18 November 2021) is 862 days in the past. Is this intentional? 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-18 -- Possible downref: Normative reference to a draft: ref. 'CACHE' -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS186' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-18 -- Possible downref: Normative reference to a draft: ref. 'HTTP' ** Obsolete normative reference: RFC 793 (ref. 'TCP') (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 5246 (ref. 'TLS12') (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7525 (ref. 'TLSBCP') (Obsoleted by RFC 9325) -- Obsolete informational reference (is this intentional?): RFC 8499 (ref. 'DNS-TERMS') (Obsoleted by RFC 9499) == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-18 == Outdated reference: A later version (-12) exists of draft-ietf-httpbis-priority-10 -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 8740 (Obsoleted by RFC 9113) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis M. Thomson, Ed. 3 Internet-Draft Mozilla 4 Obsoletes: 7540, 8740 (if approved) C. Benfield, Ed. 5 Intended status: Standards Track Apple Inc. 6 Expires: 22 May 2022 18 November 2021 8 Hypertext Transfer Protocol Version 2 (HTTP/2) 9 draft-ietf-httpbis-http2bis-06 11 Abstract 13 This specification describes an optimized expression of the semantics 14 of the Hypertext Transfer Protocol (HTTP), referred to as HTTP 15 version 2 (HTTP/2). HTTP/2 enables a more efficient use of network 16 resources and a reduced latency by introducing field compression and 17 allowing multiple concurrent exchanges on the same connection. 19 This document obsoletes RFC 7540 and RFC 8740. 21 Discussion Venues 23 This note is to be removed before publishing as an RFC. 25 Discussion of this document takes place on the HTTPBIS Working Group 26 mailing list (ietf-http-wg@w3.org), which is archived at 27 https://lists.w3.org/Archives/Public/ietf-http-wg/. 29 Source for this draft and an issue tracker can be found at 30 https://github.com/httpwg/http2-spec. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on 22 May 2022. 49 Copyright Notice 51 Copyright (c) 2021 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 56 license-info) in effect on the date of publication of this document. 57 Please review these documents carefully, as they describe your rights 58 and restrictions with respect to this document. Code Components 59 extracted from this document must include Revised BSD License text as 60 described in Section 4.e of the Trust Legal Provisions and are 61 provided without warranty as described in the Revised BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 66 2. HTTP/2 Protocol Overview . . . . . . . . . . . . . . . . . . 5 67 2.1. Document Organization . . . . . . . . . . . . . . . . . . 6 68 2.2. Conventions and Terminology . . . . . . . . . . . . . . . 6 69 3. Starting HTTP/2 . . . . . . . . . . . . . . . . . . . . . . . 7 70 3.1. HTTP/2 Version Identification . . . . . . . . . . . . . . 8 71 3.2. Starting HTTP/2 for "https" URIs . . . . . . . . . . . . 8 72 3.3. Starting HTTP/2 with Prior Knowledge . . . . . . . . . . 9 73 3.4. HTTP/2 Connection Preface . . . . . . . . . . . . . . . . 9 74 4. HTTP Frames . . . . . . . . . . . . . . . . . . . . . . . . . 10 75 4.1. Frame Format . . . . . . . . . . . . . . . . . . . . . . 10 76 4.2. Frame Size . . . . . . . . . . . . . . . . . . . . . . . 11 77 4.3. Field Section Compression and Decompression . . . . . . . 12 78 5. Streams and Multiplexing . . . . . . . . . . . . . . . . . . 13 79 5.1. Stream States . . . . . . . . . . . . . . . . . . . . . . 14 80 5.1.1. Stream Identifiers . . . . . . . . . . . . . . . . . 19 81 5.1.2. Stream Concurrency . . . . . . . . . . . . . . . . . 20 82 5.2. Flow Control . . . . . . . . . . . . . . . . . . . . . . 20 83 5.2.1. Flow-Control Principles . . . . . . . . . . . . . . . 20 84 5.2.2. Appropriate Use of Flow Control . . . . . . . . . . . 22 85 5.2.3. Flow Control Performance . . . . . . . . . . . . . . 22 86 5.3. Prioritization . . . . . . . . . . . . . . . . . . . . . 23 87 5.3.1. Background of Priority in HTTP/2 . . . . . . . . . . 23 88 5.3.2. Priority Signaling in this Document . . . . . . . . . 23 89 5.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 24 90 5.4.1. Connection Error Handling . . . . . . . . . . . . . . 25 91 5.4.2. Stream Error Handling . . . . . . . . . . . . . . . . 25 92 5.4.3. Connection Termination . . . . . . . . . . . . . . . 26 93 5.5. Extending HTTP/2 . . . . . . . . . . . . . . . . . . . . 26 94 6. Frame Definitions . . . . . . . . . . . . . . . . . . . . . . 27 95 6.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . 27 96 6.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . . . 29 97 6.3. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . 31 98 6.4. RST_STREAM . . . . . . . . . . . . . . . . . . . . . . . 32 99 6.5. SETTINGS . . . . . . . . . . . . . . . . . . . . . . . . 33 100 6.5.1. SETTINGS Format . . . . . . . . . . . . . . . . . . . 34 101 6.5.2. Defined Settings . . . . . . . . . . . . . . . . . . 35 102 6.5.3. Settings Synchronization . . . . . . . . . . . . . . 36 103 6.6. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . . . 37 104 6.7. PING . . . . . . . . . . . . . . . . . . . . . . . . . . 39 105 6.8. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . . . 40 106 6.9. WINDOW_UPDATE . . . . . . . . . . . . . . . . . . . . . . 43 107 6.9.1. The Flow-Control Window . . . . . . . . . . . . . . . 45 108 6.9.2. Initial Flow-Control Window Size . . . . . . . . . . 46 109 6.9.3. Reducing the Stream Window Size . . . . . . . . . . . 47 110 6.10. CONTINUATION . . . . . . . . . . . . . . . . . . . . . . 47 111 7. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 48 112 8. Expressing HTTP Semantics in HTTP/2 . . . . . . . . . . . . . 50 113 8.1. HTTP Message Framing . . . . . . . . . . . . . . . . . . 50 114 8.1.1. Malformed Messages . . . . . . . . . . . . . . . . . 51 115 8.2. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . . 52 116 8.2.1. Field Validity . . . . . . . . . . . . . . . . . . . 52 117 8.2.2. Connection-Specific Header Fields . . . . . . . . . . 54 118 8.2.3. Compressing the Cookie Header Field . . . . . . . . . 54 119 8.3. HTTP Control Data . . . . . . . . . . . . . . . . . . . . 55 120 8.3.1. Request Pseudo-Header Fields . . . . . . . . . . . . 55 121 8.3.2. Response Pseudo-Header Fields . . . . . . . . . . . . 57 122 8.4. Server Push . . . . . . . . . . . . . . . . . . . . . . . 57 123 8.4.1. Push Requests . . . . . . . . . . . . . . . . . . . . 59 124 8.4.2. Push Responses . . . . . . . . . . . . . . . . . . . 60 125 8.5. The CONNECT Method . . . . . . . . . . . . . . . . . . . 61 126 8.6. The Upgrade Header Field . . . . . . . . . . . . . . . . 62 127 8.7. Request Reliability . . . . . . . . . . . . . . . . . . . 62 128 8.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . 63 129 8.8.1. Simple Request . . . . . . . . . . . . . . . . . . . 63 130 8.8.2. Simple Response . . . . . . . . . . . . . . . . . . . 64 131 8.8.3. Complex Request . . . . . . . . . . . . . . . . . . . 64 132 8.8.4. Response with Body . . . . . . . . . . . . . . . . . 65 133 8.8.5. Informational Responses . . . . . . . . . . . . . . . 65 134 9. HTTP/2 Connections . . . . . . . . . . . . . . . . . . . . . 66 135 9.1. Connection Management . . . . . . . . . . . . . . . . . . 66 136 9.1.1. Connection Reuse . . . . . . . . . . . . . . . . . . 67 137 9.2. Use of TLS Features . . . . . . . . . . . . . . . . . . . 68 138 9.2.1. TLS 1.2 Features . . . . . . . . . . . . . . . . . . 68 139 9.2.2. TLS 1.2 Cipher Suites . . . . . . . . . . . . . . . . 69 140 9.2.3. TLS 1.3 Features . . . . . . . . . . . . . . . . . . 70 141 10. Security Considerations . . . . . . . . . . . . . . . . . . . 70 142 10.1. Server Authority . . . . . . . . . . . . . . . . . . . . 70 143 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 71 144 10.3. Intermediary Encapsulation Attacks . . . . . . . . . . . 71 145 10.4. Cacheability of Pushed Responses . . . . . . . . . . . . 72 146 10.5. Denial-of-Service Considerations . . . . . . . . . . . . 72 147 10.5.1. Limits on Field Block Size . . . . . . . . . . . . . 74 148 10.5.2. CONNECT Issues . . . . . . . . . . . . . . . . . . . 74 149 10.6. Use of Compression . . . . . . . . . . . . . . . . . . . 74 150 10.7. Use of Padding . . . . . . . . . . . . . . . . . . . . . 75 151 10.8. Privacy Considerations . . . . . . . . . . . . . . . . . 76 152 10.9. Remote Timing Attacks . . . . . . . . . . . . . . . . . 76 153 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 76 154 11.1. HTTP2-Settings Header Field Registration . . . . . . . . 77 155 11.2. The h2c Upgrade Token . . . . . . . . . . . . . . . . . 77 156 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 157 12.1. Normative References . . . . . . . . . . . . . . . . . . 77 158 12.2. Informative References . . . . . . . . . . . . . . . . . 79 159 Appendix A. Prohibited TLS 1.2 Cipher Suites . . . . . . . . . . 81 160 Appendix B. Changes from RFC 7540 . . . . . . . . . . . . . . . 87 161 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 87 162 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 88 163 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 88 165 1. Introduction 167 The performance of applications using the Hypertext Transfer Protocol 168 (HTTP, [HTTP]) is linked to how each version of HTTP uses the 169 underlying transport, and the conditions under which the transport 170 operates. 172 Making multiple concurrent requests can reduce latency and improve 173 application performance. HTTP/1.0 allowed only one request to be 174 outstanding at a time on a given TCP [TCP] connection. HTTP/1.1 175 ([HTTP11]) added request pipelining, but this only partially 176 addressed request concurrency and still suffers from application- 177 layer head-of-line blocking. Therefore, HTTP/1.0 and HTTP/1.1 178 clients use multiple connections to a server to make concurrent 179 requests. 181 Furthermore, HTTP fields are often repetitive and verbose, causing 182 unnecessary network traffic as well as causing the initial TCP 183 congestion window to quickly fill. This can result in excessive 184 latency when multiple requests are made on a new TCP connection. 186 HTTP/2 addresses these issues by defining an optimized mapping of 187 HTTP's semantics to an underlying connection. Specifically, it 188 allows interleaving of messages on the same connection and uses an 189 efficient coding for HTTP fields. It also allows prioritization of 190 requests, letting more important requests complete more quickly, 191 further improving performance. 193 The resulting protocol is more friendly to the network because fewer 194 TCP connections can be used in comparison to HTTP/1.x. This means 195 less competition with other flows and longer-lived connections, which 196 in turn lead to better utilization of available network capacity. 197 Note, however, that TCP head-of-line blocking is not addressed by 198 this protocol. 200 Finally, HTTP/2 also enables more efficient processing of messages 201 through use of binary message framing. 203 This document obsoletes RFC 7540 [RFC7540] and RFC 8740 [RFC8740]. 205 2. HTTP/2 Protocol Overview 207 HTTP/2 provides an optimized transport for HTTP semantics. HTTP/2 208 supports all of the core features of HTTP but aims to be more 209 efficient than HTTP/1.1. 211 The basic protocol unit in HTTP/2 is a frame (Section 4.1). Each 212 frame type serves a different purpose. For example, HEADERS and DATA 213 frames form the basis of HTTP requests and responses (Section 8.1); 214 other frame types like SETTINGS, WINDOW_UPDATE, and PUSH_PROMISE are 215 used in support of other HTTP/2 features. 217 Multiplexing of requests is achieved by having each HTTP request/ 218 response exchange associated with its own stream (Section 5). 219 Streams are largely independent of each other, so a blocked or 220 stalled request or response does not prevent progress on other 221 streams. 223 Effective use of multiplexing depends on flow control and 224 prioritization. Flow control (Section 5.2) ensures that it is 225 possible to efficiently use multiplexed streams by restricting data 226 that is transmitted to what the receiver is able to handle. 227 Prioritization (Section 5.3) ensures that limited resources are used 228 most effectively. This revision of HTTP/2 deprecates the priority 229 signaling scheme from [RFC7540]. 231 Because HTTP fields used in a connection can contain large amounts of 232 redundant data, frames that contain them are compressed 233 (Section 4.3). This has especially advantageous impact upon request 234 sizes in the common case, allowing many requests to be compressed 235 into one packet. 237 Finally, HTTP/2 adds a new, optional interaction mode whereby a 238 server can push responses to a client (Section 8.4). This is 239 intended to allow a server to speculatively send data to a client 240 that the server anticipates the client will need, trading off some 241 network usage against a potential latency gain. The server does this 242 by synthesizing a request, which it sends as a PUSH_PROMISE frame. 243 The server is then able to send a response to the synthetic request 244 on a separate stream. 246 2.1. Document Organization 248 The HTTP/2 specification is split into four parts: 250 * Starting HTTP/2 (Section 3) covers how an HTTP/2 connection is 251 initiated. 253 * The frame (Section 4) and stream (Section 5) layers describe the 254 way HTTP/2 frames are structured and formed into multiplexed 255 streams. 257 * Frame (Section 6) and error (Section 7) definitions include 258 details of the frame and error types used in HTTP/2. 260 * HTTP mappings (Section 8) and additional requirements (Section 9) 261 describe how HTTP semantics are expressed using frames and 262 streams. 264 While some of the frame and stream layer concepts are isolated from 265 HTTP, this specification does not define a completely generic frame 266 layer. The frame and stream layers are tailored to the needs of the 267 HTTP protocol. 269 2.2. Conventions and Terminology 271 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 272 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 273 "OPTIONAL" in this document are to be interpreted as described in 274 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 275 capitals, as shown here. 277 All numeric values are in network byte order. Values are unsigned 278 unless otherwise indicated. Literal values are provided in decimal 279 or hexadecimal as appropriate. Hexadecimal literals are prefixed 280 with "0x" to distinguish them from decimal literals. 282 This specification describes binary formats using the convention 283 described in Section 1.3 of RFC 9000 [QUIC]. Note that this format 284 uses network byte order and high-valued bits are listed before low- 285 valued bits. 287 The following terms are used: 289 client: The endpoint that initiates an HTTP/2 connection. Clients 290 send HTTP requests and receive HTTP responses. 292 connection: A transport-layer connection between two endpoints. 294 connection error: An error that affects the entire HTTP/2 295 connection. 297 endpoint: Either the client or server of the connection. 299 frame: The smallest unit of communication within an HTTP/2 300 connection, consisting of a header and a variable-length sequence 301 of octets structured according to the frame type. 303 peer: An endpoint. When discussing a particular endpoint, "peer" 304 refers to the endpoint that is remote to the primary subject of 305 discussion. 307 receiver: An endpoint that is receiving frames. 309 sender: An endpoint that is transmitting frames. 311 server: The endpoint that accepts an HTTP/2 connection. Servers 312 receive HTTP requests and send HTTP responses. 314 stream: A bidirectional flow of frames within the HTTP/2 connection. 316 stream error: An error on the individual HTTP/2 stream. 318 Finally, the terms "gateway", "intermediary", "proxy", and "tunnel" 319 are defined in Section 3.7 of [HTTP]. Intermediaries act as both 320 client and server at different times. 322 The term "content" as it applies to message bodies is defined in 323 Section 6.4 of [HTTP]. 325 3. Starting HTTP/2 327 An HTTP/2 connection is an application-layer protocol running on top 328 of a TCP connection ([TCP]). The client is the TCP connection 329 initiator. 331 HTTP/2 uses the "http" and "https" URI schemes defined in Section 4.2 332 of [HTTP], with the same default port numbers. As a result, 333 implementations processing requests for target resource URIs like 334 http://example.org/foo or https://example.com/bar are required to 335 first discover whether the upstream server (the immediate peer to 336 which the client wishes to establish a connection) supports HTTP/2. 338 The means by which support for HTTP/2 is determined is different for 339 "http" and "https" URIs. Discovery for "https" URIs is described in 340 Section 3.2. HTTP/2 support for "http" URIs can only be discovered 341 by out-of-band means, and requires prior knowledge of the support as 342 described in Section 3.3. 344 3.1. HTTP/2 Version Identification 346 The protocol defined in this document has two identifiers. Creating 347 a connection based on either implies the use of the transport, 348 framing, and message semantics described in this document. 350 * The string "h2" identifies the protocol where HTTP/2 uses 351 Transport Layer Security (TLS); see Section 9.2. This identifier 352 is used in the TLS application-layer protocol negotiation (ALPN) 353 extension [TLS-ALPN] field and in any place where HTTP/2 over TLS 354 is identified. 356 The "h2" string is serialized into an ALPN protocol identifier as 357 the two-octet sequence: 0x68, 0x32. 359 * The string "h2c" identifies the protocol where HTTP/2 is run over 360 cleartext TCP. This identifier is used in any place where HTTP/2 361 over TCP is identified. 363 The "h2c" string is reserved from the ALPN identifier space but 364 describes a protocol that does not use TLS. The security 365 properties of this protocol do not hold unless TLS is used; see 366 Section 10. 368 The "h2c" string was previously used as a token for use in the 369 HTTP Upgrade mechanism's Upgrade header field (Section 7.8 of 370 [HTTP]). This usage was never widely deployed, and is no longer 371 specified in this document. 373 3.2. Starting HTTP/2 for "https" URIs 375 A client that makes a request to an "https" URI uses TLS [TLS13] with 376 the application-layer protocol negotiation (ALPN) extension 377 [TLS-ALPN]. 379 HTTP/2 over TLS uses the "h2" protocol identifier. The "h2c" 380 protocol identifier MUST NOT be sent by a client or selected by a 381 server; the "h2c" protocol identifier describes a protocol that does 382 not use TLS. 384 Once TLS negotiation is complete, both the client and the server MUST 385 send a connection preface (Section 3.4). 387 3.3. Starting HTTP/2 with Prior Knowledge 389 A client can learn that a particular server supports HTTP/2 by other 390 means. For example, a client could be configured with knowledge that 391 a server supports HTTP/2. 393 A client that knows that a server supports HTTP/2 can establish a TCP 394 connection and send the connection preface (Section 3.4) followed by 395 HTTP/2 frames. Servers can identify these connections by the 396 presence of the connection preface. This only affects the 397 establishment of HTTP/2 connections over cleartext TCP; HTTP/2 398 connections over TLS MUST use protocol negotiation in TLS [TLS-ALPN]. 400 Likewise, the server MUST send a connection preface (Section 3.4). 402 Without additional information, prior support for HTTP/2 is not a 403 strong signal that a given server will support HTTP/2 for future 404 connections. For example, it is possible for server configurations 405 to change, for configurations to differ between instances in 406 clustered servers, or for network conditions to change. 408 3.4. HTTP/2 Connection Preface 410 In HTTP/2, each endpoint is required to send a connection preface as 411 a final confirmation of the protocol in use and to establish the 412 initial settings for the HTTP/2 connection. The client and server 413 each send a different connection preface. 415 The client connection preface starts with a sequence of 24 octets, 416 which in hex notation is: 418 0x505249202a20485454502f322e300d0a0d0a534d0d0a0d0a 420 That is, the connection preface starts with the string "PRI * 421 HTTP/2.0\r\n\r\nSM\r\n\r\n". This sequence MUST be followed by a 422 SETTINGS frame (Section 6.5), which MAY be empty. The client sends 423 the client connection preface as the first application data octets of 424 a connection. 426 | Note: The client connection preface is selected so that a large 427 | proportion of HTTP/1.1 or HTTP/1.0 servers and intermediaries 428 | do not attempt to process further frames. Note that this does 429 | not address the concerns raised in [TALKING]. 431 The server connection preface consists of a potentially empty 432 SETTINGS frame (Section 6.5) that MUST be the first frame the server 433 sends in the HTTP/2 connection. 435 The SETTINGS frames received from a peer as part of the connection 436 preface MUST be acknowledged (see Section 6.5.3) after sending the 437 connection preface. 439 To avoid unnecessary latency, clients are permitted to send 440 additional frames to the server immediately after sending the client 441 connection preface, without waiting to receive the server connection 442 preface. It is important to note, however, that the server 443 connection preface SETTINGS frame might include settings that 444 necessarily alter how a client is expected to communicate with the 445 server. Upon receiving the SETTINGS frame, the client is expected to 446 honor any settings established. In some configurations, it is 447 possible for the server to transmit SETTINGS before the client sends 448 additional frames, providing an opportunity to avoid this issue. 450 Clients and servers MUST treat an invalid connection preface as a 451 connection error (Section 5.4.1) of type PROTOCOL_ERROR. A GOAWAY 452 frame (Section 6.8) MAY be omitted in this case, since an invalid 453 preface indicates that the peer is not using HTTP/2. 455 4. HTTP Frames 457 Once the HTTP/2 connection is established, endpoints can begin 458 exchanging frames. 460 4.1. Frame Format 462 All frames begin with a fixed 9-octet header followed by a variable- 463 length frame payload. 465 HTTP Frame { 466 Length (24), 467 Type (8), 469 Flags (8), 471 Reserved (1), 472 Stream Identifier (31), 474 Frame Payload (..), 475 } 477 Figure 1: Frame Layout 479 The fields of the frame header are defined as: 481 Length: The length of the frame payload expressed as an unsigned 482 24-bit integer. Values greater than 2^14 (16,384) MUST NOT be 483 sent unless the receiver has set a larger value for 484 SETTINGS_MAX_FRAME_SIZE. 486 The 9 octets of the frame header are not included in this value. 488 Type: The 8-bit type of the frame. The frame type determines the 489 format and semantics of the frame. Frames defined in this 490 documented are listed in Section 6. Implementations MUST ignore 491 and discard any frame that has a type that is unknown. 493 Flags: An 8-bit field reserved for boolean flags specific to the 494 frame type. 496 Flags are assigned semantics specific to the indicated frame type. 497 Unused flags are those that have no defined semantics for a 498 particular frame type, and MUST be ignored and MUST be left unset 499 (0x0) when sending. 501 Reserved: A reserved 1-bit field. The semantics of this bit are 502 undefined, and the bit MUST remain unset (0x0) when sending and 503 MUST be ignored when receiving. 505 Stream Identifier: A stream identifier (see Section 5.1.1) expressed 506 as an unsigned 31-bit integer. The value 0x0 is reserved for 507 frames that are associated with the connection as a whole as 508 opposed to an individual stream. 510 The structure and content of the frame payload is dependent entirely 511 on the frame type. 513 4.2. Frame Size 515 The size of a frame payload is limited by the maximum size that a 516 receiver advertises in the SETTINGS_MAX_FRAME_SIZE setting. This 517 setting can have any value between 2^14 (16,384) and 2^24-1 518 (16,777,215) octets, inclusive. 520 All implementations MUST be capable of receiving and minimally 521 processing frames up to 2^14 octets in length, plus the 9-octet frame 522 header (Section 4.1). The size of the frame header is not included 523 when describing frame sizes. 525 | Note: Certain frame types, such as PING (Section 6.7), impose 526 | additional limits on the amount of frame payload data allowed. 528 An endpoint MUST send an error code of FRAME_SIZE_ERROR if a frame 529 exceeds the size defined in SETTINGS_MAX_FRAME_SIZE, exceeds any 530 limit defined for the frame type, or is too small to contain 531 mandatory frame data. A frame size error in a frame that could alter 532 the state of the entire connection MUST be treated as a connection 533 error (Section 5.4.1); this includes any frame carrying a field block 534 (Section 4.3) (that is, HEADERS, PUSH_PROMISE, and CONTINUATION), 535 SETTINGS, and any frame with a stream identifier of 0. 537 Endpoints are not obligated to use all available space in a frame. 538 Responsiveness can be improved by using frames that are smaller than 539 the permitted maximum size. Sending large frames can result in 540 delays in sending time-sensitive frames (such as RST_STREAM, 541 WINDOW_UPDATE, or PRIORITY), which, if blocked by the transmission of 542 a large frame, could affect performance. 544 4.3. Field Section Compression and Decompression 546 Field section compression is the process of compressing a set of 547 field lines (Section 5.2 of [HTTP]) to form a field block. Field 548 section decompression is the process of decoding a field block into a 549 set of field lines. Details of HTTP/2 field section compression and 550 decompression is defined in [COMPRESSION], which, for historical 551 reasons, refers to these processes as header compression and 552 decompression. 554 Field blocks carry the compressed bytes of a field section, with 555 header sections also carrying control data associated with the 556 message in the form of pseudo-header fields (Section 8.3) that use 557 the same format as a field line. 559 | Note: RFC 7540 [RFC7540] used the term "header block" in place 560 | of the more generic "field block". 562 Field blocks carry control data and header sections for requests, 563 responses, promised requests, and pushed responses (see Section 8.4). 564 All these messages, except for interim responses and requests 565 contained in PUSH_PROMISE (Section 6.6) frames, can optionally 566 include a field block that carries a trailer section. 568 A field section is a collection of field lines. Each of the field 569 lines in a field block carry a single value. The serialized field 570 block is then divided into one or more octet sequences, called field 571 block fragments, and transmitted within the frame payload of HEADERS 572 (Section 6.2) or PUSH_PROMISE (Section 6.6), each of which could be 573 followed by CONTINUATION (Section 6.10) frames. 575 The Cookie header field [COOKIE] is treated specially by the HTTP 576 mapping (see Section 8.2.3). 578 A receiving endpoint reassembles the field block by concatenating its 579 fragments and then decompresses the block to reconstruct the field 580 section. 582 A complete field section consists of either: 584 * a single HEADERS or PUSH_PROMISE frame, with the END_HEADERS flag 585 set, or 587 * a HEADERS or PUSH_PROMISE frame with the END_HEADERS flag cleared 588 and one or more CONTINUATION frames, where the last CONTINUATION 589 frame has the END_HEADERS flag set. 591 Field compression is stateful. One compression context and one 592 decompression context are used for the entire connection. A decoding 593 error in a field block MUST be treated as a connection error 594 (Section 5.4.1) of type COMPRESSION_ERROR. 596 Each field block is processed as a discrete unit. Field blocks MUST 597 be transmitted as a contiguous sequence of frames, with no 598 interleaved frames of any other type or from any other stream. The 599 last frame in a sequence of HEADERS or CONTINUATION frames has the 600 END_HEADERS flag set. The last frame in a sequence of PUSH_PROMISE 601 or CONTINUATION frames has the END_HEADERS flag set. This allows a 602 field block to be logically equivalent to a single frame. 604 Field block fragments can only be sent as the frame payload of 605 HEADERS, PUSH_PROMISE, or CONTINUATION frames because these frames 606 carry data that can modify the compression context maintained by a 607 receiver. An endpoint receiving HEADERS, PUSH_PROMISE, or 608 CONTINUATION frames needs to reassemble field blocks and perform 609 decompression even if the frames are to be discarded. A receiver 610 MUST terminate the connection with a connection error (Section 5.4.1) 611 of type COMPRESSION_ERROR if it does not decompress a field block. 613 5. Streams and Multiplexing 615 A "stream" is an independent, bidirectional sequence of frames 616 exchanged between the client and server within an HTTP/2 connection. 617 Streams have several important characteristics: 619 * A single HTTP/2 connection can contain multiple concurrently open 620 streams, with either endpoint interleaving frames from multiple 621 streams. 623 * Streams can be established and used unilaterally or shared by 624 either the client or server. 626 * Streams can be closed by either endpoint. 628 * The order in which frames are sent is significant. Recipients 629 process frames in the order they are received. In particular, the 630 order of HEADERS and DATA frames is semantically significant. 632 * Streams are identified by an integer. Stream identifiers are 633 assigned to streams by the endpoint initiating the stream. 635 5.1. Stream States 637 The lifecycle of a stream is shown in Figure 2. 639 +--------+ 640 send PP | | recv PP 641 ,--------+ idle +--------. 642 / | | \ 643 v +--------+ v 644 +----------+ | +----------+ 645 | | | send H / | | 646 ,------+ reserved | | recv H | reserved +------. 647 | | (local) | | | (remote) | | 648 | +---+------+ v +------+---+ | 649 | | +--------+ | | 650 | | recv ES | | send ES | | 651 | send H | ,-------+ open +-------. | recv H | 652 | | / | | \ | | 653 | v v +---+----+ v v | 654 | +----------+ | +----------+ | 655 | | half | | | half | | 656 | | closed | | send R / | closed | | 657 | | (remote) | | recv R | (local) | | 658 | +----+-----+ | +-----+----+ | 659 | | | | | 660 | | send ES / | recv ES / | | 661 | | send R / v send R / | | 662 | | recv R +--------+ recv R | | 663 | send R / `----------->| |<-----------' send R / | 664 | recv R | closed | recv R | 665 `----------------------->| |<-----------------------' 666 +--------+ 668 Figure 2: Stream States 670 send: endpoint sends this frame 671 recv: endpoint receives this frame 672 H: HEADERS frame (with implied CONTINUATION frames) 673 ES: END_STREAM flag 674 R: RST_STREAM frame 675 PP: PUSH_PROMISE frame (with implied CONTINUATION frames); state 676 transitions are for the promised stream 678 Note that this diagram shows stream state transitions and the frames 679 and flags that affect those transitions only. In this regard, 680 CONTINUATION frames do not result in state transitions; they are 681 effectively part of the HEADERS or PUSH_PROMISE that they follow. 682 For the purpose of state transitions, the END_STREAM flag is 683 processed as a separate event to the frame that bears it; a HEADERS 684 frame with the END_STREAM flag set can cause two state transitions. 686 Both endpoints have a subjective view of the state of a stream that 687 could be different when frames are in transit. Endpoints do not 688 coordinate the creation of streams; they are created unilaterally by 689 either endpoint. The negative consequences of a mismatch in states 690 are limited to the "closed" state after sending RST_STREAM, where 691 frames might be received for some time after closing. 693 Streams have the following states: 695 idle: All streams start in the "idle" state. 697 The following transitions are valid from this state: 699 * Sending a HEADERS frame as a client, or receiving a HEADERS 700 frame as a server, causes the stream to become "open". The 701 stream identifier is selected as described in Section 5.1.1. 702 The same HEADERS frame can also cause a stream to immediately 703 become "half-closed". 705 * Sending a PUSH_PROMISE frame on another stream reserves the 706 idle stream that is identified for later use. The stream state 707 for the reserved stream transitions to "reserved (local)". 708 Only a server may send PUSH_PROMISE frames. 710 * Receiving a PUSH_PROMISE frame on another stream reserves an 711 idle stream that is identified for later use. The stream state 712 for the reserved stream transitions to "reserved (remote)". 713 Only a client may receive PUSH_PROMISE frames. 715 * Note that the PUSH_PROMISE frame is not sent on the idle stream 716 but references the newly reserved stream in the Promised Stream 717 ID field. 719 Receiving any frame other than HEADERS or PRIORITY on a stream in 720 this state MUST be treated as a connection error (Section 5.4.1) 721 of type PROTOCOL_ERROR. If this stream is server-initiated, as 722 described in Section 5.1.1, then receiving a HEADERS frame MUST 723 also be treated as a connection error (Section 5.4.1) of type 724 PROTOCOL_ERROR. 726 reserved (local): A stream in the "reserved (local)" state is one 727 that has been promised by sending a PUSH_PROMISE frame. A 728 PUSH_PROMISE frame reserves an idle stream by associating the 729 stream with an open stream that was initiated by the remote peer 730 (see Section 8.4). 732 In this state, only the following transitions are possible: 734 * The endpoint can send a HEADERS frame. This causes the stream 735 to open in a "half-closed (remote)" state. 737 * Either endpoint can send a RST_STREAM frame to cause the stream 738 to become "closed". This releases the stream reservation. 740 An endpoint MUST NOT send any type of frame other than HEADERS, 741 RST_STREAM, or PRIORITY in this state. 743 A PRIORITY or WINDOW_UPDATE frame MAY be received in this state. 744 Receiving any type of frame other than RST_STREAM, PRIORITY, or 745 WINDOW_UPDATE on a stream in this state MUST be treated as a 746 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 748 reserved (remote): A stream in the "reserved (remote)" state has 749 been reserved by a remote peer. 751 In this state, only the following transitions are possible: 753 * Receiving a HEADERS frame causes the stream to transition to 754 "half-closed (local)". 756 * Either endpoint can send a RST_STREAM frame to cause the stream 757 to become "closed". This releases the stream reservation. 759 An endpoint MUST NOT send any type of frame other than RST_STREAM, 760 WINDOW_UPDATE, or PRIORITY in this state. 762 Receiving any type of frame other than HEADERS, RST_STREAM, or 763 PRIORITY on a stream in this state MUST be treated as a connection 764 error (Section 5.4.1) of type PROTOCOL_ERROR. 766 open: A stream in the "open" state may be used by both peers to send 767 frames of any type. In this state, sending peers observe 768 advertised stream-level flow-control limits (Section 5.2). 770 From this state, either endpoint can send a frame with an 771 END_STREAM flag set, which causes the stream to transition into 772 one of the "half-closed" states. An endpoint sending an 773 END_STREAM flag causes the stream state to become "half-closed 774 (local)"; an endpoint receiving an END_STREAM flag causes the 775 stream state to become "half-closed (remote)". 777 Either endpoint can send a RST_STREAM frame from this state, 778 causing it to transition immediately to "closed". 780 half-closed (local): A stream that is in the "half-closed (local)" 781 state cannot be used for sending frames other than WINDOW_UPDATE, 782 PRIORITY, and RST_STREAM. 784 A stream transitions from this state to "closed" when a frame is 785 received with the END_STREAM flag set or when either peer sends a 786 RST_STREAM frame. 788 An endpoint can receive any type of frame in this state. 789 Providing flow-control credit using WINDOW_UPDATE frames is 790 necessary to continue receiving flow-controlled frames. In this 791 state, a receiver can ignore WINDOW_UPDATE frames, which might 792 arrive for a short period after a frame with the END_STREAM flag 793 set is sent. 795 PRIORITY frames can be received in this state. 797 half-closed (remote): A stream that is "half-closed (remote)" is no 798 longer being used by the peer to send frames. In this state, an 799 endpoint is no longer obligated to maintain a receiver flow- 800 control window. 802 If an endpoint receives additional frames, other than 803 WINDOW_UPDATE, PRIORITY, or RST_STREAM, for a stream that is in 804 this state, it MUST respond with a stream error (Section 5.4.2) of 805 type STREAM_CLOSED. 807 A stream that is "half-closed (remote)" can be used by the 808 endpoint to send frames of any type. In this state, the endpoint 809 continues to observe advertised stream-level flow-control limits 810 (Section 5.2). 812 A stream can transition from this state to "closed" by sending a 813 frame with the END_STREAM flag set or when either peer sends a 814 RST_STREAM frame. 816 closed: The "closed" state is the terminal state. 818 A stream enters the "closed" state after an endpoint both sends 819 and receives a frame with an END_STREAM flag set. A stream also 820 enters the "closed" state after an endpoint either sends or 821 receives a RST_STREAM frame. 823 An endpoint MUST NOT send frames other than PRIORITY on a closed 824 stream. An endpoint MAY treat receipt of any other type of frame 825 on a closed stream as a connection error (Section 5.4.1) of type 826 STREAM_CLOSED, except as noted below. 828 An endpoint that sends a frame with the END_STREAM flag set or a 829 RST_STREAM frame might receive a WINDOW_UPDATE or RST_STREAM frame 830 from its peer in the time before the peer receives and processes 831 the frame that closes the stream. 833 An endpoint that sends a RST_STREAM frame on a stream that is in 834 the "open" state could receive any type of frame. The peer might 835 have sent or enqueued for sending these frames before processing 836 the RST_STREAM frame. An endpoint MUST minimally process and then 837 discard any frames it receives in this state. This means updating 838 header compression state for HEADERS and PUSH_PROMISE frames; 839 PUSH_PROMISE frames also cause the promised stream to become 840 "reserved", even when the PUSH_PROMISE frame is received on a 841 closed stream; and, the content of DATA frames counts toward the 842 connection flow-control window. 844 An endpoint can perform this minimal processing for all streams 845 that are in the "closed" state. Endpoints MAY use other signals 846 to detect that a peer has received the frames that caused the 847 stream to enter the "closed" state and treat receipt of any frame 848 other than PRIORITY as a connection error (Section 5.4.1) of type 849 PROTOCOL_ERROR. Endpoints can use frames that indicate that the 850 peer has received the closing signal to drive this. Endpoints 851 SHOULD NOT use timers for this purpose. For example, an endpoint 852 that sends a SETTINGS frame after closing a stream can safely 853 treat receipt of a DATA frame on that stream as an error after 854 receiving an acknowledgement of the settings. Other things that 855 might be used are PING frames, receiving data on streams that were 856 created after closing the stream, or responses to requests created 857 after closing the stream. 859 In the absence of more specific rules, implementations SHOULD treat 860 the receipt of a frame that is not expressly permitted in the 861 description of a state as a connection error (Section 5.4.1) of type 862 PROTOCOL_ERROR. Note that PRIORITY can be sent and received in any 863 stream state. 865 The rules in this section only apply to frames defined in this 866 document. Receipt of frames for which the semantics are unknown 867 cannot be treated as an error as the conditions for sending and 868 receiving those frames are also unknown; see Section 5.5. 870 An example of the state transitions for an HTTP request/response 871 exchange can be found in Section 8.8. An example of the state 872 transitions for server push can be found in Sections 8.4.1 and 8.4.2. 874 5.1.1. Stream Identifiers 876 Streams are identified with an unsigned 31-bit integer. Streams 877 initiated by a client MUST use odd-numbered stream identifiers; those 878 initiated by the server MUST use even-numbered stream identifiers. A 879 stream identifier of zero (0x0) is used for connection control 880 messages; the stream identifier of zero cannot be used to establish a 881 new stream. 883 The identifier of a newly established stream MUST be numerically 884 greater than all streams that the initiating endpoint has opened or 885 reserved. This governs streams that are opened using a HEADERS frame 886 and streams that are reserved using PUSH_PROMISE. An endpoint that 887 receives an unexpected stream identifier MUST respond with a 888 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 890 A HEADERS frame will transition the client-initiated stream 891 identified by the stream identifier in the frame header from "idle" 892 to "open". A PUSH_PROMISE frame will transition the server-initiated 893 stream identified by the "Promised Stream ID" field in the frame 894 payload from "idle" to "reserved". When a stream transitions out of 895 the "idle" state, all streams that might have been initiated by that 896 peer with a lower-valued stream identifier are implicitly 897 transitioned to "closed". That is, an endpoint may skip a stream 898 identifier, with the effect being that the skipped stream is 899 immediately closed. 901 Stream identifiers cannot be reused. Long-lived connections can 902 result in an endpoint exhausting the available range of stream 903 identifiers. A client that is unable to establish a new stream 904 identifier can establish a new connection for new streams. A server 905 that is unable to establish a new stream identifier can send a GOAWAY 906 frame so that the client is forced to open a new connection for new 907 streams. 909 5.1.2. Stream Concurrency 911 A peer can limit the number of concurrently active streams using the 912 SETTINGS_MAX_CONCURRENT_STREAMS parameter (see Section 6.5.2) within 913 a SETTINGS frame. The maximum concurrent streams setting is specific 914 to each endpoint and applies only to the peer that receives the 915 setting. That is, clients specify the maximum number of concurrent 916 streams the server can initiate, and servers specify the maximum 917 number of concurrent streams the client can initiate. 919 Streams that are in the "open" state or in either of the "half- 920 closed" states count toward the maximum number of streams that an 921 endpoint is permitted to open. Streams in any of these three states 922 count toward the limit advertised in the 923 SETTINGS_MAX_CONCURRENT_STREAMS setting. Streams in either of the 924 "reserved" states do not count toward the stream limit. 926 Endpoints MUST NOT exceed the limit set by their peer. An endpoint 927 that receives a HEADERS frame that causes its advertised concurrent 928 stream limit to be exceeded MUST treat this as a stream error 929 (Section 5.4.2) of type PROTOCOL_ERROR or REFUSED_STREAM. The choice 930 of error code determines whether the endpoint wishes to enable 931 automatic retry (see Section 8.7 for details). 933 An endpoint that wishes to reduce the value of 934 SETTINGS_MAX_CONCURRENT_STREAMS to a value that is below the current 935 number of open streams can either close streams that exceed the new 936 value or allow streams to complete. 938 5.2. Flow Control 940 Using streams for multiplexing introduces contention over use of the 941 TCP connection, resulting in blocked streams. A flow-control scheme 942 ensures that streams on the same connection do not destructively 943 interfere with each other. Flow control is used for both individual 944 streams and for the connection as a whole. 946 HTTP/2 provides for flow control through use of the WINDOW_UPDATE 947 frame (Section 6.9). 949 5.2.1. Flow-Control Principles 951 HTTP/2 stream flow control aims to allow a variety of flow-control 952 algorithms to be used without requiring protocol changes. Flow 953 control in HTTP/2 has the following characteristics: 955 1. Flow control is specific to a connection. Both types of flow 956 control are between the endpoints of a single hop and not over 957 the entire end-to-end path. 959 2. Flow control is based on WINDOW_UPDATE frames. Receivers 960 advertise how many octets they are prepared to receive on a 961 stream and for the entire connection. This is a credit-based 962 scheme. 964 3. Flow control is directional with overall control provided by the 965 receiver. A receiver MAY choose to set any window size that it 966 desires for each stream and for the entire connection. A sender 967 MUST respect flow-control limits imposed by a receiver. Clients, 968 servers, and intermediaries all independently advertise their 969 flow-control window as a receiver and abide by the flow-control 970 limits set by their peer when sending. 972 4. The initial value for the flow-control window is 65,535 octets 973 for both new streams and the overall connection. 975 5. The frame type determines whether flow control applies to a 976 frame. Of the frames specified in this document, only DATA 977 frames are subject to flow control; all other frame types do not 978 consume space in the advertised flow-control window. This 979 ensures that important control frames are not blocked by flow 980 control. 982 6. Flow control cannot be disabled. 984 7. HTTP/2 defines only the format and semantics of the WINDOW_UPDATE 985 frame (Section 6.9). This document does not stipulate how a 986 receiver decides when to send this frame or the value that it 987 sends, nor does it specify how a sender chooses to send packets. 988 Implementations are able to select any algorithm that suits their 989 needs. 991 Implementations are also responsible for prioritizing the sending of 992 requests and responses, choosing how to avoid head-of-line blocking 993 for requests, and managing the creation of new streams. Algorithm 994 choices for these could interact with any flow-control algorithm. 996 5.2.2. Appropriate Use of Flow Control 998 Flow control is defined to protect endpoints that are operating under 999 resource constraints. For example, a proxy needs to share memory 1000 between many connections and also might have a slow upstream 1001 connection and a fast downstream one. Flow-control addresses cases 1002 where the receiver is unable to process data on one stream yet wants 1003 to continue to process other streams in the same connection. 1005 Deployments that do not require this capability can advertise a flow- 1006 control window of the maximum size (2^31-1) and can maintain this 1007 window by sending a WINDOW_UPDATE frame when any data is received. 1008 This effectively disables flow control for that receiver. 1009 Conversely, a sender is always subject to the flow-control window 1010 advertised by the receiver. 1012 Deployments with constrained resources (for example, memory) can 1013 employ flow control to limit the amount of memory a peer can consume. 1014 Note, however, that this can lead to suboptimal use of available 1015 network resources if flow control is enabled without knowledge of the 1016 bandwidth-delay product (see [RFC7323]). 1018 Even with full awareness of the current bandwidth-delay product, 1019 implementation of flow control can be difficult. Endpoints MUST read 1020 and process HTTP/2 frames from the TCP receive buffer as soon as data 1021 is available. Failure to read promptly could lead to a deadlock when 1022 critical frames, such as WINDOW_UPDATE, are not read and acted upon. 1023 Reading frames promptly does not expose endpoints to resource 1024 exhaustion attacks as HTTP/2 flow control limits resource 1025 commitments. 1027 5.2.3. Flow Control Performance 1029 If an endpoint cannot ensure that its peer always has available flow 1030 control window space that is greater than the peer's bandwidth-delay 1031 product on this connection, its receive throughput will be limited by 1032 HTTP/2 flow control. This will result in degraded performance. 1034 Sending timely WINDOW_UPDATE frames can improve performance. 1035 Endpoints will want to balance the need to improve receive throughput 1036 with the need to manage resource exhaustion risks, and should take 1037 careful note of Section 10.5 in defining their strategy to manage 1038 window sizes. 1040 5.3. Prioritization 1042 In a multiplexed protocol like HTTP/2, prioritizing allocation of 1043 bandwidth and computation resources to streams can be critical to 1044 attaining good performance. A poor prioritization scheme can result 1045 in HTTP/2 providing poor performance. With no parallelism at the TCP 1046 layer, performance could be significantly worse than HTTP/1.1. 1048 A good prioritization scheme benefits from the application of 1049 contextual knowledge such as the content of resources, how resources 1050 are interrelated, and how those resources will be used by a peer. In 1051 particular, clients can possess knowledge about the priority of 1052 requests that is relevant to server prioritization. In those cases, 1053 having clients provide priority information can improve performance. 1055 5.3.1. Background of Priority in HTTP/2 1057 HTTP/2 included a rich system for signaling priority of requests. 1058 However, this system proved to be complex and it was not uniformly 1059 implemented. 1061 The flexible scheme meant that it was possible for clients to express 1062 priorities in very different ways, with little consistency in the 1063 approaches that were adopted. For servers, implementing generic 1064 support for the scheme was complex. Implementation of priorities was 1065 uneven in both clients and servers. Many server deployments ignored 1066 client signals when prioritizing their handling of requests. 1068 In short, the prioritization signaling in RFC7540 [RFC7540] was not 1069 successful. 1071 5.3.2. Priority Signaling in this Document 1073 This update to HTTP/2 deprecates the priority signaling defined in 1074 RFC 7540 [RFC7540]. The bulk of the text related to priority signals 1075 is not included in this document. The description of frame fields 1076 and some of the mandatory handling is retained to ensure that 1077 implementations of this document remain interoperable with 1078 implementations that use the priority signaling described in RFC 1079 7540. 1081 A thorough description of the RFC 7540 priority scheme remains in 1082 Section 5.3 of [RFC7540]. 1084 Signaling priority information is necessary to attain good 1085 performance in many cases. Where signaling priority information is 1086 important, endpoints are encouraged to use an alternative scheme, 1087 such as [I-D.ietf-httpbis-priority]. 1089 Though the priority signaling from RFC 7540 was not widely adopted, 1090 the information it provides can still be useful in the absence of 1091 better information. Endpoints that receive priority signals in 1092 HEADERS or PRIORITY frames can benefit from applying that 1093 information. In particular, implementations that consume these 1094 signals would not benefit from discarding these priority signals in 1095 the absence of alternatives. 1097 Servers SHOULD use other contextual information in determining 1098 priority of requests in the absence of any priority signals. Servers 1099 MAY interpret the complete absence of signals as an indication that 1100 the client has not implemented the feature. The defaults described 1101 in Section 5.3.5 of [RFC7540] are known to have poor performance 1102 under most conditions and their use is unlikely to be deliberate. 1104 5.4. Error Handling 1106 HTTP/2 framing permits two classes of error: 1108 * An error condition that renders the entire connection unusable is 1109 a connection error. 1111 * An error in an individual stream is a stream error. 1113 A list of error codes is included in Section 7. 1115 It is possible that an endpoint will encounter frames that would 1116 cause multiple errors. Implementations MAY discover multiple errors 1117 during processing, but they SHOULD report at most one stream and one 1118 connection error as a result. 1120 The first stream error reported for a given stream prevents any other 1121 errors on that stream from being reported. In comparison, the 1122 protocol permits multiple GOAWAY frames, though an endpoint SHOULD 1123 report just one type of connection error unless an error is 1124 encountered during graceful shutdown. If this occurs, an endpoint 1125 MAY send an additional GOAWAY frame with the new error code, in 1126 addition to any prior GOAWAY that contained NO_ERROR. 1128 If an endpoint detects multiple different errors, it MAY choose to 1129 report any one of those errors. If a frame causes a connection 1130 error, that error MUST be reported. Additionally, an endpoint MAY 1131 use any applicable error code when it detects an error condition; a 1132 generic error code (such as PROTOCOL_ERROR or INTERNAL_ERROR) can 1133 always be used in place of more specific error codes. 1135 5.4.1. Connection Error Handling 1137 A connection error is any error that prevents further processing of 1138 the frame layer or corrupts any connection state. 1140 An endpoint that encounters a connection error SHOULD first send a 1141 GOAWAY frame (Section 6.8) with the stream identifier of the last 1142 stream that it successfully received from its peer. The GOAWAY frame 1143 includes an error code (Section 7) that indicates why the connection 1144 is terminating. After sending the GOAWAY frame for an error 1145 condition, the endpoint MUST close the TCP connection. 1147 It is possible that the GOAWAY will not be reliably received by the 1148 receiving endpoint. In the event of a connection error, GOAWAY only 1149 provides a best-effort attempt to communicate with the peer about why 1150 the connection is being terminated. 1152 An endpoint can end a connection at any time. In particular, an 1153 endpoint MAY choose to treat a stream error as a connection error. 1154 Endpoints SHOULD send a GOAWAY frame when ending a connection, 1155 providing that circumstances permit it. 1157 5.4.2. Stream Error Handling 1159 A stream error is an error related to a specific stream that does not 1160 affect processing of other streams. 1162 An endpoint that detects a stream error sends a RST_STREAM frame 1163 (Section 6.4) that contains the stream identifier of the stream where 1164 the error occurred. The RST_STREAM frame includes an error code that 1165 indicates the type of error. 1167 A RST_STREAM is the last frame that an endpoint can send on a stream. 1168 The peer that sends the RST_STREAM frame MUST be prepared to receive 1169 any frames that were sent or enqueued for sending by the remote peer. 1170 These frames can be ignored, except where they modify connection 1171 state (such as the state maintained for field section compression 1172 (Section 4.3) or flow control). 1174 Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame 1175 for any stream. However, an endpoint MAY send additional RST_STREAM 1176 frames if it receives frames on a closed stream after more than a 1177 round-trip time. This behavior is permitted to deal with misbehaving 1178 implementations. 1180 To avoid looping, an endpoint MUST NOT send a RST_STREAM in response 1181 to a RST_STREAM frame. 1183 5.4.3. Connection Termination 1185 If the TCP connection is closed or reset while streams remain in the 1186 "open" or "half-closed" states, then the affected streams cannot be 1187 automatically retried (see Section 8.7 for details). 1189 5.5. Extending HTTP/2 1191 HTTP/2 permits extension of the protocol. Within the limitations 1192 described in this section, protocol extensions can be used to provide 1193 additional services or alter any aspect of the protocol. Extensions 1194 are effective only within the scope of a single HTTP/2 connection. 1196 This applies to the protocol elements defined in this document. This 1197 does not affect the existing options for extending HTTP, such as 1198 defining new methods, status codes, or fields (see Section 16 of 1199 [HTTP]). 1201 Extensions are permitted to use new frame types (Section 4.1), new 1202 settings (Section 6.5), or new error codes (Section 7). Registries 1203 for managing these extension points are defined in Section 11 of 1204 [RFC7540]. 1206 Implementations MUST ignore unknown or unsupported values in all 1207 extensible protocol elements. Implementations MUST discard frames 1208 that have unknown or unsupported types. This means that any of these 1209 extension points can be safely used by extensions without prior 1210 arrangement or negotiation. However, extension frames that appear in 1211 the middle of a field block (Section 4.3) are not permitted; these 1212 MUST be treated as a connection error (Section 5.4.1) of type 1213 PROTOCOL_ERROR. 1215 Extensions SHOULD avoid changing protocol elements defined in this 1216 document or elements for which no extension mechanism is defined. 1217 This includes changes to the layout of frames, additions or changes 1218 to the way that frames are composed into HTTP messages (Section 8.1), 1219 the definition of pseudo-header fields, or changes to any protocol 1220 element that a compliant endpoint might treat as a connection error 1221 (Section 5.4.1). 1223 An extension that changes existing elements MUST be negotiated before 1224 being used. For example, an extension that changes the layout of the 1225 HEADERS frame cannot be used until the peer has given a positive 1226 signal that this is acceptable. In this case, it could also be 1227 necessary to coordinate when the revised layout comes into effect. 1228 For example, treating frames other than DATA frames as flow 1229 controlled requires a change in semantics that both endpoints need to 1230 understand, so this can only be done through negotiation. 1232 This document doesn't mandate a specific method for negotiating the 1233 use of an extension but notes that a setting (Section 6.5.2) could be 1234 used for that purpose. If both peers set a value that indicates 1235 willingness to use the extension, then the extension can be used. If 1236 a setting is used for extension negotiation, the initial value MUST 1237 be defined in such a fashion that the extension is initially 1238 disabled. 1240 6. Frame Definitions 1242 This specification defines a number of frame types, each identified 1243 by a unique 8-bit type code. Each frame type serves a distinct 1244 purpose in the establishment and management either of the connection 1245 as a whole or of individual streams. 1247 The transmission of specific frame types can alter the state of a 1248 connection. If endpoints fail to maintain a synchronized view of the 1249 connection state, successful communication within the connection will 1250 no longer be possible. Therefore, it is important that endpoints 1251 have a shared comprehension of how the state is affected by the use 1252 of any given frame. 1254 6.1. DATA 1256 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 1257 octets associated with a stream. One or more DATA frames are used, 1258 for instance, to carry HTTP request or response message contents. 1260 DATA frames MAY also contain padding. Padding can be added to DATA 1261 frames to obscure the size of messages. Padding is a security 1262 feature; see Section 10.7. 1264 DATA Frame { 1265 Length (24), 1266 Type (8) = 0, 1268 Unused Flags (4), 1269 PADDED Flag (1), 1270 Unused Flags (2), 1271 END_STREAM Flag (1), 1273 Reserved (1), 1274 Stream Identifier (31), 1276 [Pad Length (8)], 1277 Data (..), 1278 Padding (..), 1279 } 1280 Figure 3: DATA Frame Format 1282 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1283 fields are described in Section 4. The DATA frame contains the 1284 following additional fields: 1286 Pad Length: An 8-bit field containing the length of the frame 1287 padding in units of octets. This field is conditional and is only 1288 present if the PADDED flag is set. 1290 Data: Application data. The amount of data is the remainder of the 1291 frame payload after subtracting the length of the other fields 1292 that are present. 1294 Padding: Padding octets that contain no application semantic value. 1295 Padding octets MUST be set to zero when sending. A receiver is 1296 not obligated to verify padding but MAY treat non-zero padding as 1297 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1299 The DATA frame defines the following flags: 1301 PADDED (0x8): When set, the PADDED flag indicates that the Pad 1302 Length field and any padding that it describes are present. 1304 END_STREAM (0x1): When set, the END_STREAM flag indicates that this 1305 frame is the last that the endpoint will send for the identified 1306 stream. Setting this flag causes the stream to enter one of the 1307 "half-closed" states or the "closed" state (Section 5.1). 1309 DATA frames MUST be associated with a stream. If a DATA frame is 1310 received whose stream identifier field is 0x0, the recipient MUST 1311 respond with a connection error (Section 5.4.1) of type 1312 PROTOCOL_ERROR. 1314 DATA frames are subject to flow control and can only be sent when a 1315 stream is in the "open" or "half-closed (remote)" state. The entire 1316 DATA frame payload is included in flow control, including the Pad 1317 Length and Padding fields if present. If a DATA frame is received 1318 whose stream is not in "open" or "half-closed (local)" state, the 1319 recipient MUST respond with a stream error (Section 5.4.2) of type 1320 STREAM_CLOSED. 1322 The total number of padding octets is determined by the value of the 1323 Pad Length field. If the length of the padding is the length of the 1324 frame payload or greater, the recipient MUST treat this as a 1325 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1327 | Note: A frame can be increased in size by one octet by 1328 | including a Pad Length field with a value of zero. 1330 6.2. HEADERS 1332 The HEADERS frame (type=0x1) is used to open a stream (Section 5.1), 1333 and additionally carries a field block fragment. Despite the name, a 1334 HEADERS frame can carry a header section or a trailer section. 1335 HEADERS frames can be sent on a stream in the "idle", "reserved 1336 (local)", "open", or "half-closed (remote)" state. 1338 HEADERS Frame { 1339 Length (24), 1340 Type (8) = 1, 1342 Unused Flags (2), 1343 PRIORITY Flag (1), 1344 Unused Flag (1), 1345 PADDED Flag (1), 1346 END_HEADERS Flag (1), 1347 Unused Flag (1), 1348 END_STREAM Flag (1), 1350 Reserved (1), 1351 Stream Identifier (31), 1353 [Pad Length (8)], 1354 [Exclusive (1)], 1355 [Stream Dependency (31)], 1356 [Weight (8)], 1357 Field Block Fragment (..), 1358 Padding (..), 1359 } 1361 Figure 4: HEADERS Frame Format 1363 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1364 fields are described in Section 4. The HEADERS frame payload has the 1365 following additional fields: 1367 Pad Length: An 8-bit field containing the length of the frame 1368 padding in units of octets. This field is only present if the 1369 PADDED flag is set. 1371 Exclusive: A single-bit flag. This field is only present if the 1372 PRIORITY flag is set. Priority signals in HEADERS frames are 1373 deprecated; see Section 5.3.2. 1375 Stream Dependency: A 31-bit stream identifier. This field is only 1376 present if the PRIORITY flag is set. 1378 Weight: An unsigned 8-bit integer. This field is only present if 1379 the PRIORITY flag is set. 1381 Field Block Fragment: A field block fragment (Section 4.3). 1383 Padding: Padding octets that contain no application semantic value. 1384 Padding octets MUST be set to zero when sending. A receiver is 1385 not obligated to verify padding but MAY treat non-zero padding as 1386 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1388 The HEADERS frame defines the following flags: 1390 PRIORITY (0x20): When set, the PRIORITY flag indicates that the 1391 Exclusive, Stream Dependency, and Weight fields are present. 1393 PADDED (0x8): When set, the PADDED flag indicates that the Pad 1394 Length field and any padding that it describes are present. 1396 END_HEADERS (0x4): When set, the END_HEADERS flag indicates that 1397 this frame contains an entire field block (Section 4.3) and is not 1398 followed by any CONTINUATION frames. 1400 A HEADERS frame without the END_HEADERS flag set MUST be followed 1401 by a CONTINUATION frame for the same stream. A receiver MUST 1402 treat the receipt of any other type of frame or a frame on a 1403 different stream as a connection error (Section 5.4.1) of type 1404 PROTOCOL_ERROR. 1406 END_STREAM (0x1): When set, the END_STREAM flag indicates that the 1407 field block (Section 4.3) is the last that the endpoint will send 1408 for the identified stream. 1410 A HEADERS frame with the END_STREAM flag set signals the end of a 1411 stream. However, a HEADERS frame with the END_STREAM flag set can 1412 be followed by CONTINUATION frames on the same stream. Logically, 1413 the CONTINUATION frames are part of the HEADERS frame. 1415 The frame payload of a HEADERS frame contains a field block fragment 1416 (Section 4.3). A field block that does not fit within a HEADERS 1417 frame is continued in a CONTINUATION frame (Section 6.10). 1419 HEADERS frames MUST be associated with a stream. If a HEADERS frame 1420 is received whose stream identifier field is 0x0, the recipient MUST 1421 respond with a connection error (Section 5.4.1) of type 1422 PROTOCOL_ERROR. 1424 The HEADERS frame changes the connection state as described in 1425 Section 4.3. 1427 The total number of padding octets is determined by the value of the 1428 Pad Length field. If the length of the padding is the length of the 1429 frame payload or greater, the recipient MUST treat this as a 1430 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1432 | Note: A frame can be increased in size by one octet by 1433 | including a Pad Length field with a value of zero. 1435 6.3. PRIORITY 1437 The PRIORITY frame (type=0x2) is deprecated; see Section 5.3.2. A 1438 PRIORITY frame can be sent in any stream state, including idle or 1439 closed streams. 1441 PRIORITY Frame { 1442 Length (24), 1443 Type (8) = 2, 1445 Unused Flags (8), 1447 Reserved (1), 1448 Stream Identifier (31), 1450 Exclusive (1), 1451 Stream Dependency (31), 1452 Weight (8), 1453 } 1455 Figure 5: PRIORITY Frame Format 1457 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1458 fields are described in Section 4. The frame payload of a PRIORITY 1459 frame contains the following additional fields: 1461 Exclusive: A single-bit flag. 1463 Stream Dependency: A 31-bit stream identifier. 1465 Weight: An unsigned 8-bit integer. 1467 The PRIORITY frame does not define any flags. 1469 The PRIORITY frame always identifies a stream. If a PRIORITY frame 1470 is received with a stream identifier of 0x0, the recipient MUST 1471 respond with a connection error (Section 5.4.1) of type 1472 PROTOCOL_ERROR. 1474 Sending or receiving a PRIORITY frame does not affect the state of 1475 any stream (Section 5.1). The PRIORITY frame can be sent on a stream 1476 in any state, including "idle" or "closed". A PRIORITY frame cannot 1477 be sent between consecutive frames that comprise a single field block 1478 (Section 4.3). 1480 A PRIORITY frame with a length other than 5 octets MUST be treated as 1481 a stream error (Section 5.4.2) of type FRAME_SIZE_ERROR. 1483 6.4. RST_STREAM 1485 The RST_STREAM frame (type=0x3) allows for immediate termination of a 1486 stream. RST_STREAM is sent to request cancellation of a stream or to 1487 indicate that an error condition has occurred. 1489 RST_STREAM Frame { 1490 Length (24), 1491 Type (8) = 3, 1493 Unused Flags (8), 1495 Reserved (1), 1496 Stream Identifier (31), 1498 Error Code (32), 1499 } 1501 Figure 6: RST_STREAM Frame Format 1503 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1504 fields are described in Section 4. Additionally, the RST_STREAM 1505 frame contains a single unsigned, 32-bit integer identifying the 1506 error code (Section 7). The error code indicates why the stream is 1507 being terminated. 1509 The RST_STREAM frame does not define any flags. 1511 The RST_STREAM frame fully terminates the referenced stream and 1512 causes it to enter the "closed" state. After receiving a RST_STREAM 1513 on a stream, the receiver MUST NOT send additional frames for that 1514 stream, with the exception of PRIORITY. However, after sending the 1515 RST_STREAM, the sending endpoint MUST be prepared to receive and 1516 process additional frames sent on the stream that might have been 1517 sent by the peer prior to the arrival of the RST_STREAM. 1519 RST_STREAM frames MUST be associated with a stream. If a RST_STREAM 1520 frame is received with a stream identifier of 0x0, the recipient MUST 1521 treat this as a connection error (Section 5.4.1) of type 1522 PROTOCOL_ERROR. 1524 RST_STREAM frames MUST NOT be sent for a stream in the "idle" state. 1525 If a RST_STREAM frame identifying an idle stream is received, the 1526 recipient MUST treat this as a connection error (Section 5.4.1) of 1527 type PROTOCOL_ERROR. 1529 A RST_STREAM frame with a length other than 4 octets MUST be treated 1530 as a connection error (Section 5.4.1) of type FRAME_SIZE_ERROR. 1532 6.5. SETTINGS 1534 The SETTINGS frame (type=0x4) conveys configuration parameters that 1535 affect how endpoints communicate, such as preferences and constraints 1536 on peer behavior. The SETTINGS frame is also used to acknowledge the 1537 receipt of those settings. Individually, a configuration parameter 1538 from a SETTINGS frame is referred to as a "setting". 1540 Settings are not negotiated; they describe characteristics of the 1541 sending peer, which are used by the receiving peer. Different values 1542 for the same setting can be advertised by each peer. For example, a 1543 client might set a high initial flow-control window, whereas a server 1544 might set a lower value to conserve resources. 1546 A SETTINGS frame MUST be sent by both endpoints at the start of a 1547 connection and MAY be sent at any other time by either endpoint over 1548 the lifetime of the connection. Implementations MUST support all of 1549 the settings defined by this specification. 1551 Each parameter in a SETTINGS frame replaces any existing value for 1552 that parameter. Settings are processed in the order in which they 1553 appear, and a receiver of a SETTINGS frame does not need to maintain 1554 any state other than the current value of each setting. Therefore, 1555 the value of a SETTINGS parameter is the last value that is seen by a 1556 receiver. 1558 SETTINGS frames are acknowledged by the receiving peer. To enable 1559 this, the SETTINGS frame defines the ACK flag: 1561 ACK (0x1): When set, the ACK flag indicates that this frame 1562 acknowledges receipt and application of the peer's SETTINGS frame. 1563 When this bit is set, the frame payload of the SETTINGS frame MUST 1564 be empty. Receipt of a SETTINGS frame with the ACK flag set and a 1565 length field value other than 0 MUST be treated as a connection 1566 error (Section 5.4.1) of type FRAME_SIZE_ERROR. For more 1567 information, see Section 6.5.3 ("Settings Synchronization"). 1569 SETTINGS frames always apply to a connection, never a single stream. 1570 The stream identifier for a SETTINGS frame MUST be zero (0x0). If an 1571 endpoint receives a SETTINGS frame whose stream identifier field is 1572 anything other than 0x0, the endpoint MUST respond with a connection 1573 error (Section 5.4.1) of type PROTOCOL_ERROR. 1575 The SETTINGS frame affects connection state. A badly formed or 1576 incomplete SETTINGS frame MUST be treated as a connection error 1577 (Section 5.4.1) of type PROTOCOL_ERROR. 1579 A SETTINGS frame with a length other than a multiple of 6 octets MUST 1580 be treated as a connection error (Section 5.4.1) of type 1581 FRAME_SIZE_ERROR. 1583 6.5.1. SETTINGS Format 1585 The frame payload of a SETTINGS frame consists of zero or more 1586 settings, each consisting of an unsigned 16-bit setting identifier 1587 and an unsigned 32-bit value. 1589 SETTINGS Frame { 1590 Length (24), 1591 Type (8) = 4, 1593 Unused Flags (7), 1594 ACK Flag (1), 1596 Reserved (1), 1597 Stream Identifier (31) = 0, 1599 Setting (48) ..., 1600 } 1602 Setting { 1603 Identifier (16), 1604 Value (32), 1605 } 1606 Figure 7: SETTINGS Frame Format 1608 6.5.2. Defined Settings 1610 The following settings are defined: 1612 SETTINGS_HEADER_TABLE_SIZE (0x1): Allows the sender to inform the 1613 remote endpoint of the maximum size of the compression table used 1614 to decode field blocks, in octets. The encoder can select any 1615 size equal to or less than this value by using signaling specific 1616 to the compression format inside a field block (see 1617 [COMPRESSION]). The initial value is 4,096 octets. 1619 SETTINGS_ENABLE_PUSH (0x2): This setting can be used to disable 1620 server push (Section 8.4). A server MUST NOT send a PUSH_PROMISE 1621 frame if it receives this parameter set to a value of 0. A client 1622 that has both set this parameter to 0 and had it acknowledged MUST 1623 treat the receipt of a PUSH_PROMISE frame as a connection error 1624 (Section 5.4.1) of type PROTOCOL_ERROR. 1626 The initial value of SETTINGS_ENABLE_PUSH is 1. For a client this 1627 value indicates that it is willing to receive PUSH_PROMISE frames. 1628 For a server this initial value has no effect, and is equivalent 1629 to the value 0. Any value other than 0 or 1 MUST be treated as a 1630 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1632 A server MUST NOT explicitly set this value to 1. A server MAY 1633 choose to omit this setting when it sends a SETTINGS frame, but if 1634 a server does include a value it MUST be 0. A client MUST treat 1635 receipt of a SETTINGS frame with SETTINGS_ENABLE_PUSH set to 1 as 1636 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1638 SETTINGS_MAX_CONCURRENT_STREAMS (0x3): Indicates the maximum number 1639 of concurrent streams that the sender will allow. This limit is 1640 directional: it applies to the number of streams that the sender 1641 permits the receiver to create. Initially, there is no limit to 1642 this value. It is recommended that this value be no smaller than 1643 100, so as to not unnecessarily limit parallelism. 1645 A value of 0 for SETTINGS_MAX_CONCURRENT_STREAMS SHOULD NOT be 1646 treated as special by endpoints. A zero value does prevent the 1647 creation of new streams; however, this can also happen for any 1648 limit that is exhausted with active streams. Servers SHOULD only 1649 set a zero value for short durations; if a server does not wish to 1650 accept requests, closing the connection is more appropriate. 1652 SETTINGS_INITIAL_WINDOW_SIZE (0x4): Indicates the sender's initial 1653 window size (in octets) for stream-level flow control. The 1654 initial value is 2^16-1 (65,535) octets. 1656 This setting affects the window size of all streams (see 1657 Section 6.9.2). 1659 Values above the maximum flow-control window size of 2^31-1 MUST 1660 be treated as a connection error (Section 5.4.1) of type 1661 FLOW_CONTROL_ERROR. 1663 SETTINGS_MAX_FRAME_SIZE (0x5): Indicates the size of the largest 1664 frame payload that the sender is willing to receive, in octets. 1666 The initial value is 2^14 (16,384) octets. The value advertised 1667 by an endpoint MUST be between this initial value and the maximum 1668 allowed frame size (2^24-1 or 16,777,215 octets), inclusive. 1669 Values outside this range MUST be treated as a connection error 1670 (Section 5.4.1) of type PROTOCOL_ERROR. 1672 SETTINGS_MAX_HEADER_LIST_SIZE (0x6): This advisory setting informs a 1673 peer of the maximum size of field section that the sender is 1674 prepared to accept, in octets. The value is based on the 1675 uncompressed size of field lines, including the length of the name 1676 and value in octets plus an overhead of 32 octets for each field 1677 line. 1679 For any given request, a lower limit than what is advertised MAY 1680 be enforced. The initial value of this setting is unlimited. 1682 An endpoint that receives a SETTINGS frame with any unknown or 1683 unsupported identifier MUST ignore that setting. 1685 6.5.3. Settings Synchronization 1687 Most values in SETTINGS benefit from or require an understanding of 1688 when the peer has received and applied the changed parameter values. 1689 In order to provide such synchronization timepoints, the recipient of 1690 a SETTINGS frame in which the ACK flag is not set MUST apply the 1691 updated settings as soon as possible upon receipt. 1693 The values in the SETTINGS frame MUST be processed in the order they 1694 appear, with no other frame processing between values. Unsupported 1695 settings MUST be ignored. Once all values have been processed, the 1696 recipient MUST immediately emit a SETTINGS frame with the ACK flag 1697 set. Upon receiving a SETTINGS frame with the ACK flag set, the 1698 sender of the altered settings can rely on the values from the oldest 1699 unacknowledged SETTINGS frame having been applied. 1701 If the sender of a SETTINGS frame does not receive an acknowledgement 1702 within a reasonable amount of time, it MAY issue a connection error 1703 (Section 5.4.1) of type SETTINGS_TIMEOUT. 1705 6.6. PUSH_PROMISE 1707 The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint 1708 in advance of streams the sender intends to initiate. The 1709 PUSH_PROMISE frame includes the unsigned 31-bit identifier of the 1710 stream the endpoint plans to create along with a field section that 1711 provides additional context for the stream. Section 8.4 contains a 1712 thorough description of the use of PUSH_PROMISE frames. 1714 PUSH_PROMISE Frame { 1715 Length (24), 1716 Type (8) = 5, 1718 Unused Flags (4), 1719 PADDED Flag (1), 1720 END_HEADERS Flag (1), 1721 Unused Flags (2), 1723 Reserved (1), 1724 Stream Identifier (31), 1726 [Pad Length (8)], 1727 Reserved (1), 1728 Promised Stream ID (31), 1729 Field Block Fragment (..), 1730 Padding (..), 1731 } 1733 Figure 8: PUSH_PROMISE Frame Format 1735 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1736 fields are described in Section 4. The PUSH_PROMISE frame payload 1737 has the following additional fields: 1739 Pad Length: An 8-bit field containing the length of the frame 1740 padding in units of octets. This field is only present if the 1741 PADDED flag is set. 1743 Reserved: A single reserved bit. 1745 Promised Stream ID: An unsigned 31-bit integer that identifies the 1746 stream that is reserved by the PUSH_PROMISE. The promised stream 1747 identifier MUST be a valid choice for the next stream sent by the 1748 sender (see "new stream identifier" in Section 5.1.1). 1750 Field Block Fragment: A field block fragment (Section 4.3) 1751 containing request control data and header section. 1753 Padding: Padding octets that contain no application semantic value. 1754 Padding octets MUST be set to zero when sending. A receiver is 1755 not obligated to verify padding but MAY treat non-zero padding as 1756 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1758 The PUSH_PROMISE frame defines the following flags: 1760 PADDED (0x8): When set, the PADDED flag indicates that the Pad 1761 Length field and any padding that it describes are present. 1763 END_HEADERS (0x4): When set, the END_HEADERS flag indicates that 1764 this frame contains an entire field block (Section 4.3) and is not 1765 followed by any CONTINUATION frames. 1767 A PUSH_PROMISE frame without the END_HEADERS flag set MUST be 1768 followed by a CONTINUATION frame for the same stream. A receiver 1769 MUST treat the receipt of any other type of frame or a frame on a 1770 different stream as a connection error (Section 5.4.1) of type 1771 PROTOCOL_ERROR. 1773 PUSH_PROMISE frames MUST only be sent on a peer-initiated stream that 1774 is in either the "open" or "half-closed (remote)" state. The stream 1775 identifier of a PUSH_PROMISE frame indicates the stream it is 1776 associated with. If the stream identifier field specifies the value 1777 0x0, a recipient MUST respond with a connection error (Section 5.4.1) 1778 of type PROTOCOL_ERROR. 1780 Promised streams are not required to be used in the order they are 1781 promised. The PUSH_PROMISE only reserves stream identifiers for 1782 later use. 1784 PUSH_PROMISE MUST NOT be sent if the SETTINGS_ENABLE_PUSH setting of 1785 the peer endpoint is set to 0. An endpoint that has set this setting 1786 and has received acknowledgement MUST treat the receipt of a 1787 PUSH_PROMISE frame as a connection error (Section 5.4.1) of type 1788 PROTOCOL_ERROR. 1790 Recipients of PUSH_PROMISE frames can choose to reject promised 1791 streams by returning a RST_STREAM referencing the promised stream 1792 identifier back to the sender of the PUSH_PROMISE. 1794 A PUSH_PROMISE frame modifies the connection state in two ways. 1795 First, the inclusion of a field block (Section 4.3) potentially 1796 modifies the state maintained for field section compression. Second, 1797 PUSH_PROMISE also reserves a stream for later use, causing the 1798 promised stream to enter the "reserved" state. A sender MUST NOT 1799 send a PUSH_PROMISE on a stream unless that stream is either "open" 1800 or "half-closed (remote)"; the sender MUST ensure that the promised 1801 stream is a valid choice for a new stream identifier (Section 5.1.1) 1802 (that is, the promised stream MUST be in the "idle" state). 1804 Since PUSH_PROMISE reserves a stream, ignoring a PUSH_PROMISE frame 1805 causes the stream state to become indeterminate. A receiver MUST 1806 treat the receipt of a PUSH_PROMISE on a stream that is neither 1807 "open" nor "half-closed (local)" as a connection error 1808 (Section 5.4.1) of type PROTOCOL_ERROR. However, an endpoint that 1809 has sent RST_STREAM on the associated stream MUST handle PUSH_PROMISE 1810 frames that might have been created before the RST_STREAM frame is 1811 received and processed. 1813 A receiver MUST treat the receipt of a PUSH_PROMISE that promises an 1814 illegal stream identifier (Section 5.1.1) as a connection error 1815 (Section 5.4.1) of type PROTOCOL_ERROR. Note that an illegal stream 1816 identifier is an identifier for a stream that is not currently in the 1817 "idle" state. 1819 The total number of padding octets is determined by the value of the 1820 Pad Length field. If the length of the padding is the length of the 1821 frame payload or greater, the recipient MUST treat this as a 1822 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1824 | Note: A frame can be increased in size by one octet by 1825 | including a Pad Length field with a value of zero. 1827 6.7. PING 1829 The PING frame (type=0x6) is a mechanism for measuring a minimal 1830 round-trip time from the sender, as well as determining whether an 1831 idle connection is still functional. PING frames can be sent from 1832 any endpoint. 1834 PING Frame { 1835 Length (24), 1836 Type (8) = 6, 1838 Unused Flags (7), 1839 ACK Flag (1), 1841 Reserved (1), 1842 Stream Identifier (31) = 0, 1844 Opaque Data (64), 1845 } 1846 Figure 9: PING Frame Format 1848 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1849 fields are described in Section 4. 1851 In addition to the frame header, PING frames MUST contain 8 octets of 1852 opaque data in the frame payload. A sender can include any value it 1853 chooses and use those octets in any fashion. 1855 Receivers of a PING frame that does not include an ACK flag MUST send 1856 a PING frame with the ACK flag set in response, with an identical 1857 frame payload. PING responses SHOULD be given higher priority than 1858 any other frame. 1860 The PING frame defines the following flags: 1862 ACK (0x1): When set, the ACK flag indicates that this PING frame is 1863 a PING response. An endpoint MUST set this flag in PING 1864 responses. An endpoint MUST NOT respond to PING frames containing 1865 this flag. 1867 PING frames are not associated with any individual stream. If a PING 1868 frame is received with a stream identifier field value other than 1869 0x0, the recipient MUST respond with a connection error 1870 (Section 5.4.1) of type PROTOCOL_ERROR. 1872 Receipt of a PING frame with a length field value other than 8 MUST 1873 be treated as a connection error (Section 5.4.1) of type 1874 FRAME_SIZE_ERROR. 1876 6.8. GOAWAY 1878 The GOAWAY frame (type=0x7) is used to initiate shutdown of a 1879 connection or to signal serious error conditions. GOAWAY allows an 1880 endpoint to gracefully stop accepting new streams while still 1881 finishing processing of previously established streams. This enables 1882 administrative actions, like server maintenance. 1884 There is an inherent race condition between an endpoint starting new 1885 streams and the remote sending a GOAWAY frame. To deal with this 1886 case, the GOAWAY contains the stream identifier of the last peer- 1887 initiated stream that was or might be processed on the sending 1888 endpoint in this connection. For instance, if the server sends a 1889 GOAWAY frame, the identified stream is the highest-numbered stream 1890 initiated by the client. 1892 Once sent, the sender will ignore frames sent on streams initiated by 1893 the receiver if the stream has an identifier higher than the included 1894 last stream identifier. Receivers of a GOAWAY frame MUST NOT open 1895 additional streams on the connection, although a new connection can 1896 be established for new streams. 1898 If the receiver of the GOAWAY has sent data on streams with a higher 1899 stream identifier than what is indicated in the GOAWAY frame, those 1900 streams are not or will not be processed. The receiver of the GOAWAY 1901 frame can treat the streams as though they had never been created at 1902 all, thereby allowing those streams to be retried later on a new 1903 connection. 1905 Endpoints SHOULD always send a GOAWAY frame before closing a 1906 connection so that the remote peer can know whether a stream has been 1907 partially processed or not. For example, if an HTTP client sends a 1908 POST at the same time that a server closes a connection, the client 1909 cannot know if the server started to process that POST request if the 1910 server does not send a GOAWAY frame to indicate what streams it might 1911 have acted on. 1913 An endpoint might choose to close a connection without sending a 1914 GOAWAY for misbehaving peers. 1916 A GOAWAY frame might not immediately precede closing of the 1917 connection; a receiver of a GOAWAY that has no more use for the 1918 connection SHOULD still send a GOAWAY frame before terminating the 1919 connection. 1921 GOAWAY Frame { 1922 Length (24), 1923 Type (8) = 7, 1925 Unused Flags (8), 1927 Reserved (1), 1928 Stream Identifier (31) = 0, 1930 Reserved (1), 1931 Last-Stream-ID (31), 1932 Error Code (32), 1933 Additional Debug Data (..), 1934 } 1936 Figure 10: GOAWAY Frame Format 1938 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1939 fields are described in Section 4. 1941 The GOAWAY frame does not define any flags. 1943 The GOAWAY frame applies to the connection, not a specific stream. 1944 An endpoint MUST treat a GOAWAY frame with a stream identifier other 1945 than 0x0 as a connection error (Section 5.4.1) of type 1946 PROTOCOL_ERROR. 1948 The last stream identifier in the GOAWAY frame contains the highest- 1949 numbered stream identifier for which the sender of the GOAWAY frame 1950 might have taken some action on or might yet take action on. All 1951 streams up to and including the identified stream might have been 1952 processed in some way. The last stream identifier can be set to 0 if 1953 no streams were processed. 1955 | Note: In this context, "processed" means that some data from 1956 | the stream was passed to some higher layer of software that 1957 | might have taken some action as a result. 1959 If a connection terminates without a GOAWAY frame, the last stream 1960 identifier is effectively the highest possible stream identifier. 1962 On streams with lower- or equal-numbered identifiers that were not 1963 closed completely prior to the connection being closed, reattempting 1964 requests, transactions, or any protocol activity is not possible, 1965 with the exception of idempotent actions like HTTP GET, PUT, or 1966 DELETE. Any protocol activity that uses higher-numbered streams can 1967 be safely retried using a new connection. 1969 Activity on streams numbered lower or equal to the last stream 1970 identifier might still complete successfully. The sender of a GOAWAY 1971 frame might gracefully shut down a connection by sending a GOAWAY 1972 frame, maintaining the connection in an "open" state until all in- 1973 progress streams complete. 1975 An endpoint MAY send multiple GOAWAY frames if circumstances change. 1976 For instance, an endpoint that sends GOAWAY with NO_ERROR during 1977 graceful shutdown could subsequently encounter a condition that 1978 requires immediate termination of the connection. The last stream 1979 identifier from the last GOAWAY frame received indicates which 1980 streams could have been acted upon. Endpoints MUST NOT increase the 1981 value they send in the last stream identifier, since the peers might 1982 already have retried unprocessed requests on another connection. 1984 A client that is unable to retry requests loses all requests that are 1985 in flight when the server closes the connection. This is especially 1986 true for intermediaries that might not be serving clients using 1987 HTTP/2. A server that is attempting to gracefully shut down a 1988 connection SHOULD send an initial GOAWAY frame with the last stream 1989 identifier set to 2^31-1 and a NO_ERROR code. This signals to the 1990 client that a shutdown is imminent and that initiating further 1991 requests is prohibited. After allowing time for any in-flight stream 1992 creation (at least one round-trip time), the server can send another 1993 GOAWAY frame with an updated last stream identifier. This ensures 1994 that a connection can be cleanly shut down without losing requests. 1996 After sending a GOAWAY frame, the sender can discard frames for 1997 streams initiated by the receiver with identifiers higher than the 1998 identified last stream. However, any frames that alter connection 1999 state cannot be completely ignored. For instance, HEADERS, 2000 PUSH_PROMISE, and CONTINUATION frames MUST be minimally processed to 2001 ensure the state maintained for field section compression is 2002 consistent (see Section 4.3); similarly, DATA frames MUST be counted 2003 toward the connection flow-control window. Failure to process these 2004 frames can cause flow control or field section compression state to 2005 become unsynchronized. 2007 The GOAWAY frame also contains a 32-bit error code (Section 7) that 2008 contains the reason for closing the connection. 2010 Endpoints MAY append opaque data to the frame payload of any GOAWAY 2011 frame. Additional debug data is intended for diagnostic purposes 2012 only and carries no semantic value. Debug information could contain 2013 security- or privacy-sensitive data. Logged or otherwise 2014 persistently stored debug data MUST have adequate safeguards to 2015 prevent unauthorized access. 2017 6.9. WINDOW_UPDATE 2019 The WINDOW_UPDATE frame (type=0x8) is used to implement flow control; 2020 see Section 5.2 for an overview. 2022 Flow control operates at two levels: on each individual stream and on 2023 the entire connection. 2025 Both types of flow control are hop by hop, that is, only between the 2026 two endpoints. Intermediaries do not forward WINDOW_UPDATE frames 2027 between dependent connections. However, throttling of data transfer 2028 by any receiver can indirectly cause the propagation of flow-control 2029 information toward the original sender. 2031 Flow control only applies to frames that are identified as being 2032 subject to flow control. Of the frame types defined in this 2033 document, this includes only DATA frames. Frames that are exempt 2034 from flow control MUST be accepted and processed, unless the receiver 2035 is unable to assign resources to handling the frame. A receiver MAY 2036 respond with a stream error (Section 5.4.2) or connection error 2037 (Section 5.4.1) of type FLOW_CONTROL_ERROR if it is unable to accept 2038 a frame. 2040 WINDOW_UPDATE Frame { 2041 Length (24), 2042 Type (8) = 8, 2044 Unused Flags (8), 2046 Reserved (1), 2047 Stream Identifier (31), 2049 Reserved (1), 2050 Window Size Increment (31), 2051 } 2053 Figure 11: WINDOW_UPDATE Frame Format 2055 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 2056 fields are described in Section 4. The frame payload of a 2057 WINDOW_UPDATE frame is one reserved bit plus an unsigned 31-bit 2058 integer indicating the number of octets that the sender can transmit 2059 in addition to the existing flow-control window. The legal range for 2060 the increment to the flow-control window is 1 to 2^31-1 2061 (2,147,483,647) octets. 2063 The WINDOW_UPDATE frame does not define any flags. 2065 The WINDOW_UPDATE frame can be specific to a stream or to the entire 2066 connection. In the former case, the frame's stream identifier 2067 indicates the affected stream; in the latter, the value "0" indicates 2068 that the entire connection is the subject of the frame. 2070 A receiver MUST treat the receipt of a WINDOW_UPDATE frame with a 2071 flow-control window increment of 0 as a stream error (Section 5.4.2) 2072 of type PROTOCOL_ERROR; errors on the connection flow-control window 2073 MUST be treated as a connection error (Section 5.4.1). 2075 WINDOW_UPDATE can be sent by a peer that has sent a frame with the 2076 END_STREAM flag set. This means that a receiver could receive a 2077 WINDOW_UPDATE frame on a "half-closed (remote)" or "closed" stream. 2078 A receiver MUST NOT treat this as an error (see Section 5.1). 2080 A receiver that receives a flow-controlled frame MUST always account 2081 for its contribution against the connection flow-control window, 2082 unless the receiver treats this as a connection error 2083 (Section 5.4.1). This is necessary even if the frame is in error. 2084 The sender counts the frame toward the flow-control window, but if 2085 the receiver does not, the flow-control window at the sender and 2086 receiver can become different. 2088 A WINDOW_UPDATE frame with a length other than 4 octets MUST be 2089 treated as a connection error (Section 5.4.1) of type 2090 FRAME_SIZE_ERROR. 2092 6.9.1. The Flow-Control Window 2094 Flow control in HTTP/2 is implemented using a window kept by each 2095 sender on every stream. The flow-control window is a simple integer 2096 value that indicates how many octets of data the sender is permitted 2097 to transmit; as such, its size is a measure of the buffering capacity 2098 of the receiver. 2100 Two flow-control windows are applicable: the stream flow-control 2101 window and the connection flow-control window. The sender MUST NOT 2102 send a flow-controlled frame with a length that exceeds the space 2103 available in either of the flow-control windows advertised by the 2104 receiver. Frames with zero length with the END_STREAM flag set (that 2105 is, an empty DATA frame) MAY be sent if there is no available space 2106 in either flow-control window. 2108 For flow-control calculations, the 9-octet frame header is not 2109 counted. 2111 After sending a flow-controlled frame, the sender reduces the space 2112 available in both windows by the length of the transmitted frame. 2114 The receiver of a frame sends a WINDOW_UPDATE frame as it consumes 2115 data and frees up space in flow-control windows. Separate 2116 WINDOW_UPDATE frames are sent for the stream- and connection-level 2117 flow-control windows. 2119 A sender that receives a WINDOW_UPDATE frame updates the 2120 corresponding window by the amount specified in the frame. 2122 A sender MUST NOT allow a flow-control window to exceed 2^31-1 2123 octets. If a sender receives a WINDOW_UPDATE that causes a flow- 2124 control window to exceed this maximum, it MUST terminate either the 2125 stream or the connection, as appropriate. For streams, the sender 2126 sends a RST_STREAM with an error code of FLOW_CONTROL_ERROR; for the 2127 connection, a GOAWAY frame with an error code of FLOW_CONTROL_ERROR 2128 is sent. 2130 Flow-controlled frames from the sender and WINDOW_UPDATE frames from 2131 the receiver are completely asynchronous with respect to each other. 2132 This property allows a receiver to aggressively update the window 2133 size kept by the sender to prevent streams from stalling. 2135 6.9.2. Initial Flow-Control Window Size 2137 When an HTTP/2 connection is first established, new streams are 2138 created with an initial flow-control window size of 65,535 octets. 2139 The connection flow-control window is also 65,535 octets. Both 2140 endpoints can adjust the initial window size for new streams by 2141 including a value for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS 2142 frame that forms part of the connection preface. The connection 2143 flow-control window can only be changed using WINDOW_UPDATE frames. 2145 Prior to receiving a SETTINGS frame that sets a value for 2146 SETTINGS_INITIAL_WINDOW_SIZE, an endpoint can only use the default 2147 initial window size when sending flow-controlled frames. Similarly, 2148 the connection flow-control window is set to the default initial 2149 window size until a WINDOW_UPDATE frame is received. 2151 In addition to changing the flow-control window for streams that are 2152 not yet active, a SETTINGS frame can alter the initial flow-control 2153 window size for streams with active flow-control windows (that is, 2154 streams in the "open" or "half-closed (remote)" state). When the 2155 value of SETTINGS_INITIAL_WINDOW_SIZE changes, a receiver MUST adjust 2156 the size of all stream flow-control windows that it maintains by the 2157 difference between the new value and the old value. 2159 A change to SETTINGS_INITIAL_WINDOW_SIZE can cause the available 2160 space in a flow-control window to become negative. A sender MUST 2161 track the negative flow-control window and MUST NOT send new flow- 2162 controlled frames until it receives WINDOW_UPDATE frames that cause 2163 the flow-control window to become positive. 2165 For example, if the client sends 60 KB immediately on connection 2166 establishment and the server sets the initial window size to be 16 2167 KB, the client will recalculate the available flow-control window to 2168 be -44 KB on receipt of the SETTINGS frame. The client retains a 2169 negative flow-control window until WINDOW_UPDATE frames restore the 2170 window to being positive, after which the client can resume sending. 2172 A SETTINGS frame cannot alter the connection flow-control window. 2174 An endpoint MUST treat a change to SETTINGS_INITIAL_WINDOW_SIZE that 2175 causes any flow-control window to exceed the maximum size as a 2176 connection error (Section 5.4.1) of type FLOW_CONTROL_ERROR. 2178 6.9.3. Reducing the Stream Window Size 2180 A receiver that wishes to use a smaller flow-control window than the 2181 current size can send a new SETTINGS frame. However, the receiver 2182 MUST be prepared to receive data that exceeds this window size, since 2183 the sender might send data that exceeds the lower limit prior to 2184 processing the SETTINGS frame. 2186 After sending a SETTINGS frame that reduces the initial flow-control 2187 window size, a receiver MAY continue to process streams that exceed 2188 flow-control limits. Allowing streams to continue does not allow the 2189 receiver to immediately reduce the space it reserves for flow-control 2190 windows. Progress on these streams can also stall, since 2191 WINDOW_UPDATE frames are needed to allow the sender to resume 2192 sending. The receiver MAY instead send a RST_STREAM with an error 2193 code of FLOW_CONTROL_ERROR for the affected streams. 2195 6.10. CONTINUATION 2197 The CONTINUATION frame (type=0x9) is used to continue a sequence of 2198 field block fragments (Section 4.3). Any number of CONTINUATION 2199 frames can be sent, as long as the preceding frame is on the same 2200 stream and is a HEADERS, PUSH_PROMISE, or CONTINUATION frame without 2201 the END_HEADERS flag set. 2203 CONTINUATION Frame { 2204 Length (24), 2205 Type (8) = 9, 2207 Unused Flags (5), 2208 END_HEADERS Flag (1), 2209 Unused Flags (2), 2211 Reserved (1), 2212 Stream Identifier (31), 2214 Field Block Fragment (..), 2215 } 2217 Figure 12: CONTINUATION Frame Format 2219 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 2220 fields are described in Section 4. The CONTINUATION frame payload 2221 contains a field block fragment (Section 4.3). 2223 The CONTINUATION frame defines the following flag: 2225 END_HEADERS (0x4): When set, the END_HEADERS flag indicates that 2226 this frame ends a field block (Section 4.3). 2228 If the END_HEADERS flag is not set, this frame MUST be followed by 2229 another CONTINUATION frame. A receiver MUST treat the receipt of 2230 any other type of frame or a frame on a different stream as a 2231 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 2233 The CONTINUATION frame changes the connection state as defined in 2234 Section 4.3. 2236 CONTINUATION frames MUST be associated with a stream. If a 2237 CONTINUATION frame is received whose stream identifier field is 0x0, 2238 the recipient MUST respond with a connection error (Section 5.4.1) of 2239 type PROTOCOL_ERROR. 2241 A CONTINUATION frame MUST be preceded by a HEADERS, PUSH_PROMISE or 2242 CONTINUATION frame without the END_HEADERS flag set. A recipient 2243 that observes violation of this rule MUST respond with a connection 2244 error (Section 5.4.1) of type PROTOCOL_ERROR. 2246 7. Error Codes 2248 Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY 2249 frames to convey the reasons for the stream or connection error. 2251 Error codes share a common code space. Some error codes apply only 2252 to either streams or the entire connection and have no defined 2253 semantics in the other context. 2255 The following error codes are defined: 2257 NO_ERROR (0x0): The associated condition is not a result of an 2258 error. For example, a GOAWAY might include this code to indicate 2259 graceful shutdown of a connection. 2261 PROTOCOL_ERROR (0x1): The endpoint detected an unspecific protocol 2262 error. This error is for use when a more specific error code is 2263 not available. 2265 INTERNAL_ERROR (0x2): The endpoint encountered an unexpected 2266 internal error. 2268 FLOW_CONTROL_ERROR (0x3): The endpoint detected that its peer 2269 violated the flow-control protocol. 2271 SETTINGS_TIMEOUT (0x4): The endpoint sent a SETTINGS frame but did 2272 not receive a response in a timely manner. See Section 6.5.3 2273 ("Settings Synchronization"). 2275 STREAM_CLOSED (0x5): The endpoint received a frame after a stream 2276 was half-closed. 2278 FRAME_SIZE_ERROR (0x6): The endpoint received a frame with an 2279 invalid size. 2281 REFUSED_STREAM (0x7): The endpoint refused the stream prior to 2282 performing any application processing (see Section 8.7 for 2283 details). 2285 CANCEL (0x8): Used by the endpoint to indicate that the stream is no 2286 longer needed. 2288 COMPRESSION_ERROR (0x9): The endpoint is unable to maintain the 2289 field section compression context for the connection. 2291 CONNECT_ERROR (0xa): The connection established in response to a 2292 CONNECT request (Section 8.5) was reset or abnormally closed. 2294 ENHANCE_YOUR_CALM (0xb): The endpoint detected that its peer is 2295 exhibiting a behavior that might be generating excessive load. 2297 INADEQUATE_SECURITY (0xc): The underlying transport has properties 2298 that do not meet minimum security requirements (see Section 9.2). 2300 HTTP_1_1_REQUIRED (0xd): The endpoint requires that HTTP/1.1 be used 2301 instead of HTTP/2. 2303 Unknown or unsupported error codes MUST NOT trigger any special 2304 behavior. These MAY be treated by an implementation as being 2305 equivalent to INTERNAL_ERROR. 2307 8. Expressing HTTP Semantics in HTTP/2 2309 HTTP/2 is an instantiation of the HTTP message abstraction (Section 6 2310 of [HTTP]). 2312 8.1. HTTP Message Framing 2314 A client sends an HTTP request on a new stream, using a previously 2315 unused stream identifier (Section 5.1.1). A server sends an HTTP 2316 response on the same stream as the request. 2318 An HTTP message (request or response) consists of: 2320 1. one HEADERS frame (followed by zero or more CONTINUATION frames) 2321 containing the header section (see Section 6.3 of [HTTP]), 2323 2. zero or more DATA frames containing the message content (see 2324 Section 6.4 of [HTTP]), and 2326 3. optionally, one HEADERS frame (followed by zero or more 2327 CONTINUATION frames) containing the trailer section, if present 2328 (see Section 6.5 of [HTTP]). 2330 For a response only, a server MAY send any number of interim 2331 responses before the HEADERS frame containing a final response. An 2332 interim response consists of a HEADERS frame (which might be followed 2333 by zero or more CONTINUATION frames) containing the control data and 2334 header section of an interim (1xx) HTTP response (see Section 15 of 2335 [HTTP]). A HEADERS frame with the END_STREAM flag set that carries 2336 an informational status code is malformed (Section 8.1.1). 2338 The last frame in the sequence bears an END_STREAM flag, noting that 2339 a HEADERS frame with the END_STREAM flag set can be followed by 2340 CONTINUATION frames that carry any remaining fragments of the field 2341 block. 2343 Other frames (from any stream) MUST NOT occur between the HEADERS 2344 frame and any CONTINUATION frames that might follow. 2346 HTTP/2 uses DATA frames to carry message content. The chunked 2347 transfer encoding defined in Section 7.1 of [HTTP11] cannot be used 2348 in HTTP/2; see Section 8.2.2. 2350 Trailer fields are carried in a field block that also terminates the 2351 stream. That is, trailer fields comprise a sequence starting with a 2352 HEADERS frame, followed by zero or more CONTINUATION frames, where 2353 the HEADERS frame bears an END_STREAM flag. Trailers MUST NOT 2354 include pseudo-header fields (Section 8.3). An endpoint that 2355 receives pseudo-header fields in trailers MUST treat the request or 2356 response as malformed (Section 8.1.1). 2358 An endpoint that receives a HEADERS frame without the END_STREAM flag 2359 set after receiving the HEADERS frame that opens a request or after 2360 receiving a final (non-informational) status code MUST treat the 2361 corresponding request or response as malformed (Section 8.1.1). 2363 An HTTP request/response exchange fully consumes a single stream. A 2364 request starts with the HEADERS frame that puts the stream into the 2365 "open" state. The request ends with a frame with the END_STREAM flag 2366 set, which causes the stream to become "half-closed (local)" for the 2367 client and "half-closed (remote)" for the server. A response stream 2368 starts with zero or more interim responses in HEADERS frames, 2369 followed by a HEADERS frame containing a final status code. 2371 An HTTP response is complete after the server sends -- or the client 2372 receives -- a frame with the END_STREAM flag set (including any 2373 CONTINUATION frames needed to complete a field block). A server can 2374 send a complete response prior to the client sending an entire 2375 request if the response does not depend on any portion of the request 2376 that has not been sent and received. When this is true, a server MAY 2377 request that the client abort transmission of a request without error 2378 by sending a RST_STREAM with an error code of NO_ERROR after sending 2379 a complete response (i.e., a frame with the END_STREAM flag set). 2380 Clients MUST NOT discard responses as a result of receiving such a 2381 RST_STREAM, though clients can always discard responses at their 2382 discretion for other reasons. 2384 8.1.1. Malformed Messages 2386 A malformed request or response is one that is an otherwise valid 2387 sequence of HTTP/2 frames but is invalid due to the presence of 2388 extraneous frames, prohibited fields or pseudo-header fields, the 2389 absence of mandatory pseudo-header fields, the inclusion of uppercase 2390 field names, or invalid field names and/or values (in certain 2391 circumstances; see Section 8.2). 2393 A request or response that includes message content can include a 2394 content-length header field. A request or response is also malformed 2395 if the value of a content-length header field does not equal the sum 2396 of the DATA frame payload lengths that form the content. A response 2397 that is defined to have no content, as described in Section 6.4 of 2398 [HTTP], can have a non-zero content-length header field, even though 2399 no content is included in DATA frames. 2401 Intermediaries that process HTTP requests or responses (i.e., any 2402 intermediary not acting as a tunnel) MUST NOT forward a malformed 2403 request or response. Malformed requests or responses that are 2404 detected MUST be treated as a stream error (Section 5.4.2) of type 2405 PROTOCOL_ERROR. 2407 For malformed requests, a server MAY send an HTTP response prior to 2408 closing or resetting the stream. Clients MUST NOT accept a malformed 2409 response. 2411 Endpoints that progressively process messages might have performed 2412 some processing before identifying a request or response as 2413 malformed. For instance, it might be possible to generate an 2414 informational or 404 status code without having received a complete 2415 request. Similarly, intermediaries might forward incomplete messages 2416 before detecting errors. A server MAY generate a final response 2417 before receiving an entire request when the response does not depend 2418 on the remainder of the request being correct. 2420 These requirements are intended to protect against several types of 2421 common attacks against HTTP; they are deliberately strict because 2422 being permissive can expose implementations to these vulnerabilities. 2424 8.2. HTTP Fields 2426 HTTP fields (Section 5 of [HTTP]) are conveyed by HTTP/2 in the 2427 HEADERS, CONTINUATION, and PUSH_PROMISE frames, compressed with HPACK 2428 [COMPRESSION]. 2430 Field names MUST be converted to lowercase when constructing an 2431 HTTP/2 message. 2433 8.2.1. Field Validity 2435 The definitions of field names and values in HTTP prohibits some 2436 characters that HPACK might be able to convey. HTTP/2 2437 implementations SHOULD validate field names and values according to 2438 their definitions in Sections 5.1 and 5.5 of [HTTP] respectively and 2439 treat messages that contain prohibited characters as malformed 2440 (Section 8.1.1). 2442 Failure to validate fields can be exploited for request smuggling 2443 attacks. In particular, unvalidated fields might enable attacks when 2444 messages are forwarded using HTTP 1.1 [HTTP11], where characters such 2445 as CR, LF, and COLON are used as delimiters. Implementations MUST 2446 perform the following minimal validation of field names and values: 2448 * A field name MUST NOT contain characters in the ranges 0x00-0x20, 2449 0x41-0x5a, or 0x7f-0xff (all ranges inclusive). This specifically 2450 excludes all non-visible ASCII characters, ASCII SP (0x20), and 2451 uppercase characters ('A' to 'Z', ASCII 0x41 to 0x5a). 2453 * With the exception of pseudo-header fields (Section 8.3), which 2454 have a name that starts with a single colon, field names MUST NOT 2455 include a colon (ASCII COLON, 0x3a). 2457 * A field value MUST NOT contain the zero value (ASCII NUL, 0x0), 2458 line feed (ASCII LF, 0xa), or carriage return (ASCII CR, 0xd) at 2459 any position. 2461 * A field value MUST NOT start or end with an ASCII whitespace 2462 character (ASCII SP or HTAB, 0x20 or 0x9). 2464 | Note: An implementation that validates fields according the 2465 | definitions in Sections 5.1 and 5.5 of [HTTP] only needs an 2466 | additional check that field names do not include uppercase 2467 | characters. 2469 A request or response that contains a field that violates any of 2470 these conditions MUST be treated as malformed (Section 8.1.1). In 2471 particular, an intermediary that does not process fields when 2472 forwarding messages MUST NOT forward fields that contain any of the 2473 values that are listed as prohibited above. 2475 When a request message violates one of these requirements, an 2476 implementation SHOULD generate a Section 15.5.1 of 400 (Bad Request) 2477 status code [HTTP], unless a more suitable status code is defined or 2478 the status code cannot be sent (e.g., because the error occurs in a 2479 trailer field). 2481 | Note: Field values that are not valid according to the 2482 | definition of the corresponding field do not cause a request to 2483 | be malformed; the requirements above only apply to the generic 2484 | syntax for fields as defined in Section 5 of [HTTP]. 2486 8.2.2. Connection-Specific Header Fields 2488 HTTP/2 does not use the Connection header field (Section 7.6.1 of 2489 [HTTP]) to indicate connection-specific header fields; in this 2490 protocol, connection-specific metadata is conveyed by other means. 2491 An endpoint MUST NOT generate an HTTP/2 message containing 2492 connection-specific header fields. This includes the Connection 2493 header field and those listed as having connection-specific semantics 2494 in Section 7.6.1 of [HTTP] (that is, Proxy-Connection, Keep-Alive, 2495 Transfer-Encoding, and Upgrade). Any message containing connection- 2496 specific header fields MUST be treated as malformed (Section 8.1.1). 2498 The only exception to this is the TE header field, which MAY be 2499 present in an HTTP/2 request; when it is, it MUST NOT contain any 2500 value other than "trailers". 2502 An intermediary transforming a HTTP/1.x message to HTTP/2 MUST remove 2503 connection-specific header fields as discussed in Section 7.6.1 of 2504 [HTTP], or their messages will be treated by other HTTP/2 endpoints 2505 as malformed (Section 8.1.1). 2507 | Note: HTTP/2 purposefully does not support upgrade to another 2508 | protocol. The handshake methods described in Section 3 are 2509 | believed sufficient to negotiate the use of alternative 2510 | protocols. 2512 8.2.3. Compressing the Cookie Header Field 2514 The Cookie header field [COOKIE] uses a semi-colon (";") to delimit 2515 cookie-pairs (or "crumbs"). This header field contains multiple 2516 values, but does not use a COMMA (",") as a separator, which prevents 2517 cookie-pairs from being sent on multiple field lines (see Section 5.2 2518 of [HTTP]). This can significantly reduce compression efficiency as 2519 updates to individual cookie-pairs would invalidate any field lines 2520 that are stored in the HPACK table. 2522 To allow for better compression efficiency, the Cookie header field 2523 MAY be split into separate header fields, each with one or more 2524 cookie-pairs. If there are multiple Cookie header fields after 2525 decompression, these MUST be concatenated into a single octet string 2526 using the two-octet delimiter of 0x3b, 0x20 (the ASCII string "; ") 2527 before being passed into a non-HTTP/2 context, such as an HTTP/1.1 2528 connection, or a generic HTTP server application. 2530 Therefore, the following two lists of Cookie header fields are 2531 semantically equivalent. 2533 cookie: a=b; c=d; e=f 2535 cookie: a=b 2536 cookie: c=d 2537 cookie: e=f 2539 8.3. HTTP Control Data 2541 HTTP/2 uses special pseudo-header fields beginning with ':' character 2542 (ASCII 0x3a) to convey message control data (see Section 6.2 of 2543 [HTTP]). 2545 Pseudo-header fields are not HTTP header fields. Endpoints MUST NOT 2546 generate pseudo-header fields other than those defined in this 2547 document. Note that an extension could negotiate the use of 2548 additional pseudo-header fields; see Section 5.5. 2550 Pseudo-header fields are only valid in the context in which they are 2551 defined. Pseudo-header fields defined for requests MUST NOT appear 2552 in responses; pseudo-header fields defined for responses MUST NOT 2553 appear in requests. Pseudo-header fields MUST NOT appear in a 2554 trailer section. Endpoints MUST treat a request or response that 2555 contains undefined or invalid pseudo-header fields as malformed 2556 (Section 8.1.1). 2558 All pseudo-header fields MUST appear in a field block before all 2559 regular field lines. Any request or response that contains a pseudo- 2560 header field that appears in a field block after a regular field line 2561 MUST be treated as malformed (Section 8.1.1). 2563 The same pseudo-header field name MUST NOT appear more than once in a 2564 field block. A field block for an HTTP request or response that 2565 contains a repeated pseudo-header field name MUST be treated as 2566 malformed (Section 8.1.1). 2568 8.3.1. Request Pseudo-Header Fields 2570 The following pseudo-header fields are defined for HTTP/2 requests: 2572 * The :method pseudo-header field includes the HTTP method 2573 (Section 9 of [HTTP]). 2575 * The :scheme pseudo-header field includes the scheme portion of the 2576 request target. The scheme is taken from the target URI 2577 (Section 3.1 of [RFC3986]) when generating a request directly, or 2578 from the scheme of a translated request (for example, see 2579 Section 3.3 of [HTTP11]). Scheme is omitted for CONNECT requests 2580 (Section 8.5). 2582 :scheme is not restricted to http and https schemed URIs. A proxy 2583 or gateway can translate requests for non-HTTP schemes, enabling 2584 the use of HTTP to interact with non-HTTP services. 2586 * The :authority pseudo-header field conveys the authority portion 2587 (Section 3.2 of [RFC3986]) of the target URI (Section 7.1 of 2588 [HTTP]). The recipient of a HTTP/2 request MUST ignore the Host 2589 header field if :authority is present. 2591 Clients that generate HTTP/2 requests directly MUST use the 2592 :authority pseudo-header field to convey authority information, 2593 unless there is no authority information to convey (in which case 2594 it MUST NOT generate :authority). 2596 Clients MUST NOT generate a request with a Host header field that 2597 differs from the :authority pseudo-header field. A server SHOULD 2598 treat a request as malformed if it contains a Host header field 2599 that identifies a different entity to the :authority pseudo-header 2600 field. The values of fields need to be normalized to compare them 2601 (see Section 6.2 of [RFC3986]). An origin server can apply any 2602 normalization method, whereas other servers MUST perform scheme- 2603 based normalization (see Section 6.2.3 of [RFC3986]) of the two 2604 fields. 2606 An intermediary that forwards a request over HTTP/2 MUST construct 2607 an :authority pseudo-header field using the authority information 2608 from the control data of the original request, unless the original 2609 request's target URI does not contain authority information (in 2610 which case it MUST NOT generate :authority). Note that the Host 2611 header field is not the sole source of this information; see 2612 Section 7.2 of [HTTP]. 2614 An intermediary that needs to generate a Host header field (which 2615 might be necessary to construct an HTTP/1.1 request) MUST use the 2616 value from the :authority pseudo-header field as the value of the 2617 Host field, unless the intermediary also changes the request 2618 target. This replaces any existing Host field to avoid potential 2619 vulnerabilities in HTTP routing. 2621 An intermediary that forwards a request over HTTP/2 MAY retain any 2622 Host header field. 2624 Note that request targets for CONNECT or asterisk-form OPTIONS 2625 requests never include authority information; see Section 7.1 of 2626 [HTTP]. 2628 :authority MUST NOT include the deprecated userinfo subcomponent 2629 for http or https schemed URIs. 2631 * The :path pseudo-header field includes the path and query parts of 2632 the target URI (the absolute-path production and optionally a '?' 2633 character followed by the query production; see Section 4.1 of 2634 [HTTP]). A request in asterisk form (for OPTIONS) includes the 2635 value '*' for the :path pseudo-header field. 2637 This pseudo-header field MUST NOT be empty for http or https URIs; 2638 http or https URIs that do not contain a path component MUST 2639 include a value of '/'. The exceptions to this rule are: 2641 - an OPTIONS request for an http or https URI that does not 2642 include a path component; these MUST include a :path pseudo- 2643 header field with a value of '*' (see Section 7.1 of [HTTP]) 2645 - CONNECT requests (Section 8.5), where the :path pseudo-header 2646 field is omitted. 2648 All HTTP/2 requests MUST include exactly one valid value for the 2649 :method, :scheme, and :path pseudo-header fields, unless it is a 2650 CONNECT request (Section 8.5). An HTTP request that omits mandatory 2651 pseudo-header fields is malformed (Section 8.1.1). 2653 Individual HTTP/2 requests do not carry an explicit indicator of 2654 protocol version. All HTTP/2 requests implicitly have a protocol 2655 version of "2.0" (see Section 6.2 of [HTTP]). 2657 8.3.2. Response Pseudo-Header Fields 2659 For HTTP/2 responses, a single :status pseudo-header field is defined 2660 that carries the HTTP status code field (see Section 15 of [HTTP]). 2661 This pseudo-header field MUST be included in all responses, including 2662 interim responses; otherwise, the response is malformed 2663 (Section 8.1.1). 2665 HTTP/2 responses implicitly have a protocol version of "2.0". 2667 8.4. Server Push 2669 HTTP/2 allows a server to pre-emptively send (or "push") responses 2670 (along with corresponding "promised" requests) to a client in 2671 association with a previous client-initiated request. 2673 Server push was designed to allow a server to improve client- 2674 perceived performance by predicting what requests will follow those 2675 that it receives, thereby removing a round trip for them. For 2676 example, a request for HTML is often followed by requests for 2677 stylesheets and scripts referenced by that page. When these requests 2678 are pushed, the client does not need to wait to receive the 2679 references to them in the HTML and issue separate requests. 2681 In practice, server push is difficult to use effectively, because it 2682 requires the server to correctly anticipate the additional requests 2683 the client will make, taking into account factors such as caching, 2684 content negotiation, and user behavior. Errors in prediction can 2685 lead to performance degradation, due to the opportunity cost that the 2686 additional data on the wire represents. In particular, pushing any 2687 significant amount of data can cause contention issues with more- 2688 important responses. 2690 A client can request that server push be disabled, though this is 2691 negotiated for each hop independently. The SETTINGS_ENABLE_PUSH 2692 setting can be set to 0 to indicate that server push is disabled. 2694 Promised requests MUST be safe (see Section 9.2.1 of [HTTP]) and 2695 cacheable (see Section 9.2.3 of [HTTP]). Promised requests cannot 2696 include any content or a trailer section. Clients that receive a 2697 promised request that is not cacheable, that is not known to be safe, 2698 or that indicates the presence of request content MUST reset the 2699 promised stream with a stream error (Section 5.4.2) of type 2700 PROTOCOL_ERROR. Note this could result in the promised stream being 2701 reset if the client does not recognize a newly defined method as 2702 being safe. 2704 Pushed responses that are cacheable (see Section 3 of [CACHE]) can be 2705 stored by the client, if it implements an HTTP cache. Pushed 2706 responses are considered successfully validated on the origin server 2707 (e.g., if the "no-cache" cache response directive is present; see 2708 Section 5.2.2.4 of [CACHE]) while the stream identified by the 2709 promised stream ID is still open. 2711 Pushed responses that are not cacheable MUST NOT be stored by any 2712 HTTP cache. They MAY be made available to the application 2713 separately. 2715 The server MUST include a value in the :authority pseudo-header field 2716 for which the server is authoritative (see Section 10.1). A client 2717 MUST treat a PUSH_PROMISE for which the server is not authoritative 2718 as a stream error (Section 5.4.2) of type PROTOCOL_ERROR. 2720 An intermediary can receive pushes from the server and choose not to 2721 forward them on to the client. In other words, how to make use of 2722 the pushed information is up to that intermediary. Equally, the 2723 intermediary might choose to make additional pushes to the client, 2724 without any action taken by the server. 2726 A client cannot push. Thus, servers MUST treat the receipt of a 2727 PUSH_PROMISE frame as a connection error (Section 5.4.1) of type 2728 PROTOCOL_ERROR. A server cannot set the SETTINGS_ENABLE_PUSH setting 2729 to a value other than 0 (see Section 6.5.2). 2731 8.4.1. Push Requests 2733 Server push is semantically equivalent to a server responding to a 2734 request; however, in this case, that request is also sent by the 2735 server, as a PUSH_PROMISE frame. 2737 The PUSH_PROMISE frame includes a field block that contains control 2738 data and a complete set of request header fields that the server 2739 attributes to the request. It is not possible to push a response to 2740 a request that includes message content. 2742 Promised requests are always associated with an explicit request from 2743 the client. The PUSH_PROMISE frames sent by the server are sent on 2744 that explicit request's stream. The PUSH_PROMISE frame also includes 2745 a promised stream identifier, chosen from the stream identifiers 2746 available to the server (see Section 5.1.1). 2748 The header fields in PUSH_PROMISE and any subsequent CONTINUATION 2749 frames MUST be a valid and complete set of request header fields 2750 (Section 8.3.1). The server MUST include a method in the :method 2751 pseudo-header field that is safe and cacheable. If a client receives 2752 a PUSH_PROMISE that does not include a complete and valid set of 2753 header fields or the :method pseudo-header field identifies a method 2754 that is not safe, it MUST respond with a stream error (Section 5.4.2) 2755 of type PROTOCOL_ERROR. 2757 The server SHOULD send PUSH_PROMISE (Section 6.6) frames prior to 2758 sending any frames that reference the promised responses. This 2759 avoids a race where clients issue requests prior to receiving any 2760 PUSH_PROMISE frames. 2762 For example, if the server receives a request for a document 2763 containing embedded links to multiple image files and the server 2764 chooses to push those additional images to the client, sending 2765 PUSH_PROMISE frames before the DATA frames that contain the image 2766 links ensures that the client is able to see that a resource will be 2767 pushed before discovering embedded links. Similarly, if the server 2768 pushes resources referenced by the field block (for instance, in Link 2769 header fields), sending a PUSH_PROMISE before sending the header 2770 ensures that clients do not request those resources. 2772 PUSH_PROMISE frames MUST NOT be sent by the client. 2774 PUSH_PROMISE frames can be sent by the server on any client-initiated 2775 stream, but the stream MUST be in either the "open" or "half-closed 2776 (remote)" state with respect to the server. PUSH_PROMISE frames are 2777 interspersed with the frames that comprise a response, though they 2778 cannot be interspersed with HEADERS and CONTINUATION frames that 2779 comprise a single field block. 2781 Sending a PUSH_PROMISE frame creates a new stream and puts the stream 2782 into the "reserved (local)" state for the server and the "reserved 2783 (remote)" state for the client. 2785 8.4.2. Push Responses 2787 After sending the PUSH_PROMISE frame, the server can begin delivering 2788 the pushed response as a response (Section 8.3.2) on a server- 2789 initiated stream that uses the promised stream identifier. The 2790 server uses this stream to transmit an HTTP response, using the same 2791 sequence of frames as defined in Section 8.1. This stream becomes 2792 "half-closed" to the client (Section 5.1) after the initial HEADERS 2793 frame is sent. 2795 Once a client receives a PUSH_PROMISE frame and chooses to accept the 2796 pushed response, the client SHOULD NOT issue any requests for the 2797 promised response until after the promised stream has closed. 2799 If the client determines, for any reason, that it does not wish to 2800 receive the pushed response from the server or if the server takes 2801 too long to begin sending the promised response, the client can send 2802 a RST_STREAM frame, using either the CANCEL or REFUSED_STREAM code 2803 and referencing the pushed stream's identifier. 2805 A client can use the SETTINGS_MAX_CONCURRENT_STREAMS setting to limit 2806 the number of responses that can be concurrently pushed by a server. 2807 Advertising a SETTINGS_MAX_CONCURRENT_STREAMS value of zero disables 2808 server push by preventing the server from creating the necessary 2809 streams. This does not prohibit a server from sending PUSH_PROMISE 2810 frames; clients need to reset any promised streams that are not 2811 wanted. 2813 Clients receiving a pushed response MUST validate that either the 2814 server is authoritative (see Section 10.1) or the proxy that provided 2815 the pushed response is configured for the corresponding request. For 2816 example, a server that offers a certificate for only the example.com 2817 DNS-ID is not permitted to push a response for 2818 https://www.example.org/doc. 2820 The response for a PUSH_PROMISE stream begins with a HEADERS frame, 2821 which immediately puts the stream into the "half-closed (remote)" 2822 state for the server and "half-closed (local)" state for the client, 2823 and ends with a frame with the END_STREAM flag set, which places the 2824 stream in the "closed" state. 2826 | Note: The client never sends a frame with the END_STREAM flag 2827 | set for a server push. 2829 8.5. The CONNECT Method 2831 The CONNECT method (Section 9.3.6 of [HTTP]) is used to convert an 2832 HTTP connection into a tunnel to a remote host. CONNECT is primarily 2833 used with HTTP proxies to establish a TLS session with an origin 2834 server for the purposes of interacting with https resources. 2836 In HTTP/2, the CONNECT method establishes a tunnel over a single 2837 HTTP/2 stream to a remote host, rather than converting the entire 2838 connection to a tunnel. A CONNECT header section is constructed as 2839 defined in Section 8.3.1 ("Request Pseudo-Header Fields"), with a few 2840 differences. Specifically: 2842 * The :method pseudo-header field is set to CONNECT. 2844 * The :scheme and :path pseudo-header fields MUST be omitted. 2846 * The :authority pseudo-header field contains the host and port to 2847 connect to (equivalent to the authority-form of the request-target 2848 of CONNECT requests; see Section 3.2.3 of [HTTP11]). 2850 A CONNECT request that does not conform to these restrictions is 2851 malformed (Section 8.1.1). 2853 A proxy that supports CONNECT establishes a TCP connection [TCP] to 2854 the host and port identified in the :authority pseudo-header field. 2855 Once this connection is successfully established, the proxy sends a 2856 HEADERS frame containing a 2xx series status code to the client, as 2857 defined in Section 9.3.6 of [HTTP]. 2859 After the initial HEADERS frame sent by each peer, all subsequent 2860 DATA frames correspond to data sent on the TCP connection. The frame 2861 payload of any DATA frames sent by the client is transmitted by the 2862 proxy to the TCP server; data received from the TCP server is 2863 assembled into DATA frames by the proxy. Frame types other than DATA 2864 or stream management frames (RST_STREAM, WINDOW_UPDATE, and PRIORITY) 2865 MUST NOT be sent on a connected stream and MUST be treated as a 2866 stream error (Section 5.4.2) if received. 2868 The TCP connection can be closed by either peer. The END_STREAM flag 2869 on a DATA frame is treated as being equivalent to the TCP FIN bit. A 2870 client is expected to send a DATA frame with the END_STREAM flag set 2871 after receiving a frame with the END_STREAM flag set. A proxy that 2872 receives a DATA frame with the END_STREAM flag set sends the attached 2873 data with the FIN bit set on the last TCP segment. A proxy that 2874 receives a TCP segment with the FIN bit set sends a DATA frame with 2875 the END_STREAM flag set. Note that the final TCP segment or DATA 2876 frame could be empty. 2878 A TCP connection error is signaled with RST_STREAM. A proxy treats 2879 any error in the TCP connection, which includes receiving a TCP 2880 segment with the RST bit set, as a stream error (Section 5.4.2) of 2881 type CONNECT_ERROR. Correspondingly, a proxy MUST send a TCP segment 2882 with the RST bit set if it detects an error with the stream or the 2883 HTTP/2 connection. 2885 8.6. The Upgrade Header Field 2887 HTTP/2 does not support the 101 (Switching Protocols) informational 2888 status code (Section 15.2.2 of [HTTP]). 2890 The semantics of 101 (Switching Protocols) aren't applicable to a 2891 multiplexed protocol. Similar functionality might be enabled through 2892 the use of extended CONNECT [RFC8441] and other protocols are able to 2893 use the same mechanisms that HTTP/2 uses to negotiate their use (see 2894 Section 3). 2896 8.7. Request Reliability 2898 In general, an HTTP client is unable to retry a non-idempotent 2899 request when an error occurs because there is no means to determine 2900 the nature of the error (see Section 9.2.2 of [HTTP]). It is 2901 possible that some server processing occurred prior to the error, 2902 which could result in undesirable effects if the request were 2903 reattempted. 2905 HTTP/2 provides two mechanisms for providing a guarantee to a client 2906 that a request has not been processed: 2908 * The GOAWAY frame indicates the highest stream number that might 2909 have been processed. Requests on streams with higher numbers are 2910 therefore guaranteed to be safe to retry. 2912 * The REFUSED_STREAM error code can be included in a RST_STREAM 2913 frame to indicate that the stream is being closed prior to any 2914 processing having occurred. Any request that was sent on the 2915 reset stream can be safely retried. 2917 Requests that have not been processed have not failed; clients MAY 2918 automatically retry them, even those with non-idempotent methods. 2920 A server MUST NOT indicate that a stream has not been processed 2921 unless it can guarantee that fact. If frames that are on a stream 2922 are passed to the application layer for any stream, then 2923 REFUSED_STREAM MUST NOT be used for that stream, and a GOAWAY frame 2924 MUST include a stream identifier that is greater than or equal to the 2925 given stream identifier. 2927 In addition to these mechanisms, the PING frame provides a way for a 2928 client to easily test a connection. Connections that remain idle can 2929 become broken as some middleboxes (for instance, network address 2930 translators or load balancers) silently discard connection bindings. 2931 The PING frame allows a client to safely test whether a connection is 2932 still active without sending a request. 2934 8.8. Examples 2936 This section shows HTTP/1.1 requests and responses, with 2937 illustrations of equivalent HTTP/2 requests and responses. 2939 8.8.1. Simple Request 2941 An HTTP GET request includes control data and a request header with 2942 no message content and is therefore transmitted as a single HEADERS 2943 frame, followed by zero or more CONTINUATION frames containing the 2944 serialized block of request header fields. The HEADERS frame in the 2945 following has both the END_HEADERS and END_STREAM flags set; no 2946 CONTINUATION frames are sent. 2948 GET /resource HTTP/1.1 HEADERS 2949 Host: example.org ==> + END_STREAM 2950 Accept: image/jpeg + END_HEADERS 2951 :method = GET 2952 :scheme = https 2953 :authority = example.org 2954 :path = /resource 2955 host = example.org 2956 accept = image/jpeg 2958 8.8.2. Simple Response 2960 Similarly, a response that includes only control data and a response 2961 header is transmitted as a HEADERS frame (again, followed by zero or 2962 more CONTINUATION frames) containing the serialized block of response 2963 header fields. 2965 HTTP/1.1 304 Not Modified HEADERS 2966 ETag: "xyzzy" ==> + END_STREAM 2967 Expires: Thu, 23 Jan ... + END_HEADERS 2968 :status = 304 2969 etag = "xyzzy" 2970 expires = Thu, 23 Jan ... 2972 8.8.3. Complex Request 2974 An HTTP POST request that includes control data and a request header 2975 and message content is transmitted as one HEADERS frame, followed by 2976 zero or more CONTINUATION frames containing the request header, 2977 followed by one or more DATA frames, with the last CONTINUATION (or 2978 HEADERS) frame having the END_HEADERS flag set and the final DATA 2979 frame having the END_STREAM flag set: 2981 POST /resource HTTP/1.1 HEADERS 2982 Host: example.org ==> - END_STREAM 2983 Content-Type: image/jpeg - END_HEADERS 2984 Content-Length: 123 :method = POST 2985 :authority = example.org 2986 :path = /resource 2987 {binary data} :scheme = https 2989 CONTINUATION 2990 + END_HEADERS 2991 content-type = image/jpeg 2992 host = example.org 2993 content-length = 123 2995 DATA 2996 + END_STREAM 2997 {binary data} 2999 Note that data contributing to any given field line could be spread 3000 between field block fragments. The allocation of field lines to 3001 frames in this example is illustrative only. 3003 8.8.4. Response with Body 3005 A response that includes control data and a response header and 3006 message content is transmitted as a HEADERS frame, followed by zero 3007 or more CONTINUATION frames, followed by one or more DATA frames, 3008 with the last DATA frame in the sequence having the END_STREAM flag 3009 set: 3011 HTTP/1.1 200 OK HEADERS 3012 Content-Type: image/jpeg ==> - END_STREAM 3013 Content-Length: 123 + END_HEADERS 3014 :status = 200 3015 {binary data} content-type = image/jpeg 3016 content-length = 123 3018 DATA 3019 + END_STREAM 3020 {binary data} 3022 8.8.5. Informational Responses 3024 An informational response using a 1xx status code other than 101 is 3025 transmitted as a HEADERS frame, followed by zero or more CONTINUATION 3026 frames. 3028 A trailer section is sent as a field block after both the request or 3029 response field block and all the DATA frames have been sent. The 3030 HEADERS frame starting the field block that comprises the trailer 3031 section has the END_STREAM flag set. 3033 The following example includes both a 100 (Continue) status code, 3034 which is sent in response to a request containing a "100-continue" 3035 token in the Expect header field, and a trailer section: 3037 HTTP/1.1 100 Continue HEADERS 3038 Extension-Field: bar ==> - END_STREAM 3039 + END_HEADERS 3040 :status = 100 3041 extension-field = bar 3043 HTTP/1.1 200 OK HEADERS 3044 Content-Type: image/jpeg ==> - END_STREAM 3045 Transfer-Encoding: chunked + END_HEADERS 3046 Trailer: Foo :status = 200 3047 content-type = image/jpeg 3048 123 trailer = Foo 3049 {binary data} 3050 0 DATA 3051 Foo: bar - END_STREAM 3052 {binary data} 3054 HEADERS 3055 + END_STREAM 3056 + END_HEADERS 3057 foo = bar 3059 9. HTTP/2 Connections 3061 This section outlines attributes of the HTTP protocol that improve 3062 interoperability, reduce exposure to known security vulnerabilities, 3063 or reduce the potential for implementation variation. 3065 9.1. Connection Management 3067 HTTP/2 connections are persistent. For best performance, it is 3068 expected that clients will not close connections until it is 3069 determined that no further communication with a server is necessary 3070 (for example, when a user navigates away from a particular web page) 3071 or until the server closes the connection. 3073 Clients SHOULD NOT open more than one HTTP/2 connection to a given 3074 host and port pair, where the host is derived from a URI, a selected 3075 alternative service [ALT-SVC], or a configured proxy. 3077 A client can create additional connections as replacements, either to 3078 replace connections that are near to exhausting the available stream 3079 identifier space (Section 5.1.1), to refresh the keying material for 3080 a TLS connection, or to replace connections that have encountered 3081 errors (Section 5.4.1). 3083 A client MAY open multiple connections to the same IP address and TCP 3084 port using different Server Name Indication [TLS-EXT] values or to 3085 provide different TLS client certificates but SHOULD avoid creating 3086 multiple connections with the same configuration. 3088 Servers are encouraged to maintain open connections for as long as 3089 possible but are permitted to terminate idle connections if 3090 necessary. When either endpoint chooses to close the transport-layer 3091 TCP connection, the terminating endpoint SHOULD first send a GOAWAY 3092 (Section 6.8) frame so that both endpoints can reliably determine 3093 whether previously sent frames have been processed and gracefully 3094 complete or terminate any necessary remaining tasks. 3096 9.1.1. Connection Reuse 3098 Connections that are made to an origin server, either directly or 3099 through a tunnel created using the CONNECT method (Section 8.5), MAY 3100 be reused for requests with multiple different URI authority 3101 components. A connection can be reused as long as the origin server 3102 is authoritative (Section 10.1). For TCP connections without TLS, 3103 this depends on the host having resolved to the same IP address. 3105 For https resources, connection reuse additionally depends on having 3106 a certificate that is valid for the host in the URI. The certificate 3107 presented by the server MUST satisfy any checks that the client would 3108 perform when forming a new TLS connection for the host in the URI. A 3109 single certificate can be used to establish authority for multiple 3110 origins. Section 4.3 of [HTTP] describes how a client determines 3111 whether a server is authoritative for a URI. 3113 In some deployments, reusing a connection for multiple origins can 3114 result in requests being directed to the wrong origin server. For 3115 example, TLS termination might be performed by a middlebox that uses 3116 the TLS Server Name Indication (SNI) [TLS-EXT] extension to select an 3117 origin server. This means that it is possible for clients to send 3118 requests to servers that might not be the intended target for the 3119 request, even though the server is otherwise authoritative. 3121 A server that does not wish clients to reuse connections can indicate 3122 that it is not authoritative for a request by sending a 421 3123 (Misdirected Request) status code in response to the request (see 3124 Section 15.5.20 of [HTTP]). 3126 A client that is configured to use a proxy over HTTP/2 directs 3127 requests to that proxy through a single connection. That is, all 3128 requests sent via a proxy reuse the connection to the proxy. 3130 9.2. Use of TLS Features 3132 Implementations of HTTP/2 MUST use TLS version 1.2 [TLS12] or higher 3133 for HTTP/2 over TLS. The general TLS usage guidance in [TLSBCP] 3134 SHOULD be followed, with some additional restrictions that are 3135 specific to HTTP/2. 3137 The TLS implementation MUST support the Server Name Indication (SNI) 3138 [TLS-EXT] extension to TLS. If the server is identified by a domain 3139 name [DNS-TERMS], clients MUST send the server_name TLS extension 3140 unless an alternative mechanism to indicate the target host is used. 3142 Requirements for deployments of HTTP/2 that negotiate TLS 1.3 [TLS13] 3143 are included in Section 9.2.3. Deployments of TLS 1.2 are subject to 3144 the requirements in Section 9.2.1 and Section 9.2.2. Implementations 3145 are encouraged to provide defaults that comply, but it is recognized 3146 that deployments are ultimately responsible for compliance. 3148 9.2.1. TLS 1.2 Features 3150 This section describes restrictions on the TLS 1.2 feature set that 3151 can be used with HTTP/2. Due to deployment limitations, it might not 3152 be possible to fail TLS negotiation when these restrictions are not 3153 met. An endpoint MAY immediately terminate an HTTP/2 connection that 3154 does not meet these TLS requirements with a connection error 3155 (Section 5.4.1) of type INADEQUATE_SECURITY. 3157 A deployment of HTTP/2 over TLS 1.2 MUST disable compression. TLS 3158 compression can lead to the exposure of information that would not 3159 otherwise be revealed [RFC3749]. Generic compression is unnecessary 3160 since HTTP/2 provides compression features that are more aware of 3161 context and therefore likely to be more appropriate for use for 3162 performance, security, or other reasons. 3164 A deployment of HTTP/2 over TLS 1.2 MUST disable renegotiation. An 3165 endpoint MUST treat a TLS renegotiation as a connection error 3166 (Section 5.4.1) of type PROTOCOL_ERROR. Note that disabling 3167 renegotiation can result in long-lived connections becoming unusable 3168 due to limits on the number of messages the underlying cipher suite 3169 can encipher. 3171 An endpoint MAY use renegotiation to provide confidentiality 3172 protection for client credentials offered in the handshake, but any 3173 renegotiation MUST occur prior to sending the connection preface. A 3174 server SHOULD request a client certificate if it sees a renegotiation 3175 request immediately after establishing a connection. 3177 This effectively prevents the use of renegotiation in response to a 3178 request for a specific protected resource. A future specification 3179 might provide a way to support this use case. Alternatively, a 3180 server might use an error (Section 5.4) of type HTTP_1_1_REQUIRED to 3181 request the client use a protocol that supports renegotiation. 3183 Implementations MUST support ephemeral key exchange sizes of at least 3184 2048 bits for cipher suites that use ephemeral finite field Diffie- 3185 Hellman (DHE) [TLS13] and 224 bits for cipher suites that use 3186 ephemeral elliptic curve Diffie-Hellman (ECDHE) [RFC8422]. Clients 3187 MUST accept DHE sizes of up to 4096 bits. Endpoints MAY treat 3188 negotiation of key sizes smaller than the lower limits as a 3189 connection error (Section 5.4.1) of type INADEQUATE_SECURITY. 3191 9.2.2. TLS 1.2 Cipher Suites 3193 A deployment of HTTP/2 over TLS 1.2 SHOULD NOT use any of the cipher 3194 suites that are listed in the list of prohibited cipher suites 3195 (Appendix A). 3197 Endpoints MAY choose to generate a connection error (Section 5.4.1) 3198 of type INADEQUATE_SECURITY if one of the prohibited cipher suites is 3199 negotiated. A deployment that chooses to use a prohibited cipher 3200 suite risks triggering a connection error unless the set of potential 3201 peers is known to accept that cipher suite. 3203 Implementations MUST NOT generate this error in reaction to the 3204 negotiation of a cipher suite that is not prohibited. Consequently, 3205 when clients offer a cipher suite that is not prohibited, they have 3206 to be prepared to use that cipher suite with HTTP/2. 3208 The list of prohibited cipher suites includes the cipher suite that 3209 TLS 1.2 makes mandatory, which means that TLS 1.2 deployments could 3210 have non-intersecting sets of permitted cipher suites. To avoid this 3211 problem causing TLS handshake failures, deployments of HTTP/2 that 3212 use TLS 1.2 MUST support TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 3213 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186]. 3215 Note that clients might advertise support of cipher suites that are 3216 prohibited in order to allow for connection to servers that do not 3217 support HTTP/2. This allows servers to select HTTP/1.1 with a cipher 3218 suite that is prohibited in HTTP/2. However, this can result in 3219 HTTP/2 being negotiated with a prohibited cipher suite if the 3220 application protocol and cipher suite are independently selected. 3222 9.2.3. TLS 1.3 Features 3224 TLS 1.3 includes a number of features not available in earlier 3225 versions. This section discusses the use of these features. 3227 HTTP/2 servers MUST NOT send post-handshake TLS 1.3 3228 CertificateRequest messages. HTTP/2 clients MUST treat a TLS post- 3229 handshake CertificateRequest message as a connection error 3230 (Section 5.4.1) of type PROTOCOL_ERROR. 3232 The prohibition on post-handshake authentication applies even if the 3233 client offered the "post_handshake_auth" TLS extension. Post- 3234 handshake authentication support might be advertised independently of 3235 ALPN [TLS-ALPN]. Clients might offer the capability for use in other 3236 protocols, but inclusion of the extension cannot imply support within 3237 HTTP/2. 3239 [TLS13] defines other post-handshake messages, NewSessionTicket and 3240 KeyUpdate, which can be used as they have no direct interaction with 3241 HTTP/2. Unless the use of a new type of TLS message depends on an 3242 interaction with the application-layer protocol, that TLS message can 3243 be sent after the handshake completes. 3245 TLS early data MAY be used to send requests, provided that the 3246 guidance in [RFC8470] is observed. Clients send requests in early 3247 data assuming initial values for all server settings. 3249 10. Security Considerations 3251 The use of TLS is necessary to provide many of the security 3252 properties of this protocol. Many of the claims in this section do 3253 not hold unless TLS is used as described in Section 9.2. 3255 10.1. Server Authority 3257 HTTP/2 relies on the HTTP definition of authority for determining 3258 whether a server is authoritative in providing a given response (see 3259 Section 4.3 of [HTTP]). This relies on local name resolution for the 3260 "http" URI scheme and the authenticated server identity for the 3261 "https" scheme. 3263 10.2. Cross-Protocol Attacks 3265 In a cross-protocol attack, an attacker causes a client to initiate a 3266 transaction in one protocol toward a server that understands a 3267 different protocol. An attacker might be able to cause the 3268 transaction to appear as a valid transaction in the second protocol. 3269 In combination with the capabilities of the web context, this can be 3270 used to interact with poorly protected servers in private networks. 3272 Completing a TLS handshake with an ALPN identifier for HTTP/2 can be 3273 considered sufficient protection against cross-protocol attacks. 3274 ALPN provides a positive indication that a server is willing to 3275 proceed with HTTP/2, which prevents attacks on other TLS-based 3276 protocols. 3278 The encryption in TLS makes it difficult for attackers to control the 3279 data that could be used in a cross-protocol attack on a cleartext 3280 protocol. 3282 The cleartext version of HTTP/2 has minimal protection against cross- 3283 protocol attacks. The connection preface (Section 3.4) contains a 3284 string that is designed to confuse HTTP/1.1 servers, but no special 3285 protection is offered for other protocols. 3287 10.3. Intermediary Encapsulation Attacks 3289 HPACK permits encoding of field names and values that might be 3290 treated as delimiters in other HTTP versions. An intermediary that 3291 translates an HTTP/2 request or response MUST validate fields 3292 according to the rules in Section 8.2 before translating a message to 3293 another HTTP version. Translating a field that includes invalid 3294 delimiters could be used to cause recipients to incorrectly interpret 3295 a message, which could be exploited by an attacker. 3297 An intermediary can reject fields that contain invalid field names or 3298 values for other reasons, in particular those that do not conform to 3299 the HTTP ABNF grammar from Section 5 of [HTTP]. Intermediaries that 3300 do not perform any validation of fields other than the minimum 3301 required by Section 8.2 could forward messages that contain invalid 3302 field names or values. 3304 An intermediary that receives any field that requires removal before 3305 forwarding (see Section 7.6.1 of [HTTP]) MUST remove or replace those 3306 header fields when forwarding messages. Additionally, intermediaries 3307 should take care when forwarding messages containing Content-Length 3308 fields to ensure that the message is well-formed (Section 8.1.1). 3309 This ensures that if the message is translated into HTTP/1.1 at any 3310 point the framing will be correct. 3312 10.4. Cacheability of Pushed Responses 3314 Pushed responses do not have an explicit request from the client; the 3315 request is provided by the server in the PUSH_PROMISE frame. 3317 Caching responses that are pushed is possible based on the guidance 3318 provided by the origin server in the Cache-Control header field. 3319 However, this can cause issues if a single server hosts more than one 3320 tenant. For example, a server might offer multiple users each a 3321 small portion of its URI space. 3323 Where multiple tenants share space on the same server, that server 3324 MUST ensure that tenants are not able to push representations of 3325 resources that they do not have authority over. Failure to enforce 3326 this would allow a tenant to provide a representation that would be 3327 served out of cache, overriding the actual representation that the 3328 authoritative tenant provides. 3330 Pushed responses for which an origin server is not authoritative (see 3331 Section 10.1) MUST NOT be used or cached. 3333 10.5. Denial-of-Service Considerations 3335 An HTTP/2 connection can demand a greater commitment of resources to 3336 operate than an HTTP/1.1 connection. The use of field section 3337 compression and flow control depend on a commitment of resources for 3338 storing a greater amount of state. Settings for these features 3339 ensure that memory commitments for these features are strictly 3340 bounded. 3342 The number of PUSH_PROMISE frames is not constrained in the same 3343 fashion. A client that accepts server push SHOULD limit the number 3344 of streams it allows to be in the "reserved (remote)" state. An 3345 excessive number of server push streams can be treated as a stream 3346 error (Section 5.4.2) of type ENHANCE_YOUR_CALM. 3348 A number of HTTP/2 implementations were found to be vulnerable to 3349 denial of service [NFLX-2019-002]. The following lists known ways 3350 that implementations might be subject to denial of service attack: 3352 * Inefficient tracking of outstanding outbound frames can lead to 3353 overload if an adversary can cause large numbers of frames to be 3354 enqueued for sending. A peer could use one of several techniques 3355 to cause large numbers of frames to be generated: 3357 - Providing tiny increments to flow control in WINDOW_UPDATE 3358 frames can cause a sender to generate a large number of DATA 3359 frames. 3361 - An endpoint is required to respond to a PING frame. 3363 - Each SETTINGS frame requires acknowledgment. 3365 - An invalid request (or server push) can cause a peer to send 3366 RST_STREAM frames in response. 3368 * Large numbers of small or empty frames can be abused to cause a 3369 peer to expend time processing frame headers. Caution is required 3370 here as some uses of small frames are entirely legitimate, such as 3371 the sending of an empty DATA or CONTINUATION frame at the end of a 3372 stream. 3374 * The SETTINGS frame might also be abused to cause a peer to expend 3375 additional processing time. This might be done by pointlessly 3376 changing settings, sending multiple undefined settings, or 3377 changing the same setting multiple times in the same frame. 3379 * Handling reprioritization with PRIORITY frames can require 3380 significant processing time and can lead to overload if many 3381 PRIORITY frames are sent. 3383 * Field section compression also offers some opportunities to waste 3384 processing resources; see Section 7 of [COMPRESSION] for more 3385 details on potential abuses. 3387 * Limits in SETTINGS cannot be reduced instantaneously, which leaves 3388 an endpoint exposed to behavior from a peer that could exceed the 3389 new limits. In particular, immediately after establishing a 3390 connection, limits set by a server are not known to clients and 3391 could be exceeded without being an obvious protocol violation. 3393 * An attacker can provide large amounts of flow control credit at 3394 the HTTP/2 layer, but withhold credit at the TCP layer, preventing 3395 frames from being sent. An endpoint that constructs and remembers 3396 frames for sending without considering TCP limits might be subject 3397 to resource exhaustion. 3399 Most of the features that might be exploited for denial of service -- 3400 i.e., SETTINGS changes, small frames, field section compression -- 3401 have legitimate uses. These features become a burden only when they 3402 are used unnecessarily or to excess. 3404 An endpoint that doesn't monitor use of these features exposes itself 3405 to a risk of denial of service. Implementations SHOULD track the use 3406 of these features and set limits on their use. An endpoint MAY treat 3407 activity that is suspicious as a connection error (Section 5.4.1) of 3408 type ENHANCE_YOUR_CALM. 3410 10.5.1. Limits on Field Block Size 3412 A large field block (Section 4.3) can cause an implementation to 3413 commit a large amount of state. Field lines that are critical for 3414 routing can appear toward the end of a field block, which prevents 3415 streaming of fields to their ultimate destination. This ordering and 3416 other reasons, such as ensuring cache correctness, mean that an 3417 endpoint might need to buffer the entire field block. Since there is 3418 no hard limit to the size of a field block, some endpoints could be 3419 forced to commit a large amount of available memory for field blocks. 3421 An endpoint can use the SETTINGS_MAX_HEADER_LIST_SIZE to advise peers 3422 of limits that might apply on the size of uncompressed field blocks. 3423 This setting is only advisory, so endpoints MAY choose to send field 3424 blocks that exceed this limit and risk the request or response being 3425 treated as malformed. This setting is specific to a connection, so 3426 any request or response could encounter a hop with a lower, unknown 3427 limit. An intermediary can attempt to avoid this problem by passing 3428 on values presented by different peers, but they are not obliged to 3429 do so. 3431 A server that receives a larger field block than it is willing to 3432 handle can send an HTTP 431 (Request Header Fields Too Large) status 3433 code [RFC6585]. A client can discard responses that it cannot 3434 process. The field block MUST be processed to ensure a consistent 3435 connection state, unless the connection is closed. 3437 10.5.2. CONNECT Issues 3439 The CONNECT method can be used to create disproportionate load on a 3440 proxy, since stream creation is relatively inexpensive when compared 3441 to the creation and maintenance of a TCP connection. A proxy might 3442 also maintain some resources for a TCP connection beyond the closing 3443 of the stream that carries the CONNECT request, since the outgoing 3444 TCP connection remains in the TIME_WAIT state. Therefore, a proxy 3445 cannot rely on SETTINGS_MAX_CONCURRENT_STREAMS alone to limit the 3446 resources consumed by CONNECT requests. 3448 10.6. Use of Compression 3450 Compression can allow an attacker to recover secret data when it is 3451 compressed in the same context as data under attacker control. 3452 HTTP/2 enables compression of field lines (Section 4.3); the 3453 following concerns also apply to the use of HTTP compressed content- 3454 codings (Section 8.4.1 of [HTTP]). 3456 There are demonstrable attacks on compression that exploit the 3457 characteristics of the web (e.g., [BREACH]). The attacker induces 3458 multiple requests containing varying plaintext, observing the length 3459 of the resulting ciphertext in each, which reveals a shorter length 3460 when a guess about the secret is correct. 3462 Implementations communicating on a secure channel MUST NOT compress 3463 content that includes both confidential and attacker-controlled data 3464 unless separate compression dictionaries are used for each source of 3465 data. Compression MUST NOT be used if the source of data cannot be 3466 reliably determined. Generic stream compression, such as that 3467 provided by TLS, MUST NOT be used with HTTP/2 (see Section 9.2). 3469 Further considerations regarding the compression of header fields are 3470 described in [COMPRESSION]. 3472 10.7. Use of Padding 3474 Padding within HTTP/2 is not intended as a replacement for general 3475 purpose padding, such as that provided by TLS [TLS13]. Redundant 3476 padding could even be counterproductive. Correct application can 3477 depend on having specific knowledge of the data that is being padded. 3479 To mitigate attacks that rely on compression, disabling or limiting 3480 compression might be preferable to padding as a countermeasure. 3482 Padding can be used to obscure the exact size of frame content and is 3483 provided to mitigate specific attacks within HTTP, for example, 3484 attacks where compressed content includes both attacker-controlled 3485 plaintext and secret data (e.g., [BREACH]). 3487 Use of padding can result in less protection than might seem 3488 immediately obvious. At best, padding only makes it more difficult 3489 for an attacker to infer length information by increasing the number 3490 of frames an attacker has to observe. Incorrectly implemented 3491 padding schemes can be easily defeated. In particular, randomized 3492 padding with a predictable distribution provides very little 3493 protection; similarly, padding frame payloads to a fixed size exposes 3494 information as frame payload sizes cross the fixed-sized boundary, 3495 which could be possible if an attacker can control plaintext. 3497 Intermediaries SHOULD retain padding for DATA frames but MAY drop 3498 padding for HEADERS and PUSH_PROMISE frames. A valid reason for an 3499 intermediary to change the amount of padding of frames is to improve 3500 the protections that padding provides. 3502 10.8. Privacy Considerations 3504 Several characteristics of HTTP/2 provide an observer an opportunity 3505 to correlate actions of a single client or server over time. These 3506 include the value of settings, the manner in which flow-control 3507 windows are managed, the way priorities are allocated to streams, the 3508 timing of reactions to stimulus, and the handling of any features 3509 that are controlled by settings. 3511 As far as these create observable differences in behavior, they could 3512 be used as a basis for fingerprinting a specific client, as defined 3513 in Section 3.2 of [PRIVACY]. 3515 HTTP/2's preference for using a single TCP connection allows 3516 correlation of a user's activity on a site. Reusing connections for 3517 different origins allows tracking across those origins. 3519 Because the PING and SETTINGS frames solicit immediate responses, 3520 they can be used by an endpoint to measure latency to their peer. 3521 This might have privacy implications in certain scenarios. 3523 10.9. Remote Timing Attacks 3525 Remote timing attacks extract secrets from servers by observing 3526 variations in the time that servers take when processing requests 3527 that use secrets. HTTP/2 enables concurrent request creation and 3528 processing, which can give attackers better control over when request 3529 processing commences. Multiple HTTP/2 requests can be included in 3530 the same IP packet or TLS record. HTTP/2 can therefore make remote 3531 timing attacks more efficient by eliminating variability in request 3532 delivery, leaving only request order and the delivery of responses as 3533 sources of timing variability. 3535 Ensuring that processing time is not dependent on the value of 3536 secrets is the best defense against any form of timing attack. 3538 11. IANA Considerations 3540 This revision of the document marks the HTTP2-Settings header field 3541 and the h2c Upgrade token, both defined in [RFC7540], as obsolete. 3543 Section 11 of [RFC7540] registered the h2 and h2c ALPN identifiers 3544 along with the PRI HTTP method. RFC 7540 also established a registry 3545 for frame types, settings, and error codes. These registrations and 3546 registries apply to HTTP/2, but are not redefined in this document. 3548 IANA is requested to update references to RFC 7540 in the following 3549 registries to refer to this document: Application-Layer Protocol 3550 Negotiation (ALPN) Protocol IDs, HTTP/2 Frame Type, HTTP/2 Settings, 3551 HTTP/2 Error Code, and HTTP Method Registry. The registration of the 3552 PRI method needs to be updated to refer to Section 3.4; all other 3553 section numbers have not changed. 3555 11.1. HTTP2-Settings Header Field Registration 3557 This section marks the HTTP2-Settings header field registered by 3558 Section 11.5 of [RFC7540] in the Hypertext Transfer Protocol (HTTP) 3559 Field Name Registry as obsolete. This capability has been removed: 3560 see Section 3.1. The registration is updated to include the details 3561 as required by Section 18.4 of [HTTP]: 3563 Field Name: HTTP2-Settings 3565 Status: Standard 3567 Ref.: Section 3.2.1 of [RFC7540] 3569 Comments: Obsolete; see Section 11.1 of this document 3571 11.2. The h2c Upgrade Token 3573 This section records the h2c upgrade token registered by Section 11.8 3574 of [RFC7540] in the Hypertext Transfer Protocol (HTTP) Upgrade Token 3575 Registry as obsolete. This capability has been removed: see 3576 Section 3.1. The registration is updated as follows: 3578 Value: h2c 3580 Description: Hypertext Transfer Protocol version 2 (HTTP/2) 3582 Expected Version Tokens: None 3584 Reference: Section 3.1 of this document 3586 12. References 3588 12.1. Normative References 3590 [CACHE] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3591 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 3592 draft-ietf-httpbis-cache-18, 18 August 2021, 3593 . 3596 [COMPRESSION] 3597 Peon, R. and H. Ruellan, "HPACK: Header Compression for 3598 HTTP/2", RFC 7541, May 2015, 3599 . 3601 [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3602 April 2011, . 3604 [FIPS186] NIST, "Digital Signature Standard (DSS)", FIPS PUB 186-4, 3605 July 2013, . 3607 [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3608 Ed., "HTTP Semantics", Work in Progress, Internet-Draft, 3609 draft-ietf-httpbis-semantics-18, 18 August 2021, 3610 . 3613 [QUIC] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 3614 Multiplexed and Secure Transport", RFC 9000, 3615 DOI 10.17487/RFC9000, May 2021, 3616 . 3618 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3619 Requirement Levels", BCP 14, RFC 2119, March 1997, 3620 . 3622 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3623 Resource Identifier (URI): Generic Syntax", STD 66, 3624 RFC 3986, January 2005, 3625 . 3627 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3628 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3629 May 2017, . 3631 [RFC8470] Thomson, M., Nottingham, M., and W. Tarreau, "Using Early 3632 Data in HTTP", RFC 8470, DOI 10.17487/RFC8470, September 3633 2018, . 3635 [TCP] Postel, J., "Transmission Control Protocol", STD 7, 3636 RFC 793, September 1981, 3637 . 3639 [TLS-ALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan, 3640 "Transport Layer Security (TLS) Application-Layer Protocol 3641 Negotiation Extension", RFC 7301, July 2014, 3642 . 3644 [TLS-ECDHE] 3645 Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 3646 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 3647 August 2008, . 3649 [TLS-EXT] Eastlake 3rd, D., "Transport Layer Security (TLS) 3650 Extensions: Extension Definitions", RFC 6066, January 3651 2011, . 3653 [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer Security 3654 (TLS) Protocol Version 1.2", RFC 5246, August 2008, 3655 . 3657 [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3658 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3659 . 3661 [TLSBCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 3662 "Recommendations for Secure Use of Transport Layer 3663 Security (TLS) and Datagram Transport Layer Security 3664 (DTLS)", BCP 195, RFC 7525, May 2015, 3665 . 3667 12.2. Informative References 3669 [ALT-SVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP 3670 Alternative Services", RFC 7838, April 2016, 3671 . 3673 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 3674 CRIME Attack", 12 July 2013, 3675 . 3678 [DNS-TERMS] 3679 Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 3680 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 3681 January 2019, . 3683 [HTTP11] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3684 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 3685 ietf-httpbis-messaging-18, 18 August 2021, 3686 . 3689 [I-D.ietf-httpbis-priority] 3690 Oku, K. and L. Pardue, "Extensible Prioritization Scheme 3691 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 3692 httpbis-priority-10, 18 November 2021, 3693 . 3696 [NFLX-2019-002] 3697 Netflix, "HTTP/2 Denial of Service Advisory", 13 August 3698 2019, . 3701 [PRIVACY] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 3702 Morris, J., Hansen, M., and R. Smith, "Privacy 3703 Considerations for Internet Protocols", RFC 6973, 3704 DOI 10.17487/RFC6973, July 2013, 3705 . 3707 [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol 3708 Compression Methods", RFC 3749, May 2004, 3709 . 3711 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 3712 Codes", RFC 6585, April 2012, 3713 . 3715 [RFC7323] Borman, D., Braden, B., Jacobson, V., and R. 3716 Scheffenegger, Ed., "TCP Extensions for High Performance", 3717 RFC 7323, September 2014, 3718 . 3720 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 3721 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 3722 DOI 10.17487/RFC7540, May 2015, 3723 . 3725 [RFC8422] Nir, Y., Josefsson, S., and M. Pegourie-Gonnard, "Elliptic 3726 Curve Cryptography (ECC) Cipher Suites for Transport Layer 3727 Security (TLS) Versions 1.2 and Earlier", RFC 8422, August 3728 2018, . 3730 [RFC8441] McManus, P., "Bootstrapping WebSockets with HTTP/2", 3731 RFC 8441, DOI 10.17487/RFC8441, September 2018, 3732 . 3734 [RFC8740] Benjamin, D., "Using TLS 1.3 with HTTP/2", RFC 8740, 3735 DOI 10.17487/RFC8740, February 2020, 3736 . 3738 [TALKING] Huang, L., Chen, E., Barth, A., Rescorla, E., and C. 3739 Jackson, "Talking to Yourself for Fun and Profit", 2011, 3740 . 3742 Appendix A. Prohibited TLS 1.2 Cipher Suites 3744 An HTTP/2 implementation MAY treat the negotiation of any of the 3745 following cipher suites with TLS 1.2 as a connection error 3746 (Section 5.4.1) of type INADEQUATE_SECURITY: 3748 * TLS_NULL_WITH_NULL_NULL 3749 * TLS_RSA_WITH_NULL_MD5 3750 * TLS_RSA_WITH_NULL_SHA 3751 * TLS_RSA_EXPORT_WITH_RC4_40_MD5 3752 * TLS_RSA_WITH_RC4_128_MD5 3753 * TLS_RSA_WITH_RC4_128_SHA 3754 * TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 3755 * TLS_RSA_WITH_IDEA_CBC_SHA 3756 * TLS_RSA_EXPORT_WITH_DES40_CBC_SHA 3757 * TLS_RSA_WITH_DES_CBC_SHA 3758 * TLS_RSA_WITH_3DES_EDE_CBC_SHA 3759 * TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA 3760 * TLS_DH_DSS_WITH_DES_CBC_SHA 3761 * TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 3762 * TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA 3763 * TLS_DH_RSA_WITH_DES_CBC_SHA 3764 * TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 3765 * TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA 3766 * TLS_DHE_DSS_WITH_DES_CBC_SHA 3767 * TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 3768 * TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA 3769 * TLS_DHE_RSA_WITH_DES_CBC_SHA 3770 * TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 3771 * TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 3772 * TLS_DH_anon_WITH_RC4_128_MD5 3773 * TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA 3774 * TLS_DH_anon_WITH_DES_CBC_SHA 3775 * TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 3776 * TLS_KRB5_WITH_DES_CBC_SHA 3777 * TLS_KRB5_WITH_3DES_EDE_CBC_SHA 3778 * TLS_KRB5_WITH_RC4_128_SHA 3779 * TLS_KRB5_WITH_IDEA_CBC_SHA 3780 * TLS_KRB5_WITH_DES_CBC_MD5 3781 * TLS_KRB5_WITH_3DES_EDE_CBC_MD5 3782 * TLS_KRB5_WITH_RC4_128_MD5 3783 * TLS_KRB5_WITH_IDEA_CBC_MD5 3784 * TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA 3785 * TLS_KRB5_EXPORT_WITH_RC2_CBC_40_SHA 3786 * TLS_KRB5_EXPORT_WITH_RC4_40_SHA 3787 * TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5 3788 * TLS_KRB5_EXPORT_WITH_RC2_CBC_40_MD5 3789 * TLS_KRB5_EXPORT_WITH_RC4_40_MD5 3790 * TLS_PSK_WITH_NULL_SHA 3791 * TLS_DHE_PSK_WITH_NULL_SHA 3792 * TLS_RSA_PSK_WITH_NULL_SHA 3793 * TLS_RSA_WITH_AES_128_CBC_SHA 3794 * TLS_DH_DSS_WITH_AES_128_CBC_SHA 3795 * TLS_DH_RSA_WITH_AES_128_CBC_SHA 3796 * TLS_DHE_DSS_WITH_AES_128_CBC_SHA 3797 * TLS_DHE_RSA_WITH_AES_128_CBC_SHA 3798 * TLS_DH_anon_WITH_AES_128_CBC_SHA 3799 * TLS_RSA_WITH_AES_256_CBC_SHA 3800 * TLS_DH_DSS_WITH_AES_256_CBC_SHA 3801 * TLS_DH_RSA_WITH_AES_256_CBC_SHA 3802 * TLS_DHE_DSS_WITH_AES_256_CBC_SHA 3803 * TLS_DHE_RSA_WITH_AES_256_CBC_SHA 3804 * TLS_DH_anon_WITH_AES_256_CBC_SHA 3805 * TLS_RSA_WITH_NULL_SHA256 3806 * TLS_RSA_WITH_AES_128_CBC_SHA256 3807 * TLS_RSA_WITH_AES_256_CBC_SHA256 3808 * TLS_DH_DSS_WITH_AES_128_CBC_SHA256 3809 * TLS_DH_RSA_WITH_AES_128_CBC_SHA256 3810 * TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 3811 * TLS_RSA_WITH_CAMELLIA_128_CBC_SHA 3812 * TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA 3813 * TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA 3814 * TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA 3815 * TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA 3816 * TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA 3817 * TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 3818 * TLS_DH_DSS_WITH_AES_256_CBC_SHA256 3819 * TLS_DH_RSA_WITH_AES_256_CBC_SHA256 3820 * TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 3821 * TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 3822 * TLS_DH_anon_WITH_AES_128_CBC_SHA256 3823 * TLS_DH_anon_WITH_AES_256_CBC_SHA256 3824 * TLS_RSA_WITH_CAMELLIA_256_CBC_SHA 3825 * TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA 3826 * TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA 3827 * TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA 3828 * TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA 3829 * TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA 3830 * TLS_PSK_WITH_RC4_128_SHA 3831 * TLS_PSK_WITH_3DES_EDE_CBC_SHA 3832 * TLS_PSK_WITH_AES_128_CBC_SHA 3833 * TLS_PSK_WITH_AES_256_CBC_SHA 3834 * TLS_DHE_PSK_WITH_RC4_128_SHA 3835 * TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA 3836 * TLS_DHE_PSK_WITH_AES_128_CBC_SHA 3837 * TLS_DHE_PSK_WITH_AES_256_CBC_SHA 3838 * TLS_RSA_PSK_WITH_RC4_128_SHA 3839 * TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA 3840 * TLS_RSA_PSK_WITH_AES_128_CBC_SHA 3841 * TLS_RSA_PSK_WITH_AES_256_CBC_SHA 3842 * TLS_RSA_WITH_SEED_CBC_SHA 3843 * TLS_DH_DSS_WITH_SEED_CBC_SHA 3844 * TLS_DH_RSA_WITH_SEED_CBC_SHA 3845 * TLS_DHE_DSS_WITH_SEED_CBC_SHA 3846 * TLS_DHE_RSA_WITH_SEED_CBC_SHA 3847 * TLS_DH_anon_WITH_SEED_CBC_SHA 3848 * TLS_RSA_WITH_AES_128_GCM_SHA256 3849 * TLS_RSA_WITH_AES_256_GCM_SHA384 3850 * TLS_DH_RSA_WITH_AES_128_GCM_SHA256 3851 * TLS_DH_RSA_WITH_AES_256_GCM_SHA384 3852 * TLS_DH_DSS_WITH_AES_128_GCM_SHA256 3853 * TLS_DH_DSS_WITH_AES_256_GCM_SHA384 3854 * TLS_DH_anon_WITH_AES_128_GCM_SHA256 3855 * TLS_DH_anon_WITH_AES_256_GCM_SHA384 3856 * TLS_PSK_WITH_AES_128_GCM_SHA256 3857 * TLS_PSK_WITH_AES_256_GCM_SHA384 3858 * TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 3859 * TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 3860 * TLS_PSK_WITH_AES_128_CBC_SHA256 3861 * TLS_PSK_WITH_AES_256_CBC_SHA384 3862 * TLS_PSK_WITH_NULL_SHA256 3863 * TLS_PSK_WITH_NULL_SHA384 3864 * TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 3865 * TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 3866 * TLS_DHE_PSK_WITH_NULL_SHA256 3867 * TLS_DHE_PSK_WITH_NULL_SHA384 3868 * TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 3869 * TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 3870 * TLS_RSA_PSK_WITH_NULL_SHA256 3871 * TLS_RSA_PSK_WITH_NULL_SHA384 3872 * TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 3873 * TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA256 3874 * TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA256 3875 * TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA256 3876 * TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 3877 * TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA256 3878 * TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 3879 * TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA256 3880 * TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA256 3881 * TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA256 3882 * TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 3883 * TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA256 3884 * TLS_EMPTY_RENEGOTIATION_INFO_SCSV 3885 * TLS_ECDH_ECDSA_WITH_NULL_SHA 3886 * TLS_ECDH_ECDSA_WITH_RC4_128_SHA 3887 * TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 3888 * TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 3889 * TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 3890 * TLS_ECDHE_ECDSA_WITH_NULL_SHA 3891 * TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 3892 * TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 3893 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 3894 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 3895 * TLS_ECDH_RSA_WITH_NULL_SHA 3896 * TLS_ECDH_RSA_WITH_RC4_128_SHA 3897 * TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 3898 * TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 3899 * TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 3900 * TLS_ECDHE_RSA_WITH_NULL_SHA 3901 * TLS_ECDHE_RSA_WITH_RC4_128_SHA 3902 * TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 3903 * TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 3904 * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 3905 * TLS_ECDH_anon_WITH_NULL_SHA 3906 * TLS_ECDH_anon_WITH_RC4_128_SHA 3907 * TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 3908 * TLS_ECDH_anon_WITH_AES_128_CBC_SHA 3909 * TLS_ECDH_anon_WITH_AES_256_CBC_SHA 3910 * TLS_SRP_SHA_WITH_3DES_EDE_CBC_SHA 3911 * TLS_SRP_SHA_RSA_WITH_3DES_EDE_CBC_SHA 3912 * TLS_SRP_SHA_DSS_WITH_3DES_EDE_CBC_SHA 3913 * TLS_SRP_SHA_WITH_AES_128_CBC_SHA 3914 * TLS_SRP_SHA_RSA_WITH_AES_128_CBC_SHA 3915 * TLS_SRP_SHA_DSS_WITH_AES_128_CBC_SHA 3916 * TLS_SRP_SHA_WITH_AES_256_CBC_SHA 3917 * TLS_SRP_SHA_RSA_WITH_AES_256_CBC_SHA 3918 * TLS_SRP_SHA_DSS_WITH_AES_256_CBC_SHA 3919 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 3920 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 3921 * TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 3922 * TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 3923 * TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 3924 * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 3925 * TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 3926 * TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 3927 * TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 3928 * TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 3929 * TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 3930 * TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 3931 * TLS_ECDHE_PSK_WITH_RC4_128_SHA 3932 * TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA 3933 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA 3934 * TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA 3935 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 3936 * TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 3937 * TLS_ECDHE_PSK_WITH_NULL_SHA 3938 * TLS_ECDHE_PSK_WITH_NULL_SHA256 3939 * TLS_ECDHE_PSK_WITH_NULL_SHA384 3940 * TLS_RSA_WITH_ARIA_128_CBC_SHA256 3941 * TLS_RSA_WITH_ARIA_256_CBC_SHA384 3942 * TLS_DH_DSS_WITH_ARIA_128_CBC_SHA256 3943 * TLS_DH_DSS_WITH_ARIA_256_CBC_SHA384 3944 * TLS_DH_RSA_WITH_ARIA_128_CBC_SHA256 3945 * TLS_DH_RSA_WITH_ARIA_256_CBC_SHA384 3946 * TLS_DHE_DSS_WITH_ARIA_128_CBC_SHA256 3947 * TLS_DHE_DSS_WITH_ARIA_256_CBC_SHA384 3948 * TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256 3949 * TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384 3950 * TLS_DH_anon_WITH_ARIA_128_CBC_SHA256 3951 * TLS_DH_anon_WITH_ARIA_256_CBC_SHA384 3952 * TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256 3953 * TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384 3954 * TLS_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256 3955 * TLS_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384 3956 * TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256 3957 * TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384 3958 * TLS_ECDH_RSA_WITH_ARIA_128_CBC_SHA256 3959 * TLS_ECDH_RSA_WITH_ARIA_256_CBC_SHA384 3960 * TLS_RSA_WITH_ARIA_128_GCM_SHA256 3961 * TLS_RSA_WITH_ARIA_256_GCM_SHA384 3962 * TLS_DH_RSA_WITH_ARIA_128_GCM_SHA256 3963 * TLS_DH_RSA_WITH_ARIA_256_GCM_SHA384 3964 * TLS_DH_DSS_WITH_ARIA_128_GCM_SHA256 3965 * TLS_DH_DSS_WITH_ARIA_256_GCM_SHA384 3966 * TLS_DH_anon_WITH_ARIA_128_GCM_SHA256 3967 * TLS_DH_anon_WITH_ARIA_256_GCM_SHA384 3968 * TLS_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256 3969 * TLS_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384 3970 * TLS_ECDH_RSA_WITH_ARIA_128_GCM_SHA256 3971 * TLS_ECDH_RSA_WITH_ARIA_256_GCM_SHA384 3972 * TLS_PSK_WITH_ARIA_128_CBC_SHA256 3973 * TLS_PSK_WITH_ARIA_256_CBC_SHA384 3974 * TLS_DHE_PSK_WITH_ARIA_128_CBC_SHA256 3975 * TLS_DHE_PSK_WITH_ARIA_256_CBC_SHA384 3976 * TLS_RSA_PSK_WITH_ARIA_128_CBC_SHA256 3977 * TLS_RSA_PSK_WITH_ARIA_256_CBC_SHA384 3978 * TLS_PSK_WITH_ARIA_128_GCM_SHA256 3979 * TLS_PSK_WITH_ARIA_256_GCM_SHA384 3980 * TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256 3981 * TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384 3982 * TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256 3983 * TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384 3984 * TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 3985 * TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 3986 * TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 3987 * TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 3988 * TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 3989 * TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 3990 * TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256 3991 * TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384 3992 * TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256 3993 * TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384 3994 * TLS_DH_RSA_WITH_CAMELLIA_128_GCM_SHA256 3995 * TLS_DH_RSA_WITH_CAMELLIA_256_GCM_SHA384 3996 * TLS_DH_DSS_WITH_CAMELLIA_128_GCM_SHA256 3997 * TLS_DH_DSS_WITH_CAMELLIA_256_GCM_SHA384 3998 * TLS_DH_anon_WITH_CAMELLIA_128_GCM_SHA256 3999 * TLS_DH_anon_WITH_CAMELLIA_256_GCM_SHA384 4000 * TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 4001 * TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 4002 * TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256 4003 * TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384 4004 * TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 4005 * TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 4006 * TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256 4007 * TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384 4008 * TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256 4009 * TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 4010 * TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 4011 * TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 4012 * TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 4013 * TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 4014 * TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 4015 * TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 4016 * TLS_RSA_WITH_AES_128_CCM 4017 * TLS_RSA_WITH_AES_256_CCM 4018 * TLS_RSA_WITH_AES_128_CCM_8 4019 * TLS_RSA_WITH_AES_256_CCM_8 4020 * TLS_PSK_WITH_AES_128_CCM 4021 * TLS_PSK_WITH_AES_256_CCM 4022 * TLS_PSK_WITH_AES_128_CCM_8 4023 * TLS_PSK_WITH_AES_256_CCM_8 4024 | Note: This list was assembled from the set of registered TLS 4025 | cipher suites when [RFC7540] was developed. This list includes 4026 | those cipher suites that do not offer an ephemeral key exchange 4027 | and those that are based on the TLS null, stream, or block 4028 | cipher type (as defined in Section 6.2.3 of [TLS12]). 4029 | Additional cipher suites with these properties could be 4030 | defined; these would not be explicitly prohibited. 4032 Appendix B. Changes from RFC 7540 4034 This revision includes a number of editorial updates, plus the 4035 following substantive changes: 4037 * Use of TLS 1.3 was defined based on RFC 8740, which this document 4038 obsoletes. 4040 * The priority scheme defined in RFC 7540 is deprecated. 4041 Definitions for the format of the PRIORITY frame and the priority 4042 fields in the HEADERS frame have been retained, plus the rules 4043 governing when PRIORITY frames can be sent and received, but the 4044 semantics of these fields are only described in RFC 7540. The 4045 priority signaling scheme from RFC 7540 was not successful. Using 4046 the simpler successor signaling [I-D.ietf-httpbis-priority] is 4047 recommended. 4049 * The HTTP/1.1 Upgrade mechanism is no longer specified in this 4050 document. It was never widely deployed, with plaintext HTTP/2 4051 users choosing to use the prior-knowledge implementation instead. 4053 * Validation for field names and values has been narrowed. The 4054 validation that is mandatory for intermediaries is precisely 4055 defined and error reporting for requests has been amended to 4056 encourage sending 400-series status codes. 4058 * The ranges of codepoints for settings and frame types that were 4059 reserved for "Experimental Use" are now available for general use. 4061 * Connection-specific header fields - which are prohibited - are 4062 more precisely and comprehensively identified. 4064 * Host and :authority are no longer permitted to disagree. 4066 Contributors 4068 The previous version of this document was authored by Mike Belshe and 4069 Roberto Peon. 4071 Acknowledgments 4073 Credit for non-trivial input to this document is owed to a large 4074 number of people who have contributed to the HTTP working group over 4075 the years. [RFC7540] contains a more extensive list of people that 4076 deserve acknowledgment for their contributions. 4078 Authors' Addresses 4080 Martin Thomson (editor) 4081 Mozilla 4082 Australia 4084 Email: mt@lowentropy.net 4086 Cory Benfield (editor) 4087 Apple Inc. 4089 Email: cbenfield@apple.com