idnits 2.17.1 draft-ietf-httpbis-http2bis-07.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 (24 January 2022) is 821 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' == 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 -- Obsolete informational reference (is this intentional?): RFC 6125 (Obsoleted by RFC 9525) -- 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 (~~), 4 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: 28 July 2022 24 January 2022 8 HTTP/2 9 draft-ietf-httpbis-http2bis-07 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 28 July 2022. 49 Copyright Notice 51 Copyright (c) 2022 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 4.3.1. Compression State . . . . . . . . . . . . . . . . . . 13 79 5. Streams and Multiplexing . . . . . . . . . . . . . . . . . . 14 80 5.1. Stream States . . . . . . . . . . . . . . . . . . . . . . 15 81 5.1.1. Stream Identifiers . . . . . . . . . . . . . . . . . 20 82 5.1.2. Stream Concurrency . . . . . . . . . . . . . . . . . 21 83 5.2. Flow Control . . . . . . . . . . . . . . . . . . . . . . 21 84 5.2.1. Flow-Control Principles . . . . . . . . . . . . . . . 21 85 5.2.2. Appropriate Use of Flow Control . . . . . . . . . . . 23 86 5.2.3. Flow Control Performance . . . . . . . . . . . . . . 23 87 5.3. Prioritization . . . . . . . . . . . . . . . . . . . . . 24 88 5.3.1. Background on Priority in RFC 7540 . . . . . . . . . 24 89 5.3.2. Priority Signaling in this Document . . . . . . . . . 24 90 5.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 25 91 5.4.1. Connection Error Handling . . . . . . . . . . . . . . 26 92 5.4.2. Stream Error Handling . . . . . . . . . . . . . . . . 26 93 5.4.3. Connection Termination . . . . . . . . . . . . . . . 27 94 5.5. Extending HTTP/2 . . . . . . . . . . . . . . . . . . . . 27 95 6. Frame Definitions . . . . . . . . . . . . . . . . . . . . . . 28 96 6.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . 28 97 6.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . . . 30 98 6.3. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . 32 99 6.4. RST_STREAM . . . . . . . . . . . . . . . . . . . . . . . 33 100 6.5. SETTINGS . . . . . . . . . . . . . . . . . . . . . . . . 34 101 6.5.1. SETTINGS Format . . . . . . . . . . . . . . . . . . . 35 102 6.5.2. Defined Settings . . . . . . . . . . . . . . . . . . 36 103 6.5.3. Settings Synchronization . . . . . . . . . . . . . . 38 104 6.6. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . . . 38 105 6.7. PING . . . . . . . . . . . . . . . . . . . . . . . . . . 41 106 6.8. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . . . 42 107 6.9. WINDOW_UPDATE . . . . . . . . . . . . . . . . . . . . . . 45 108 6.9.1. The Flow-Control Window . . . . . . . . . . . . . . . 47 109 6.9.2. Initial Flow-Control Window Size . . . . . . . . . . 48 110 6.9.3. Reducing the Stream Window Size . . . . . . . . . . . 49 111 6.10. CONTINUATION . . . . . . . . . . . . . . . . . . . . . . 49 112 7. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 50 113 8. Expressing HTTP Semantics in HTTP/2 . . . . . . . . . . . . . 51 114 8.1. HTTP Message Framing . . . . . . . . . . . . . . . . . . 51 115 8.1.1. Malformed Messages . . . . . . . . . . . . . . . . . 53 116 8.2. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . . 54 117 8.2.1. Field Validity . . . . . . . . . . . . . . . . . . . 54 118 8.2.2. Connection-Specific Header Fields . . . . . . . . . . 55 119 8.2.3. Compressing the Cookie Header Field . . . . . . . . . 56 120 8.3. HTTP Control Data . . . . . . . . . . . . . . . . . . . . 56 121 8.3.1. Request Pseudo-Header Fields . . . . . . . . . . . . 57 122 8.3.2. Response Pseudo-Header Fields . . . . . . . . . . . . 59 123 8.4. Server Push . . . . . . . . . . . . . . . . . . . . . . . 59 124 8.4.1. Push Requests . . . . . . . . . . . . . . . . . . . . 60 125 8.4.2. Push Responses . . . . . . . . . . . . . . . . . . . 62 126 8.5. The CONNECT Method . . . . . . . . . . . . . . . . . . . 63 127 8.6. The Upgrade Header Field . . . . . . . . . . . . . . . . 64 128 8.7. Request Reliability . . . . . . . . . . . . . . . . . . . 64 129 8.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . 65 130 8.8.1. Simple Request . . . . . . . . . . . . . . . . . . . 65 131 8.8.2. Simple Response . . . . . . . . . . . . . . . . . . . 65 132 8.8.3. Complex Request . . . . . . . . . . . . . . . . . . . 66 133 8.8.4. Response with Body . . . . . . . . . . . . . . . . . 66 134 8.8.5. Informational Responses . . . . . . . . . . . . . . . 67 135 9. HTTP/2 Connections . . . . . . . . . . . . . . . . . . . . . 68 136 9.1. Connection Management . . . . . . . . . . . . . . . . . . 68 137 9.1.1. Connection Reuse . . . . . . . . . . . . . . . . . . 68 138 9.2. Use of TLS Features . . . . . . . . . . . . . . . . . . . 69 139 9.2.1. TLS 1.2 Features . . . . . . . . . . . . . . . . . . 70 140 9.2.2. TLS 1.2 Cipher Suites . . . . . . . . . . . . . . . . 71 141 9.2.3. TLS 1.3 Features . . . . . . . . . . . . . . . . . . 71 142 10. Security Considerations . . . . . . . . . . . . . . . . . . . 72 143 10.1. Server Authority . . . . . . . . . . . . . . . . . . . . 72 144 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 72 145 10.3. Intermediary Encapsulation Attacks . . . . . . . . . . . 73 146 10.4. Cacheability of Pushed Responses . . . . . . . . . . . . 73 147 10.5. Denial-of-Service Considerations . . . . . . . . . . . . 74 148 10.5.1. Limits on Field Block Size . . . . . . . . . . . . . 75 149 10.5.2. CONNECT Issues . . . . . . . . . . . . . . . . . . . 76 150 10.6. Use of Compression . . . . . . . . . . . . . . . . . . . 76 151 10.7. Use of Padding . . . . . . . . . . . . . . . . . . . . . 77 152 10.8. Privacy Considerations . . . . . . . . . . . . . . . . . 77 153 10.9. Remote Timing Attacks . . . . . . . . . . . . . . . . . 78 154 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 78 155 11.1. HTTP2-Settings Header Field Registration . . . . . . . . 79 156 11.2. The h2c Upgrade Token . . . . . . . . . . . . . . . . . 79 157 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 79 158 12.1. Normative References . . . . . . . . . . . . . . . . . . 79 159 12.2. Informative References . . . . . . . . . . . . . . . . . 81 160 Appendix A. Prohibited TLS 1.2 Cipher Suites . . . . . . . . . . 83 161 Appendix B. Changes from RFC 7540 . . . . . . . . . . . . . . . 89 162 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 90 163 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 90 164 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90 166 1. Introduction 168 The performance of applications using the Hypertext Transfer Protocol 169 (HTTP, [HTTP]) is linked to how each version of HTTP uses the 170 underlying transport, and the conditions under which the transport 171 operates. 173 Making multiple concurrent requests can reduce latency and improve 174 application performance. HTTP/1.0 allowed only one request to be 175 outstanding at a time on a given TCP [TCP] connection. HTTP/1.1 176 ([HTTP11]) added request pipelining, but this only partially 177 addressed request concurrency and still suffers from application- 178 layer head-of-line blocking. Therefore, HTTP/1.0 and HTTP/1.1 179 clients use multiple connections to a server to make concurrent 180 requests. 182 Furthermore, HTTP fields are often repetitive and verbose, causing 183 unnecessary network traffic as well as causing the initial TCP 184 congestion window to quickly fill. This can result in excessive 185 latency when multiple requests are made on a new TCP connection. 187 HTTP/2 addresses these issues by defining an optimized mapping of 188 HTTP's semantics to an underlying connection. Specifically, it 189 allows interleaving of messages on the same connection and uses an 190 efficient coding for HTTP fields. It also allows prioritization of 191 requests, letting more important requests complete more quickly, 192 further improving performance. 194 The resulting protocol is more friendly to the network because fewer 195 TCP connections can be used in comparison to HTTP/1.x. This means 196 less competition with other flows and longer-lived connections, which 197 in turn lead to better utilization of available network capacity. 198 Note, however, that TCP head-of-line blocking is not addressed by 199 this protocol. 201 Finally, HTTP/2 also enables more efficient processing of messages 202 through use of binary message framing. 204 This document obsoletes RFC 7540 [RFC7540] and RFC 8740 [RFC8740]. 205 Appendix B lists notable changes. 207 2. HTTP/2 Protocol Overview 209 HTTP/2 provides an optimized transport for HTTP semantics. HTTP/2 210 supports all of the core features of HTTP but aims to be more 211 efficient than HTTP/1.1. 213 HTTP/2 is a connection-oriented application-layer protocol that runs 214 over a TCP connection ([TCP]). The client is the TCP connection 215 initiator. 217 The basic protocol unit in HTTP/2 is a frame (Section 4.1). Each 218 frame type serves a different purpose. For example, HEADERS and DATA 219 frames form the basis of HTTP requests and responses (Section 8.1); 220 other frame types like SETTINGS, WINDOW_UPDATE, and PUSH_PROMISE are 221 used in support of other HTTP/2 features. 223 Multiplexing of requests is achieved by having each HTTP request/ 224 response exchange associated with its own stream (Section 5). 225 Streams are largely independent of each other, so a blocked or 226 stalled request or response does not prevent progress on other 227 streams. 229 Effective use of multiplexing depends on flow control and 230 prioritization. Flow control (Section 5.2) ensures that it is 231 possible to efficiently use multiplexed streams by restricting data 232 that is transmitted to what the receiver is able to handle. 233 Prioritization (Section 5.3) ensures that limited resources are used 234 most effectively. This revision of HTTP/2 deprecates the priority 235 signaling scheme from [RFC7540]. 237 Because HTTP fields used in a connection can contain large amounts of 238 redundant data, frames that contain them are compressed 239 (Section 4.3). This has especially advantageous impact upon request 240 sizes in the common case, allowing many requests to be compressed 241 into one packet. 243 Finally, HTTP/2 adds a new, optional interaction mode whereby a 244 server can push responses to a client (Section 8.4). This is 245 intended to allow a server to speculatively send data to a client 246 that the server anticipates the client will need, trading off some 247 network usage against a potential latency gain. The server does this 248 by synthesizing a request, which it sends as a PUSH_PROMISE frame. 249 The server is then able to send a response to the synthetic request 250 on a separate stream. 252 2.1. Document Organization 254 The HTTP/2 specification is split into four parts: 256 * Starting HTTP/2 (Section 3) covers how an HTTP/2 connection is 257 initiated. 259 * The frame (Section 4) and stream (Section 5) layers describe the 260 way HTTP/2 frames are structured and formed into multiplexed 261 streams. 263 * Frame (Section 6) and error (Section 7) definitions include 264 details of the frame and error types used in HTTP/2. 266 * HTTP mappings (Section 8) and additional requirements (Section 9) 267 describe how HTTP semantics are expressed using frames and 268 streams. 270 While some of the frame and stream layer concepts are isolated from 271 HTTP, this specification does not define a completely generic frame 272 layer. The frame and stream layers are tailored to the needs of the 273 HTTP protocol. 275 2.2. Conventions and Terminology 277 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 278 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 279 "OPTIONAL" in this document are to be interpreted as described in 280 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 281 capitals, as shown here. 283 All numeric values are in network byte order. Values are unsigned 284 unless otherwise indicated. Literal values are provided in decimal 285 or hexadecimal as appropriate. Hexadecimal literals are prefixed 286 with "0x" to distinguish them from decimal literals. 288 This specification describes binary formats using the convention 289 described in Section 1.3 of RFC 9000 [QUIC]. Note that this format 290 uses network byte order and high-valued bits are listed before low- 291 valued bits. 293 The following terms are used: 295 client: The endpoint that initiates an HTTP/2 connection. Clients 296 send HTTP requests and receive HTTP responses. 298 connection: A transport-layer connection between two endpoints. 300 connection error: An error that affects the entire HTTP/2 301 connection. 303 endpoint: Either the client or server of the connection. 305 frame: The smallest unit of communication within an HTTP/2 306 connection, consisting of a header and a variable-length sequence 307 of octets structured according to the frame type. 309 peer: An endpoint. When discussing a particular endpoint, "peer" 310 refers to the endpoint that is remote to the primary subject of 311 discussion. 313 receiver: An endpoint that is receiving frames. 315 sender: An endpoint that is transmitting frames. 317 server: The endpoint that accepts an HTTP/2 connection. Servers 318 receive HTTP requests and send HTTP responses. 320 stream: A bidirectional flow of frames within the HTTP/2 connection. 322 stream error: An error on the individual HTTP/2 stream. 324 Finally, the terms "gateway", "intermediary", "proxy", and "tunnel" 325 are defined in Section 3.7 of [HTTP]. Intermediaries act as both 326 client and server at different times. 328 The term "content" as it applies to message bodies is defined in 329 Section 6.4 of [HTTP]. 331 3. Starting HTTP/2 333 Implementations that generate HTTP requests need to discover whether 334 a server supports HTTP/2. 336 HTTP/2 uses the "http" and "https" URI schemes defined in Section 4.2 337 of [HTTP], with the same default port numbers as HTTP/1.1 ([HTTP11]). 338 These URIs do not include any indication about what HTTP versions an 339 upstream server (the immediate peer to which the client wishes to 340 establish a connection) supports. 342 The means by which support for HTTP/2 is determined is different for 343 "http" and "https" URIs. Discovery for "https" URIs is described in 344 Section 3.2. HTTP/2 support for "http" URIs can only be discovered 345 by out-of-band means, and requires prior knowledge of the support as 346 described in Section 3.3. 348 3.1. HTTP/2 Version Identification 350 The protocol defined in this document has two identifiers. Creating 351 a connection based on either implies the use of the transport, 352 framing, and message semantics described in this document. 354 * The string "h2" identifies the protocol where HTTP/2 uses 355 Transport Layer Security (TLS); see Section 9.2. This identifier 356 is used in the TLS application-layer protocol negotiation (ALPN) 357 extension [TLS-ALPN] field and in any place where HTTP/2 over TLS 358 is identified. 360 The "h2" string is serialized into an ALPN protocol identifier as 361 the two-octet sequence: 0x68, 0x32. 363 * The "h2c" string was previously used as a token for use in the 364 HTTP Upgrade mechanism's Upgrade header field (Section 7.8 of 365 [HTTP]). This usage was never widely deployed and is deprecated 366 by this document. The same apples to the HTTP2-Settings header 367 field, which was used with the upgrade to "h2c". 369 3.2. Starting HTTP/2 for "https" URIs 371 A client that makes a request to an "https" URI uses TLS [TLS13] with 372 the application-layer protocol negotiation (ALPN) extension 373 [TLS-ALPN]. 375 HTTP/2 over TLS uses the "h2" protocol identifier. The "h2c" 376 protocol identifier MUST NOT be sent by a client or selected by a 377 server; the "h2c" protocol identifier describes a protocol that does 378 not use TLS. 380 Once TLS negotiation is complete, both the client and the server MUST 381 send a connection preface (Section 3.4). 383 3.3. Starting HTTP/2 with Prior Knowledge 385 A client can learn that a particular server supports HTTP/2 by other 386 means. For example, a client could be configured with knowledge that 387 a server supports HTTP/2. 389 A client that knows that a server supports HTTP/2 can establish a TCP 390 connection and send the connection preface (Section 3.4) followed by 391 HTTP/2 frames. Servers can identify these connections by the 392 presence of the connection preface. This only affects the 393 establishment of HTTP/2 connections over cleartext TCP; HTTP/2 394 connections over TLS MUST use protocol negotiation in TLS [TLS-ALPN]. 396 Likewise, the server MUST send a connection preface (Section 3.4). 398 Without additional information, prior support for HTTP/2 is not a 399 strong signal that a given server will support HTTP/2 for future 400 connections. For example, it is possible for server configurations 401 to change, for configurations to differ between instances in 402 clustered servers, or for network conditions to change. 404 3.4. HTTP/2 Connection Preface 406 In HTTP/2, each endpoint is required to send a connection preface as 407 a final confirmation of the protocol in use and to establish the 408 initial settings for the HTTP/2 connection. The client and server 409 each send a different connection preface. 411 The client connection preface starts with a sequence of 24 octets, 412 which in hex notation is: 414 0x505249202a20485454502f322e300d0a0d0a534d0d0a0d0a 416 That is, the connection preface starts with the string "PRI * 417 HTTP/2.0\r\n\r\nSM\r\n\r\n". This sequence MUST be followed by a 418 SETTINGS frame (Section 6.5), which MAY be empty. The client sends 419 the client connection preface as the first application data octets of 420 a connection. 422 | Note: The client connection preface is selected so that a large 423 | proportion of HTTP/1.1 or HTTP/1.0 servers and intermediaries 424 | do not attempt to process further frames. Note that this does 425 | not address the concerns raised in [TALKING]. 427 The server connection preface consists of a potentially empty 428 SETTINGS frame (Section 6.5) that MUST be the first frame the server 429 sends in the HTTP/2 connection. 431 The SETTINGS frames received from a peer as part of the connection 432 preface MUST be acknowledged (see Section 6.5.3) after sending the 433 connection preface. 435 To avoid unnecessary latency, clients are permitted to send 436 additional frames to the server immediately after sending the client 437 connection preface, without waiting to receive the server connection 438 preface. It is important to note, however, that the server 439 connection preface SETTINGS frame might include settings that 440 necessarily alter how a client is expected to communicate with the 441 server. Upon receiving the SETTINGS frame, the client is expected to 442 honor any settings established. In some configurations, it is 443 possible for the server to transmit SETTINGS before the client sends 444 additional frames, providing an opportunity to avoid this issue. 446 Clients and servers MUST treat an invalid connection preface as a 447 connection error (Section 5.4.1) of type PROTOCOL_ERROR. A GOAWAY 448 frame (Section 6.8) MAY be omitted in this case, since an invalid 449 preface indicates that the peer is not using HTTP/2. 451 4. HTTP Frames 453 Once the HTTP/2 connection is established, endpoints can begin 454 exchanging frames. 456 4.1. Frame Format 458 All frames begin with a fixed 9-octet header followed by a variable- 459 length frame payload. 461 HTTP Frame { 462 Length (24), 463 Type (8), 465 Flags (8), 467 Reserved (1), 468 Stream Identifier (31), 470 Frame Payload (..), 471 } 473 Figure 1: Frame Layout 475 The fields of the frame header are defined as: 477 Length: The length of the frame payload expressed as an unsigned 478 24-bit integer in units of octets. Values greater than 2^14 479 (16,384) MUST NOT be sent unless the receiver has set a larger 480 value for SETTINGS_MAX_FRAME_SIZE. 482 The 9 octets of the frame header are not included in this value. 484 Type: The 8-bit type of the frame. The frame type determines the 485 format and semantics of the frame. Frames defined in this 486 document are listed in Section 6. Implementations MUST ignore and 487 discard frames of unknown types. 489 Flags: An 8-bit field reserved for boolean flags specific to the 490 frame type. 492 Flags are assigned semantics specific to the indicated frame type. 493 Unused flags are those that have no defined semantics for a 494 particular frame type. Unused flags MUST be ignored on receipt 495 and MUST be left unset (0x0) when sending. 497 Reserved: A reserved 1-bit field. The semantics of this bit are 498 undefined, and the bit MUST remain unset (0x0) when sending and 499 MUST be ignored when receiving. 501 Stream Identifier: A stream identifier (see Section 5.1.1) expressed 502 as an unsigned 31-bit integer. The value 0x0 is reserved for 503 frames that are associated with the connection as a whole as 504 opposed to an individual stream. 506 The structure and content of the frame payload is dependent entirely 507 on the frame type. 509 4.2. Frame Size 511 The size of a frame payload is limited by the maximum size that a 512 receiver advertises in the SETTINGS_MAX_FRAME_SIZE setting. This 513 setting can have any value between 2^14 (16,384) and 2^24-1 514 (16,777,215) octets, inclusive. 516 All implementations MUST be capable of receiving and minimally 517 processing frames up to 2^14 octets in length, plus the 9-octet frame 518 header (Section 4.1). The size of the frame header is not included 519 when describing frame sizes. 521 | Note: Certain frame types, such as PING (Section 6.7), impose 522 | additional limits on the amount of frame payload data allowed. 524 An endpoint MUST send an error code of FRAME_SIZE_ERROR if a frame 525 exceeds the size defined in SETTINGS_MAX_FRAME_SIZE, exceeds any 526 limit defined for the frame type, or is too small to contain 527 mandatory frame data. A frame size error in a frame that could alter 528 the state of the entire connection MUST be treated as a connection 529 error (Section 5.4.1); this includes any frame carrying a field block 530 (Section 4.3) (that is, HEADERS, PUSH_PROMISE, and CONTINUATION), 531 SETTINGS, and any frame with a stream identifier of 0. 533 Endpoints are not obligated to use all available space in a frame. 534 Responsiveness can be improved by using frames that are smaller than 535 the permitted maximum size. Sending large frames can result in 536 delays in sending time-sensitive frames (such as RST_STREAM, 537 WINDOW_UPDATE, or PRIORITY), which, if blocked by the transmission of 538 a large frame, could affect performance. 540 4.3. Field Section Compression and Decompression 542 Field section compression is the process of compressing a set of 543 field lines (Section 5.2 of [HTTP]) to form a field block. Field 544 section decompression is the process of decoding a field block into a 545 set of field lines. Details of HTTP/2 field section compression and 546 decompression is defined in [COMPRESSION], which, for historical 547 reasons, refers to these processes as header compression and 548 decompression. 550 Each field block carries all of the compressed field lines of a 551 single field section. Header sections also include control data 552 associated with the message in the form of pseudo-header fields 553 (Section 8.3) that use the same format as a field line. 555 | Note: RFC 7540 [RFC7540] used the term "header block" in place 556 | of the more generic "field block". 558 Field blocks carry control data and header sections for requests, 559 responses, promised requests, and pushed responses (see Section 8.4). 560 All these messages, except for interim responses and requests 561 contained in PUSH_PROMISE (Section 6.6) frames, can optionally 562 include a field block that carries a trailer section. 564 A field section is a collection of field lines. Each of the field 565 lines in a field block carry a single value. The serialized field 566 block is then divided into one or more octet sequences, called field 567 block fragments. The first field block fragment is transmitted 568 within the frame payload of HEADERS (Section 6.2) or PUSH_PROMISE 569 (Section 6.6), each of which could be followed by CONTINUATION 570 (Section 6.10) frames to carry subsequent field block fragments. 572 The Cookie header field [COOKIE] is treated specially by the HTTP 573 mapping (see Section 8.2.3). 575 A receiving endpoint reassembles the field block by concatenating its 576 fragments and then decompresses the block to reconstruct the field 577 section. 579 A complete field section consists of either: 581 * a single HEADERS or PUSH_PROMISE frame, with the END_HEADERS flag 582 set, or 584 * a HEADERS or PUSH_PROMISE frame with the END_HEADERS flag unset 585 and one or more CONTINUATION frames, where the last CONTINUATION 586 frame has the END_HEADERS flag set. 588 Each field block is processed as a discrete unit. Field blocks MUST 589 be transmitted as a contiguous sequence of frames, with no 590 interleaved frames of any other type or from any other stream. The 591 last frame in a sequence of HEADERS or CONTINUATION frames has the 592 END_HEADERS flag set. The last frame in a sequence of PUSH_PROMISE 593 or CONTINUATION frames has the END_HEADERS flag set. This allows a 594 field block to be logically equivalent to a single frame. 596 Field block fragments can only be sent as the frame payload of 597 HEADERS, PUSH_PROMISE, or CONTINUATION frames because these frames 598 carry data that can modify the compression context maintained by a 599 receiver. An endpoint receiving HEADERS, PUSH_PROMISE, or 600 CONTINUATION frames needs to reassemble field blocks and perform 601 decompression even if the frames are to be discarded. A receiver 602 MUST terminate the connection with a connection error (Section 5.4.1) 603 of type COMPRESSION_ERROR if it does not decompress a field block. 605 A decoding error in a field block MUST be treated as a connection 606 error (Section 5.4.1) of type COMPRESSION_ERROR. 608 4.3.1. Compression State 610 Field compression is stateful. Each endpoint has an HPACK encoder 611 context and an HPACK decoder context that are used for encoding and 612 decoding all field blocks on a connection. Section 4 of 613 [COMPRESSION] defines the dynamic table, which is the primary state 614 for each context. 616 The dynamic table has a maximum size that is set by an HPACK decoder. 617 An endpoint communicates the size chosen by its HPACK decoder context 618 using the SETTINGS_HEADER_TABLE_SIZE setting; see Section 6.5.2. 619 When a connection is established, the dynamic table size for the 620 HPACK decoder and encoder at both endpoints starts at 4,096 bytes, 621 the initial value of the SETTINGS_HEADER_TABLE_SIZE setting. 623 Any change to the maximum value set using SETTINGS_HEADER_TABLE_SIZE 624 takes effect when the endpoint acknowledges settings (Section 6.5.3). 625 The HPACK encoder at that endpoint can set the dynamic table to any 626 size up to the maximum value set by the decoder. An HPACK encoder 627 declares the size of the dynamic table with a Dynamic Table Size 628 Update instruction (Section 6.3 of [COMPRESSION]). 630 Once an endpoint acknowledges a change to SETTINGS_HEADER_TABLE_SIZE 631 that reduces the maximum below the current size of the dynamic table, 632 its HPACK encoder MUST start the next field block with a Dynamic 633 Table Size Update instruction that sets the dynamic table to a size 634 that is less than or equal to the reduced maximum; see Section 4.2 of 635 [COMPRESSION]. An endpoint MUST treat a field block that follows an 636 acknowledgment of the reduction to the maximum dynamic table size as 637 a connection error (Section 5.4.1) of type COMPRESSION_ERROR if it 638 does not start with a conformant Dynamic Table Size Update 639 instruction. 641 | Implementers are advised that reducing the value of 642 | SETTINGS_HEADER_TABLE_SIZE is not widely interoperable. Use of 643 | the connection preface to reduce the value below the initial 644 | value of 4,096 is somewhat better supported, but this might 645 | fail with some implementations. 647 5. Streams and Multiplexing 649 A "stream" is an independent, bidirectional sequence of frames 650 exchanged between the client and server within an HTTP/2 connection. 651 Streams have several important characteristics: 653 * A single HTTP/2 connection can contain multiple concurrently open 654 streams, with either endpoint interleaving frames from multiple 655 streams. 657 * Streams can be established and used unilaterally or shared by 658 either endpoint. 660 * Streams can be closed by either endpoint. 662 * The order in which frames are sent is significant. Recipients 663 process frames in the order they are received. In particular, the 664 order of HEADERS and DATA frames is semantically significant. 666 * Streams are identified by an integer. Stream identifiers are 667 assigned to streams by the endpoint initiating the stream. 669 5.1. Stream States 671 The lifecycle of a stream is shown in Figure 2. 673 +--------+ 674 send PP | | recv PP 675 ,--------+ idle +--------. 676 / | | \ 677 v +--------+ v 678 +----------+ | +----------+ 679 | | | send H / | | 680 ,------+ reserved | | recv H | reserved +------. 681 | | (local) | | | (remote) | | 682 | +---+------+ v +------+---+ | 683 | | +--------+ | | 684 | | recv ES | | send ES | | 685 | send H | ,-------+ open +-------. | recv H | 686 | | / | | \ | | 687 | v v +---+----+ v v | 688 | +----------+ | +----------+ | 689 | | half | | | half | | 690 | | closed | | send R / | closed | | 691 | | (remote) | | recv R | (local) | | 692 | +----+-----+ | +-----+----+ | 693 | | | | | 694 | | send ES / | recv ES / | | 695 | | send R / v send R / | | 696 | | recv R +--------+ recv R | | 697 | send R / `----------->| |<-----------' send R / | 698 | recv R | closed | recv R | 699 `----------------------->| |<-----------------------' 700 +--------+ 702 Figure 2: Stream States 704 send: endpoint sends this frame 705 recv: endpoint receives this frame 706 H: HEADERS frame (with implied CONTINUATION frames) 707 ES: END_STREAM flag 708 R: RST_STREAM frame 709 PP: PUSH_PROMISE frame (with implied CONTINUATION frames); state 710 transitions are for the promised stream 712 Note that this diagram shows stream state transitions and the frames 713 and flags that affect those transitions only. In this regard, 714 CONTINUATION frames do not result in state transitions; they are 715 effectively part of the HEADERS or PUSH_PROMISE that they follow. 716 For the purpose of state transitions, the END_STREAM flag is 717 processed as a separate event to the frame that bears it; a HEADERS 718 frame with the END_STREAM flag set can cause two state transitions. 720 Both endpoints have a subjective view of the state of a stream that 721 could be different when frames are in transit. Endpoints do not 722 coordinate the creation of streams; they are created unilaterally by 723 either endpoint. The negative consequences of a mismatch in states 724 are limited to the "closed" state after sending RST_STREAM, where 725 frames might be received for some time after closing. 727 Streams have the following states: 729 idle: All streams start in the "idle" state. 731 The following transitions are valid from this state: 733 * Sending a HEADERS frame as a client, or receiving a HEADERS 734 frame as a server, causes the stream to become "open". The 735 stream identifier is selected as described in Section 5.1.1. 736 The same HEADERS frame can also cause a stream to immediately 737 become "half-closed". 739 * Sending a PUSH_PROMISE frame on another stream reserves the 740 idle stream that is identified for later use. The stream state 741 for the reserved stream transitions to "reserved (local)". 742 Only a server may send PUSH_PROMISE frames. 744 * Receiving a PUSH_PROMISE frame on another stream reserves an 745 idle stream that is identified for later use. The stream state 746 for the reserved stream transitions to "reserved (remote)". 747 Only a client may receive PUSH_PROMISE frames. 749 * Note that the PUSH_PROMISE frame is not sent on the idle stream 750 but references the newly reserved stream in the Promised Stream 751 ID field. 753 * Opening a stream with a higher-valued stream identifier causes 754 the stream to transition immediately to a "closed" state; note 755 that this transition is not shown in the diagram. 757 Receiving any frame other than HEADERS or PRIORITY on a stream in 758 this state MUST be treated as a connection error (Section 5.4.1) 759 of type PROTOCOL_ERROR. If this stream is server-initiated, as 760 described in Section 5.1.1, then receiving a HEADERS frame MUST 761 also be treated as a connection error (Section 5.4.1) of type 762 PROTOCOL_ERROR. 764 reserved (local): A stream in the "reserved (local)" state is one 765 that has been promised by sending a PUSH_PROMISE frame. A 766 PUSH_PROMISE frame reserves an idle stream by associating the 767 stream with an open stream that was initiated by the remote peer 768 (see Section 8.4). 770 In this state, only the following transitions are possible: 772 * The endpoint can send a HEADERS frame. This causes the stream 773 to open in a "half-closed (remote)" state. 775 * Either endpoint can send a RST_STREAM frame to cause the stream 776 to become "closed". This releases the stream reservation. 778 An endpoint MUST NOT send any type of frame other than HEADERS, 779 RST_STREAM, or PRIORITY in this state. 781 A PRIORITY or WINDOW_UPDATE frame MAY be received in this state. 782 Receiving any type of frame other than RST_STREAM, PRIORITY, or 783 WINDOW_UPDATE on a stream in this state MUST be treated as a 784 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 786 reserved (remote): A stream in the "reserved (remote)" state has 787 been reserved by a remote peer. 789 In this state, only the following transitions are possible: 791 * Receiving a HEADERS frame causes the stream to transition to 792 "half-closed (local)". 794 * Either endpoint can send a RST_STREAM frame to cause the stream 795 to become "closed". This releases the stream reservation. 797 An endpoint MUST NOT send any type of frame other than RST_STREAM, 798 WINDOW_UPDATE, or PRIORITY in this state. 800 Receiving any type of frame other than HEADERS, RST_STREAM, or 801 PRIORITY on a stream in this state MUST be treated as a connection 802 error (Section 5.4.1) of type PROTOCOL_ERROR. 804 open: A stream in the "open" state may be used by both peers to send 805 frames of any type. In this state, sending peers observe 806 advertised stream-level flow-control limits (Section 5.2). 808 From this state, either endpoint can send a frame with an 809 END_STREAM flag set, which causes the stream to transition into 810 one of the "half-closed" states. An endpoint sending an 811 END_STREAM flag causes the stream state to become "half-closed 812 (local)"; an endpoint receiving an END_STREAM flag causes the 813 stream state to become "half-closed (remote)". 815 Either endpoint can send a RST_STREAM frame from this state, 816 causing it to transition immediately to "closed". 818 half-closed (local): A stream that is in the "half-closed (local)" 819 state cannot be used for sending frames other than WINDOW_UPDATE, 820 PRIORITY, and RST_STREAM. 822 A stream transitions from this state to "closed" when a frame is 823 received with the END_STREAM flag set or when either peer sends a 824 RST_STREAM frame. 826 An endpoint can receive any type of frame in this state. 827 Providing flow-control credit using WINDOW_UPDATE frames is 828 necessary to continue receiving flow-controlled frames. In this 829 state, a receiver can ignore WINDOW_UPDATE frames, which might 830 arrive for a short period after a frame with the END_STREAM flag 831 set is sent. 833 PRIORITY frames can be received in this state. 835 half-closed (remote): A stream that is "half-closed (remote)" is no 836 longer being used by the peer to send frames. In this state, an 837 endpoint is no longer obligated to maintain a receiver flow- 838 control window. 840 If an endpoint receives additional frames, other than 841 WINDOW_UPDATE, PRIORITY, or RST_STREAM, for a stream that is in 842 this state, it MUST respond with a stream error (Section 5.4.2) of 843 type STREAM_CLOSED. 845 A stream that is "half-closed (remote)" can be used by the 846 endpoint to send frames of any type. In this state, the endpoint 847 continues to observe advertised stream-level flow-control limits 848 (Section 5.2). 850 A stream can transition from this state to "closed" by sending a 851 frame with the END_STREAM flag set or when either peer sends a 852 RST_STREAM frame. 854 closed: The "closed" state is the terminal state. 856 A stream enters the "closed" state after an endpoint both sends 857 and receives a frame with an END_STREAM flag set. A stream also 858 enters the "closed" state after an endpoint either sends or 859 receives a RST_STREAM frame. 861 An endpoint MUST NOT send frames other than PRIORITY on a closed 862 stream. An endpoint MAY treat receipt of any other type of frame 863 on a closed stream as a connection error (Section 5.4.1) of type 864 STREAM_CLOSED, except as noted below. 866 An endpoint that sends a frame with the END_STREAM flag set or a 867 RST_STREAM frame might receive a WINDOW_UPDATE or RST_STREAM frame 868 from its peer in the time before the peer receives and processes 869 the frame that closes the stream. 871 An endpoint that sends a RST_STREAM frame on a stream that is in 872 the "open" or "half-closed (local)" state could receive any type 873 of frame. The peer might have sent or enqueued for sending these 874 frames before processing the RST_STREAM frame. An endpoint MUST 875 minimally process and then discard any frames it receives in this 876 state. This means updating header compression state for HEADERS 877 and PUSH_PROMISE frames; PUSH_PROMISE frames also cause the 878 promised stream to become "reserved", even when the PUSH_PROMISE 879 frame is received on a closed stream; and, the content of DATA 880 frames count toward the connection flow-control window. 882 An endpoint can perform this minimal processing for all streams 883 that are in the "closed" state. Endpoints MAY use other signals 884 to detect that a peer has received the frames that caused the 885 stream to enter the "closed" state and treat receipt of any frame 886 other than PRIORITY as a connection error (Section 5.4.1) of type 887 PROTOCOL_ERROR. Endpoints can use frames that indicate that the 888 peer has received the closing signal to drive this. Endpoints 889 SHOULD NOT use timers for this purpose. For example, an endpoint 890 that sends a SETTINGS frame after closing a stream can safely 891 treat receipt of a DATA frame on that stream as an error after 892 receiving an acknowledgment of the settings. Other things that 893 might be used are PING frames, receiving data on streams that were 894 created after closing the stream, or responses to requests created 895 after closing the stream. 897 In the absence of more specific rules, implementations SHOULD treat 898 the receipt of a frame that is not expressly permitted in the 899 description of a state as a connection error (Section 5.4.1) of type 900 PROTOCOL_ERROR. Note that PRIORITY can be sent and received in any 901 stream state. 903 The rules in this section only apply to frames defined in this 904 document. Receipt of frames for which the semantics are unknown 905 cannot be treated as an error as the conditions for sending and 906 receiving those frames are also unknown; see Section 5.5. 908 An example of the state transitions for an HTTP request/response 909 exchange can be found in Section 8.8. An example of the state 910 transitions for server push can be found in Sections 8.4.1 and 8.4.2. 912 5.1.1. Stream Identifiers 914 Streams are identified by an unsigned 31-bit integer. Streams 915 initiated by a client MUST use odd-numbered stream identifiers; those 916 initiated by the server MUST use even-numbered stream identifiers. A 917 stream identifier of zero (0x0) is used for connection control 918 messages; the stream identifier of zero cannot be used to establish a 919 new stream. 921 The identifier of a newly established stream MUST be numerically 922 greater than all streams that the initiating endpoint has opened or 923 reserved. This governs streams that are opened using a HEADERS frame 924 and streams that are reserved using PUSH_PROMISE. An endpoint that 925 receives an unexpected stream identifier MUST respond with a 926 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 928 A HEADERS frame will transition the client-initiated stream 929 identified by the stream identifier in the frame header from "idle" 930 to "open". A PUSH_PROMISE frame will transition the server-initiated 931 stream identified by the "Promised Stream ID" field in the frame 932 payload from "idle" to "reserved". When a stream transitions out of 933 the "idle" state, all "idle" streams that might have been opened by 934 the peer with a lower-valued stream identifier immediately transition 935 to "closed". That is, an endpoint may skip a stream identifier, with 936 the effect being that the skipped stream is immediately closed. 938 Stream identifiers cannot be reused. Long-lived connections can 939 result in an endpoint exhausting the available range of stream 940 identifiers. A client that is unable to establish a new stream 941 identifier can establish a new connection for new streams. A server 942 that is unable to establish a new stream identifier can send a GOAWAY 943 frame so that the client is forced to open a new connection for new 944 streams. 946 5.1.2. Stream Concurrency 948 A peer can limit the number of concurrently active streams using the 949 SETTINGS_MAX_CONCURRENT_STREAMS parameter (see Section 6.5.2) within 950 a SETTINGS frame. The maximum concurrent streams setting is specific 951 to each endpoint and applies only to the peer that receives the 952 setting. That is, clients specify the maximum number of concurrent 953 streams the server can initiate, and servers specify the maximum 954 number of concurrent streams the client can initiate. 956 Streams that are in the "open" state or in either of the "half- 957 closed" states count toward the maximum number of streams that an 958 endpoint is permitted to open. Streams in any of these three states 959 count toward the limit advertised in the 960 SETTINGS_MAX_CONCURRENT_STREAMS setting. Streams in either of the 961 "reserved" states do not count toward the stream limit. 963 Endpoints MUST NOT exceed the limit set by their peer. An endpoint 964 that receives a HEADERS frame that causes its advertised concurrent 965 stream limit to be exceeded MUST treat this as a stream error 966 (Section 5.4.2) of type PROTOCOL_ERROR or REFUSED_STREAM. The choice 967 of error code determines whether the endpoint wishes to enable 968 automatic retry (see Section 8.7 for details). 970 An endpoint that wishes to reduce the value of 971 SETTINGS_MAX_CONCURRENT_STREAMS to a value that is below the current 972 number of open streams can either close streams that exceed the new 973 value or allow streams to complete. 975 5.2. Flow Control 977 Using streams for multiplexing introduces contention over use of the 978 TCP connection, resulting in blocked streams. A flow-control scheme 979 ensures that streams on the same connection do not destructively 980 interfere with each other. Flow control is used for both individual 981 streams and for the connection as a whole. 983 HTTP/2 provides for flow control through use of the WINDOW_UPDATE 984 frame (Section 6.9). 986 5.2.1. Flow-Control Principles 988 HTTP/2 stream flow control aims to allow a variety of flow-control 989 algorithms to be used without requiring protocol changes. Flow 990 control in HTTP/2 has the following characteristics: 992 1. Flow control is specific to a connection. HTTP/2 flow control 993 operates between the endpoints of a single hop and not over the 994 entire end-to-end path. 996 2. Flow control is based on WINDOW_UPDATE frames. Receivers 997 advertise how many octets they are prepared to receive on a 998 stream and for the entire connection. This is a credit-based 999 scheme. 1001 3. Flow control is directional with overall control provided by the 1002 receiver. A receiver MAY choose to set any window size that it 1003 desires for each stream and for the entire connection. A sender 1004 MUST respect flow-control limits imposed by a receiver. Clients, 1005 servers, and intermediaries all independently advertise their 1006 flow-control window as a receiver and abide by the flow-control 1007 limits set by their peer when sending. 1009 4. The initial value for the flow-control window is 65,535 octets 1010 for both new streams and the overall connection. 1012 5. The frame type determines whether flow control applies to a 1013 frame. Of the frames specified in this document, only DATA 1014 frames are subject to flow control; all other frame types do not 1015 consume space in the advertised flow-control window. This 1016 ensures that important control frames are not blocked by flow 1017 control. 1019 6. An endpoint can choose to disable its own flow control, but an 1020 endpoint cannot ignore flow control signals from its peer. 1022 7. HTTP/2 defines only the format and semantics of the WINDOW_UPDATE 1023 frame (Section 6.9). This document does not stipulate how a 1024 receiver decides when to send this frame or the value that it 1025 sends, nor does it specify how a sender chooses to send packets. 1026 Implementations are able to select any algorithm that suits their 1027 needs. 1029 Implementations are also responsible for prioritizing the sending of 1030 requests and responses, choosing how to avoid head-of-line blocking 1031 for requests, and managing the creation of new streams. Algorithm 1032 choices for these could interact with any flow-control algorithm. 1034 5.2.2. Appropriate Use of Flow Control 1036 Flow control is defined to protect endpoints that are operating under 1037 resource constraints. For example, a proxy needs to share memory 1038 between many connections and also might have a slow upstream 1039 connection and a fast downstream one. Flow control addresses cases 1040 where the receiver is unable to process data on one stream yet wants 1041 to continue to process other streams in the same connection. 1043 Deployments that do not require this capability can advertise a flow- 1044 control window of the maximum size (2^31-1) and can maintain this 1045 window by sending a WINDOW_UPDATE frame when any data is received. 1046 This effectively disables flow control for that receiver. 1047 Conversely, a sender is always subject to the flow-control window 1048 advertised by the receiver. 1050 Deployments with constrained resources (for example, memory) can 1051 employ flow control to limit the amount of memory a peer can consume. 1052 Note, however, that this can lead to suboptimal use of available 1053 network resources if flow control is enabled without knowledge of the 1054 bandwidth-delay product (see [RFC7323]). 1056 Even with full awareness of the current bandwidth-delay product, 1057 implementation of flow control can be difficult. Endpoints MUST read 1058 and process HTTP/2 frames from the TCP receive buffer as soon as data 1059 is available. Failure to read promptly could lead to a deadlock when 1060 critical frames, such as WINDOW_UPDATE, are not read and acted upon. 1061 Reading frames promptly does not expose endpoints to resource 1062 exhaustion attacks as HTTP/2 flow control limits resource 1063 commitments. 1065 5.2.3. Flow Control Performance 1067 If an endpoint cannot ensure that its peer always has available flow 1068 control window space that is greater than the peer's bandwidth-delay 1069 product on this connection, its receive throughput will be limited by 1070 HTTP/2 flow control. This will result in degraded performance. 1072 Sending timely WINDOW_UPDATE frames can improve performance. 1073 Endpoints will want to balance the need to improve receive throughput 1074 with the need to manage resource exhaustion risks, and should take 1075 careful note of Section 10.5 in defining their strategy to manage 1076 window sizes. 1078 5.3. Prioritization 1080 In a multiplexed protocol like HTTP/2, prioritizing allocation of 1081 bandwidth and computation resources to streams can be critical to 1082 attaining good performance. A poor prioritization scheme can result 1083 in HTTP/2 providing poor performance. With no parallelism at the TCP 1084 layer, performance could be significantly worse than HTTP/1.1. 1086 A good prioritization scheme benefits from the application of 1087 contextual knowledge such as the content of resources, how resources 1088 are interrelated, and how those resources will be used by a peer. In 1089 particular, clients can possess knowledge about the priority of 1090 requests that is relevant to server prioritization. In those cases, 1091 having clients provide priority information can improve performance. 1093 5.3.1. Background on Priority in RFC 7540 1095 RFC 7540 defined a rich system for signaling priority of requests. 1096 However, this system proved to be complex and it was not uniformly 1097 implemented. 1099 The flexible scheme meant that it was possible for clients to express 1100 priorities in very different ways, with little consistency in the 1101 approaches that were adopted. For servers, implementing generic 1102 support for the scheme was complex. Implementation of priorities was 1103 uneven in both clients and servers. Many server deployments ignored 1104 client signals when prioritizing their handling of requests. 1106 In short, the prioritization signaling in RFC7540 [RFC7540] was not 1107 successful. 1109 5.3.2. Priority Signaling in this Document 1111 This update to HTTP/2 deprecates the priority signaling defined in 1112 RFC 7540 [RFC7540]. The bulk of the text related to priority signals 1113 is not included in this document. The description of frame fields 1114 and some of the mandatory handling is retained to ensure that 1115 implementations of this document remain interoperable with 1116 implementations that use the priority signaling described in RFC 1117 7540. 1119 A thorough description of the RFC 7540 priority scheme remains in 1120 Section 5.3 of [RFC7540]. 1122 Signaling priority information is necessary to attain good 1123 performance in many cases. Where signaling priority information is 1124 important, endpoints are encouraged to use an alternative scheme, 1125 such as [I-D.ietf-httpbis-priority]. 1127 Though the priority signaling from RFC 7540 was not widely adopted, 1128 the information it provides can still be useful in the absence of 1129 better information. Endpoints that receive priority signals in 1130 HEADERS or PRIORITY frames can benefit from applying that 1131 information. In particular, implementations that consume these 1132 signals would not benefit from discarding these priority signals in 1133 the absence of alternatives. 1135 Servers SHOULD use other contextual information in determining 1136 priority of requests in the absence of any priority signals. Servers 1137 MAY interpret the complete absence of signals as an indication that 1138 the client has not implemented the feature. The defaults described 1139 in Section 5.3.5 of [RFC7540] are known to have poor performance 1140 under most conditions and their use is unlikely to be deliberate. 1142 5.4. Error Handling 1144 HTTP/2 framing permits two classes of error: 1146 * An error condition that renders the entire connection unusable is 1147 a connection error. 1149 * An error in an individual stream is a stream error. 1151 A list of error codes is included in Section 7. 1153 It is possible that an endpoint will encounter frames that would 1154 cause multiple errors. Implementations MAY discover multiple errors 1155 during processing, but they SHOULD report at most one stream and one 1156 connection error as a result. 1158 The first stream error reported for a given stream prevents any other 1159 errors on that stream from being reported. In comparison, the 1160 protocol permits multiple GOAWAY frames, though an endpoint SHOULD 1161 report just one type of connection error unless an error is 1162 encountered during graceful shutdown. If this occurs, an endpoint 1163 MAY send an additional GOAWAY frame with the new error code, in 1164 addition to any prior GOAWAY that contained NO_ERROR. 1166 If an endpoint detects multiple different errors, it MAY choose to 1167 report any one of those errors. If a frame causes a connection 1168 error, that error MUST be reported. Additionally, an endpoint MAY 1169 use any applicable error code when it detects an error condition; a 1170 generic error code (such as PROTOCOL_ERROR or INTERNAL_ERROR) can 1171 always be used in place of more specific error codes. 1173 5.4.1. Connection Error Handling 1175 A connection error is any error that prevents further processing of 1176 the frame layer or corrupts any connection state. 1178 An endpoint that encounters a connection error SHOULD first send a 1179 GOAWAY frame (Section 6.8) with the stream identifier of the last 1180 stream that it successfully received from its peer. The GOAWAY frame 1181 includes an error code (Section 7) that indicates why the connection 1182 is terminating. After sending the GOAWAY frame for an error 1183 condition, the endpoint MUST close the TCP connection. 1185 It is possible that the GOAWAY will not be reliably received by the 1186 receiving endpoint. In the event of a connection error, GOAWAY only 1187 provides a best-effort attempt to communicate with the peer about why 1188 the connection is being terminated. 1190 An endpoint can end a connection at any time. In particular, an 1191 endpoint MAY choose to treat a stream error as a connection error. 1192 Endpoints SHOULD send a GOAWAY frame when ending a connection, 1193 providing that circumstances permit it. 1195 5.4.2. Stream Error Handling 1197 A stream error is an error related to a specific stream that does not 1198 affect processing of other streams. 1200 An endpoint that detects a stream error sends a RST_STREAM frame 1201 (Section 6.4) that contains the stream identifier of the stream where 1202 the error occurred. The RST_STREAM frame includes an error code that 1203 indicates the type of error. 1205 A RST_STREAM is the last frame that an endpoint can send on a stream. 1206 The peer that sends the RST_STREAM frame MUST be prepared to receive 1207 any frames that were sent or enqueued for sending by the remote peer. 1208 These frames can be ignored, except where they modify connection 1209 state (such as the state maintained for field section compression 1210 (Section 4.3) or flow control). 1212 Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame 1213 for any stream. However, an endpoint MAY send additional RST_STREAM 1214 frames if it receives frames on a closed stream after more than a 1215 round-trip time. This behavior is permitted to deal with misbehaving 1216 implementations. 1218 To avoid looping, an endpoint MUST NOT send a RST_STREAM in response 1219 to a RST_STREAM frame. 1221 5.4.3. Connection Termination 1223 If the TCP connection is closed or reset while streams remain in the 1224 "open" or "half-closed" states, then the affected streams cannot be 1225 automatically retried (see Section 8.7 for details). 1227 5.5. Extending HTTP/2 1229 HTTP/2 permits extension of the protocol. Within the limitations 1230 described in this section, protocol extensions can be used to provide 1231 additional services or alter any aspect of the protocol. Extensions 1232 are effective only within the scope of a single HTTP/2 connection. 1234 This applies to the protocol elements defined in this document. This 1235 does not affect the existing options for extending HTTP, such as 1236 defining new methods, status codes, or fields (see Section 16 of 1237 [HTTP]). 1239 Extensions are permitted to use new frame types (Section 4.1), new 1240 settings (Section 6.5), or new error codes (Section 7). Registries 1241 for managing these extension points are defined in Section 11 of 1242 [RFC7540]. 1244 Implementations MUST ignore unknown or unsupported values in all 1245 extensible protocol elements. Implementations MUST discard frames 1246 that have unknown or unsupported types. This means that any of these 1247 extension points can be safely used by extensions without prior 1248 arrangement or negotiation. However, extension frames that appear in 1249 the middle of a field block (Section 4.3) are not permitted; these 1250 MUST be treated as a connection error (Section 5.4.1) of type 1251 PROTOCOL_ERROR. 1253 Extensions SHOULD avoid changing protocol elements defined in this 1254 document or elements for which no extension mechanism is defined. 1255 This includes changes to the layout of frames, additions or changes 1256 to the way that frames are composed into HTTP messages (Section 8.1), 1257 the definition of pseudo-header fields, or changes to any protocol 1258 element that a compliant endpoint might treat as a connection error 1259 (Section 5.4.1). 1261 An extension that changes existing protocol elements or state MUST be 1262 negotiated before being used. For example, an extension that changes 1263 the layout of the HEADERS frame cannot be used until the peer has 1264 given a positive signal that this is acceptable. In this case, it 1265 could also be necessary to coordinate when the revised layout comes 1266 into effect. For example, treating frames other than DATA frames as 1267 flow controlled requires a change in semantics that both endpoints 1268 need to understand, so this can only be done through negotiation. 1270 This document doesn't mandate a specific method for negotiating the 1271 use of an extension but notes that a setting (Section 6.5.2) could be 1272 used for that purpose. If both peers set a value that indicates 1273 willingness to use the extension, then the extension can be used. If 1274 a setting is used for extension negotiation, the initial value MUST 1275 be defined in such a fashion that the extension is initially 1276 disabled. 1278 6. Frame Definitions 1280 This specification defines a number of frame types, each identified 1281 by a unique 8-bit type code. Each frame type serves a distinct 1282 purpose in the establishment and management either of the connection 1283 as a whole or of individual streams. 1285 The transmission of specific frame types can alter the state of a 1286 connection. If endpoints fail to maintain a synchronized view of the 1287 connection state, successful communication within the connection will 1288 no longer be possible. Therefore, it is important that endpoints 1289 have a shared comprehension of how the state is affected by the use 1290 of any given frame. 1292 6.1. DATA 1294 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 1295 octets associated with a stream. One or more DATA frames are used, 1296 for instance, to carry HTTP request or response message contents. 1298 DATA frames MAY also contain padding. Padding can be added to DATA 1299 frames to obscure the size of messages. Padding is a security 1300 feature; see Section 10.7. 1302 DATA Frame { 1303 Length (24), 1304 Type (8) = 0x0, 1306 Unused Flags (4), 1307 PADDED Flag (1), 1308 Unused Flags (2), 1309 END_STREAM Flag (1), 1311 Reserved (1), 1312 Stream Identifier (31), 1314 [Pad Length (8)], 1315 Data (..), 1316 Padding (..2040), 1317 } 1318 Figure 3: DATA Frame Format 1320 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1321 fields are described in Section 4. The DATA frame contains the 1322 following additional fields: 1324 Pad Length: An 8-bit field containing the length of the frame 1325 padding in units of octets. This field is conditional and is only 1326 present if the PADDED flag is set. 1328 Data: Application data. The amount of data is the remainder of the 1329 frame payload after subtracting the length of the other fields 1330 that are present. 1332 Padding: Padding octets that contain no application semantic value. 1333 Padding octets MUST be set to zero when sending. A receiver is 1334 not obligated to verify padding but MAY treat non-zero padding as 1335 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1337 The DATA frame defines the following flags: 1339 PADDED (0x8): When set, the PADDED flag indicates that the Pad 1340 Length field and any padding that it describes are present. 1342 END_STREAM (0x1): When set, the END_STREAM flag indicates that this 1343 frame is the last that the endpoint will send for the identified 1344 stream. Setting this flag causes the stream to enter one of the 1345 "half-closed" states or the "closed" state (Section 5.1). 1347 | Note: An endpoint that learns of stream closure after sending 1348 | all data can close a stream by sending a STREAM frame with a 1349 | zero-length Data field and the END_STREAM flag set. This is 1350 | only possible if the endpoint does not send trailers as the 1351 | END_STREAM flag appears on a HEADERS frame in that case; see 1352 | Section 8.1. 1354 DATA frames MUST be associated with a stream. If a DATA frame is 1355 received whose stream identifier field is 0x0, the recipient MUST 1356 respond with a connection error (Section 5.4.1) of type 1357 PROTOCOL_ERROR. 1359 DATA frames are subject to flow control and can only be sent when a 1360 stream is in the "open" or "half-closed (remote)" state. The entire 1361 DATA frame payload is included in flow control, including the Pad 1362 Length and Padding fields if present. If a DATA frame is received 1363 whose stream is not in "open" or "half-closed (local)" state, the 1364 recipient MUST respond with a stream error (Section 5.4.2) of type 1365 STREAM_CLOSED. 1367 The total number of padding octets is determined by the value of the 1368 Pad Length field. If the length of the padding is the length of the 1369 frame payload or greater, the recipient MUST treat this as a 1370 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1372 | Note: A frame can be increased in size by one octet by 1373 | including a Pad Length field with a value of zero. 1375 6.2. HEADERS 1377 The HEADERS frame (type=0x1) is used to open a stream (Section 5.1), 1378 and additionally carries a field block fragment. Despite the name, a 1379 HEADERS frame can carry a header section or a trailer section. 1380 HEADERS frames can be sent on a stream in the "idle", "reserved 1381 (local)", "open", or "half-closed (remote)" state. 1383 HEADERS Frame { 1384 Length (24), 1385 Type (8) = 0x1, 1387 Unused Flags (2), 1388 PRIORITY Flag (1), 1389 Unused Flag (1), 1390 PADDED Flag (1), 1391 END_HEADERS Flag (1), 1392 Unused Flag (1), 1393 END_STREAM Flag (1), 1395 Reserved (1), 1396 Stream Identifier (31), 1398 [Pad Length (8)], 1399 [Exclusive (1)], 1400 [Stream Dependency (31)], 1401 [Weight (8)], 1402 Field Block Fragment (..), 1403 Padding (..2040), 1404 } 1406 Figure 4: HEADERS Frame Format 1408 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1409 fields are described in Section 4. The HEADERS frame payload has the 1410 following additional fields: 1412 Pad Length: An 8-bit field containing the length of the frame 1413 padding in units of octets. This field is only present if the 1414 PADDED flag is set. 1416 Exclusive: A single-bit flag. This field is only present if the 1417 PRIORITY flag is set. Priority signals in HEADERS frames are 1418 deprecated; see Section 5.3.2. 1420 Stream Dependency: A 31-bit stream identifier. This field is only 1421 present if the PRIORITY flag is set. 1423 Weight: An unsigned 8-bit integer. This field is only present if 1424 the PRIORITY flag is set. 1426 Field Block Fragment: A field block fragment (Section 4.3). 1428 Padding: Padding octets that contain no application semantic value. 1429 Padding octets MUST be set to zero when sending. A receiver is 1430 not obligated to verify padding but MAY treat non-zero padding as 1431 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1433 The HEADERS frame defines the following flags: 1435 PRIORITY (0x20): When set, the PRIORITY flag indicates that the 1436 Exclusive, Stream Dependency, and Weight fields are present. 1438 PADDED (0x8): When set, the PADDED flag indicates that the Pad 1439 Length field and any padding that it describes are present. 1441 END_HEADERS (0x4): When set, the END_HEADERS flag indicates that 1442 this frame contains an entire field block (Section 4.3) and is not 1443 followed by any CONTINUATION frames. 1445 A HEADERS frame without the END_HEADERS flag set MUST be followed 1446 by a CONTINUATION frame for the same stream. A receiver MUST 1447 treat the receipt of any other type of frame or a frame on a 1448 different stream as a connection error (Section 5.4.1) of type 1449 PROTOCOL_ERROR. 1451 END_STREAM (0x1): When set, the END_STREAM flag indicates that the 1452 field block (Section 4.3) is the last that the endpoint will send 1453 for the identified stream. 1455 A HEADERS frame with the END_STREAM flag set signals the end of a 1456 stream. However, a HEADERS frame with the END_STREAM flag set can 1457 be followed by CONTINUATION frames on the same stream. Logically, 1458 the CONTINUATION frames are part of the HEADERS frame. 1460 The frame payload of a HEADERS frame contains a field block fragment 1461 (Section 4.3). A field block that does not fit within a HEADERS 1462 frame is continued in a CONTINUATION frame (Section 6.10). 1464 HEADERS frames MUST be associated with a stream. If a HEADERS frame 1465 is received whose stream identifier field is 0x0, the recipient MUST 1466 respond with a connection error (Section 5.4.1) of type 1467 PROTOCOL_ERROR. 1469 The HEADERS frame changes the connection state as described in 1470 Section 4.3. 1472 The total number of padding octets is determined by the value of the 1473 Pad Length field. If the length of the padding is the length of the 1474 frame payload or greater, the recipient MUST treat this as a 1475 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1477 | Note: A frame can be increased in size by one octet by 1478 | including a Pad Length field with a value of zero. 1480 6.3. PRIORITY 1482 The PRIORITY frame (type=0x2) is deprecated; see Section 5.3.2. A 1483 PRIORITY frame can be sent in any stream state, including idle or 1484 closed streams. 1486 PRIORITY Frame { 1487 Length (24) = 0x5, 1488 Type (8) = 0x2, 1490 Unused Flags (8), 1492 Reserved (1), 1493 Stream Identifier (31), 1495 Exclusive (1), 1496 Stream Dependency (31), 1497 Weight (8), 1498 } 1500 Figure 5: PRIORITY Frame Format 1502 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1503 fields are described in Section 4. The frame payload of a PRIORITY 1504 frame contains the following additional fields: 1506 Exclusive: A single-bit flag. 1508 Stream Dependency: A 31-bit stream identifier. 1510 Weight: An unsigned 8-bit integer. 1512 The PRIORITY frame does not define any flags. 1514 The PRIORITY frame always identifies a stream. If a PRIORITY frame 1515 is received with a stream identifier of 0x0, the recipient MUST 1516 respond with a connection error (Section 5.4.1) of type 1517 PROTOCOL_ERROR. 1519 Sending or receiving a PRIORITY frame does not affect the state of 1520 any stream (Section 5.1). The PRIORITY frame can be sent on a stream 1521 in any state, including "idle" or "closed". A PRIORITY frame cannot 1522 be sent between consecutive frames that comprise a single field block 1523 (Section 4.3). 1525 A PRIORITY frame with a length other than 5 octets MUST be treated as 1526 a stream error (Section 5.4.2) of type FRAME_SIZE_ERROR. 1528 6.4. RST_STREAM 1530 The RST_STREAM frame (type=0x3) allows for immediate termination of a 1531 stream. RST_STREAM is sent to request cancellation of a stream or to 1532 indicate that an error condition has occurred. 1534 RST_STREAM Frame { 1535 Length (24) = 0x4, 1536 Type (8) = 0x3, 1538 Unused Flags (8), 1540 Reserved (1), 1541 Stream Identifier (31), 1543 Error Code (32), 1544 } 1546 Figure 6: RST_STREAM Frame Format 1548 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1549 fields are described in Section 4. Additionally, the RST_STREAM 1550 frame contains a single unsigned, 32-bit integer identifying the 1551 error code (Section 7). The error code indicates why the stream is 1552 being terminated. 1554 The RST_STREAM frame does not define any flags. 1556 The RST_STREAM frame fully terminates the referenced stream and 1557 causes it to enter the "closed" state. After receiving a RST_STREAM 1558 on a stream, the receiver MUST NOT send additional frames for that 1559 stream, except for PRIORITY. However, after sending the RST_STREAM, 1560 the sending endpoint MUST be prepared to receive and process 1561 additional frames sent on the stream that might have been sent by the 1562 peer prior to the arrival of the RST_STREAM. 1564 RST_STREAM frames MUST be associated with a stream. If a RST_STREAM 1565 frame is received with a stream identifier of 0x0, the recipient MUST 1566 treat this as a connection error (Section 5.4.1) of type 1567 PROTOCOL_ERROR. 1569 RST_STREAM frames MUST NOT be sent for a stream in the "idle" state. 1570 If a RST_STREAM frame identifying an idle stream is received, the 1571 recipient MUST treat this as a connection error (Section 5.4.1) of 1572 type PROTOCOL_ERROR. 1574 A RST_STREAM frame with a length other than 4 octets MUST be treated 1575 as a connection error (Section 5.4.1) of type FRAME_SIZE_ERROR. 1577 6.5. SETTINGS 1579 The SETTINGS frame (type=0x4) conveys configuration parameters that 1580 affect how endpoints communicate, such as preferences and constraints 1581 on peer behavior. The SETTINGS frame is also used to acknowledge the 1582 receipt of those settings. Individually, a configuration parameter 1583 from a SETTINGS frame is referred to as a "setting". 1585 Settings are not negotiated; they describe characteristics of the 1586 sending peer, which are used by the receiving peer. Different values 1587 for the same setting can be advertised by each peer. For example, a 1588 client might set a high initial flow-control window, whereas a server 1589 might set a lower value to conserve resources. 1591 A SETTINGS frame MUST be sent by both endpoints at the start of a 1592 connection and MAY be sent at any other time by either endpoint over 1593 the lifetime of the connection. Implementations MUST support all of 1594 the settings defined by this specification. 1596 Each parameter in a SETTINGS frame replaces any existing value for 1597 that parameter. Settings are processed in the order in which they 1598 appear, and a receiver of a SETTINGS frame does not need to maintain 1599 any state other than the current value of each setting. Therefore, 1600 the value of a SETTINGS parameter is the last value that is seen by a 1601 receiver. 1603 SETTINGS frames are acknowledged by the receiving peer. To enable 1604 this, the SETTINGS frame defines the ACK flag: 1606 ACK (0x1): When set, the ACK flag indicates that this frame 1607 acknowledges receipt and application of the peer's SETTINGS frame. 1608 When this bit is set, the frame payload of the SETTINGS frame MUST 1609 be empty. Receipt of a SETTINGS frame with the ACK flag set and a 1610 length field value other than 0 MUST be treated as a connection 1611 error (Section 5.4.1) of type FRAME_SIZE_ERROR. For more 1612 information, see Section 6.5.3 ("Settings Synchronization"). 1614 SETTINGS frames always apply to a connection, never a single stream. 1615 The stream identifier for a SETTINGS frame MUST be zero (0x0). If an 1616 endpoint receives a SETTINGS frame whose stream identifier field is 1617 anything other than 0x0, the endpoint MUST respond with a connection 1618 error (Section 5.4.1) of type PROTOCOL_ERROR. 1620 The SETTINGS frame affects connection state. A badly formed or 1621 incomplete SETTINGS frame MUST be treated as a connection error 1622 (Section 5.4.1) of type PROTOCOL_ERROR. 1624 A SETTINGS frame with a length other than a multiple of 6 octets MUST 1625 be treated as a connection error (Section 5.4.1) of type 1626 FRAME_SIZE_ERROR. 1628 6.5.1. SETTINGS Format 1630 The frame payload of a SETTINGS frame consists of zero or more 1631 settings, each consisting of an unsigned 16-bit setting identifier 1632 and an unsigned 32-bit value. 1634 SETTINGS Frame { 1635 Length (24), 1636 Type (8) = 0x4, 1638 Unused Flags (7), 1639 ACK Flag (1), 1641 Reserved (1), 1642 Stream Identifier (31) = 0, 1644 Setting (48) ..., 1645 } 1647 Setting { 1648 Identifier (16), 1649 Value (32), 1650 } 1652 Figure 7: SETTINGS Frame Format 1654 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1655 fields are described in Section 4. The frame payload of a SETTINGS 1656 frame contains any number of Setting fields, each of which consists 1657 of: 1659 Identifier: A 16-bit setting identifier; see Section 6.5.2. 1661 Value: A 32-bit value for the setting. 1663 6.5.2. Defined Settings 1665 The following settings are defined: 1667 SETTINGS_HEADER_TABLE_SIZE (0x1): Allows the sender to inform the 1668 remote endpoint of the maximum size of the compression table used 1669 to decode field blocks, in units of octets. The encoder can 1670 select any size equal to or less than this value by using 1671 signaling specific to the compression format inside a field block 1672 (see [COMPRESSION]). The initial value is 4,096 octets. 1674 SETTINGS_ENABLE_PUSH (0x2): This setting can be used to disable 1675 server push (Section 8.4). A server MUST NOT send a PUSH_PROMISE 1676 frame if it receives this parameter set to a value of 0. A client 1677 that has both set this parameter to 0 and had it acknowledged MUST 1678 treat the receipt of a PUSH_PROMISE frame as a connection error 1679 (Section 5.4.1) of type PROTOCOL_ERROR. 1681 The initial value of SETTINGS_ENABLE_PUSH is 1. For a client this 1682 value indicates that it is willing to receive PUSH_PROMISE frames. 1683 For a server this initial value has no effect, and is equivalent 1684 to the value 0. Any value other than 0 or 1 MUST be treated as a 1685 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1687 A server MUST NOT explicitly set this value to 1. A server MAY 1688 choose to omit this setting when it sends a SETTINGS frame, but if 1689 a server does include a value it MUST be 0. A client MUST treat 1690 receipt of a SETTINGS frame with SETTINGS_ENABLE_PUSH set to 1 as 1691 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1693 SETTINGS_MAX_CONCURRENT_STREAMS (0x3): Indicates the maximum number 1694 of concurrent streams that the sender will allow. This limit is 1695 directional: it applies to the number of streams that the sender 1696 permits the receiver to create. Initially, there is no limit to 1697 this value. It is recommended that this value be no smaller than 1698 100, so as to not unnecessarily limit parallelism. 1700 A value of 0 for SETTINGS_MAX_CONCURRENT_STREAMS SHOULD NOT be 1701 treated as special by endpoints. A zero value does prevent the 1702 creation of new streams; however, this can also happen for any 1703 limit that is exhausted with active streams. Servers SHOULD only 1704 set a zero value for short durations; if a server does not wish to 1705 accept requests, closing the connection is more appropriate. 1707 SETTINGS_INITIAL_WINDOW_SIZE (0x4): Indicates the sender's initial 1708 window size (in units of octets) for stream-level flow control. 1709 The initial value is 2^16-1 (65,535) octets. 1711 This setting affects the window size of all streams (see 1712 Section 6.9.2). 1714 Values above the maximum flow-control window size of 2^31-1 MUST 1715 be treated as a connection error (Section 5.4.1) of type 1716 FLOW_CONTROL_ERROR. 1718 SETTINGS_MAX_FRAME_SIZE (0x5): Indicates the size of the largest 1719 frame payload that the sender is willing to receive, in units of 1720 octets. 1722 The initial value is 2^14 (16,384) octets. The value advertised 1723 by an endpoint MUST be between this initial value and the maximum 1724 allowed frame size (2^24-1 or 16,777,215 octets), inclusive. 1725 Values outside this range MUST be treated as a connection error 1726 (Section 5.4.1) of type PROTOCOL_ERROR. 1728 SETTINGS_MAX_HEADER_LIST_SIZE (0x6): This advisory setting informs a 1729 peer of the maximum size of field section that the sender is 1730 prepared to accept, in units of octets. The value is based on the 1731 uncompressed size of field lines, including the length of the name 1732 and value in units of octets plus an overhead of 32 octets for 1733 each field line. 1735 For any given request, a lower limit than what is advertised MAY 1736 be enforced. The initial value of this setting is unlimited. 1738 An endpoint that receives a SETTINGS frame with any unknown or 1739 unsupported identifier MUST ignore that setting. 1741 6.5.3. Settings Synchronization 1743 Most values in SETTINGS benefit from or require an understanding of 1744 when the peer has received and applied the changed parameter values. 1745 In order to provide such synchronization timepoints, the recipient of 1746 a SETTINGS frame in which the ACK flag is not set MUST apply the 1747 updated settings as soon as possible upon receipt. SETTINGS frames 1748 are acknowledged in the order in which they are received. 1750 The values in the SETTINGS frame MUST be processed in the order they 1751 appear, with no other frame processing between values. Unsupported 1752 settings MUST be ignored. Once all values have been processed, the 1753 recipient MUST immediately emit a SETTINGS frame with the ACK flag 1754 set. Upon receiving a SETTINGS frame with the ACK flag set, the 1755 sender of the altered settings can rely on the values from the oldest 1756 unacknowledged SETTINGS frame having been applied. 1758 If the sender of a SETTINGS frame does not receive an acknowledgment 1759 within a reasonable amount of time, it MAY issue a connection error 1760 (Section 5.4.1) of type SETTINGS_TIMEOUT. In setting a timeout, some 1761 allowance needs to be made for processing delays at the peer; a 1762 timeout that is solely based on the round trip time between endpoints 1763 might result in spurious errors. 1765 6.6. PUSH_PROMISE 1767 The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint 1768 in advance of streams the sender intends to initiate. The 1769 PUSH_PROMISE frame includes the unsigned 31-bit identifier of the 1770 stream the endpoint plans to create along with a field section that 1771 provides additional context for the stream. Section 8.4 contains a 1772 thorough description of the use of PUSH_PROMISE frames. 1774 PUSH_PROMISE Frame { 1775 Length (24), 1776 Type (8) = 0x5, 1778 Unused Flags (4), 1779 PADDED Flag (1), 1780 END_HEADERS Flag (1), 1781 Unused Flags (2), 1783 Reserved (1), 1784 Stream Identifier (31), 1786 [Pad Length (8)], 1787 Reserved (1), 1788 Promised Stream ID (31), 1789 Field Block Fragment (..), 1790 Padding (..2040), 1791 } 1793 Figure 8: PUSH_PROMISE Frame Format 1795 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1796 fields are described in Section 4. The PUSH_PROMISE frame payload 1797 has the following additional fields: 1799 Pad Length: An 8-bit field containing the length of the frame 1800 padding in units of octets. This field is only present if the 1801 PADDED flag is set. 1803 Reserved: A single reserved bit. 1805 Promised Stream ID: An unsigned 31-bit integer that identifies the 1806 stream that is reserved by the PUSH_PROMISE. The promised stream 1807 identifier MUST be a valid choice for the next stream sent by the 1808 sender (see "new stream identifier" in Section 5.1.1). 1810 Field Block Fragment: A field block fragment (Section 4.3) 1811 containing request control data and header section. 1813 Padding: Padding octets that contain no application semantic value. 1814 Padding octets MUST be set to zero when sending. A receiver is 1815 not obligated to verify padding but MAY treat non-zero padding as 1816 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1818 The PUSH_PROMISE frame defines the following flags: 1820 PADDED (0x8): When set, the PADDED flag indicates that the Pad 1821 Length field and any padding that it describes are present. 1823 END_HEADERS (0x4): When set, the END_HEADERS flag indicates that 1824 this frame contains an entire field block (Section 4.3) and is not 1825 followed by any CONTINUATION frames. 1827 A PUSH_PROMISE frame without the END_HEADERS flag set MUST be 1828 followed by a CONTINUATION frame for the same stream. A receiver 1829 MUST treat the receipt of any other type of frame or a frame on a 1830 different stream as a connection error (Section 5.4.1) of type 1831 PROTOCOL_ERROR. 1833 PUSH_PROMISE frames MUST only be sent on a peer-initiated stream that 1834 is in either the "open" or "half-closed (remote)" state. The stream 1835 identifier of a PUSH_PROMISE frame indicates the stream it is 1836 associated with. If the stream identifier field specifies the value 1837 0x0, a recipient MUST respond with a connection error (Section 5.4.1) 1838 of type PROTOCOL_ERROR. 1840 Promised streams are not required to be used in the order they are 1841 promised. The PUSH_PROMISE only reserves stream identifiers for 1842 later use. 1844 PUSH_PROMISE MUST NOT be sent if the SETTINGS_ENABLE_PUSH setting of 1845 the peer endpoint is set to 0. An endpoint that has set this setting 1846 and has received acknowledgment MUST treat the receipt of a 1847 PUSH_PROMISE frame as a connection error (Section 5.4.1) of type 1848 PROTOCOL_ERROR. 1850 Recipients of PUSH_PROMISE frames can choose to reject promised 1851 streams by returning a RST_STREAM referencing the promised stream 1852 identifier back to the sender of the PUSH_PROMISE. 1854 A PUSH_PROMISE frame modifies the connection state in two ways. 1855 First, the inclusion of a field block (Section 4.3) potentially 1856 modifies the state maintained for field section compression. Second, 1857 PUSH_PROMISE also reserves a stream for later use, causing the 1858 promised stream to enter the "reserved" state. A sender MUST NOT 1859 send a PUSH_PROMISE on a stream unless that stream is either "open" 1860 or "half-closed (remote)"; the sender MUST ensure that the promised 1861 stream is a valid choice for a new stream identifier (Section 5.1.1) 1862 (that is, the promised stream MUST be in the "idle" state). 1864 Since PUSH_PROMISE reserves a stream, ignoring a PUSH_PROMISE frame 1865 causes the stream state to become indeterminate. A receiver MUST 1866 treat the receipt of a PUSH_PROMISE on a stream that is neither 1867 "open" nor "half-closed (local)" as a connection error 1868 (Section 5.4.1) of type PROTOCOL_ERROR. However, an endpoint that 1869 has sent RST_STREAM on the associated stream MUST handle PUSH_PROMISE 1870 frames that might have been created before the RST_STREAM frame is 1871 received and processed. 1873 A receiver MUST treat the receipt of a PUSH_PROMISE that promises an 1874 illegal stream identifier (Section 5.1.1) as a connection error 1875 (Section 5.4.1) of type PROTOCOL_ERROR. Note that an illegal stream 1876 identifier is an identifier for a stream that is not currently in the 1877 "idle" state. 1879 The total number of padding octets is determined by the value of the 1880 Pad Length field. If the length of the padding is the length of the 1881 frame payload or greater, the recipient MUST treat this as a 1882 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1884 | Note: A frame can be increased in size by one octet by 1885 | including a Pad Length field with a value of zero. 1887 6.7. PING 1889 The PING frame (type=0x6) is a mechanism for measuring a minimal 1890 round-trip time from the sender, as well as determining whether an 1891 idle connection is still functional. PING frames can be sent from 1892 any endpoint. 1894 PING Frame { 1895 Length (24) = 0x8, 1896 Type (8) = 0x6, 1898 Unused Flags (7), 1899 ACK Flag (1), 1901 Reserved (1), 1902 Stream Identifier (31) = 0, 1904 Opaque Data (64), 1905 } 1907 Figure 9: PING Frame Format 1909 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1910 fields are described in Section 4. 1912 In addition to the frame header, PING frames MUST contain 8 octets of 1913 opaque data in the frame payload. A sender can include any value it 1914 chooses and use those octets in any fashion. 1916 Receivers of a PING frame that does not include an ACK flag MUST send 1917 a PING frame with the ACK flag set in response, with an identical 1918 frame payload. PING responses SHOULD be given higher priority than 1919 any other frame. 1921 The PING frame defines the following flags: 1923 ACK (0x1): When set, the ACK flag indicates that this PING frame is 1924 a PING response. An endpoint MUST set this flag in PING 1925 responses. An endpoint MUST NOT respond to PING frames containing 1926 this flag. 1928 PING frames are not associated with any individual stream. If a PING 1929 frame is received with a stream identifier field value other than 1930 0x0, the recipient MUST respond with a connection error 1931 (Section 5.4.1) of type PROTOCOL_ERROR. 1933 Receipt of a PING frame with a length field value other than 8 MUST 1934 be treated as a connection error (Section 5.4.1) of type 1935 FRAME_SIZE_ERROR. 1937 6.8. GOAWAY 1939 The GOAWAY frame (type=0x7) is used to initiate shutdown of a 1940 connection or to signal serious error conditions. GOAWAY allows an 1941 endpoint to gracefully stop accepting new streams while still 1942 finishing processing of previously established streams. This enables 1943 administrative actions, like server maintenance. 1945 There is an inherent race condition between an endpoint starting new 1946 streams and the remote sending a GOAWAY frame. To deal with this 1947 case, the GOAWAY contains the stream identifier of the last peer- 1948 initiated stream that was or might be processed on the sending 1949 endpoint in this connection. For instance, if the server sends a 1950 GOAWAY frame, the identified stream is the highest-numbered stream 1951 initiated by the client. 1953 Once sent, the sender will ignore frames sent on streams initiated by 1954 the receiver if the stream has an identifier higher than the included 1955 last stream identifier. Receivers of a GOAWAY frame MUST NOT open 1956 additional streams on the connection, although a new connection can 1957 be established for new streams. 1959 If the receiver of the GOAWAY has sent data on streams with a higher 1960 stream identifier than what is indicated in the GOAWAY frame, those 1961 streams are not or will not be processed. The receiver of the GOAWAY 1962 frame can treat the streams as though they had never been created at 1963 all, thereby allowing those streams to be retried later on a new 1964 connection. 1966 Endpoints SHOULD always send a GOAWAY frame before closing a 1967 connection so that the remote peer can know whether a stream has been 1968 partially processed or not. For example, if an HTTP client sends a 1969 POST at the same time that a server closes a connection, the client 1970 cannot know if the server started to process that POST request if the 1971 server does not send a GOAWAY frame to indicate what streams it might 1972 have acted on. 1974 An endpoint might choose to close a connection without sending a 1975 GOAWAY for misbehaving peers. 1977 A GOAWAY frame might not immediately precede closing of the 1978 connection; a receiver of a GOAWAY that has no more use for the 1979 connection SHOULD still send a GOAWAY frame before terminating the 1980 connection. 1982 GOAWAY Frame { 1983 Length (24), 1984 Type (8) = 0x7, 1986 Unused Flags (8), 1988 Reserved (1), 1989 Stream Identifier (31) = 0, 1991 Reserved (1), 1992 Last-Stream-ID (31), 1993 Error Code (32), 1994 Additional Debug Data (..), 1995 } 1997 Figure 10: GOAWAY Frame Format 1999 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 2000 fields are described in Section 4. 2002 The GOAWAY frame does not define any flags. 2004 The GOAWAY frame applies to the connection, not a specific stream. 2005 An endpoint MUST treat a GOAWAY frame with a stream identifier other 2006 than 0x0 as a connection error (Section 5.4.1) of type 2007 PROTOCOL_ERROR. 2009 The last stream identifier in the GOAWAY frame contains the highest- 2010 numbered stream identifier for which the sender of the GOAWAY frame 2011 might have taken some action on or might yet take action on. All 2012 streams up to and including the identified stream might have been 2013 processed in some way. The last stream identifier can be set to 0 if 2014 no streams were processed. 2016 | Note: In this context, "processed" means that some data from 2017 | the stream was passed to some higher layer of software that 2018 | might have taken some action as a result. 2020 If a connection terminates without a GOAWAY frame, the last stream 2021 identifier is effectively the highest possible stream identifier. 2023 On streams with lower- or equal-numbered identifiers that were not 2024 closed completely prior to the connection being closed, reattempting 2025 requests, transactions, or any protocol activity is not possible, 2026 except for idempotent actions like HTTP GET, PUT, or DELETE. Any 2027 protocol activity that uses higher-numbered streams can be safely 2028 retried using a new connection. 2030 Activity on streams numbered lower or equal to the last stream 2031 identifier might still complete successfully. The sender of a GOAWAY 2032 frame might gracefully shut down a connection by sending a GOAWAY 2033 frame, maintaining the connection in an "open" state until all in- 2034 progress streams complete. 2036 An endpoint MAY send multiple GOAWAY frames if circumstances change. 2037 For instance, an endpoint that sends GOAWAY with NO_ERROR during 2038 graceful shutdown could subsequently encounter a condition that 2039 requires immediate termination of the connection. The last stream 2040 identifier from the last GOAWAY frame received indicates which 2041 streams could have been acted upon. Endpoints MUST NOT increase the 2042 value they send in the last stream identifier, since the peers might 2043 already have retried unprocessed requests on another connection. 2045 A client that is unable to retry requests loses all requests that are 2046 in flight when the server closes the connection. This is especially 2047 true for intermediaries that might not be serving clients using 2048 HTTP/2. A server that is attempting to gracefully shut down a 2049 connection SHOULD send an initial GOAWAY frame with the last stream 2050 identifier set to 2^31-1 and a NO_ERROR code. This signals to the 2051 client that a shutdown is imminent and that initiating further 2052 requests is prohibited. After allowing time for any in-flight stream 2053 creation (at least one round-trip time), the server MAY send another 2054 GOAWAY frame with an updated last stream identifier. This ensures 2055 that a connection can be cleanly shut down without losing requests. 2057 After sending a GOAWAY frame, the sender can discard frames for 2058 streams initiated by the receiver with identifiers higher than the 2059 identified last stream. However, any frames that alter connection 2060 state cannot be completely ignored. For instance, HEADERS, 2061 PUSH_PROMISE, and CONTINUATION frames MUST be minimally processed to 2062 ensure the state maintained for field section compression is 2063 consistent (see Section 4.3); similarly, DATA frames MUST be counted 2064 toward the connection flow-control window. Failure to process these 2065 frames can cause flow control or field section compression state to 2066 become unsynchronized. 2068 The GOAWAY frame also contains a 32-bit error code (Section 7) that 2069 contains the reason for closing the connection. 2071 Endpoints MAY append opaque data to the frame payload of any GOAWAY 2072 frame. Additional debug data is intended for diagnostic purposes 2073 only and carries no semantic value. Debug information could contain 2074 security- or privacy-sensitive data. Logged or otherwise 2075 persistently stored debug data MUST have adequate safeguards to 2076 prevent unauthorized access. 2078 6.9. WINDOW_UPDATE 2080 The WINDOW_UPDATE frame (type=0x8) is used to implement flow control; 2081 see Section 5.2 for an overview. 2083 Flow control operates at two levels: on each individual stream and on 2084 the entire connection. 2086 Both types of flow control are hop by hop, that is, only between the 2087 two endpoints. Intermediaries do not forward WINDOW_UPDATE frames 2088 between dependent connections. However, throttling of data transfer 2089 by any receiver can indirectly cause the propagation of flow-control 2090 information toward the original sender. 2092 Flow control only applies to frames that are identified as being 2093 subject to flow control. Of the frame types defined in this 2094 document, this includes only DATA frames. Frames that are exempt 2095 from flow control MUST be accepted and processed, unless the receiver 2096 is unable to assign resources to handling the frame. A receiver MAY 2097 respond with a stream error (Section 5.4.2) or connection error 2098 (Section 5.4.1) of type FLOW_CONTROL_ERROR if it is unable to accept 2099 a frame. 2101 WINDOW_UPDATE Frame { 2102 Length (24) = 0x4, 2103 Type (8) = 0x8, 2105 Unused Flags (8), 2107 Reserved (1), 2108 Stream Identifier (31), 2110 Reserved (1), 2111 Window Size Increment (31), 2112 } 2114 Figure 11: WINDOW_UPDATE Frame Format 2116 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 2117 fields are described in Section 4. The frame payload of a 2118 WINDOW_UPDATE frame is one reserved bit plus an unsigned 31-bit 2119 integer indicating the number of octets that the sender can transmit 2120 in addition to the existing flow-control window. The legal range for 2121 the increment to the flow-control window is 1 to 2^31-1 2122 (2,147,483,647) octets. 2124 The WINDOW_UPDATE frame does not define any flags. 2126 The WINDOW_UPDATE frame can be specific to a stream or to the entire 2127 connection. In the former case, the frame's stream identifier 2128 indicates the affected stream; in the latter, the value "0" indicates 2129 that the entire connection is the subject of the frame. 2131 A receiver MUST treat the receipt of a WINDOW_UPDATE frame with a 2132 flow-control window increment of 0 as a stream error (Section 5.4.2) 2133 of type PROTOCOL_ERROR; errors on the connection flow-control window 2134 MUST be treated as a connection error (Section 5.4.1). 2136 WINDOW_UPDATE can be sent by a peer that has sent a frame with the 2137 END_STREAM flag set. This means that a receiver could receive a 2138 WINDOW_UPDATE frame on a "half-closed (remote)" or "closed" stream. 2139 A receiver MUST NOT treat this as an error (see Section 5.1). 2141 A receiver that receives a flow-controlled frame MUST always account 2142 for its contribution against the connection flow-control window, 2143 unless the receiver treats this as a connection error 2144 (Section 5.4.1). This is necessary even if the frame is in error. 2145 The sender counts the frame toward the flow-control window, but if 2146 the receiver does not, the flow-control window at the sender and 2147 receiver can become different. 2149 A WINDOW_UPDATE frame with a length other than 4 octets MUST be 2150 treated as a connection error (Section 5.4.1) of type 2151 FRAME_SIZE_ERROR. 2153 6.9.1. The Flow-Control Window 2155 Flow control in HTTP/2 is implemented using a window kept by each 2156 sender on every stream. The flow-control window is a simple integer 2157 value that indicates how many octets of data the sender is permitted 2158 to transmit; as such, its size is a measure of the buffering capacity 2159 of the receiver. 2161 Two flow-control windows are applicable: the stream flow-control 2162 window and the connection flow-control window. The sender MUST NOT 2163 send a flow-controlled frame with a length that exceeds the space 2164 available in either of the flow-control windows advertised by the 2165 receiver. Frames with zero length with the END_STREAM flag set (that 2166 is, an empty DATA frame) MAY be sent if there is no available space 2167 in either flow-control window. 2169 For flow-control calculations, the 9-octet frame header is not 2170 counted. 2172 After sending a flow-controlled frame, the sender reduces the space 2173 available in both windows by the length of the transmitted frame. 2175 The receiver of a frame sends a WINDOW_UPDATE frame as it consumes 2176 data and frees up space in flow-control windows. Separate 2177 WINDOW_UPDATE frames are sent for the stream- and connection-level 2178 flow-control windows. Receivers are advised to have mechanisms in 2179 place to avoid sending WINDOW_UPDATE frames with very small 2180 increments; see Section 4.2.3.3 of [RFC1122]. 2182 A sender that receives a WINDOW_UPDATE frame updates the 2183 corresponding window by the amount specified in the frame. 2185 A sender MUST NOT allow a flow-control window to exceed 2^31-1 2186 octets. If a sender receives a WINDOW_UPDATE that causes a flow- 2187 control window to exceed this maximum, it MUST terminate either the 2188 stream or the connection, as appropriate. For streams, the sender 2189 sends a RST_STREAM with an error code of FLOW_CONTROL_ERROR; for the 2190 connection, a GOAWAY frame with an error code of FLOW_CONTROL_ERROR 2191 is sent. 2193 Flow-controlled frames from the sender and WINDOW_UPDATE frames from 2194 the receiver are completely asynchronous with respect to each other. 2195 This property allows a receiver to aggressively update the window 2196 size kept by the sender to prevent streams from stalling. 2198 6.9.2. Initial Flow-Control Window Size 2200 When an HTTP/2 connection is first established, new streams are 2201 created with an initial flow-control window size of 65,535 octets. 2202 The connection flow-control window is also 65,535 octets. Both 2203 endpoints can adjust the initial window size for new streams by 2204 including a value for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS 2205 frame. The connection flow-control window can only be changed using 2206 WINDOW_UPDATE frames. 2208 Prior to receiving a SETTINGS frame that sets a value for 2209 SETTINGS_INITIAL_WINDOW_SIZE, an endpoint can only use the default 2210 initial window size when sending flow-controlled frames. Similarly, 2211 the connection flow-control window is set based on the default 2212 initial window size until a WINDOW_UPDATE frame is received. 2214 In addition to changing the flow-control window for streams that are 2215 not yet active, a SETTINGS frame can alter the initial flow-control 2216 window size for streams with active flow-control windows (that is, 2217 streams in the "open" or "half-closed (remote)" state). When the 2218 value of SETTINGS_INITIAL_WINDOW_SIZE changes, a receiver MUST adjust 2219 the size of all stream flow-control windows that it maintains by the 2220 difference between the new value and the old value. 2222 A change to SETTINGS_INITIAL_WINDOW_SIZE can cause the available 2223 space in a flow-control window to become negative. A sender MUST 2224 track the negative flow-control window and MUST NOT send new flow- 2225 controlled frames until it receives WINDOW_UPDATE frames that cause 2226 the flow-control window to become positive. 2228 For example, if the client sends 60 KB immediately on connection 2229 establishment and the server sets the initial window size to be 16 2230 KB, the client will recalculate the available flow-control window to 2231 be -44 KB on receipt of the SETTINGS frame. The client retains a 2232 negative flow-control window until WINDOW_UPDATE frames restore the 2233 window to being positive, after which the client can resume sending. 2235 A SETTINGS frame cannot alter the connection flow-control window. 2237 An endpoint MUST treat a change to SETTINGS_INITIAL_WINDOW_SIZE that 2238 causes any flow-control window to exceed the maximum size as a 2239 connection error (Section 5.4.1) of type FLOW_CONTROL_ERROR. 2241 6.9.3. Reducing the Stream Window Size 2243 A receiver that wishes to use a smaller flow-control window than the 2244 current size can send a new SETTINGS frame. However, the receiver 2245 MUST be prepared to receive data that exceeds this window size, since 2246 the sender might send data that exceeds the lower limit prior to 2247 processing the SETTINGS frame. 2249 After sending a SETTINGS frame that reduces the initial flow-control 2250 window size, a receiver MAY continue to process streams that exceed 2251 flow-control limits. Allowing streams to continue does not allow the 2252 receiver to immediately reduce the space it reserves for flow-control 2253 windows. Progress on these streams can also stall, since 2254 WINDOW_UPDATE frames are needed to allow the sender to resume 2255 sending. The receiver MAY instead send a RST_STREAM with an error 2256 code of FLOW_CONTROL_ERROR for the affected streams. 2258 6.10. CONTINUATION 2260 The CONTINUATION frame (type=0x9) is used to continue a sequence of 2261 field block fragments (Section 4.3). Any number of CONTINUATION 2262 frames can be sent, as long as the preceding frame is on the same 2263 stream and is a HEADERS, PUSH_PROMISE, or CONTINUATION frame without 2264 the END_HEADERS flag set. 2266 CONTINUATION Frame { 2267 Length (24), 2268 Type (8) = 0x9, 2270 Unused Flags (5), 2271 END_HEADERS Flag (1), 2272 Unused Flags (2), 2274 Reserved (1), 2275 Stream Identifier (31), 2277 Field Block Fragment (..), 2278 } 2280 Figure 12: CONTINUATION Frame Format 2282 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 2283 fields are described in Section 4. The CONTINUATION frame payload 2284 contains a field block fragment (Section 4.3). 2286 The CONTINUATION frame defines the following flag: 2288 END_HEADERS (0x4): When set, the END_HEADERS flag indicates that 2289 this frame ends a field block (Section 4.3). 2291 If the END_HEADERS flag is not set, this frame MUST be followed by 2292 another CONTINUATION frame. A receiver MUST treat the receipt of 2293 any other type of frame or a frame on a different stream as a 2294 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 2296 The CONTINUATION frame changes the connection state as defined in 2297 Section 4.3. 2299 CONTINUATION frames MUST be associated with a stream. If a 2300 CONTINUATION frame is received whose stream identifier field is 0x0, 2301 the recipient MUST respond with a connection error (Section 5.4.1) of 2302 type PROTOCOL_ERROR. 2304 A CONTINUATION frame MUST be preceded by a HEADERS, PUSH_PROMISE or 2305 CONTINUATION frame without the END_HEADERS flag set. A recipient 2306 that observes violation of this rule MUST respond with a connection 2307 error (Section 5.4.1) of type PROTOCOL_ERROR. 2309 7. Error Codes 2311 Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY 2312 frames to convey the reasons for the stream or connection error. 2314 Error codes share a common code space. Some error codes apply only 2315 to either streams or the entire connection and have no defined 2316 semantics in the other context. 2318 The following error codes are defined: 2320 NO_ERROR (0x0): The associated condition is not a result of an 2321 error. For example, a GOAWAY might include this code to indicate 2322 graceful shutdown of a connection. 2324 PROTOCOL_ERROR (0x1): The endpoint detected an unspecific protocol 2325 error. This error is for use when a more specific error code is 2326 not available. 2328 INTERNAL_ERROR (0x2): The endpoint encountered an unexpected 2329 internal error. 2331 FLOW_CONTROL_ERROR (0x3): The endpoint detected that its peer 2332 violated the flow-control protocol. 2334 SETTINGS_TIMEOUT (0x4): The endpoint sent a SETTINGS frame but did 2335 not receive a response in a timely manner. See Section 6.5.3 2336 ("Settings Synchronization"). 2338 STREAM_CLOSED (0x5): The endpoint received a frame after a stream 2339 was half-closed. 2341 FRAME_SIZE_ERROR (0x6): The endpoint received a frame with an 2342 invalid size. 2344 REFUSED_STREAM (0x7): The endpoint refused the stream prior to 2345 performing any application processing (see Section 8.7 for 2346 details). 2348 CANCEL (0x8): Used by the endpoint to indicate that the stream is no 2349 longer needed. 2351 COMPRESSION_ERROR (0x9): The endpoint is unable to maintain the 2352 field section compression context for the connection. 2354 CONNECT_ERROR (0xa): The connection established in response to a 2355 CONNECT request (Section 8.5) was reset or abnormally closed. 2357 ENHANCE_YOUR_CALM (0xb): The endpoint detected that its peer is 2358 exhibiting a behavior that might be generating excessive load. 2360 INADEQUATE_SECURITY (0xc): The underlying transport has properties 2361 that do not meet minimum security requirements (see Section 9.2). 2363 HTTP_1_1_REQUIRED (0xd): The endpoint requires that HTTP/1.1 be used 2364 instead of HTTP/2. 2366 Unknown or unsupported error codes MUST NOT trigger any special 2367 behavior. These MAY be treated by an implementation as being 2368 equivalent to INTERNAL_ERROR. 2370 8. Expressing HTTP Semantics in HTTP/2 2372 HTTP/2 is an instantiation of the HTTP message abstraction (Section 6 2373 of [HTTP]). 2375 8.1. HTTP Message Framing 2377 A client sends an HTTP request on a new stream, using a previously 2378 unused stream identifier (Section 5.1.1). A server sends an HTTP 2379 response on the same stream as the request. 2381 An HTTP message (request or response) consists of: 2383 1. one HEADERS frame (followed by zero or more CONTINUATION frames) 2384 containing the header section (see Section 6.3 of [HTTP]), 2386 2. zero or more DATA frames containing the message content (see 2387 Section 6.4 of [HTTP]), and 2389 3. optionally, one HEADERS frame (followed by zero or more 2390 CONTINUATION frames) containing the trailer section, if present 2391 (see Section 6.5 of [HTTP]). 2393 For a response only, a server MAY send any number of interim 2394 responses before the HEADERS frame containing a final response. An 2395 interim response consists of a HEADERS frame (which might be followed 2396 by zero or more CONTINUATION frames) containing the control data and 2397 header section of an interim (1xx) HTTP response (see Section 15 of 2398 [HTTP]). A HEADERS frame with the END_STREAM flag set that carries 2399 an informational status code is malformed (Section 8.1.1). 2401 The last frame in the sequence bears an END_STREAM flag, noting that 2402 a HEADERS frame with the END_STREAM flag set can be followed by 2403 CONTINUATION frames that carry any remaining fragments of the field 2404 block. 2406 Other frames (from any stream) MUST NOT occur between the HEADERS 2407 frame and any CONTINUATION frames that might follow. 2409 HTTP/2 uses DATA frames to carry message content. The chunked 2410 transfer encoding defined in Section 7.1 of [HTTP11] cannot be used 2411 in HTTP/2; see Section 8.2.2. 2413 Trailer fields are carried in a field block that also terminates the 2414 stream. That is, trailer fields comprise a sequence starting with a 2415 HEADERS frame, followed by zero or more CONTINUATION frames, where 2416 the HEADERS frame bears an END_STREAM flag. Trailers MUST NOT 2417 include pseudo-header fields (Section 8.3). An endpoint that 2418 receives pseudo-header fields in trailers MUST treat the request or 2419 response as malformed (Section 8.1.1). 2421 An endpoint that receives a HEADERS frame without the END_STREAM flag 2422 set after receiving the HEADERS frame that opens a request or after 2423 receiving a final (non-informational) status code MUST treat the 2424 corresponding request or response as malformed (Section 8.1.1). 2426 An HTTP request/response exchange fully consumes a single stream. A 2427 request starts with the HEADERS frame that puts the stream into the 2428 "open" state. The request ends with a frame with the END_STREAM flag 2429 set, which causes the stream to become "half-closed (local)" for the 2430 client and "half-closed (remote)" for the server. A response stream 2431 starts with zero or more interim responses in HEADERS frames, 2432 followed by a HEADERS frame containing a final status code. 2434 An HTTP response is complete after the server sends -- or the client 2435 receives -- a frame with the END_STREAM flag set (including any 2436 CONTINUATION frames needed to complete a field block). A server can 2437 send a complete response prior to the client sending an entire 2438 request if the response does not depend on any portion of the request 2439 that has not been sent and received. When this is true, a server MAY 2440 request that the client abort transmission of a request without error 2441 by sending a RST_STREAM with an error code of NO_ERROR after sending 2442 a complete response (i.e., a frame with the END_STREAM flag set). 2443 Clients MUST NOT discard responses as a result of receiving such a 2444 RST_STREAM, though clients can always discard responses at their 2445 discretion for other reasons. 2447 8.1.1. Malformed Messages 2449 A malformed request or response is one that is an otherwise valid 2450 sequence of HTTP/2 frames but is invalid due to the presence of 2451 extraneous frames, prohibited fields or pseudo-header fields, the 2452 absence of mandatory pseudo-header fields, the inclusion of uppercase 2453 field names, or invalid field names and/or values (in certain 2454 circumstances; see Section 8.2). 2456 A request or response that includes message content can include a 2457 content-length header field. A request or response is also malformed 2458 if the value of a content-length header field does not equal the sum 2459 of the DATA frame payload lengths that form the content, unless the 2460 message is defined as having no content. For example, 204 or 304 2461 responses contain no content, as does the response to a HEAD request. 2462 A response that is defined to have no content, as described in 2463 Section 6.4.1 of [HTTP], MAY have a non-zero content-length header 2464 field, even though no content is included in DATA frames. 2466 Intermediaries that process HTTP requests or responses (i.e., any 2467 intermediary not acting as a tunnel) MUST NOT forward a malformed 2468 request or response. Malformed requests or responses that are 2469 detected MUST be treated as a stream error (Section 5.4.2) of type 2470 PROTOCOL_ERROR. 2472 For malformed requests, a server MAY send an HTTP response prior to 2473 closing or resetting the stream. Clients MUST NOT accept a malformed 2474 response. 2476 Endpoints that progressively process messages might have performed 2477 some processing before identifying a request or response as 2478 malformed. For instance, it might be possible to generate an 2479 informational or 404 status code without having received a complete 2480 request. Similarly, intermediaries might forward incomplete messages 2481 before detecting errors. A server MAY generate a final response 2482 before receiving an entire request when the response does not depend 2483 on the remainder of the request being correct. 2485 These requirements are intended to protect against several types of 2486 common attacks against HTTP; they are deliberately strict because 2487 being permissive can expose implementations to these vulnerabilities. 2489 8.2. HTTP Fields 2491 HTTP fields (Section 5 of [HTTP]) are conveyed by HTTP/2 in the 2492 HEADERS, CONTINUATION, and PUSH_PROMISE frames, compressed with HPACK 2493 [COMPRESSION]. 2495 Field names MUST be converted to lowercase when constructing an 2496 HTTP/2 message. 2498 8.2.1. Field Validity 2500 The definitions of field names and values in HTTP prohibit some 2501 characters that HPACK might be able to convey. HTTP/2 2502 implementations SHOULD validate field names and values according to 2503 their definitions in Sections 5.1 and 5.5 of [HTTP] respectively and 2504 treat messages that contain prohibited characters as malformed 2505 (Section 8.1.1). 2507 Failure to validate fields can be exploited for request smuggling 2508 attacks. In particular, unvalidated fields might enable attacks when 2509 messages are forwarded using HTTP 1.1 [HTTP11], where characters such 2510 as CR, LF, and COLON are used as delimiters. Implementations MUST 2511 perform the following minimal validation of field names and values: 2513 * A field name MUST NOT contain characters in the ranges 0x00-0x20, 2514 0x41-0x5a, or 0x7f-0xff (all ranges inclusive). This specifically 2515 excludes all non-visible ASCII characters, ASCII SP (0x20), and 2516 uppercase characters ('A' to 'Z', ASCII 0x41 to 0x5a). 2518 * With the exception of pseudo-header fields (Section 8.3), which 2519 have a name that starts with a single colon, field names MUST NOT 2520 include a colon (ASCII COLON, 0x3a). 2522 * A field value MUST NOT contain the zero value (ASCII NUL, 0x0), 2523 line feed (ASCII LF, 0xa), or carriage return (ASCII CR, 0xd) at 2524 any position. 2526 * A field value MUST NOT start or end with an ASCII whitespace 2527 character (ASCII SP or HTAB, 0x20 or 0x9). 2529 | Note: An implementation that validates fields according the 2530 | definitions in Sections 5.1 and 5.5 of [HTTP] only needs an 2531 | additional check that field names do not include uppercase 2532 | characters. 2534 A request or response that contains a field that violates any of 2535 these conditions MUST be treated as malformed (Section 8.1.1). In 2536 particular, an intermediary that does not process fields when 2537 forwarding messages MUST NOT forward fields that contain any of the 2538 values that are listed as prohibited above. 2540 When a request message violates one of these requirements, an 2541 implementation SHOULD generate a 400 (Bad Request) status code (see 2542 Section 15.5.1 of [HTTP]), unless a more suitable status code is 2543 defined or the status code cannot be sent (e.g., because the error 2544 occurs in a trailer field). 2546 | Note: Field values that are not valid according to the 2547 | definition of the corresponding field do not cause a request to 2548 | be malformed; the requirements above only apply to the generic 2549 | syntax for fields as defined in Section 5 of [HTTP]. 2551 8.2.2. Connection-Specific Header Fields 2553 HTTP/2 does not use the Connection header field (Section 7.6.1 of 2554 [HTTP]) to indicate connection-specific header fields; in this 2555 protocol, connection-specific metadata is conveyed by other means. 2556 An endpoint MUST NOT generate an HTTP/2 message containing 2557 connection-specific header fields. This includes the Connection 2558 header field and those listed as having connection-specific semantics 2559 in Section 7.6.1 of [HTTP] (that is, Proxy-Connection, Keep-Alive, 2560 Transfer-Encoding, and Upgrade). Any message containing connection- 2561 specific header fields MUST be treated as malformed (Section 8.1.1). 2563 The only exception to this is the TE header field, which MAY be 2564 present in an HTTP/2 request; when it is, it MUST NOT contain any 2565 value other than "trailers". 2567 An intermediary transforming an HTTP/1.x message to HTTP/2 MUST 2568 remove connection-specific header fields as discussed in 2569 Section 7.6.1 of [HTTP], or their messages will be treated by other 2570 HTTP/2 endpoints as malformed (Section 8.1.1). 2572 | Note: HTTP/2 purposefully does not support upgrade to another 2573 | protocol. The handshake methods described in Section 3 are 2574 | believed sufficient to negotiate the use of alternative 2575 | protocols. 2577 8.2.3. Compressing the Cookie Header Field 2579 The Cookie header field [COOKIE] uses a semicolon (";") to delimit 2580 cookie-pairs (or "crumbs"). This header field contains multiple 2581 values, but does not use a COMMA (",") as a separator, which prevents 2582 cookie-pairs from being sent on multiple field lines (see Section 5.2 2583 of [HTTP]). This can significantly reduce compression efficiency as 2584 updates to individual cookie-pairs would invalidate any field lines 2585 that are stored in the HPACK table. 2587 To allow for better compression efficiency, the Cookie header field 2588 MAY be split into separate header fields, each with one or more 2589 cookie-pairs. If there are multiple Cookie header fields after 2590 decompression, these MUST be concatenated into a single octet string 2591 using the two-octet delimiter of 0x3b, 0x20 (the ASCII string "; ") 2592 before being passed into a non-HTTP/2 context, such as an HTTP/1.1 2593 connection, or a generic HTTP server application. 2595 Therefore, the following two lists of Cookie header fields are 2596 semantically equivalent. 2598 cookie: a=b; c=d; e=f 2600 cookie: a=b 2601 cookie: c=d 2602 cookie: e=f 2604 8.3. HTTP Control Data 2606 HTTP/2 uses special pseudo-header fields beginning with ':' character 2607 (ASCII 0x3a) to convey message control data (see Section 6.2 of 2608 [HTTP]). 2610 Pseudo-header fields are not HTTP header fields. Endpoints MUST NOT 2611 generate pseudo-header fields other than those defined in this 2612 document. Note that an extension could negotiate the use of 2613 additional pseudo-header fields; see Section 5.5. 2615 Pseudo-header fields are only valid in the context in which they are 2616 defined. Pseudo-header fields defined for requests MUST NOT appear 2617 in responses; pseudo-header fields defined for responses MUST NOT 2618 appear in requests. Pseudo-header fields MUST NOT appear in a 2619 trailer section. Endpoints MUST treat a request or response that 2620 contains undefined or invalid pseudo-header fields as malformed 2621 (Section 8.1.1). 2623 All pseudo-header fields MUST appear in a field block before all 2624 regular field lines. Any request or response that contains a pseudo- 2625 header field that appears in a field block after a regular field line 2626 MUST be treated as malformed (Section 8.1.1). 2628 The same pseudo-header field name MUST NOT appear more than once in a 2629 field block. A field block for an HTTP request or response that 2630 contains a repeated pseudo-header field name MUST be treated as 2631 malformed (Section 8.1.1). 2633 8.3.1. Request Pseudo-Header Fields 2635 The following pseudo-header fields are defined for HTTP/2 requests: 2637 * The :method pseudo-header field includes the HTTP method 2638 (Section 9 of [HTTP]). 2640 * The :scheme pseudo-header field includes the scheme portion of the 2641 request target. The scheme is taken from the target URI 2642 (Section 3.1 of [RFC3986]) when generating a request directly, or 2643 from the scheme of a translated request (for example, see 2644 Section 3.3 of [HTTP11]). Scheme is omitted for CONNECT requests 2645 (Section 8.5). 2647 :scheme is not restricted to http and https schemed URIs. A proxy 2648 or gateway can translate requests for non-HTTP schemes, enabling 2649 the use of HTTP to interact with non-HTTP services. 2651 * The :authority pseudo-header field conveys the authority portion 2652 (Section 3.2 of [RFC3986]) of the target URI (Section 7.1 of 2653 [HTTP]). The recipient of a HTTP/2 request MUST NOT use the Host 2654 header field to determine the target URI if :authority is present. 2656 Clients that generate HTTP/2 requests directly MUST use the 2657 :authority pseudo-header field to convey authority information, 2658 unless there is no authority information to convey (in which case 2659 it MUST NOT generate :authority). 2661 Clients MUST NOT generate a request with a Host header field that 2662 differs from the :authority pseudo-header field. A server SHOULD 2663 treat a request as malformed if it contains a Host header field 2664 that identifies a different entity to the :authority pseudo-header 2665 field. The values of fields need to be normalized to compare them 2666 (see Section 6.2 of [RFC3986]). An origin server can apply any 2667 normalization method, whereas other servers MUST perform scheme- 2668 based normalization (see Section 6.2.3 of [RFC3986]) of the two 2669 fields. 2671 An intermediary that forwards a request over HTTP/2 MUST construct 2672 an :authority pseudo-header field using the authority information 2673 from the control data of the original request, unless the original 2674 request's target URI does not contain authority information (in 2675 which case it MUST NOT generate :authority). Note that the Host 2676 header field is not the sole source of this information; see 2677 Section 7.2 of [HTTP]. 2679 An intermediary that needs to generate a Host header field (which 2680 might be necessary to construct an HTTP/1.1 request) MUST use the 2681 value from the :authority pseudo-header field as the value of the 2682 Host field, unless the intermediary also changes the request 2683 target. This replaces any existing Host field to avoid potential 2684 vulnerabilities in HTTP routing. 2686 An intermediary that forwards a request over HTTP/2 MAY retain any 2687 Host header field. 2689 Note that request targets for CONNECT or asterisk-form OPTIONS 2690 requests never include authority information; see Section 7.1 of 2691 [HTTP]. 2693 :authority MUST NOT include the deprecated userinfo subcomponent 2694 for http or https schemed URIs. 2696 * The :path pseudo-header field includes the path and query parts of 2697 the target URI (the absolute-path production and optionally a '?' 2698 character followed by the query production; see Section 4.1 of 2699 [HTTP]). A request in asterisk form (for OPTIONS) includes the 2700 value '*' for the :path pseudo-header field. 2702 This pseudo-header field MUST NOT be empty for http or https URIs; 2703 http or https URIs that do not contain a path component MUST 2704 include a value of '/'. The exceptions to this rule are: 2706 - an OPTIONS request for an http or https URI that does not 2707 include a path component; these MUST include a :path pseudo- 2708 header field with a value of '*' (see Section 7.1 of [HTTP]) 2710 - CONNECT requests (Section 8.5), where the :path pseudo-header 2711 field is omitted. 2713 All HTTP/2 requests MUST include exactly one valid value for the 2714 :method, :scheme, and :path pseudo-header fields, unless it is a 2715 CONNECT request (Section 8.5). An HTTP request that omits mandatory 2716 pseudo-header fields is malformed (Section 8.1.1). 2718 Individual HTTP/2 requests do not carry an explicit indicator of 2719 protocol version. All HTTP/2 requests implicitly have a protocol 2720 version of "2.0" (see Section 6.2 of [HTTP]). 2722 8.3.2. Response Pseudo-Header Fields 2724 For HTTP/2 responses, a single :status pseudo-header field is defined 2725 that carries the HTTP status code field (see Section 15 of [HTTP]). 2726 This pseudo-header field MUST be included in all responses, including 2727 interim responses; otherwise, the response is malformed 2728 (Section 8.1.1). 2730 HTTP/2 responses implicitly have a protocol version of "2.0". 2732 8.4. Server Push 2734 HTTP/2 allows a server to preemptively send (or "push") responses 2735 (along with corresponding "promised" requests) to a client in 2736 association with a previous client-initiated request. 2738 Server push was designed to allow a server to improve client- 2739 perceived performance by predicting what requests will follow those 2740 that it receives, thereby removing a round trip for them. For 2741 example, a request for HTML is often followed by requests for 2742 stylesheets and scripts referenced by that page. When these requests 2743 are pushed, the client does not need to wait to receive the 2744 references to them in the HTML and issue separate requests. 2746 In practice, server push is difficult to use effectively, because it 2747 requires the server to correctly anticipate the additional requests 2748 the client will make, taking into account factors such as caching, 2749 content negotiation, and user behavior. Errors in prediction can 2750 lead to performance degradation, due to the opportunity cost that the 2751 additional data on the wire represents. In particular, pushing any 2752 significant amount of data can cause contention issues with more- 2753 important responses. 2755 A client can request that server push be disabled, though this is 2756 negotiated for each hop independently. The SETTINGS_ENABLE_PUSH 2757 setting can be set to 0 to indicate that server push is disabled. 2759 Promised requests MUST be safe (see Section 9.2.1 of [HTTP]) and 2760 cacheable (see Section 9.2.3 of [HTTP]). Promised requests cannot 2761 include any content or a trailer section. Clients that receive a 2762 promised request that is not cacheable, that is not known to be safe, 2763 or that indicates the presence of request content MUST reset the 2764 promised stream with a stream error (Section 5.4.2) of type 2765 PROTOCOL_ERROR. Note this could result in the promised stream being 2766 reset if the client does not recognize a newly defined method as 2767 being safe. 2769 Pushed responses that are cacheable (see Section 3 of [CACHE]) can be 2770 stored by the client, if it implements an HTTP cache. Pushed 2771 responses are considered successfully validated on the origin server 2772 (e.g., if the "no-cache" cache response directive is present; see 2773 Section 5.2.2.4 of [CACHE]) while the stream identified by the 2774 promised stream ID is still open. 2776 Pushed responses that are not cacheable MUST NOT be stored by any 2777 HTTP cache. They MAY be made available to the application 2778 separately. 2780 The server MUST include a value in the :authority pseudo-header field 2781 for which the server is authoritative (see Section 10.1). A client 2782 MUST treat a PUSH_PROMISE for which the server is not authoritative 2783 as a stream error (Section 5.4.2) of type PROTOCOL_ERROR. 2785 An intermediary can receive pushes from the server and choose not to 2786 forward them on to the client. In other words, how to make use of 2787 the pushed information is up to that intermediary. Equally, the 2788 intermediary might choose to make additional pushes to the client, 2789 without any action taken by the server. 2791 A client cannot push. Thus, servers MUST treat the receipt of a 2792 PUSH_PROMISE frame as a connection error (Section 5.4.1) of type 2793 PROTOCOL_ERROR. A server cannot set the SETTINGS_ENABLE_PUSH setting 2794 to a value other than 0 (see Section 6.5.2). 2796 8.4.1. Push Requests 2798 Server push is semantically equivalent to a server responding to a 2799 request; however, in this case, that request is also sent by the 2800 server, as a PUSH_PROMISE frame. 2802 The PUSH_PROMISE frame includes a field block that contains control 2803 data and a complete set of request header fields that the server 2804 attributes to the request. It is not possible to push a response to 2805 a request that includes message content. 2807 Promised requests are always associated with an explicit request from 2808 the client. The PUSH_PROMISE frames sent by the server are sent on 2809 that explicit request's stream. The PUSH_PROMISE frame also includes 2810 a promised stream identifier, chosen from the stream identifiers 2811 available to the server (see Section 5.1.1). 2813 The header fields in PUSH_PROMISE and any subsequent CONTINUATION 2814 frames MUST be a valid and complete set of request header fields 2815 (Section 8.3.1). The server MUST include a method in the :method 2816 pseudo-header field that is safe and cacheable. If a client receives 2817 a PUSH_PROMISE that does not include a complete and valid set of 2818 header fields or the :method pseudo-header field identifies a method 2819 that is not safe, it MUST respond on the promised stream with a 2820 stream error (Section 5.4.2) of type PROTOCOL_ERROR. 2822 The server SHOULD send PUSH_PROMISE (Section 6.6) frames prior to 2823 sending any frames that reference the promised responses. This 2824 avoids a race where clients issue requests prior to receiving any 2825 PUSH_PROMISE frames. 2827 For example, if the server receives a request for a document 2828 containing embedded links to multiple image files and the server 2829 chooses to push those additional images to the client, sending 2830 PUSH_PROMISE frames before the DATA frames that contain the image 2831 links ensures that the client is able to see that a resource will be 2832 pushed before discovering embedded links. Similarly, if the server 2833 pushes resources referenced by the field block (for instance, in Link 2834 header fields), sending a PUSH_PROMISE before sending the header 2835 ensures that clients do not request those resources. 2837 PUSH_PROMISE frames MUST NOT be sent by the client. 2839 PUSH_PROMISE frames can be sent by the server on any client-initiated 2840 stream, but the stream MUST be in either the "open" or "half-closed 2841 (remote)" state with respect to the server. PUSH_PROMISE frames are 2842 interspersed with the frames that comprise a response, though they 2843 cannot be interspersed with HEADERS and CONTINUATION frames that 2844 comprise a single field block. 2846 Sending a PUSH_PROMISE frame creates a new stream and puts the stream 2847 into the "reserved (local)" state for the server and the "reserved 2848 (remote)" state for the client. 2850 8.4.2. Push Responses 2852 After sending the PUSH_PROMISE frame, the server can begin delivering 2853 the pushed response as a response (Section 8.3.2) on a server- 2854 initiated stream that uses the promised stream identifier. The 2855 server uses this stream to transmit an HTTP response, using the same 2856 sequence of frames as defined in Section 8.1. This stream becomes 2857 "half-closed" to the client (Section 5.1) after the initial HEADERS 2858 frame is sent. 2860 Once a client receives a PUSH_PROMISE frame and chooses to accept the 2861 pushed response, the client SHOULD NOT issue any requests for the 2862 promised response until after the promised stream has closed. 2864 If the client determines, for any reason, that it does not wish to 2865 receive the pushed response from the server or if the server takes 2866 too long to begin sending the promised response, the client can send 2867 a RST_STREAM frame, using either the CANCEL or REFUSED_STREAM code 2868 and referencing the pushed stream's identifier. 2870 A client can use the SETTINGS_MAX_CONCURRENT_STREAMS setting to limit 2871 the number of responses that can be concurrently pushed by a server. 2872 Advertising a SETTINGS_MAX_CONCURRENT_STREAMS value of zero prevents 2873 the server from opening the streams necessary to push responses. 2874 However, this does not prevent the server from reserving streams 2875 using PUSH_PROMISE frames, because "reserved" streams do not count 2876 toward the concurrent stream limit. Clients that do not wish to 2877 receive pushed resources need to reset any unwanted reserved streams 2878 or set SETTINGS_ENABLE_PUSH to 0. 2880 Clients receiving a pushed response MUST validate that either the 2881 server is authoritative (see Section 10.1) or the proxy that provided 2882 the pushed response is configured for the corresponding request. For 2883 example, a server that offers a certificate for only the example.com 2884 DNS-ID (see [RFC6125]) is not permitted to push a response for 2885 https://www.example.org/doc. 2887 The response for a PUSH_PROMISE stream begins with a HEADERS frame, 2888 which immediately puts the stream into the "half-closed (remote)" 2889 state for the server and "half-closed (local)" state for the client, 2890 and ends with a frame with the END_STREAM flag set, which places the 2891 stream in the "closed" state. 2893 | Note: The client never sends a frame with the END_STREAM flag 2894 | set for a server push. 2896 8.5. The CONNECT Method 2898 The CONNECT method (Section 9.3.6 of [HTTP]) is used to convert an 2899 HTTP connection into a tunnel to a remote host. CONNECT is primarily 2900 used with HTTP proxies to establish a TLS session with an origin 2901 server for the purposes of interacting with https resources. 2903 In HTTP/2, the CONNECT method establishes a tunnel over a single 2904 HTTP/2 stream to a remote host, rather than converting the entire 2905 connection to a tunnel. A CONNECT header section is constructed as 2906 defined in Section 8.3.1 ("Request Pseudo-Header Fields"), with a few 2907 differences. Specifically: 2909 * The :method pseudo-header field is set to CONNECT. 2911 * The :scheme and :path pseudo-header fields MUST be omitted. 2913 * The :authority pseudo-header field contains the host and port to 2914 connect to (equivalent to the authority-form of the request-target 2915 of CONNECT requests; see Section 3.2.3 of [HTTP11]). 2917 A CONNECT request that does not conform to these restrictions is 2918 malformed (Section 8.1.1). 2920 A proxy that supports CONNECT establishes a TCP connection [TCP] to 2921 the host and port identified in the :authority pseudo-header field. 2922 Once this connection is successfully established, the proxy sends a 2923 HEADERS frame containing a 2xx series status code to the client, as 2924 defined in Section 9.3.6 of [HTTP]. 2926 After the initial HEADERS frame sent by each peer, all subsequent 2927 DATA frames correspond to data sent on the TCP connection. The frame 2928 payload of any DATA frames sent by the client is transmitted by the 2929 proxy to the TCP server; data received from the TCP server is 2930 assembled into DATA frames by the proxy. Frame types other than DATA 2931 or stream management frames (RST_STREAM, WINDOW_UPDATE, and PRIORITY) 2932 MUST NOT be sent on a connected stream and MUST be treated as a 2933 stream error (Section 5.4.2) if received. 2935 The TCP connection can be closed by either peer. The END_STREAM flag 2936 on a DATA frame is treated as being equivalent to the TCP FIN bit. A 2937 client is expected to send a DATA frame with the END_STREAM flag set 2938 after receiving a frame with the END_STREAM flag set. A proxy that 2939 receives a DATA frame with the END_STREAM flag set sends the attached 2940 data with the FIN bit set on the last TCP segment. A proxy that 2941 receives a TCP segment with the FIN bit set sends a DATA frame with 2942 the END_STREAM flag set. Note that the final TCP segment or DATA 2943 frame could be empty. 2945 A TCP connection error is signaled with RST_STREAM. A proxy treats 2946 any error in the TCP connection, which includes receiving a TCP 2947 segment with the RST bit set, as a stream error (Section 5.4.2) of 2948 type CONNECT_ERROR. Correspondingly, a proxy MUST send a TCP segment 2949 with the RST bit set if it detects an error with the stream or the 2950 HTTP/2 connection. 2952 8.6. The Upgrade Header Field 2954 HTTP/2 does not support the 101 (Switching Protocols) informational 2955 status code (Section 15.2.2 of [HTTP]). 2957 The semantics of 101 (Switching Protocols) aren't applicable to a 2958 multiplexed protocol. Similar functionality might be enabled through 2959 the use of extended CONNECT [RFC8441] and other protocols are able to 2960 use the same mechanisms that HTTP/2 uses to negotiate their use (see 2961 Section 3). 2963 8.7. Request Reliability 2965 In general, an HTTP client is unable to retry a non-idempotent 2966 request when an error occurs because there is no means to determine 2967 the nature of the error (see Section 9.2.2 of [HTTP]). It is 2968 possible that some server processing occurred prior to the error, 2969 which could result in undesirable effects if the request were 2970 reattempted. 2972 HTTP/2 provides two mechanisms for providing a guarantee to a client 2973 that a request has not been processed: 2975 * The GOAWAY frame indicates the highest stream number that might 2976 have been processed. Requests on streams with higher numbers are 2977 therefore guaranteed to be safe to retry. 2979 * The REFUSED_STREAM error code can be included in a RST_STREAM 2980 frame to indicate that the stream is being closed prior to any 2981 processing having occurred. Any request that was sent on the 2982 reset stream can be safely retried. 2984 Requests that have not been processed have not failed; clients MAY 2985 automatically retry them, even those with non-idempotent methods. 2987 A server MUST NOT indicate that a stream has not been processed 2988 unless it can guarantee that fact. If frames that are on a stream 2989 are passed to the application layer for any stream, then 2990 REFUSED_STREAM MUST NOT be used for that stream, and a GOAWAY frame 2991 MUST include a stream identifier that is greater than or equal to the 2992 given stream identifier. 2994 In addition to these mechanisms, the PING frame provides a way for a 2995 client to easily test a connection. Connections that remain idle can 2996 become broken as some middleboxes (for instance, network address 2997 translators or load balancers) silently discard connection bindings. 2998 The PING frame allows a client to safely test whether a connection is 2999 still active without sending a request. 3001 8.8. Examples 3003 This section shows HTTP/1.1 requests and responses, with 3004 illustrations of equivalent HTTP/2 requests and responses. 3006 8.8.1. Simple Request 3008 An HTTP GET request includes control data and a request header with 3009 no message content and is therefore transmitted as a single HEADERS 3010 frame, followed by zero or more CONTINUATION frames containing the 3011 serialized block of request header fields. The HEADERS frame in the 3012 following has both the END_HEADERS and END_STREAM flags set; no 3013 CONTINUATION frames are sent. 3015 GET /resource HTTP/1.1 HEADERS 3016 Host: example.org ==> + END_STREAM 3017 Accept: image/jpeg + END_HEADERS 3018 :method = GET 3019 :scheme = https 3020 :authority = example.org 3021 :path = /resource 3022 host = example.org 3023 accept = image/jpeg 3025 8.8.2. Simple Response 3027 Similarly, a response that includes only control data and a response 3028 header is transmitted as a HEADERS frame (again, followed by zero or 3029 more CONTINUATION frames) containing the serialized block of response 3030 header fields. 3032 HTTP/1.1 304 Not Modified HEADERS 3033 ETag: "xyzzy" ==> + END_STREAM 3034 Expires: Thu, 23 Jan ... + END_HEADERS 3035 :status = 304 3036 etag = "xyzzy" 3037 expires = Thu, 23 Jan ... 3039 8.8.3. Complex Request 3041 An HTTP POST request that includes control data and a request header 3042 and message content is transmitted as one HEADERS frame, followed by 3043 zero or more CONTINUATION frames containing the request header, 3044 followed by one or more DATA frames, with the last CONTINUATION (or 3045 HEADERS) frame having the END_HEADERS flag set and the final DATA 3046 frame having the END_STREAM flag set: 3048 POST /resource HTTP/1.1 HEADERS 3049 Host: example.org ==> - END_STREAM 3050 Content-Type: image/jpeg - END_HEADERS 3051 Content-Length: 123 :method = POST 3052 :authority = example.org 3053 :path = /resource 3054 {binary data} :scheme = https 3056 CONTINUATION 3057 + END_HEADERS 3058 content-type = image/jpeg 3059 host = example.org 3060 content-length = 123 3062 DATA 3063 + END_STREAM 3064 {binary data} 3066 Note that data contributing to any given field line could be spread 3067 between field block fragments. The allocation of field lines to 3068 frames in this example is illustrative only. 3070 8.8.4. Response with Body 3072 A response that includes control data and a response header and 3073 message content is transmitted as a HEADERS frame, followed by zero 3074 or more CONTINUATION frames, followed by one or more DATA frames, 3075 with the last DATA frame in the sequence having the END_STREAM flag 3076 set: 3078 HTTP/1.1 200 OK HEADERS 3079 Content-Type: image/jpeg ==> - END_STREAM 3080 Content-Length: 123 + END_HEADERS 3081 :status = 200 3082 {binary data} content-type = image/jpeg 3083 content-length = 123 3085 DATA 3086 + END_STREAM 3087 {binary data} 3089 8.8.5. Informational Responses 3091 An informational response using a 1xx status code other than 101 is 3092 transmitted as a HEADERS frame, followed by zero or more CONTINUATION 3093 frames. 3095 A trailer section is sent as a field block after both the request or 3096 response field block and all the DATA frames have been sent. The 3097 HEADERS frame starting the field block that comprises the trailer 3098 section has the END_STREAM flag set. 3100 The following example includes both a 100 (Continue) status code, 3101 which is sent in response to a request containing a "100-continue" 3102 token in the Expect header field, and a trailer section: 3104 HTTP/1.1 100 Continue HEADERS 3105 Extension-Field: bar ==> - END_STREAM 3106 + END_HEADERS 3107 :status = 100 3108 extension-field = bar 3110 HTTP/1.1 200 OK HEADERS 3111 Content-Type: image/jpeg ==> - END_STREAM 3112 Transfer-Encoding: chunked + END_HEADERS 3113 Trailer: Foo :status = 200 3114 content-type = image/jpeg 3115 123 trailer = Foo 3116 {binary data} 3117 0 DATA 3118 Foo: bar - END_STREAM 3119 {binary data} 3121 HEADERS 3122 + END_STREAM 3123 + END_HEADERS 3124 foo = bar 3126 9. HTTP/2 Connections 3128 This section outlines attributes of the HTTP protocol that improve 3129 interoperability, reduce exposure to known security vulnerabilities, 3130 or reduce the potential for implementation variation. 3132 9.1. Connection Management 3134 HTTP/2 connections are persistent. For best performance, it is 3135 expected that clients will not close connections until it is 3136 determined that no further communication with a server is necessary 3137 (for example, when a user navigates away from a particular web page) 3138 or until the server closes the connection. 3140 Clients SHOULD NOT open more than one HTTP/2 connection to a given 3141 host and port pair, where the host is derived from a URI, a selected 3142 alternative service [ALT-SVC], or a configured proxy. 3144 A client can create additional connections as replacements, either to 3145 replace connections that are near to exhausting the available stream 3146 identifier space (Section 5.1.1), to refresh the keying material for 3147 a TLS connection, or to replace connections that have encountered 3148 errors (Section 5.4.1). 3150 A client MAY open multiple connections to the same IP address and TCP 3151 port using different Server Name Indication [TLS-EXT] values or to 3152 provide different TLS client certificates but SHOULD avoid creating 3153 multiple connections with the same configuration. 3155 Servers are encouraged to maintain open connections for as long as 3156 possible but are permitted to terminate idle connections if 3157 necessary. When either endpoint chooses to close the transport-layer 3158 TCP connection, the terminating endpoint SHOULD first send a GOAWAY 3159 (Section 6.8) frame so that both endpoints can reliably determine 3160 whether previously sent frames have been processed and gracefully 3161 complete or terminate any necessary remaining tasks. 3163 9.1.1. Connection Reuse 3165 Connections that are made to an origin server, either directly or 3166 through a tunnel created using the CONNECT method (Section 8.5), MAY 3167 be reused for requests with multiple different URI authority 3168 components. A connection can be reused as long as the origin server 3169 is authoritative (Section 10.1). For TCP connections without TLS, 3170 this depends on the host having resolved to the same IP address. 3172 For https resources, connection reuse additionally depends on having 3173 a certificate that is valid for the host in the URI. The certificate 3174 presented by the server MUST satisfy any checks that the client would 3175 perform when forming a new TLS connection for the host in the URI. A 3176 single certificate can be used to establish authority for multiple 3177 origins. Section 4.3 of [HTTP] describes how a client determines 3178 whether a server is authoritative for a URI. 3180 In some deployments, reusing a connection for multiple origins can 3181 result in requests being directed to the wrong origin server. For 3182 example, TLS termination might be performed by a middlebox that uses 3183 the TLS Server Name Indication (SNI) [TLS-EXT] extension to select an 3184 origin server. This means that it is possible for clients to send 3185 requests to servers that might not be the intended target for the 3186 request, even though the server is otherwise authoritative. 3188 A server that does not wish clients to reuse connections can indicate 3189 that it is not authoritative for a request by sending a 421 3190 (Misdirected Request) status code in response to the request (see 3191 Section 15.5.20 of [HTTP]). 3193 A client that is configured to use a proxy over HTTP/2 directs 3194 requests to that proxy through a single connection. That is, all 3195 requests sent via a proxy reuse the connection to the proxy. 3197 9.2. Use of TLS Features 3199 Implementations of HTTP/2 MUST use TLS version 1.2 [TLS12] or higher 3200 for HTTP/2 over TLS. The general TLS usage guidance in [TLSBCP] 3201 SHOULD be followed, with some additional restrictions that are 3202 specific to HTTP/2. 3204 The TLS implementation MUST support the Server Name Indication (SNI) 3205 [TLS-EXT] extension to TLS. If the server is identified by a domain 3206 name [DNS-TERMS], clients MUST send the server_name TLS extension 3207 unless an alternative mechanism to indicate the target host is used. 3209 Requirements for deployments of HTTP/2 that negotiate TLS 1.3 [TLS13] 3210 are included in Section 9.2.3. Deployments of TLS 1.2 are subject to 3211 the requirements in Section 9.2.1 and Section 9.2.2. Implementations 3212 are encouraged to provide defaults that comply, but it is recognized 3213 that deployments are ultimately responsible for compliance. 3215 9.2.1. TLS 1.2 Features 3217 This section describes restrictions on the TLS 1.2 feature set that 3218 can be used with HTTP/2. Due to deployment limitations, it might not 3219 be possible to fail TLS negotiation when these restrictions are not 3220 met. An endpoint MAY immediately terminate an HTTP/2 connection that 3221 does not meet these TLS requirements with a connection error 3222 (Section 5.4.1) of type INADEQUATE_SECURITY. 3224 A deployment of HTTP/2 over TLS 1.2 MUST disable compression. TLS 3225 compression can lead to the exposure of information that would not 3226 otherwise be revealed [RFC3749]. Generic compression is unnecessary 3227 since HTTP/2 provides compression features that are more aware of 3228 context and therefore likely to be more appropriate for use for 3229 performance, security, or other reasons. 3231 A deployment of HTTP/2 over TLS 1.2 MUST disable renegotiation. An 3232 endpoint MUST treat a TLS renegotiation as a connection error 3233 (Section 5.4.1) of type PROTOCOL_ERROR. Note that disabling 3234 renegotiation can result in long-lived connections becoming unusable 3235 due to limits on the number of messages the underlying cipher suite 3236 can encipher. 3238 An endpoint MAY use renegotiation to provide confidentiality 3239 protection for client credentials offered in the handshake, but any 3240 renegotiation MUST occur prior to sending the connection preface. A 3241 server SHOULD request a client certificate if it sees a renegotiation 3242 request immediately after establishing a connection. 3244 This effectively prevents the use of renegotiation in response to a 3245 request for a specific protected resource. A future specification 3246 might provide a way to support this use case. Alternatively, a 3247 server might use an error (Section 5.4) of type HTTP_1_1_REQUIRED to 3248 request the client use a protocol that supports renegotiation. 3250 Implementations MUST support ephemeral key exchange sizes of at least 3251 2048 bits for cipher suites that use ephemeral finite field Diffie- 3252 Hellman (DHE) (Section 8.1.2 of [TLS12] and 224 bits for cipher 3253 suites that use ephemeral elliptic curve Diffie-Hellman (ECDHE) 3254 [RFC8422]. Clients MUST accept DHE sizes of up to 4096 bits. 3255 Endpoints MAY treat negotiation of key sizes smaller than the lower 3256 limits as a connection error (Section 5.4.1) of type 3257 INADEQUATE_SECURITY. 3259 9.2.2. TLS 1.2 Cipher Suites 3261 A deployment of HTTP/2 over TLS 1.2 SHOULD NOT use any of the cipher 3262 suites that are listed in the list of prohibited cipher suites 3263 (Appendix A). 3265 Endpoints MAY choose to generate a connection error (Section 5.4.1) 3266 of type INADEQUATE_SECURITY if one of the prohibited cipher suites is 3267 negotiated. A deployment that chooses to use a prohibited cipher 3268 suite risks triggering a connection error unless the set of potential 3269 peers is known to accept that cipher suite. 3271 Implementations MUST NOT generate this error in reaction to the 3272 negotiation of a cipher suite that is not prohibited. Consequently, 3273 when clients offer a cipher suite that is not prohibited, they have 3274 to be prepared to use that cipher suite with HTTP/2. 3276 The list of prohibited cipher suites includes the cipher suite that 3277 TLS 1.2 makes mandatory, which means that TLS 1.2 deployments could 3278 have non-intersecting sets of permitted cipher suites. To avoid this 3279 problem causing TLS handshake failures, deployments of HTTP/2 that 3280 use TLS 1.2 MUST support TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 3281 [TLS-ECDHE] with the P-256 elliptic curve [RFC8422]. 3283 Note that clients might advertise support of cipher suites that are 3284 prohibited in order to allow for connection to servers that do not 3285 support HTTP/2. This allows servers to select HTTP/1.1 with a cipher 3286 suite that is prohibited in HTTP/2. However, this can result in 3287 HTTP/2 being negotiated with a prohibited cipher suite if the 3288 application protocol and cipher suite are independently selected. 3290 9.2.3. TLS 1.3 Features 3292 TLS 1.3 includes a number of features not available in earlier 3293 versions. This section discusses the use of these features. 3295 HTTP/2 servers MUST NOT send post-handshake TLS 1.3 3296 CertificateRequest messages. HTTP/2 clients MUST treat a TLS post- 3297 handshake CertificateRequest message as a connection error 3298 (Section 5.4.1) of type PROTOCOL_ERROR. 3300 The prohibition on post-handshake authentication applies even if the 3301 client offered the "post_handshake_auth" TLS extension. Post- 3302 handshake authentication support might be advertised independently of 3303 ALPN [TLS-ALPN]. Clients might offer the capability for use in other 3304 protocols, but inclusion of the extension cannot imply support within 3305 HTTP/2. 3307 [TLS13] defines other post-handshake messages, NewSessionTicket and 3308 KeyUpdate, which can be used as they have no direct interaction with 3309 HTTP/2. Unless the use of a new type of TLS message depends on an 3310 interaction with the application-layer protocol, that TLS message can 3311 be sent after the handshake completes. 3313 TLS early data MAY be used to send requests, provided that the 3314 guidance in [RFC8470] is observed. Clients send requests in early 3315 data assuming initial values for all server settings. 3317 10. Security Considerations 3319 The use of TLS is necessary to provide many of the security 3320 properties of this protocol. Many of the claims in this section do 3321 not hold unless TLS is used as described in Section 9.2. 3323 10.1. Server Authority 3325 HTTP/2 relies on the HTTP definition of authority for determining 3326 whether a server is authoritative in providing a given response (see 3327 Section 4.3 of [HTTP]). This relies on local name resolution for the 3328 "http" URI scheme and the authenticated server identity for the 3329 "https" scheme. 3331 10.2. Cross-Protocol Attacks 3333 In a cross-protocol attack, an attacker causes a client to initiate a 3334 transaction in one protocol toward a server that understands a 3335 different protocol. An attacker might be able to cause the 3336 transaction to appear as a valid transaction in the second protocol. 3337 In combination with the capabilities of the web context, this can be 3338 used to interact with poorly protected servers in private networks. 3340 Completing a TLS handshake with an ALPN identifier for HTTP/2 can be 3341 considered sufficient protection against cross-protocol attacks. 3342 ALPN provides a positive indication that a server is willing to 3343 proceed with HTTP/2, which prevents attacks on other TLS-based 3344 protocols. 3346 The encryption in TLS makes it difficult for attackers to control the 3347 data that could be used in a cross-protocol attack on a cleartext 3348 protocol. 3350 The cleartext version of HTTP/2 has minimal protection against cross- 3351 protocol attacks. The connection preface (Section 3.4) contains a 3352 string that is designed to confuse HTTP/1.1 servers, but no special 3353 protection is offered for other protocols. 3355 10.3. Intermediary Encapsulation Attacks 3357 HPACK permits encoding of field names and values that might be 3358 treated as delimiters in other HTTP versions. An intermediary that 3359 translates an HTTP/2 request or response MUST validate fields 3360 according to the rules in Section 8.2 before translating a message to 3361 another HTTP version. Translating a field that includes invalid 3362 delimiters could be used to cause recipients to incorrectly interpret 3363 a message, which could be exploited by an attacker. 3365 Section 8.2 does not include specific rules for validation of pseudo- 3366 header fields. If the values of these fields are used, additional 3367 validation is necessary. This is particularly important where 3368 :scheme, :authority, and :path are combined to form a single URI 3369 string ([RFC3986]). Similar problems might occur when that URI or 3370 just :path are combined with :method to construct a request line (as 3371 in Section 3 of [HTTP11]). Simple concatenation is not secure unless 3372 the input values are fully validated. 3374 An intermediary can reject fields that contain invalid field names or 3375 values for other reasons, in particular those that do not conform to 3376 the HTTP ABNF grammar from Section 5 of [HTTP]. Intermediaries that 3377 do not perform any validation of fields other than the minimum 3378 required by Section 8.2 could forward messages that contain invalid 3379 field names or values. 3381 An intermediary that receives any field that requires removal before 3382 forwarding (see Section 7.6.1 of [HTTP]) MUST remove or replace those 3383 header fields when forwarding messages. Additionally, intermediaries 3384 should take care when forwarding messages containing Content-Length 3385 fields to ensure that the message is well-formed (Section 8.1.1). 3386 This ensures that if the message is translated into HTTP/1.1 at any 3387 point the framing will be correct. 3389 10.4. Cacheability of Pushed Responses 3391 Pushed responses do not have an explicit request from the client; the 3392 request is provided by the server in the PUSH_PROMISE frame. 3394 Caching responses that are pushed is possible based on the guidance 3395 provided by the origin server in the Cache-Control header field. 3396 However, this can cause issues if a single server hosts more than one 3397 tenant. For example, a server might offer multiple users each a 3398 small portion of its URI space. 3400 Where multiple tenants share space on the same server, that server 3401 MUST ensure that tenants are not able to push representations of 3402 resources that they do not have authority over. Failure to enforce 3403 this would allow a tenant to provide a representation that would be 3404 served out of cache, overriding the actual representation that the 3405 authoritative tenant provides. 3407 Pushed responses for which an origin server is not authoritative (see 3408 Section 10.1) MUST NOT be used or cached. 3410 10.5. Denial-of-Service Considerations 3412 An HTTP/2 connection can demand a greater commitment of resources to 3413 operate than an HTTP/1.1 connection. The use of field section 3414 compression and flow control depend on a commitment of resources for 3415 storing a greater amount of state. Settings for these features 3416 ensure that memory commitments for these features are strictly 3417 bounded. 3419 The number of PUSH_PROMISE frames is not constrained in the same 3420 fashion. A client that accepts server push SHOULD limit the number 3421 of streams it allows to be in the "reserved (remote)" state. An 3422 excessive number of server push streams can be treated as a stream 3423 error (Section 5.4.2) of type ENHANCE_YOUR_CALM. 3425 A number of HTTP/2 implementations were found to be vulnerable to 3426 denial of service [NFLX-2019-002]. The following lists known ways 3427 that implementations might be subject to denial of service attack: 3429 * Inefficient tracking of outstanding outbound frames can lead to 3430 overload if an adversary can cause large numbers of frames to be 3431 enqueued for sending. A peer could use one of several techniques 3432 to cause large numbers of frames to be generated: 3434 - Providing tiny increments to flow control in WINDOW_UPDATE 3435 frames can cause a sender to generate a large number of DATA 3436 frames. 3438 - An endpoint is required to respond to a PING frame. 3440 - Each SETTINGS frame requires acknowledgment. 3442 - An invalid request (or server push) can cause a peer to send 3443 RST_STREAM frames in response. 3445 * An attacker can provide large amounts of flow control credit at 3446 the HTTP/2 layer, but withhold credit at the TCP layer, preventing 3447 frames from being sent. An endpoint that constructs and remembers 3448 frames for sending without considering TCP limits might be subject 3449 to resource exhaustion. 3451 * Large numbers of small or empty frames can be abused to cause a 3452 peer to expend time processing frame headers. Caution is required 3453 here as some uses of small frames are entirely legitimate, such as 3454 the sending of an empty DATA or CONTINUATION frame at the end of a 3455 stream. 3457 * The SETTINGS frame might also be abused to cause a peer to expend 3458 additional processing time. This might be done by pointlessly 3459 changing settings, sending multiple undefined settings, or 3460 changing the same setting multiple times in the same frame. 3462 * Handling reprioritization with PRIORITY frames can require 3463 significant processing time and can lead to overload if many 3464 PRIORITY frames are sent. 3466 * Field section compression also offers some opportunities to waste 3467 processing resources; see Section 7 of [COMPRESSION] for more 3468 details on potential abuses. 3470 * Limits in SETTINGS cannot be reduced instantaneously, which leaves 3471 an endpoint exposed to behavior from a peer that could exceed the 3472 new limits. In particular, immediately after establishing a 3473 connection, limits set by a server are not known to clients and 3474 could be exceeded without being an obvious protocol violation. 3476 Most of the features that might be exploited for denial of service -- 3477 i.e., SETTINGS changes, small frames, field section compression -- 3478 have legitimate uses. These features become a burden only when they 3479 are used unnecessarily or to excess. 3481 An endpoint that doesn't monitor use of these features exposes itself 3482 to a risk of denial of service. Implementations SHOULD track the use 3483 of these features and set limits on their use. An endpoint MAY treat 3484 activity that is suspicious as a connection error (Section 5.4.1) of 3485 type ENHANCE_YOUR_CALM. 3487 10.5.1. Limits on Field Block Size 3489 A large field block (Section 4.3) can cause an implementation to 3490 commit a large amount of state. Field lines that are critical for 3491 routing can appear toward the end of a field block, which prevents 3492 streaming of fields to their ultimate destination. This ordering and 3493 other reasons, such as ensuring cache correctness, mean that an 3494 endpoint might need to buffer the entire field block. Since there is 3495 no hard limit to the size of a field block, some endpoints could be 3496 forced to commit a large amount of available memory for field blocks. 3498 An endpoint can use the SETTINGS_MAX_HEADER_LIST_SIZE to advise peers 3499 of limits that might apply on the size of uncompressed field blocks. 3500 This setting is only advisory, so endpoints MAY choose to send field 3501 blocks that exceed this limit and risk the request or response being 3502 treated as malformed. This setting is specific to a connection, so 3503 any request or response could encounter a hop with a lower, unknown 3504 limit. An intermediary can attempt to avoid this problem by passing 3505 on values presented by different peers, but they are not obliged to 3506 do so. 3508 A server that receives a larger field block than it is willing to 3509 handle can send an HTTP 431 (Request Header Fields Too Large) status 3510 code [RFC6585]. A client can discard responses that it cannot 3511 process. The field block MUST be processed to ensure a consistent 3512 connection state, unless the connection is closed. 3514 10.5.2. CONNECT Issues 3516 The CONNECT method can be used to create disproportionate load on a 3517 proxy, since stream creation is relatively inexpensive when compared 3518 to the creation and maintenance of a TCP connection. A proxy might 3519 also maintain some resources for a TCP connection beyond the closing 3520 of the stream that carries the CONNECT request, since the outgoing 3521 TCP connection remains in the TIME_WAIT state. Therefore, a proxy 3522 cannot rely on SETTINGS_MAX_CONCURRENT_STREAMS alone to limit the 3523 resources consumed by CONNECT requests. 3525 10.6. Use of Compression 3527 Compression can allow an attacker to recover secret data when it is 3528 compressed in the same context as data under attacker control. 3529 HTTP/2 enables compression of field lines (Section 4.3); the 3530 following concerns also apply to the use of HTTP compressed content- 3531 codings (Section 8.4.1 of [HTTP]). 3533 There are demonstrable attacks on compression that exploit the 3534 characteristics of the web (e.g., [BREACH]). The attacker induces 3535 multiple requests containing varying plaintext, observing the length 3536 of the resulting ciphertext in each, which reveals a shorter length 3537 when a guess about the secret is correct. 3539 Implementations communicating on a secure channel MUST NOT compress 3540 content that includes both confidential and attacker-controlled data 3541 unless separate compression dictionaries are used for each source of 3542 data. Compression MUST NOT be used if the source of data cannot be 3543 reliably determined. Generic stream compression, such as that 3544 provided by TLS, MUST NOT be used with HTTP/2 (see Section 9.2). 3546 Further considerations regarding the compression of header fields are 3547 described in [COMPRESSION]. 3549 10.7. Use of Padding 3551 Padding within HTTP/2 is not intended as a replacement for general 3552 purpose padding, such as that provided by TLS [TLS13]. Redundant 3553 padding could even be counterproductive. Correct application can 3554 depend on having specific knowledge of the data that is being padded. 3556 To mitigate attacks that rely on compression, disabling or limiting 3557 compression might be preferable to padding as a countermeasure. 3559 Padding can be used to obscure the exact size of frame content and is 3560 provided to mitigate specific attacks within HTTP, for example, 3561 attacks where compressed content includes both attacker-controlled 3562 plaintext and secret data (e.g., [BREACH]). 3564 Use of padding can result in less protection than might seem 3565 immediately obvious. At best, padding only makes it more difficult 3566 for an attacker to infer length information by increasing the number 3567 of frames an attacker has to observe. Incorrectly implemented 3568 padding schemes can be easily defeated. In particular, randomized 3569 padding with a predictable distribution provides very little 3570 protection; similarly, padding frame payloads to a fixed size exposes 3571 information as frame payload sizes cross the fixed-sized boundary, 3572 which could be possible if an attacker can control plaintext. 3574 Intermediaries SHOULD retain padding for DATA frames, but MAY drop 3575 padding for HEADERS and PUSH_PROMISE frames. A valid reason for an 3576 intermediary to change the amount of padding of frames is to improve 3577 the protections that padding provides. 3579 10.8. Privacy Considerations 3581 Several characteristics of HTTP/2 provide an observer an opportunity 3582 to correlate actions of a single client or server over time. These 3583 include the value of settings, the manner in which flow-control 3584 windows are managed, the way priorities are allocated to streams, the 3585 timing of reactions to stimulus, and the handling of any features 3586 that are controlled by settings. 3588 As far as these create observable differences in behavior, they could 3589 be used as a basis for fingerprinting a specific client, as defined 3590 in Section 3.2 of [PRIVACY]. 3592 HTTP/2's preference for using a single TCP connection allows 3593 correlation of a user's activity on a site. Reusing connections for 3594 different origins allows tracking across those origins. 3596 Because the PING and SETTINGS frames solicit immediate responses, 3597 they can be used by an endpoint to measure latency to their peer. 3598 This might have privacy implications in certain scenarios. 3600 10.9. Remote Timing Attacks 3602 Remote timing attacks extract secrets from servers by observing 3603 variations in the time that servers take when processing requests 3604 that use secrets. HTTP/2 enables concurrent request creation and 3605 processing, which can give attackers better control over when request 3606 processing commences. Multiple HTTP/2 requests can be included in 3607 the same IP packet or TLS record. HTTP/2 can therefore make remote 3608 timing attacks more efficient by eliminating variability in request 3609 delivery, leaving only request order and the delivery of responses as 3610 sources of timing variability. 3612 Ensuring that processing time is not dependent on the value of 3613 secrets is the best defense against any form of timing attack. 3615 11. IANA Considerations 3617 This revision of the document marks the HTTP2-Settings header field 3618 and the h2c Upgrade token, both defined in [RFC7540], as obsolete. 3620 Section 11 of [RFC7540] registered the h2 and h2c ALPN identifiers 3621 along with the PRI HTTP method. RFC 7540 also established a registry 3622 for frame types, settings, and error codes. These registrations and 3623 registries apply to HTTP/2, but are not redefined in this document. 3625 IANA is requested to update references to RFC 7540 in the following 3626 registries to refer to this document: Application-Layer Protocol 3627 Negotiation (ALPN) Protocol IDs, HTTP/2 Frame Type, HTTP/2 Settings, 3628 HTTP/2 Error Code, and HTTP Method Registry. The registration of the 3629 PRI method needs to be updated to refer to Section 3.4; all other 3630 section numbers have not changed. 3632 IANA is requested to change the policy on those portions of the 3633 "HTTP/2 Frame Type" and "HTTP/2 Settings" registries that were 3634 reserved for Experimental Use in RFC 7540. These portions of the 3635 registry shall operate on the same policy as the remainder of each 3636 registry. 3638 11.1. HTTP2-Settings Header Field Registration 3640 This section marks the HTTP2-Settings header field registered by 3641 Section 11.5 of [RFC7540] in the Hypertext Transfer Protocol (HTTP) 3642 Field Name Registry as obsolete. This capability has been removed: 3643 see Section 3.1. The registration is updated to include the details 3644 as required by Section 18.4 of [HTTP]: 3646 Field Name: HTTP2-Settings 3648 Status: Standard 3650 Ref.: Section 3.2.1 of [RFC7540] 3652 Comments: Obsolete; see Section 11.1 of this document 3654 11.2. The h2c Upgrade Token 3656 This section records the h2c upgrade token registered by Section 11.8 3657 of [RFC7540] in the Hypertext Transfer Protocol (HTTP) Upgrade Token 3658 Registry as obsolete. This capability has been removed: see 3659 Section 3.1. The registration is updated as follows: 3661 Value: h2c 3663 Description: Hypertext Transfer Protocol version 2 (HTTP/2) 3665 Expected Version Tokens: None 3667 Reference: Section 3.1 of this document 3669 12. References 3671 12.1. Normative References 3673 [CACHE] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3674 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 3675 draft-ietf-httpbis-cache-18, 18 August 2021, 3676 . 3679 [COMPRESSION] 3680 Peon, R. and H. Ruellan, "HPACK: Header Compression for 3681 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 3682 . 3684 [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3685 DOI 10.17487/RFC6265, April 2011, 3686 . 3688 [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3689 Ed., "HTTP Semantics", Work in Progress, Internet-Draft, 3690 draft-ietf-httpbis-semantics-18, 18 August 2021, 3691 . 3694 [QUIC] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 3695 Multiplexed and Secure Transport", RFC 9000, 3696 DOI 10.17487/RFC9000, May 2021, 3697 . 3699 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3700 Requirement Levels", BCP 14, RFC 2119, 3701 DOI 10.17487/RFC2119, March 1997, 3702 . 3704 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3705 Resource Identifier (URI): Generic Syntax", STD 66, 3706 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3707 . 3709 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3710 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3711 May 2017, . 3713 [RFC8422] Nir, Y., Josefsson, S., and M. Pegourie-Gonnard, "Elliptic 3714 Curve Cryptography (ECC) Cipher Suites for Transport Layer 3715 Security (TLS) Versions 1.2 and Earlier", RFC 8422, 3716 DOI 10.17487/RFC8422, August 2018, 3717 . 3719 [RFC8470] Thomson, M., Nottingham, M., and W. Tarreau, "Using Early 3720 Data in HTTP", RFC 8470, DOI 10.17487/RFC8470, September 3721 2018, . 3723 [TCP] Postel, J., "Transmission Control Protocol", STD 7, 3724 RFC 793, DOI 10.17487/RFC793, September 1981, 3725 . 3727 [TLS-ALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan, 3728 "Transport Layer Security (TLS) Application-Layer Protocol 3729 Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, 3730 July 2014, . 3732 [TLS-ECDHE] 3733 Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 3734 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 3735 DOI 10.17487/RFC5289, August 2008, 3736 . 3738 [TLS-EXT] Eastlake 3rd, D., "Transport Layer Security (TLS) 3739 Extensions: Extension Definitions", RFC 6066, 3740 DOI 10.17487/RFC6066, January 2011, 3741 . 3743 [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer Security 3744 (TLS) Protocol Version 1.2", RFC 5246, 3745 DOI 10.17487/RFC5246, August 2008, 3746 . 3748 [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3749 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3750 . 3752 [TLSBCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 3753 "Recommendations for Secure Use of Transport Layer 3754 Security (TLS) and Datagram Transport Layer Security 3755 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 3756 2015, . 3758 12.2. Informative References 3760 [ALT-SVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP 3761 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 3762 April 2016, . 3764 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 3765 CRIME Attack", 12 July 2013, 3766 . 3769 [DNS-TERMS] 3770 Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 3771 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 3772 January 2019, . 3774 [HTTP11] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3775 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 3776 ietf-httpbis-messaging-18, 18 August 2021, 3777 . 3780 [I-D.ietf-httpbis-priority] 3781 Oku, K. and L. Pardue, "Extensible Prioritization Scheme 3782 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 3783 httpbis-priority-12, 17 January 2022, 3784 . 3787 [NFLX-2019-002] 3788 Netflix, "HTTP/2 Denial of Service Advisory", 13 August 3789 2019, . 3792 [PRIVACY] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 3793 Morris, J., Hansen, M., and R. Smith, "Privacy 3794 Considerations for Internet Protocols", RFC 6973, 3795 DOI 10.17487/RFC6973, July 2013, 3796 . 3798 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 3799 Communication Layers", RFC 1122, DOI 10.17487/RFC1122, 3800 October 1989, . 3802 [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol 3803 Compression Methods", RFC 3749, DOI 10.17487/RFC3749, May 3804 2004, . 3806 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3807 Verification of Domain-Based Application Service Identity 3808 within Internet Public Key Infrastructure Using X.509 3809 (PKIX) Certificates in the Context of Transport Layer 3810 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3811 2011, . 3813 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 3814 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 3815 . 3817 [RFC7323] Borman, D., Braden, B., Jacobson, V., and R. 3818 Scheffenegger, Ed., "TCP Extensions for High Performance", 3819 RFC 7323, DOI 10.17487/RFC7323, September 2014, 3820 . 3822 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 3823 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 3824 DOI 10.17487/RFC7540, May 2015, 3825 . 3827 [RFC8441] McManus, P., "Bootstrapping WebSockets with HTTP/2", 3828 RFC 8441, DOI 10.17487/RFC8441, September 2018, 3829 . 3831 [RFC8740] Benjamin, D., "Using TLS 1.3 with HTTP/2", RFC 8740, 3832 DOI 10.17487/RFC8740, February 2020, 3833 . 3835 [TALKING] Huang, L., Chen, E., Barth, A., Rescorla, E., and C. 3836 Jackson, "Talking to Yourself for Fun and Profit", 2011, 3837 . 3840 Appendix A. Prohibited TLS 1.2 Cipher Suites 3842 An HTTP/2 implementation MAY treat the negotiation of any of the 3843 following cipher suites with TLS 1.2 as a connection error 3844 (Section 5.4.1) of type INADEQUATE_SECURITY: 3846 * TLS_NULL_WITH_NULL_NULL 3847 * TLS_RSA_WITH_NULL_MD5 3848 * TLS_RSA_WITH_NULL_SHA 3849 * TLS_RSA_EXPORT_WITH_RC4_40_MD5 3850 * TLS_RSA_WITH_RC4_128_MD5 3851 * TLS_RSA_WITH_RC4_128_SHA 3852 * TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 3853 * TLS_RSA_WITH_IDEA_CBC_SHA 3854 * TLS_RSA_EXPORT_WITH_DES40_CBC_SHA 3855 * TLS_RSA_WITH_DES_CBC_SHA 3856 * TLS_RSA_WITH_3DES_EDE_CBC_SHA 3857 * TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA 3858 * TLS_DH_DSS_WITH_DES_CBC_SHA 3859 * TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 3860 * TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA 3861 * TLS_DH_RSA_WITH_DES_CBC_SHA 3862 * TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 3863 * TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA 3864 * TLS_DHE_DSS_WITH_DES_CBC_SHA 3865 * TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 3866 * TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA 3867 * TLS_DHE_RSA_WITH_DES_CBC_SHA 3868 * TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 3869 * TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 3870 * TLS_DH_anon_WITH_RC4_128_MD5 3871 * TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA 3872 * TLS_DH_anon_WITH_DES_CBC_SHA 3873 * TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 3874 * TLS_KRB5_WITH_DES_CBC_SHA 3875 * TLS_KRB5_WITH_3DES_EDE_CBC_SHA 3876 * TLS_KRB5_WITH_RC4_128_SHA 3877 * TLS_KRB5_WITH_IDEA_CBC_SHA 3878 * TLS_KRB5_WITH_DES_CBC_MD5 3879 * TLS_KRB5_WITH_3DES_EDE_CBC_MD5 3880 * TLS_KRB5_WITH_RC4_128_MD5 3881 * TLS_KRB5_WITH_IDEA_CBC_MD5 3882 * TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA 3883 * TLS_KRB5_EXPORT_WITH_RC2_CBC_40_SHA 3884 * TLS_KRB5_EXPORT_WITH_RC4_40_SHA 3885 * TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5 3886 * TLS_KRB5_EXPORT_WITH_RC2_CBC_40_MD5 3887 * TLS_KRB5_EXPORT_WITH_RC4_40_MD5 3888 * TLS_PSK_WITH_NULL_SHA 3889 * TLS_DHE_PSK_WITH_NULL_SHA 3890 * TLS_RSA_PSK_WITH_NULL_SHA 3891 * TLS_RSA_WITH_AES_128_CBC_SHA 3892 * TLS_DH_DSS_WITH_AES_128_CBC_SHA 3893 * TLS_DH_RSA_WITH_AES_128_CBC_SHA 3894 * TLS_DHE_DSS_WITH_AES_128_CBC_SHA 3895 * TLS_DHE_RSA_WITH_AES_128_CBC_SHA 3896 * TLS_DH_anon_WITH_AES_128_CBC_SHA 3897 * TLS_RSA_WITH_AES_256_CBC_SHA 3898 * TLS_DH_DSS_WITH_AES_256_CBC_SHA 3899 * TLS_DH_RSA_WITH_AES_256_CBC_SHA 3900 * TLS_DHE_DSS_WITH_AES_256_CBC_SHA 3901 * TLS_DHE_RSA_WITH_AES_256_CBC_SHA 3902 * TLS_DH_anon_WITH_AES_256_CBC_SHA 3903 * TLS_RSA_WITH_NULL_SHA256 3904 * TLS_RSA_WITH_AES_128_CBC_SHA256 3905 * TLS_RSA_WITH_AES_256_CBC_SHA256 3906 * TLS_DH_DSS_WITH_AES_128_CBC_SHA256 3907 * TLS_DH_RSA_WITH_AES_128_CBC_SHA256 3908 * TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 3909 * TLS_RSA_WITH_CAMELLIA_128_CBC_SHA 3910 * TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA 3911 * TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA 3912 * TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA 3913 * TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA 3914 * TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA 3915 * TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 3916 * TLS_DH_DSS_WITH_AES_256_CBC_SHA256 3917 * TLS_DH_RSA_WITH_AES_256_CBC_SHA256 3918 * TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 3919 * TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 3920 * TLS_DH_anon_WITH_AES_128_CBC_SHA256 3921 * TLS_DH_anon_WITH_AES_256_CBC_SHA256 3922 * TLS_RSA_WITH_CAMELLIA_256_CBC_SHA 3923 * TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA 3924 * TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA 3925 * TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA 3926 * TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA 3927 * TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA 3928 * TLS_PSK_WITH_RC4_128_SHA 3929 * TLS_PSK_WITH_3DES_EDE_CBC_SHA 3930 * TLS_PSK_WITH_AES_128_CBC_SHA 3931 * TLS_PSK_WITH_AES_256_CBC_SHA 3932 * TLS_DHE_PSK_WITH_RC4_128_SHA 3933 * TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA 3934 * TLS_DHE_PSK_WITH_AES_128_CBC_SHA 3935 * TLS_DHE_PSK_WITH_AES_256_CBC_SHA 3936 * TLS_RSA_PSK_WITH_RC4_128_SHA 3937 * TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA 3938 * TLS_RSA_PSK_WITH_AES_128_CBC_SHA 3939 * TLS_RSA_PSK_WITH_AES_256_CBC_SHA 3940 * TLS_RSA_WITH_SEED_CBC_SHA 3941 * TLS_DH_DSS_WITH_SEED_CBC_SHA 3942 * TLS_DH_RSA_WITH_SEED_CBC_SHA 3943 * TLS_DHE_DSS_WITH_SEED_CBC_SHA 3944 * TLS_DHE_RSA_WITH_SEED_CBC_SHA 3945 * TLS_DH_anon_WITH_SEED_CBC_SHA 3946 * TLS_RSA_WITH_AES_128_GCM_SHA256 3947 * TLS_RSA_WITH_AES_256_GCM_SHA384 3948 * TLS_DH_RSA_WITH_AES_128_GCM_SHA256 3949 * TLS_DH_RSA_WITH_AES_256_GCM_SHA384 3950 * TLS_DH_DSS_WITH_AES_128_GCM_SHA256 3951 * TLS_DH_DSS_WITH_AES_256_GCM_SHA384 3952 * TLS_DH_anon_WITH_AES_128_GCM_SHA256 3953 * TLS_DH_anon_WITH_AES_256_GCM_SHA384 3954 * TLS_PSK_WITH_AES_128_GCM_SHA256 3955 * TLS_PSK_WITH_AES_256_GCM_SHA384 3956 * TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 3957 * TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 3958 * TLS_PSK_WITH_AES_128_CBC_SHA256 3959 * TLS_PSK_WITH_AES_256_CBC_SHA384 3960 * TLS_PSK_WITH_NULL_SHA256 3961 * TLS_PSK_WITH_NULL_SHA384 3962 * TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 3963 * TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 3964 * TLS_DHE_PSK_WITH_NULL_SHA256 3965 * TLS_DHE_PSK_WITH_NULL_SHA384 3966 * TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 3967 * TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 3968 * TLS_RSA_PSK_WITH_NULL_SHA256 3969 * TLS_RSA_PSK_WITH_NULL_SHA384 3970 * TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 3971 * TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA256 3972 * TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA256 3973 * TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA256 3974 * TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 3975 * TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA256 3976 * TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 3977 * TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA256 3978 * TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA256 3979 * TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA256 3980 * TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 3981 * TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA256 3982 * TLS_EMPTY_RENEGOTIATION_INFO_SCSV 3983 * TLS_ECDH_ECDSA_WITH_NULL_SHA 3984 * TLS_ECDH_ECDSA_WITH_RC4_128_SHA 3985 * TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 3986 * TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 3987 * TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 3988 * TLS_ECDHE_ECDSA_WITH_NULL_SHA 3989 * TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 3990 * TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 3991 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 3992 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 3993 * TLS_ECDH_RSA_WITH_NULL_SHA 3994 * TLS_ECDH_RSA_WITH_RC4_128_SHA 3995 * TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 3996 * TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 3997 * TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 3998 * TLS_ECDHE_RSA_WITH_NULL_SHA 3999 * TLS_ECDHE_RSA_WITH_RC4_128_SHA 4000 * TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 4001 * TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 4002 * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 4003 * TLS_ECDH_anon_WITH_NULL_SHA 4004 * TLS_ECDH_anon_WITH_RC4_128_SHA 4005 * TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 4006 * TLS_ECDH_anon_WITH_AES_128_CBC_SHA 4007 * TLS_ECDH_anon_WITH_AES_256_CBC_SHA 4008 * TLS_SRP_SHA_WITH_3DES_EDE_CBC_SHA 4009 * TLS_SRP_SHA_RSA_WITH_3DES_EDE_CBC_SHA 4010 * TLS_SRP_SHA_DSS_WITH_3DES_EDE_CBC_SHA 4011 * TLS_SRP_SHA_WITH_AES_128_CBC_SHA 4012 * TLS_SRP_SHA_RSA_WITH_AES_128_CBC_SHA 4013 * TLS_SRP_SHA_DSS_WITH_AES_128_CBC_SHA 4014 * TLS_SRP_SHA_WITH_AES_256_CBC_SHA 4015 * TLS_SRP_SHA_RSA_WITH_AES_256_CBC_SHA 4016 * TLS_SRP_SHA_DSS_WITH_AES_256_CBC_SHA 4017 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 4018 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 4019 * TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 4020 * TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 4021 * TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 4022 * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 4023 * TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 4024 * TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 4025 * TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 4026 * TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 4027 * TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 4028 * TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 4029 * TLS_ECDHE_PSK_WITH_RC4_128_SHA 4030 * TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA 4031 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA 4032 * TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA 4033 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 4034 * TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 4035 * TLS_ECDHE_PSK_WITH_NULL_SHA 4036 * TLS_ECDHE_PSK_WITH_NULL_SHA256 4037 * TLS_ECDHE_PSK_WITH_NULL_SHA384 4038 * TLS_RSA_WITH_ARIA_128_CBC_SHA256 4039 * TLS_RSA_WITH_ARIA_256_CBC_SHA384 4040 * TLS_DH_DSS_WITH_ARIA_128_CBC_SHA256 4041 * TLS_DH_DSS_WITH_ARIA_256_CBC_SHA384 4042 * TLS_DH_RSA_WITH_ARIA_128_CBC_SHA256 4043 * TLS_DH_RSA_WITH_ARIA_256_CBC_SHA384 4044 * TLS_DHE_DSS_WITH_ARIA_128_CBC_SHA256 4045 * TLS_DHE_DSS_WITH_ARIA_256_CBC_SHA384 4046 * TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256 4047 * TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384 4048 * TLS_DH_anon_WITH_ARIA_128_CBC_SHA256 4049 * TLS_DH_anon_WITH_ARIA_256_CBC_SHA384 4050 * TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256 4051 * TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384 4052 * TLS_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256 4053 * TLS_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384 4054 * TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256 4055 * TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384 4056 * TLS_ECDH_RSA_WITH_ARIA_128_CBC_SHA256 4057 * TLS_ECDH_RSA_WITH_ARIA_256_CBC_SHA384 4058 * TLS_RSA_WITH_ARIA_128_GCM_SHA256 4059 * TLS_RSA_WITH_ARIA_256_GCM_SHA384 4060 * TLS_DH_RSA_WITH_ARIA_128_GCM_SHA256 4061 * TLS_DH_RSA_WITH_ARIA_256_GCM_SHA384 4062 * TLS_DH_DSS_WITH_ARIA_128_GCM_SHA256 4063 * TLS_DH_DSS_WITH_ARIA_256_GCM_SHA384 4064 * TLS_DH_anon_WITH_ARIA_128_GCM_SHA256 4065 * TLS_DH_anon_WITH_ARIA_256_GCM_SHA384 4066 * TLS_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256 4067 * TLS_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384 4068 * TLS_ECDH_RSA_WITH_ARIA_128_GCM_SHA256 4069 * TLS_ECDH_RSA_WITH_ARIA_256_GCM_SHA384 4070 * TLS_PSK_WITH_ARIA_128_CBC_SHA256 4071 * TLS_PSK_WITH_ARIA_256_CBC_SHA384 4072 * TLS_DHE_PSK_WITH_ARIA_128_CBC_SHA256 4073 * TLS_DHE_PSK_WITH_ARIA_256_CBC_SHA384 4074 * TLS_RSA_PSK_WITH_ARIA_128_CBC_SHA256 4075 * TLS_RSA_PSK_WITH_ARIA_256_CBC_SHA384 4076 * TLS_PSK_WITH_ARIA_128_GCM_SHA256 4077 * TLS_PSK_WITH_ARIA_256_GCM_SHA384 4078 * TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256 4079 * TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384 4080 * TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256 4081 * TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384 4082 * TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 4083 * TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 4084 * TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 4085 * TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 4086 * TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 4087 * TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 4088 * TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256 4089 * TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384 4090 * TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256 4091 * TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384 4092 * TLS_DH_RSA_WITH_CAMELLIA_128_GCM_SHA256 4093 * TLS_DH_RSA_WITH_CAMELLIA_256_GCM_SHA384 4094 * TLS_DH_DSS_WITH_CAMELLIA_128_GCM_SHA256 4095 * TLS_DH_DSS_WITH_CAMELLIA_256_GCM_SHA384 4096 * TLS_DH_anon_WITH_CAMELLIA_128_GCM_SHA256 4097 * TLS_DH_anon_WITH_CAMELLIA_256_GCM_SHA384 4098 * TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 4099 * TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 4100 * TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256 4101 * TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384 4102 * TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 4103 * TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 4104 * TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256 4105 * TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384 4106 * TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256 4107 * TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 4108 * TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 4109 * TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 4110 * TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 4111 * TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 4112 * TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 4113 * TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 4114 * TLS_RSA_WITH_AES_128_CCM 4115 * TLS_RSA_WITH_AES_256_CCM 4116 * TLS_RSA_WITH_AES_128_CCM_8 4117 * TLS_RSA_WITH_AES_256_CCM_8 4118 * TLS_PSK_WITH_AES_128_CCM 4119 * TLS_PSK_WITH_AES_256_CCM 4120 * TLS_PSK_WITH_AES_128_CCM_8 4121 * TLS_PSK_WITH_AES_256_CCM_8 4123 | Note: This list was assembled from the set of registered TLS 4124 | cipher suites when [RFC7540] was developed. This list includes 4125 | those cipher suites that do not offer an ephemeral key exchange 4126 | and those that are based on the TLS null, stream, or block 4127 | cipher type (as defined in Section 6.2.3 of [TLS12]). 4128 | Additional cipher suites with these properties could be 4129 | defined; these would not be explicitly prohibited. 4131 For more details, see Section 9.2.2 4133 Appendix B. Changes from RFC 7540 4135 This revision includes the following substantive changes: 4137 * Use of TLS 1.3 was defined based on RFC 8740, which this document 4138 obsoletes. 4140 * The priority scheme defined in RFC 7540 is deprecated. 4141 Definitions for the format of the PRIORITY frame and the priority 4142 fields in the HEADERS frame have been retained, plus the rules 4143 governing when PRIORITY frames can be sent and received, but the 4144 semantics of these fields are only described in RFC 7540. The 4145 priority signaling scheme from RFC 7540 was not successful. Using 4146 the simpler successor signaling [I-D.ietf-httpbis-priority] is 4147 recommended. 4149 * The HTTP/1.1 Upgrade mechanism is deprecated and no longer 4150 specified in this document. It was never widely deployed, with 4151 plaintext HTTP/2 users choosing to use the prior-knowledge 4152 implementation instead. 4154 * Validation for field names and values has been narrowed. The 4155 validation that is mandatory for intermediaries is precisely 4156 defined and error reporting for requests has been amended to 4157 encourage sending 400-series status codes. 4159 * The ranges of codepoints for settings and frame types that were 4160 reserved for "Experimental Use" are now available for general use. 4162 * Connection-specific header fields - which are prohibited - are 4163 more precisely and comprehensively identified. 4165 * Host and :authority are no longer permitted to disagree. 4167 * Rules for sending Dynamic Table Size Update instructions after 4168 changes in settings have been clarified in Section 4.3.1. 4170 Editorial changes are also included. In particular, changes to 4171 terminology and document structure are in response to updates to core 4172 HTTP semantics [HTTP]. Those documents now include some concepts 4173 that were first defined in RFC 7540, such as the 421 status code or 4174 connection coalescing. 4176 Contributors 4178 The previous version of this document was authored by Mike Belshe and 4179 Roberto Peon. 4181 Acknowledgments 4183 Credit for non-trivial input to this document is owed to a large 4184 number of people who have contributed to the HTTP working group over 4185 the years. [RFC7540] contains a more extensive list of people that 4186 deserve acknowledgment for their contributions. 4188 Authors' Addresses 4190 Martin Thomson (editor) 4191 Mozilla 4192 Australia 4194 Email: mt@lowentropy.net 4196 Cory Benfield (editor) 4197 Apple Inc. 4199 Email: cbenfield@apple.com