idnits 2.17.1 draft-ietf-httpbis-http2bis-01.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 mention this, which it should. -- The draft header indicates that this document obsoletes RFC7540, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (22 February 2021) is 1158 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-14 -- 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-14 -- Possible downref: Normative reference to a draft: ref. 'HTTP' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-14 -- Possible downref: Normative reference to a draft: ref. 'HTTP11' ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** 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) -- Obsolete informational reference (is this intentional?): RFC 4492 (Obsoleted by RFC 8422) -- Obsolete informational reference (is this intentional?): RFC 7525 (ref. 'TLSBCP') (Obsoleted by RFC 9325) Summary: 3 errors (**), 0 flaws (~~), 4 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: 26 August 2021 22 February 2021 8 Hypertext Transfer Protocol Version 2 (HTTP/2) 9 draft-ietf-httpbis-http2bis-01 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. It also introduces unsolicited push of 19 representations from servers to clients. 21 This specification is an alternative to, but does not obsolete, the 22 HTTP/1.1 message syntax. HTTP's existing semantics remain unchanged. 24 Discussion Venues 26 Discussion of this document takes place on the HTTPBIS Working Group 27 mailing list (ietf-http-wg@w3.org), which is archived at 28 https://lists.w3.org/Archives/Public/ietf-http-wg/. 30 This note is to be removed before publishing as an RFC. 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 26 August 2021. 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 . . . . . . . . . . . . . . 7 73 3.2. Starting HTTP/2 for "http" URIs . . . . . . . . . . . . . 8 74 3.2.1. HTTP2-Settings Header Field . . . . . . . . . . . . . 9 75 3.3. Starting HTTP/2 for "https" URIs . . . . . . . . . . . . 10 76 3.4. Starting HTTP/2 with Prior Knowledge . . . . . . . . . . 10 77 3.5. HTTP/2 Connection Preface . . . . . . . . . . . . . . . . 11 78 4. HTTP Frames . . . . . . . . . . . . . . . . . . . . . . . . . 12 79 4.1. Frame Format . . . . . . . . . . . . . . . . . . . . . . 12 80 4.2. Frame Size . . . . . . . . . . . . . . . . . . . . . . . 13 81 4.3. Field Section Compression and Decompression . . . . . . . 14 82 5. Streams and Multiplexing . . . . . . . . . . . . . . . . . . 15 83 5.1. Stream States . . . . . . . . . . . . . . . . . . . . . . 16 84 5.1.1. Stream Identifiers . . . . . . . . . . . . . . . . . 21 85 5.1.2. Stream Concurrency . . . . . . . . . . . . . . . . . 22 86 5.2. Flow Control . . . . . . . . . . . . . . . . . . . . . . 22 87 5.2.1. Flow-Control Principles . . . . . . . . . . . . . . . 23 88 5.2.2. Appropriate Use of Flow Control . . . . . . . . . . . 24 89 5.3. Stream Priority . . . . . . . . . . . . . . . . . . . . . 24 90 5.3.1. Stream Dependencies . . . . . . . . . . . . . . . . . 25 91 5.3.2. Dependency Weighting . . . . . . . . . . . . . . . . 26 92 5.3.3. Reprioritization . . . . . . . . . . . . . . . . . . 26 93 5.3.4. Prioritization State Management . . . . . . . . . . . 27 94 5.3.5. Default Priorities . . . . . . . . . . . . . . . . . 29 95 5.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 29 96 5.4.1. Connection Error Handling . . . . . . . . . . . . . . 29 97 5.4.2. Stream Error Handling . . . . . . . . . . . . . . . . 30 98 5.4.3. Connection Termination . . . . . . . . . . . . . . . 30 99 5.5. Extending HTTP/2 . . . . . . . . . . . . . . . . . . . . 30 100 6. Frame Definitions . . . . . . . . . . . . . . . . . . . . . . 32 101 6.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . 32 102 6.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . . . 33 103 6.3. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . 35 104 6.4. RST_STREAM . . . . . . . . . . . . . . . . . . . . . . . 37 105 6.5. SETTINGS . . . . . . . . . . . . . . . . . . . . . . . . 37 106 6.5.1. SETTINGS Format . . . . . . . . . . . . . . . . . . . 38 107 6.5.2. Defined SETTINGS Parameters . . . . . . . . . . . . . 39 108 6.5.3. Settings Synchronization . . . . . . . . . . . . . . 40 109 6.6. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . . . 41 110 6.7. PING . . . . . . . . . . . . . . . . . . . . . . . . . . 43 111 6.8. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . . . 44 112 6.9. WINDOW_UPDATE . . . . . . . . . . . . . . . . . . . . . . 46 113 6.9.1. The Flow-Control Window . . . . . . . . . . . . . . . 48 114 6.9.2. Initial Flow-Control Window Size . . . . . . . . . . 49 115 6.9.3. Reducing the Stream Window Size . . . . . . . . . . . 50 116 6.10. CONTINUATION . . . . . . . . . . . . . . . . . . . . . . 50 117 7. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 51 118 8. HTTP Message Exchanges . . . . . . . . . . . . . . . . . . . 52 119 8.1. HTTP Message Framing . . . . . . . . . . . . . . . . . . 52 120 8.1.1. Upgrading from HTTP/2 . . . . . . . . . . . . . . . . 54 121 8.1.2. HTTP Fields . . . . . . . . . . . . . . . . . . . . . 54 122 8.1.3. Examples . . . . . . . . . . . . . . . . . . . . . . 58 123 8.1.4. Request Reliability Mechanisms in HTTP/2 . . . . . . 60 124 8.2. Server Push . . . . . . . . . . . . . . . . . . . . . . . 61 125 8.2.1. Push Requests . . . . . . . . . . . . . . . . . . . . 62 126 8.2.2. Push Responses . . . . . . . . . . . . . . . . . . . 63 127 8.3. The CONNECT Method . . . . . . . . . . . . . . . . . . . 64 128 9. Additional HTTP Requirements/Considerations . . . . . . . . . 65 129 9.1. Connection Management . . . . . . . . . . . . . . . . . . 66 130 9.1.1. Connection Reuse . . . . . . . . . . . . . . . . . . 66 131 9.2. Use of TLS Features . . . . . . . . . . . . . . . . . . . 67 132 9.2.1. TLS 1.2 Features . . . . . . . . . . . . . . . . . . 67 133 9.2.2. TLS 1.2 Cipher Suites . . . . . . . . . . . . . . . . 68 134 9.2.3. TLS 1.3 Features . . . . . . . . . . . . . . . . . . 69 135 10. Security Considerations . . . . . . . . . . . . . . . . . . . 69 136 10.1. Server Authority . . . . . . . . . . . . . . . . . . . . 70 137 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 70 138 10.3. Intermediary Encapsulation Attacks . . . . . . . . . . . 70 139 10.4. Cacheability of Pushed Responses . . . . . . . . . . . . 71 140 10.5. Denial-of-Service Considerations . . . . . . . . . . . . 71 141 10.5.1. Limits on Field Block Size . . . . . . . . . . . . . 73 142 10.5.2. CONNECT Issues . . . . . . . . . . . . . . . . . . . 73 143 10.6. Use of Compression . . . . . . . . . . . . . . . . . . . 74 144 10.7. Use of Padding . . . . . . . . . . . . . . . . . . . . . 74 145 10.8. Privacy Considerations . . . . . . . . . . . . . . . . . 75 146 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75 147 11.1. Registration of HTTP/2 Identification Strings . . . . . 75 148 11.2. Frame Type Registry . . . . . . . . . . . . . . . . . . 76 149 11.3. Settings Registry . . . . . . . . . . . . . . . . . . . 77 150 11.4. Error Code Registry . . . . . . . . . . . . . . . . . . 78 151 11.5. HTTP2-Settings Header Field Registration . . . . . . . . 80 152 11.6. PRI Method Registration . . . . . . . . . . . . . . . . 80 153 11.7. The h2c Upgrade Token . . . . . . . . . . . . . . . . . 80 154 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 81 155 12.1. Normative References . . . . . . . . . . . . . . . . . . 81 156 12.2. Informative References . . . . . . . . . . . . . . . . . 82 157 Appendix A. Prohibited TLS 1.2 Cipher Suites . . . . . . . . . . 84 158 Appendix B. Changes from RFC 7540 . . . . . . . . . . . . . . . 90 159 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 90 160 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 90 161 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 91 163 1. Introduction 165 The Hypertext Transfer Protocol (HTTP) is a wildly successful 166 protocol. However, the way HTTP/1.1 uses the underlying transport 167 ([HTTP11]) has several characteristics that have a negative overall 168 effect on application performance today. 170 In particular, HTTP/1.0 allowed only one request to be outstanding at 171 a time on a given TCP connection. HTTP/1.1 added request pipelining, 172 but this only partially addressed request concurrency and still 173 suffers from head-of-line blocking. Therefore, HTTP/1.0 and HTTP/1.1 174 clients that need to make many requests use multiple connections to a 175 server in order to achieve concurrency and thereby reduce latency. 177 Furthermore, HTTP header fields are often repetitive and verbose, 178 causing unnecessary network traffic as well as causing the initial 179 TCP [TCP] congestion window to quickly fill. This can result in 180 excessive latency when multiple requests are made on a new TCP 181 connection. 183 HTTP/2 addresses these issues by defining an optimized mapping of 184 HTTP's semantics to an underlying connection. Specifically, it 185 allows interleaving of request and response messages on the same 186 connection and uses an efficient coding for HTTP header fields. It 187 also allows prioritization of requests, letting more important 188 requests complete more quickly, further improving performance. 190 The resulting protocol is more friendly to the network because fewer 191 TCP connections can be used in comparison to HTTP/1.x. This means 192 less competition with other flows and longer-lived connections, which 193 in turn lead to better utilization of available network capacity. 195 Finally, HTTP/2 also enables more efficient processing of messages 196 through use of binary message framing. 198 2. HTTP/2 Protocol Overview 200 HTTP/2 provides an optimized transport for HTTP semantics. HTTP/2 201 supports all of the core features of HTTP but aims to be more 202 efficient than HTTP/1.1. 204 The basic protocol unit in HTTP/2 is a frame (Section 4.1). Each 205 frame type serves a different purpose. For example, HEADERS and DATA 206 frames form the basis of HTTP requests and responses (Section 8.1); 207 other frame types like SETTINGS, WINDOW_UPDATE, and PUSH_PROMISE are 208 used in support of other HTTP/2 features. 210 Multiplexing of requests is achieved by having each HTTP request/ 211 response exchange associated with its own stream (Section 5). 212 Streams are largely independent of each other, so a blocked or 213 stalled request or response does not prevent progress on other 214 streams. 216 Flow control and prioritization ensure that it is possible to 217 efficiently use multiplexed streams. Flow control (Section 5.2) 218 helps to ensure that only data that can be used by a receiver is 219 transmitted. Prioritization (Section 5.3) ensures that limited 220 resources can be directed to the most important streams first. 222 HTTP/2 adds a new interaction mode whereby a server can push 223 responses to a client (Section 8.2). Server push allows a server to 224 speculatively send data to a client that the server anticipates the 225 client will need, trading off some network usage against a potential 226 latency gain. The server does this by synthesizing a request, which 227 it sends as a PUSH_PROMISE frame. The server is then able to send a 228 response to the synthetic request on a separate stream. 230 Because HTTP header fields used in a connection can contain large 231 amounts of redundant data, frames that contain them are compressed 232 (Section 4.3). This has especially advantageous impact upon request 233 sizes in the common case, allowing many requests to be compressed 234 into one packet. 236 2.1. Document Organization 238 The HTTP/2 specification is split into four parts: 240 * Starting HTTP/2 (Section 3) covers how an HTTP/2 connection is 241 initiated. 243 * The frame (Section 4) and stream (Section 5) layers describe the 244 way HTTP/2 frames are structured and formed into multiplexed 245 streams. 247 * Frame (Section 6) and error (Section 7) definitions include 248 details of the frame and error types used in HTTP/2. 250 * HTTP mappings (Section 8) and additional requirements (Section 9) 251 describe how HTTP semantics are expressed using frames and 252 streams. 254 While some of the frame and stream layer concepts are isolated from 255 HTTP, this specification does not define a completely generic frame 256 layer. The frame and stream layers are tailored to the needs of the 257 HTTP protocol and server push. 259 2.2. Conventions and Terminology 261 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 262 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 263 document are to be interpreted as described in RFC 2119 [RFC2119]. 265 All numeric values are in network byte order. Values are unsigned 266 unless otherwise indicated. Literal values are provided in decimal 267 or hexadecimal as appropriate. Hexadecimal literals are prefixed 268 with "0x" to distinguish them from decimal literals. 270 The following terms are used: 272 client: The endpoint that initiates an HTTP/2 connection. Clients 273 send HTTP requests and receive HTTP responses. 275 connection: A transport-layer connection between two endpoints. 277 connection error: An error that affects the entire HTTP/2 278 connection. 280 endpoint: Either the client or server of the connection. 282 frame: The smallest unit of communication within an HTTP/2 283 connection, consisting of a header and a variable-length sequence 284 of octets structured according to the frame type. 286 peer: An endpoint. When discussing a particular endpoint, "peer" 287 refers to the endpoint that is remote to the primary subject of 288 discussion. 290 receiver: An endpoint that is receiving frames. 292 sender: An endpoint that is transmitting frames. 294 server: The endpoint that accepts an HTTP/2 connection. Servers 295 receive HTTP requests and send HTTP responses. 297 stream: A bidirectional flow of frames within the HTTP/2 connection. 299 stream error: An error on the individual HTTP/2 stream. 301 Finally, the terms "gateway", "intermediary", "proxy", and "tunnel" 302 are defined in Section 3.7 of [HTTP]. Intermediaries act as both 303 client and server at different times. 305 The term "content" as it applies to message bodies is defined in 306 Section 6.4 of [HTTP]. 308 3. Starting HTTP/2 310 An HTTP/2 connection is an application-layer protocol running on top 311 of a TCP connection ([TCP]). The client is the TCP connection 312 initiator. 314 HTTP/2 uses the "http" and "https" URI schemes defined in Section 4.2 315 of [HTTP]. HTTP/2 shares the same default port numbers: 80 for 316 "http" URIs and 443 for "https" URIs. As a result, implementations 317 processing requests for target resource URIs like 318 "http://example.org/foo" or "https://example.com/bar" are required to 319 first discover whether the upstream server (the immediate peer to 320 which the client wishes to establish a connection) supports HTTP/2. 322 The means by which support for HTTP/2 is determined is different for 323 "http" and "https" URIs. Discovery for "http" URIs is described in 324 Section 3.2. Discovery for "https" URIs is described in Section 3.3. 326 3.1. HTTP/2 Version Identification 328 The protocol defined in this document has two identifiers. 330 * The string "h2" identifies the protocol where HTTP/2 uses 331 Transport Layer Security (TLS) [TLS13]. This identifier is used 332 in the TLS application-layer protocol negotiation (ALPN) extension 333 [TLS-ALPN] field and in any place where HTTP/2 over TLS is 334 identified. 336 The "h2" string is serialized into an ALPN protocol identifier as 337 the two-octet sequence: 0x68, 0x32. 339 * The string "h2c" identifies the protocol where HTTP/2 is run over 340 cleartext TCP. This identifier is used in the HTTP/1.1 Upgrade 341 header field and in any place where HTTP/2 over TCP is identified. 343 The "h2c" string is reserved from the ALPN identifier space but 344 describes a protocol that does not use TLS. 346 Negotiating "h2" or "h2c" implies the use of the transport, security, 347 framing, and message semantics described in this document. 349 3.2. Starting HTTP/2 for "http" URIs 351 A client that makes a request for an "http" URI without prior 352 knowledge about support for HTTP/2 on the next hop uses the HTTP 353 Upgrade mechanism (Section 7.8 of [HTTP]). The client does so by 354 making an HTTP/1.1 request that includes an Upgrade header field with 355 the "h2c" token. Such an HTTP/1.1 request MUST include exactly one 356 HTTP2-Settings (Section 3.2.1) header field. 358 For example: 360 GET / HTTP/1.1 361 Host: server.example.com 362 Connection: Upgrade, HTTP2-Settings 363 Upgrade: h2c 364 HTTP2-Settings: 366 Requests that contain message content MUST be sent in their entirety 367 before the client can send HTTP/2 frames. This means that a large 368 request can block the use of the connection until it is completely 369 sent. 371 If concurrency of an initial request with subsequent requests is 372 important, an OPTIONS request can be used to perform the upgrade to 373 HTTP/2, at the cost of an additional round trip. 375 A server that does not support HTTP/2 can respond to the request as 376 though the Upgrade header field were absent: 378 HTTP/1.1 200 OK 379 Content-Length: 243 380 Content-Type: text/html 382 ... 384 A server MUST ignore an "h2" token in an Upgrade header field. 385 Presence of a token with "h2" implies HTTP/2 over TLS, which is 386 instead negotiated as described in Section 3.3. 388 A server that supports HTTP/2 accepts the upgrade with a 101 389 (Switching Protocols) response. After the empty line that terminates 390 the 101 response, the server can begin sending HTTP/2 frames. These 391 frames MUST include a response to the request that initiated the 392 upgrade. 394 For example: 396 HTTP/1.1 101 Switching Protocols 397 Connection: Upgrade 398 Upgrade: h2c 400 [ HTTP/2 connection ... 402 The first HTTP/2 frame sent by the server MUST be a server connection 403 preface (Section 3.5) consisting of a SETTINGS frame (Section 6.5). 404 Upon receiving the 101 response, the client MUST send a connection 405 preface (Section 3.5), which includes a SETTINGS frame. 407 The HTTP/1.1 request that is sent prior to upgrade is assigned a 408 stream identifier of 1 (see Section 5.1.1) with default priority 409 values (Section 5.3.5). Stream 1 is implicitly "half-closed" from 410 the client toward the server (see Section 5.1), since the request is 411 completed as an HTTP/1.1 request. After commencing the HTTP/2 412 connection, stream 1 is used for the response. 414 3.2.1. HTTP2-Settings Header Field 416 A request that upgrades from HTTP/1.1 to HTTP/2 MUST include exactly 417 one "HTTP2-Settings" header field. The "HTTP2-Settings" header field 418 is a connection-specific header field that includes parameters that 419 govern the HTTP/2 connection, provided in anticipation of the server 420 accepting the request to upgrade. 422 HTTP2-Settings = token68 424 A server MUST NOT upgrade the connection to HTTP/2 if this header 425 field is not present or if more than one is present. A server MUST 426 NOT send this header field. 428 The content of the "HTTP2-Settings" header field is the frame payload 429 of a SETTINGS frame (Section 6.5), encoded as a base64url string 430 (that is, the URL- and filename-safe Base64 encoding described in 431 Section 5 of [RFC4648], with any trailing '=' characters omitted). 432 The ABNF [RFC5234] production for "token68" is defined in 433 Section 11.2 of [HTTP]. 435 Since the upgrade is only intended to apply to the immediate 436 connection, a client sending the "HTTP2-Settings" header field MUST 437 also send "HTTP2-Settings" as a connection option in the "Connection" 438 header field to prevent it from being forwarded (see Section 7.6.1 of 439 [HTTP]). 441 A server decodes and interprets these values as it would any other 442 SETTINGS frame. Explicit acknowledgement of these settings 443 (Section 6.5.3) is not necessary, since a 101 response serves as 444 implicit acknowledgement. Providing these values in the upgrade 445 request gives a client an opportunity to provide parameters prior to 446 receiving any frames from the server. 448 3.3. Starting HTTP/2 for "https" URIs 450 A client that makes a request to an "https" URI uses TLS [TLS13] with 451 the application-layer protocol negotiation (ALPN) extension 452 [TLS-ALPN]. 454 HTTP/2 over TLS uses the "h2" protocol identifier. The "h2c" 455 protocol identifier MUST NOT be sent by a client or selected by a 456 server; the "h2c" protocol identifier describes a protocol that does 457 not use TLS. 459 Once TLS negotiation is complete, both the client and the server MUST 460 send a connection preface (Section 3.5). 462 3.4. Starting HTTP/2 with Prior Knowledge 464 A client can learn that a particular server supports HTTP/2 by other 465 means. For example, [ALT-SVC] describes a mechanism for advertising 466 this capability. 468 A client MUST send the connection preface (Section 3.5) and then MAY 469 immediately send HTTP/2 frames to such a server; servers can identify 470 these connections by the presence of the connection preface. This 471 only affects the establishment of HTTP/2 connections over cleartext 472 TCP; implementations that support HTTP/2 over TLS MUST use protocol 473 negotiation in TLS [TLS-ALPN]. 475 Likewise, the server MUST send a connection preface (Section 3.5). 477 Without additional information, prior support for HTTP/2 is not a 478 strong signal that a given server will support HTTP/2 for future 479 connections. For example, it is possible for server configurations 480 to change, for configurations to differ between instances in 481 clustered servers, or for network conditions to change. 483 3.5. HTTP/2 Connection Preface 485 In HTTP/2, each endpoint is required to send a connection preface as 486 a final confirmation of the protocol in use and to establish the 487 initial settings for the HTTP/2 connection. The client and server 488 each send a different connection preface. 490 The client connection preface starts with a sequence of 24 octets, 491 which in hex notation is: 493 0x505249202a20485454502f322e300d0a0d0a534d0d0a0d0a 495 That is, the connection preface starts with the string "PRI * 496 HTTP/2.0\r\n\r\nSM\r\n\r\n". This sequence MUST be followed by a 497 SETTINGS frame (Section 6.5), which MAY be empty. The client sends 498 the client connection preface immediately upon receipt of a 101 499 (Switching Protocols) response (indicating a successful upgrade) or 500 as the first application data octets of a TLS connection. If 501 starting an HTTP/2 connection with prior knowledge of server support 502 for the protocol, the client connection preface is sent upon 503 connection establishment. 505 | Note: The client connection preface is selected so that a large 506 | proportion of HTTP/1.1 or HTTP/1.0 servers and intermediaries 507 | do not attempt to process further frames. Note that this does 508 | not address the concerns raised in [TALKING]. 510 The server connection preface consists of a potentially empty 511 SETTINGS frame (Section 6.5) that MUST be the first frame the server 512 sends in the HTTP/2 connection. 514 The SETTINGS frames received from a peer as part of the connection 515 preface MUST be acknowledged (see Section 6.5.3) after sending the 516 connection preface. 518 To avoid unnecessary latency, clients are permitted to send 519 additional frames to the server immediately after sending the client 520 connection preface, without waiting to receive the server connection 521 preface. It is important to note, however, that the server 522 connection preface SETTINGS frame might include parameters that 523 necessarily alter how a client is expected to communicate with the 524 server. Upon receiving the SETTINGS frame, the client is expected to 525 honor any parameters established. In some configurations, it is 526 possible for the server to transmit SETTINGS before the client sends 527 additional frames, providing an opportunity to avoid this issue. 529 Clients and servers MUST treat an invalid connection preface as a 530 connection error (Section 5.4.1) of type PROTOCOL_ERROR. A GOAWAY 531 frame (Section 6.8) MAY be omitted in this case, since an invalid 532 preface indicates that the peer is not using HTTP/2. 534 4. HTTP Frames 536 Once the HTTP/2 connection is established, endpoints can begin 537 exchanging frames. 539 4.1. Frame Format 541 All frames begin with a fixed 9-octet header followed by a variable- 542 length frame payload. 544 +-----------------------------------------------+ 545 | Length (24) | 546 +---------------+---------------+---------------+ 547 | Type (8) | Flags (8) | 548 +-+-------------+---------------+-------------------------------+ 549 |R| Stream Identifier (31) | 550 +=+=============================================================+ 551 | Frame Payload (0...) ... 552 +---------------------------------------------------------------+ 554 Figure 1: Frame Layout 556 The fields of the frame header are defined as: 558 Length: The length of the frame payload expressed as an unsigned 559 24-bit integer. Values greater than 2^(14) (16,384) MUST NOT be 560 sent unless the receiver has set a larger value for 561 SETTINGS_MAX_FRAME_SIZE. 563 The 9 octets of the frame header are not included in this value. 565 Type: The 8-bit type of the frame. The frame type determines the 566 format and semantics of the frame. Implementations MUST ignore 567 and discard any frame that has a type that is unknown. 569 Flags: An 8-bit field reserved for boolean flags specific to the 570 frame type. 572 Flags are assigned semantics specific to the indicated frame type. 573 Flags that have no defined semantics for a particular frame type 574 MUST be ignored and MUST be left unset (0x0) when sending. 576 R: A reserved 1-bit field. The semantics of this bit are undefined, 577 and the bit MUST remain unset (0x0) when sending and MUST be 578 ignored when receiving. 580 Stream Identifier: A stream identifier (see Section 5.1.1) expressed 581 as an unsigned 31-bit integer. The value 0x0 is reserved for 582 frames that are associated with the connection as a whole as 583 opposed to an individual stream. 585 The structure and content of the frame payload is dependent entirely 586 on the frame type. 588 4.2. Frame Size 590 The size of a frame payload is limited by the maximum size that a 591 receiver advertises in the SETTINGS_MAX_FRAME_SIZE setting. This 592 setting can have any value between 2^(14) (16,384) and 2^(24)-1 593 (16,777,215) octets, inclusive. 595 All implementations MUST be capable of receiving and minimally 596 processing frames up to 2^(14) octets in length, plus the 9-octet 597 frame header (Section 4.1). The size of the frame header is not 598 included when describing frame sizes. 600 | Note: Certain frame types, such as PING (Section 6.7), impose 601 | additional limits on the amount of frame payload data allowed. 603 An endpoint MUST send an error code of FRAME_SIZE_ERROR if a frame 604 exceeds the size defined in SETTINGS_MAX_FRAME_SIZE, exceeds any 605 limit defined for the frame type, or is too small to contain 606 mandatory frame data. A frame size error in a frame that could alter 607 the state of the entire connection MUST be treated as a connection 608 error (Section 5.4.1); this includes any frame carrying a field block 609 (Section 4.3) (that is, HEADERS, PUSH_PROMISE, and CONTINUATION), 610 SETTINGS, and any frame with a stream identifier of 0. 612 Endpoints are not obligated to use all available space in a frame. 613 Responsiveness can be improved by using frames that are smaller than 614 the permitted maximum size. Sending large frames can result in 615 delays in sending time-sensitive frames (such as RST_STREAM, 616 WINDOW_UPDATE, or PRIORITY), which, if blocked by the transmission of 617 a large frame, could affect performance. 619 4.3. Field Section Compression and Decompression 621 Field section compression is the process of compressing a set of 622 field lines to form a field block. Field section decompression is 623 the process of decoding a field block into a set of field lines. 624 Details of HTTP/2 field section compression and decompression is 625 defined in [COMPRESSION], which, for historical reasons, refers to 626 these processes as header compression and decompression. 628 Field blocks carry the compressed bytes of a field section, with 629 header sections also carrying control data associated with the 630 message in the form of pseudo-header fields (Section 8.1.2.1) that 631 use the same format as a field line. 633 | Note: Previous versions of this specification used the term 634 | "header block" in place of the more generic "field block". 636 Field blocks carry control data and header sections for requests, 637 responses, promised requests, and pushed responses (see Section 8.2). 638 All these messages, except for interim responses and requests 639 contained in PUSH_PROMISE (Section 6.6) frames can optionally include 640 a field block that carries a trailer section. 642 A field section is a collection of zero or more field lines. Each of 643 the field lines in a field block carry a single value. The 644 serialized field block is then divided into one or more octet 645 sequences, called field block fragments, and transmitted within the 646 frame payload of HEADERS (Section 6.2) or PUSH_PROMISE (Section 6.6), 647 each of which could be followed by CONTINUATION (Section 6.10) 648 frames. 650 The Cookie header field [COOKIE] is treated specially by the HTTP 651 mapping (see Section 8.1.2.5). 653 A receiving endpoint reassembles the field block by concatenating its 654 fragments and then decompresses the block to reconstruct the field 655 section. 657 A complete field section consists of either: 659 * a single HEADERS or PUSH_PROMISE frame, with the END_HEADERS flag 660 set, or 662 * a HEADERS or PUSH_PROMISE frame with the END_HEADERS flag cleared 663 and one or more CONTINUATION frames, where the last CONTINUATION 664 frame has the END_HEADERS flag set. 666 Field compression is stateful. One compression context and one 667 decompression context are used for the entire connection. A decoding 668 error in a field block MUST be treated as a connection error 669 (Section 5.4.1) of type COMPRESSION_ERROR. 671 Each field block is processed as a discrete unit. Field blocks MUST 672 be transmitted as a contiguous sequence of frames, with no 673 interleaved frames of any other type or from any other stream. The 674 last frame in a sequence of HEADERS or CONTINUATION frames has the 675 END_HEADERS flag set. The last frame in a sequence of PUSH_PROMISE 676 or CONTINUATION frames has the END_HEADERS flag set. This allows a 677 field block to be logically equivalent to a single frame. 679 Field block fragments can only be sent as the frame payload of 680 HEADERS, PUSH_PROMISE, or CONTINUATION frames because these frames 681 carry data that can modify the compression context maintained by a 682 receiver. An endpoint receiving HEADERS, PUSH_PROMISE, or 683 CONTINUATION frames needs to reassemble field blocks and perform 684 decompression even if the frames are to be discarded. A receiver 685 MUST terminate the connection with a connection error (Section 5.4.1) 686 of type COMPRESSION_ERROR if it does not decompress a field block. 688 5. Streams and Multiplexing 690 A "stream" is an independent, bidirectional sequence of frames 691 exchanged between the client and server within an HTTP/2 connection. 692 Streams have several important characteristics: 694 * A single HTTP/2 connection can contain multiple concurrently open 695 streams, with either endpoint interleaving frames from multiple 696 streams. 698 * Streams can be established and used unilaterally or shared by 699 either the client or server. 701 * Streams can be closed by either endpoint. 703 * The order in which frames are sent on a stream is significant. 704 Recipients process frames in the order they are received. In 705 particular, the order of HEADERS and DATA frames is semantically 706 significant. 708 * Streams are identified by an integer. Stream identifiers are 709 assigned to streams by the endpoint initiating the stream. 711 5.1. Stream States 713 The lifecycle of a stream is shown in Figure 2. 715 +--------+ 716 send PP | | recv PP 717 ,--------| idle |--------. 718 / | | \ 719 v +--------+ v 720 +----------+ | +----------+ 721 | | | send H / | | 722 ,------| reserved | | recv H | reserved |------. 723 | | (local) | | | (remote) | | 724 | +----------+ v +----------+ | 725 | | +--------+ | | 726 | | recv ES | | send ES | | 727 | send H | ,-------| open |-------. | recv H | 728 | | / | | \ | | 729 | v v +--------+ v v | 730 | +----------+ | +----------+ | 731 | | half | | | half | | 732 | | closed | | send R / | closed | | 733 | | (remote) | | recv R | (local) | | 734 | +----------+ | +----------+ | 735 | | | | | 736 | | send ES / | recv ES / | | 737 | | send R / v send R / | | 738 | | recv R +--------+ recv R | | 739 | send R / `----------->| |<-----------' send R / | 740 | recv R | closed | recv R | 741 `----------------------->| |<----------------------' 742 +--------+ 744 send: endpoint sends this frame 745 recv: endpoint receives this frame 747 H: HEADERS frame (with implied CONTINUATIONs) 748 ES: END_STREAM flag 749 R: RST_STREAM frame 750 PP: PUSH_PROMISE frame (with implied CONTINUATIONs) 751 Note: State transitions are for the promised stream. 753 Figure 2: Stream States 755 Note that this diagram shows stream state transitions and the frames 756 and flags that affect those transitions only. In this regard, 757 CONTINUATION frames do not result in state transitions; they are 758 effectively part of the HEADERS or PUSH_PROMISE that they follow. 759 For the purpose of state transitions, the END_STREAM flag is 760 processed as a separate event to the frame that bears it; a HEADERS 761 frame with the END_STREAM flag set can cause two state transitions. 763 Both endpoints have a subjective view of the state of a stream that 764 could be different when frames are in transit. Endpoints do not 765 coordinate the creation of streams; they are created unilaterally by 766 either endpoint. The negative consequences of a mismatch in states 767 are limited to the "closed" state after sending RST_STREAM, where 768 frames might be received for some time after closing. 770 Streams have the following states: 772 idle: All streams start in the "idle" state. 774 The following transitions are valid from this state: 776 * Sending or receiving a HEADERS frame causes the stream to 777 become "open". The stream identifier is selected as described 778 in Section 5.1.1. The same HEADERS frame can also cause a 779 stream to immediately become "half-closed". 781 * Sending a PUSH_PROMISE frame on another stream reserves the 782 idle stream that is identified for later use. The stream state 783 for the reserved stream transitions to "reserved (local)". 785 * Receiving a PUSH_PROMISE frame on another stream reserves an 786 idle stream that is identified for later use. The stream state 787 for the reserved stream transitions to "reserved (remote)". 789 * Note that the PUSH_PROMISE frame is not sent on the idle stream 790 but references the newly reserved stream in the Promised Stream 791 ID field. 793 Receiving any frame other than HEADERS or PRIORITY on a stream in 794 this state MUST be treated as a connection error (Section 5.4.1) 795 of type PROTOCOL_ERROR. 797 reserved (local): A stream in the "reserved (local)" state is one 798 that has been promised by sending a PUSH_PROMISE frame. A 799 PUSH_PROMISE frame reserves an idle stream by associating the 800 stream with an open stream that was initiated by the remote peer 801 (see Section 8.2). 803 In this state, only the following transitions are possible: 805 * The endpoint can send a HEADERS frame. This causes the stream 806 to open in a "half-closed (remote)" state. 808 * Either endpoint can send a RST_STREAM frame to cause the stream 809 to become "closed". This releases the stream reservation. 811 An endpoint MUST NOT send any type of frame other than HEADERS, 812 RST_STREAM, or PRIORITY in this state. 814 A PRIORITY or WINDOW_UPDATE frame MAY be received in this state. 815 Receiving any type of frame other than RST_STREAM, PRIORITY, or 816 WINDOW_UPDATE on a stream in this state MUST be treated as a 817 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 819 reserved (remote): A stream in the "reserved (remote)" state has 820 been reserved by a remote peer. 822 In this state, only the following transitions are possible: 824 * Receiving a HEADERS frame causes the stream to transition to 825 "half-closed (local)". 827 * Either endpoint can send a RST_STREAM frame to cause the stream 828 to become "closed". This releases the stream reservation. 830 An endpoint MAY send a PRIORITY frame in this state to 831 reprioritize the reserved stream. An endpoint MUST NOT send any 832 type of frame other than RST_STREAM, WINDOW_UPDATE, or PRIORITY in 833 this state. 835 Receiving any type of frame other than HEADERS, RST_STREAM, or 836 PRIORITY on a stream in this state MUST be treated as a connection 837 error (Section 5.4.1) of type PROTOCOL_ERROR. 839 open: A stream in the "open" state may be used by both peers to send 840 frames of any type. In this state, sending peers observe 841 advertised stream-level flow-control limits (Section 5.2). 843 From this state, either endpoint can send a frame with an 844 END_STREAM flag set, which causes the stream to transition into 845 one of the "half-closed" states. An endpoint sending an 846 END_STREAM flag causes the stream state to become "half-closed 847 (local)"; an endpoint receiving an END_STREAM flag causes the 848 stream state to become "half-closed (remote)". 850 Either endpoint can send a RST_STREAM frame from this state, 851 causing it to transition immediately to "closed". 853 half-closed (local): A stream that is in the "half-closed (local)" 854 state cannot be used for sending frames other than WINDOW_UPDATE, 855 PRIORITY, and RST_STREAM. 857 A stream transitions from this state to "closed" when a frame that 858 contains an END_STREAM flag is received or when either peer sends 859 a RST_STREAM frame. 861 An endpoint can receive any type of frame in this state. 862 Providing flow-control credit using WINDOW_UPDATE frames is 863 necessary to continue receiving flow-controlled frames. In this 864 state, a receiver can ignore WINDOW_UPDATE frames, which might 865 arrive for a short period after a frame bearing the END_STREAM 866 flag is sent. 868 PRIORITY frames received in this state are used to reprioritize 869 streams that depend on the identified stream. 871 half-closed (remote): A stream that is "half-closed (remote)" is no 872 longer being used by the peer to send frames. In this state, an 873 endpoint is no longer obligated to maintain a receiver flow- 874 control window. 876 If an endpoint receives additional frames, other than 877 WINDOW_UPDATE, PRIORITY, or RST_STREAM, for a stream that is in 878 this state, it MUST respond with a stream error (Section 5.4.2) of 879 type STREAM_CLOSED. 881 A stream that is "half-closed (remote)" can be used by the 882 endpoint to send frames of any type. In this state, the endpoint 883 continues to observe advertised stream-level flow-control limits 884 (Section 5.2). 886 A stream can transition from this state to "closed" by sending a 887 frame that contains an END_STREAM flag or when either peer sends a 888 RST_STREAM frame. 890 closed: The "closed" state is the terminal state. 892 An endpoint MUST NOT send frames other than PRIORITY on a closed 893 stream. An endpoint that receives any frame other than PRIORITY 894 after receiving a RST_STREAM MUST treat that as a stream error 895 (Section 5.4.2) of type STREAM_CLOSED. Similarly, an endpoint 896 that receives any frames after receiving a frame with the 897 END_STREAM flag set MUST treat that as a connection error 898 (Section 5.4.1) of type STREAM_CLOSED, unless the frame is 899 permitted as described below. 901 WINDOW_UPDATE or RST_STREAM frames can be received in this state 902 for a short period after a DATA or HEADERS frame containing an 903 END_STREAM flag is sent. Until the remote peer receives and 904 processes RST_STREAM or the frame bearing the END_STREAM flag, it 905 might send frames of these types. Endpoints MUST ignore 906 WINDOW_UPDATE or RST_STREAM frames received in this state, though 907 endpoints MAY choose to treat frames that arrive a significant 908 time after sending END_STREAM as a connection error 909 (Section 5.4.1) of type PROTOCOL_ERROR. 911 PRIORITY frames can be sent on closed streams to prioritize 912 streams that are dependent on the closed stream. Endpoints SHOULD 913 process PRIORITY frames, though they can be ignored if the stream 914 has been removed from the dependency tree (see Section 5.3.4). 916 If this state is reached as a result of sending a RST_STREAM 917 frame, the peer that receives the RST_STREAM might have already 918 sent -- or enqueued for sending -- frames on the stream that 919 cannot be withdrawn. An endpoint MUST ignore frames that it 920 receives on closed streams after it has sent a RST_STREAM frame. 921 An endpoint MAY choose to limit the period over which it ignores 922 frames and treat frames that arrive after this time as being in 923 error. 925 Flow-controlled frames (i.e., DATA) received after sending 926 RST_STREAM are counted toward the connection flow-control window. 927 Even though these frames might be ignored, because they are sent 928 before the sender receives the RST_STREAM, the sender will 929 consider the frames to count against the flow-control window. 931 An endpoint might receive a PUSH_PROMISE frame after it sends 932 RST_STREAM. PUSH_PROMISE causes a stream to become "reserved" 933 even if the associated stream has been reset. Therefore, a 934 RST_STREAM is needed to close an unwanted promised stream. 936 In the absence of more specific guidance elsewhere in this document, 937 implementations SHOULD treat the receipt of a frame that is not 938 expressly permitted in the description of a state as a connection 939 error (Section 5.4.1) of type PROTOCOL_ERROR. Note that PRIORITY can 940 be sent and received in any stream state. Frames of unknown types 941 are ignored. 943 An example of the state transitions for an HTTP request/response 944 exchange can be found in Section 8.1. An example of the state 945 transitions for server push can be found in Sections 8.2.1 and 8.2.2. 947 5.1.1. Stream Identifiers 949 Streams are identified with an unsigned 31-bit integer. Streams 950 initiated by a client MUST use odd-numbered stream identifiers; those 951 initiated by the server MUST use even-numbered stream identifiers. A 952 stream identifier of zero (0x0) is used for connection control 953 messages; the stream identifier of zero cannot be used to establish a 954 new stream. 956 HTTP/1.1 requests that are upgraded to HTTP/2 (see Section 3.2) are 957 responded to with a stream identifier of one (0x1). After the 958 upgrade completes, stream 0x1 is "half-closed (local)" to the client. 959 Therefore, stream 0x1 cannot be selected as a new stream identifier 960 by a client that upgrades from HTTP/1.1. 962 The identifier of a newly established stream MUST be numerically 963 greater than all streams that the initiating endpoint has opened or 964 reserved. This governs streams that are opened using a HEADERS frame 965 and streams that are reserved using PUSH_PROMISE. An endpoint that 966 receives an unexpected stream identifier MUST respond with a 967 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 969 A HEADERS frame will transition the client-initiated stream 970 identified by the stream identifier in the frame header from "idle" 971 to "open". A PUSH_PROMISE frame will transition the server-initiated 972 stream identified by the "Promised Stream ID" field in the frame 973 payload from "idle" to "reserved". When a stream transitions out of 974 the "idle" state, all streams that might have been initiated by that 975 peer with a lower-valued stream identifier are implicitly 976 transitioned to "closed". That is, an endpoint may skip a stream 977 identifier, with the effect being that the skipped stream is 978 immediately closed. 980 Stream identifiers cannot be reused. Long-lived connections can 981 result in an endpoint exhausting the available range of stream 982 identifiers. A client that is unable to establish a new stream 983 identifier can establish a new connection for new streams. A server 984 that is unable to establish a new stream identifier can send a GOAWAY 985 frame so that the client is forced to open a new connection for new 986 streams. 988 5.1.2. Stream Concurrency 990 A peer can limit the number of concurrently active streams using the 991 SETTINGS_MAX_CONCURRENT_STREAMS parameter (see Section 6.5.2) within 992 a SETTINGS frame. The maximum concurrent streams setting is specific 993 to each endpoint and applies only to the peer that receives the 994 setting. That is, clients specify the maximum number of concurrent 995 streams the server can initiate, and servers specify the maximum 996 number of concurrent streams the client can initiate. 998 Streams that are in the "open" state or in either of the "half- 999 closed" states count toward the maximum number of streams that an 1000 endpoint is permitted to open. Streams in any of these three states 1001 count toward the limit advertised in the 1002 SETTINGS_MAX_CONCURRENT_STREAMS setting. Streams in either of the 1003 "reserved" states do not count toward the stream limit. 1005 Endpoints MUST NOT exceed the limit set by their peer. An endpoint 1006 that receives a HEADERS frame that causes its advertised concurrent 1007 stream limit to be exceeded MUST treat this as a stream error 1008 (Section 5.4.2) of type PROTOCOL_ERROR or REFUSED_STREAM. The choice 1009 of error code determines whether the endpoint wishes to enable 1010 automatic retry (see Section 8.1.4) for details). 1012 An endpoint that wishes to reduce the value of 1013 SETTINGS_MAX_CONCURRENT_STREAMS to a value that is below the current 1014 number of open streams can either close streams that exceed the new 1015 value or allow streams to complete. 1017 5.2. Flow Control 1019 Using streams for multiplexing introduces contention over use of the 1020 TCP connection, resulting in blocked streams. A flow-control scheme 1021 ensures that streams on the same connection do not destructively 1022 interfere with each other. Flow control is used for both individual 1023 streams and for the connection as a whole. 1025 HTTP/2 provides for flow control through use of the WINDOW_UPDATE 1026 frame (Section 6.9). 1028 5.2.1. Flow-Control Principles 1030 HTTP/2 stream flow control aims to allow a variety of flow-control 1031 algorithms to be used without requiring protocol changes. Flow 1032 control in HTTP/2 has the following characteristics: 1034 1. Flow control is specific to a connection. Both types of flow 1035 control are between the endpoints of a single hop and not over 1036 the entire end-to-end path. 1038 2. Flow control is based on WINDOW_UPDATE frames. Receivers 1039 advertise how many octets they are prepared to receive on a 1040 stream and for the entire connection. This is a credit-based 1041 scheme. 1043 3. Flow control is directional with overall control provided by the 1044 receiver. A receiver MAY choose to set any window size that it 1045 desires for each stream and for the entire connection. A sender 1046 MUST respect flow-control limits imposed by a receiver. Clients, 1047 servers, and intermediaries all independently advertise their 1048 flow-control window as a receiver and abide by the flow-control 1049 limits set by their peer when sending. 1051 4. The initial value for the flow-control window is 65,535 octets 1052 for both new streams and the overall connection. 1054 5. The frame type determines whether flow control applies to a 1055 frame. Of the frames specified in this document, only DATA 1056 frames are subject to flow control; all other frame types do not 1057 consume space in the advertised flow-control window. This 1058 ensures that important control frames are not blocked by flow 1059 control. 1061 6. Flow control cannot be disabled. 1063 7. HTTP/2 defines only the format and semantics of the WINDOW_UPDATE 1064 frame (Section 6.9). This document does not stipulate how a 1065 receiver decides when to send this frame or the value that it 1066 sends, nor does it specify how a sender chooses to send packets. 1067 Implementations are able to select any algorithm that suits their 1068 needs. 1070 Implementations are also responsible for managing how requests and 1071 responses are sent based on priority, choosing how to avoid head-of- 1072 line blocking for requests, and managing the creation of new streams. 1073 Algorithm choices for these could interact with any flow-control 1074 algorithm. 1076 5.2.2. Appropriate Use of Flow Control 1078 Flow control is defined to protect endpoints that are operating under 1079 resource constraints. For example, a proxy needs to share memory 1080 between many connections and also might have a slow upstream 1081 connection and a fast downstream one. Flow-control addresses cases 1082 where the receiver is unable to process data on one stream yet wants 1083 to continue to process other streams in the same connection. 1085 Deployments that do not require this capability can advertise a flow- 1086 control window of the maximum size (2^(31)-1) and can maintain this 1087 window by sending a WINDOW_UPDATE frame when any data is received. 1088 This effectively disables flow control for that receiver. 1089 Conversely, a sender is always subject to the flow-control window 1090 advertised by the receiver. 1092 Deployments with constrained resources (for example, memory) can 1093 employ flow control to limit the amount of memory a peer can consume. 1094 Note, however, that this can lead to suboptimal use of available 1095 network resources if flow control is enabled without knowledge of the 1096 bandwidth-delay product (see [RFC7323]). 1098 Even with full awareness of the current bandwidth-delay product, 1099 implementation of flow control can be difficult. When using flow 1100 control, the receiver MUST read from the TCP receive buffer in a 1101 timely fashion. Failure to do so could lead to a deadlock when 1102 critical frames, such as WINDOW_UPDATE, are not read and acted upon. 1104 5.3. Stream Priority 1106 A client can assign a priority for a new stream by including 1107 prioritization information in the HEADERS frame (Section 6.2) that 1108 opens the stream. At any other time, the PRIORITY frame 1109 (Section 6.3) can be used to change the priority of a stream. 1111 The purpose of prioritization is to allow an endpoint to express how 1112 it would prefer its peer to allocate resources when managing 1113 concurrent streams. Most importantly, priority can be used to select 1114 streams for transmitting frames when there is limited capacity for 1115 sending. 1117 Streams can be prioritized by marking them as dependent on the 1118 completion of other streams (Section 5.3.1). Each dependency is 1119 assigned a relative weight, a number that is used to determine the 1120 relative proportion of available resources that are assigned to 1121 streams dependent on the same stream. 1123 Explicitly setting the priority for a stream is input to a 1124 prioritization process. It does not guarantee any particular 1125 processing or transmission order for the stream relative to any other 1126 stream. An endpoint cannot force a peer to process concurrent 1127 streams in a particular order using priority. Expressing priority is 1128 therefore only a suggestion. 1130 Prioritization information can be omitted from messages. Defaults 1131 are used prior to any explicit values being provided (Section 5.3.5). 1133 The information that an endpoint maintains for stream priority is 1134 separate from other state. Importantly, this includes stream states 1135 (Section 5.1). A stream in any state can have its priority changed 1136 with a PRIORITY frame. The state of a stream is not changed as a 1137 result of changing its priority. The number of streams for which 1138 state is remembered is at the discretion of an endpoint, see 1139 Section 5.3.4 for details. 1141 5.3.1. Stream Dependencies 1143 Each stream can be given an explicit dependency on another stream. 1144 Including a dependency expresses a preference to allocate resources 1145 to the identified stream rather than to the dependent stream. 1147 A stream that is not dependent on any other stream is given a stream 1148 dependency of 0x0. In other words, the non-existent stream 0 forms 1149 the root of the tree. 1151 A stream that depends on another stream is a dependent stream. The 1152 stream upon which a stream is dependent is a parent stream. A 1153 dependency on a stream that is not currently in the tree -- such as a 1154 stream in the "idle" state -- results in that stream being given a 1155 default priority (Section 5.3.5). 1157 When assigning a dependency on another stream, the stream is added as 1158 a new dependency of the parent stream. Dependent streams that share 1159 the same parent are not ordered with respect to each other. For 1160 example, if streams B and C are dependent on stream A, and if stream 1161 D is created with a dependency on stream A, this results in a 1162 dependency order of A followed by B, C, and D in any order. 1164 A A 1165 / \ ==> /|\ 1166 B C B D C 1168 Figure 3: Example of Default Dependency Creation 1170 An exclusive flag allows for the insertion of a new level of 1171 dependencies. The exclusive flag causes the stream to become the 1172 sole dependency of its parent stream, causing other dependencies to 1173 become dependent on the exclusive stream. In the previous example, 1174 if stream D is created with an exclusive dependency on stream A, this 1175 results in D becoming the dependency parent of B and C. 1177 A 1178 A | 1179 / \ ==> D 1180 B C / \ 1181 B C 1183 Figure 4: Example of Exclusive Dependency Creation 1185 Inside the dependency tree, a dependent stream SHOULD only be 1186 allocated resources if either all of the streams that it depends on 1187 (the chain of parent streams up to 0x0) are closed or it is not 1188 possible to make progress on them. 1190 A stream cannot depend on itself. An endpoint MUST treat this as a 1191 stream error (Section 5.4.2) of type PROTOCOL_ERROR. 1193 5.3.2. Dependency Weighting 1195 All dependent streams are allocated an integer weight between 1 and 1196 256 (inclusive). 1198 Streams with the same parent SHOULD be allocated resources 1199 proportionally based on their weight. Thus, if stream B depends on 1200 stream A with weight 4, stream C depends on stream A with weight 12, 1201 and no progress can be made on stream A, stream B ideally receives 1202 one-third of the resources allocated to stream C. 1204 5.3.3. Reprioritization 1206 Stream priorities are changed using the PRIORITY frame. Setting a 1207 dependency causes a stream to become dependent on the identified 1208 parent stream. 1210 Dependent streams move with their parent stream if the parent is 1211 reprioritized. Setting a dependency with the exclusive flag for a 1212 reprioritized stream causes all the dependencies of the new parent 1213 stream to become dependent on the reprioritized stream. 1215 If a stream is made dependent on one of its own dependencies, the 1216 formerly dependent stream is first moved to be dependent on the 1217 reprioritized stream's previous parent. The moved dependency retains 1218 its weight. 1220 For example, consider an original dependency tree where B and C 1221 depend on A, D and E depend on C, and F depends on D. If A is made 1222 dependent on D, then D takes the place of A. All other dependency 1223 relationships stay the same, except for F, which becomes dependent on 1224 A if the reprioritization is exclusive. 1226 x x x x 1227 | / \ | | 1228 A D A D D 1229 / \ / / \ / \ | 1230 B C ==> F B C ==> F A OR A 1231 / \ | / \ /|\ 1232 D E E B C B C F 1233 | | | 1234 F E E 1235 (intermediate) (non-exclusive) (exclusive) 1237 Figure 5: Example of Dependency Reordering 1239 5.3.4. Prioritization State Management 1241 When a stream is removed from the dependency tree, its dependencies 1242 can be moved to become dependent on the parent of the closed stream. 1243 The weights of new dependencies are recalculated by distributing the 1244 weight of the dependency of the closed stream proportionally based on 1245 the weights of its dependencies. 1247 Streams that are removed from the dependency tree cause some 1248 prioritization information to be lost. Resources are shared between 1249 streams with the same parent stream, which means that if a stream in 1250 that set closes or becomes blocked, any spare capacity allocated to a 1251 stream is distributed to the immediate neighbors of the stream. 1252 However, if the common dependency is removed from the tree, those 1253 streams share resources with streams at the next highest level. 1255 For example, assume streams A and B share a parent, and streams C and 1256 D both depend on stream A. Prior to the removal of stream A, if 1257 streams A and D are unable to proceed, then stream C receives all the 1258 resources dedicated to stream A. If stream A is removed from the 1259 tree, the weight of stream A is divided between streams C and D. If 1260 stream D is still unable to proceed, this results in stream C 1261 receiving a reduced proportion of resources. For equal starting 1262 weights, C receives one third, rather than one half, of available 1263 resources. 1265 It is possible for a stream to become closed while prioritization 1266 information that creates a dependency on that stream is in transit. 1267 If a stream identified in a dependency has no associated priority 1268 information, then the dependent stream is instead assigned a default 1269 priority (Section 5.3.5). This potentially creates suboptimal 1270 prioritization, since the stream could be given a priority that is 1271 different from what is intended. 1273 To avoid these problems, an endpoint SHOULD retain stream 1274 prioritization state for a period after streams become closed. The 1275 longer state is retained, the lower the chance that streams are 1276 assigned incorrect or default priority values. 1278 Similarly, streams that are in the "idle" state can be assigned 1279 priority or become a parent of other streams. This allows for the 1280 creation of a grouping node in the dependency tree, which enables 1281 more flexible expressions of priority. Idle streams begin with a 1282 default priority (Section 5.3.5). 1284 The retention of priority information for streams that are not 1285 counted toward the limit set by SETTINGS_MAX_CONCURRENT_STREAMS could 1286 create a large state burden for an endpoint. Therefore, the amount 1287 of prioritization state that is retained MAY be limited. 1289 The amount of additional state an endpoint maintains for 1290 prioritization could be dependent on load; under high load, 1291 prioritization state can be discarded to limit resource commitments. 1292 In extreme cases, an endpoint could even discard prioritization state 1293 for active or reserved streams. If a limit is applied, endpoints 1294 SHOULD maintain state for at least as many streams as allowed by 1295 their setting for SETTINGS_MAX_CONCURRENT_STREAMS. Implementations 1296 SHOULD also attempt to retain state for streams that are in active 1297 use in the priority tree. 1299 If it has retained enough state to do so, an endpoint receiving a 1300 PRIORITY frame that changes the priority of a closed stream SHOULD 1301 alter the dependencies of the streams that depend on it. 1303 5.3.5. Default Priorities 1305 All streams are initially assigned a non-exclusive dependency on 1306 stream 0x0. Pushed streams (Section 8.2) initially depend on their 1307 associated stream. In both cases, streams are assigned a default 1308 weight of 16. 1310 5.4. Error Handling 1312 HTTP/2 framing permits two classes of error: 1314 * An error condition that renders the entire connection unusable is 1315 a connection error. 1317 * An error in an individual stream is a stream error. 1319 A list of error codes is included in Section 7. 1321 It is possible that an endpoint will encounter frames that would 1322 cause multiple errors. Implementations MAY discover multiple errors 1323 during processing, but they SHOULD report at most one stream and one 1324 connection error as a result. 1326 The first stream error reported for a given stream prevents any other 1327 errors on that stream from being reported. In comparison, the 1328 protocol permits multiple GOAWAY frames, though an endpoint SHOULD 1329 report just one type of connection error unless an error is 1330 encountered during graceful shutdown. If this occurs, an endpoint 1331 MAY send an additional GOAWAY frame with the new error code, in 1332 addition to any prior GOAWAY that contained NO_ERROR. 1334 If an endpoint detects multiple different errors, it MAY choose to 1335 report any one of those errors. If a frame causes a connection 1336 error, that error MUST be reported. 1338 5.4.1. Connection Error Handling 1340 A connection error is any error that prevents further processing of 1341 the frame layer or corrupts any connection state. 1343 An endpoint that encounters a connection error SHOULD first send a 1344 GOAWAY frame (Section 6.8) with the stream identifier of the last 1345 stream that it successfully received from its peer. The GOAWAY frame 1346 includes an error code that indicates why the connection is 1347 terminating. After sending the GOAWAY frame for an error condition, 1348 the endpoint MUST close the TCP connection. 1350 It is possible that the GOAWAY will not be reliably received by the 1351 receiving endpoint. In the event of a connection error, GOAWAY only 1352 provides a best-effort attempt to communicate with the peer about why 1353 the connection is being terminated. 1355 An endpoint can end a connection at any time. In particular, an 1356 endpoint MAY choose to treat a stream error as a connection error. 1357 Endpoints SHOULD send a GOAWAY frame when ending a connection, 1358 providing that circumstances permit it. 1360 5.4.2. Stream Error Handling 1362 A stream error is an error related to a specific stream that does not 1363 affect processing of other streams. 1365 An endpoint that detects a stream error sends a RST_STREAM frame 1366 (Section 6.4) that contains the stream identifier of the stream where 1367 the error occurred. The RST_STREAM frame includes an error code that 1368 indicates the type of error. 1370 A RST_STREAM is the last frame that an endpoint can send on a stream. 1371 The peer that sends the RST_STREAM frame MUST be prepared to receive 1372 any frames that were sent or enqueued for sending by the remote peer. 1373 These frames can be ignored, except where they modify connection 1374 state (such as the state maintained for field section compression 1375 (Section 4.3) or flow control). 1377 Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame 1378 for any stream. However, an endpoint MAY send additional RST_STREAM 1379 frames if it receives frames on a closed stream after more than a 1380 round-trip time. This behavior is permitted to deal with misbehaving 1381 implementations. 1383 To avoid looping, an endpoint MUST NOT send a RST_STREAM in response 1384 to a RST_STREAM frame. 1386 5.4.3. Connection Termination 1388 If the TCP connection is closed or reset while streams remain in 1389 "open" or "half-closed" state, then the affected streams cannot be 1390 automatically retried (see Section 8.1.4 for details). 1392 5.5. Extending HTTP/2 1394 HTTP/2 permits extension of the protocol. Within the limitations 1395 described in this section, protocol extensions can be used to provide 1396 additional services or alter any aspect of the protocol. Extensions 1397 are effective only within the scope of a single HTTP/2 connection. 1399 This applies to the protocol elements defined in this document. This 1400 does not affect the existing options for extending HTTP, such as 1401 defining new methods, status codes, or fields (see Section 16 of 1402 [HTTP]). 1404 Extensions are permitted to use new frame types (Section 4.1), new 1405 settings (Section 6.5.2), or new error codes (Section 7). Registries 1406 are established for managing these extension points: frame types 1407 (Section 11.2), settings (Section 11.3), and error codes 1408 (Section 11.4). 1410 Implementations MUST ignore unknown or unsupported values in all 1411 extensible protocol elements. Implementations MUST discard frames 1412 that have unknown or unsupported types. This means that any of these 1413 extension points can be safely used by extensions without prior 1414 arrangement or negotiation. However, extension frames that appear in 1415 the middle of a field block (Section 4.3) are not permitted; these 1416 MUST be treated as a connection error (Section 5.4.1) of type 1417 PROTOCOL_ERROR. 1419 Extensions SHOULD avoiding changing protocol elements defined in this 1420 document or elements for which no extension mechanism is defined. 1421 This includes changes to the layout of frames, additions or changes 1422 to the way that frames are composed into HTTP messages (Section 8), 1423 the definition of pseudo-header fields, or changes to any protocol 1424 element that a compliant endpoint might treat as a connection error 1425 (Section 5.4.1). 1427 An extension that changes existing elements MUST be negotiated before 1428 being used. For example, an extension that changes the layout of the 1429 HEADERS frame cannot be used until the peer has given a positive 1430 signal that this is acceptable. In this case, it could also be 1431 necessary to coordinate when the revised layout comes into effect. 1432 For example, treating frames other than DATA frames as flow 1433 controlled requires a change in semantics that both endpoints need to 1434 understand, so this can only be done through negotiation. 1436 This document doesn't mandate a specific method for negotiating the 1437 use of an extension but notes that a setting (Section 6.5.2) could be 1438 used for that purpose. If both peers set a value that indicates 1439 willingness to use the extension, then the extension can be used. If 1440 a setting is used for extension negotiation, the initial value MUST 1441 be defined in such a fashion that the extension is initially 1442 disabled. 1444 6. Frame Definitions 1446 This specification defines a number of frame types, each identified 1447 by a unique 8-bit type code. Each frame type serves a distinct 1448 purpose in the establishment and management either of the connection 1449 as a whole or of individual streams. 1451 The transmission of specific frame types can alter the state of a 1452 connection. If endpoints fail to maintain a synchronized view of the 1453 connection state, successful communication within the connection will 1454 no longer be possible. Therefore, it is important that endpoints 1455 have a shared comprehension of how the state is affected by the use 1456 any given frame. 1458 6.1. DATA 1460 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 1461 octets associated with a stream. One or more DATA frames are used, 1462 for instance, to carry HTTP request or response message contents. 1464 DATA frames MAY also contain padding. Padding can be added to DATA 1465 frames to obscure the size of messages. Padding is a security 1466 feature; see Section 10.7. 1468 +---------------+ 1469 |Pad Length? (8)| 1470 +---------------+-----------------------------------------------+ 1471 | Data (*) ... 1472 +---------------------------------------------------------------+ 1473 | Padding (*) ... 1474 +---------------------------------------------------------------+ 1476 Figure 6: DATA Frame Payload 1478 The DATA frame contains the following fields: 1480 Pad Length: An 8-bit field containing the length of the frame 1481 padding in units of octets. This field is conditional (as 1482 signified by a "?" in the diagram) and is only present if the 1483 PADDED flag is set. 1485 Data: Application data. The amount of data is the remainder of the 1486 frame payload after subtracting the length of the other fields 1487 that are present. 1489 Padding: Padding octets that contain no application semantic value. 1491 Padding octets MUST be set to zero when sending. A receiver is 1492 not obligated to verify padding but MAY treat non-zero padding as 1493 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1495 The DATA frame defines the following flags: 1497 END_STREAM (0x1): When set, bit 0 indicates that this frame is the 1498 last that the endpoint will send for the identified stream. 1499 Setting this flag causes the stream to enter one of the 1500 "half-closed" states or the "closed" state (Section 5.1). 1502 PADDED (0x8): When set, bit 3 indicates that the Pad Length field 1503 and any padding that it describes are present. 1505 DATA frames MUST be associated with a stream. If a DATA frame is 1506 received whose stream identifier field is 0x0, the recipient MUST 1507 respond with a connection error (Section 5.4.1) of type 1508 PROTOCOL_ERROR. 1510 DATA frames are subject to flow control and can only be sent when a 1511 stream is in the "open" or "half-closed (remote)" state. The entire 1512 DATA frame payload is included in flow control, including the Pad 1513 Length and Padding fields if present. If a DATA frame is received 1514 whose stream is not in "open" or "half-closed (local)" state, the 1515 recipient MUST respond with a stream error (Section 5.4.2) of type 1516 STREAM_CLOSED. 1518 The total number of padding octets is determined by the value of the 1519 Pad Length field. If the length of the padding is the length of the 1520 frame payload or greater, the recipient MUST treat this as a 1521 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1523 | Note: A frame can be increased in size by one octet by 1524 | including a Pad Length field with a value of zero. 1526 6.2. HEADERS 1528 The HEADERS frame (type=0x1) is used to open a stream (Section 5.1), 1529 and additionally carries a field block fragment. Despite the name, a 1530 HEADERS frame can carry a header section or a trailer section. 1531 HEADERS frames can be sent on a stream in the "idle", "reserved 1532 (local)", "open", or "half-closed (remote)" state. 1534 +---------------+ 1535 |Pad Length? (8)| 1536 +-+-------------+-----------------------------------------------+ 1537 |E| Stream Dependency? (31) | 1538 +-+-------------+-----------------------------------------------+ 1539 | Weight? (8) | 1540 +-+-------------+-----------------------------------------------+ 1541 | Field Block Fragment (*) ... 1542 +---------------------------------------------------------------+ 1543 | Padding (*) ... 1544 +---------------------------------------------------------------+ 1546 Figure 7: HEADERS Frame Payload 1548 The HEADERS frame payload has the following fields: 1550 Pad Length: An 8-bit field containing the length of the frame 1551 padding in units of octets. This field is only present if the 1552 PADDED flag is set. 1554 E: A single-bit flag indicating that the stream dependency is 1555 exclusive (see Section 5.3). This field is only present if the 1556 PRIORITY flag is set. 1558 Stream Dependency: A 31-bit stream identifier for the stream that 1559 this stream depends on (see Section 5.3). This field is only 1560 present if the PRIORITY flag is set. 1562 Weight: An unsigned 8-bit integer representing a priority weight for 1563 the stream (see Section 5.3). Add one to the value to obtain a 1564 weight between 1 and 256. This field is only present if the 1565 PRIORITY flag is set. 1567 Field Block Fragment: A field block fragment (Section 4.3). 1569 Padding: Padding octets. 1571 The HEADERS frame defines the following flags: 1573 END_STREAM (0x1): When set, bit 0 indicates that the field block 1574 (Section 4.3) is the last that the endpoint will send for the 1575 identified stream. 1577 A HEADERS frame carries the END_STREAM flag that signals the end 1578 of a stream. However, a HEADERS frame with the END_STREAM flag 1579 set can be followed by CONTINUATION frames on the same stream. 1580 Logically, the CONTINUATION frames are part of the HEADERS frame. 1582 END_HEADERS (0x4): When set, bit 2 indicates that this frame 1583 contains an entire field block (Section 4.3) and is not followed 1584 by any CONTINUATION frames. 1586 A HEADERS frame without the END_HEADERS flag set MUST be followed 1587 by a CONTINUATION frame for the same stream. A receiver MUST 1588 treat the receipt of any other type of frame or a frame on a 1589 different stream as a connection error (Section 5.4.1) of type 1590 PROTOCOL_ERROR. 1592 PADDED (0x8): When set, bit 3 indicates that the Pad Length field 1593 and any padding that it describes are present. 1595 PRIORITY (0x20): When set, bit 5 indicates that the Exclusive Flag 1596 (E), Stream Dependency, and Weight fields are present; see 1597 Section 5.3. 1599 The frame payload of a HEADERS frame contains a field block fragment 1600 (Section 4.3). A field block that does not fit within a HEADERS 1601 frame is continued in a CONTINUATION frame (Section 6.10). 1603 HEADERS frames MUST be associated with a stream. If a HEADERS frame 1604 is received whose stream identifier field is 0x0, the recipient MUST 1605 respond with a connection error (Section 5.4.1) of type 1606 PROTOCOL_ERROR. 1608 The HEADERS frame changes the connection state as described in 1609 Section 4.3. 1611 The HEADERS frame can include padding. Padding fields and flags are 1612 identical to those defined for DATA frames (Section 6.1). Padding 1613 that exceeds the size remaining for the header block fragment MUST be 1614 treated as a PROTOCOL_ERROR. 1616 Prioritization information in a HEADERS frame is logically equivalent 1617 to a separate PRIORITY frame, but inclusion in HEADERS avoids the 1618 potential for churn in stream prioritization when new streams are 1619 created. Prioritization fields in HEADERS frames subsequent to the 1620 first on a stream reprioritize the stream (Section 5.3.3). 1622 6.3. PRIORITY 1624 The PRIORITY frame (type=0x2) specifies the sender-advised priority 1625 of a stream (Section 5.3). It can be sent in any stream state, 1626 including idle or closed streams. 1628 +-+-------------------------------------------------------------+ 1629 |E| Stream Dependency (31) | 1630 +-+-------------+-----------------------------------------------+ 1631 | Weight (8) | 1632 +-+-------------+ 1634 Figure 8: PRIORITY Frame Payload 1636 The frame payload of a PRIORITY frame contains the following fields: 1638 E: A single-bit flag indicating that the stream dependency is 1639 exclusive (see Section 5.3). 1641 Stream Dependency: A 31-bit stream identifier for the stream that 1642 this stream depends on (see Section 5.3). 1644 Weight: An unsigned 8-bit integer representing a priority weight for 1645 the stream (see Section 5.3). Add one to the value to obtain a 1646 weight between 1 and 256. 1648 The PRIORITY frame does not define any flags. 1650 The PRIORITY frame always identifies a stream. If a PRIORITY frame 1651 is received with a stream identifier of 0x0, the recipient MUST 1652 respond with a connection error (Section 5.4.1) of type 1653 PROTOCOL_ERROR. 1655 Sending or receiving a PRIORITY frame does not affect the state of 1656 any stream (Section 5.1), only the priority of streams is altered. 1658 The PRIORITY frame can be sent on a stream in any state, though it 1659 cannot be sent between consecutive frames that comprise a single 1660 field block (Section 4.3). Note that this frame could arrive after 1661 processing or frame sending has completed, which would cause it to 1662 have no effect on the identified stream. For a stream that is in the 1663 "half-closed (remote)" or "closed" state, this frame can only affect 1664 processing of the identified stream and its dependent streams; it 1665 does not affect frame transmission on that stream. 1667 The PRIORITY frame can be sent for a stream in the "idle" or "closed" 1668 state. This allows for the reprioritization of a group of dependent 1669 streams by altering the priority of an unused or closed parent 1670 stream. 1672 A PRIORITY frame with a length other than 5 octets MUST be treated as 1673 a stream error (Section 5.4.2) of type FRAME_SIZE_ERROR. 1675 6.4. RST_STREAM 1677 The RST_STREAM frame (type=0x3) allows for immediate termination of a 1678 stream. RST_STREAM is sent to request cancellation of a stream or to 1679 indicate that an error condition has occurred. 1681 +---------------------------------------------------------------+ 1682 | Error Code (32) | 1683 +---------------------------------------------------------------+ 1685 Figure 9: RST_STREAM Frame Payload 1687 The RST_STREAM frame contains a single unsigned, 32-bit integer 1688 identifying the error code (Section 7). The error code indicates why 1689 the stream is being terminated. 1691 The RST_STREAM frame does not define any flags. 1693 The RST_STREAM frame fully terminates the referenced stream and 1694 causes it to enter the "closed" state. After receiving a RST_STREAM 1695 on a stream, the receiver MUST NOT send additional frames for that 1696 stream, with the exception of PRIORITY. However, after sending the 1697 RST_STREAM, the sending endpoint MUST be prepared to receive and 1698 process additional frames sent on the stream that might have been 1699 sent by the peer prior to the arrival of the RST_STREAM. 1701 RST_STREAM frames MUST be associated with a stream. If a RST_STREAM 1702 frame is received with a stream identifier of 0x0, the recipient MUST 1703 treat this as a connection error (Section 5.4.1) of type 1704 PROTOCOL_ERROR. 1706 RST_STREAM frames MUST NOT be sent for a stream in the "idle" state. 1707 If a RST_STREAM frame identifying an idle stream is received, the 1708 recipient MUST treat this as a connection error (Section 5.4.1) of 1709 type PROTOCOL_ERROR. 1711 A RST_STREAM frame with a length other than 4 octets MUST be treated 1712 as a connection error (Section 5.4.1) of type FRAME_SIZE_ERROR. 1714 6.5. SETTINGS 1716 The SETTINGS frame (type=0x4) conveys configuration parameters that 1717 affect how endpoints communicate, such as preferences and constraints 1718 on peer behavior. The SETTINGS frame is also used to acknowledge the 1719 receipt of those parameters. Individually, a SETTINGS parameter can 1720 also be referred to as a "setting". 1722 SETTINGS parameters are not negotiated; they describe characteristics 1723 of the sending peer, which are used by the receiving peer. Different 1724 values for the same parameter can be advertised by each peer. For 1725 example, a client might set a high initial flow-control window, 1726 whereas a server might set a lower value to conserve resources. 1728 A SETTINGS frame MUST be sent by both endpoints at the start of a 1729 connection and MAY be sent at any other time by either endpoint over 1730 the lifetime of the connection. Implementations MUST support all of 1731 the parameters defined by this specification. 1733 Each parameter in a SETTINGS frame replaces any existing value for 1734 that parameter. Parameters are processed in the order in which they 1735 appear, and a receiver of a SETTINGS frame does not need to maintain 1736 any state other than the current value of its parameters. Therefore, 1737 the value of a SETTINGS parameter is the last value that is seen by a 1738 receiver. 1740 SETTINGS parameters are acknowledged by the receiving peer. To 1741 enable this, the SETTINGS frame defines the following flag: 1743 ACK (0x1): When set, bit 0 indicates that this frame acknowledges 1744 receipt and application of the peer's SETTINGS frame. When this 1745 bit is set, the frame payload of the SETTINGS frame MUST be empty. 1746 Receipt of a SETTINGS frame with the ACK flag set and a length 1747 field value other than 0 MUST be treated as a connection error 1748 (Section 5.4.1) of type FRAME_SIZE_ERROR. For more information, 1749 see Section 6.5.3 ("Settings Synchronization"). 1751 SETTINGS frames always apply to a connection, never a single stream. 1752 The stream identifier for a SETTINGS frame MUST be zero (0x0). If an 1753 endpoint receives a SETTINGS frame whose stream identifier field is 1754 anything other than 0x0, the endpoint MUST respond with a connection 1755 error (Section 5.4.1) of type PROTOCOL_ERROR. 1757 The SETTINGS frame affects connection state. A badly formed or 1758 incomplete SETTINGS frame MUST be treated as a connection error 1759 (Section 5.4.1) of type PROTOCOL_ERROR. 1761 A SETTINGS frame with a length other than a multiple of 6 octets MUST 1762 be treated as a connection error (Section 5.4.1) of type 1763 FRAME_SIZE_ERROR. 1765 6.5.1. SETTINGS Format 1767 The frame payload of a SETTINGS frame consists of zero or more 1768 parameters, each consisting of an unsigned 16-bit setting identifier 1769 and an unsigned 32-bit value. 1771 +-------------------------------+ 1772 | Identifier (16) | 1773 +-------------------------------+-------------------------------+ 1774 | Value (32) | 1775 +---------------------------------------------------------------+ 1777 Figure 10: Setting Format 1779 6.5.2. Defined SETTINGS Parameters 1781 The following parameters are defined: 1783 SETTINGS_HEADER_TABLE_SIZE (0x1): Allows the sender to inform the 1784 remote endpoint of the maximum size of the compression table used 1785 to decode field blocks, in octets. The encoder can select any 1786 size equal to or less than this value by using signaling specific 1787 to the compression format inside a field block (see 1788 [COMPRESSION]). The initial value is 4,096 octets. 1790 SETTINGS_ENABLE_PUSH (0x2): This setting can be used to disable 1791 server push (Section 8.2). An endpoint MUST NOT send a 1792 PUSH_PROMISE frame if it receives this parameter set to a value of 1793 0. An endpoint that has both set this parameter to 0 and had it 1794 acknowledged MUST treat the receipt of a PUSH_PROMISE frame as a 1795 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1797 The initial value is 1, which indicates that server push is 1798 permitted. Any value other than 0 or 1 MUST be treated as a 1799 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1801 SETTINGS_MAX_CONCURRENT_STREAMS (0x3): Indicates the maximum number 1802 of concurrent streams that the sender will allow. This limit is 1803 directional: it applies to the number of streams that the sender 1804 permits the receiver to create. Initially, there is no limit to 1805 this value. It is recommended that this value be no smaller than 1806 100, so as to not unnecessarily limit parallelism. 1808 A value of 0 for SETTINGS_MAX_CONCURRENT_STREAMS SHOULD NOT be 1809 treated as special by endpoints. A zero value does prevent the 1810 creation of new streams; however, this can also happen for any 1811 limit that is exhausted with active streams. Servers SHOULD only 1812 set a zero value for short durations; if a server does not wish to 1813 accept requests, closing the connection is more appropriate. 1815 SETTINGS_INITIAL_WINDOW_SIZE (0x4): Indicates the sender's initial 1816 window size (in octets) for stream-level flow control. The 1817 initial value is 2^(16)-1 (65,535) octets. 1819 This setting affects the window size of all streams (see 1820 Section 6.9.2). 1822 Values above the maximum flow-control window size of 2^(31)-1 MUST 1823 be treated as a connection error (Section 5.4.1) of type 1824 FLOW_CONTROL_ERROR. 1826 SETTINGS_MAX_FRAME_SIZE (0x5): Indicates the size of the largest 1827 frame payload that the sender is willing to receive, in octets. 1829 The initial value is 2^(14) (16,384) octets. The value advertised 1830 by an endpoint MUST be between this initial value and the maximum 1831 allowed frame size (2^(24)-1 or 16,777,215 octets), inclusive. 1832 Values outside this range MUST be treated as a connection error 1833 (Section 5.4.1) of type PROTOCOL_ERROR. 1835 SETTINGS_MAX_HEADER_LIST_SIZE (0x6): This advisory setting informs a 1836 peer of the maximum size of field section that the sender is 1837 prepared to accept, in octets. The value is based on the 1838 uncompressed size of field lines, including the length of the name 1839 and value in octets plus an overhead of 32 octets for each field 1840 line. 1842 For any given request, a lower limit than what is advertised MAY 1843 be enforced. The initial value of this setting is unlimited. 1845 An endpoint that receives a SETTINGS frame with any unknown or 1846 unsupported identifier MUST ignore that setting. 1848 6.5.3. Settings Synchronization 1850 Most values in SETTINGS benefit from or require an understanding of 1851 when the peer has received and applied the changed parameter values. 1852 In order to provide such synchronization timepoints, the recipient of 1853 a SETTINGS frame in which the ACK flag is not set MUST apply the 1854 updated parameters as soon as possible upon receipt. 1856 The values in the SETTINGS frame MUST be processed in the order they 1857 appear, with no other frame processing between values. Unsupported 1858 parameters MUST be ignored. Once all values have been processed, the 1859 recipient MUST immediately emit a SETTINGS frame with the ACK flag 1860 set. Upon receiving a SETTINGS frame with the ACK flag set, the 1861 sender of the altered parameters can rely on the setting having been 1862 applied. 1864 If the sender of a SETTINGS frame does not receive an acknowledgement 1865 within a reasonable amount of time, it MAY issue a connection error 1866 (Section 5.4.1) of type SETTINGS_TIMEOUT. 1868 6.6. PUSH_PROMISE 1870 The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint 1871 in advance of streams the sender intends to initiate. The 1872 PUSH_PROMISE frame includes the unsigned 31-bit identifier of the 1873 stream the endpoint plans to create along with a field section that 1874 provides additional context for the stream. Section 8.2 contains a 1875 thorough description of the use of PUSH_PROMISE frames. 1877 +---------------+ 1878 |Pad Length? (8)| 1879 +-+-------------+-----------------------------------------------+ 1880 |R| Promised Stream ID (31) | 1881 +-+-----------------------------+-------------------------------+ 1882 | Field Block Fragment (*) ... 1883 +---------------------------------------------------------------+ 1884 | Padding (*) ... 1885 +---------------------------------------------------------------+ 1887 Figure 11: PUSH_PROMISE Frame Payload 1889 The PUSH_PROMISE frame payload has the following fields: 1891 Pad Length: An 8-bit field containing the length of the frame 1892 padding in units of octets. This field is only present if the 1893 PADDED flag is set. 1895 R: A single reserved bit. 1897 Promised Stream ID: An unsigned 31-bit integer that identifies the 1898 stream that is reserved by the PUSH_PROMISE. The promised stream 1899 identifier MUST be a valid choice for the next stream sent by the 1900 sender (see "new stream identifier" in Section 5.1.1). 1902 Field Block Fragment: A field block fragment (Section 4.3) 1903 containing request control data and header section. 1905 Padding: Padding octets. 1907 The PUSH_PROMISE frame defines the following flags: 1909 END_HEADERS (0x4): When set, bit 2 indicates that this frame 1910 contains an entire field block (Section 4.3) and is not followed 1911 by any CONTINUATION frames. 1913 A PUSH_PROMISE frame without the END_HEADERS flag set MUST be 1914 followed by a CONTINUATION frame for the same stream. A receiver 1915 MUST treat the receipt of any other type of frame or a frame on a 1916 different stream as a connection error (Section 5.4.1) of type 1917 PROTOCOL_ERROR. 1919 PADDED (0x8): When set, bit 3 indicates that the Pad Length field 1920 and any padding that it describes are present. 1922 PUSH_PROMISE frames MUST only be sent on a peer-initiated stream that 1923 is in either the "open" or "half-closed (remote)" state. The stream 1924 identifier of a PUSH_PROMISE frame indicates the stream it is 1925 associated with. If the stream identifier field specifies the value 1926 0x0, a recipient MUST respond with a connection error (Section 5.4.1) 1927 of type PROTOCOL_ERROR. 1929 Promised streams are not required to be used in the order they are 1930 promised. The PUSH_PROMISE only reserves stream identifiers for 1931 later use. 1933 PUSH_PROMISE MUST NOT be sent if the SETTINGS_ENABLE_PUSH setting of 1934 the peer endpoint is set to 0. An endpoint that has set this setting 1935 and has received acknowledgement MUST treat the receipt of a 1936 PUSH_PROMISE frame as a connection error (Section 5.4.1) of type 1937 PROTOCOL_ERROR. 1939 Recipients of PUSH_PROMISE frames can choose to reject promised 1940 streams by returning a RST_STREAM referencing the promised stream 1941 identifier back to the sender of the PUSH_PROMISE. 1943 A PUSH_PROMISE frame modifies the connection state in two ways. 1944 First, the inclusion of a field block (Section 4.3) potentially 1945 modifies the state maintained for field section compression. Second, 1946 PUSH_PROMISE also reserves a stream for later use, causing the 1947 promised stream to enter the "reserved" state. A sender MUST NOT 1948 send a PUSH_PROMISE on a stream unless that stream is either "open" 1949 or "half-closed (remote)"; the sender MUST ensure that the promised 1950 stream is a valid choice for a new stream identifier (Section 5.1.1) 1951 (that is, the promised stream MUST be in the "idle" state). 1953 Since PUSH_PROMISE reserves a stream, ignoring a PUSH_PROMISE frame 1954 causes the stream state to become indeterminate. A receiver MUST 1955 treat the receipt of a PUSH_PROMISE on a stream that is neither 1956 "open" nor "half-closed (local)" as a connection error 1957 (Section 5.4.1) of type PROTOCOL_ERROR. However, an endpoint that 1958 has sent RST_STREAM on the associated stream MUST handle PUSH_PROMISE 1959 frames that might have been created before the RST_STREAM frame is 1960 received and processed. 1962 A receiver MUST treat the receipt of a PUSH_PROMISE that promises an 1963 illegal stream identifier (Section 5.1.1) as a connection error 1964 (Section 5.4.1) of type PROTOCOL_ERROR. Note that an illegal stream 1965 identifier is an identifier for a stream that is not currently in the 1966 "idle" state. 1968 The PUSH_PROMISE frame can include padding. Padding fields and flags 1969 are identical to those defined for DATA frames (Section 6.1). 1971 6.7. PING 1973 The PING frame (type=0x6) is a mechanism for measuring a minimal 1974 round-trip time from the sender, as well as determining whether an 1975 idle connection is still functional. PING frames can be sent from 1976 any endpoint. 1978 +---------------------------------------------------------------+ 1979 | | 1980 | Opaque Data (64) | 1981 | | 1982 +---------------------------------------------------------------+ 1984 Figure 12: PING Frame Payload 1986 In addition to the frame header, PING frames MUST contain 8 octets of 1987 opaque data in the frame payload. A sender can include any value it 1988 chooses and use those octets in any fashion. 1990 Receivers of a PING frame that does not include an ACK flag MUST send 1991 a PING frame with the ACK flag set in response, with an identical 1992 frame payload. PING responses SHOULD be given higher priority than 1993 any other frame. 1995 The PING frame defines the following flags: 1997 ACK (0x1): When set, bit 0 indicates that this PING frame is a PING 1998 response. An endpoint MUST set this flag in PING responses. An 1999 endpoint MUST NOT respond to PING frames containing this flag. 2001 PING frames are not associated with any individual stream. If a PING 2002 frame is received with a stream identifier field value other than 2003 0x0, the recipient MUST respond with a connection error 2004 (Section 5.4.1) of type PROTOCOL_ERROR. 2006 Receipt of a PING frame with a length field value other than 8 MUST 2007 be treated as a connection error (Section 5.4.1) of type 2008 FRAME_SIZE_ERROR. 2010 6.8. GOAWAY 2012 The GOAWAY frame (type=0x7) is used to initiate shutdown of a 2013 connection or to signal serious error conditions. GOAWAY allows an 2014 endpoint to gracefully stop accepting new streams while still 2015 finishing processing of previously established streams. This enables 2016 administrative actions, like server maintenance. 2018 There is an inherent race condition between an endpoint starting new 2019 streams and the remote sending a GOAWAY frame. To deal with this 2020 case, the GOAWAY contains the stream identifier of the last peer- 2021 initiated stream that was or might be processed on the sending 2022 endpoint in this connection. For instance, if the server sends a 2023 GOAWAY frame, the identified stream is the highest-numbered stream 2024 initiated by the client. 2026 Once sent, the sender will ignore frames sent on streams initiated by 2027 the receiver if the stream has an identifier higher than the included 2028 last stream identifier. Receivers of a GOAWAY frame MUST NOT open 2029 additional streams on the connection, although a new connection can 2030 be established for new streams. 2032 If the receiver of the GOAWAY has sent data on streams with a higher 2033 stream identifier than what is indicated in the GOAWAY frame, those 2034 streams are not or will not be processed. The receiver of the GOAWAY 2035 frame can treat the streams as though they had never been created at 2036 all, thereby allowing those streams to be retried later on a new 2037 connection. 2039 Endpoints SHOULD always send a GOAWAY frame before closing a 2040 connection so that the remote peer can know whether a stream has been 2041 partially processed or not. For example, if an HTTP client sends a 2042 POST at the same time that a server closes a connection, the client 2043 cannot know if the server started to process that POST request if the 2044 server does not send a GOAWAY frame to indicate what streams it might 2045 have acted on. 2047 An endpoint might choose to close a connection without sending a 2048 GOAWAY for misbehaving peers. 2050 A GOAWAY frame might not immediately precede closing of the 2051 connection; a receiver of a GOAWAY that has no more use for the 2052 connection SHOULD still send a GOAWAY frame before terminating the 2053 connection. 2055 +-+-------------------------------------------------------------+ 2056 |R| Last-Stream-ID (31) | 2057 +-+-------------------------------------------------------------+ 2058 | Error Code (32) | 2059 +---------------------------------------------------------------+ 2060 | Additional Debug Data (*) | 2061 +---------------------------------------------------------------+ 2063 Figure 13: GOAWAY Frame Payload 2065 The GOAWAY frame does not define any flags. 2067 The GOAWAY frame applies to the connection, not a specific stream. 2068 An endpoint MUST treat a GOAWAY frame with a stream identifier other 2069 than 0x0 as a connection error (Section 5.4.1) of type 2070 PROTOCOL_ERROR. 2072 The last stream identifier in the GOAWAY frame contains the highest- 2073 numbered stream identifier for which the sender of the GOAWAY frame 2074 might have taken some action on or might yet take action on. All 2075 streams up to and including the identified stream might have been 2076 processed in some way. The last stream identifier can be set to 0 if 2077 no streams were processed. 2079 | Note: In this context, "processed" means that some data from 2080 | the stream was passed to some higher layer of software that 2081 | might have taken some action as a result. 2083 If a connection terminates without a GOAWAY frame, the last stream 2084 identifier is effectively the highest possible stream identifier. 2086 On streams with lower- or equal-numbered identifiers that were not 2087 closed completely prior to the connection being closed, reattempting 2088 requests, transactions, or any protocol activity is not possible, 2089 with the exception of idempotent actions like HTTP GET, PUT, or 2090 DELETE. Any protocol activity that uses higher-numbered streams can 2091 be safely retried using a new connection. 2093 Activity on streams numbered lower or equal to the last stream 2094 identifier might still complete successfully. The sender of a GOAWAY 2095 frame might gracefully shut down a connection by sending a GOAWAY 2096 frame, maintaining the connection in an "open" state until all in- 2097 progress streams complete. 2099 An endpoint MAY send multiple GOAWAY frames if circumstances change. 2100 For instance, an endpoint that sends GOAWAY with NO_ERROR during 2101 graceful shutdown could subsequently encounter a condition that 2102 requires immediate termination of the connection. The last stream 2103 identifier from the last GOAWAY frame received indicates which 2104 streams could have been acted upon. Endpoints MUST NOT increase the 2105 value they send in the last stream identifier, since the peers might 2106 already have retried unprocessed requests on another connection. 2108 A client that is unable to retry requests loses all requests that are 2109 in flight when the server closes the connection. This is especially 2110 true for intermediaries that might not be serving clients using 2111 HTTP/2. A server that is attempting to gracefully shut down a 2112 connection SHOULD send an initial GOAWAY frame with the last stream 2113 identifier set to 2^(31)-1 and a NO_ERROR code. This signals to the 2114 client that a shutdown is imminent and that initiating further 2115 requests is prohibited. After allowing time for any in-flight stream 2116 creation (at least one round-trip time), the server can send another 2117 GOAWAY frame with an updated last stream identifier. This ensures 2118 that a connection can be cleanly shut down without losing requests. 2120 After sending a GOAWAY frame, the sender can discard frames for 2121 streams initiated by the receiver with identifiers higher than the 2122 identified last stream. However, any frames that alter connection 2123 state cannot be completely ignored. For instance, HEADERS, 2124 PUSH_PROMISE, and CONTINUATION frames MUST be minimally processed to 2125 ensure the state maintained for field section compression is 2126 consistent (see Section 4.3); similarly, DATA frames MUST be counted 2127 toward the connection flow-control window. Failure to process these 2128 frames can cause flow control or field section compression state to 2129 become unsynchronized. 2131 The GOAWAY frame also contains a 32-bit error code (Section 7) that 2132 contains the reason for closing the connection. 2134 Endpoints MAY append opaque data to the frame payload of any GOAWAY 2135 frame. Additional debug data is intended for diagnostic purposes 2136 only and carries no semantic value. Debug information could contain 2137 security- or privacy-sensitive data. Logged or otherwise 2138 persistently stored debug data MUST have adequate safeguards to 2139 prevent unauthorized access. 2141 6.9. WINDOW_UPDATE 2143 The WINDOW_UPDATE frame (type=0x8) is used to implement flow control; 2144 see Section 5.2 for an overview. 2146 Flow control operates at two levels: on each individual stream and on 2147 the entire connection. 2149 Both types of flow control are hop by hop, that is, only between the 2150 two endpoints. Intermediaries do not forward WINDOW_UPDATE frames 2151 between dependent connections. However, throttling of data transfer 2152 by any receiver can indirectly cause the propagation of flow-control 2153 information toward the original sender. 2155 Flow control only applies to frames that are identified as being 2156 subject to flow control. Of the frame types defined in this 2157 document, this includes only DATA frames. Frames that are exempt 2158 from flow control MUST be accepted and processed, unless the receiver 2159 is unable to assign resources to handling the frame. A receiver MAY 2160 respond with a stream error (Section 5.4.2) or connection error 2161 (Section 5.4.1) of type FLOW_CONTROL_ERROR if it is unable to accept 2162 a frame. 2164 +-+-------------------------------------------------------------+ 2165 |R| Window Size Increment (31) | 2166 +-+-------------------------------------------------------------+ 2168 Figure 14: WINDOW_UPDATE Frame Payload 2170 The frame payload of a WINDOW_UPDATE frame is one reserved bit plus 2171 an unsigned 31-bit integer indicating the number of octets that the 2172 sender can transmit in addition to the existing flow-control window. 2173 The legal range for the increment to the flow-control window is 1 to 2174 2^(31)-1 (2,147,483,647) octets. 2176 The WINDOW_UPDATE frame does not define any flags. 2178 The WINDOW_UPDATE frame can be specific to a stream or to the entire 2179 connection. In the former case, the frame's stream identifier 2180 indicates the affected stream; in the latter, the value "0" indicates 2181 that the entire connection is the subject of the frame. 2183 A receiver MUST treat the receipt of a WINDOW_UPDATE frame with an 2184 flow-control window increment of 0 as a stream error (Section 5.4.2) 2185 of type PROTOCOL_ERROR; errors on the connection flow-control window 2186 MUST be treated as a connection error (Section 5.4.1). 2188 WINDOW_UPDATE can be sent by a peer that has sent a frame bearing the 2189 END_STREAM flag. This means that a receiver could receive a 2190 WINDOW_UPDATE frame on a "half-closed (remote)" or "closed" stream. 2191 A receiver MUST NOT treat this as an error (see Section 5.1). 2193 A receiver that receives a flow-controlled frame MUST always account 2194 for its contribution against the connection flow-control window, 2195 unless the receiver treats this as a connection error 2196 (Section 5.4.1). This is necessary even if the frame is in error. 2198 The sender counts the frame toward the flow-control window, but if 2199 the receiver does not, the flow-control window at the sender and 2200 receiver can become different. 2202 A WINDOW_UPDATE frame with a length other than 4 octets MUST be 2203 treated as a connection error (Section 5.4.1) of type 2204 FRAME_SIZE_ERROR. 2206 6.9.1. The Flow-Control Window 2208 Flow control in HTTP/2 is implemented using a window kept by each 2209 sender on every stream. The flow-control window is a simple integer 2210 value that indicates how many octets of data the sender is permitted 2211 to transmit; as such, its size is a measure of the buffering capacity 2212 of the receiver. 2214 Two flow-control windows are applicable: the stream flow-control 2215 window and the connection flow-control window. The sender MUST NOT 2216 send a flow-controlled frame with a length that exceeds the space 2217 available in either of the flow-control windows advertised by the 2218 receiver. Frames with zero length with the END_STREAM flag set (that 2219 is, an empty DATA frame) MAY be sent if there is no available space 2220 in either flow-control window. 2222 For flow-control calculations, the 9-octet frame header is not 2223 counted. 2225 After sending a flow-controlled frame, the sender reduces the space 2226 available in both windows by the length of the transmitted frame. 2228 The receiver of a frame sends a WINDOW_UPDATE frame as it consumes 2229 data and frees up space in flow-control windows. Separate 2230 WINDOW_UPDATE frames are sent for the stream- and connection-level 2231 flow-control windows. 2233 A sender that receives a WINDOW_UPDATE frame updates the 2234 corresponding window by the amount specified in the frame. 2236 A sender MUST NOT allow a flow-control window to exceed 2^(31)-1 2237 octets. If a sender receives a WINDOW_UPDATE that causes a flow- 2238 control window to exceed this maximum, it MUST terminate either the 2239 stream or the connection, as appropriate. For streams, the sender 2240 sends a RST_STREAM with an error code of FLOW_CONTROL_ERROR; for the 2241 connection, a GOAWAY frame with an error code of FLOW_CONTROL_ERROR 2242 is sent. 2244 Flow-controlled frames from the sender and WINDOW_UPDATE frames from 2245 the receiver are completely asynchronous with respect to each other. 2246 This property allows a receiver to aggressively update the window 2247 size kept by the sender to prevent streams from stalling. 2249 6.9.2. Initial Flow-Control Window Size 2251 When an HTTP/2 connection is first established, new streams are 2252 created with an initial flow-control window size of 65,535 octets. 2253 The connection flow-control window is also 65,535 octets. Both 2254 endpoints can adjust the initial window size for new streams by 2255 including a value for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS 2256 frame that forms part of the connection preface. The connection 2257 flow-control window can only be changed using WINDOW_UPDATE frames. 2259 Prior to receiving a SETTINGS frame that sets a value for 2260 SETTINGS_INITIAL_WINDOW_SIZE, an endpoint can only use the default 2261 initial window size when sending flow-controlled frames. Similarly, 2262 the connection flow-control window is set to the default initial 2263 window size until a WINDOW_UPDATE frame is received. 2265 In addition to changing the flow-control window for streams that are 2266 not yet active, a SETTINGS frame can alter the initial flow-control 2267 window size for streams with active flow-control windows (that is, 2268 streams in the "open" or "half-closed (remote)" state). When the 2269 value of SETTINGS_INITIAL_WINDOW_SIZE changes, a receiver MUST adjust 2270 the size of all stream flow-control windows that it maintains by the 2271 difference between the new value and the old value. 2273 A change to SETTINGS_INITIAL_WINDOW_SIZE can cause the available 2274 space in a flow-control window to become negative. A sender MUST 2275 track the negative flow-control window and MUST NOT send new flow- 2276 controlled frames until it receives WINDOW_UPDATE frames that cause 2277 the flow-control window to become positive. 2279 For example, if the client sends 60 KB immediately on connection 2280 establishment and the server sets the initial window size to be 16 2281 KB, the client will recalculate the available flow-control window to 2282 be -44 KB on receipt of the SETTINGS frame. The client retains a 2283 negative flow-control window until WINDOW_UPDATE frames restore the 2284 window to being positive, after which the client can resume sending. 2286 A SETTINGS frame cannot alter the connection flow-control window. 2288 An endpoint MUST treat a change to SETTINGS_INITIAL_WINDOW_SIZE that 2289 causes any flow-control window to exceed the maximum size as a 2290 connection error (Section 5.4.1) of type FLOW_CONTROL_ERROR. 2292 6.9.3. Reducing the Stream Window Size 2294 A receiver that wishes to use a smaller flow-control window than the 2295 current size can send a new SETTINGS frame. However, the receiver 2296 MUST be prepared to receive data that exceeds this window size, since 2297 the sender might send data that exceeds the lower limit prior to 2298 processing the SETTINGS frame. 2300 After sending a SETTINGS frame that reduces the initial flow-control 2301 window size, a receiver MAY continue to process streams that exceed 2302 flow-control limits. Allowing streams to continue does not allow the 2303 receiver to immediately reduce the space it reserves for flow-control 2304 windows. Progress on these streams can also stall, since 2305 WINDOW_UPDATE frames are needed to allow the sender to resume 2306 sending. The receiver MAY instead send a RST_STREAM with an error 2307 code of FLOW_CONTROL_ERROR for the affected streams. 2309 6.10. CONTINUATION 2311 The CONTINUATION frame (type=0x9) is used to continue a sequence of 2312 field block fragments (Section 4.3). Any number of CONTINUATION 2313 frames can be sent, as long as the preceding frame is on the same 2314 stream and is a HEADERS, PUSH_PROMISE, or CONTINUATION frame without 2315 the END_HEADERS flag set. 2317 +---------------------------------------------------------------+ 2318 | Field Block Fragment (*) ... 2319 +---------------------------------------------------------------+ 2321 Figure 15: CONTINUATION Frame Payload 2323 The CONTINUATION frame payload contains a field block fragment 2324 (Section 4.3). 2326 The CONTINUATION frame defines the following flag: 2328 END_HEADERS (0x4): When set, bit 2 indicates that this frame ends a 2329 field block (Section 4.3). 2331 If the END_HEADERS bit is not set, this frame MUST be followed by 2332 another CONTINUATION frame. A receiver MUST treat the receipt of 2333 any other type of frame or a frame on a different stream as a 2334 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 2336 The CONTINUATION frame changes the connection state as defined in 2337 Section 4.3. 2339 CONTINUATION frames MUST be associated with a stream. If a 2340 CONTINUATION frame is received whose stream identifier field is 0x0, 2341 the recipient MUST respond with a connection error (Section 5.4.1) of 2342 type PROTOCOL_ERROR. 2344 A CONTINUATION frame MUST be preceded by a HEADERS, PUSH_PROMISE or 2345 CONTINUATION frame without the END_HEADERS flag set. A recipient 2346 that observes violation of this rule MUST respond with a connection 2347 error (Section 5.4.1) of type PROTOCOL_ERROR. 2349 7. Error Codes 2351 Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY 2352 frames to convey the reasons for the stream or connection error. 2354 Error codes share a common code space. Some error codes apply only 2355 to either streams or the entire connection and have no defined 2356 semantics in the other context. 2358 The following error codes are defined: 2360 NO_ERROR (0x0): The associated condition is not a result of an 2361 error. For example, a GOAWAY might include this code to indicate 2362 graceful shutdown of a connection. 2364 PROTOCOL_ERROR (0x1): The endpoint detected an unspecific protocol 2365 error. This error is for use when a more specific error code is 2366 not available. 2368 INTERNAL_ERROR (0x2): The endpoint encountered an unexpected 2369 internal error. 2371 FLOW_CONTROL_ERROR (0x3): The endpoint detected that its peer 2372 violated the flow-control protocol. 2374 SETTINGS_TIMEOUT (0x4): The endpoint sent a SETTINGS frame but did 2375 not receive a response in a timely manner. See Section 6.5.3 2376 ("Settings Synchronization"). 2378 STREAM_CLOSED (0x5): The endpoint received a frame after a stream 2379 was half-closed. 2381 FRAME_SIZE_ERROR (0x6): The endpoint received a frame with an 2382 invalid size. 2384 REFUSED_STREAM (0x7): The endpoint refused the stream prior to 2385 performing any application processing (see Section 8.1.4 for 2386 details). 2388 CANCEL (0x8): Used by the endpoint to indicate that the stream is no 2389 longer needed. 2391 COMPRESSION_ERROR (0x9): The endpoint is unable to maintain the 2392 field section compression context for the connection. 2394 CONNECT_ERROR (0xa): The connection established in response to a 2395 CONNECT request (Section 8.3) was reset or abnormally closed. 2397 ENHANCE_YOUR_CALM (0xb): The endpoint detected that its peer is 2398 exhibiting a behavior that might be generating excessive load. 2400 INADEQUATE_SECURITY (0xc): The underlying transport has properties 2401 that do not meet minimum security requirements (see Section 9.2). 2403 HTTP_1_1_REQUIRED (0xd): The endpoint requires that HTTP/1.1 be used 2404 instead of HTTP/2. 2406 Unknown or unsupported error codes MUST NOT trigger any special 2407 behavior. These MAY be treated by an implementation as being 2408 equivalent to INTERNAL_ERROR. 2410 8. HTTP Message Exchanges 2412 HTTP/2 defines a framing of the HTTP message abstraction (Section 6 2413 of [HTTP]). 2415 8.1. HTTP Message Framing 2417 A client sends an HTTP request on a new stream, using a previously 2418 unused stream identifier (Section 5.1.1). A server sends an HTTP 2419 response on the same stream as the request. 2421 An HTTP message (request or response) consists of: 2423 1. one HEADERS frame (followed by zero or more CONTINUATION frames) 2424 containing the header section (see Section 6.3 of [HTTP]), 2426 2. zero or more DATA frames containing the message content (see 2427 Section 6.4 of [HTTP]), and 2429 3. optionally, one HEADERS frame, followed by zero or more 2430 CONTINUATION frames containing the trailer-part, if present (see 2431 Section 6.5 of [HTTP]). 2433 For a response only, a server MAY send any number of interim 2434 responses before the HEADERS frame containing a final response. An 2435 interim response consists of a HEADERS frames (which might be 2436 followed by zero or more CONTINUATION frames) containing the control 2437 data and header section of an interim (1xx) HTTP response (see 2438 Section 15 of [HTTP]). A HEADERS frame with an END_STREAM flag that 2439 carries an informational status code is malformed (Section 8.1.2.6). 2441 The last frame in the sequence bears an END_STREAM flag, noting that 2442 a HEADERS frame bearing the END_STREAM flag can be followed by 2443 CONTINUATION frames that carry any remaining fragments of the field 2444 block. 2446 Other frames (from any stream) MUST NOT occur between the HEADERS 2447 frame and any CONTINUATION frames that might follow. 2449 HTTP/2 uses DATA frames to carry message content. The "chunked" 2450 transfer encoding defined in Section 7.1 of [HTTP11] cannot be used 2451 in HTTP/2. 2453 Trailer fields are carried in a field block that also terminates the 2454 stream. That is, trailer fields comprise a sequence starting with a 2455 HEADERS frame, followed by zero or more CONTINUATION frames, where 2456 the HEADERS frame bears an END_STREAM flag. Trailers MUST NOT 2457 include pseudo-header fields (Section 8.1.2.1). An endpoint that 2458 receives pseudo-header fields in trailers MUST treat the request or 2459 response as malformed (Section 8.1.2.6). 2461 An endpoint that receives a HEADERS frame without the END_STREAM flag 2462 set after receiving the HEADERS frame that opens a request or after 2463 receiving a final (non-informational) status code MUST treat the 2464 corresponding request or response as malformed (Section 8.1.2.6). 2466 An HTTP request/response exchange fully consumes a single stream. A 2467 request starts with the HEADERS frame that puts the stream into an 2468 "open" state. The request ends with a frame bearing END_STREAM, 2469 which causes the stream to become "half-closed (local)" for the 2470 client and "half-closed (remote)" for the server. A response stream 2471 starts with zero or more interim responses in HEADERS frames or a 2472 HEADERS frame containing a final status code. 2474 An HTTP response is complete after the server sends -- or the client 2475 receives -- a frame with the END_STREAM flag set (including any 2476 CONTINUATION frames needed to complete a field block). A server can 2477 send a complete response prior to the client sending an entire 2478 request if the response does not depend on any portion of the request 2479 that has not been sent and received. When this is true, a server MAY 2480 request that the client abort transmission of a request without error 2481 by sending a RST_STREAM with an error code of NO_ERROR after sending 2482 a complete response (i.e., a frame with the END_STREAM flag). 2483 Clients MUST NOT discard responses as a result of receiving such a 2484 RST_STREAM, though clients can always discard responses at their 2485 discretion for other reasons. 2487 8.1.1. Upgrading from HTTP/2 2489 HTTP/2 removes support for the 101 (Switching Protocols) 2490 informational status code (Section 15.2.2 of [HTTP]). 2492 The semantics of 101 (Switching Protocols) aren't applicable to a 2493 multiplexed protocol. Alternative protocols are able to use the same 2494 mechanisms that HTTP/2 uses to negotiate their use (see Section 3). 2496 8.1.2. HTTP Fields 2498 HTTP fields carry information as a series of field lines, which are 2499 key-value pairs. For a listing of registered HTTP fields, see the 2500 "Hypertext Transfer Protocol (HTTP) Field Name Registry" registry 2501 maintained at https://www.iana.org/assignments/http-fields/. 2503 Just as in HTTP/1.x, field names are strings of ASCII characters that 2504 are compared in a case-insensitive fashion. Field names MUST be 2505 converted to lowercase prior to their encoding in HTTP/2. A request 2506 or response containing uppercase header field names MUST be treated 2507 as malformed (Section 8.1.2.6). 2509 8.1.2.1. Pseudo-Header Fields 2511 While HTTP/1.x used the message start-line (see Section 2.1 of 2512 [HTTP11]) to convey control data, HTTP/2 uses special pseudo-header 2513 fields beginning with ':' character (ASCII 0x3a) for this purpose. 2515 Pseudo-header fields are not HTTP header fields. Pseudo-header 2516 fields contain control data (see Section 6.2 of [HTTP]). Endpoints 2517 MUST NOT generate pseudo-header fields other than those defined in 2518 this document. Note that an extension could negotiate the use of 2519 additional pseudo-header fields; see Section 5.5. 2521 Pseudo-header fields are only valid in the context in which they are 2522 defined. Pseudo-header fields defined for requests MUST NOT appear 2523 in responses; pseudo-header fields defined for responses MUST NOT 2524 appear in requests. Pseudo-header fields MUST NOT appear in a 2525 trailer section. Endpoints MUST treat a request or response that 2526 contains undefined or invalid pseudo-header fields as malformed 2527 (Section 8.1.2.6). 2529 All pseudo-header fields MUST appear in a field block before all 2530 regular field lines. Any request or response that contains a pseudo- 2531 header field that appears in a field block after a regular field line 2532 MUST be treated as malformed (Section 8.1.2.6). 2534 8.1.2.2. Connection-Specific Header Fields 2536 HTTP/2 does not use the "Connection" header field to indicate 2537 connection-specific header fields; in this protocol, connection- 2538 specific metadata is conveyed by other means. An endpoint MUST NOT 2539 generate an HTTP/2 message containing connection-specific header 2540 fields; any message containing connection-specific header fields MUST 2541 be treated as malformed (Section 8.1.2.6). 2543 The only exception to this is the TE header field, which MAY be 2544 present in an HTTP/2 request; when it is, it MUST NOT contain any 2545 value other than "trailers". 2547 An intermediary transforming a HTTP/1.x message to HTTP/2 MUST remove 2548 connection-specific header fields as discussed in Section 7.6.1 of 2549 [HTTP], or their messages will be treated by other HTTP/2 endpoints 2550 as malformed (Section 8.1.2.6). 2552 | Note: HTTP/2 purposefully does not support upgrade to another 2553 | protocol. The handshake methods described in Section 3 are 2554 | believed sufficient to negotiate the use of alternative 2555 | protocols. 2557 8.1.2.3. Request Pseudo-Header Fields 2559 The following pseudo-header fields are defined for HTTP/2 requests: 2561 * The ":method" pseudo-header field includes the HTTP method 2562 (Section 9 of [HTTP]). 2564 * The ":scheme" pseudo-header field includes the scheme portion of 2565 the target URI (Section 3.1 of [RFC3986]). 2567 ":scheme" is not restricted to "http" and "https" schemed URIs. A 2568 proxy or gateway can translate requests for non-HTTP schemes, 2569 enabling the use of HTTP to interact with non-HTTP services. 2571 * The ":authority" pseudo-header field includes the authority 2572 portion of the target URI (Section 3.2 of [RFC3986]). The 2573 authority MUST NOT include the deprecated "userinfo" subcomponent 2574 for "http" or "https" schemed URIs. 2576 To ensure that HTTP/1.1 control data can be reproduced accurately, 2577 this pseudo-header field MUST be omitted when translating from an 2578 HTTP/1.1 request that has a request target in origin or asterisk 2579 form (see Section 3.2 of [HTTP11]). Clients that generate HTTP/2 2580 requests directly SHOULD use the ":authority" pseudo-header field 2581 instead of the "Host" header field. An intermediary that converts 2582 an HTTP/2 request to HTTP/1.1 MUST create a "Host" header field if 2583 one is not present in a request by copying the value of the 2584 ":authority" pseudo-header field. 2586 * The ":path" pseudo-header field includes the path and query parts 2587 of the target URI (the "path-absolute" production and optionally a 2588 '?' character followed by the "query" production (see Sections 3.3 2589 and 3.4 of [RFC3986]). A request in asterisk form includes the 2590 value '*' for the ":path" pseudo-header field. 2592 This pseudo-header field MUST NOT be empty for "http" or "https" 2593 URIs; "http" or "https" URIs that do not contain a path component 2594 MUST include a value of '/'. The exception to this rule is an 2595 OPTIONS request for an "http" or "https" URI that does not include 2596 a path component; these MUST include a ":path" pseudo-header field 2597 with a value of '*' (see Section 7.1 of [HTTP]). 2599 All HTTP/2 requests MUST include exactly one valid value for the 2600 ":method", ":scheme", and ":path" pseudo-header fields, unless it is 2601 a CONNECT request (Section 8.3). An HTTP request that omits 2602 mandatory pseudo-header fields is malformed (Section 8.1.2.6). 2604 Individual HTTP/2 requests do not carry an explicit indicator of 2605 protocol version. All HTTP/2 messages implicitly have a protocol 2606 version of "2.0" (see Section 6.2 of [HTTP]). 2608 8.1.2.4. Response Pseudo-Header Fields 2610 For HTTP/2 responses, a single ":status" pseudo-header field is 2611 defined that carries the HTTP status code field (see Section 15 of 2612 [HTTP]). This pseudo-header field MUST be included in all responses, 2613 including interim responses; otherwise, the response is malformed 2614 (Section 8.1.2.6). 2616 HTTP/2 responses implicitly have a protocol version of "2.0". 2618 8.1.2.5. Compressing the Cookie Header Field 2620 The Cookie header field [COOKIE] uses a semi-colon (";") to delimit 2621 cookie-pairs (or "crumbs"). This header field contains multiple 2622 values, but does not use a COMMA (",") as a separator, which prevents 2623 cookie-pairs from being sent on multiple field lines (see Section 5.2 2624 of [HTTP]). This can significantly reduce compression efficiency as 2625 updates to individual cookie-pairs would invalidate any field lines 2626 that are stored in the HPACK table. 2628 To allow for better compression efficiency, the Cookie header field 2629 MAY be split into separate header fields, each with one or more 2630 cookie-pairs. If there are multiple Cookie header fields after 2631 decompression, these MUST be concatenated into a single octet string 2632 using the two-octet delimiter of 0x3B, 0x20 (the ASCII string "; ") 2633 before being passed into a non-HTTP/2 context, such as an HTTP/1.1 2634 connection, or a generic HTTP server application. 2636 Therefore, the following two lists of Cookie header fields are 2637 semantically equivalent. 2639 cookie: a=b; c=d; e=f 2641 cookie: a=b 2642 cookie: c=d 2643 cookie: e=f 2645 8.1.2.6. Malformed Requests and Responses 2647 A malformed request or response is one that is an otherwise valid 2648 sequence of HTTP/2 frames but is invalid due to the presence of 2649 extraneous frames, prohibited fields or pseudo-header fields, the 2650 absence of mandatory fields or pseudo-header fields, or the inclusion 2651 of uppercase field names. 2653 A request or response that includes message content can include a 2654 "content-length" header field. A request or response is also 2655 malformed if the value of a "content-length" header field does not 2656 equal the sum of the DATA frame payload lengths that form the 2657 content. A response that is defined to have no content, as described 2658 in Section 6.4 of [HTTP], can have a non-zero "content-length" header 2659 field, even though no content is included in DATA frames. 2661 Intermediaries that process HTTP requests or responses (i.e., any 2662 intermediary not acting as a tunnel) MUST NOT forward a malformed 2663 request or response. Malformed requests or responses that are 2664 detected MUST be treated as a stream error (Section 5.4.2) of type 2665 PROTOCOL_ERROR. 2667 For malformed requests, a server MAY send an HTTP response prior to 2668 closing or resetting the stream. Clients MUST NOT accept a malformed 2669 response. Note that these requirements are intended to protect 2670 against several types of common attacks against HTTP; they are 2671 deliberately strict because being permissive can expose 2672 implementations to these vulnerabilities. 2674 8.1.3. Examples 2676 This section shows HTTP/1.1 requests and responses, with 2677 illustrations of equivalent HTTP/2 requests and responses. 2679 An HTTP GET request includes control data and a request header with 2680 no message content and is therefore transmitted as a single HEADERS 2681 frame, followed by zero or more CONTINUATION frames containing the 2682 serialized block of request header fields. The HEADERS frame in the 2683 following has both the END_HEADERS and END_STREAM flags set; no 2684 CONTINUATION frames are sent. 2686 GET /resource HTTP/1.1 HEADERS 2687 Host: example.org ==> + END_STREAM 2688 Accept: image/jpeg + END_HEADERS 2689 :method = GET 2690 :scheme = https 2691 :path = /resource 2692 host = example.org 2693 accept = image/jpeg 2695 Similarly, a response that includes only control data and a response 2696 header is transmitted as a HEADERS frame (again, followed by zero or 2697 more CONTINUATION frames) containing the serialized block of response 2698 header fields. 2700 HTTP/1.1 304 Not Modified HEADERS 2701 ETag: "xyzzy" ==> + END_STREAM 2702 Expires: Thu, 23 Jan ... + END_HEADERS 2703 :status = 304 2704 etag = "xyzzy" 2705 expires = Thu, 23 Jan ... 2707 An HTTP POST request that includes control data and a request header 2708 and message content is transmitted as one HEADERS frame, followed by 2709 zero or more CONTINUATION frames containing the request header, 2710 followed by one or more DATA frames, with the last CONTINUATION (or 2711 HEADERS) frame having the END_HEADERS flag set and the final DATA 2712 frame having the END_STREAM flag set: 2714 POST /resource HTTP/1.1 HEADERS 2715 Host: example.org ==> - END_STREAM 2716 Content-Type: image/jpeg - END_HEADERS 2717 Content-Length: 123 :method = POST 2718 :path = /resource 2719 {binary data} :scheme = https 2721 CONTINUATION 2722 + END_HEADERS 2723 content-type = image/jpeg 2724 host = example.org 2725 content-length = 123 2727 DATA 2728 + END_STREAM 2729 {binary data} 2731 Note that data contributing to any given field line could be spread 2732 between field block fragments. The allocation of field lines to 2733 frames in this example is illustrative only. 2735 A response that includes control data and a response header and 2736 message content is transmitted as a HEADERS frame, followed by zero 2737 or more CONTINUATION frames, followed by one or more DATA frames, 2738 with the last DATA frame in the sequence having the END_STREAM flag 2739 set: 2741 HTTP/1.1 200 OK HEADERS 2742 Content-Type: image/jpeg ==> - END_STREAM 2743 Content-Length: 123 + END_HEADERS 2744 :status = 200 2745 {binary data} content-type = image/jpeg 2746 content-length = 123 2748 DATA 2749 + END_STREAM 2750 {binary data} 2752 An informational response using a 1xx status code other than 101 is 2753 transmitted as a HEADERS frame, followed by zero or more CONTINUATION 2754 frames. 2756 A trailer section is sent as a field block after both the request or 2757 response field block and all the DATA frames have been sent. The 2758 HEADERS frame starting the field block that comprises the trailer 2759 section has the END_STREAM flag set. 2761 The following example includes both a 100 (Continue) status code, 2762 which is sent in response to a request containing a "100-continue" 2763 token in the Expect header field, and a trailer section: 2765 HTTP/1.1 100 Continue HEADERS 2766 Extension-Field: bar ==> - END_STREAM 2767 + END_HEADERS 2768 :status = 100 2769 extension-field = bar 2771 HTTP/1.1 200 OK HEADERS 2772 Content-Type: image/jpeg ==> - END_STREAM 2773 Transfer-Encoding: chunked + END_HEADERS 2774 Trailer: Foo :status = 200 2775 content-length = 123 2776 123 content-type = image/jpeg 2777 {binary data} trailer = Foo 2778 0 2779 Foo: bar DATA 2780 - END_STREAM 2781 {binary data} 2783 HEADERS 2784 + END_STREAM 2785 + END_HEADERS 2786 foo = bar 2788 8.1.4. Request Reliability Mechanisms in HTTP/2 2790 In general, an HTTP client is unable to retry a non-idempotent 2791 request when an error occurs because there is no means to determine 2792 the nature of the error. It is possible that some server processing 2793 occurred prior to the error, which could result in undesirable 2794 effects if the request were reattempted. 2796 HTTP/2 provides two mechanisms for providing a guarantee to a client 2797 that a request has not been processed: 2799 * The GOAWAY frame indicates the highest stream number that might 2800 have been processed. Requests on streams with higher numbers are 2801 therefore guaranteed to be safe to retry. 2803 * The REFUSED_STREAM error code can be included in a RST_STREAM 2804 frame to indicate that the stream is being closed prior to any 2805 processing having occurred. Any request that was sent on the 2806 reset stream can be safely retried. 2808 Requests that have not been processed have not failed; clients MAY 2809 automatically retry them, even those with non-idempotent methods. 2811 A server MUST NOT indicate that a stream has not been processed 2812 unless it can guarantee that fact. If frames that are on a stream 2813 are passed to the application layer for any stream, then 2814 REFUSED_STREAM MUST NOT be used for that stream, and a GOAWAY frame 2815 MUST include a stream identifier that is greater than or equal to the 2816 given stream identifier. 2818 In addition to these mechanisms, the PING frame provides a way for a 2819 client to easily test a connection. Connections that remain idle can 2820 become broken as some middleboxes (for instance, network address 2821 translators or load balancers) silently discard connection bindings. 2822 The PING frame allows a client to safely test whether a connection is 2823 still active without sending a request. 2825 8.2. Server Push 2827 HTTP/2 allows a server to pre-emptively send (or "push") responses 2828 (along with corresponding "promised" requests) to a client in 2829 association with a previous client-initiated request. This can be 2830 useful when the server knows the client will need to have those 2831 responses available in order to fully process the response to the 2832 original request. 2834 A client can request that server push be disabled, though this is 2835 negotiated for each hop independently. The SETTINGS_ENABLE_PUSH 2836 setting can be set to 0 to indicate that server push is disabled. 2838 Promised requests MUST be safe (see Section 9.2.1 of [HTTP]) and 2839 cacheable (see Section 9.2.3 of [HTTP]). Promised requests cannot 2840 include any content or a trailer section. Clients that receive a 2841 promised request that is not cacheable, that is not known to be safe, 2842 or that indicates the presence of request content MUST reset the 2843 promised stream with a stream error (Section 5.4.2) of type 2844 PROTOCOL_ERROR. Note this could result in the promised stream being 2845 reset if the client does not recognize a newly defined method as 2846 being safe. 2848 Pushed responses that are cacheable (see Section 3 of [CACHE]) can be 2849 stored by the client, if it implements an HTTP cache. Pushed 2850 responses are considered successfully validated on the origin server 2851 (e.g., if the "no-cache" cache response directive is present; see 2852 Section 5.2.2.3 of [CACHE]) while the stream identified by the 2853 promised stream ID is still open. 2855 Pushed responses that are not cacheable MUST NOT be stored by any 2856 HTTP cache. They MAY be made available to the application 2857 separately. 2859 The server MUST include a value in the ":authority" pseudo-header 2860 field for which the server is authoritative (see Section 10.1). A 2861 client MUST treat a PUSH_PROMISE for which the server is not 2862 authoritative as a stream error (Section 5.4.2) of type 2863 PROTOCOL_ERROR. 2865 An intermediary can receive pushes from the server and choose not to 2866 forward them on to the client. In other words, how to make use of 2867 the pushed information is up to that intermediary. Equally, the 2868 intermediary might choose to make additional pushes to the client, 2869 without any action taken by the server. 2871 A client cannot push. Thus, servers MUST treat the receipt of a 2872 PUSH_PROMISE frame as a connection error (Section 5.4.1) of type 2873 PROTOCOL_ERROR. Clients MUST reject any attempt to change the 2874 SETTINGS_ENABLE_PUSH setting to a value other than 0 by treating the 2875 message as a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 2877 8.2.1. Push Requests 2879 Server push is semantically equivalent to a server responding to a 2880 request; however, in this case, that request is also sent by the 2881 server, as a PUSH_PROMISE frame. 2883 The PUSH_PROMISE frame includes a field block that contains control 2884 data and a complete set of request header fields that the server 2885 attributes to the request. It is not possible to push a response to 2886 a request that includes message content. 2888 Promised requests are always associated with an explicit request from 2889 the client. The PUSH_PROMISE frames sent by the server are sent on 2890 that explicit request's stream. The PUSH_PROMISE frame also includes 2891 a promised stream identifier, chosen from the stream identifiers 2892 available to the server (see Section 5.1.1). 2894 The header fields in PUSH_PROMISE and any subsequent CONTINUATION 2895 frames MUST be a valid and complete set of request header fields 2896 (Section 8.1.2.3). The server MUST include a method in the ":method" 2897 pseudo-header field that is safe and cacheable. If a client receives 2898 a PUSH_PROMISE that does not include a complete and valid set of 2899 header fields or the ":method" pseudo-header field identifies a 2900 method that is not safe, it MUST respond with a stream error 2901 (Section 5.4.2) of type PROTOCOL_ERROR. 2903 The server SHOULD send PUSH_PROMISE (Section 6.6) frames prior to 2904 sending any frames that reference the promised responses. This 2905 avoids a race where clients issue requests prior to receiving any 2906 PUSH_PROMISE frames. 2908 For example, if the server receives a request for a document 2909 containing embedded links to multiple image files and the server 2910 chooses to push those additional images to the client, sending 2911 PUSH_PROMISE frames before the DATA frames that contain the image 2912 links ensures that the client is able to see that a resource will be 2913 pushed before discovering embedded links. Similarly, if the server 2914 pushes responses referenced by the field block (for instance, in Link 2915 header fields), sending a PUSH_PROMISE before sending the header 2916 block ensures that clients do not request those resources. 2918 PUSH_PROMISE frames MUST NOT be sent by the client. 2920 PUSH_PROMISE frames can be sent by the server in response to any 2921 client-initiated stream, but the stream MUST be in either the "open" 2922 or "half-closed (remote)" state with respect to the server. 2923 PUSH_PROMISE frames are interspersed with the frames that comprise a 2924 response, though they cannot be interspersed with HEADERS and 2925 CONTINUATION frames that comprise a single field block. 2927 Sending a PUSH_PROMISE frame creates a new stream and puts the stream 2928 into the "reserved (local)" state for the server and the "reserved 2929 (remote)" state for the client. 2931 8.2.2. Push Responses 2933 After sending the PUSH_PROMISE frame, the server can begin delivering 2934 the pushed response as a response (Section 8.1.2.4) on a server- 2935 initiated stream that uses the promised stream identifier. The 2936 server uses this stream to transmit an HTTP response, using the same 2937 sequence of frames as defined in Section 8.1. This stream becomes 2938 "half-closed" to the client (Section 5.1) after the initial HEADERS 2939 frame is sent. 2941 Once a client receives a PUSH_PROMISE frame and chooses to accept the 2942 pushed response, the client SHOULD NOT issue any requests for the 2943 promised response until after the promised stream has closed. 2945 If the client determines, for any reason, that it does not wish to 2946 receive the pushed response from the server or if the server takes 2947 too long to begin sending the promised response, the client can send 2948 a RST_STREAM frame, using either the CANCEL or REFUSED_STREAM code 2949 and referencing the pushed stream's identifier. 2951 A client can use the SETTINGS_MAX_CONCURRENT_STREAMS setting to limit 2952 the number of responses that can be concurrently pushed by a server. 2953 Advertising a SETTINGS_MAX_CONCURRENT_STREAMS value of zero disables 2954 server push by preventing the server from creating the necessary 2955 streams. This does not prohibit a server from sending PUSH_PROMISE 2956 frames; clients need to reset any promised streams that are not 2957 wanted. 2959 Clients receiving a pushed response MUST validate that either the 2960 server is authoritative (see Section 10.1) or the proxy that provided 2961 the pushed response is configured for the corresponding request. For 2962 example, a server that offers a certificate for only the 2963 "example.com" DNS-ID is not permitted to push a response for 2964 "https://www.example.org/doc". 2966 The response for a PUSH_PROMISE stream begins with a HEADERS frame, 2967 which immediately puts the stream into the "half-closed (remote)" 2968 state for the server and "half-closed (local)" state for the client, 2969 and ends with a frame bearing END_STREAM, which places the stream in 2970 the "closed" state. 2972 | Note: The client never sends a frame with the END_STREAM flag 2973 | for a server push. 2975 8.3. The CONNECT Method 2977 In HTTP/1.x, the pseudo-method CONNECT (Section 9.3.6 of [HTTP]) is 2978 used to convert an HTTP connection into a tunnel to a remote host. 2979 CONNECT is primarily used with HTTP proxies to establish a TLS 2980 session with an origin server for the purposes of interacting with 2981 "https" resources. 2983 In HTTP/2, the CONNECT method is used to establish a tunnel over a 2984 single HTTP/2 stream to a remote host for similar purposes. A 2985 CONNECT header section is constructed as defined in Section 8.1.2.3 2986 ("Request Pseudo-Header Fields"), with a few differences. 2987 Specifically: 2989 * The ":method" pseudo-header field is set to "CONNECT". 2991 * The ":scheme" and ":path" pseudo-header fields MUST be omitted. 2993 * The ":authority" pseudo-header field contains the host and port to 2994 connect to (equivalent to the authority-form of the request-target 2995 of CONNECT requests; see Section 3.2.3 of [HTTP11]). 2997 A CONNECT request that does not conform to these restrictions is 2998 malformed (Section 8.1.2.6). 3000 A proxy that supports CONNECT establishes a TCP connection [TCP] to 3001 the host and port identified in the ":authority" pseudo-header field. 3002 Once this connection is successfully established, the proxy sends a 3003 HEADERS frame containing a 2xx series status code to the client, as 3004 defined in Section 9.3.6 of [HTTP]. 3006 After the initial HEADERS frame sent by each peer, all subsequent 3007 DATA frames correspond to data sent on the TCP connection. The frame 3008 payload of any DATA frames sent by the client is transmitted by the 3009 proxy to the TCP server; data received from the TCP server is 3010 assembled into DATA frames by the proxy. Frame types other than DATA 3011 or stream management frames (RST_STREAM, WINDOW_UPDATE, and PRIORITY) 3012 MUST NOT be sent on a connected stream and MUST be treated as a 3013 stream error (Section 5.4.2) if received. 3015 The TCP connection can be closed by either peer. The END_STREAM flag 3016 on a DATA frame is treated as being equivalent to the TCP FIN bit. A 3017 client is expected to send a DATA frame with the END_STREAM flag set 3018 after receiving a frame bearing the END_STREAM flag. A proxy that 3019 receives a DATA frame with the END_STREAM flag set sends the attached 3020 data with the FIN bit set on the last TCP segment. A proxy that 3021 receives a TCP segment with the FIN bit set sends a DATA frame with 3022 the END_STREAM flag set. Note that the final TCP segment or DATA 3023 frame could be empty. 3025 A TCP connection error is signaled with RST_STREAM. A proxy treats 3026 any error in the TCP connection, which includes receiving a TCP 3027 segment with the RST bit set, as a stream error (Section 5.4.2) of 3028 type CONNECT_ERROR. Correspondingly, a proxy MUST send a TCP segment 3029 with the RST bit set if it detects an error with the stream or the 3030 HTTP/2 connection. 3032 9. Additional HTTP Requirements/Considerations 3034 This section outlines attributes of the HTTP protocol that improve 3035 interoperability, reduce exposure to known security vulnerabilities, 3036 or reduce the potential for implementation variation. 3038 9.1. Connection Management 3040 HTTP/2 connections are persistent. For best performance, it is 3041 expected that clients will not close connections until it is 3042 determined that no further communication with a server is necessary 3043 (for example, when a user navigates away from a particular web page) 3044 or until the server closes the connection. 3046 Clients SHOULD NOT open more than one HTTP/2 connection to a given 3047 host and port pair, where the host is derived from a URI, a selected 3048 alternative service [ALT-SVC], or a configured proxy. 3050 A client can create additional connections as replacements, either to 3051 replace connections that are near to exhausting the available stream 3052 identifier space (Section 5.1.1), to refresh the keying material for 3053 a TLS connection, or to replace connections that have encountered 3054 errors (Section 5.4.1). 3056 A client MAY open multiple connections to the same IP address and TCP 3057 port using different Server Name Indication [TLS-EXT] values or to 3058 provide different TLS client certificates but SHOULD avoid creating 3059 multiple connections with the same configuration. 3061 Servers are encouraged to maintain open connections for as long as 3062 possible but are permitted to terminate idle connections if 3063 necessary. When either endpoint chooses to close the transport-layer 3064 TCP connection, the terminating endpoint SHOULD first send a GOAWAY 3065 (Section 6.8) frame so that both endpoints can reliably determine 3066 whether previously sent frames have been processed and gracefully 3067 complete or terminate any necessary remaining tasks. 3069 9.1.1. Connection Reuse 3071 Connections that are made to an origin server, either directly or 3072 through a tunnel created using the CONNECT method (Section 8.3), MAY 3073 be reused for requests with multiple different URI authority 3074 components. A connection can be reused as long as the origin server 3075 is authoritative (Section 10.1). For TCP connections without TLS, 3076 this depends on the host having resolved to the same IP address. 3078 For "https" resources, connection reuse additionally depends on 3079 having a certificate that is valid for the host in the URI. The 3080 certificate presented by the server MUST satisfy any checks that the 3081 client would perform when forming a new TLS connection for the host 3082 in the URI. A single certificate can be used to establish authority 3083 for multiple origins. Section 4.3 of [HTTP] describes how a client 3084 determines whether a server is authoritative for a URI. 3086 In some deployments, reusing a connection for multiple origins can 3087 result in requests being directed to the wrong origin server. For 3088 example, TLS termination might be performed by a middlebox that uses 3089 the TLS Server Name Indication (SNI) [TLS-EXT] extension to select an 3090 origin server. This means that it is possible for clients to send 3091 requests to servers that might not be the intended target for the 3092 request, even though the server is otherwise authoritative. 3094 A server that does not wish clients to reuse connections can indicate 3095 that it is not authoritative for a request by sending a 421 3096 (Misdirected Request) status code in response to the request (see 3097 Section 15.5.20 of [HTTP]). 3099 A client that is configured to use a proxy over HTTP/2 directs 3100 requests to that proxy through a single connection. That is, all 3101 requests sent via a proxy reuse the connection to the proxy. 3103 9.2. Use of TLS Features 3105 Implementations of HTTP/2 MUST use TLS version 1.2 [TLS12] or higher 3106 for HTTP/2 over TLS. The general TLS usage guidance in [TLSBCP] 3107 SHOULD be followed, with some additional restrictions that are 3108 specific to HTTP/2. 3110 The TLS implementation MUST support the Server Name Indication (SNI) 3111 [TLS-EXT] extension to TLS. If the server is identified by a domain 3112 name [DNS-TERMS], clients MUST send the server_name TLS extension 3113 unless an alternative mechanism to indicate the target host is used. 3115 Requirements for deployments of HTTP/2 that negotiate TLS 1.3 [TLS13] 3116 are included in Section 9.2.3. Deployments of TLS 1.2 are subject to 3117 the requirements in Section 9.2.1 and Section 9.2.2. Implementations 3118 are encouraged to provide defaults that comply, but it is recognized 3119 that deployments are ultimately responsible for compliance. 3121 9.2.1. TLS 1.2 Features 3123 This section describes restrictions on the TLS 1.2 feature set that 3124 can be used with HTTP/2. Due to deployment limitations, it might not 3125 be possible to fail TLS negotiation when these restrictions are not 3126 met. An endpoint MAY immediately terminate an HTTP/2 connection that 3127 does not meet these TLS requirements with a connection error 3128 (Section 5.4.1) of type INADEQUATE_SECURITY. 3130 A deployment of HTTP/2 over TLS 1.2 MUST disable compression. TLS 3131 compression can lead to the exposure of information that would not 3132 otherwise be revealed [RFC3749]. Generic compression is unnecessary 3133 since HTTP/2 provides compression features that are more aware of 3134 context and therefore likely to be more appropriate for use for 3135 performance, security, or other reasons. 3137 A deployment of HTTP/2 over TLS 1.2 MUST disable renegotiation. An 3138 endpoint MUST treat a TLS renegotiation as a connection error 3139 (Section 5.4.1) of type PROTOCOL_ERROR. Note that disabling 3140 renegotiation can result in long-lived connections becoming unusable 3141 due to limits on the number of messages the underlying cipher suite 3142 can encipher. 3144 An endpoint MAY use renegotiation to provide confidentiality 3145 protection for client credentials offered in the handshake, but any 3146 renegotiation MUST occur prior to sending the connection preface. A 3147 server SHOULD request a client certificate if it sees a renegotiation 3148 request immediately after establishing a connection. 3150 This effectively prevents the use of renegotiation in response to a 3151 request for a specific protected resource. A future specification 3152 might provide a way to support this use case. Alternatively, a 3153 server might use an error (Section 5.4) of type HTTP_1_1_REQUIRED to 3154 request the client use a protocol that supports renegotiation. 3156 Implementations MUST support ephemeral key exchange sizes of at least 3157 2048 bits for cipher suites that use ephemeral finite field Diffie- 3158 Hellman (DHE) [TLS13] and 224 bits for cipher suites that use 3159 ephemeral elliptic curve Diffie-Hellman (ECDHE) [RFC4492]. Clients 3160 MUST accept DHE sizes of up to 4096 bits. Endpoints MAY treat 3161 negotiation of key sizes smaller than the lower limits as a 3162 connection error (Section 5.4.1) of type INADEQUATE_SECURITY. 3164 9.2.2. TLS 1.2 Cipher Suites 3166 A deployment of HTTP/2 over TLS 1.2 SHOULD NOT use any of the cipher 3167 suites that are listed in the list of prohibited cipher suites 3168 (Appendix A). 3170 Endpoints MAY choose to generate a connection error (Section 5.4.1) 3171 of type INADEQUATE_SECURITY if one of the prohibited cipher suites is 3172 negotiated. A deployment that chooses to use a prohibited cipher 3173 suite risks triggering a connection error unless the set of potential 3174 peers is known to accept that cipher suite. 3176 Implementations MUST NOT generate this error in reaction to the 3177 negotiation of a cipher suite that is not prohibited. Consequently, 3178 when clients offer a cipher suite that is not prohibited, they have 3179 to be prepared to use that cipher suite with HTTP/2. 3181 The list of prohibited cipher suites includes the cipher suite that 3182 TLS 1.2 makes mandatory, which means that TLS 1.2 deployments could 3183 have non-intersecting sets of permitted cipher suites. To avoid this 3184 problem causing TLS handshake failures, deployments of HTTP/2 that 3185 use TLS 1.2 MUST support TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 3186 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186]. 3188 Note that clients might advertise support of cipher suites that are 3189 prohibited in order to allow for connection to servers that do not 3190 support HTTP/2. This allows servers to select HTTP/1.1 with a cipher 3191 suite that is prohibited in HTTP/2. However, this can result in 3192 HTTP/2 being negotiated with a prohibited cipher suite if the 3193 application protocol and cipher suite are independently selected. 3195 9.2.3. TLS 1.3 Features 3197 TLS 1.3 includes a number of features not available in earlier 3198 versions. This section discusses the use of these features. 3200 HTTP/2 servers MUST NOT send post-handshake TLS 1.3 3201 CertificateRequest messages. HTTP/2 clients MUST treat a TLS post- 3202 handshake CertificateRequest message as a connection error 3203 (Section 5.4.1) of type PROTOCOL_ERROR. 3205 The prohibition on post-handshake authentication applies even if the 3206 client offered the "post_handshake_auth" TLS extension. Post- 3207 handshake authentication support might be advertised independently of 3208 ALPN [TLS-ALPN]. Clients might offer the capability for use in other 3209 protocols, but inclusion of the extension cannot imply support within 3210 HTTP/2. 3212 [TLS13] defines other post-handshake messages, NewSessionTicket and 3213 KeyUpdate, which can be used as they have no direct interaction with 3214 HTTP/2. Unless the use of a new type of TLS message depends on an 3215 interaction with the application-layer protocol, that TLS message can 3216 be sent after the handshake completes. 3218 TLS early data MAY be used to send requests, provided that the 3219 guidance in [RFC8470] is observed. Clients send requests in early 3220 data assuming initial values for all server settings. 3222 10. Security Considerations 3223 10.1. Server Authority 3225 HTTP/2 relies on the HTTP definition of authority for determining 3226 whether a server is authoritative in providing a given response (see 3227 Section 4.3 of [HTTP]). This relies on local name resolution for the 3228 "http" URI scheme and the authenticated server identity for the 3229 "https" scheme. 3231 10.2. Cross-Protocol Attacks 3233 In a cross-protocol attack, an attacker causes a client to initiate a 3234 transaction in one protocol toward a server that understands a 3235 different protocol. An attacker might be able to cause the 3236 transaction to appear as a valid transaction in the second protocol. 3237 In combination with the capabilities of the web context, this can be 3238 used to interact with poorly protected servers in private networks. 3240 Completing a TLS handshake with an ALPN identifier for HTTP/2 can be 3241 considered sufficient protection against cross-protocol attacks. 3242 ALPN provides a positive indication that a server is willing to 3243 proceed with HTTP/2, which prevents attacks on other TLS-based 3244 protocols. 3246 The encryption in TLS makes it difficult for attackers to control the 3247 data that could be used in a cross-protocol attack on a cleartext 3248 protocol. 3250 The cleartext version of HTTP/2 has minimal protection against cross- 3251 protocol attacks. The connection preface (Section 3.5) contains a 3252 string that is designed to confuse HTTP/1.1 servers, but no special 3253 protection is offered for other protocols. A server that is willing 3254 to ignore parts of an HTTP/1.1 request containing an Upgrade header 3255 field in addition to the client connection preface could be exposed 3256 to a cross-protocol attack. 3258 10.3. Intermediary Encapsulation Attacks 3260 The HTTP/2 field block encoding allows the expression of names that 3261 are not valid field names in HTTP. Requests or responses containing 3262 invalid field names MUST be treated as malformed (Section 8.1.2.6). 3263 An intermediary therefore cannot translate an HTTP/2 request or 3264 response containing an invalid field name into an HTTP/1.1 message. 3266 Similarly, HTTP/2 allows field values that are not valid. While most 3267 of the values that can be encoded will not alter header field 3268 parsing, carriage return (CR, ASCII 0xd), line feed (LF, ASCII 0xa), 3269 and the zero character (NUL, ASCII 0x0) might be exploited by an 3270 attacker if they are translated verbatim. Any request or response 3271 that contains a character not permitted in a field value MUST be 3272 treated as malformed (Section 8.1.2.6). Valid characters are defined 3273 by the "field-content" ABNF rule in Section 5.5 of [HTTP]. 3275 10.4. Cacheability of Pushed Responses 3277 Pushed responses do not have an explicit request from the client; the 3278 request is provided by the server in the PUSH_PROMISE frame. 3280 Caching responses that are pushed is possible based on the guidance 3281 provided by the origin server in the Cache-Control header field. 3282 However, this can cause issues if a single server hosts more than one 3283 tenant. For example, a server might offer multiple users each a 3284 small portion of its URI space. 3286 Where multiple tenants share space on the same server, that server 3287 MUST ensure that tenants are not able to push representations of 3288 resources that they do not have authority over. Failure to enforce 3289 this would allow a tenant to provide a representation that would be 3290 served out of cache, overriding the actual representation that the 3291 authoritative tenant provides. 3293 Pushed responses for which an origin server is not authoritative (see 3294 Section 10.1) MUST NOT be used or cached. 3296 10.5. Denial-of-Service Considerations 3298 An HTTP/2 connection can demand a greater commitment of resources to 3299 operate than an HTTP/1.1 connection. The use of field section 3300 compression and flow control depend on a commitment of resources for 3301 storing a greater amount of state. Settings for these features 3302 ensure that memory commitments for these features are strictly 3303 bounded. 3305 The number of PUSH_PROMISE frames is not constrained in the same 3306 fashion. A client that accepts server push SHOULD limit the number 3307 of streams it allows to be in the "reserved (remote)" state. An 3308 excessive number of server push streams can be treated as a stream 3309 error (Section 5.4.2) of type ENHANCE_YOUR_CALM. 3311 A number of HTTP/2 implementations were found to be vulnerable to 3312 denial of service [NFLX-2019-002]. The following lists known ways 3313 that implementations might be subject to denial of service attack: 3315 * Inefficient tracking of outstanding outbound frames can lead to 3316 overload if an adversary can cause large numbers of frames to be 3317 enqueued for sending. A peer could use one of several techniques 3318 to cause large numbers of frames to be generated: 3320 - Providing tiny increments to flow control in WINDOW_UPDATE 3321 frames can cause a sender to generate a large number of DATA 3322 frames. 3324 - An endpoint is required to respond to a PING frame. 3326 - Each SETTINGS frame requires acknowledgment. 3328 - An invalid request (or server push) can cause a peer to send 3329 RST_STREAM frames in response. 3331 * Large numbers of small or empty frames can be abused to cause a 3332 peer to expend time processing frame headers. Caution is required 3333 here as some uses of small frames are entirely legitimate, such as 3334 the sending of an empty DATA or CONTINUATION frame at the end of a 3335 stream. 3337 * The SETTINGS frame might also be abused to cause a peer to expend 3338 additional processing time. This might be done by pointlessly 3339 changing SETTINGS parameters, setting multiple undefined 3340 parameters, or changing the same setting multiple times in the 3341 same frame. 3343 * Handling reprioritization with PRIORITY frames can require 3344 significant processing time and can lead to overload if many 3345 PRIORITY frames are sent. 3347 * Field section compression also offers some opportunities to waste 3348 processing resources; see Section 7 of [COMPRESSION] for more 3349 details on potential abuses. 3351 * Limits in SETTINGS parameters cannot be reduced instantaneously, 3352 which leaves an endpoint exposed to behavior from a peer that 3353 could exceed the new limits. In particular, immediately after 3354 establishing a connection, limits set by a server are not known to 3355 clients and could be exceeded without being an obvious protocol 3356 violation. 3358 * An attacker can provide large amounts of flow control credit at 3359 the HTTP/2 layer, but withhold credit at the TCP layer, preventing 3360 frames from being sent. An endpoint that constructs and remembers 3361 frames for sending without considering TCP limits might be subject 3362 to resource exhaustion. 3364 Most of the features that might be exploited for denial of service -- 3365 i.e., SETTINGS changes, small frames, field section compression -- 3366 have legitimate uses. These features become a burden only when they 3367 are used unnecessarily or to excess. 3369 An endpoint that doesn't monitor use of these features exposes itself 3370 to a risk of denial of service. Implementations SHOULD track the use 3371 of these features and set limits on their use. An endpoint MAY treat 3372 activity that is suspicious as a connection error (Section 5.4.1) of 3373 type ENHANCE_YOUR_CALM. 3375 10.5.1. Limits on Field Block Size 3377 A large field block (Section 4.3) can cause an implementation to 3378 commit a large amount of state. Field lines that are critical for 3379 routing can appear toward the end of a field block, which prevents 3380 streaming of fields to their ultimate destination. This ordering and 3381 other reasons, such as ensuring cache correctness, mean that an 3382 endpoint might need to buffer the entire field block. Since there is 3383 no hard limit to the size of a field block, some endpoints could be 3384 forced to commit a large amount of available memory for field blocks. 3386 An endpoint can use the SETTINGS_MAX_HEADER_LIST_SIZE to advise peers 3387 of limits that might apply on the size of uncompressed field blocks. 3388 This setting is only advisory, so endpoints MAY choose to send field 3389 blocks that exceed this limit and risk having the request or response 3390 being treated as malformed. This setting is specific to a 3391 connection, so any request or response could encounter a hop with a 3392 lower, unknown limit. An intermediary can attempt to avoid this 3393 problem by passing on values presented by different peers, but they 3394 are not obliged to do so. 3396 A server that receives a larger field block than it is willing to 3397 handle can send an HTTP 431 (Request Header Fields Too Large) status 3398 code [RFC6585]. A client can discard responses that it cannot 3399 process. The field block MUST be processed to ensure a consistent 3400 connection state, unless the connection is closed. 3402 10.5.2. CONNECT Issues 3404 The CONNECT method can be used to create disproportionate load on an 3405 proxy, since stream creation is relatively inexpensive when compared 3406 to the creation and maintenance of a TCP connection. A proxy might 3407 also maintain some resources for a TCP connection beyond the closing 3408 of the stream that carries the CONNECT request, since the outgoing 3409 TCP connection remains in the TIME_WAIT state. Therefore, a proxy 3410 cannot rely on SETTINGS_MAX_CONCURRENT_STREAMS alone to limit the 3411 resources consumed by CONNECT requests. 3413 10.6. Use of Compression 3415 Compression can allow an attacker to recover secret data when it is 3416 compressed in the same context as data under attacker control. 3417 HTTP/2 enables compression of field lines (Section 4.3); the 3418 following concerns also apply to the use of HTTP compressed content- 3419 codings (Section 8.4.1 of [HTTP]). 3421 There are demonstrable attacks on compression that exploit the 3422 characteristics of the web (e.g., [BREACH]). The attacker induces 3423 multiple requests containing varying plaintext, observing the length 3424 of the resulting ciphertext in each, which reveals a shorter length 3425 when a guess about the secret is correct. 3427 Implementations communicating on a secure channel MUST NOT compress 3428 content that includes both confidential and attacker-controlled data 3429 unless separate compression dictionaries are used for each source of 3430 data. Compression MUST NOT be used if the source of data cannot be 3431 reliably determined. Generic stream compression, such as that 3432 provided by TLS, MUST NOT be used with HTTP/2 (see Section 9.2). 3434 Further considerations regarding the compression of header fields are 3435 described in [COMPRESSION]. 3437 10.7. Use of Padding 3439 Padding within HTTP/2 is not intended as a replacement for general 3440 purpose padding, such as that provided by TLS [TLS13]. Redundant 3441 padding could even be counterproductive. Correct application can 3442 depend on having specific knowledge of the data that is being padded. 3444 To mitigate attacks that rely on compression, disabling or limiting 3445 compression might be preferable to padding as a countermeasure. 3447 Padding can be used to obscure the exact size of frame content and is 3448 provided to mitigate specific attacks within HTTP, for example, 3449 attacks where compressed content includes both attacker-controlled 3450 plaintext and secret data (e.g., [BREACH]). 3452 Use of padding can result in less protection than might seem 3453 immediately obvious. At best, padding only makes it more difficult 3454 for an attacker to infer length information by increasing the number 3455 of frames an attacker has to observe. Incorrectly implemented 3456 padding schemes can be easily defeated. In particular, randomized 3457 padding with a predictable distribution provides very little 3458 protection; similarly, padding frame payloads to a fixed size exposes 3459 information as frame payload sizes cross the fixed-sized boundary, 3460 which could be possible if an attacker can control plaintext. 3462 Intermediaries SHOULD retain padding for DATA frames but MAY drop 3463 padding for HEADERS and PUSH_PROMISE frames. A valid reason for an 3464 intermediary to change the amount of padding of frames is to improve 3465 the protections that padding provides. 3467 10.8. Privacy Considerations 3469 Several characteristics of HTTP/2 provide an observer an opportunity 3470 to correlate actions of a single client or server over time. These 3471 include the value of settings, the manner in which flow-control 3472 windows are managed, the way priorities are allocated to streams, the 3473 timing of reactions to stimulus, and the handling of any features 3474 that are controlled by settings. 3476 As far as these create observable differences in behavior, they could 3477 be used as a basis for fingerprinting a specific client, as defined 3478 in Section 3.2 of [PRIVACY]. 3480 HTTP/2's preference for using a single TCP connection allows 3481 correlation of a user's activity on a site. Reusing connections for 3482 different origins allows tracking across those origins. 3484 Because the PING and SETTINGS frames solicit immediate responses, 3485 they can be used by an endpoint to measure latency to their peer. 3486 This might have privacy implications in certain scenarios. 3488 11. IANA Considerations 3490 A string for identifying HTTP/2 is entered into the "Application- 3491 Layer Protocol Negotiation (ALPN) Protocol IDs" registry established 3492 in [TLS-ALPN]. 3494 This document establishes a registry for frame types, settings, and 3495 error codes. These new registries appear in the new "Hypertext 3496 Transfer Protocol version 2 (HTTP/2) Parameters" section. 3498 This document registers the "HTTP2-Settings" header field for use in 3499 HTTP. 3501 This document registers the "PRI" method for use in HTTP to avoid 3502 collisions with the connection preface (Section 3.5). 3504 11.1. Registration of HTTP/2 Identification Strings 3506 This document creates two registrations for the identification of 3507 HTTP/2 (see Section 3.3) in the "Application-Layer Protocol 3508 Negotiation (ALPN) Protocol IDs" registry established in [TLS-ALPN]. 3510 The "h2" string identifies HTTP/2 when used over TLS: 3512 Protocol: HTTP/2 over TLS 3514 Identification Sequence: 0x68 0x32 ("h2") 3516 Specification: This document 3518 The "h2c" string identifies HTTP/2 when used over cleartext TCP: 3520 Protocol: HTTP/2 over TCP 3522 Identification Sequence: 0x68 0x32 0x63 ("h2c") 3524 Specification: This document 3526 11.2. Frame Type Registry 3528 This document establishes a registry for HTTP/2 frame type codes. 3529 The "HTTP/2 Frame Type" registry manages an 8-bit space. The "HTTP/2 3530 Frame Type" registry operates under either of the "IETF Review" or 3531 "IESG Approval" policies [RFC5226] for values between 0x00 and 0xef, 3532 with values between 0xf0 and 0xff being reserved for Experimental 3533 Use. 3535 New entries in this registry require the following information: 3537 Frame Type: A name or label for the frame type. 3539 Code: The 8-bit code assigned to the frame type. 3541 Specification: A reference to a specification that includes a 3542 description of the frame layout, its semantics, and flags that the 3543 frame type uses, including any parts of the frame that are 3544 conditionally present based on the value of flags. 3546 The entries in the following table are registered by this document. 3548 +===============+======+==============+ 3549 | Frame Type | Code | Section | 3550 +===============+======+==============+ 3551 | DATA | 0x0 | Section 6.1 | 3552 +---------------+------+--------------+ 3553 | HEADERS | 0x1 | Section 6.2 | 3554 +---------------+------+--------------+ 3555 | PRIORITY | 0x2 | Section 6.3 | 3556 +---------------+------+--------------+ 3557 | RST_STREAM | 0x3 | Section 6.4 | 3558 +---------------+------+--------------+ 3559 | SETTINGS | 0x4 | Section 6.5 | 3560 +---------------+------+--------------+ 3561 | PUSH_PROMISE | 0x5 | Section 6.6 | 3562 +---------------+------+--------------+ 3563 | PING | 0x6 | Section 6.7 | 3564 +---------------+------+--------------+ 3565 | GOAWAY | 0x7 | Section 6.8 | 3566 +---------------+------+--------------+ 3567 | WINDOW_UPDATE | 0x8 | Section 6.9 | 3568 +---------------+------+--------------+ 3569 | CONTINUATION | 0x9 | Section 6.10 | 3570 +---------------+------+--------------+ 3572 Table 1 3574 11.3. Settings Registry 3576 This document establishes a registry for HTTP/2 settings. The 3577 "HTTP/2 Settings" registry manages a 16-bit space. The "HTTP/2 3578 Settings" registry operates under the "Expert Review" policy 3579 [RFC5226] for values in the range from 0x0000 to 0xefff, with values 3580 between and 0xf000 and 0xffff being reserved for Experimental Use. 3582 New registrations are advised to provide the following information: 3584 Name: A symbolic name for the setting. Specifying a setting name is 3585 optional. 3587 Code: The 16-bit code assigned to the setting. 3589 Initial Value: An initial value for the setting. 3591 Specification: An optional reference to a specification that 3592 describes the use of the setting. 3594 The entries in the following table are registered by this document. 3596 +========================+======+===============+===============+ 3597 | Name | Code | Initial Value | Specification | 3598 +========================+======+===============+===============+ 3599 | HEADER_TABLE_SIZE | 0x1 | 4096 | Section 6.5.2 | 3600 +------------------------+------+---------------+---------------+ 3601 | ENABLE_PUSH | 0x2 | 1 | Section 6.5.2 | 3602 +------------------------+------+---------------+---------------+ 3603 | MAX_CONCURRENT_STREAMS | 0x3 | (infinite) | Section 6.5.2 | 3604 +------------------------+------+---------------+---------------+ 3605 | INITIAL_WINDOW_SIZE | 0x4 | 65535 | Section 6.5.2 | 3606 +------------------------+------+---------------+---------------+ 3607 | MAX_FRAME_SIZE | 0x5 | 16384 | Section 6.5.2 | 3608 +------------------------+------+---------------+---------------+ 3609 | MAX_HEADER_LIST_SIZE | 0x6 | (infinite) | Section 6.5.2 | 3610 +------------------------+------+---------------+---------------+ 3612 Table 2 3614 11.4. Error Code Registry 3616 This document establishes a registry for HTTP/2 error codes. The 3617 "HTTP/2 Error Code" registry manages a 32-bit space. The "HTTP/2 3618 Error Code" registry operates under the "Expert Review" policy 3619 [RFC5226]. 3621 Registrations for error codes are required to include a description 3622 of the error code. An expert reviewer is advised to examine new 3623 registrations for possible duplication with existing error codes. 3624 Use of existing registrations is to be encouraged, but not mandated. 3626 New registrations are advised to provide the following information: 3628 Name: A name for the error code. Specifying an error code name is 3629 optional. 3631 Code: The 32-bit error code value. 3633 Description: A brief description of the error code semantics, longer 3634 if no detailed specification is provided. 3636 Specification: An optional reference for a specification that 3637 defines the error code. 3639 The entries in the following table are registered by this document. 3641 +=====================+======+======================+===============+ 3642 | Name | Code | Description | Specification | 3643 +=====================+======+======================+===============+ 3644 | NO_ERROR | 0x0 | Graceful shutdown | Section 7 | 3645 +---------------------+------+----------------------+---------------+ 3646 | PROTOCOL_ERROR | 0x1 | Protocol error | Section 7 | 3647 | | | detected | | 3648 +---------------------+------+----------------------+---------------+ 3649 | INTERNAL_ERROR | 0x2 | Implementation | Section 7 | 3650 | | | fault | | 3651 +---------------------+------+----------------------+---------------+ 3652 | FLOW_CONTROL_ERROR | 0x3 | Flow-control | Section 7 | 3653 | | | limits exceeded | | 3654 +---------------------+------+----------------------+---------------+ 3655 | SETTINGS_TIMEOUT | 0x4 | Settings not | Section 7 | 3656 | | | acknowledged | | 3657 +---------------------+------+----------------------+---------------+ 3658 | STREAM_CLOSED | 0x5 | Frame received | Section 7 | 3659 | | | for closed stream | | 3660 +---------------------+------+----------------------+---------------+ 3661 | FRAME_SIZE_ERROR | 0x6 | Frame size | Section 7 | 3662 | | | incorrect | | 3663 +---------------------+------+----------------------+---------------+ 3664 | REFUSED_STREAM | 0x7 | Stream not | Section 7 | 3665 | | | processed | | 3666 +---------------------+------+----------------------+---------------+ 3667 | CANCEL | 0x8 | Stream cancelled | Section 7 | 3668 +---------------------+------+----------------------+---------------+ 3669 | COMPRESSION_ERROR | 0x9 | Compression state | Section 7 | 3670 | | | not updated | | 3671 +---------------------+------+----------------------+---------------+ 3672 | CONNECT_ERROR | 0xa | TCP connection | Section 7 | 3673 | | | error for CONNECT | | 3674 | | | method | | 3675 +---------------------+------+----------------------+---------------+ 3676 | ENHANCE_YOUR_CALM | 0xb | Processing | Section 7 | 3677 | | | capacity exceeded | | 3678 +---------------------+------+----------------------+---------------+ 3679 | INADEQUATE_SECURITY | 0xc | Negotiated TLS | Section 7 | 3680 | | | parameters not | | 3681 | | | acceptable | | 3682 +---------------------+------+----------------------+---------------+ 3683 | HTTP_1_1_REQUIRED | 0xd | Use HTTP/1.1 for | Section 7 | 3684 | | | the request | | 3685 +---------------------+------+----------------------+---------------+ 3687 Table 3 3689 11.5. HTTP2-Settings Header Field Registration 3691 This section registers the "HTTP2-Settings" header field in the 3692 "Permanent Message Header Field Names" registry [BCP90]. 3694 Header field name: HTTP2-Settings 3696 Applicable protocol: http 3698 Status: standard 3700 Author/Change controller: IETF 3702 Specification document(s): Section 3.2.1 of this document 3704 Related information: This header field is only used by an HTTP/2 3705 client for Upgrade-based negotiation. 3707 11.6. PRI Method Registration 3709 This section registers the "PRI" method in the "HTTP Method Registry" 3710 (Section 18.2 of [HTTP]). 3712 Method Name: PRI 3714 Safe: Yes 3716 Idempotent: Yes 3718 Specification document(s): Section 3.5 of this document 3720 Related information: This method is never used by an actual client. 3721 This method will appear to be used when an HTTP/1.1 server or 3722 intermediary attempts to parse an HTTP/2 connection preface. 3724 11.7. The h2c Upgrade Token 3726 This document registers the "h2c" upgrade token in the "HTTP Upgrade 3727 Tokens" registry (Section 18.10 of [HTTP]). 3729 Value: h2c 3731 Description: Hypertext Transfer Protocol version 2 (HTTP/2) 3733 Expected Version Tokens: None 3735 Reference: Section 3.2 of this document 3737 12. References 3739 12.1. Normative References 3741 [CACHE] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3742 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 3743 draft-ietf-httpbis-cache-14, 13 January 2021, 3744 . 3746 [COMPRESSION] 3747 Peon, R. and H. Ruellan, "HPACK: Header Compression for 3748 HTTP/2", RFC 7541, May 2015, 3749 . 3751 [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3752 April 2011, . 3754 [FIPS186] NIST, "Digital Signature Standard (DSS)", FIPS PUB 186-4, 3755 July 2013, . 3757 [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3758 Ed., "HTTP Semantics", Work in Progress, Internet-Draft, 3759 draft-ietf-httpbis-semantics-14, 13 January 2021, 3760 . 3763 [HTTP11] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 3764 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 3765 ietf-httpbis-messaging-14, 13 January 2021, 3766 . 3769 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3770 Requirement Levels", BCP 14, RFC 2119, March 1997, 3771 . 3773 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3774 Resource Identifier (URI): Generic Syntax", STD 66, 3775 RFC 3986, January 2005, 3776 . 3778 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 3779 Encodings", RFC 4648, October 2006, 3780 . 3782 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3783 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3784 May 2008, . 3786 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3787 Specifications: ABNF", STD 68, RFC 5234, January 2008, 3788 . 3790 [RFC8470] Thomson, M., Nottingham, M., and W. Tarreau, "Using Early 3791 Data in HTTP", RFC 8470, DOI 10.17487/RFC8470, September 3792 2018, . 3794 [TCP] Postel, J., "Transmission Control Protocol", STD 7, 3795 RFC 793, September 1981, 3796 . 3798 [TLS-ALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan, 3799 "Transport Layer Security (TLS) Application-Layer Protocol 3800 Negotiation Extension", RFC 7301, July 2014, 3801 . 3803 [TLS-ECDHE] 3804 Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 3805 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 3806 August 2008, . 3808 [TLS-EXT] Eastlake 3rd, D., "Transport Layer Security (TLS) 3809 Extensions: Extension Definitions", RFC 6066, January 3810 2011, . 3812 [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer Security 3813 (TLS) Protocol Version 1.2", RFC 5246, August 2008, 3814 . 3816 [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3817 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3818 . 3820 12.2. Informative References 3822 [ALT-SVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP 3823 Alternative Services", RFC 7838, April 2016, 3824 . 3826 [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration 3827 Procedures for Message Header Fields", BCP 90, RFC 3864, 3828 September 2004, . 3830 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 3831 CRIME Attack", 12 July 2013, 3832 . 3835 [DNS-TERMS] 3836 Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 3837 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 3838 January 2019, . 3840 [NFLX-2019-002] 3841 Netflix, "HTTP/2 Denial of Service Advisory", 13 August 3842 2019, . 3845 [PRIVACY] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 3846 Morris, J., Hansen, M., and R. Smith, "Privacy 3847 Considerations for Internet Protocols", RFC 6973, 3848 DOI 10.17487/RFC6973, July 2013, 3849 . 3851 [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol 3852 Compression Methods", RFC 3749, May 2004, 3853 . 3855 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 3856 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 3857 for Transport Layer Security (TLS)", RFC 4492, May 2006, 3858 . 3860 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 3861 Codes", RFC 6585, April 2012, 3862 . 3864 [RFC7323] Borman, D., Braden, B., Jacobson, V., and R. 3865 Scheffenegger, Ed., "TCP Extensions for High Performance", 3866 RFC 7323, September 2014, 3867 . 3869 [TALKING] Huang, L., Chen, E., Barth, A., Rescorla, E., and C. 3870 Jackson, "Talking to Yourself for Fun and Profit", 2011, 3871 . 3873 [TLSBCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 3874 "Recommendations for Secure Use of Transport Layer 3875 Security (TLS) and Datagram Transport Layer Security 3876 (DTLS)", BCP 195, RFC 7525, May 2015, 3877 . 3879 Appendix A. Prohibited TLS 1.2 Cipher Suites 3881 An HTTP/2 implementation MAY treat the negotiation of any of the 3882 following cipher suites with TLS 1.2 as a connection error 3883 (Section 5.4.1) of type INADEQUATE_SECURITY: 3885 * TLS_NULL_WITH_NULL_NULL 3886 * TLS_RSA_WITH_NULL_MD5 3887 * TLS_RSA_WITH_NULL_SHA 3888 * TLS_RSA_EXPORT_WITH_RC4_40_MD5 3889 * TLS_RSA_WITH_RC4_128_MD5 3890 * TLS_RSA_WITH_RC4_128_SHA 3891 * TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 3892 * TLS_RSA_WITH_IDEA_CBC_SHA 3893 * TLS_RSA_EXPORT_WITH_DES40_CBC_SHA 3894 * TLS_RSA_WITH_DES_CBC_SHA 3895 * TLS_RSA_WITH_3DES_EDE_CBC_SHA 3896 * TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA 3897 * TLS_DH_DSS_WITH_DES_CBC_SHA 3898 * TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 3899 * TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA 3900 * TLS_DH_RSA_WITH_DES_CBC_SHA 3901 * TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 3902 * TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA 3903 * TLS_DHE_DSS_WITH_DES_CBC_SHA 3904 * TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 3905 * TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA 3906 * TLS_DHE_RSA_WITH_DES_CBC_SHA 3907 * TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 3908 * TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 3909 * TLS_DH_anon_WITH_RC4_128_MD5 3910 * TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA 3911 * TLS_DH_anon_WITH_DES_CBC_SHA 3912 * TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 3913 * TLS_KRB5_WITH_DES_CBC_SHA 3914 * TLS_KRB5_WITH_3DES_EDE_CBC_SHA 3915 * TLS_KRB5_WITH_RC4_128_SHA 3916 * TLS_KRB5_WITH_IDEA_CBC_SHA 3917 * TLS_KRB5_WITH_DES_CBC_MD5 3918 * TLS_KRB5_WITH_3DES_EDE_CBC_MD5 3919 * TLS_KRB5_WITH_RC4_128_MD5 3920 * TLS_KRB5_WITH_IDEA_CBC_MD5 3921 * TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA 3922 * TLS_KRB5_EXPORT_WITH_RC2_CBC_40_SHA 3923 * TLS_KRB5_EXPORT_WITH_RC4_40_SHA 3924 * TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5 3925 * TLS_KRB5_EXPORT_WITH_RC2_CBC_40_MD5 3926 * TLS_KRB5_EXPORT_WITH_RC4_40_MD5 3927 * TLS_PSK_WITH_NULL_SHA 3928 * TLS_DHE_PSK_WITH_NULL_SHA 3929 * TLS_RSA_PSK_WITH_NULL_SHA 3930 * TLS_RSA_WITH_AES_128_CBC_SHA 3931 * TLS_DH_DSS_WITH_AES_128_CBC_SHA 3932 * TLS_DH_RSA_WITH_AES_128_CBC_SHA 3933 * TLS_DHE_DSS_WITH_AES_128_CBC_SHA 3934 * TLS_DHE_RSA_WITH_AES_128_CBC_SHA 3935 * TLS_DH_anon_WITH_AES_128_CBC_SHA 3936 * TLS_RSA_WITH_AES_256_CBC_SHA 3937 * TLS_DH_DSS_WITH_AES_256_CBC_SHA 3938 * TLS_DH_RSA_WITH_AES_256_CBC_SHA 3939 * TLS_DHE_DSS_WITH_AES_256_CBC_SHA 3940 * TLS_DHE_RSA_WITH_AES_256_CBC_SHA 3941 * TLS_DH_anon_WITH_AES_256_CBC_SHA 3942 * TLS_RSA_WITH_NULL_SHA256 3943 * TLS_RSA_WITH_AES_128_CBC_SHA256 3944 * TLS_RSA_WITH_AES_256_CBC_SHA256 3945 * TLS_DH_DSS_WITH_AES_128_CBC_SHA256 3946 * TLS_DH_RSA_WITH_AES_128_CBC_SHA256 3947 * TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 3948 * TLS_RSA_WITH_CAMELLIA_128_CBC_SHA 3949 * TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA 3950 * TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA 3951 * TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA 3952 * TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA 3953 * TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA 3954 * TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 3955 * TLS_DH_DSS_WITH_AES_256_CBC_SHA256 3956 * TLS_DH_RSA_WITH_AES_256_CBC_SHA256 3957 * TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 3958 * TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 3959 * TLS_DH_anon_WITH_AES_128_CBC_SHA256 3960 * TLS_DH_anon_WITH_AES_256_CBC_SHA256 3961 * TLS_RSA_WITH_CAMELLIA_256_CBC_SHA 3962 * TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA 3963 * TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA 3964 * TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA 3965 * TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA 3966 * TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA 3967 * TLS_PSK_WITH_RC4_128_SHA 3968 * TLS_PSK_WITH_3DES_EDE_CBC_SHA 3969 * TLS_PSK_WITH_AES_128_CBC_SHA 3970 * TLS_PSK_WITH_AES_256_CBC_SHA 3971 * TLS_DHE_PSK_WITH_RC4_128_SHA 3972 * TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA 3973 * TLS_DHE_PSK_WITH_AES_128_CBC_SHA 3974 * TLS_DHE_PSK_WITH_AES_256_CBC_SHA 3975 * TLS_RSA_PSK_WITH_RC4_128_SHA 3976 * TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA 3977 * TLS_RSA_PSK_WITH_AES_128_CBC_SHA 3978 * TLS_RSA_PSK_WITH_AES_256_CBC_SHA 3979 * TLS_RSA_WITH_SEED_CBC_SHA 3980 * TLS_DH_DSS_WITH_SEED_CBC_SHA 3981 * TLS_DH_RSA_WITH_SEED_CBC_SHA 3982 * TLS_DHE_DSS_WITH_SEED_CBC_SHA 3983 * TLS_DHE_RSA_WITH_SEED_CBC_SHA 3984 * TLS_DH_anon_WITH_SEED_CBC_SHA 3985 * TLS_RSA_WITH_AES_128_GCM_SHA256 3986 * TLS_RSA_WITH_AES_256_GCM_SHA384 3987 * TLS_DH_RSA_WITH_AES_128_GCM_SHA256 3988 * TLS_DH_RSA_WITH_AES_256_GCM_SHA384 3989 * TLS_DH_DSS_WITH_AES_128_GCM_SHA256 3990 * TLS_DH_DSS_WITH_AES_256_GCM_SHA384 3991 * TLS_DH_anon_WITH_AES_128_GCM_SHA256 3992 * TLS_DH_anon_WITH_AES_256_GCM_SHA384 3993 * TLS_PSK_WITH_AES_128_GCM_SHA256 3994 * TLS_PSK_WITH_AES_256_GCM_SHA384 3995 * TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 3996 * TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 3997 * TLS_PSK_WITH_AES_128_CBC_SHA256 3998 * TLS_PSK_WITH_AES_256_CBC_SHA384 3999 * TLS_PSK_WITH_NULL_SHA256 4000 * TLS_PSK_WITH_NULL_SHA384 4001 * TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 4002 * TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 4003 * TLS_DHE_PSK_WITH_NULL_SHA256 4004 * TLS_DHE_PSK_WITH_NULL_SHA384 4005 * TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 4006 * TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 4007 * TLS_RSA_PSK_WITH_NULL_SHA256 4008 * TLS_RSA_PSK_WITH_NULL_SHA384 4009 * TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 4010 * TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA256 4011 * TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA256 4012 * TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA256 4013 * TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 4014 * TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA256 4015 * TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 4016 * TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA256 4017 * TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA256 4018 * TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA256 4019 * TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 4020 * TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA256 4021 * TLS_EMPTY_RENEGOTIATION_INFO_SCSV 4022 * TLS_ECDH_ECDSA_WITH_NULL_SHA 4023 * TLS_ECDH_ECDSA_WITH_RC4_128_SHA 4024 * TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 4025 * TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 4026 * TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 4027 * TLS_ECDHE_ECDSA_WITH_NULL_SHA 4028 * TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 4029 * TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 4030 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 4031 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 4032 * TLS_ECDH_RSA_WITH_NULL_SHA 4033 * TLS_ECDH_RSA_WITH_RC4_128_SHA 4034 * TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 4035 * TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 4036 * TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 4037 * TLS_ECDHE_RSA_WITH_NULL_SHA 4038 * TLS_ECDHE_RSA_WITH_RC4_128_SHA 4039 * TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 4040 * TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 4041 * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 4042 * TLS_ECDH_anon_WITH_NULL_SHA 4043 * TLS_ECDH_anon_WITH_RC4_128_SHA 4044 * TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 4045 * TLS_ECDH_anon_WITH_AES_128_CBC_SHA 4046 * TLS_ECDH_anon_WITH_AES_256_CBC_SHA 4047 * TLS_SRP_SHA_WITH_3DES_EDE_CBC_SHA 4048 * TLS_SRP_SHA_RSA_WITH_3DES_EDE_CBC_SHA 4049 * TLS_SRP_SHA_DSS_WITH_3DES_EDE_CBC_SHA 4050 * TLS_SRP_SHA_WITH_AES_128_CBC_SHA 4051 * TLS_SRP_SHA_RSA_WITH_AES_128_CBC_SHA 4052 * TLS_SRP_SHA_DSS_WITH_AES_128_CBC_SHA 4053 * TLS_SRP_SHA_WITH_AES_256_CBC_SHA 4054 * TLS_SRP_SHA_RSA_WITH_AES_256_CBC_SHA 4055 * TLS_SRP_SHA_DSS_WITH_AES_256_CBC_SHA 4056 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 4057 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 4058 * TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 4059 * TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 4060 * TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 4061 * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 4062 * TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 4063 * TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 4064 * TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 4065 * TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 4066 * TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 4067 * TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 4068 * TLS_ECDHE_PSK_WITH_RC4_128_SHA 4069 * TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA 4070 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA 4071 * TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA 4072 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 4073 * TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 4074 * TLS_ECDHE_PSK_WITH_NULL_SHA 4075 * TLS_ECDHE_PSK_WITH_NULL_SHA256 4076 * TLS_ECDHE_PSK_WITH_NULL_SHA384 4077 * TLS_RSA_WITH_ARIA_128_CBC_SHA256 4078 * TLS_RSA_WITH_ARIA_256_CBC_SHA384 4079 * TLS_DH_DSS_WITH_ARIA_128_CBC_SHA256 4080 * TLS_DH_DSS_WITH_ARIA_256_CBC_SHA384 4081 * TLS_DH_RSA_WITH_ARIA_128_CBC_SHA256 4082 * TLS_DH_RSA_WITH_ARIA_256_CBC_SHA384 4083 * TLS_DHE_DSS_WITH_ARIA_128_CBC_SHA256 4084 * TLS_DHE_DSS_WITH_ARIA_256_CBC_SHA384 4085 * TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256 4086 * TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384 4087 * TLS_DH_anon_WITH_ARIA_128_CBC_SHA256 4088 * TLS_DH_anon_WITH_ARIA_256_CBC_SHA384 4089 * TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256 4090 * TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384 4091 * TLS_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256 4092 * TLS_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384 4093 * TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256 4094 * TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384 4095 * TLS_ECDH_RSA_WITH_ARIA_128_CBC_SHA256 4096 * TLS_ECDH_RSA_WITH_ARIA_256_CBC_SHA384 4097 * TLS_RSA_WITH_ARIA_128_GCM_SHA256 4098 * TLS_RSA_WITH_ARIA_256_GCM_SHA384 4099 * TLS_DH_RSA_WITH_ARIA_128_GCM_SHA256 4100 * TLS_DH_RSA_WITH_ARIA_256_GCM_SHA384 4101 * TLS_DH_DSS_WITH_ARIA_128_GCM_SHA256 4102 * TLS_DH_DSS_WITH_ARIA_256_GCM_SHA384 4103 * TLS_DH_anon_WITH_ARIA_128_GCM_SHA256 4104 * TLS_DH_anon_WITH_ARIA_256_GCM_SHA384 4105 * TLS_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256 4106 * TLS_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384 4107 * TLS_ECDH_RSA_WITH_ARIA_128_GCM_SHA256 4108 * TLS_ECDH_RSA_WITH_ARIA_256_GCM_SHA384 4109 * TLS_PSK_WITH_ARIA_128_CBC_SHA256 4110 * TLS_PSK_WITH_ARIA_256_CBC_SHA384 4111 * TLS_DHE_PSK_WITH_ARIA_128_CBC_SHA256 4112 * TLS_DHE_PSK_WITH_ARIA_256_CBC_SHA384 4113 * TLS_RSA_PSK_WITH_ARIA_128_CBC_SHA256 4114 * TLS_RSA_PSK_WITH_ARIA_256_CBC_SHA384 4115 * TLS_PSK_WITH_ARIA_128_GCM_SHA256 4116 * TLS_PSK_WITH_ARIA_256_GCM_SHA384 4117 * TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256 4118 * TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384 4119 * TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256 4120 * TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384 4121 * TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 4122 * TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 4123 * TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 4124 * TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 4125 * TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 4126 * TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 4127 * TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256 4128 * TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384 4129 * TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256 4130 * TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384 4131 * TLS_DH_RSA_WITH_CAMELLIA_128_GCM_SHA256 4132 * TLS_DH_RSA_WITH_CAMELLIA_256_GCM_SHA384 4133 * TLS_DH_DSS_WITH_CAMELLIA_128_GCM_SHA256 4134 * TLS_DH_DSS_WITH_CAMELLIA_256_GCM_SHA384 4135 * TLS_DH_anon_WITH_CAMELLIA_128_GCM_SHA256 4136 * TLS_DH_anon_WITH_CAMELLIA_256_GCM_SHA384 4137 * TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 4138 * TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 4139 * TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256 4140 * TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384 4141 * TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 4142 * TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 4143 * TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256 4144 * TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384 4145 * TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256 4146 * TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 4147 * TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 4148 * TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 4149 * TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 4150 * TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 4151 * TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 4152 * TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 4153 * TLS_RSA_WITH_AES_128_CCM 4154 * TLS_RSA_WITH_AES_256_CCM 4155 * TLS_RSA_WITH_AES_128_CCM_8 4156 * TLS_RSA_WITH_AES_256_CCM_8 4157 * TLS_PSK_WITH_AES_128_CCM 4158 * TLS_PSK_WITH_AES_256_CCM 4159 * TLS_PSK_WITH_AES_128_CCM_8 4160 * TLS_PSK_WITH_AES_256_CCM_8 4161 | Note: This list was assembled from the set of registered TLS 4162 | cipher suites at the time of writing. This list includes those 4163 | cipher suites that do not offer an ephemeral key exchange and 4164 | those that are based on the TLS null, stream, or block cipher 4165 | type (as defined in Section 6.2.3 of [TLS12]). Additional 4166 | cipher suites with these properties could be defined; these 4167 | would not be explicitly prohibited. 4169 Appendix B. Changes from RFC 7540 4171 This revision includes a number of editorial updates, plus the 4172 following substantive changes: 4174 * Use of TLS 1.3 is defined based on RFC 8740, which this document 4175 obsoletes. 4177 Contributors 4179 The previous version of this document was authored by Mike Belshe and 4180 Roberto Peon. 4182 Acknowledgements 4184 This document includes substantial input from the following 4185 individuals: 4187 * Adam Langley, Wan-Teh Chang, Jim Morrison, Mark Nottingham, Alyssa 4188 Wilk, Costin Manolache, William Chan, Vitaliy Lvin, Joe Chan, Adam 4189 Barth, Ryan Hamilton, Gavin Peters, Kent Alstad, Kevin Lindsay, 4190 Paul Amer, Fan Yang, and Jonathan Leighton (SPDY contributors). 4192 * Gabriel Montenegro and Willy Tarreau (Upgrade mechanism). 4194 * William Chan, Salvatore Loreto, Osama Mazahir, Gabriel Montenegro, 4195 Jitu Padhye, Roberto Peon, and Rob Trace (Flow control). 4197 * Mike Bishop (Extensibility). 4199 * Mark Nottingham, Julian Reschke, James Snell, Jeff Pinner, Mike 4200 Bishop, and Hervé Ruellan (Substantial editorial 4201 contributions). 4203 * Kari Hurtta, Tatsuhiro Tsujikawa, Greg Wilkins, Poul-Henning Kamp, 4204 and Jonathan Thackray. 4206 * Alexey Melnikov, who was an editor of this document in 2013. 4208 * David Benjamin, who was author of RFC 8740, the contents of which 4209 are integrated here. 4211 A substantial proportion of Martin's contribution was supported by 4212 Microsoft during his employment there. 4214 The Japanese HTTP/2 community provided invaluable contributions, 4215 including a number of implementations as well as numerous technical 4216 and editorial contributions. 4218 Authors' Addresses 4220 Martin Thomson (editor) 4221 Mozilla 4222 Australia 4224 Email: mt@lowentropy.net 4226 Cory Benfield (editor) 4227 Apple Inc. 4229 Email: cbenfield@apple.com