idnits 2.17.1 draft-ietf-httpbis-http2bis-03.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 (12 July 2021) is 1019 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-15 -- Possible downref: Normative reference to a draft: ref. 'CACHE' -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS186' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-15 -- 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 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-15 == Outdated reference: A later version (-12) exists of draft-ietf-httpbis-priority-03 -- Obsolete informational reference (is this intentional?): RFC 4492 (Obsoleted by RFC 8422) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 8740 (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 7525 (ref. 'TLSBCP') (Obsoleted by RFC 9325) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 10 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: 13 January 2022 12 July 2021 8 Hypertext Transfer Protocol Version 2 (HTTP/2) 9 draft-ietf-httpbis-http2bis-03 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 perception of latency by introducing header 17 field compression and allowing multiple concurrent exchanges on the 18 same connection. 20 This specification is an alternative to, but does not obsolete, the 21 HTTP/1.1 message syntax. HTTP's existing semantics remain unchanged. 22 This document obsoletes RFC 7540 and RFC 8740. 24 Discussion Venues 26 This note is to be removed before publishing as an RFC. 28 Discussion of this document takes place on the HTTPBIS Working Group 29 mailing list (ietf-http-wg@w3.org), which is archived at 30 https://lists.w3.org/Archives/Public/ietf-http-wg/. 32 Source for this draft and an issue tracker can be found at 33 https://github.com/httpwg/http2-spec. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on 13 January 2022. 51 Copyright Notice 53 Copyright (c) 2021 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 58 license-info) in effect on the date of publication of this document. 59 Please review these documents carefully, as they describe your rights 60 and restrictions with respect to this document. Code Components 61 extracted from this document must include Simplified BSD License text 62 as described in Section 4.e of the Trust Legal Provisions and are 63 provided without warranty as described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. HTTP/2 Protocol Overview . . . . . . . . . . . . . . . . . . 5 69 2.1. Document Organization . . . . . . . . . . . . . . . . . . 6 70 2.2. Conventions and Terminology . . . . . . . . . . . . . . . 6 71 3. Starting HTTP/2 . . . . . . . . . . . . . . . . . . . . . . . 7 72 3.1. HTTP/2 Version Identification . . . . . . . . . . . . . . 8 73 3.2. Starting HTTP/2 for "https" URIs . . . . . . . . . . . . 8 74 3.3. Starting HTTP/2 with Prior Knowledge . . . . . . . . . . 8 75 3.4. HTTP/2 Connection Preface . . . . . . . . . . . . . . . . 9 76 4. HTTP Frames . . . . . . . . . . . . . . . . . . . . . . . . . 10 77 4.1. Frame Format . . . . . . . . . . . . . . . . . . . . . . 10 78 4.2. Frame Size . . . . . . . . . . . . . . . . . . . . . . . 11 79 4.3. Field Section Compression and Decompression . . . . . . . 12 80 5. Streams and Multiplexing . . . . . . . . . . . . . . . . . . 13 81 5.1. Stream States . . . . . . . . . . . . . . . . . . . . . . 14 82 5.1.1. Stream Identifiers . . . . . . . . . . . . . . . . . 19 83 5.1.2. Stream Concurrency . . . . . . . . . . . . . . . . . 19 84 5.2. Flow Control . . . . . . . . . . . . . . . . . . . . . . 20 85 5.2.1. Flow-Control Principles . . . . . . . . . . . . . . . 20 86 5.2.2. Appropriate Use of Flow Control . . . . . . . . . . . 21 87 5.2.3. Flow Control Performance . . . . . . . . . . . . . . 22 88 5.3. Prioritization . . . . . . . . . . . . . . . . . . . . . 22 89 5.3.1. Background of Priority in HTTP/2 . . . . . . . . . . 22 90 5.3.2. Priority Signaling in this Document . . . . . . . . . 23 91 5.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 23 92 5.4.1. Connection Error Handling . . . . . . . . . . . . . . 24 93 5.4.2. Stream Error Handling . . . . . . . . . . . . . . . . 25 94 5.4.3. Connection Termination . . . . . . . . . . . . . . . 25 95 5.5. Extending HTTP/2 . . . . . . . . . . . . . . . . . . . . 25 96 6. Frame Definitions . . . . . . . . . . . . . . . . . . . . . . 26 97 6.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . 27 98 6.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . . . 28 99 6.3. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . 30 100 6.4. RST_STREAM . . . . . . . . . . . . . . . . . . . . . . . 31 101 6.5. SETTINGS . . . . . . . . . . . . . . . . . . . . . . . . 32 102 6.5.1. SETTINGS Format . . . . . . . . . . . . . . . . . . . 33 103 6.5.2. Defined Settings . . . . . . . . . . . . . . . . . . 34 104 6.5.3. Settings Synchronization . . . . . . . . . . . . . . 36 105 6.6. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . . . 36 106 6.7. PING . . . . . . . . . . . . . . . . . . . . . . . . . . 38 107 6.8. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . . . 39 108 6.9. WINDOW_UPDATE . . . . . . . . . . . . . . . . . . . . . . 42 109 6.9.1. The Flow-Control Window . . . . . . . . . . . . . . . 44 110 6.9.2. Initial Flow-Control Window Size . . . . . . . . . . 45 111 6.9.3. Reducing the Stream Window Size . . . . . . . . . . . 46 112 6.10. CONTINUATION . . . . . . . . . . . . . . . . . . . . . . 46 113 7. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 47 114 8. Expressing HTTP Semantics in HTTP/2 . . . . . . . . . . . . . 48 115 8.1. HTTP Message Framing . . . . . . . . . . . . . . . . . . 49 116 8.1.1. Malformed Messages . . . . . . . . . . . . . . . . . 50 117 8.2. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . . 51 118 8.2.1. Field Validity . . . . . . . . . . . . . . . . . . . 51 119 8.2.2. Connection-Specific Header Fields . . . . . . . . . . 52 120 8.2.3. Compressing the Cookie Header Field . . . . . . . . . 53 121 8.3. HTTP Control Data . . . . . . . . . . . . . . . . . . . . 53 122 8.3.1. Request Pseudo-Header Fields . . . . . . . . . . . . 54 123 8.3.2. Response Pseudo-Header Fields . . . . . . . . . . . . 55 124 8.4. Server Push . . . . . . . . . . . . . . . . . . . . . . . 56 125 8.4.1. Push Requests . . . . . . . . . . . . . . . . . . . . 57 126 8.4.2. Push Responses . . . . . . . . . . . . . . . . . . . 58 127 8.5. The CONNECT Method . . . . . . . . . . . . . . . . . . . 59 128 8.6. The Upgrade Header Field . . . . . . . . . . . . . . . . 60 129 8.7. Request Reliability . . . . . . . . . . . . . . . . . . . 61 130 8.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . 61 131 9. HTTP/2 Connections . . . . . . . . . . . . . . . . . . . . . 64 132 9.1. Connection Management . . . . . . . . . . . . . . . . . . 64 133 9.1.1. Connection Reuse . . . . . . . . . . . . . . . . . . 65 134 9.2. Use of TLS Features . . . . . . . . . . . . . . . . . . . 66 135 9.2.1. TLS 1.2 Features . . . . . . . . . . . . . . . . . . 66 136 9.2.2. TLS 1.2 Cipher Suites . . . . . . . . . . . . . . . . 67 137 9.2.3. TLS 1.3 Features . . . . . . . . . . . . . . . . . . 68 138 10. Security Considerations . . . . . . . . . . . . . . . . . . . 68 139 10.1. Server Authority . . . . . . . . . . . . . . . . . . . . 68 140 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 69 141 10.3. Intermediary Encapsulation Attacks . . . . . . . . . . . 69 142 10.4. Cacheability of Pushed Responses . . . . . . . . . . . . 70 143 10.5. Denial-of-Service Considerations . . . . . . . . . . . . 70 144 10.5.1. Limits on Field Block Size . . . . . . . . . . . . . 72 145 10.5.2. CONNECT Issues . . . . . . . . . . . . . . . . . . . 72 146 10.6. Use of Compression . . . . . . . . . . . . . . . . . . . 72 147 10.7. Use of Padding . . . . . . . . . . . . . . . . . . . . . 73 148 10.8. Privacy Considerations . . . . . . . . . . . . . . . . . 74 149 10.9. Remote Timing Attacks . . . . . . . . . . . . . . . . . 74 150 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 151 11.1. Registration of HTTP/2 Identification Strings . . . . . 75 152 11.2. Frame Type Registry . . . . . . . . . . . . . . . . . . 75 153 11.3. Settings Registry . . . . . . . . . . . . . . . . . . . 76 154 11.4. Error Code Registry . . . . . . . . . . . . . . . . . . 77 155 11.5. HTTP2-Settings Header Field Registration . . . . . . . . 79 156 11.6. PRI Method Registration . . . . . . . . . . . . . . . . 79 157 11.7. The h2c Upgrade Token . . . . . . . . . . . . . . . . . 79 158 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 79 159 12.1. Normative References . . . . . . . . . . . . . . . . . . 79 160 12.2. Informative References . . . . . . . . . . . . . . . . . 81 161 Appendix A. Prohibited TLS 1.2 Cipher Suites . . . . . . . . . . 83 162 Appendix B. Changes from RFC 7540 . . . . . . . . . . . . . . . 89 163 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 89 164 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 89 165 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90 167 1. Introduction 169 The Hypertext Transfer Protocol (HTTP) is a wildly successful 170 protocol. However, the way HTTP/1.1 uses the underlying transport 171 ([HTTP11]) has several characteristics that have a negative overall 172 effect on application performance today. 174 In particular, HTTP/1.0 allowed only one request to be outstanding at 175 a time on a given TCP connection. HTTP/1.1 added request pipelining, 176 but this only partially addressed request concurrency and still 177 suffers from head-of-line blocking. Therefore, HTTP/1.0 and HTTP/1.1 178 clients that need to make many requests use multiple connections to a 179 server in order to achieve concurrency and thereby reduce latency. 181 Furthermore, HTTP header fields are often repetitive and verbose, 182 causing unnecessary network traffic as well as causing the initial 183 TCP [TCP] congestion window to quickly fill. This can result in 184 excessive latency when multiple requests are made on a new TCP 185 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 request and response messages on the same 190 connection and uses an efficient coding for HTTP header fields. It 191 also allows prioritization of requests, letting more important 192 requests complete more quickly, 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. 199 Finally, HTTP/2 also enables more efficient processing of messages 200 through use of binary message framing. 202 This document obsoletes RFC 7540 [RFC7540] and RFC 8740 [RFC8740]. 204 2. HTTP/2 Protocol Overview 206 HTTP/2 provides an optimized transport for HTTP semantics. HTTP/2 207 supports all of the core features of HTTP but aims to be more 208 efficient than HTTP/1.1. 210 The basic protocol unit in HTTP/2 is a frame (Section 4.1). Each 211 frame type serves a different purpose. For example, HEADERS and DATA 212 frames form the basis of HTTP requests and responses (Section 8.1); 213 other frame types like SETTINGS, WINDOW_UPDATE, and PUSH_PROMISE are 214 used in support of other HTTP/2 features. 216 Multiplexing of requests is achieved by having each HTTP request/ 217 response exchange associated with its own stream (Section 5). 218 Streams are largely independent of each other, so a blocked or 219 stalled request or response does not prevent progress on other 220 streams. 222 Flow control and prioritization ensure that it is possible to 223 efficiently use multiplexed streams. Flow control (Section 5.2) 224 helps to ensure that only data that can be used by a receiver is 225 transmitted. Prioritization (Section 5.3) ensures that limited 226 resources can be directed to the most important streams first. 228 Because HTTP header fields used in a connection can contain large 229 amounts of redundant data, frames that contain them are compressed 230 (Section 4.3). This has especially advantageous impact upon request 231 sizes in the common case, allowing many requests to be compressed 232 into one packet. 234 Finally, HTTP/2 adds a new, optional interaction mode whereby a 235 server can push responses to a client (Section 8.4). This is 236 intended to allow a server to speculatively send data to a client 237 that the server anticipates the client will need, trading off some 238 network usage against a potential latency gain. The server does this 239 by synthesizing a request, which it sends as a PUSH_PROMISE frame. 240 The server is then able to send a response to the synthetic request 241 on a separate stream. 243 2.1. Document Organization 245 The HTTP/2 specification is split into four parts: 247 * Starting HTTP/2 (Section 3) covers how an HTTP/2 connection is 248 initiated. 250 * The frame (Section 4) and stream (Section 5) layers describe the 251 way HTTP/2 frames are structured and formed into multiplexed 252 streams. 254 * Frame (Section 6) and error (Section 7) definitions include 255 details of the frame and error types used in HTTP/2. 257 * HTTP mappings (Section 8) and additional requirements (Section 9) 258 describe how HTTP semantics are expressed using frames and 259 streams. 261 While some of the frame and stream layer concepts are isolated from 262 HTTP, this specification does not define a completely generic frame 263 layer. The frame and stream layers are tailored to the needs of the 264 HTTP protocol and server push. 266 2.2. Conventions and Terminology 268 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 269 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 270 document are to be interpreted as described in RFC 2119 [RFC2119]. 272 All numeric values are in network byte order. Values are unsigned 273 unless otherwise indicated. Literal values are provided in decimal 274 or hexadecimal as appropriate. Hexadecimal literals are prefixed 275 with "0x" to distinguish them from decimal literals. 277 This specification describes binary formats using the convention 278 described in Section 1.3 of RFC 9000 [QUIC]. 280 The following terms are used: 282 client: The endpoint that initiates an HTTP/2 connection. Clients 283 send HTTP requests and receive HTTP responses. 285 connection: A transport-layer connection between two endpoints. 287 connection error: An error that affects the entire HTTP/2 288 connection. 290 endpoint: Either the client or server of the connection. 292 frame: The smallest unit of communication within an HTTP/2 293 connection, consisting of a header and a variable-length sequence 294 of octets structured according to the frame type. 296 peer: An endpoint. When discussing a particular endpoint, "peer" 297 refers to the endpoint that is remote to the primary subject of 298 discussion. 300 receiver: An endpoint that is receiving frames. 302 sender: An endpoint that is transmitting frames. 304 server: The endpoint that accepts an HTTP/2 connection. Servers 305 receive HTTP requests and send HTTP responses. 307 stream: A bidirectional flow of frames within the HTTP/2 connection. 309 stream error: An error on the individual HTTP/2 stream. 311 Finally, the terms "gateway", "intermediary", "proxy", and "tunnel" 312 are defined in Section 3.7 of [HTTP]. Intermediaries act as both 313 client and server at different times. 315 The term "content" as it applies to message bodies is defined in 316 Section 6.4 of [HTTP]. 318 3. Starting HTTP/2 320 An HTTP/2 connection is an application-layer protocol running on top 321 of a TCP connection ([TCP]). The client is the TCP connection 322 initiator. 324 HTTP/2 uses the "http" and "https" URI schemes defined in Section 4.2 325 of [HTTP], with the same default port numbers. As a result, 326 implementations processing requests for target resource URIs like 327 "http://example.org/foo" or "https://example.com/bar" are required to 328 first discover whether the upstream server (the immediate peer to 329 which the client wishes to establish a connection) supports HTTP/2. 331 The means by which support for HTTP/2 is determined is different for 332 "http" and "https" URIs. Discovery for "https" URIs is described in 333 Section 3.2. HTTP/2 support for "http" URIs can only be discovered 334 by out-of-band means, and requires prior knowledge of the support as 335 described in Section 3.3. 337 3.1. HTTP/2 Version Identification 339 The protocol defined in this document has two identifiers. 341 * The string "h2" identifies the protocol where HTTP/2 uses 342 Transport Layer Security (TLS) [TLS13]. This identifier is used 343 in the TLS application-layer protocol negotiation (ALPN) extension 344 [TLS-ALPN] field and in any place where HTTP/2 over TLS is 345 identified. 347 The "h2" string is serialized into an ALPN protocol identifier as 348 the two-octet sequence: 0x68, 0x32. 350 * The string "h2c" identifies the protocol where HTTP/2 is run over 351 cleartext TCP. This identifier is used in any place where HTTP/2 352 over TCP is identified. 354 The "h2c" string is reserved from the ALPN identifier space but 355 describes a protocol that does not use TLS. 357 The "h2c" string was previously used as a token for use in the 358 HTTP Upgrade mechanism's Upgrade header field (Section 7.8 of 359 [HTTP]). This usage was never widely deployed, and is no longer 360 specified in this document. 362 Negotiating "h2" or "h2c" implies the use of the transport, security, 363 framing, and message semantics described in this document. 365 3.2. Starting HTTP/2 for "https" URIs 367 A client that makes a request to an "https" URI uses TLS [TLS13] with 368 the application-layer protocol negotiation (ALPN) extension 369 [TLS-ALPN]. 371 HTTP/2 over TLS uses the "h2" protocol identifier. The "h2c" 372 protocol identifier MUST NOT be sent by a client or selected by a 373 server; the "h2c" protocol identifier describes a protocol that does 374 not use TLS. 376 Once TLS negotiation is complete, both the client and the server MUST 377 send a connection preface (Section 3.4). 379 3.3. Starting HTTP/2 with Prior Knowledge 381 A client can learn that a particular server supports HTTP/2 by other 382 means. For example, [ALT-SVC] describes a mechanism for advertising 383 this capability. 385 A client MUST send the connection preface (Section 3.4) and then MAY 386 immediately send HTTP/2 frames to such a server; servers can identify 387 these connections by the presence of the connection preface. This 388 only affects the establishment of HTTP/2 connections over cleartext 389 TCP; implementations that support HTTP/2 over TLS MUST use protocol 390 negotiation in TLS [TLS-ALPN]. 392 Likewise, the server MUST send a connection preface (Section 3.4). 394 Without additional information, prior support for HTTP/2 is not a 395 strong signal that a given server will support HTTP/2 for future 396 connections. For example, it is possible for server configurations 397 to change, for configurations to differ between instances in 398 clustered servers, or for network conditions to change. 400 3.4. HTTP/2 Connection Preface 402 In HTTP/2, each endpoint is required to send a connection preface as 403 a final confirmation of the protocol in use and to establish the 404 initial settings for the HTTP/2 connection. The client and server 405 each send a different connection preface. 407 The client connection preface starts with a sequence of 24 octets, 408 which in hex notation is: 410 0x505249202a20485454502f322e300d0a0d0a534d0d0a0d0a 412 That is, the connection preface starts with the string "PRI * 413 HTTP/2.0\r\n\r\nSM\r\n\r\n". This sequence MUST be followed by a 414 SETTINGS frame (Section 6.5), which MAY be empty. The client sends 415 the client connection preface as the first application data octets of 416 a connection. 418 | Note: The client connection preface is selected so that a large 419 | proportion of HTTP/1.1 or HTTP/1.0 servers and intermediaries 420 | do not attempt to process further frames. Note that this does 421 | not address the concerns raised in [TALKING]. 423 The server connection preface consists of a potentially empty 424 SETTINGS frame (Section 6.5) that MUST be the first frame the server 425 sends in the HTTP/2 connection. 427 The SETTINGS frames received from a peer as part of the connection 428 preface MUST be acknowledged (see Section 6.5.3) after sending the 429 connection preface. 431 To avoid unnecessary latency, clients are permitted to send 432 additional frames to the server immediately after sending the client 433 connection preface, without waiting to receive the server connection 434 preface. It is important to note, however, that the server 435 connection preface SETTINGS frame might include settings that 436 necessarily alter how a client is expected to communicate with the 437 server. Upon receiving the SETTINGS frame, the client is expected to 438 honor any settings established. In some configurations, it is 439 possible for the server to transmit SETTINGS before the client sends 440 additional frames, providing an opportunity to avoid this issue. 442 Clients and servers MUST treat an invalid connection preface as a 443 connection error (Section 5.4.1) of type PROTOCOL_ERROR. A GOAWAY 444 frame (Section 6.8) MAY be omitted in this case, since an invalid 445 preface indicates that the peer is not using HTTP/2. 447 4. HTTP Frames 449 Once the HTTP/2 connection is established, endpoints can begin 450 exchanging frames. 452 4.1. Frame Format 454 All frames begin with a fixed 9-octet header followed by a variable- 455 length frame payload. 457 HTTP Frame { 458 Length (24), 459 Type (8), 460 Flags (8), 461 Reserved (1), 462 Stream Identifier (31), 463 Frame Payload (..), 464 } 466 Figure 1: Frame Layout 468 The fields of the frame header are defined as: 470 Length: The length of the frame payload expressed as an unsigned 471 24-bit integer. Values greater than 2^14 (16,384) MUST NOT be 472 sent unless the receiver has set a larger value for 473 SETTINGS_MAX_FRAME_SIZE. 475 The 9 octets of the frame header are not included in this value. 477 Type: The 8-bit type of the frame. The frame type determines the 478 format and semantics of the frame. Implementations MUST ignore 479 and discard any frame that has a type that is unknown. 481 Flags: An 8-bit field reserved for boolean flags specific to the 482 frame type. 484 Flags are assigned semantics specific to the indicated frame type. 485 Unused Flags are those that have no defined semantics for a 486 particular frame type, and MUST be ignored and MUST be left unset 487 (0x0) when sending. 489 Reserved: A reserved 1-bit field. The semantics of this bit are 490 undefined, and the bit MUST remain unset (0x0) when sending and 491 MUST be ignored when receiving. 493 Stream Identifier: A stream identifier (see Section 5.1.1) expressed 494 as an unsigned 31-bit integer. The value 0x0 is reserved for 495 frames that are associated with the connection as a whole as 496 opposed to an individual stream. 498 The structure and content of the frame payload is dependent entirely 499 on the frame type. 501 4.2. Frame Size 503 The size of a frame payload is limited by the maximum size that a 504 receiver advertises in the SETTINGS_MAX_FRAME_SIZE setting. This 505 setting can have any value between 2^14 (16,384) and 2^24-1 506 (16,777,215) octets, inclusive. 508 All implementations MUST be capable of receiving and minimally 509 processing frames up to 2^14 octets in length, plus the 9-octet frame 510 header (Section 4.1). The size of the frame header is not included 511 when describing frame sizes. 513 | Note: Certain frame types, such as PING (Section 6.7), impose 514 | additional limits on the amount of frame payload data allowed. 516 An endpoint MUST send an error code of FRAME_SIZE_ERROR if a frame 517 exceeds the size defined in SETTINGS_MAX_FRAME_SIZE, exceeds any 518 limit defined for the frame type, or is too small to contain 519 mandatory frame data. A frame size error in a frame that could alter 520 the state of the entire connection MUST be treated as a connection 521 error (Section 5.4.1); this includes any frame carrying a field block 522 (Section 4.3) (that is, HEADERS, PUSH_PROMISE, and CONTINUATION), 523 SETTINGS, and any frame with a stream identifier of 0. 525 Endpoints are not obligated to use all available space in a frame. 526 Responsiveness can be improved by using frames that are smaller than 527 the permitted maximum size. Sending large frames can result in 528 delays in sending time-sensitive frames (such as RST_STREAM, 529 WINDOW_UPDATE, or PRIORITY), which, if blocked by the transmission of 530 a large frame, could affect performance. 532 4.3. Field Section Compression and Decompression 534 Field section compression is the process of compressing a set of 535 field lines to form a field block. Field section decompression is 536 the process of decoding a field block into a set of field lines. 537 Details of HTTP/2 field section compression and decompression is 538 defined in [COMPRESSION], which, for historical reasons, refers to 539 these processes as header compression and decompression. 541 Field blocks carry the compressed bytes of a field section, with 542 header sections also carrying control data associated with the 543 message in the form of pseudo-header fields (Section 8.3) that use 544 the same format as a field line. 546 | Note: Previous versions of this specification used the term 547 | "header block" in place of the more generic "field block". 549 Field blocks carry control data and header sections for requests, 550 responses, promised requests, and pushed responses (see Section 8.4). 551 All these messages, except for interim responses and requests 552 contained in PUSH_PROMISE (Section 6.6) frames can optionally include 553 a field block that carries a trailer section. 555 A field section is a collection of zero or more field lines. Each of 556 the field lines in a field block carry a single value. The 557 serialized field block is then divided into one or more octet 558 sequences, called field block fragments, and transmitted within the 559 frame payload of HEADERS (Section 6.2) or PUSH_PROMISE (Section 6.6), 560 each of which could be followed by CONTINUATION (Section 6.10) 561 frames. 563 The Cookie header field [COOKIE] is treated specially by the HTTP 564 mapping (see Section 8.2.3). 566 A receiving endpoint reassembles the field block by concatenating its 567 fragments and then decompresses the block to reconstruct the field 568 section. 570 A complete field section consists of either: 572 * a single HEADERS or PUSH_PROMISE frame, with the END_HEADERS flag 573 set, or 575 * a HEADERS or PUSH_PROMISE frame with the END_HEADERS flag cleared 576 and one or more CONTINUATION frames, where the last CONTINUATION 577 frame has the END_HEADERS flag set. 579 Field compression is stateful. One compression context and one 580 decompression context are used for the entire connection. A decoding 581 error in a field block MUST be treated as a connection error 582 (Section 5.4.1) of type COMPRESSION_ERROR. 584 Each field block is processed as a discrete unit. Field blocks MUST 585 be transmitted as a contiguous sequence of frames, with no 586 interleaved frames of any other type or from any other stream. The 587 last frame in a sequence of HEADERS or CONTINUATION frames has the 588 END_HEADERS flag set. The last frame in a sequence of PUSH_PROMISE 589 or CONTINUATION frames has the END_HEADERS flag set. This allows a 590 field block to be logically equivalent to a single frame. 592 Field block fragments can only be sent as the frame payload of 593 HEADERS, PUSH_PROMISE, or CONTINUATION frames because these frames 594 carry data that can modify the compression context maintained by a 595 receiver. An endpoint receiving HEADERS, PUSH_PROMISE, or 596 CONTINUATION frames needs to reassemble field blocks and perform 597 decompression even if the frames are to be discarded. A receiver 598 MUST terminate the connection with a connection error (Section 5.4.1) 599 of type COMPRESSION_ERROR if it does not decompress a field block. 601 5. Streams and Multiplexing 603 A "stream" is an independent, bidirectional sequence of frames 604 exchanged between the client and server within an HTTP/2 connection. 605 Streams have several important characteristics: 607 * A single HTTP/2 connection can contain multiple concurrently open 608 streams, with either endpoint interleaving frames from multiple 609 streams. 611 * Streams can be established and used unilaterally or shared by 612 either the client or server. 614 * Streams can be closed by either endpoint. 616 * The order in which frames are sent on a stream is significant. 617 Recipients process frames in the order they are received. In 618 particular, the order of HEADERS and DATA frames is semantically 619 significant. 621 * Streams are identified by an integer. Stream identifiers are 622 assigned to streams by the endpoint initiating the stream. 624 5.1. Stream States 626 The lifecycle of a stream is shown in Figure 2. 628 +--------+ 629 send PP | | recv PP 630 ,--------| idle |--------. 631 / | | \ 632 v +--------+ v 633 +----------+ | +----------+ 634 | | | send H / | | 635 ,------| reserved | | recv H | reserved |------. 636 | | (local) | | | (remote) | | 637 | +----------+ v +----------+ | 638 | | +--------+ | | 639 | | recv ES | | send ES | | 640 | send H | ,-------| open |-------. | recv H | 641 | | / | | \ | | 642 | v v +--------+ v v | 643 | +----------+ | +----------+ | 644 | | half | | | half | | 645 | | closed | | send R / | closed | | 646 | | (remote) | | recv R | (local) | | 647 | +----------+ | +----------+ | 648 | | | | | 649 | | send ES / | recv ES / | | 650 | | send R / v send R / | | 651 | | recv R +--------+ recv R | | 652 | send R / `----------->| |<-----------' send R / | 653 | recv R | closed | recv R | 654 `----------------------->| |<----------------------' 655 +--------+ 657 send: endpoint sends this frame 658 recv: endpoint receives this frame 660 H: HEADERS frame (with implied CONTINUATIONs) 661 ES: END_STREAM flag 662 R: RST_STREAM frame 663 PP: PUSH_PROMISE frame (with implied CONTINUATIONs) 664 Note: State transitions are for the promised stream. 666 Figure 2: Stream States 668 Note that this diagram shows stream state transitions and the frames 669 and flags that affect those transitions only. In this regard, 670 CONTINUATION frames do not result in state transitions; they are 671 effectively part of the HEADERS or PUSH_PROMISE that they follow. 672 For the purpose of state transitions, the END_STREAM flag is 673 processed as a separate event to the frame that bears it; a HEADERS 674 frame with the END_STREAM flag set can cause two state transitions. 676 Both endpoints have a subjective view of the state of a stream that 677 could be different when frames are in transit. Endpoints do not 678 coordinate the creation of streams; they are created unilaterally by 679 either endpoint. The negative consequences of a mismatch in states 680 are limited to the "closed" state after sending RST_STREAM, where 681 frames might be received for some time after closing. 683 Streams have the following states: 685 idle: All streams start in the "idle" state. 687 The following transitions are valid from this state: 689 * Sending or receiving a HEADERS frame causes the stream to 690 become "open". The stream identifier is selected as described 691 in Section 5.1.1. The same HEADERS frame can also cause a 692 stream to immediately become "half-closed". 694 * Sending a PUSH_PROMISE frame on another stream reserves the 695 idle stream that is identified for later use. The stream state 696 for the reserved stream transitions to "reserved (local)". 698 * Receiving a PUSH_PROMISE frame on another stream reserves an 699 idle stream that is identified for later use. The stream state 700 for the reserved stream transitions to "reserved (remote)". 702 * Note that the PUSH_PROMISE frame is not sent on the idle stream 703 but references the newly reserved stream in the Promised Stream 704 ID field. 706 Receiving any frame other than HEADERS or PRIORITY on a stream in 707 this state MUST be treated as a connection error (Section 5.4.1) 708 of type PROTOCOL_ERROR. 710 reserved (local): A stream in the "reserved (local)" state is one 711 that has been promised by sending a PUSH_PROMISE frame. A 712 PUSH_PROMISE frame reserves an idle stream by associating the 713 stream with an open stream that was initiated by the remote peer 714 (see Section 8.4). 716 In this state, only the following transitions are possible: 718 * The endpoint can send a HEADERS frame. This causes the stream 719 to open in a "half-closed (remote)" state. 721 * Either endpoint can send a RST_STREAM frame to cause the stream 722 to become "closed". This releases the stream reservation. 724 An endpoint MUST NOT send any type of frame other than HEADERS, 725 RST_STREAM, or PRIORITY in this state. 727 A PRIORITY or WINDOW_UPDATE frame MAY be received in this state. 728 Receiving any type of frame other than RST_STREAM, PRIORITY, or 729 WINDOW_UPDATE on a stream in this state MUST be treated as a 730 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 732 reserved (remote): A stream in the "reserved (remote)" state has 733 been reserved by a remote peer. 735 In this state, only the following transitions are possible: 737 * Receiving a HEADERS frame causes the stream to transition to 738 "half-closed (local)". 740 * Either endpoint can send a RST_STREAM frame to cause the stream 741 to become "closed". This releases the stream reservation. 743 An endpoint MUST NOT send any type of frame other than RST_STREAM, 744 WINDOW_UPDATE, or PRIORITY in this state. 746 Receiving any type of frame other than HEADERS, RST_STREAM, or 747 PRIORITY on a stream in this state MUST be treated as a connection 748 error (Section 5.4.1) of type PROTOCOL_ERROR. 750 open: A stream in the "open" state may be used by both peers to send 751 frames of any type. In this state, sending peers observe 752 advertised stream-level flow-control limits (Section 5.2). 754 From this state, either endpoint can send a frame with an 755 END_STREAM flag set, which causes the stream to transition into 756 one of the "half-closed" states. An endpoint sending an 757 END_STREAM flag causes the stream state to become "half-closed 758 (local)"; an endpoint receiving an END_STREAM flag causes the 759 stream state to become "half-closed (remote)". 761 Either endpoint can send a RST_STREAM frame from this state, 762 causing it to transition immediately to "closed". 764 half-closed (local): A stream that is in the "half-closed (local)" 765 state cannot be used for sending frames other than WINDOW_UPDATE, 766 PRIORITY, and RST_STREAM. 768 A stream transitions from this state to "closed" when a frame that 769 contains an END_STREAM flag is received or when either peer sends 770 a RST_STREAM frame. 772 An endpoint can receive any type of frame in this state. 773 Providing flow-control credit using WINDOW_UPDATE frames is 774 necessary to continue receiving flow-controlled frames. In this 775 state, a receiver can ignore WINDOW_UPDATE frames, which might 776 arrive for a short period after a frame bearing the END_STREAM 777 flag is sent. 779 PRIORITY frames can be received in this state. 781 half-closed (remote): A stream that is "half-closed (remote)" is no 782 longer being used by the peer to send frames. In this state, an 783 endpoint is no longer obligated to maintain a receiver flow- 784 control window. 786 If an endpoint receives additional frames, other than 787 WINDOW_UPDATE, PRIORITY, or RST_STREAM, for a stream that is in 788 this state, it MUST respond with a stream error (Section 5.4.2) of 789 type STREAM_CLOSED. 791 A stream that is "half-closed (remote)" can be used by the 792 endpoint to send frames of any type. In this state, the endpoint 793 continues to observe advertised stream-level flow-control limits 794 (Section 5.2). 796 A stream can transition from this state to "closed" by sending a 797 frame that contains an END_STREAM flag or when either peer sends a 798 RST_STREAM frame. 800 closed: The "closed" state is the terminal state. 802 An stream enters the "closed" state after an endpoint both sends 803 and receives a frame with an END_STREAM flag set. A stream also 804 enters the "closed" state after an endpoint either sends or 805 receives a RST_STREAM frame. 807 An endpoint MUST NOT send frames other than PRIORITY on a closed 808 stream. An endpoint MAY treat receipt of any other type of frame 809 on a "closed" stream as a connection error (Section 5.4.1) of type 810 STREAM_CLOSED, except as noted below. 812 An endpoint that sends a frame with the END_STREAM flag set or a 813 RST_STREAM frame might receive a WINDOW_UPDATE or RST_STREAM frame 814 from its peer in the time before the peer receives and processes 815 the frame that closes the stream. 817 An endpoint that sends a RST_STREAM frame on a stream that is in 818 the "open" state could receive any type of frame. The peer might 819 have sent or enqueued for sending these frames before processing 820 the RST_STREAM frame. An endpoint MUST minimally process and then 821 discard any frames it receives in this state. This means updating 822 header compression state for HEADERS and PUSH_PROMISE frames; 823 PUSH_PROMISE frames also cause the promised stream to become 824 "reserved", even when the PUSH_PROMISE frame is received on a 825 closed stream; and, the content of DATA frames counts toward the 826 connection flow-control window. 828 An endpoint can perform this minimal processing for all streams 829 that are in the "closed" state. Endpoints MAY use other signals 830 to detect that a peer has received the frames that caused stream 831 to become "closed" and treat receipt of any frame other than 832 PRIORITY as a connection error (Section 5.4.1) of type 833 PROTOCOL_ERROR. Endpoints can use frames that indicate that the 834 peer has received the closing signal to drive this. Endpoints 835 SHOULD NOT use timers for this purpose. For example, an endpoint 836 that sends a SETTINGS frame after closing a stream can safely 837 treat receipt of a DATA frame on that stream as an error after 838 receiving an acknowledgement of the settings. Other things that 839 might be used are PING frames, receiving data on streams that were 840 created after closing the stream, or responses to requests created 841 after closing the stream. 843 In the absence of more specific guidance elsewhere in this document, 844 implementations SHOULD treat the receipt of a frame that is not 845 expressly permitted in the description of a state as a connection 846 error (Section 5.4.1) of type PROTOCOL_ERROR. Note that PRIORITY can 847 be sent and received in any stream state. Frames of unknown types 848 are ignored. 850 An example of the state transitions for an HTTP request/response 851 exchange can be found in Section 8.8. An example of the state 852 transitions for server push can be found in Sections 8.4.1 and 8.4.2. 854 5.1.1. Stream Identifiers 856 Streams are identified with an unsigned 31-bit integer. Streams 857 initiated by a client MUST use odd-numbered stream identifiers; those 858 initiated by the server MUST use even-numbered stream identifiers. A 859 stream identifier of zero (0x0) is used for connection control 860 messages; the stream identifier of zero cannot be used to establish a 861 new stream. 863 The identifier of a newly established stream MUST be numerically 864 greater than all streams that the initiating endpoint has opened or 865 reserved. This governs streams that are opened using a HEADERS frame 866 and streams that are reserved using PUSH_PROMISE. An endpoint that 867 receives an unexpected stream identifier MUST respond with a 868 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 870 A HEADERS frame will transition the client-initiated stream 871 identified by the stream identifier in the frame header from "idle" 872 to "open". A PUSH_PROMISE frame will transition the server-initiated 873 stream identified by the "Promised Stream ID" field in the frame 874 payload from "idle" to "reserved". When a stream transitions out of 875 the "idle" state, all streams that might have been initiated by that 876 peer with a lower-valued stream identifier are implicitly 877 transitioned to "closed". That is, an endpoint may skip a stream 878 identifier, with the effect being that the skipped stream is 879 immediately closed. 881 Stream identifiers cannot be reused. Long-lived connections can 882 result in an endpoint exhausting the available range of stream 883 identifiers. A client that is unable to establish a new stream 884 identifier can establish a new connection for new streams. A server 885 that is unable to establish a new stream identifier can send a GOAWAY 886 frame so that the client is forced to open a new connection for new 887 streams. 889 5.1.2. Stream Concurrency 891 A peer can limit the number of concurrently active streams using the 892 SETTINGS_MAX_CONCURRENT_STREAMS parameter (see Section 6.5.2) within 893 a SETTINGS frame. The maximum concurrent streams setting is specific 894 to each endpoint and applies only to the peer that receives the 895 setting. That is, clients specify the maximum number of concurrent 896 streams the server can initiate, and servers specify the maximum 897 number of concurrent streams the client can initiate. 899 Streams that are in the "open" state or in either of the "half- 900 closed" states count toward the maximum number of streams that an 901 endpoint is permitted to open. Streams in any of these three states 902 count toward the limit advertised in the 903 SETTINGS_MAX_CONCURRENT_STREAMS setting. Streams in either of the 904 "reserved" states do not count toward the stream limit. 906 Endpoints MUST NOT exceed the limit set by their peer. An endpoint 907 that receives a HEADERS frame that causes its advertised concurrent 908 stream limit to be exceeded MUST treat this as a stream error 909 (Section 5.4.2) of type PROTOCOL_ERROR or REFUSED_STREAM. The choice 910 of error code determines whether the endpoint wishes to enable 911 automatic retry (see Section 8.7) for details). 913 An endpoint that wishes to reduce the value of 914 SETTINGS_MAX_CONCURRENT_STREAMS to a value that is below the current 915 number of open streams can either close streams that exceed the new 916 value or allow streams to complete. 918 5.2. Flow Control 920 Using streams for multiplexing introduces contention over use of the 921 TCP connection, resulting in blocked streams. A flow-control scheme 922 ensures that streams on the same connection do not destructively 923 interfere with each other. Flow control is used for both individual 924 streams and for the connection as a whole. 926 HTTP/2 provides for flow control through use of the WINDOW_UPDATE 927 frame (Section 6.9). 929 5.2.1. Flow-Control Principles 931 HTTP/2 stream flow control aims to allow a variety of flow-control 932 algorithms to be used without requiring protocol changes. Flow 933 control in HTTP/2 has the following characteristics: 935 1. Flow control is specific to a connection. Both types of flow 936 control are between the endpoints of a single hop and not over 937 the entire end-to-end path. 939 2. Flow control is based on WINDOW_UPDATE frames. Receivers 940 advertise how many octets they are prepared to receive on a 941 stream and for the entire connection. This is a credit-based 942 scheme. 944 3. Flow control is directional with overall control provided by the 945 receiver. A receiver MAY choose to set any window size that it 946 desires for each stream and for the entire connection. A sender 947 MUST respect flow-control limits imposed by a receiver. Clients, 948 servers, and intermediaries all independently advertise their 949 flow-control window as a receiver and abide by the flow-control 950 limits set by their peer when sending. 952 4. The initial value for the flow-control window is 65,535 octets 953 for both new streams and the overall connection. 955 5. The frame type determines whether flow control applies to a 956 frame. Of the frames specified in this document, only DATA 957 frames are subject to flow control; all other frame types do not 958 consume space in the advertised flow-control window. This 959 ensures that important control frames are not blocked by flow 960 control. 962 6. Flow control cannot be disabled. 964 7. HTTP/2 defines only the format and semantics of the WINDOW_UPDATE 965 frame (Section 6.9). This document does not stipulate how a 966 receiver decides when to send this frame or the value that it 967 sends, nor does it specify how a sender chooses to send packets. 968 Implementations are able to select any algorithm that suits their 969 needs. 971 Implementations are also responsible for prioritizing the sending of 972 requests and responses, choosing how to avoid head-of-line blocking 973 for requests, and managing the creation of new streams. Algorithm 974 choices for these could interact with any flow-control algorithm. 976 5.2.2. Appropriate Use of Flow Control 978 Flow control is defined to protect endpoints that are operating under 979 resource constraints. For example, a proxy needs to share memory 980 between many connections and also might have a slow upstream 981 connection and a fast downstream one. Flow-control addresses cases 982 where the receiver is unable to process data on one stream yet wants 983 to continue to process other streams in the same connection. 985 Deployments that do not require this capability can advertise a flow- 986 control window of the maximum size (2^31-1) and can maintain this 987 window by sending a WINDOW_UPDATE frame when any data is received. 988 This effectively disables flow control for that receiver. 989 Conversely, a sender is always subject to the flow-control window 990 advertised by the receiver. 992 Deployments with constrained resources (for example, memory) can 993 employ flow control to limit the amount of memory a peer can consume. 994 Note, however, that this can lead to suboptimal use of available 995 network resources if flow control is enabled without knowledge of the 996 bandwidth-delay product (see [RFC7323]). 998 Even with full awareness of the current bandwidth-delay product, 999 implementation of flow control can be difficult. When using flow 1000 control, the receiver MUST read from the TCP receive buffer in a 1001 timely fashion. Failure to do so could lead to a deadlock when 1002 critical frames, such as WINDOW_UPDATE, are not read and acted upon. 1004 5.2.3. Flow Control Performance 1006 If an endpoint cannot ensure that its peer always has available flow 1007 control window space that is greater than the peer's bandwidth-delay 1008 product on this connection, its receive throughput will be limited by 1009 HTTP/2 flow control. This will result in degraded performance. 1011 Sending timely WINDOW_UPDATE frames can improve performance. 1012 Endpoints will want to balance the need to improve receive throughput 1013 with the need to manage resource exhaustion risks, and should take 1014 careful note of Section 10.5 in defining their strategy to manage 1015 window sizes. 1017 5.3. Prioritization 1019 In a multiplexed protocol like HTTP/2, prioritizing allocation of 1020 bandwidth and computation resources to streams can be critical to 1021 attaining good performance. A poor prioritization scheme can result 1022 in HTTP/2 providing poor performance. With no parallelism at the TCP 1023 layer, performance could be significantly worse than HTTP/1.1. 1025 A good prioritization scheme benefits from the application of 1026 contextual knowledge such as the content of resources, how resources 1027 are interrelated, and how those resources will be used by a peer. In 1028 particular, clients can possess knowledge about the priority of 1029 requests that is relevant to server prioritization. In those cases, 1030 having clients provide priority information can improve performance. 1032 5.3.1. Background of Priority in HTTP/2 1034 HTTP/2 included a rich system for signaling priority of requests. 1035 However, this system proved to be complex and it was not uniformly 1036 implemented. 1038 The flexible scheme meant that it was possible for clients to express 1039 priorities in very different ways, with little consistency in the 1040 approaches that were adopted. For servers, implementing generic 1041 support for the scheme was complex. Implementation of priorities was 1042 uneven in both clients and servers. Many server deployments ignored 1043 client signals when prioritizing their handling of requests. 1045 In short, the prioritization signaling in RFC7540 [RFC7540] was not 1046 successful. 1048 5.3.2. Priority Signaling in this Document 1050 This update to HTTP/2 deprecates the priority signaling defined in 1051 RFC 7540 [RFC7540]. The bulk of the text related to priority signals 1052 is not included in this document. The description of frame fields 1053 and some of the mandatory handling is retained to ensure that 1054 implementations of this document remain interoperable with 1055 implementations that use the priority signaling described in RFC 1056 7540. 1058 A thorough description of the RFC 7540 priority scheme remains in 1059 Section 5.3 of [RFC7540]. 1061 Signaling priority information is necessary to attain good 1062 performance in many cases. Where signaling priority information is 1063 important, endpoints are encouraged to use an alternative scheme, 1064 such as [I-D.ietf-httpbis-priority]. 1066 Though the priority signaling from RFC 7540 was not widely adopted, 1067 the information it provides can still be useful in the absence of 1068 better information. Endpoints that receive priority signals in 1069 HEADERS or PRIORITY frames can benefit from applying that 1070 information. In particular, implementations that consume these 1071 signals would not benefit from discarding these priority signals in 1072 the absence of alternatives. 1074 Servers SHOULD use other contextual information in determining 1075 priority of requests in the absence of any priority signals. Servers 1076 MAY interpret the complete absence of signals as an indication that 1077 the client has not implemented the feature. The defaults described 1078 in Section 5.3.5 of [RFC7540] are known to have poor performance 1079 under most conditions and their use is unlikely to be deliberate. 1081 5.4. Error Handling 1083 HTTP/2 framing permits two classes of error: 1085 * An error condition that renders the entire connection unusable is 1086 a connection error. 1088 * An error in an individual stream is a stream error. 1090 A list of error codes is included in Section 7. 1092 It is possible that an endpoint will encounter frames that would 1093 cause multiple errors. Implementations MAY discover multiple errors 1094 during processing, but they SHOULD report at most one stream and one 1095 connection error as a result. 1097 The first stream error reported for a given stream prevents any other 1098 errors on that stream from being reported. In comparison, the 1099 protocol permits multiple GOAWAY frames, though an endpoint SHOULD 1100 report just one type of connection error unless an error is 1101 encountered during graceful shutdown. If this occurs, an endpoint 1102 MAY send an additional GOAWAY frame with the new error code, in 1103 addition to any prior GOAWAY that contained NO_ERROR. 1105 If an endpoint detects multiple different errors, it MAY choose to 1106 report any one of those errors. If a frame causes a connection 1107 error, that error MUST be reported. Additionally, an endpoint MAY 1108 use any applicable error code when it detects an error condition; a 1109 generic error code (such as PROTOCOL_ERROR or INTERNAL_ERROR) can 1110 always be used in place of more specific error codes. 1112 5.4.1. Connection Error Handling 1114 A connection error is any error that prevents further processing of 1115 the frame layer or corrupts any connection state. 1117 An endpoint that encounters a connection error SHOULD first send a 1118 GOAWAY frame (Section 6.8) with the stream identifier of the last 1119 stream that it successfully received from its peer. The GOAWAY frame 1120 includes an error code that indicates why the connection is 1121 terminating. After sending the GOAWAY frame for an error condition, 1122 the endpoint MUST close the TCP connection. 1124 It is possible that the GOAWAY will not be reliably received by the 1125 receiving endpoint. In the event of a connection error, GOAWAY only 1126 provides a best-effort attempt to communicate with the peer about why 1127 the connection is being terminated. 1129 An endpoint can end a connection at any time. In particular, an 1130 endpoint MAY choose to treat a stream error as a connection error. 1131 Endpoints SHOULD send a GOAWAY frame when ending a connection, 1132 providing that circumstances permit it. 1134 5.4.2. Stream Error Handling 1136 A stream error is an error related to a specific stream that does not 1137 affect processing of other streams. 1139 An endpoint that detects a stream error sends a RST_STREAM frame 1140 (Section 6.4) that contains the stream identifier of the stream where 1141 the error occurred. The RST_STREAM frame includes an error code that 1142 indicates the type of error. 1144 A RST_STREAM is the last frame that an endpoint can send on a stream. 1145 The peer that sends the RST_STREAM frame MUST be prepared to receive 1146 any frames that were sent or enqueued for sending by the remote peer. 1147 These frames can be ignored, except where they modify connection 1148 state (such as the state maintained for field section compression 1149 (Section 4.3) or flow control). 1151 Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame 1152 for any stream. However, an endpoint MAY send additional RST_STREAM 1153 frames if it receives frames on a closed stream after more than a 1154 round-trip time. This behavior is permitted to deal with misbehaving 1155 implementations. 1157 To avoid looping, an endpoint MUST NOT send a RST_STREAM in response 1158 to a RST_STREAM frame. 1160 5.4.3. Connection Termination 1162 If the TCP connection is closed or reset while streams remain in 1163 "open" or "half-closed" state, then the affected streams cannot be 1164 automatically retried (see Section 8.7 for details). 1166 5.5. Extending HTTP/2 1168 HTTP/2 permits extension of the protocol. Within the limitations 1169 described in this section, protocol extensions can be used to provide 1170 additional services or alter any aspect of the protocol. Extensions 1171 are effective only within the scope of a single HTTP/2 connection. 1173 This applies to the protocol elements defined in this document. This 1174 does not affect the existing options for extending HTTP, such as 1175 defining new methods, status codes, or fields (see Section 16 of 1176 [HTTP]). 1178 Extensions are permitted to use new frame types (Section 4.1), new 1179 settings (Section 6.5.2), or new error codes (Section 7). Registries 1180 are established for managing these extension points: frame types 1181 (Section 11.2), settings (Section 11.3), and error codes 1182 (Section 11.4). 1184 Implementations MUST ignore unknown or unsupported values in all 1185 extensible protocol elements. Implementations MUST discard frames 1186 that have unknown or unsupported types. This means that any of these 1187 extension points can be safely used by extensions without prior 1188 arrangement or negotiation. However, extension frames that appear in 1189 the middle of a field block (Section 4.3) are not permitted; these 1190 MUST be treated as a connection error (Section 5.4.1) of type 1191 PROTOCOL_ERROR. 1193 Extensions SHOULD avoiding changing protocol elements defined in this 1194 document or elements for which no extension mechanism is defined. 1195 This includes changes to the layout of frames, additions or changes 1196 to the way that frames are composed into HTTP messages (Section 8.1), 1197 the definition of pseudo-header fields, or changes to any protocol 1198 element that a compliant endpoint might treat as a connection error 1199 (Section 5.4.1). 1201 An extension that changes existing elements MUST be negotiated before 1202 being used. For example, an extension that changes the layout of the 1203 HEADERS frame cannot be used until the peer has given a positive 1204 signal that this is acceptable. In this case, it could also be 1205 necessary to coordinate when the revised layout comes into effect. 1206 For example, treating frames other than DATA frames as flow 1207 controlled requires a change in semantics that both endpoints need to 1208 understand, so this can only be done through negotiation. 1210 This document doesn't mandate a specific method for negotiating the 1211 use of an extension but notes that a setting (Section 6.5.2) could be 1212 used for that purpose. If both peers set a value that indicates 1213 willingness to use the extension, then the extension can be used. If 1214 a setting is used for extension negotiation, the initial value MUST 1215 be defined in such a fashion that the extension is initially 1216 disabled. 1218 6. Frame Definitions 1220 This specification defines a number of frame types, each identified 1221 by a unique 8-bit type code. Each frame type serves a distinct 1222 purpose in the establishment and management either of the connection 1223 as a whole or of individual streams. 1225 The transmission of specific frame types can alter the state of a 1226 connection. If endpoints fail to maintain a synchronized view of the 1227 connection state, successful communication within the connection will 1228 no longer be possible. Therefore, it is important that endpoints 1229 have a shared comprehension of how the state is affected by the use 1230 any given frame. 1232 6.1. DATA 1234 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 1235 octets associated with a stream. One or more DATA frames are used, 1236 for instance, to carry HTTP request or response message contents. 1238 DATA frames MAY also contain padding. Padding can be added to DATA 1239 frames to obscure the size of messages. Padding is a security 1240 feature; see Section 10.7. 1242 DATA Frame { 1243 Length (24), 1244 Type (8) = 0, 1245 Unused Flags (4), 1246 PADDED Flag (1), 1247 Unused Flags (2), 1248 END_STREAM Flag (1), 1249 Reserved (1), 1250 Stream Identifier (31), 1251 [Pad Length (8)], 1252 Data (..), 1253 Padding (..), 1254 } 1256 Figure 3: DATA Frame Format 1258 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1259 fields are described in Section 4. The DATA frame contains the 1260 following additional fields: 1262 Pad Length: An 8-bit field containing the length of the frame 1263 padding in units of octets. This field is conditional (as 1264 signified by a "?" in the diagram) and is only present if the 1265 PADDED flag is set. 1267 Data: Application data. The amount of data is the remainder of the 1268 frame payload after subtracting the length of the other fields 1269 that are present. 1271 Padding: Padding octets that contain no application semantic value. 1273 Padding octets MUST be set to zero when sending. A receiver is 1274 not obligated to verify padding but MAY treat non-zero padding as 1275 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1277 The DATA frame defines the following flags: 1279 PADDED (0x8): When set, the PADDED Flag indicates that the Pad 1280 Length field and any padding that it describes are present. 1282 END_STREAM (0x1): When set, the END_STREAM Flag indicates that this 1283 frame is the last that the endpoint will send for the identified 1284 stream. Setting this flag causes the stream to enter one of the 1285 "half-closed" states or the "closed" state (Section 5.1). 1287 DATA frames MUST be associated with a stream. If a DATA frame is 1288 received whose stream identifier field is 0x0, the recipient MUST 1289 respond with a connection error (Section 5.4.1) of type 1290 PROTOCOL_ERROR. 1292 DATA frames are subject to flow control and can only be sent when a 1293 stream is in the "open" or "half-closed (remote)" state. The entire 1294 DATA frame payload is included in flow control, including the Pad 1295 Length and Padding fields if present. If a DATA frame is received 1296 whose stream is not in "open" or "half-closed (local)" state, the 1297 recipient MUST respond with a stream error (Section 5.4.2) of type 1298 STREAM_CLOSED. 1300 The total number of padding octets is determined by the value of the 1301 Pad Length field. If the length of the padding is the length of the 1302 frame payload or greater, the recipient MUST treat this as a 1303 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1305 | Note: A frame can be increased in size by one octet by 1306 | including a Pad Length field with a value of zero. 1308 6.2. HEADERS 1310 The HEADERS frame (type=0x1) is used to open a stream (Section 5.1), 1311 and additionally carries a field block fragment. Despite the name, a 1312 HEADERS frame can carry a header section or a trailer section. 1313 HEADERS frames can be sent on a stream in the "idle", "reserved 1314 (local)", "open", or "half-closed (remote)" state. 1316 HEADERS Frame { 1317 Length (24), 1318 Type (8) = 1, 1319 Unused Flags (2), 1320 PRIORITY Flag (1), 1321 Unused Flag (1), 1322 PADDED Flag (1), 1323 END_HEADERS Flag (1), 1324 Unused Flag (1), 1325 END_STREAM Flag (1), 1326 Reserved (1), 1327 Stream Identifier (31), 1328 [Pad Length (8)], 1329 [Exclusive (1)], 1330 [Stream Dependency (31)], 1331 [Weight (8)], 1332 Field Block Fragment (..), 1333 Padding (..), 1334 } 1336 Figure 4: HEADERS Frame Format 1338 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1339 fields are described in Section 4. The HEADERS frame payload has the 1340 following additional fields: 1342 Pad Length: An 8-bit field containing the length of the frame 1343 padding in units of octets. This field is only present if the 1344 PADDED flag is set. 1346 Exclusive: A single-bit flag. This field is only present if the 1347 PRIORITY flag is set. 1349 Stream Dependency: A 31-bit stream identifier. This field is only 1350 present if the PRIORITY flag is set. 1352 Weight: An unsigned 8-bit integer. This field is only present if 1353 the PRIORITY flag is set. 1355 Field Block Fragment: A field block fragment (Section 4.3). 1357 Padding: Padding octets. 1359 The HEADERS frame defines the following flags: 1361 PRIORITY (0x20): When set, the PRIORITY Flag indicates that the 1362 Exclusive, Stream Dependency, and Weight fields are present. 1364 PADDED (0x8): When set, the PADDED Flag indicates that the Pad 1365 Length field and any padding that it describes are present. 1367 END_HEADERS (0x4): When set, the END_HEADERS Flag indicates that 1368 this frame contains an entire field block (Section 4.3) and is not 1369 followed by any CONTINUATION frames. 1371 A HEADERS frame without the END_HEADERS flag set MUST be followed 1372 by a CONTINUATION frame for the same stream. A receiver MUST 1373 treat the receipt of any other type of frame or a frame on a 1374 different stream as a connection error (Section 5.4.1) of type 1375 PROTOCOL_ERROR. 1377 END_STREAM (0x1): When set, the END_STREAM Flag indicates that the 1378 field block (Section 4.3) is the last that the endpoint will send 1379 for the identified stream. 1381 A HEADERS frame carries the END_STREAM flag that signals the end 1382 of a stream. However, a HEADERS frame with the END_STREAM flag 1383 set can be followed by CONTINUATION frames on the same stream. 1384 Logically, the CONTINUATION frames are part of the HEADERS frame. 1386 The frame payload of a HEADERS frame contains a field block fragment 1387 (Section 4.3). A field block that does not fit within a HEADERS 1388 frame is continued in a CONTINUATION frame (Section 6.10). 1390 HEADERS frames MUST be associated with a stream. If a HEADERS frame 1391 is received whose stream identifier field is 0x0, the recipient MUST 1392 respond with a connection error (Section 5.4.1) of type 1393 PROTOCOL_ERROR. 1395 The HEADERS frame changes the connection state as described in 1396 Section 4.3. 1398 The HEADERS frame can include padding. Padding fields and flags are 1399 identical to those defined for DATA frames (Section 6.1). Padding 1400 that exceeds the size remaining for the field block fragment MUST be 1401 treated as a PROTOCOL_ERROR. 1403 6.3. PRIORITY 1405 The PRIORITY frame (type=0x2) is deprecated; see Section 5.3.2. A 1406 PRIORITY frame can be sent in any stream state, including idle or 1407 closed streams. 1409 PRIORITY Frame { 1410 Length (24), 1411 Type (8) = 2, 1412 Unused Flags (8), 1413 Reserved (1), 1414 Stream Identifier (31), 1415 Exclusive (1), 1416 Stream Dependency (31), 1417 Weight (8), 1418 } 1420 Figure 5: PRIORITY Frame Format 1422 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1423 fields are described in Section 4. The frame payload of a PRIORITY 1424 frame contains the following additional fields: 1426 Exclusive: A single-bit flag. 1428 Stream Dependency: A 31-bit stream identifier. 1430 Weight: An unsigned 8-bit integer. 1432 The PRIORITY frame does not define any flags. 1434 The PRIORITY frame always identifies a stream. If a PRIORITY frame 1435 is received with a stream identifier of 0x0, the recipient MUST 1436 respond with a connection error (Section 5.4.1) of type 1437 PROTOCOL_ERROR. 1439 Sending or receiving a PRIORITY frame does not affect the state of 1440 any stream (Section 5.1). The PRIORITY frame can be sent on a stream 1441 in any state, including "idle" or "closed". A PRIORITY frame cannot 1442 be sent between consecutive frames that comprise a single field block 1443 (Section 4.3). 1445 A PRIORITY frame with a length other than 5 octets MUST be treated as 1446 a stream error (Section 5.4.2) of type FRAME_SIZE_ERROR. 1448 6.4. RST_STREAM 1450 The RST_STREAM frame (type=0x3) allows for immediate termination of a 1451 stream. RST_STREAM is sent to request cancellation of a stream or to 1452 indicate that an error condition has occurred. 1454 RST_STREAM Frame { 1455 Length (24), 1456 Type (8) = 3, 1457 Unused Flags (8), 1458 Reserved (1), 1459 Stream Identifier (31), 1460 Error Code (32), 1461 } 1463 Figure 6: RST_STREAM Frame Format 1465 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1466 fields are described in Section 4. Additionally, the RST_STREAM 1467 frame contains a single unsigned, 32-bit integer identifying the 1468 error code (Section 7). The error code indicates why the stream is 1469 being terminated. 1471 The RST_STREAM frame does not define any flags. 1473 The RST_STREAM frame fully terminates the referenced stream and 1474 causes it to enter the "closed" state. After receiving a RST_STREAM 1475 on a stream, the receiver MUST NOT send additional frames for that 1476 stream, with the exception of PRIORITY. However, after sending the 1477 RST_STREAM, the sending endpoint MUST be prepared to receive and 1478 process additional frames sent on the stream that might have been 1479 sent by the peer prior to the arrival of the RST_STREAM. 1481 RST_STREAM frames MUST be associated with a stream. If a RST_STREAM 1482 frame is received with a stream identifier of 0x0, the recipient MUST 1483 treat this as a connection error (Section 5.4.1) of type 1484 PROTOCOL_ERROR. 1486 RST_STREAM frames MUST NOT be sent for a stream in the "idle" state. 1487 If a RST_STREAM frame identifying an idle stream is received, the 1488 recipient MUST treat this as a connection error (Section 5.4.1) of 1489 type PROTOCOL_ERROR. 1491 A RST_STREAM frame with a length other than 4 octets MUST be treated 1492 as a connection error (Section 5.4.1) of type FRAME_SIZE_ERROR. 1494 6.5. SETTINGS 1496 The SETTINGS frame (type=0x4) conveys configuration parameters that 1497 affect how endpoints communicate, such as preferences and constraints 1498 on peer behavior. The SETTINGS frame is also used to acknowledge the 1499 receipt of those settings. Individually, a configuration parameter 1500 from a SETTINGS frame is referred to as a "setting". 1502 Settings are not negotiated; they describe characteristics of the 1503 sending peer, which are used by the receiving peer. Different values 1504 for the same setting can be advertised by each peer. For example, a 1505 client might set a high initial flow-control window, whereas a server 1506 might set a lower value to conserve resources. 1508 A SETTINGS frame MUST be sent by both endpoints at the start of a 1509 connection and MAY be sent at any other time by either endpoint over 1510 the lifetime of the connection. Implementations MUST support all of 1511 the settings defined by this specification. 1513 Each parameter in a SETTINGS frame replaces any existing value for 1514 that parameter. Settings are processed in the order in which they 1515 appear, and a receiver of a SETTINGS frame does not need to maintain 1516 any state other than the current value of each setting. Therefore, 1517 the value of a SETTINGS parameter is the last value that is seen by a 1518 receiver. 1520 SETTINGS frames are acknowledged by the receiving peer. To enable 1521 this, the SETTINGS frame defines the ACK flag: 1523 ACK (0x1): When set, the ACK Flag indicates that this frame 1524 acknowledges receipt and application of the peer's SETTINGS frame. 1525 When this bit is set, the frame payload of the SETTINGS frame MUST 1526 be empty. Receipt of a SETTINGS frame with the ACK flag set and a 1527 length field value other than 0 MUST be treated as a connection 1528 error (Section 5.4.1) of type FRAME_SIZE_ERROR. For more 1529 information, see Section 6.5.3 ("Settings Synchronization"). 1531 SETTINGS frames always apply to a connection, never a single stream. 1532 The stream identifier for a SETTINGS frame MUST be zero (0x0). If an 1533 endpoint receives a SETTINGS frame whose stream identifier field is 1534 anything other than 0x0, the endpoint MUST respond with a connection 1535 error (Section 5.4.1) of type PROTOCOL_ERROR. 1537 The SETTINGS frame affects connection state. A badly formed or 1538 incomplete SETTINGS frame MUST be treated as a connection error 1539 (Section 5.4.1) of type PROTOCOL_ERROR. 1541 A SETTINGS frame with a length other than a multiple of 6 octets MUST 1542 be treated as a connection error (Section 5.4.1) of type 1543 FRAME_SIZE_ERROR. 1545 6.5.1. SETTINGS Format 1547 The frame payload of a SETTINGS frame consists of zero or more 1548 settings, each consisting of an unsigned 16-bit setting identifier 1549 and an unsigned 32-bit value. 1551 SETTINGS Frame { 1552 Length (24), 1553 Type (8) = 4, 1554 Unused Flags (7), 1555 ACK Flag (1), 1556 Reserved (1), 1557 Stream Identifier (31), 1558 Setting (..) ..., 1559 } 1561 Setting { 1562 Identifier (16), 1563 Value (32), 1564 } 1566 Figure 7: SETTINGS Frame Format 1568 6.5.2. Defined Settings 1570 The following settings are defined: 1572 SETTINGS_HEADER_TABLE_SIZE (0x1): Allows the sender to inform the 1573 remote endpoint of the maximum size of the compression table used 1574 to decode field blocks, in octets. The encoder can select any 1575 size equal to or less than this value by using signaling specific 1576 to the compression format inside a field block (see 1577 [COMPRESSION]). The initial value is 4,096 octets. 1579 SETTINGS_ENABLE_PUSH (0x2): This setting can be used to disable 1580 server push (Section 8.4). A server MUST NOT send a PUSH_PROMISE 1581 frame if it receives this parameter set to a value of 0. A client 1582 that has both set this parameter to 0 and had it acknowledged MUST 1583 treat the receipt of a PUSH_PROMISE frame as a connection error 1584 (Section 5.4.1) of type PROTOCOL_ERROR. 1586 The initial value of SETTINGS_ENABLE_PUSH is 1, which indicates 1587 that server push is permitted. Any value other than 0 or 1 MUST 1588 be treated as a connection error (Section 5.4.1) of type 1589 PROTOCOL_ERROR. 1591 A server MUST NOT explicitly set this value to 1. A server MAY 1592 choose to omit this setting when it sends a SETTINGS frame, but if 1593 a server does include a value it MUST be 0. A client MUST treat 1594 receipt of a SETTINGS frame with SETTINGS_ENABLE_PUSH set to 1 as 1595 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1597 SETTINGS_MAX_CONCURRENT_STREAMS (0x3): Indicates the maximum number 1598 of concurrent streams that the sender will allow. This limit is 1599 directional: it applies to the number of streams that the sender 1600 permits the receiver to create. Initially, there is no limit to 1601 this value. It is recommended that this value be no smaller than 1602 100, so as to not unnecessarily limit parallelism. 1604 A value of 0 for SETTINGS_MAX_CONCURRENT_STREAMS SHOULD NOT be 1605 treated as special by endpoints. A zero value does prevent the 1606 creation of new streams; however, this can also happen for any 1607 limit that is exhausted with active streams. Servers SHOULD only 1608 set a zero value for short durations; if a server does not wish to 1609 accept requests, closing the connection is more appropriate. 1611 SETTINGS_INITIAL_WINDOW_SIZE (0x4): Indicates the sender's initial 1612 window size (in octets) for stream-level flow control. The 1613 initial value is 2^16-1 (65,535) octets. 1615 This setting affects the window size of all streams (see 1616 Section 6.9.2). 1618 Values above the maximum flow-control window size of 2^31-1 MUST 1619 be treated as a connection error (Section 5.4.1) of type 1620 FLOW_CONTROL_ERROR. 1622 SETTINGS_MAX_FRAME_SIZE (0x5): Indicates the size of the largest 1623 frame payload that the sender is willing to receive, in octets. 1625 The initial value is 2^14 (16,384) octets. The value advertised 1626 by an endpoint MUST be between this initial value and the maximum 1627 allowed frame size (2^24-1 or 16,777,215 octets), inclusive. 1628 Values outside this range MUST be treated as a connection error 1629 (Section 5.4.1) of type PROTOCOL_ERROR. 1631 SETTINGS_MAX_HEADER_LIST_SIZE (0x6): This advisory setting informs a 1632 peer of the maximum size of field section that the sender is 1633 prepared to accept, in octets. The value is based on the 1634 uncompressed size of field lines, including the length of the name 1635 and value in octets plus an overhead of 32 octets for each field 1636 line. 1638 For any given request, a lower limit than what is advertised MAY 1639 be enforced. The initial value of this setting is unlimited. 1641 An endpoint that receives a SETTINGS frame with any unknown or 1642 unsupported identifier MUST ignore that setting. 1644 6.5.3. Settings Synchronization 1646 Most values in SETTINGS benefit from or require an understanding of 1647 when the peer has received and applied the changed parameter values. 1648 In order to provide such synchronization timepoints, the recipient of 1649 a SETTINGS frame in which the ACK flag is not set MUST apply the 1650 updated settings as soon as possible upon receipt. 1652 The values in the SETTINGS frame MUST be processed in the order they 1653 appear, with no other frame processing between values. Unsupported 1654 settings MUST be ignored. Once all values have been processed, the 1655 recipient MUST immediately emit a SETTINGS frame with the ACK flag 1656 set. Upon receiving a SETTINGS frame with the ACK flag set, the 1657 sender of the altered settings can rely on the value having been 1658 applied. 1660 If the sender of a SETTINGS frame does not receive an acknowledgement 1661 within a reasonable amount of time, it MAY issue a connection error 1662 (Section 5.4.1) of type SETTINGS_TIMEOUT. 1664 6.6. PUSH_PROMISE 1666 The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint 1667 in advance of streams the sender intends to initiate. The 1668 PUSH_PROMISE frame includes the unsigned 31-bit identifier of the 1669 stream the endpoint plans to create along with a field section that 1670 provides additional context for the stream. Section 8.4 contains a 1671 thorough description of the use of PUSH_PROMISE frames. 1673 PUSH_PROMISE Frame { 1674 Length (24), 1675 Type (8) = 5, 1676 Unused Flags (4), 1677 PADDED Flag (1), 1678 END_HEADERS Flag (1), 1679 Unused Flags (2), 1680 Reserved (1), 1681 Stream Identifier (31), 1682 [Pad Length (8)], 1683 Reserved (1), 1684 Promised Stream ID (31), 1685 Field Block Fragment (..), 1686 Padding (..), 1687 } 1689 Figure 8: PUSH_PROMISE Frame Format 1691 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1692 fields are described in Section 4. The PUSH_PROMISE frame payload 1693 has the following additional fields: 1695 Pad Length: An 8-bit field containing the length of the frame 1696 padding in units of octets. This field is only present if the 1697 PADDED flag is set. 1699 R: A single reserved bit. 1701 Promised Stream ID: An unsigned 31-bit integer that identifies the 1702 stream that is reserved by the PUSH_PROMISE. The promised stream 1703 identifier MUST be a valid choice for the next stream sent by the 1704 sender (see "new stream identifier" in Section 5.1.1). 1706 Field Block Fragment: A field block fragment (Section 4.3) 1707 containing request control data and header section. 1709 Padding: Padding octets. 1711 The PUSH_PROMISE frame defines the following flags: 1713 PADDED (0x8): When set, the PADDED Flag indicates that the Pad 1714 Length field and any padding that it describes are present. 1716 END_HEADERS (0x4): When set, the END_HEADERS Flag indicates that 1717 this frame contains an entire field block (Section 4.3) and is not 1718 followed by any CONTINUATION frames. 1720 A PUSH_PROMISE frame without the END_HEADERS flag set MUST be 1721 followed by a CONTINUATION frame for the same stream. A receiver 1722 MUST treat the receipt of any other type of frame or a frame on a 1723 different stream as a connection error (Section 5.4.1) of type 1724 PROTOCOL_ERROR. 1726 PUSH_PROMISE frames MUST only be sent on a peer-initiated stream that 1727 is in either the "open" or "half-closed (remote)" state. The stream 1728 identifier of a PUSH_PROMISE frame indicates the stream it is 1729 associated with. If the stream identifier field specifies the value 1730 0x0, a recipient MUST respond with a connection error (Section 5.4.1) 1731 of type PROTOCOL_ERROR. 1733 Promised streams are not required to be used in the order they are 1734 promised. The PUSH_PROMISE only reserves stream identifiers for 1735 later use. 1737 PUSH_PROMISE MUST NOT be sent if the SETTINGS_ENABLE_PUSH setting of 1738 the peer endpoint is set to 0. An endpoint that has set this setting 1739 and has received acknowledgement MUST treat the receipt of a 1740 PUSH_PROMISE frame as a connection error (Section 5.4.1) of type 1741 PROTOCOL_ERROR. 1743 Recipients of PUSH_PROMISE frames can choose to reject promised 1744 streams by returning a RST_STREAM referencing the promised stream 1745 identifier back to the sender of the PUSH_PROMISE. 1747 A PUSH_PROMISE frame modifies the connection state in two ways. 1748 First, the inclusion of a field block (Section 4.3) potentially 1749 modifies the state maintained for field section compression. Second, 1750 PUSH_PROMISE also reserves a stream for later use, causing the 1751 promised stream to enter the "reserved" state. A sender MUST NOT 1752 send a PUSH_PROMISE on a stream unless that stream is either "open" 1753 or "half-closed (remote)"; the sender MUST ensure that the promised 1754 stream is a valid choice for a new stream identifier (Section 5.1.1) 1755 (that is, the promised stream MUST be in the "idle" state). 1757 Since PUSH_PROMISE reserves a stream, ignoring a PUSH_PROMISE frame 1758 causes the stream state to become indeterminate. A receiver MUST 1759 treat the receipt of a PUSH_PROMISE on a stream that is neither 1760 "open" nor "half-closed (local)" as a connection error 1761 (Section 5.4.1) of type PROTOCOL_ERROR. However, an endpoint that 1762 has sent RST_STREAM on the associated stream MUST handle PUSH_PROMISE 1763 frames that might have been created before the RST_STREAM frame is 1764 received and processed. 1766 A receiver MUST treat the receipt of a PUSH_PROMISE that promises an 1767 illegal stream identifier (Section 5.1.1) as a connection error 1768 (Section 5.4.1) of type PROTOCOL_ERROR. Note that an illegal stream 1769 identifier is an identifier for a stream that is not currently in the 1770 "idle" state. 1772 The PUSH_PROMISE frame can include padding. Padding fields and flags 1773 are identical to those defined for DATA frames (Section 6.1). 1775 6.7. PING 1777 The PING frame (type=0x6) is a mechanism for measuring a minimal 1778 round-trip time from the sender, as well as determining whether an 1779 idle connection is still functional. PING frames can be sent from 1780 any endpoint. 1782 PING Frame { 1783 Length (24), 1784 Type (8) = 6, 1785 Unused Flags (7), 1786 ACK Flag (1), 1787 Reserved (1), 1788 Stream Identifier (31), 1789 Opaque Data (64), 1790 } 1792 Figure 9: PING Frame Format 1794 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1795 fields are described in Section 4. 1797 In addition to the frame header, PING frames MUST contain 8 octets of 1798 opaque data in the frame payload. A sender can include any value it 1799 chooses and use those octets in any fashion. 1801 Receivers of a PING frame that does not include an ACK flag MUST send 1802 a PING frame with the ACK flag set in response, with an identical 1803 frame payload. PING responses SHOULD be given higher priority than 1804 any other frame. 1806 The PING frame defines the following flags: 1808 ACK (0x1): When set, the ACK Flag indicates that this PING frame is 1809 a PING response. An endpoint MUST set this flag in PING 1810 responses. An endpoint MUST NOT respond to PING frames containing 1811 this flag. 1813 PING frames are not associated with any individual stream. If a PING 1814 frame is received with a stream identifier field value other than 1815 0x0, the recipient MUST respond with a connection error 1816 (Section 5.4.1) of type PROTOCOL_ERROR. 1818 Receipt of a PING frame with a length field value other than 8 MUST 1819 be treated as a connection error (Section 5.4.1) of type 1820 FRAME_SIZE_ERROR. 1822 6.8. GOAWAY 1824 The GOAWAY frame (type=0x7) is used to initiate shutdown of a 1825 connection or to signal serious error conditions. GOAWAY allows an 1826 endpoint to gracefully stop accepting new streams while still 1827 finishing processing of previously established streams. This enables 1828 administrative actions, like server maintenance. 1830 There is an inherent race condition between an endpoint starting new 1831 streams and the remote sending a GOAWAY frame. To deal with this 1832 case, the GOAWAY contains the stream identifier of the last peer- 1833 initiated stream that was or might be processed on the sending 1834 endpoint in this connection. For instance, if the server sends a 1835 GOAWAY frame, the identified stream is the highest-numbered stream 1836 initiated by the client. 1838 Once sent, the sender will ignore frames sent on streams initiated by 1839 the receiver if the stream has an identifier higher than the included 1840 last stream identifier. Receivers of a GOAWAY frame MUST NOT open 1841 additional streams on the connection, although a new connection can 1842 be established for new streams. 1844 If the receiver of the GOAWAY has sent data on streams with a higher 1845 stream identifier than what is indicated in the GOAWAY frame, those 1846 streams are not or will not be processed. The receiver of the GOAWAY 1847 frame can treat the streams as though they had never been created at 1848 all, thereby allowing those streams to be retried later on a new 1849 connection. 1851 Endpoints SHOULD always send a GOAWAY frame before closing a 1852 connection so that the remote peer can know whether a stream has been 1853 partially processed or not. For example, if an HTTP client sends a 1854 POST at the same time that a server closes a connection, the client 1855 cannot know if the server started to process that POST request if the 1856 server does not send a GOAWAY frame to indicate what streams it might 1857 have acted on. 1859 An endpoint might choose to close a connection without sending a 1860 GOAWAY for misbehaving peers. 1862 A GOAWAY frame might not immediately precede closing of the 1863 connection; a receiver of a GOAWAY that has no more use for the 1864 connection SHOULD still send a GOAWAY frame before terminating the 1865 connection. 1867 GOAWAY Frame { 1868 Length (24), 1869 Type (8) = 7, 1870 Unused Flags (8), 1871 Reserved (1), 1872 Stream Identifier (31), 1873 Reserved (1), 1874 Last-Stream-ID (31), 1875 Error Code (32), 1876 Additional Debug Data (..), 1877 } 1878 Figure 10: GOAWAY Frame Format 1880 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1881 fields are described in Section 4. 1883 The GOAWAY frame does not define any flags. 1885 The GOAWAY frame applies to the connection, not a specific stream. 1886 An endpoint MUST treat a GOAWAY frame with a stream identifier other 1887 than 0x0 as a connection error (Section 5.4.1) of type 1888 PROTOCOL_ERROR. 1890 The last stream identifier in the GOAWAY frame contains the highest- 1891 numbered stream identifier for which the sender of the GOAWAY frame 1892 might have taken some action on or might yet take action on. All 1893 streams up to and including the identified stream might have been 1894 processed in some way. The last stream identifier can be set to 0 if 1895 no streams were processed. 1897 | Note: In this context, "processed" means that some data from 1898 | the stream was passed to some higher layer of software that 1899 | might have taken some action as a result. 1901 If a connection terminates without a GOAWAY frame, the last stream 1902 identifier is effectively the highest possible stream identifier. 1904 On streams with lower- or equal-numbered identifiers that were not 1905 closed completely prior to the connection being closed, reattempting 1906 requests, transactions, or any protocol activity is not possible, 1907 with the exception of idempotent actions like HTTP GET, PUT, or 1908 DELETE. Any protocol activity that uses higher-numbered streams can 1909 be safely retried using a new connection. 1911 Activity on streams numbered lower or equal to the last stream 1912 identifier might still complete successfully. The sender of a GOAWAY 1913 frame might gracefully shut down a connection by sending a GOAWAY 1914 frame, maintaining the connection in an "open" state until all in- 1915 progress streams complete. 1917 An endpoint MAY send multiple GOAWAY frames if circumstances change. 1918 For instance, an endpoint that sends GOAWAY with NO_ERROR during 1919 graceful shutdown could subsequently encounter a condition that 1920 requires immediate termination of the connection. The last stream 1921 identifier from the last GOAWAY frame received indicates which 1922 streams could have been acted upon. Endpoints MUST NOT increase the 1923 value they send in the last stream identifier, since the peers might 1924 already have retried unprocessed requests on another connection. 1926 A client that is unable to retry requests loses all requests that are 1927 in flight when the server closes the connection. This is especially 1928 true for intermediaries that might not be serving clients using 1929 HTTP/2. A server that is attempting to gracefully shut down a 1930 connection SHOULD send an initial GOAWAY frame with the last stream 1931 identifier set to 2^31-1 and a NO_ERROR code. This signals to the 1932 client that a shutdown is imminent and that initiating further 1933 requests is prohibited. After allowing time for any in-flight stream 1934 creation (at least one round-trip time), the server can send another 1935 GOAWAY frame with an updated last stream identifier. This ensures 1936 that a connection can be cleanly shut down without losing requests. 1938 After sending a GOAWAY frame, the sender can discard frames for 1939 streams initiated by the receiver with identifiers higher than the 1940 identified last stream. However, any frames that alter connection 1941 state cannot be completely ignored. For instance, HEADERS, 1942 PUSH_PROMISE, and CONTINUATION frames MUST be minimally processed to 1943 ensure the state maintained for field section compression is 1944 consistent (see Section 4.3); similarly, DATA frames MUST be counted 1945 toward the connection flow-control window. Failure to process these 1946 frames can cause flow control or field section compression state to 1947 become unsynchronized. 1949 The GOAWAY frame also contains a 32-bit error code (Section 7) that 1950 contains the reason for closing the connection. 1952 Endpoints MAY append opaque data to the frame payload of any GOAWAY 1953 frame. Additional debug data is intended for diagnostic purposes 1954 only and carries no semantic value. Debug information could contain 1955 security- or privacy-sensitive data. Logged or otherwise 1956 persistently stored debug data MUST have adequate safeguards to 1957 prevent unauthorized access. 1959 6.9. WINDOW_UPDATE 1961 The WINDOW_UPDATE frame (type=0x8) is used to implement flow control; 1962 see Section 5.2 for an overview. 1964 Flow control operates at two levels: on each individual stream and on 1965 the entire connection. 1967 Both types of flow control are hop by hop, that is, only between the 1968 two endpoints. Intermediaries do not forward WINDOW_UPDATE frames 1969 between dependent connections. However, throttling of data transfer 1970 by any receiver can indirectly cause the propagation of flow-control 1971 information toward the original sender. 1973 Flow control only applies to frames that are identified as being 1974 subject to flow control. Of the frame types defined in this 1975 document, this includes only DATA frames. Frames that are exempt 1976 from flow control MUST be accepted and processed, unless the receiver 1977 is unable to assign resources to handling the frame. A receiver MAY 1978 respond with a stream error (Section 5.4.2) or connection error 1979 (Section 5.4.1) of type FLOW_CONTROL_ERROR if it is unable to accept 1980 a frame. 1982 WINDOW_UPDATE Frame { 1983 Length (24), 1984 Type (8) = 8, 1985 Unused Flags (8), 1986 Reserved (1), 1987 Stream Identifier (31), 1988 Reserved (1), 1989 Window Size Increment (31), 1990 } 1992 Figure 11: WINDOW_UPDATE Frame Format 1994 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 1995 fields are described in Section 4. The frame payload of a 1996 WINDOW_UPDATE frame is one reserved bit plus an unsigned 31-bit 1997 integer indicating the number of octets that the sender can transmit 1998 in addition to the existing flow-control window. The legal range for 1999 the increment to the flow-control window is 1 to 2^31-1 2000 (2,147,483,647) octets. 2002 The WINDOW_UPDATE frame does not define any flags. 2004 The WINDOW_UPDATE frame can be specific to a stream or to the entire 2005 connection. In the former case, the frame's stream identifier 2006 indicates the affected stream; in the latter, the value "0" indicates 2007 that the entire connection is the subject of the frame. 2009 A receiver MUST treat the receipt of a WINDOW_UPDATE frame with an 2010 flow-control window increment of 0 as a stream error (Section 5.4.2) 2011 of type PROTOCOL_ERROR; errors on the connection flow-control window 2012 MUST be treated as a connection error (Section 5.4.1). 2014 WINDOW_UPDATE can be sent by a peer that has sent a frame bearing the 2015 END_STREAM flag. This means that a receiver could receive a 2016 WINDOW_UPDATE frame on a "half-closed (remote)" or "closed" stream. 2017 A receiver MUST NOT treat this as an error (see Section 5.1). 2019 A receiver that receives a flow-controlled frame MUST always account 2020 for its contribution against the connection flow-control window, 2021 unless the receiver treats this as a connection error 2022 (Section 5.4.1). This is necessary even if the frame is in error. 2023 The sender counts the frame toward the flow-control window, but if 2024 the receiver does not, the flow-control window at the sender and 2025 receiver can become different. 2027 A WINDOW_UPDATE frame with a length other than 4 octets MUST be 2028 treated as a connection error (Section 5.4.1) of type 2029 FRAME_SIZE_ERROR. 2031 6.9.1. The Flow-Control Window 2033 Flow control in HTTP/2 is implemented using a window kept by each 2034 sender on every stream. The flow-control window is a simple integer 2035 value that indicates how many octets of data the sender is permitted 2036 to transmit; as such, its size is a measure of the buffering capacity 2037 of the receiver. 2039 Two flow-control windows are applicable: the stream flow-control 2040 window and the connection flow-control window. The sender MUST NOT 2041 send a flow-controlled frame with a length that exceeds the space 2042 available in either of the flow-control windows advertised by the 2043 receiver. Frames with zero length with the END_STREAM flag set (that 2044 is, an empty DATA frame) MAY be sent if there is no available space 2045 in either flow-control window. 2047 For flow-control calculations, the 9-octet frame header is not 2048 counted. 2050 After sending a flow-controlled frame, the sender reduces the space 2051 available in both windows by the length of the transmitted frame. 2053 The receiver of a frame sends a WINDOW_UPDATE frame as it consumes 2054 data and frees up space in flow-control windows. Separate 2055 WINDOW_UPDATE frames are sent for the stream- and connection-level 2056 flow-control windows. 2058 A sender that receives a WINDOW_UPDATE frame updates the 2059 corresponding window by the amount specified in the frame. 2061 A sender MUST NOT allow a flow-control window to exceed 2^31-1 2062 octets. If a sender receives a WINDOW_UPDATE that causes a flow- 2063 control window to exceed this maximum, it MUST terminate either the 2064 stream or the connection, as appropriate. For streams, the sender 2065 sends a RST_STREAM with an error code of FLOW_CONTROL_ERROR; for the 2066 connection, a GOAWAY frame with an error code of FLOW_CONTROL_ERROR 2067 is sent. 2069 Flow-controlled frames from the sender and WINDOW_UPDATE frames from 2070 the receiver are completely asynchronous with respect to each other. 2071 This property allows a receiver to aggressively update the window 2072 size kept by the sender to prevent streams from stalling. 2074 6.9.2. Initial Flow-Control Window Size 2076 When an HTTP/2 connection is first established, new streams are 2077 created with an initial flow-control window size of 65,535 octets. 2078 The connection flow-control window is also 65,535 octets. Both 2079 endpoints can adjust the initial window size for new streams by 2080 including a value for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS 2081 frame that forms part of the connection preface. The connection 2082 flow-control window can only be changed using WINDOW_UPDATE frames. 2084 Prior to receiving a SETTINGS frame that sets a value for 2085 SETTINGS_INITIAL_WINDOW_SIZE, an endpoint can only use the default 2086 initial window size when sending flow-controlled frames. Similarly, 2087 the connection flow-control window is set to the default initial 2088 window size until a WINDOW_UPDATE frame is received. 2090 In addition to changing the flow-control window for streams that are 2091 not yet active, a SETTINGS frame can alter the initial flow-control 2092 window size for streams with active flow-control windows (that is, 2093 streams in the "open" or "half-closed (remote)" state). When the 2094 value of SETTINGS_INITIAL_WINDOW_SIZE changes, a receiver MUST adjust 2095 the size of all stream flow-control windows that it maintains by the 2096 difference between the new value and the old value. 2098 A change to SETTINGS_INITIAL_WINDOW_SIZE can cause the available 2099 space in a flow-control window to become negative. A sender MUST 2100 track the negative flow-control window and MUST NOT send new flow- 2101 controlled frames until it receives WINDOW_UPDATE frames that cause 2102 the flow-control window to become positive. 2104 For example, if the client sends 60 KB immediately on connection 2105 establishment and the server sets the initial window size to be 16 2106 KB, the client will recalculate the available flow-control window to 2107 be -44 KB on receipt of the SETTINGS frame. The client retains a 2108 negative flow-control window until WINDOW_UPDATE frames restore the 2109 window to being positive, after which the client can resume sending. 2111 A SETTINGS frame cannot alter the connection flow-control window. 2113 An endpoint MUST treat a change to SETTINGS_INITIAL_WINDOW_SIZE that 2114 causes any flow-control window to exceed the maximum size as a 2115 connection error (Section 5.4.1) of type FLOW_CONTROL_ERROR. 2117 6.9.3. Reducing the Stream Window Size 2119 A receiver that wishes to use a smaller flow-control window than the 2120 current size can send a new SETTINGS frame. However, the receiver 2121 MUST be prepared to receive data that exceeds this window size, since 2122 the sender might send data that exceeds the lower limit prior to 2123 processing the SETTINGS frame. 2125 After sending a SETTINGS frame that reduces the initial flow-control 2126 window size, a receiver MAY continue to process streams that exceed 2127 flow-control limits. Allowing streams to continue does not allow the 2128 receiver to immediately reduce the space it reserves for flow-control 2129 windows. Progress on these streams can also stall, since 2130 WINDOW_UPDATE frames are needed to allow the sender to resume 2131 sending. The receiver MAY instead send a RST_STREAM with an error 2132 code of FLOW_CONTROL_ERROR for the affected streams. 2134 6.10. CONTINUATION 2136 The CONTINUATION frame (type=0x9) is used to continue a sequence of 2137 field block fragments (Section 4.3). Any number of CONTINUATION 2138 frames can be sent, as long as the preceding frame is on the same 2139 stream and is a HEADERS, PUSH_PROMISE, or CONTINUATION frame without 2140 the END_HEADERS flag set. 2142 CONTINUATION Frame { 2143 Length (24), 2144 Type (8) = 9, 2145 Unused Flags (5), 2146 END_HEADERS Flag (1), 2147 Unused Flags (2), 2148 Reserved (1), 2149 Stream Identifier (31), 2150 Field Block Fragment (..), 2151 } 2152 Figure 12: CONTINUATION Frame Format 2154 The Length, Type, Unused Flag(s), Reserved, and Stream Identifier 2155 fields are described in Section 4. The CONTINUATION frame payload 2156 contains a field block fragment (Section 4.3). 2158 The CONTINUATION frame defines the following flag: 2160 END_HEADERS (0x4): When set, the END_HEADERS Flag indicates that 2161 this frame ends a field block (Section 4.3). 2163 If the END_HEADERS Flag is not set, this frame MUST be followed by 2164 another CONTINUATION frame. A receiver MUST treat the receipt of 2165 any other type of frame or a frame on a different stream as a 2166 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 2168 The CONTINUATION frame changes the connection state as defined in 2169 Section 4.3. 2171 CONTINUATION frames MUST be associated with a stream. If a 2172 CONTINUATION frame is received whose stream identifier field is 0x0, 2173 the recipient MUST respond with a connection error (Section 5.4.1) of 2174 type PROTOCOL_ERROR. 2176 A CONTINUATION frame MUST be preceded by a HEADERS, PUSH_PROMISE or 2177 CONTINUATION frame without the END_HEADERS flag set. A recipient 2178 that observes violation of this rule MUST respond with a connection 2179 error (Section 5.4.1) of type PROTOCOL_ERROR. 2181 7. Error Codes 2183 Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY 2184 frames to convey the reasons for the stream or connection error. 2186 Error codes share a common code space. Some error codes apply only 2187 to either streams or the entire connection and have no defined 2188 semantics in the other context. 2190 The following error codes are defined: 2192 NO_ERROR (0x0): The associated condition is not a result of an 2193 error. For example, a GOAWAY might include this code to indicate 2194 graceful shutdown of a connection. 2196 PROTOCOL_ERROR (0x1): The endpoint detected an unspecific protocol 2197 error. This error is for use when a more specific error code is 2198 not available. 2200 INTERNAL_ERROR (0x2): The endpoint encountered an unexpected 2201 internal error. 2203 FLOW_CONTROL_ERROR (0x3): The endpoint detected that its peer 2204 violated the flow-control protocol. 2206 SETTINGS_TIMEOUT (0x4): The endpoint sent a SETTINGS frame but did 2207 not receive a response in a timely manner. See Section 6.5.3 2208 ("Settings Synchronization"). 2210 STREAM_CLOSED (0x5): The endpoint received a frame after a stream 2211 was half-closed. 2213 FRAME_SIZE_ERROR (0x6): The endpoint received a frame with an 2214 invalid size. 2216 REFUSED_STREAM (0x7): The endpoint refused the stream prior to 2217 performing any application processing (see Section 8.7 for 2218 details). 2220 CANCEL (0x8): Used by the endpoint to indicate that the stream is no 2221 longer needed. 2223 COMPRESSION_ERROR (0x9): The endpoint is unable to maintain the 2224 field section compression context for the connection. 2226 CONNECT_ERROR (0xa): The connection established in response to a 2227 CONNECT request (Section 8.5) was reset or abnormally closed. 2229 ENHANCE_YOUR_CALM (0xb): The endpoint detected that its peer is 2230 exhibiting a behavior that might be generating excessive load. 2232 INADEQUATE_SECURITY (0xc): The underlying transport has properties 2233 that do not meet minimum security requirements (see Section 9.2). 2235 HTTP_1_1_REQUIRED (0xd): The endpoint requires that HTTP/1.1 be used 2236 instead of HTTP/2. 2238 Unknown or unsupported error codes MUST NOT trigger any special 2239 behavior. These MAY be treated by an implementation as being 2240 equivalent to INTERNAL_ERROR. 2242 8. Expressing HTTP Semantics in HTTP/2 2244 HTTP/2 is an instantiation of the HTTP message abstraction (Section 6 2245 of [HTTP]). 2247 8.1. HTTP Message Framing 2249 A client sends an HTTP request on a new stream, using a previously 2250 unused stream identifier (Section 5.1.1). A server sends an HTTP 2251 response on the same stream as the request. 2253 An HTTP message (request or response) consists of: 2255 1. one HEADERS frame (followed by zero or more CONTINUATION frames) 2256 containing the header section (see Section 6.3 of [HTTP]), 2258 2. zero or more DATA frames containing the message content (see 2259 Section 6.4 of [HTTP]), and 2261 3. optionally, one HEADERS frame, followed by zero or more 2262 CONTINUATION frames containing the trailer-part, if present (see 2263 Section 6.5 of [HTTP]). 2265 For a response only, a server MAY send any number of interim 2266 responses before the HEADERS frame containing a final response. An 2267 interim response consists of a HEADERS frames (which might be 2268 followed by zero or more CONTINUATION frames) containing the control 2269 data and header section of an interim (1xx) HTTP response (see 2270 Section 15 of [HTTP]). A HEADERS frame with an END_STREAM flag that 2271 carries an informational status code is malformed (Section 8.1.1). 2273 The last frame in the sequence bears an END_STREAM flag, noting that 2274 a HEADERS frame bearing the END_STREAM flag can be followed by 2275 CONTINUATION frames that carry any remaining fragments of the field 2276 block. 2278 Other frames (from any stream) MUST NOT occur between the HEADERS 2279 frame and any CONTINUATION frames that might follow. 2281 HTTP/2 uses DATA frames to carry message content. The "chunked" 2282 transfer encoding defined in Section 7.1 of [HTTP11] cannot be used 2283 in HTTP/2. 2285 Trailer fields are carried in a field block that also terminates the 2286 stream. That is, trailer fields comprise a sequence starting with a 2287 HEADERS frame, followed by zero or more CONTINUATION frames, where 2288 the HEADERS frame bears an END_STREAM flag. Trailers MUST NOT 2289 include pseudo-header fields (Section 8.3). An endpoint that 2290 receives pseudo-header fields in trailers MUST treat the request or 2291 response as malformed (Section 8.1.1). 2293 An endpoint that receives a HEADERS frame without the END_STREAM flag 2294 set after receiving the HEADERS frame that opens a request or after 2295 receiving a final (non-informational) status code MUST treat the 2296 corresponding request or response as malformed (Section 8.1.1). 2298 An HTTP request/response exchange fully consumes a single stream. A 2299 request starts with the HEADERS frame that puts the stream into an 2300 "open" state. The request ends with a frame bearing END_STREAM, 2301 which causes the stream to become "half-closed (local)" for the 2302 client and "half-closed (remote)" for the server. A response stream 2303 starts with zero or more interim responses in HEADERS frames or a 2304 HEADERS frame containing a final status code. 2306 An HTTP response is complete after the server sends -- or the client 2307 receives -- a frame with the END_STREAM flag set (including any 2308 CONTINUATION frames needed to complete a field block). A server can 2309 send a complete response prior to the client sending an entire 2310 request if the response does not depend on any portion of the request 2311 that has not been sent and received. When this is true, a server MAY 2312 request that the client abort transmission of a request without error 2313 by sending a RST_STREAM with an error code of NO_ERROR after sending 2314 a complete response (i.e., a frame with the END_STREAM flag). 2315 Clients MUST NOT discard responses as a result of receiving such a 2316 RST_STREAM, though clients can always discard responses at their 2317 discretion for other reasons. 2319 8.1.1. Malformed Messages 2321 A malformed request or response is one that is an otherwise valid 2322 sequence of HTTP/2 frames but is invalid due to the presence of 2323 extraneous frames, prohibited fields or pseudo-header fields, the 2324 absence of mandatory fields or pseudo-header fields, the inclusion of 2325 uppercase field names, or invalid field names and/or values (in 2326 certain circumstances; see Section 8.2). 2328 A request or response that includes message content can include a 2329 "content-length" header field. A request or response is also 2330 malformed if the value of a "content-length" header field does not 2331 equal the sum of the DATA frame payload lengths that form the 2332 content. A response that is defined to have no content, as described 2333 in Section 6.4 of [HTTP], can have a non-zero "content-length" header 2334 field, even though no content is included in DATA frames. 2336 Intermediaries that process HTTP requests or responses (i.e., any 2337 intermediary not acting as a tunnel) MUST NOT forward a malformed 2338 request or response. Malformed requests or responses that are 2339 detected MUST be treated as a stream error (Section 5.4.2) of type 2340 PROTOCOL_ERROR. 2342 For malformed requests, a server MAY send an HTTP response prior to 2343 closing or resetting the stream. Clients MUST NOT accept a malformed 2344 response. 2346 Endpoints that progressively process messages might have performed 2347 some processing before identifying a request or response as 2348 malformed. For instance, it might be possible to generate an 2349 informational or 404 status code without having received a complete 2350 request. Similarly, intermediaries might forward incomplete messages 2351 before detecting errors. A server MAY generate a final response 2352 before receiving an entire request when the response does not depend 2353 on the remainder of the request being correct. A server or 2354 intermediary MAY use RST_STREAM -- with a code other than 2355 REFUSED_STREAM -- to abort a stream if a malformed request or 2356 response is received. 2358 These requirements are intended to protect against several types of 2359 common attacks against HTTP; they are deliberately strict because 2360 being permissive can expose implementations to these vulnerabilities. 2362 8.2. HTTP Fields 2364 HTTP fields (Section 5 of [HTTP]) are conveyed by HTTP/2 in the 2365 HEADERS, CONTINUATION, and PUSH_PROMISE frames, compressed with HPACK 2366 [COMPRESSION]. 2368 To improve efficiency and interoperability, field names MUST be 2369 converted to lowercase when constructing an HTTP/2 message. 2371 8.2.1. Field Validity 2373 HPACK is capable of carrying field names or values that are not valid 2374 in HTTP. Though HPACK can carry any octet, fields are not valid in 2375 the following cases: 2377 * A field name MUST NOT contain characters in the ranges 0x00-0x20, 2378 0x41-0x5A, or 0x7F-0xFF (all ranges inclusive). This limits field 2379 names to visible ASCII characters, other than ASCII SP (0x20) and 2380 uppercase characters ('A' to 'Z', ASCII 0x41 to 0x5a). 2382 * With the exception of pseudo-header fields (Section 8.3), which 2383 have a name that starts with a single colon, field names MUST NOT 2384 include a colon (ASCII COLON, 0x3a). 2386 * A field value MUST NOT contain the zero value (ASCII NUL, 0x0), 2387 line feed (ASCII LF, 0xa), or carriage return (ASCII CR, 0xd) at 2388 any position. 2390 * A field value MUST NOT start or end with an ASCII whitespace 2391 character (ASCII SP or HTAB, 0x20 or 0x9). 2393 A request or response that contains a field that violates any of 2394 these conditions MUST be treated as malformed (Section 8.1.1). In 2395 particular, an intermediary that does not process fields when 2396 forwarding messages MUST NOT forward fields that contain any of the 2397 values that are listed as prohibited above. 2399 A recipient MAY treat a message that contains a field name or value 2400 that includes other characters disallowed by Section 5.1 of [HTTP] 2401 and Section 5.5 of [HTTP] as malformed (Section 8.1.1). 2403 When a request message violates one of the requirements above, it 2404 SHOULD be responded to using the 400 (Bad Request) status code 2405 Section 15.5.1 of [HTTP] before the stream is reset, unless a more 2406 suitable status code is defined, or the status code cannot be sent 2407 (e.g., because the error occurs in a trailer field). 2409 Note that field values that are not valid according to the definition 2410 of the corresponding field do not cause a request to be malformed; 2411 the requirements above only apply to the generic syntax for field 2412 values as defined in Section 5.5 of [HTTP]. 2414 8.2.2. Connection-Specific Header Fields 2416 HTTP/2 does not use the "Connection" header field (Section 7.6.1 of 2417 [HTTP]) to indicate connection-specific header fields; in this 2418 protocol, connection-specific metadata is conveyed by other means. 2419 An endpoint MUST NOT generate an HTTP/2 message containing 2420 connection-specific header fields; any message containing connection- 2421 specific header fields MUST be treated as malformed (Section 8.1.1). 2423 The only exception to this is the TE header field, which MAY be 2424 present in an HTTP/2 request; when it is, it MUST NOT contain any 2425 value other than "trailers". 2427 An intermediary transforming a HTTP/1.x message to HTTP/2 MUST remove 2428 connection-specific header fields as discussed in Section 7.6.1 of 2429 [HTTP], or their messages will be treated by other HTTP/2 endpoints 2430 as malformed (Section 8.1.1). 2432 | Note: HTTP/2 purposefully does not support upgrade to another 2433 | protocol. The handshake methods described in Section 3 are 2434 | believed sufficient to negotiate the use of alternative 2435 | protocols. 2437 8.2.3. Compressing the Cookie Header Field 2439 The Cookie header field [COOKIE] uses a semi-colon (";") to delimit 2440 cookie-pairs (or "crumbs"). This header field contains multiple 2441 values, but does not use a COMMA (",") as a separator, which prevents 2442 cookie-pairs from being sent on multiple field lines (see Section 5.2 2443 of [HTTP]). This can significantly reduce compression efficiency as 2444 updates to individual cookie-pairs would invalidate any field lines 2445 that are stored in the HPACK table. 2447 To allow for better compression efficiency, the Cookie header field 2448 MAY be split into separate header fields, each with one or more 2449 cookie-pairs. If there are multiple Cookie header fields after 2450 decompression, these MUST be concatenated into a single octet string 2451 using the two-octet delimiter of 0x3B, 0x20 (the ASCII string "; ") 2452 before being passed into a non-HTTP/2 context, such as an HTTP/1.1 2453 connection, or a generic HTTP server application. 2455 Therefore, the following two lists of Cookie header fields are 2456 semantically equivalent. 2458 cookie: a=b; c=d; e=f 2460 cookie: a=b 2461 cookie: c=d 2462 cookie: e=f 2464 8.3. HTTP Control Data 2466 HTTP/2 uses special pseudo-header fields beginning with ':' character 2467 (ASCII 0x3a) to convey message control data (see Section 6.2 of 2468 [HTTP]). 2470 Pseudo-header fields are not HTTP header fields. Endpoints MUST NOT 2471 generate pseudo-header fields other than those defined in this 2472 document. Note that an extension could negotiate the use of 2473 additional pseudo-header fields; see Section 5.5. 2475 Pseudo-header fields are only valid in the context in which they are 2476 defined. Pseudo-header fields defined for requests MUST NOT appear 2477 in responses; pseudo-header fields defined for responses MUST NOT 2478 appear in requests. Pseudo-header fields MUST NOT appear in a 2479 trailer section. Endpoints MUST treat a request or response that 2480 contains undefined or invalid pseudo-header fields as malformed 2481 (Section 8.1.1). 2483 All pseudo-header fields MUST appear in a field block before all 2484 regular field lines. Any request or response that contains a pseudo- 2485 header field that appears in a field block after a regular field line 2486 MUST be treated as malformed (Section 8.1.1). 2488 8.3.1. Request Pseudo-Header Fields 2490 The following pseudo-header fields are defined for HTTP/2 requests: 2492 * The ":method" pseudo-header field includes the HTTP method 2493 (Section 9 of [HTTP]). 2495 * The ":scheme" pseudo-header field includes the scheme portion of 2496 the request target. The scheme is taken from the target URI 2497 (Section 3.1 of [RFC3986]) when generating a request directly, or 2498 from the scheme of a translated request (for example. see 2499 Section 3.3 of [HTTP11]). Scheme is omitted for CONNECT requests 2500 (Section 8.5). 2502 ":scheme" is not restricted to "http" and "https" schemed URIs. A 2503 proxy or gateway can translate requests for non-HTTP schemes, 2504 enabling the use of HTTP to interact with non-HTTP services. 2506 * The ":authority" pseudo-header field includes the authority 2507 portion of the target URI (Section 3.2 of [RFC3986]). The 2508 authority MUST NOT include the deprecated "userinfo" subcomponent 2509 for "http" or "https" schemed URIs. 2511 Clients that generate HTTP/2 requests directly SHOULD use the 2512 ":authority" pseudo-header field instead of the "Host" header 2513 field. 2515 An intermediary that translates a request to HTTP/2 from another 2516 HTTP version MUST translate any authority information from the 2517 request into an ":authority" pseudo-header field. If the control 2518 data in the original request contains authority information, an 2519 intermediary MUST include a ":authority" pseudo-header field. If 2520 control data does not contain authority, an intermediary MUST NOT 2521 add an ":authority" pseudo-header field. For reference, an 2522 HTTP/1.1 Section 3.2 of request target [HTTP11] in authority-form 2523 always includes authority, a request target in absolute-form 2524 includes authority if the target URI includes authority, and 2525 request targets in origin- or asterisk-form do not include 2526 authority. 2528 An intermediary that translates a request to another HTTP version 2529 from HTTP/2 can construct a "Host" header field by copying the 2530 value of the ":authority" pseudo-header field if that version 2531 requires that "Host" be included in a request, as HTTP/1.1 does 2532 for some forms of request target (see Section 3.2 of [HTTP11]). 2534 An intermediary that translates a request to HTTP/2 from another 2535 HTTP version MUST retain any "Host" header field, even if an 2536 authority is part of control data. 2538 The value of the "Host" header field MUST be ignored if control 2539 data contains authority (that is, the ":authority" pseudo-header 2540 field is present). 2542 * The ":path" pseudo-header field includes the path and query parts 2543 of the target URI (the "path-absolute" production and optionally a 2544 '?' character followed by the "query" production (see Sections 3.3 2545 and 3.4 of [RFC3986]). A request in asterisk form includes the 2546 value '*' for the ":path" pseudo-header field. 2548 This pseudo-header field MUST NOT be empty for "http" or "https" 2549 URIs; "http" or "https" URIs that do not contain a path component 2550 MUST include a value of '/'. The exception to this rule is an 2551 OPTIONS request for an "http" or "https" URI that does not include 2552 a path component; these MUST include a ":path" pseudo-header field 2553 with a value of '*' (see Section 7.1 of [HTTP]). 2555 All HTTP/2 requests MUST include exactly one valid value for the 2556 ":method", ":scheme", and ":path" pseudo-header fields, unless it is 2557 a CONNECT request (Section 8.5). An HTTP request that omits 2558 mandatory pseudo-header fields is malformed (Section 8.1.1). 2560 Individual HTTP/2 requests do not carry an explicit indicator of 2561 protocol version. All HTTP/2 messages implicitly have a protocol 2562 version of "2.0" (see Section 6.2 of [HTTP]). 2564 8.3.2. Response Pseudo-Header Fields 2566 For HTTP/2 responses, a single ":status" pseudo-header field is 2567 defined that carries the HTTP status code field (see Section 15 of 2568 [HTTP]). This pseudo-header field MUST be included in all responses, 2569 including interim responses; otherwise, the response is malformed 2570 (Section 8.1.1). 2572 HTTP/2 responses implicitly have a protocol version of "2.0". 2574 8.4. Server Push 2576 HTTP/2 allows a server to pre-emptively send (or "push") responses 2577 (along with corresponding "promised" requests) to a client in 2578 association with a previous client-initiated request. 2580 Server push was designed to allow a server to improve client- 2581 perceived performance by predicting what requests will follow those 2582 that it receives, thereby removing a round trip for them. For 2583 example, a request for HTML is often followed by requests for 2584 stylesheets and scripts referenced by that page. When these requests 2585 are pushed, the client does not need to wait to receive the 2586 references to them in the HTML and issue separate requests. 2588 In practice, server push is difficult to use effectively, because it 2589 requires the server to correctly anticipate the additional requests 2590 the client will make, taking into account factors such as caching, 2591 content negotiation, and user behavior. Errors in prediction can 2592 lead to performance degradation, due to the opportunity cost that the 2593 additional data on the wire represents. In particular, pushing any 2594 significant amount of data can cause contention issues with more- 2595 important responses. 2597 A client can request that server push be disabled, though this is 2598 negotiated for each hop independently. The SETTINGS_ENABLE_PUSH 2599 setting can be set to 0 to indicate that server push is disabled. 2601 Promised requests MUST be safe (see Section 9.2.1 of [HTTP]) and 2602 cacheable (see Section 9.2.3 of [HTTP]). Promised requests cannot 2603 include any content or a trailer section. Clients that receive a 2604 promised request that is not cacheable, that is not known to be safe, 2605 or that indicates the presence of request content MUST reset the 2606 promised stream with a stream error (Section 5.4.2) of type 2607 PROTOCOL_ERROR. Note this could result in the promised stream being 2608 reset if the client does not recognize a newly defined method as 2609 being safe. 2611 Pushed responses that are cacheable (see Section 3 of [CACHE]) can be 2612 stored by the client, if it implements an HTTP cache. Pushed 2613 responses are considered successfully validated on the origin server 2614 (e.g., if the "no-cache" cache response directive is present; see 2615 Section 5.2.2.3 of [CACHE]) while the stream identified by the 2616 promised stream ID is still open. 2618 Pushed responses that are not cacheable MUST NOT be stored by any 2619 HTTP cache. They MAY be made available to the application 2620 separately. 2622 The server MUST include a value in the ":authority" pseudo-header 2623 field for which the server is authoritative (see Section 10.1). A 2624 client MUST treat a PUSH_PROMISE for which the server is not 2625 authoritative as a stream error (Section 5.4.2) of type 2626 PROTOCOL_ERROR. 2628 An intermediary can receive pushes from the server and choose not to 2629 forward them on to the client. In other words, how to make use of 2630 the pushed information is up to that intermediary. Equally, the 2631 intermediary might choose to make additional pushes to the client, 2632 without any action taken by the server. 2634 A client cannot push. Thus, servers MUST treat the receipt of a 2635 PUSH_PROMISE frame as a connection error (Section 5.4.1) of type 2636 PROTOCOL_ERROR. A server cannot set the SETTINGS_ENABLE_PUSH setting 2637 to a value other than 0 (see Section 6.5.2). 2639 8.4.1. Push Requests 2641 Server push is semantically equivalent to a server responding to a 2642 request; however, in this case, that request is also sent by the 2643 server, as a PUSH_PROMISE frame. 2645 The PUSH_PROMISE frame includes a field block that contains control 2646 data and a complete set of request header fields that the server 2647 attributes to the request. It is not possible to push a response to 2648 a request that includes message content. 2650 Promised requests are always associated with an explicit request from 2651 the client. The PUSH_PROMISE frames sent by the server are sent on 2652 that explicit request's stream. The PUSH_PROMISE frame also includes 2653 a promised stream identifier, chosen from the stream identifiers 2654 available to the server (see Section 5.1.1). 2656 The header fields in PUSH_PROMISE and any subsequent CONTINUATION 2657 frames MUST be a valid and complete set of request header fields 2658 (Section 8.3.1). The server MUST include a method in the ":method" 2659 pseudo-header field that is safe and cacheable. If a client receives 2660 a PUSH_PROMISE that does not include a complete and valid set of 2661 header fields or the ":method" pseudo-header field identifies a 2662 method that is not safe, it MUST respond with a stream error 2663 (Section 5.4.2) of type PROTOCOL_ERROR. 2665 The server SHOULD send PUSH_PROMISE (Section 6.6) frames prior to 2666 sending any frames that reference the promised responses. This 2667 avoids a race where clients issue requests prior to receiving any 2668 PUSH_PROMISE frames. 2670 For example, if the server receives a request for a document 2671 containing embedded links to multiple image files and the server 2672 chooses to push those additional images to the client, sending 2673 PUSH_PROMISE frames before the DATA frames that contain the image 2674 links ensures that the client is able to see that a resource will be 2675 pushed before discovering embedded links. Similarly, if the server 2676 pushes responses referenced by the field block (for instance, in Link 2677 header fields), sending a PUSH_PROMISE before sending the header 2678 ensures that clients do not request those resources. 2680 PUSH_PROMISE frames MUST NOT be sent by the client. 2682 PUSH_PROMISE frames can be sent by the server in response to any 2683 client-initiated stream, but the stream MUST be in either the "open" 2684 or "half-closed (remote)" state with respect to the server. 2685 PUSH_PROMISE frames are interspersed with the frames that comprise a 2686 response, though they cannot be interspersed with HEADERS and 2687 CONTINUATION frames that comprise a single field block. 2689 Sending a PUSH_PROMISE frame creates a new stream and puts the stream 2690 into the "reserved (local)" state for the server and the "reserved 2691 (remote)" state for the client. 2693 8.4.2. Push Responses 2695 After sending the PUSH_PROMISE frame, the server can begin delivering 2696 the pushed response as a response (Section 8.3.2) on a server- 2697 initiated stream that uses the promised stream identifier. The 2698 server uses this stream to transmit an HTTP response, using the same 2699 sequence of frames as defined in Section 8.1. This stream becomes 2700 "half-closed" to the client (Section 5.1) after the initial HEADERS 2701 frame is sent. 2703 Once a client receives a PUSH_PROMISE frame and chooses to accept the 2704 pushed response, the client SHOULD NOT issue any requests for the 2705 promised response until after the promised stream has closed. 2707 If the client determines, for any reason, that it does not wish to 2708 receive the pushed response from the server or if the server takes 2709 too long to begin sending the promised response, the client can send 2710 a RST_STREAM frame, using either the CANCEL or REFUSED_STREAM code 2711 and referencing the pushed stream's identifier. 2713 A client can use the SETTINGS_MAX_CONCURRENT_STREAMS setting to limit 2714 the number of responses that can be concurrently pushed by a server. 2715 Advertising a SETTINGS_MAX_CONCURRENT_STREAMS value of zero disables 2716 server push by preventing the server from creating the necessary 2717 streams. This does not prohibit a server from sending PUSH_PROMISE 2718 frames; clients need to reset any promised streams that are not 2719 wanted. 2721 Clients receiving a pushed response MUST validate that either the 2722 server is authoritative (see Section 10.1) or the proxy that provided 2723 the pushed response is configured for the corresponding request. For 2724 example, a server that offers a certificate for only the 2725 "example.com" DNS-ID is not permitted to push a response for 2726 "https://www.example.org/doc". 2728 The response for a PUSH_PROMISE stream begins with a HEADERS frame, 2729 which immediately puts the stream into the "half-closed (remote)" 2730 state for the server and "half-closed (local)" state for the client, 2731 and ends with a frame bearing END_STREAM, which places the stream in 2732 the "closed" state. 2734 | Note: The client never sends a frame with the END_STREAM flag 2735 | for a server push. 2737 8.5. The CONNECT Method 2739 The CONNECT method (Section 9.3.6 of [HTTP]) is used to convert an 2740 HTTP connection into a tunnel to a remote host. CONNECT is primarily 2741 used with HTTP proxies to establish a TLS session with an origin 2742 server for the purposes of interacting with "https" resources. 2744 In HTTP/2, the CONNECT method establishes a tunnel over a single 2745 HTTP/2 stream to a remote host, rather than converting the entire 2746 connection to a tunnel. A CONNECT header section is constructed as 2747 defined in Section 8.3.1 ("Request Pseudo-Header Fields"), with a few 2748 differences. Specifically: 2750 * The ":method" pseudo-header field is set to "CONNECT". 2752 * The ":scheme" and ":path" pseudo-header fields MUST be omitted. 2754 * The ":authority" pseudo-header field contains the host and port to 2755 connect to (equivalent to the authority-form of the request-target 2756 of CONNECT requests; see Section 3.2.3 of [HTTP11]). 2758 A CONNECT request that does not conform to these restrictions is 2759 malformed (Section 8.1.1). 2761 A proxy that supports CONNECT establishes a TCP connection [TCP] to 2762 the host and port identified in the ":authority" pseudo-header field. 2763 Once this connection is successfully established, the proxy sends a 2764 HEADERS frame containing a 2xx series status code to the client, as 2765 defined in Section 9.3.6 of [HTTP]. 2767 After the initial HEADERS frame sent by each peer, all subsequent 2768 DATA frames correspond to data sent on the TCP connection. The frame 2769 payload of any DATA frames sent by the client is transmitted by the 2770 proxy to the TCP server; data received from the TCP server is 2771 assembled into DATA frames by the proxy. Frame types other than DATA 2772 or stream management frames (RST_STREAM, WINDOW_UPDATE, and PRIORITY) 2773 MUST NOT be sent on a connected stream and MUST be treated as a 2774 stream error (Section 5.4.2) if received. 2776 The TCP connection can be closed by either peer. The END_STREAM flag 2777 on a DATA frame is treated as being equivalent to the TCP FIN bit. A 2778 client is expected to send a DATA frame with the END_STREAM flag set 2779 after receiving a frame bearing the END_STREAM flag. A proxy that 2780 receives a DATA frame with the END_STREAM flag set sends the attached 2781 data with the FIN bit set on the last TCP segment. A proxy that 2782 receives a TCP segment with the FIN bit set sends a DATA frame with 2783 the END_STREAM flag set. Note that the final TCP segment or DATA 2784 frame could be empty. 2786 A TCP connection error is signaled with RST_STREAM. A proxy treats 2787 any error in the TCP connection, which includes receiving a TCP 2788 segment with the RST bit set, as a stream error (Section 5.4.2) of 2789 type CONNECT_ERROR. Correspondingly, a proxy MUST send a TCP segment 2790 with the RST bit set if it detects an error with the stream or the 2791 HTTP/2 connection. 2793 8.6. The Upgrade Header Field 2795 HTTP/2 does not support the 101 (Switching Protocols) informational 2796 status code (Section 15.2.2 of [HTTP]). 2798 The semantics of 101 (Switching Protocols) aren't applicable to a 2799 multiplexed protocol. Alternative protocols are able to use the same 2800 mechanisms that HTTP/2 uses to negotiate their use (see Section 3). 2802 8.7. Request Reliability 2804 In general, an HTTP client is unable to retry a non-idempotent 2805 request when an error occurs because there is no means to determine 2806 the nature of the error (see Section 9.2.2 of [HTTP]). It is 2807 possible that some server processing occurred prior to the error, 2808 which could result in undesirable effects if the request were 2809 reattempted. 2811 HTTP/2 provides two mechanisms for providing a guarantee to a client 2812 that a request has not been processed: 2814 * The GOAWAY frame indicates the highest stream number that might 2815 have been processed. Requests on streams with higher numbers are 2816 therefore guaranteed to be safe to retry. 2818 * The REFUSED_STREAM error code can be included in a RST_STREAM 2819 frame to indicate that the stream is being closed prior to any 2820 processing having occurred. Any request that was sent on the 2821 reset stream can be safely retried. 2823 Requests that have not been processed have not failed; clients MAY 2824 automatically retry them, even those with non-idempotent methods. 2826 A server MUST NOT indicate that a stream has not been processed 2827 unless it can guarantee that fact. If frames that are on a stream 2828 are passed to the application layer for any stream, then 2829 REFUSED_STREAM MUST NOT be used for that stream, and a GOAWAY frame 2830 MUST include a stream identifier that is greater than or equal to the 2831 given stream identifier. 2833 In addition to these mechanisms, the PING frame provides a way for a 2834 client to easily test a connection. Connections that remain idle can 2835 become broken as some middleboxes (for instance, network address 2836 translators or load balancers) silently discard connection bindings. 2837 The PING frame allows a client to safely test whether a connection is 2838 still active without sending a request. 2840 8.8. Examples 2842 This section shows HTTP/1.1 requests and responses, with 2843 illustrations of equivalent HTTP/2 requests and responses. 2845 An HTTP GET request includes control data and a request header with 2846 no message content and is therefore transmitted as a single HEADERS 2847 frame, followed by zero or more CONTINUATION frames containing the 2848 serialized block of request header fields. The HEADERS frame in the 2849 following has both the END_HEADERS and END_STREAM flags set; no 2850 CONTINUATION frames are sent. 2852 GET /resource HTTP/1.1 HEADERS 2853 Host: example.org ==> + END_STREAM 2854 Accept: image/jpeg + END_HEADERS 2855 :method = GET 2856 :scheme = https 2857 :path = /resource 2858 host = example.org 2859 accept = image/jpeg 2861 Similarly, a response that includes only control data and a response 2862 header is transmitted as a HEADERS frame (again, followed by zero or 2863 more CONTINUATION frames) containing the serialized block of response 2864 header fields. 2866 HTTP/1.1 304 Not Modified HEADERS 2867 ETag: "xyzzy" ==> + END_STREAM 2868 Expires: Thu, 23 Jan ... + END_HEADERS 2869 :status = 304 2870 etag = "xyzzy" 2871 expires = Thu, 23 Jan ... 2873 An HTTP POST request that includes control data and a request header 2874 and message content is transmitted as one HEADERS frame, followed by 2875 zero or more CONTINUATION frames containing the request header, 2876 followed by one or more DATA frames, with the last CONTINUATION (or 2877 HEADERS) frame having the END_HEADERS flag set and the final DATA 2878 frame having the END_STREAM flag set: 2880 POST /resource HTTP/1.1 HEADERS 2881 Host: example.org ==> - END_STREAM 2882 Content-Type: image/jpeg - END_HEADERS 2883 Content-Length: 123 :method = POST 2884 :path = /resource 2885 {binary data} :scheme = https 2887 CONTINUATION 2888 + END_HEADERS 2889 content-type = image/jpeg 2890 host = example.org 2891 content-length = 123 2893 DATA 2894 + END_STREAM 2895 {binary data} 2897 Note that data contributing to any given field line could be spread 2898 between field block fragments. The allocation of field lines to 2899 frames in this example is illustrative only. 2901 A response that includes control data and a response header and 2902 message content is transmitted as a HEADERS frame, followed by zero 2903 or more CONTINUATION frames, followed by one or more DATA frames, 2904 with the last DATA frame in the sequence having the END_STREAM flag 2905 set: 2907 HTTP/1.1 200 OK HEADERS 2908 Content-Type: image/jpeg ==> - END_STREAM 2909 Content-Length: 123 + END_HEADERS 2910 :status = 200 2911 {binary data} content-type = image/jpeg 2912 content-length = 123 2914 DATA 2915 + END_STREAM 2916 {binary data} 2918 An informational response using a 1xx status code other than 101 is 2919 transmitted as a HEADERS frame, followed by zero or more CONTINUATION 2920 frames. 2922 A trailer section is sent as a field block after both the request or 2923 response field block and all the DATA frames have been sent. The 2924 HEADERS frame starting the field block that comprises the trailer 2925 section has the END_STREAM flag set. 2927 The following example includes both a 100 (Continue) status code, 2928 which is sent in response to a request containing a "100-continue" 2929 token in the Expect header field, and a trailer section: 2931 HTTP/1.1 100 Continue HEADERS 2932 Extension-Field: bar ==> - END_STREAM 2933 + END_HEADERS 2934 :status = 100 2935 extension-field = bar 2937 HTTP/1.1 200 OK HEADERS 2938 Content-Type: image/jpeg ==> - END_STREAM 2939 Transfer-Encoding: chunked + END_HEADERS 2940 Trailer: Foo :status = 200 2941 content-length = 123 2942 123 content-type = image/jpeg 2943 {binary data} trailer = Foo 2944 0 2945 Foo: bar DATA 2946 - END_STREAM 2947 {binary data} 2949 HEADERS 2950 + END_STREAM 2951 + END_HEADERS 2952 foo = bar 2954 9. HTTP/2 Connections 2956 This section outlines attributes of the HTTP protocol that improve 2957 interoperability, reduce exposure to known security vulnerabilities, 2958 or reduce the potential for implementation variation. 2960 9.1. Connection Management 2962 HTTP/2 connections are persistent. For best performance, it is 2963 expected that clients will not close connections until it is 2964 determined that no further communication with a server is necessary 2965 (for example, when a user navigates away from a particular web page) 2966 or until the server closes the connection. 2968 Clients SHOULD NOT open more than one HTTP/2 connection to a given 2969 host and port pair, where the host is derived from a URI, a selected 2970 alternative service [ALT-SVC], or a configured proxy. 2972 A client can create additional connections as replacements, either to 2973 replace connections that are near to exhausting the available stream 2974 identifier space (Section 5.1.1), to refresh the keying material for 2975 a TLS connection, or to replace connections that have encountered 2976 errors (Section 5.4.1). 2978 A client MAY open multiple connections to the same IP address and TCP 2979 port using different Server Name Indication [TLS-EXT] values or to 2980 provide different TLS client certificates but SHOULD avoid creating 2981 multiple connections with the same configuration. 2983 Servers are encouraged to maintain open connections for as long as 2984 possible but are permitted to terminate idle connections if 2985 necessary. When either endpoint chooses to close the transport-layer 2986 TCP connection, the terminating endpoint SHOULD first send a GOAWAY 2987 (Section 6.8) frame so that both endpoints can reliably determine 2988 whether previously sent frames have been processed and gracefully 2989 complete or terminate any necessary remaining tasks. 2991 9.1.1. Connection Reuse 2993 Connections that are made to an origin server, either directly or 2994 through a tunnel created using the CONNECT method (Section 8.5), MAY 2995 be reused for requests with multiple different URI authority 2996 components. A connection can be reused as long as the origin server 2997 is authoritative (Section 10.1). For TCP connections without TLS, 2998 this depends on the host having resolved to the same IP address. 3000 For "https" resources, connection reuse additionally depends on 3001 having a certificate that is valid for the host in the URI. The 3002 certificate presented by the server MUST satisfy any checks that the 3003 client would perform when forming a new TLS connection for the host 3004 in the URI. A single certificate can be used to establish authority 3005 for multiple origins. Section 4.3 of [HTTP] describes how a client 3006 determines whether a server is authoritative for a URI. 3008 In some deployments, reusing a connection for multiple origins can 3009 result in requests being directed to the wrong origin server. For 3010 example, TLS termination might be performed by a middlebox that uses 3011 the TLS Server Name Indication (SNI) [TLS-EXT] extension to select an 3012 origin server. This means that it is possible for clients to send 3013 requests to servers that might not be the intended target for the 3014 request, even though the server is otherwise authoritative. 3016 A server that does not wish clients to reuse connections can indicate 3017 that it is not authoritative for a request by sending a 421 3018 (Misdirected Request) status code in response to the request (see 3019 Section 15.5.20 of [HTTP]). 3021 A client that is configured to use a proxy over HTTP/2 directs 3022 requests to that proxy through a single connection. That is, all 3023 requests sent via a proxy reuse the connection to the proxy. 3025 9.2. Use of TLS Features 3027 Implementations of HTTP/2 MUST use TLS version 1.2 [TLS12] or higher 3028 for HTTP/2 over TLS. The general TLS usage guidance in [TLSBCP] 3029 SHOULD be followed, with some additional restrictions that are 3030 specific to HTTP/2. 3032 The TLS implementation MUST support the Server Name Indication (SNI) 3033 [TLS-EXT] extension to TLS. If the server is identified by a domain 3034 name [DNS-TERMS], clients MUST send the server_name TLS extension 3035 unless an alternative mechanism to indicate the target host is used. 3037 Requirements for deployments of HTTP/2 that negotiate TLS 1.3 [TLS13] 3038 are included in Section 9.2.3. Deployments of TLS 1.2 are subject to 3039 the requirements in Section 9.2.1 and Section 9.2.2. Implementations 3040 are encouraged to provide defaults that comply, but it is recognized 3041 that deployments are ultimately responsible for compliance. 3043 9.2.1. TLS 1.2 Features 3045 This section describes restrictions on the TLS 1.2 feature set that 3046 can be used with HTTP/2. Due to deployment limitations, it might not 3047 be possible to fail TLS negotiation when these restrictions are not 3048 met. An endpoint MAY immediately terminate an HTTP/2 connection that 3049 does not meet these TLS requirements with a connection error 3050 (Section 5.4.1) of type INADEQUATE_SECURITY. 3052 A deployment of HTTP/2 over TLS 1.2 MUST disable compression. TLS 3053 compression can lead to the exposure of information that would not 3054 otherwise be revealed [RFC3749]. Generic compression is unnecessary 3055 since HTTP/2 provides compression features that are more aware of 3056 context and therefore likely to be more appropriate for use for 3057 performance, security, or other reasons. 3059 A deployment of HTTP/2 over TLS 1.2 MUST disable renegotiation. An 3060 endpoint MUST treat a TLS renegotiation as a connection error 3061 (Section 5.4.1) of type PROTOCOL_ERROR. Note that disabling 3062 renegotiation can result in long-lived connections becoming unusable 3063 due to limits on the number of messages the underlying cipher suite 3064 can encipher. 3066 An endpoint MAY use renegotiation to provide confidentiality 3067 protection for client credentials offered in the handshake, but any 3068 renegotiation MUST occur prior to sending the connection preface. A 3069 server SHOULD request a client certificate if it sees a renegotiation 3070 request immediately after establishing a connection. 3072 This effectively prevents the use of renegotiation in response to a 3073 request for a specific protected resource. A future specification 3074 might provide a way to support this use case. Alternatively, a 3075 server might use an error (Section 5.4) of type HTTP_1_1_REQUIRED to 3076 request the client use a protocol that supports renegotiation. 3078 Implementations MUST support ephemeral key exchange sizes of at least 3079 2048 bits for cipher suites that use ephemeral finite field Diffie- 3080 Hellman (DHE) [TLS13] and 224 bits for cipher suites that use 3081 ephemeral elliptic curve Diffie-Hellman (ECDHE) [RFC4492]. Clients 3082 MUST accept DHE sizes of up to 4096 bits. Endpoints MAY treat 3083 negotiation of key sizes smaller than the lower limits as a 3084 connection error (Section 5.4.1) of type INADEQUATE_SECURITY. 3086 9.2.2. TLS 1.2 Cipher Suites 3088 A deployment of HTTP/2 over TLS 1.2 SHOULD NOT use any of the cipher 3089 suites that are listed in the list of prohibited cipher suites 3090 (Appendix A). 3092 Endpoints MAY choose to generate a connection error (Section 5.4.1) 3093 of type INADEQUATE_SECURITY if one of the prohibited cipher suites is 3094 negotiated. A deployment that chooses to use a prohibited cipher 3095 suite risks triggering a connection error unless the set of potential 3096 peers is known to accept that cipher suite. 3098 Implementations MUST NOT generate this error in reaction to the 3099 negotiation of a cipher suite that is not prohibited. Consequently, 3100 when clients offer a cipher suite that is not prohibited, they have 3101 to be prepared to use that cipher suite with HTTP/2. 3103 The list of prohibited cipher suites includes the cipher suite that 3104 TLS 1.2 makes mandatory, which means that TLS 1.2 deployments could 3105 have non-intersecting sets of permitted cipher suites. To avoid this 3106 problem causing TLS handshake failures, deployments of HTTP/2 that 3107 use TLS 1.2 MUST support TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 3108 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186]. 3110 Note that clients might advertise support of cipher suites that are 3111 prohibited in order to allow for connection to servers that do not 3112 support HTTP/2. This allows servers to select HTTP/1.1 with a cipher 3113 suite that is prohibited in HTTP/2. However, this can result in 3114 HTTP/2 being negotiated with a prohibited cipher suite if the 3115 application protocol and cipher suite are independently selected. 3117 9.2.3. TLS 1.3 Features 3119 TLS 1.3 includes a number of features not available in earlier 3120 versions. This section discusses the use of these features. 3122 HTTP/2 servers MUST NOT send post-handshake TLS 1.3 3123 CertificateRequest messages. HTTP/2 clients MUST treat a TLS post- 3124 handshake CertificateRequest message as a connection error 3125 (Section 5.4.1) of type PROTOCOL_ERROR. 3127 The prohibition on post-handshake authentication applies even if the 3128 client offered the "post_handshake_auth" TLS extension. Post- 3129 handshake authentication support might be advertised independently of 3130 ALPN [TLS-ALPN]. Clients might offer the capability for use in other 3131 protocols, but inclusion of the extension cannot imply support within 3132 HTTP/2. 3134 [TLS13] defines other post-handshake messages, NewSessionTicket and 3135 KeyUpdate, which can be used as they have no direct interaction with 3136 HTTP/2. Unless the use of a new type of TLS message depends on an 3137 interaction with the application-layer protocol, that TLS message can 3138 be sent after the handshake completes. 3140 TLS early data MAY be used to send requests, provided that the 3141 guidance in [RFC8470] is observed. Clients send requests in early 3142 data assuming initial values for all server settings. 3144 10. Security Considerations 3146 10.1. Server Authority 3148 HTTP/2 relies on the HTTP definition of authority for determining 3149 whether a server is authoritative in providing a given response (see 3150 Section 4.3 of [HTTP]). This relies on local name resolution for the 3151 "http" URI scheme and the authenticated server identity for the 3152 "https" scheme. 3154 10.2. Cross-Protocol Attacks 3156 In a cross-protocol attack, an attacker causes a client to initiate a 3157 transaction in one protocol toward a server that understands a 3158 different protocol. An attacker might be able to cause the 3159 transaction to appear as a valid transaction in the second protocol. 3160 In combination with the capabilities of the web context, this can be 3161 used to interact with poorly protected servers in private networks. 3163 Completing a TLS handshake with an ALPN identifier for HTTP/2 can be 3164 considered sufficient protection against cross-protocol attacks. 3165 ALPN provides a positive indication that a server is willing to 3166 proceed with HTTP/2, which prevents attacks on other TLS-based 3167 protocols. 3169 The encryption in TLS makes it difficult for attackers to control the 3170 data that could be used in a cross-protocol attack on a cleartext 3171 protocol. 3173 The cleartext version of HTTP/2 has minimal protection against cross- 3174 protocol attacks. The connection preface (Section 3.4) contains a 3175 string that is designed to confuse HTTP/1.1 servers, but no special 3176 protection is offered for other protocols. 3178 10.3. Intermediary Encapsulation Attacks 3180 HPACK permits encoding of field names and values that might be 3181 treated as delimiters in other HTTP versions. An intermediary that 3182 translates an HTTP/2 request or response MUST validate fields 3183 according to the rules in Section 8.2 roles before translating a 3184 message to another HTTP version. Translating a field that includes 3185 invalid delimiters could be used to cause recipients to incorrectly 3186 interpret a message, which could be exploited by an attacker. 3188 An intermediary can reject fields that contain invalid field names or 3189 values for other reasons, in particular those that do not conform to 3190 the HTTP ABNF grammar from Section 5 of [HTTP]. Intermediaries that 3191 do not perform any validation of fields other than the minimum 3192 required by Section 8.2 could forward messages that contain invalid 3193 field names or values. 3195 An intermediary that receives any field that requires removal before 3196 forwarding (see Section 7.6.1 of [HTTP]) MUST remove or replace those 3197 header fields when forwarding messages. Additionally, intermediaries 3198 should take care when forwarding messages containing Content-Length 3199 fields to ensure that the message is well-formed (Section 8.1.1). 3200 This ensures that if the message is translated into HTTP/1.1 at any 3201 point the framing will be correct. 3203 10.4. Cacheability of Pushed Responses 3205 Pushed responses do not have an explicit request from the client; the 3206 request is provided by the server in the PUSH_PROMISE frame. 3208 Caching responses that are pushed is possible based on the guidance 3209 provided by the origin server in the Cache-Control header field. 3210 However, this can cause issues if a single server hosts more than one 3211 tenant. For example, a server might offer multiple users each a 3212 small portion of its URI space. 3214 Where multiple tenants share space on the same server, that server 3215 MUST ensure that tenants are not able to push representations of 3216 resources that they do not have authority over. Failure to enforce 3217 this would allow a tenant to provide a representation that would be 3218 served out of cache, overriding the actual representation that the 3219 authoritative tenant provides. 3221 Pushed responses for which an origin server is not authoritative (see 3222 Section 10.1) MUST NOT be used or cached. 3224 10.5. Denial-of-Service Considerations 3226 An HTTP/2 connection can demand a greater commitment of resources to 3227 operate than an HTTP/1.1 connection. The use of field section 3228 compression and flow control depend on a commitment of resources for 3229 storing a greater amount of state. Settings for these features 3230 ensure that memory commitments for these features are strictly 3231 bounded. 3233 The number of PUSH_PROMISE frames is not constrained in the same 3234 fashion. A client that accepts server push SHOULD limit the number 3235 of streams it allows to be in the "reserved (remote)" state. An 3236 excessive number of server push streams can be treated as a stream 3237 error (Section 5.4.2) of type ENHANCE_YOUR_CALM. 3239 A number of HTTP/2 implementations were found to be vulnerable to 3240 denial of service [NFLX-2019-002]. The following lists known ways 3241 that implementations might be subject to denial of service attack: 3243 * Inefficient tracking of outstanding outbound frames can lead to 3244 overload if an adversary can cause large numbers of frames to be 3245 enqueued for sending. A peer could use one of several techniques 3246 to cause large numbers of frames to be generated: 3248 - Providing tiny increments to flow control in WINDOW_UPDATE 3249 frames can cause a sender to generate a large number of DATA 3250 frames. 3252 - An endpoint is required to respond to a PING frame. 3254 - Each SETTINGS frame requires acknowledgment. 3256 - An invalid request (or server push) can cause a peer to send 3257 RST_STREAM frames in response. 3259 * Large numbers of small or empty frames can be abused to cause a 3260 peer to expend time processing frame headers. Caution is required 3261 here as some uses of small frames are entirely legitimate, such as 3262 the sending of an empty DATA or CONTINUATION frame at the end of a 3263 stream. 3265 * The SETTINGS frame might also be abused to cause a peer to expend 3266 additional processing time. This might be done by pointlessly 3267 changing settings, sending multiple undefined settings, or 3268 changing the same setting multiple times in the same frame. 3270 * Handling reprioritization with PRIORITY frames can require 3271 significant processing time and can lead to overload if many 3272 PRIORITY frames are sent. 3274 * Field section compression also offers some opportunities to waste 3275 processing resources; see Section 7 of [COMPRESSION] for more 3276 details on potential abuses. 3278 * Limits in SETTINGS cannot be reduced instantaneously, which leaves 3279 an endpoint exposed to behavior from a peer that could exceed the 3280 new limits. In particular, immediately after establishing a 3281 connection, limits set by a server are not known to clients and 3282 could be exceeded without being an obvious protocol violation. 3284 * An attacker can provide large amounts of flow control credit at 3285 the HTTP/2 layer, but withhold credit at the TCP layer, preventing 3286 frames from being sent. An endpoint that constructs and remembers 3287 frames for sending without considering TCP limits might be subject 3288 to resource exhaustion. 3290 Most of the features that might be exploited for denial of service -- 3291 i.e., SETTINGS changes, small frames, field section compression -- 3292 have legitimate uses. These features become a burden only when they 3293 are used unnecessarily or to excess. 3295 An endpoint that doesn't monitor use of these features exposes itself 3296 to a risk of denial of service. Implementations SHOULD track the use 3297 of these features and set limits on their use. An endpoint MAY treat 3298 activity that is suspicious as a connection error (Section 5.4.1) of 3299 type ENHANCE_YOUR_CALM. 3301 10.5.1. Limits on Field Block Size 3303 A large field block (Section 4.3) can cause an implementation to 3304 commit a large amount of state. Field lines that are critical for 3305 routing can appear toward the end of a field block, which prevents 3306 streaming of fields to their ultimate destination. This ordering and 3307 other reasons, such as ensuring cache correctness, mean that an 3308 endpoint might need to buffer the entire field block. Since there is 3309 no hard limit to the size of a field block, some endpoints could be 3310 forced to commit a large amount of available memory for field blocks. 3312 An endpoint can use the SETTINGS_MAX_HEADER_LIST_SIZE to advise peers 3313 of limits that might apply on the size of uncompressed field blocks. 3314 This setting is only advisory, so endpoints MAY choose to send field 3315 blocks that exceed this limit and risk having the request or response 3316 being treated as malformed. This setting is specific to a 3317 connection, so any request or response could encounter a hop with a 3318 lower, unknown limit. An intermediary can attempt to avoid this 3319 problem by passing on values presented by different peers, but they 3320 are not obliged to do so. 3322 A server that receives a larger field block than it is willing to 3323 handle can send an HTTP 431 (Request Header Fields Too Large) status 3324 code [RFC6585]. A client can discard responses that it cannot 3325 process. The field block MUST be processed to ensure a consistent 3326 connection state, unless the connection is closed. 3328 10.5.2. CONNECT Issues 3330 The CONNECT method can be used to create disproportionate load on an 3331 proxy, since stream creation is relatively inexpensive when compared 3332 to the creation and maintenance of a TCP connection. A proxy might 3333 also maintain some resources for a TCP connection beyond the closing 3334 of the stream that carries the CONNECT request, since the outgoing 3335 TCP connection remains in the TIME_WAIT state. Therefore, a proxy 3336 cannot rely on SETTINGS_MAX_CONCURRENT_STREAMS alone to limit the 3337 resources consumed by CONNECT requests. 3339 10.6. Use of Compression 3341 Compression can allow an attacker to recover secret data when it is 3342 compressed in the same context as data under attacker control. 3343 HTTP/2 enables compression of field lines (Section 4.3); the 3344 following concerns also apply to the use of HTTP compressed content- 3345 codings (Section 8.4.1 of [HTTP]). 3347 There are demonstrable attacks on compression that exploit the 3348 characteristics of the web (e.g., [BREACH]). The attacker induces 3349 multiple requests containing varying plaintext, observing the length 3350 of the resulting ciphertext in each, which reveals a shorter length 3351 when a guess about the secret is correct. 3353 Implementations communicating on a secure channel MUST NOT compress 3354 content that includes both confidential and attacker-controlled data 3355 unless separate compression dictionaries are used for each source of 3356 data. Compression MUST NOT be used if the source of data cannot be 3357 reliably determined. Generic stream compression, such as that 3358 provided by TLS, MUST NOT be used with HTTP/2 (see Section 9.2). 3360 Further considerations regarding the compression of header fields are 3361 described in [COMPRESSION]. 3363 10.7. Use of Padding 3365 Padding within HTTP/2 is not intended as a replacement for general 3366 purpose padding, such as that provided by TLS [TLS13]. Redundant 3367 padding could even be counterproductive. Correct application can 3368 depend on having specific knowledge of the data that is being padded. 3370 To mitigate attacks that rely on compression, disabling or limiting 3371 compression might be preferable to padding as a countermeasure. 3373 Padding can be used to obscure the exact size of frame content and is 3374 provided to mitigate specific attacks within HTTP, for example, 3375 attacks where compressed content includes both attacker-controlled 3376 plaintext and secret data (e.g., [BREACH]). 3378 Use of padding can result in less protection than might seem 3379 immediately obvious. At best, padding only makes it more difficult 3380 for an attacker to infer length information by increasing the number 3381 of frames an attacker has to observe. Incorrectly implemented 3382 padding schemes can be easily defeated. In particular, randomized 3383 padding with a predictable distribution provides very little 3384 protection; similarly, padding frame payloads to a fixed size exposes 3385 information as frame payload sizes cross the fixed-sized boundary, 3386 which could be possible if an attacker can control plaintext. 3388 Intermediaries SHOULD retain padding for DATA frames but MAY drop 3389 padding for HEADERS and PUSH_PROMISE frames. A valid reason for an 3390 intermediary to change the amount of padding of frames is to improve 3391 the protections that padding provides. 3393 10.8. Privacy Considerations 3395 Several characteristics of HTTP/2 provide an observer an opportunity 3396 to correlate actions of a single client or server over time. These 3397 include the value of settings, the manner in which flow-control 3398 windows are managed, the way priorities are allocated to streams, the 3399 timing of reactions to stimulus, and the handling of any features 3400 that are controlled by settings. 3402 As far as these create observable differences in behavior, they could 3403 be used as a basis for fingerprinting a specific client, as defined 3404 in Section 3.2 of [PRIVACY]. 3406 HTTP/2's preference for using a single TCP connection allows 3407 correlation of a user's activity on a site. Reusing connections for 3408 different origins allows tracking across those origins. 3410 Because the PING and SETTINGS frames solicit immediate responses, 3411 they can be used by an endpoint to measure latency to their peer. 3412 This might have privacy implications in certain scenarios. 3414 10.9. Remote Timing Attacks 3416 Remote timing attacks extract secrets from servers by observing 3417 variations in the time that servers take when processing requests 3418 that use secrets. HTTP/2 enables concurrent request creation and 3419 processing, which can give attackers better control over when request 3420 processing commences. Multiple HTTP/2 requests can be included in 3421 the same IP packet or TLS record. HTTP/2 can therefore make remote 3422 timing attacks more efficient by eliminating variability in request 3423 delivery, leaving only request order and the delivery of responses as 3424 sources of timing variability. 3426 Ensuring that processing time is not dependent on the value of 3427 secrets is the best defense against any form of timing attack. 3429 11. IANA Considerations 3431 A string for identifying HTTP/2 is entered into the "Application- 3432 Layer Protocol Negotiation (ALPN) Protocol IDs" registry established 3433 in [TLS-ALPN]. 3435 This document establishes a registry for frame types, settings, and 3436 error codes. These new registries appear in the new "Hypertext 3437 Transfer Protocol version 2 (HTTP/2)" section. 3439 This revision of the document marks the "HTTP2-Settings" header field 3440 registered in [RFC7540] obsolete. 3442 This document registers the "PRI" method for use in HTTP to avoid 3443 collisions with the connection preface (Section 3.4). 3445 11.1. Registration of HTTP/2 Identification Strings 3447 This document creates two registrations for the identification of 3448 HTTP/2 (see Section 3.2) in the "Application-Layer Protocol 3449 Negotiation (ALPN) Protocol IDs" registry established in [TLS-ALPN]. 3451 The "h2" string identifies HTTP/2 when used over TLS: 3453 Protocol: HTTP/2 over TLS 3455 Identification Sequence: 0x68 0x32 ("h2") 3457 Specification: This document 3459 The "h2c" string identifies HTTP/2 when used over cleartext TCP: 3461 Protocol: HTTP/2 over TCP 3463 Identification Sequence: 0x68 0x32 0x63 ("h2c") 3465 Specification: This document 3467 11.2. Frame Type Registry 3469 This document establishes a registry for HTTP/2 frame type codes. 3470 The "HTTP/2 Frame Type" registry manages an 8-bit space. The "HTTP/2 3471 Frame Type" registry operates under either of the Section 4.8 of 3472 "IETF Review" [RFC8126] or Section 4.10 of "IESG Approval" [RFC8126] 3473 policies. 3475 New entries in this registry require the following information: 3477 Frame Type: A name or label for the frame type. 3479 Code: The 8-bit code assigned to the frame type. 3481 Specification: A reference to a specification that includes a 3482 description of the frame layout, its semantics, and flags that the 3483 frame type uses, including any parts of the frame that are 3484 conditionally present based on the value of flags. 3486 The entries in the following table are registered by this document. 3488 +===============+======+==============+ 3489 | Frame Type | Code | Section | 3490 +===============+======+==============+ 3491 | DATA | 0x0 | Section 6.1 | 3492 +---------------+------+--------------+ 3493 | HEADERS | 0x1 | Section 6.2 | 3494 +---------------+------+--------------+ 3495 | PRIORITY | 0x2 | Section 6.3 | 3496 +---------------+------+--------------+ 3497 | RST_STREAM | 0x3 | Section 6.4 | 3498 +---------------+------+--------------+ 3499 | SETTINGS | 0x4 | Section 6.5 | 3500 +---------------+------+--------------+ 3501 | PUSH_PROMISE | 0x5 | Section 6.6 | 3502 +---------------+------+--------------+ 3503 | PING | 0x6 | Section 6.7 | 3504 +---------------+------+--------------+ 3505 | GOAWAY | 0x7 | Section 6.8 | 3506 +---------------+------+--------------+ 3507 | WINDOW_UPDATE | 0x8 | Section 6.9 | 3508 +---------------+------+--------------+ 3509 | CONTINUATION | 0x9 | Section 6.10 | 3510 +---------------+------+--------------+ 3512 Table 1 3514 11.3. Settings Registry 3516 This document establishes a registry for HTTP/2 settings. The 3517 "HTTP/2 Settings" registry manages a 16-bit space. The "HTTP/2 3518 Settings" registry operates under the Section 4.5 of "Expert Review" 3519 policy [RFC8126]. 3521 New registrations are advised to provide the following information: 3523 Name: A symbolic name for the setting. Specifying a setting name is 3524 optional. 3526 Code: The 16-bit code assigned to the setting. 3528 Initial Value: An initial value for the setting. 3530 Specification: An optional reference to a specification that 3531 describes the use of the setting. 3533 The entries in the following table are registered by this document. 3535 +========================+======+===============+===============+ 3536 | Name | Code | Initial Value | Specification | 3537 +========================+======+===============+===============+ 3538 | HEADER_TABLE_SIZE | 0x1 | 4096 | Section 6.5.2 | 3539 +------------------------+------+---------------+---------------+ 3540 | ENABLE_PUSH | 0x2 | 1 | Section 6.5.2 | 3541 +------------------------+------+---------------+---------------+ 3542 | MAX_CONCURRENT_STREAMS | 0x3 | (infinite) | Section 6.5.2 | 3543 +------------------------+------+---------------+---------------+ 3544 | INITIAL_WINDOW_SIZE | 0x4 | 65535 | Section 6.5.2 | 3545 +------------------------+------+---------------+---------------+ 3546 | MAX_FRAME_SIZE | 0x5 | 16384 | Section 6.5.2 | 3547 +------------------------+------+---------------+---------------+ 3548 | MAX_HEADER_LIST_SIZE | 0x6 | (infinite) | Section 6.5.2 | 3549 +------------------------+------+---------------+---------------+ 3551 Table 2 3553 11.4. Error Code Registry 3555 This document establishes a registry for HTTP/2 error codes. The 3556 "HTTP/2 Error Code" registry manages a 32-bit space. The "HTTP/2 3557 Error Code" registry operates under the Section 4.5 of "Expert 3558 Review" policy [RFC8126]. 3560 Registrations for error codes are required to include a description 3561 of the error code. An expert reviewer is advised to examine new 3562 registrations for possible duplication with existing error codes. 3563 Use of existing registrations is to be encouraged, but not mandated. 3565 New registrations are advised to provide the following information: 3567 Name: A name for the error code. Specifying an error code name is 3568 optional. 3570 Code: The 32-bit error code value. 3572 Description: A brief description of the error code semantics, longer 3573 if no detailed specification is provided. 3575 Specification: An optional reference for a specification that 3576 defines the error code. 3578 The entries in the following table are registered by this document. 3580 +=====================+======+======================+===============+ 3581 | Name | Code | Description | Specification | 3582 +=====================+======+======================+===============+ 3583 | NO_ERROR | 0x0 | Graceful shutdown | Section 7 | 3584 +---------------------+------+----------------------+---------------+ 3585 | PROTOCOL_ERROR | 0x1 | Protocol error | Section 7 | 3586 | | | detected | | 3587 +---------------------+------+----------------------+---------------+ 3588 | INTERNAL_ERROR | 0x2 | Implementation | Section 7 | 3589 | | | fault | | 3590 +---------------------+------+----------------------+---------------+ 3591 | FLOW_CONTROL_ERROR | 0x3 | Flow-control | Section 7 | 3592 | | | limits exceeded | | 3593 +---------------------+------+----------------------+---------------+ 3594 | SETTINGS_TIMEOUT | 0x4 | Settings not | Section 7 | 3595 | | | acknowledged | | 3596 +---------------------+------+----------------------+---------------+ 3597 | STREAM_CLOSED | 0x5 | Frame received | Section 7 | 3598 | | | for closed stream | | 3599 +---------------------+------+----------------------+---------------+ 3600 | FRAME_SIZE_ERROR | 0x6 | Frame size | Section 7 | 3601 | | | incorrect | | 3602 +---------------------+------+----------------------+---------------+ 3603 | REFUSED_STREAM | 0x7 | Stream not | Section 7 | 3604 | | | processed | | 3605 +---------------------+------+----------------------+---------------+ 3606 | CANCEL | 0x8 | Stream cancelled | Section 7 | 3607 +---------------------+------+----------------------+---------------+ 3608 | COMPRESSION_ERROR | 0x9 | Compression state | Section 7 | 3609 | | | not updated | | 3610 +---------------------+------+----------------------+---------------+ 3611 | CONNECT_ERROR | 0xa | TCP connection | Section 7 | 3612 | | | error for CONNECT | | 3613 | | | method | | 3614 +---------------------+------+----------------------+---------------+ 3615 | ENHANCE_YOUR_CALM | 0xb | Processing | Section 7 | 3616 | | | capacity exceeded | | 3617 +---------------------+------+----------------------+---------------+ 3618 | INADEQUATE_SECURITY | 0xc | Negotiated TLS | Section 7 | 3619 | | | parameters not | | 3620 | | | acceptable | | 3621 +---------------------+------+----------------------+---------------+ 3622 | HTTP_1_1_REQUIRED | 0xd | Use HTTP/1.1 for | Section 7 | 3623 | | | the request | | 3624 +---------------------+------+----------------------+---------------+ 3626 Table 3 3628 11.5. HTTP2-Settings Header Field Registration 3630 This section marks the "HTTP2-Settings" header field registered in 3631 Section 11.5 of [RFC7540] as obsoleted. The registration is updated 3632 to include the details as required by Section 18.4 of [HTTP]: 3634 Field Name: HTTP2-Settings 3636 Status: Standard 3638 Ref.: Section 3.2.1 of [RFC7540] 3640 Comments: Obsolete; see Section 11.5 3642 11.6. PRI Method Registration 3644 This section registers the "PRI" method in the "HTTP Method Registry" 3645 (Section 18.2 of [HTTP]). 3647 Method Name: PRI 3649 Safe: Yes 3651 Idempotent: Yes 3653 Specification document(s): Section 3.4 of this document 3655 Related information: This method is never used by an actual client. 3656 This method will appear to be used when an HTTP/1.1 server or 3657 intermediary attempts to parse an HTTP/2 connection preface. 3659 11.7. The h2c Upgrade Token 3661 Previous versions of this document (Section 11.8 of [RFC7540]) 3662 registered an upgrade token. This capability has been removed: see 3663 Section 3.1. 3665 12. References 3667 12.1. Normative References 3669 [CACHE] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3670 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 3671 draft-ietf-httpbis-cache-15, 30 March 2021, 3672 . 3675 [COMPRESSION] 3676 Peon, R. and H. Ruellan, "HPACK: Header Compression for 3677 HTTP/2", RFC 7541, May 2015, 3678 . 3680 [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3681 April 2011, . 3683 [FIPS186] NIST, "Digital Signature Standard (DSS)", FIPS PUB 186-4, 3684 July 2013, . 3686 [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3687 Ed., "HTTP Semantics", Work in Progress, Internet-Draft, 3688 draft-ietf-httpbis-semantics-15, 30 March 2021, 3689 . 3692 [QUIC] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 3693 Multiplexed and Secure Transport", RFC 9000, 3694 DOI 10.17487/RFC9000, May 2021, 3695 . 3697 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3698 Requirement Levels", BCP 14, RFC 2119, March 1997, 3699 . 3701 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3702 Resource Identifier (URI): Generic Syntax", STD 66, 3703 RFC 3986, January 2005, 3704 . 3706 [RFC8126] Cotton, M., Leiba, B., and R. Narten, "Guidelines for 3707 Writing an IANA Considerations Section in RFCs", BCP 26, 3708 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3709 . 3711 [RFC8470] Thomson, M., Nottingham, M., and W. Tarreau, "Using Early 3712 Data in HTTP", RFC 8470, DOI 10.17487/RFC8470, September 3713 2018, . 3715 [TCP] Postel, J., "Transmission Control Protocol", STD 7, 3716 RFC 793, September 1981, 3717 . 3719 [TLS-ALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan, 3720 "Transport Layer Security (TLS) Application-Layer Protocol 3721 Negotiation Extension", RFC 7301, July 2014, 3722 . 3724 [TLS-ECDHE] 3725 Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 3726 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 3727 August 2008, . 3729 [TLS-EXT] Eastlake 3rd, D., "Transport Layer Security (TLS) 3730 Extensions: Extension Definitions", RFC 6066, January 3731 2011, . 3733 [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer Security 3734 (TLS) Protocol Version 1.2", RFC 5246, August 2008, 3735 . 3737 [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3738 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3739 . 3741 12.2. Informative References 3743 [ALT-SVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP 3744 Alternative Services", RFC 7838, April 2016, 3745 . 3747 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 3748 CRIME Attack", 12 July 2013, 3749 . 3752 [DNS-TERMS] 3753 Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 3754 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 3755 January 2019, . 3757 [HTTP11] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3758 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 3759 ietf-httpbis-messaging-15, 30 March 2021, 3760 . 3763 [I-D.ietf-httpbis-priority] 3764 Oku, K. and L. Pardue, "Extensible Prioritization Scheme 3765 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 3766 httpbis-priority-03, 11 January 2021, 3767 . 3770 [NFLX-2019-002] 3771 Netflix, "HTTP/2 Denial of Service Advisory", 13 August 3772 2019, . 3775 [PRIVACY] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 3776 Morris, J., Hansen, M., and R. Smith, "Privacy 3777 Considerations for Internet Protocols", RFC 6973, 3778 DOI 10.17487/RFC6973, July 2013, 3779 . 3781 [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol 3782 Compression Methods", RFC 3749, May 2004, 3783 . 3785 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 3786 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 3787 for Transport Layer Security (TLS)", RFC 4492, May 2006, 3788 . 3790 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 3791 Codes", RFC 6585, April 2012, 3792 . 3794 [RFC7323] Borman, D., Braden, B., Jacobson, V., and R. 3795 Scheffenegger, Ed., "TCP Extensions for High Performance", 3796 RFC 7323, September 2014, 3797 . 3799 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 3800 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 3801 DOI 10.17487/RFC7540, May 2015, 3802 . 3804 [RFC8740] Benjamin, D., "Using TLS 1.3 with HTTP/2", RFC 8740, 3805 DOI 10.17487/RFC8740, February 2020, 3806 . 3808 [TALKING] Huang, L., Chen, E., Barth, A., Rescorla, E., and C. 3809 Jackson, "Talking to Yourself for Fun and Profit", 2011, 3810 . 3812 [TLSBCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 3813 "Recommendations for Secure Use of Transport Layer 3814 Security (TLS) and Datagram Transport Layer Security 3815 (DTLS)", BCP 195, RFC 7525, May 2015, 3816 . 3818 Appendix A. Prohibited TLS 1.2 Cipher Suites 3820 An HTTP/2 implementation MAY treat the negotiation of any of the 3821 following cipher suites with TLS 1.2 as a connection error 3822 (Section 5.4.1) of type INADEQUATE_SECURITY: 3824 * TLS_NULL_WITH_NULL_NULL 3825 * TLS_RSA_WITH_NULL_MD5 3826 * TLS_RSA_WITH_NULL_SHA 3827 * TLS_RSA_EXPORT_WITH_RC4_40_MD5 3828 * TLS_RSA_WITH_RC4_128_MD5 3829 * TLS_RSA_WITH_RC4_128_SHA 3830 * TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 3831 * TLS_RSA_WITH_IDEA_CBC_SHA 3832 * TLS_RSA_EXPORT_WITH_DES40_CBC_SHA 3833 * TLS_RSA_WITH_DES_CBC_SHA 3834 * TLS_RSA_WITH_3DES_EDE_CBC_SHA 3835 * TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA 3836 * TLS_DH_DSS_WITH_DES_CBC_SHA 3837 * TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 3838 * TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA 3839 * TLS_DH_RSA_WITH_DES_CBC_SHA 3840 * TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 3841 * TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA 3842 * TLS_DHE_DSS_WITH_DES_CBC_SHA 3843 * TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 3844 * TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA 3845 * TLS_DHE_RSA_WITH_DES_CBC_SHA 3846 * TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 3847 * TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 3848 * TLS_DH_anon_WITH_RC4_128_MD5 3849 * TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA 3850 * TLS_DH_anon_WITH_DES_CBC_SHA 3851 * TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 3852 * TLS_KRB5_WITH_DES_CBC_SHA 3853 * TLS_KRB5_WITH_3DES_EDE_CBC_SHA 3854 * TLS_KRB5_WITH_RC4_128_SHA 3855 * TLS_KRB5_WITH_IDEA_CBC_SHA 3856 * TLS_KRB5_WITH_DES_CBC_MD5 3857 * TLS_KRB5_WITH_3DES_EDE_CBC_MD5 3858 * TLS_KRB5_WITH_RC4_128_MD5 3859 * TLS_KRB5_WITH_IDEA_CBC_MD5 3860 * TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA 3861 * TLS_KRB5_EXPORT_WITH_RC2_CBC_40_SHA 3862 * TLS_KRB5_EXPORT_WITH_RC4_40_SHA 3863 * TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5 3864 * TLS_KRB5_EXPORT_WITH_RC2_CBC_40_MD5 3865 * TLS_KRB5_EXPORT_WITH_RC4_40_MD5 3866 * TLS_PSK_WITH_NULL_SHA 3867 * TLS_DHE_PSK_WITH_NULL_SHA 3868 * TLS_RSA_PSK_WITH_NULL_SHA 3869 * TLS_RSA_WITH_AES_128_CBC_SHA 3870 * TLS_DH_DSS_WITH_AES_128_CBC_SHA 3871 * TLS_DH_RSA_WITH_AES_128_CBC_SHA 3872 * TLS_DHE_DSS_WITH_AES_128_CBC_SHA 3873 * TLS_DHE_RSA_WITH_AES_128_CBC_SHA 3874 * TLS_DH_anon_WITH_AES_128_CBC_SHA 3875 * TLS_RSA_WITH_AES_256_CBC_SHA 3876 * TLS_DH_DSS_WITH_AES_256_CBC_SHA 3877 * TLS_DH_RSA_WITH_AES_256_CBC_SHA 3878 * TLS_DHE_DSS_WITH_AES_256_CBC_SHA 3879 * TLS_DHE_RSA_WITH_AES_256_CBC_SHA 3880 * TLS_DH_anon_WITH_AES_256_CBC_SHA 3881 * TLS_RSA_WITH_NULL_SHA256 3882 * TLS_RSA_WITH_AES_128_CBC_SHA256 3883 * TLS_RSA_WITH_AES_256_CBC_SHA256 3884 * TLS_DH_DSS_WITH_AES_128_CBC_SHA256 3885 * TLS_DH_RSA_WITH_AES_128_CBC_SHA256 3886 * TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 3887 * TLS_RSA_WITH_CAMELLIA_128_CBC_SHA 3888 * TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA 3889 * TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA 3890 * TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA 3891 * TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA 3892 * TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA 3893 * TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 3894 * TLS_DH_DSS_WITH_AES_256_CBC_SHA256 3895 * TLS_DH_RSA_WITH_AES_256_CBC_SHA256 3896 * TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 3897 * TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 3898 * TLS_DH_anon_WITH_AES_128_CBC_SHA256 3899 * TLS_DH_anon_WITH_AES_256_CBC_SHA256 3900 * TLS_RSA_WITH_CAMELLIA_256_CBC_SHA 3901 * TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA 3902 * TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA 3903 * TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA 3904 * TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA 3905 * TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA 3906 * TLS_PSK_WITH_RC4_128_SHA 3907 * TLS_PSK_WITH_3DES_EDE_CBC_SHA 3908 * TLS_PSK_WITH_AES_128_CBC_SHA 3909 * TLS_PSK_WITH_AES_256_CBC_SHA 3910 * TLS_DHE_PSK_WITH_RC4_128_SHA 3911 * TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA 3912 * TLS_DHE_PSK_WITH_AES_128_CBC_SHA 3913 * TLS_DHE_PSK_WITH_AES_256_CBC_SHA 3914 * TLS_RSA_PSK_WITH_RC4_128_SHA 3915 * TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA 3916 * TLS_RSA_PSK_WITH_AES_128_CBC_SHA 3917 * TLS_RSA_PSK_WITH_AES_256_CBC_SHA 3918 * TLS_RSA_WITH_SEED_CBC_SHA 3919 * TLS_DH_DSS_WITH_SEED_CBC_SHA 3920 * TLS_DH_RSA_WITH_SEED_CBC_SHA 3921 * TLS_DHE_DSS_WITH_SEED_CBC_SHA 3922 * TLS_DHE_RSA_WITH_SEED_CBC_SHA 3923 * TLS_DH_anon_WITH_SEED_CBC_SHA 3924 * TLS_RSA_WITH_AES_128_GCM_SHA256 3925 * TLS_RSA_WITH_AES_256_GCM_SHA384 3926 * TLS_DH_RSA_WITH_AES_128_GCM_SHA256 3927 * TLS_DH_RSA_WITH_AES_256_GCM_SHA384 3928 * TLS_DH_DSS_WITH_AES_128_GCM_SHA256 3929 * TLS_DH_DSS_WITH_AES_256_GCM_SHA384 3930 * TLS_DH_anon_WITH_AES_128_GCM_SHA256 3931 * TLS_DH_anon_WITH_AES_256_GCM_SHA384 3932 * TLS_PSK_WITH_AES_128_GCM_SHA256 3933 * TLS_PSK_WITH_AES_256_GCM_SHA384 3934 * TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 3935 * TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 3936 * TLS_PSK_WITH_AES_128_CBC_SHA256 3937 * TLS_PSK_WITH_AES_256_CBC_SHA384 3938 * TLS_PSK_WITH_NULL_SHA256 3939 * TLS_PSK_WITH_NULL_SHA384 3940 * TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 3941 * TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 3942 * TLS_DHE_PSK_WITH_NULL_SHA256 3943 * TLS_DHE_PSK_WITH_NULL_SHA384 3944 * TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 3945 * TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 3946 * TLS_RSA_PSK_WITH_NULL_SHA256 3947 * TLS_RSA_PSK_WITH_NULL_SHA384 3948 * TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 3949 * TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA256 3950 * TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA256 3951 * TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA256 3952 * TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 3953 * TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA256 3954 * TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 3955 * TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA256 3956 * TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA256 3957 * TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA256 3958 * TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 3959 * TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA256 3960 * TLS_EMPTY_RENEGOTIATION_INFO_SCSV 3961 * TLS_ECDH_ECDSA_WITH_NULL_SHA 3962 * TLS_ECDH_ECDSA_WITH_RC4_128_SHA 3963 * TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 3964 * TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 3965 * TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 3966 * TLS_ECDHE_ECDSA_WITH_NULL_SHA 3967 * TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 3968 * TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 3969 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 3970 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 3971 * TLS_ECDH_RSA_WITH_NULL_SHA 3972 * TLS_ECDH_RSA_WITH_RC4_128_SHA 3973 * TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 3974 * TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 3975 * TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 3976 * TLS_ECDHE_RSA_WITH_NULL_SHA 3977 * TLS_ECDHE_RSA_WITH_RC4_128_SHA 3978 * TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 3979 * TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 3980 * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 3981 * TLS_ECDH_anon_WITH_NULL_SHA 3982 * TLS_ECDH_anon_WITH_RC4_128_SHA 3983 * TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 3984 * TLS_ECDH_anon_WITH_AES_128_CBC_SHA 3985 * TLS_ECDH_anon_WITH_AES_256_CBC_SHA 3986 * TLS_SRP_SHA_WITH_3DES_EDE_CBC_SHA 3987 * TLS_SRP_SHA_RSA_WITH_3DES_EDE_CBC_SHA 3988 * TLS_SRP_SHA_DSS_WITH_3DES_EDE_CBC_SHA 3989 * TLS_SRP_SHA_WITH_AES_128_CBC_SHA 3990 * TLS_SRP_SHA_RSA_WITH_AES_128_CBC_SHA 3991 * TLS_SRP_SHA_DSS_WITH_AES_128_CBC_SHA 3992 * TLS_SRP_SHA_WITH_AES_256_CBC_SHA 3993 * TLS_SRP_SHA_RSA_WITH_AES_256_CBC_SHA 3994 * TLS_SRP_SHA_DSS_WITH_AES_256_CBC_SHA 3995 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 3996 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 3997 * TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 3998 * TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 3999 * TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 4000 * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 4001 * TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 4002 * TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 4003 * TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 4004 * TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 4005 * TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 4006 * TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 4007 * TLS_ECDHE_PSK_WITH_RC4_128_SHA 4008 * TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA 4009 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA 4010 * TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA 4011 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 4012 * TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 4013 * TLS_ECDHE_PSK_WITH_NULL_SHA 4014 * TLS_ECDHE_PSK_WITH_NULL_SHA256 4015 * TLS_ECDHE_PSK_WITH_NULL_SHA384 4016 * TLS_RSA_WITH_ARIA_128_CBC_SHA256 4017 * TLS_RSA_WITH_ARIA_256_CBC_SHA384 4018 * TLS_DH_DSS_WITH_ARIA_128_CBC_SHA256 4019 * TLS_DH_DSS_WITH_ARIA_256_CBC_SHA384 4020 * TLS_DH_RSA_WITH_ARIA_128_CBC_SHA256 4021 * TLS_DH_RSA_WITH_ARIA_256_CBC_SHA384 4022 * TLS_DHE_DSS_WITH_ARIA_128_CBC_SHA256 4023 * TLS_DHE_DSS_WITH_ARIA_256_CBC_SHA384 4024 * TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256 4025 * TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384 4026 * TLS_DH_anon_WITH_ARIA_128_CBC_SHA256 4027 * TLS_DH_anon_WITH_ARIA_256_CBC_SHA384 4028 * TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256 4029 * TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384 4030 * TLS_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256 4031 * TLS_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384 4032 * TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256 4033 * TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384 4034 * TLS_ECDH_RSA_WITH_ARIA_128_CBC_SHA256 4035 * TLS_ECDH_RSA_WITH_ARIA_256_CBC_SHA384 4036 * TLS_RSA_WITH_ARIA_128_GCM_SHA256 4037 * TLS_RSA_WITH_ARIA_256_GCM_SHA384 4038 * TLS_DH_RSA_WITH_ARIA_128_GCM_SHA256 4039 * TLS_DH_RSA_WITH_ARIA_256_GCM_SHA384 4040 * TLS_DH_DSS_WITH_ARIA_128_GCM_SHA256 4041 * TLS_DH_DSS_WITH_ARIA_256_GCM_SHA384 4042 * TLS_DH_anon_WITH_ARIA_128_GCM_SHA256 4043 * TLS_DH_anon_WITH_ARIA_256_GCM_SHA384 4044 * TLS_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256 4045 * TLS_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384 4046 * TLS_ECDH_RSA_WITH_ARIA_128_GCM_SHA256 4047 * TLS_ECDH_RSA_WITH_ARIA_256_GCM_SHA384 4048 * TLS_PSK_WITH_ARIA_128_CBC_SHA256 4049 * TLS_PSK_WITH_ARIA_256_CBC_SHA384 4050 * TLS_DHE_PSK_WITH_ARIA_128_CBC_SHA256 4051 * TLS_DHE_PSK_WITH_ARIA_256_CBC_SHA384 4052 * TLS_RSA_PSK_WITH_ARIA_128_CBC_SHA256 4053 * TLS_RSA_PSK_WITH_ARIA_256_CBC_SHA384 4054 * TLS_PSK_WITH_ARIA_128_GCM_SHA256 4055 * TLS_PSK_WITH_ARIA_256_GCM_SHA384 4056 * TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256 4057 * TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384 4058 * TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256 4059 * TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384 4060 * TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 4061 * TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 4062 * TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 4063 * TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 4064 * TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 4065 * TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 4066 * TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256 4067 * TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384 4068 * TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256 4069 * TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384 4070 * TLS_DH_RSA_WITH_CAMELLIA_128_GCM_SHA256 4071 * TLS_DH_RSA_WITH_CAMELLIA_256_GCM_SHA384 4072 * TLS_DH_DSS_WITH_CAMELLIA_128_GCM_SHA256 4073 * TLS_DH_DSS_WITH_CAMELLIA_256_GCM_SHA384 4074 * TLS_DH_anon_WITH_CAMELLIA_128_GCM_SHA256 4075 * TLS_DH_anon_WITH_CAMELLIA_256_GCM_SHA384 4076 * TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 4077 * TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 4078 * TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256 4079 * TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384 4080 * TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 4081 * TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 4082 * TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256 4083 * TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384 4084 * TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256 4085 * TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 4086 * TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 4087 * TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 4088 * TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 4089 * TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 4090 * TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 4091 * TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 4092 * TLS_RSA_WITH_AES_128_CCM 4093 * TLS_RSA_WITH_AES_256_CCM 4094 * TLS_RSA_WITH_AES_128_CCM_8 4095 * TLS_RSA_WITH_AES_256_CCM_8 4096 * TLS_PSK_WITH_AES_128_CCM 4097 * TLS_PSK_WITH_AES_256_CCM 4098 * TLS_PSK_WITH_AES_128_CCM_8 4099 * TLS_PSK_WITH_AES_256_CCM_8 4100 | Note: This list was assembled from the set of registered TLS 4101 | cipher suites at the time of writing. This list includes those 4102 | cipher suites that do not offer an ephemeral key exchange and 4103 | those that are based on the TLS null, stream, or block cipher 4104 | type (as defined in Section 6.2.3 of [TLS12]). Additional 4105 | cipher suites with these properties could be defined; these 4106 | would not be explicitly prohibited. 4108 Appendix B. Changes from RFC 7540 4110 This revision includes a number of editorial updates, plus the 4111 following substantive changes: 4113 * Use of TLS 1.3 is defined based on RFC 8740, which this document 4114 obsoletes. 4116 * The priority scheme defined in RFC 7540 is deprecated. 4117 Definitions for the format of the PRIORITY frame and the priority 4118 fields in the HEADERS frame have been retained, plus the rules 4119 governing when PRIORITY frames can be sent and received, but the 4120 semantics of these fields is only described in RFC 7540. The 4121 priority signaling scheme from RFC 7540 was not successful. Using 4122 the simpler successor signaling [I-D.ietf-httpbis-priority] is 4123 recommended. 4125 * The HTTP/1.1 Upgrade mechanism is no longer specified in this 4126 document. It was never widely deployed, with plaintext HTTP/2 4127 users choosing to use the prior-knowledge implementation instead. 4129 * Validation for field names and values has been narrowed. The 4130 validation that is mandatory for intermediaries is precisely 4131 defined and error reporting for requests has been amended to 4132 encourage sending 400-series status codes. 4134 * The ranges of codepoints for settings and frame types that were 4135 reserved for "Experimental Use" are now available for general use. 4137 Contributors 4139 The previous version of this document was authored by Mike Belshe and 4140 Roberto Peon. 4142 Acknowledgments 4144 Credit for non-trivial input to this document is owed to a large 4145 number of people who have contributed to the HTTP working group over 4146 the years. [RFC7540] contains a more extensive list of people that 4147 deserve acknowledgment for their contributions. 4149 Authors' Addresses 4151 Martin Thomson (editor) 4152 Mozilla 4153 Australia 4155 Email: mt@lowentropy.net 4157 Cory Benfield (editor) 4158 Apple Inc. 4160 Email: cbenfield@apple.com