idnits 2.17.1 draft-thomson-httpbis-http2bis-00.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 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 (28 August 2020) is 1335 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS186' ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 793 (ref. 'TCP') (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 5246 (ref. 'TLS12') (Obsoleted by RFC 8446) == Outdated reference: A later version (-14) exists of draft-ietf-httpbis-alt-svc-06 -- 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: 10 errors (**), 0 flaws (~~), 2 warnings (==), 5 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 (if approved) 28 August 2020 5 Intended status: Standards Track 6 Expires: 1 March 2021 8 Hypertext Transfer Protocol Version 2 (HTTP/2) 9 draft-thomson-httpbis-http2bis-00 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/martinthomson/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 1 March 2021. 51 Copyright Notice 53 Copyright (c) 2020 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. Header Compression and Decompression . . . . . . . . . . 14 82 5. Streams and Multiplexing . . . . . . . . . . . . . . . . . . 15 83 5.1. Stream States . . . . . . . . . . . . . . . . . . . . . . 15 84 5.1.1. Stream Identifiers . . . . . . . . . . . . . . . . . 21 85 5.1.2. Stream Concurrency . . . . . . . . . . . . . . . . . 21 86 5.2. Flow Control . . . . . . . . . . . . . . . . . . . . . . 22 87 5.2.1. Flow-Control Principles . . . . . . . . . . . . . . . 22 88 5.2.2. Appropriate Use of Flow Control . . . . . . . . . . . 23 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 . . . . . . . . . . . . . . . . . 28 95 5.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 28 96 5.4.1. Connection Error Handling . . . . . . . . . . . . . . 28 97 5.4.2. Stream Error Handling . . . . . . . . . . . . . . . . 29 98 5.4.3. Connection Termination . . . . . . . . . . . . . . . 29 99 5.5. Extending HTTP/2 . . . . . . . . . . . . . . . . . . . . 30 100 6. Frame Definitions . . . . . . . . . . . . . . . . . . . . . . 31 101 6.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . 31 102 6.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . . . 32 103 6.3. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . 34 104 6.4. RST_STREAM . . . . . . . . . . . . . . . . . . . . . . . 36 105 6.5. SETTINGS . . . . . . . . . . . . . . . . . . . . . . . . 36 106 6.5.1. SETTINGS Format . . . . . . . . . . . . . . . . . . . 37 107 6.5.2. Defined SETTINGS Parameters . . . . . . . . . . . . . 38 108 6.5.3. Settings Synchronization . . . . . . . . . . . . . . 39 109 6.6. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . . . 40 110 6.7. PING . . . . . . . . . . . . . . . . . . . . . . . . . . 42 111 6.8. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . . . 43 112 6.9. WINDOW_UPDATE . . . . . . . . . . . . . . . . . . . . . . 45 113 6.9.1. The Flow-Control Window . . . . . . . . . . . . . . . 47 114 6.9.2. Initial Flow-Control Window Size . . . . . . . . . . 48 115 6.9.3. Reducing the Stream Window Size . . . . . . . . . . . 49 116 6.10. CONTINUATION . . . . . . . . . . . . . . . . . . . . . . 49 117 7. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 50 118 8. HTTP Message Exchanges . . . . . . . . . . . . . . . . . . . 51 119 8.1. HTTP Request/Response Exchange . . . . . . . . . . . . . 51 120 8.1.1. Upgrading from HTTP/2 . . . . . . . . . . . . . . . . 53 121 8.1.2. HTTP Header Fields . . . . . . . . . . . . . . . . . 53 122 8.1.3. Examples . . . . . . . . . . . . . . . . . . . . . . 57 123 8.1.4. Request Reliability Mechanisms in HTTP/2 . . . . . . 59 124 8.2. Server Push . . . . . . . . . . . . . . . . . . . . . . . 60 125 8.2.1. Push Requests . . . . . . . . . . . . . . . . . . . . 61 126 8.2.2. Push Responses . . . . . . . . . . . . . . . . . . . 62 127 8.3. The CONNECT Method . . . . . . . . . . . . . . . . . . . 63 128 9. Additional HTTP Requirements/Considerations . . . . . . . . . 64 129 9.1. Connection Management . . . . . . . . . . . . . . . . . . 65 130 9.1.1. Connection Reuse . . . . . . . . . . . . . . . . . . 65 131 9.1.2. The 421 (Misdirected Request) Status Code . . . . . . 66 132 9.2. Use of TLS Features . . . . . . . . . . . . . . . . . . . 67 133 9.2.1. TLS 1.2 Features . . . . . . . . . . . . . . . . . . 67 134 9.2.2. TLS 1.2 Cipher Suites . . . . . . . . . . . . . . . . 68 135 10. Security Considerations . . . . . . . . . . . . . . . . . . . 69 136 10.1. Server Authority . . . . . . . . . . . . . . . . . . . . 69 137 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . 69 138 10.3. Intermediary Encapsulation Attacks . . . . . . . . . . . 69 139 10.4. Cacheability of Pushed Responses . . . . . . . . . . . . 70 140 10.5. Denial-of-Service Considerations . . . . . . . . . . . . 70 141 10.5.1. Limits on Header Block Size . . . . . . . . . . . . 71 142 10.5.2. CONNECT Issues . . . . . . . . . . . . . . . . . . . 72 143 10.6. Use of Compression . . . . . . . . . . . . . . . . . . . 72 144 10.7. Use of Padding . . . . . . . . . . . . . . . . . . . . . 73 145 10.8. Privacy Considerations . . . . . . . . . . . . . . . . . 73 146 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 147 11.1. Registration of HTTP/2 Identification Strings . . . . . 74 148 11.2. Frame Type Registry . . . . . . . . . . . . . . . . . . 75 149 11.3. Settings Registry . . . . . . . . . . . . . . . . . . . 76 150 11.4. Error Code Registry . . . . . . . . . . . . . . . . . . 76 151 11.5. HTTP2-Settings Header Field Registration . . . . . . . . 79 152 11.6. PRI Method Registration . . . . . . . . . . . . . . . . 79 153 11.7. The 421 (Misdirected Request) HTTP Status Code . . . . . 79 154 11.8. The h2c Upgrade Token . . . . . . . . . . . . . . . . . 80 155 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 80 156 12.1. Normative References . . . . . . . . . . . . . . . . . . 80 157 12.2. Informative References . . . . . . . . . . . . . . . . . 82 158 Appendix A. Prohibited TLS 1.2 Cipher Suites . . . . . . . . . . 83 159 Appendix B. Changes from RFC 7540 . . . . . . . . . . . . . . . 89 160 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 89 161 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 89 162 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 90 164 1. Introduction 166 The Hypertext Transfer Protocol (HTTP) is a wildly successful 167 protocol. However, the way HTTP/1.1 uses the underlying transport 168 (Section 6 of [RFC7230]) has several characteristics that have a 169 negative overall effect on application performance today. 171 In particular, HTTP/1.0 allowed only one request to be outstanding at 172 a time on a given TCP connection. HTTP/1.1 added request pipelining, 173 but this only partially addressed request concurrency and still 174 suffers from head-of-line blocking. Therefore, HTTP/1.0 and HTTP/1.1 175 clients that need to make many requests use multiple connections to a 176 server in order to achieve concurrency and thereby reduce latency. 178 Furthermore, HTTP header fields are often repetitive and verbose, 179 causing unnecessary network traffic as well as causing the initial 180 TCP [TCP] congestion window to quickly fill. This can result in 181 excessive latency when multiple requests are made on a new TCP 182 connection. 184 HTTP/2 addresses these issues by defining an optimized mapping of 185 HTTP's semantics to an underlying connection. Specifically, it 186 allows interleaving of request and response messages on the same 187 connection and uses an efficient coding for HTTP header fields. It 188 also allows prioritization of requests, letting more important 189 requests complete more quickly, further improving performance. 191 The resulting protocol is more friendly to the network because fewer 192 TCP connections can be used in comparison to HTTP/1.x. This means 193 less competition with other flows and longer-lived connections, which 194 in turn lead to better utilization of available network capacity. 196 Finally, HTTP/2 also enables more efficient processing of messages 197 through use of binary message framing. 199 2. HTTP/2 Protocol Overview 201 HTTP/2 provides an optimized transport for HTTP semantics. HTTP/2 202 supports all of the core features of HTTP/1.1 but aims to be more 203 efficient in several ways. 205 The basic protocol unit in HTTP/2 is a frame (Section 4.1). Each 206 frame type serves a different purpose. For example, HEADERS and DATA 207 frames form the basis of HTTP requests and responses (Section 8.1); 208 other frame types like SETTINGS, WINDOW_UPDATE, and PUSH_PROMISE are 209 used in support of other HTTP/2 features. 211 Multiplexing of requests is achieved by having each HTTP request/ 212 response exchange associated with its own stream (Section 5). 213 Streams are largely independent of each other, so a blocked or 214 stalled request or response does not prevent progress on other 215 streams. 217 Flow control and prioritization ensure that it is possible to 218 efficiently use multiplexed streams. Flow control (Section 5.2) 219 helps to ensure that only data that can be used by a receiver is 220 transmitted. Prioritization (Section 5.3) ensures that limited 221 resources can be directed to the most important streams first. 223 HTTP/2 adds a new interaction mode whereby a server can push 224 responses to a client (Section 8.2). Server push allows a server to 225 speculatively send data to a client that the server anticipates the 226 client will need, trading off some network usage against a potential 227 latency gain. The server does this by synthesizing a request, which 228 it sends as a PUSH_PROMISE frame. The server is then able to send a 229 response to the synthetic request on a separate stream. 231 Because HTTP header fields used in a connection can contain large 232 amounts of redundant data, frames that contain them are compressed 233 (Section 4.3). This has especially advantageous impact upon request 234 sizes in the common case, allowing many requests to be compressed 235 into one packet. 237 2.1. Document Organization 239 The HTTP/2 specification is split into four parts: 241 * Starting HTTP/2 (Section 3) covers how an HTTP/2 connection is 242 initiated. 244 * The frame (Section 4) and stream (Section 5) layers describe the 245 way HTTP/2 frames are structured and formed into multiplexed 246 streams. 248 * Frame (Section 6) and error (Section 7) definitions include 249 details of the frame and error types used in HTTP/2. 251 * HTTP mappings (Section 8) and additional requirements (Section 9) 252 describe how HTTP semantics are expressed using frames and 253 streams. 255 While some of the frame and stream layer concepts are isolated from 256 HTTP, this specification does not define a completely generic frame 257 layer. The frame and stream layers are tailored to the needs of the 258 HTTP protocol and server push. 260 2.2. Conventions and Terminology 262 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 263 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 264 document are to be interpreted as described in RFC 2119 [RFC2119]. 266 All numeric values are in network byte order. Values are unsigned 267 unless otherwise indicated. Literal values are provided in decimal 268 or hexadecimal as appropriate. Hexadecimal literals are prefixed 269 with "0x" to distinguish them from decimal literals. 271 The following terms are used: 273 client: The endpoint that initiates an HTTP/2 connection. Clients 274 send HTTP requests and receive HTTP responses. 276 connection: A transport-layer connection between two endpoints. 278 connection error: An error that affects the entire HTTP/2 279 connection. 281 endpoint: Either the client or server of the connection. 283 frame: The smallest unit of communication within an HTTP/2 284 connection, consisting of a header and a variable-length sequence 285 of octets structured according to the frame type. 287 peer: An endpoint. When discussing a particular endpoint, "peer" 288 refers to the endpoint that is remote to the primary subject of 289 discussion. 291 receiver: An endpoint that is receiving frames. 293 sender: An endpoint that is transmitting frames. 295 server: The endpoint that accepts an HTTP/2 connection. Servers 296 receive HTTP requests and send HTTP responses. 298 stream: A bidirectional flow of frames within the HTTP/2 connection. 300 stream error: An error on the individual HTTP/2 stream. 302 Finally, the terms "gateway", "intermediary", "proxy", and "tunnel" 303 are defined in Section 2.3 of [RFC7230]. Intermediaries act as both 304 client and server at different times. 306 The term "payload body" is defined in Section 3.3 of [RFC7230]. 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 same "http" and "https" URI schemes used by HTTP/1.1. 315 HTTP/2 shares the same default port numbers: 80 for "http" URIs and 316 443 for "https" URIs. As a result, implementations processing 317 requests for target resource URIs like "http://example.org/foo" or 318 "https://example.com/bar" are required to first discover whether the 319 upstream server (the immediate peer to which the client wishes to 320 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) [TLS12]. 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 6.7 of [RFC7230]). 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 a payload body 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 payload of a 429 SETTINGS frame (Section 6.5), encoded as a base64url string (that is, 430 the URL- and filename-safe Base64 encoding described in Section 5 of 431 [RFC4648], with any trailing '=' characters omitted). The ABNF 432 [RFC5234] production for "token68" is defined in Section 2.1 of 433 [RFC7235]. 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 6.1 of 439 [RFC7230]). 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 [TLS12] 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 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 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 header 609 block (Section 4.3) (that is, HEADERS, PUSH_PROMISE, and 610 CONTINUATION), 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. Header Compression and Decompression 621 Just as in HTTP/1, a header field in HTTP/2 is a name with one or 622 more associated values. Header fields are used within HTTP request 623 and response messages as well as in server push operations (see 624 Section 8.2). 626 Header lists are collections of zero or more header fields. When 627 transmitted over a connection, a header list is serialized into a 628 header block using HTTP header compression [COMPRESSION]. The 629 serialized header block is then divided into one or more octet 630 sequences, called header block fragments, and transmitted within the 631 payload of HEADERS (Section 6.2), PUSH_PROMISE (Section 6.6), or 632 CONTINUATION (Section 6.10) frames. 634 The Cookie header field [COOKIE] is treated specially by the HTTP 635 mapping (see Section 8.1.2.5). 637 A receiving endpoint reassembles the header block by concatenating 638 its fragments and then decompresses the block to reconstruct the 639 header list. 641 A complete header block consists of either: 643 * a single HEADERS or PUSH_PROMISE frame, with the END_HEADERS flag 644 set, or 646 * a HEADERS or PUSH_PROMISE frame with the END_HEADERS flag cleared 647 and one or more CONTINUATION frames, where the last CONTINUATION 648 frame has the END_HEADERS flag set. 650 Header compression is stateful. One compression context and one 651 decompression context are used for the entire connection. A decoding 652 error in a header block MUST be treated as a connection error 653 (Section 5.4.1) of type COMPRESSION_ERROR. 655 Each header block is processed as a discrete unit. Header blocks 656 MUST be transmitted as a contiguous sequence of frames, with no 657 interleaved frames of any other type or from any other stream. The 658 last frame in a sequence of HEADERS or CONTINUATION frames has the 659 END_HEADERS flag set. The last frame in a sequence of PUSH_PROMISE 660 or CONTINUATION frames has the END_HEADERS flag set. This allows a 661 header block to be logically equivalent to a single frame. 663 Header block fragments can only be sent as the payload of HEADERS, 664 PUSH_PROMISE, or CONTINUATION frames because these frames carry data 665 that can modify the compression context maintained by a receiver. An 666 endpoint receiving HEADERS, PUSH_PROMISE, or CONTINUATION frames 667 needs to reassemble header blocks and perform decompression even if 668 the frames are to be discarded. A receiver MUST terminate the 669 connection with a connection error (Section 5.4.1) of type 670 COMPRESSION_ERROR if it does not decompress a header block. 672 5. Streams and Multiplexing 674 A "stream" is an independent, bidirectional sequence of frames 675 exchanged between the client and server within an HTTP/2 connection. 676 Streams have several important characteristics: 678 * A single HTTP/2 connection can contain multiple concurrently open 679 streams, with either endpoint interleaving frames from multiple 680 streams. 682 * Streams can be established and used unilaterally or shared by 683 either the client or server. 685 * Streams can be closed by either endpoint. 687 * The order in which frames are sent on a stream is significant. 688 Recipients process frames in the order they are received. In 689 particular, the order of HEADERS and DATA frames is semantically 690 significant. 692 * Streams are identified by an integer. Stream identifiers are 693 assigned to streams by the endpoint initiating the stream. 695 5.1. Stream States 697 The lifecycle of a stream is shown in Figure 2. 699 +--------+ 700 send PP | | recv PP 701 ,--------| idle |--------. 702 / | | \ 703 v +--------+ v 704 +----------+ | +----------+ 705 | | | send H / | | 706 ,------| reserved | | recv H | reserved |------. 707 | | (local) | | | (remote) | | 708 | +----------+ v +----------+ | 709 | | +--------+ | | 710 | | recv ES | | send ES | | 711 | send H | ,-------| open |-------. | recv H | 712 | | / | | \ | | 713 | v v +--------+ v v | 714 | +----------+ | +----------+ | 715 | | half | | | half | | 716 | | closed | | send R / | closed | | 717 | | (remote) | | recv R | (local) | | 718 | +----------+ | +----------+ | 719 | | | | | 720 | | send ES / | recv ES / | | 721 | | send R / v send R / | | 722 | | recv R +--------+ recv R | | 723 | send R / `----------->| |<-----------' send R / | 724 | recv R | closed | recv R | 725 `----------------------->| |<----------------------' 726 +--------+ 728 send: endpoint sends this frame 729 recv: endpoint receives this frame 731 H: HEADERS frame (with implied CONTINUATIONs) 732 ES: END_STREAM flag 733 R: RST_STREAM frame 734 PP: PUSH_PROMISE frame (with implied CONTINUATIONs) 735 Note: State transitions are for the promised stream. 737 Figure 2: Stream States 739 Note that this diagram shows stream state transitions and the frames 740 and flags that affect those transitions only. In this regard, 741 CONTINUATION frames do not result in state transitions; they are 742 effectively part of the HEADERS or PUSH_PROMISE that they follow. 743 For the purpose of state transitions, the END_STREAM flag is 744 processed as a separate event to the frame that bears it; a HEADERS 745 frame with the END_STREAM flag set can cause two state transitions. 747 Both endpoints have a subjective view of the state of a stream that 748 could be different when frames are in transit. Endpoints do not 749 coordinate the creation of streams; they are created unilaterally by 750 either endpoint. The negative consequences of a mismatch in states 751 are limited to the "closed" state after sending RST_STREAM, where 752 frames might be received for some time after closing. 754 Streams have the following states: 756 idle: All streams start in the "idle" state. 758 The following transitions are valid from this state: 760 * Sending or receiving a HEADERS frame causes the stream to 761 become "open". The stream identifier is selected as described 762 in Section 5.1.1. The same HEADERS frame can also cause a 763 stream to immediately become "half-closed". 765 * Sending a PUSH_PROMISE frame on another stream reserves the 766 idle stream that is identified for later use. The stream state 767 for the reserved stream transitions to "reserved (local)". 769 * Receiving a PUSH_PROMISE frame on another stream reserves an 770 idle stream that is identified for later use. The stream state 771 for the reserved stream transitions to "reserved (remote)". 773 * Note that the PUSH_PROMISE frame is not sent on the idle stream 774 but references the newly reserved stream in the Promised Stream 775 ID field. 777 Receiving any frame other than HEADERS or PRIORITY on a stream in 778 this state MUST be treated as a connection error (Section 5.4.1) 779 of type PROTOCOL_ERROR. 781 reserved (local): A stream in the "reserved (local)" state is one 782 that has been promised by sending a PUSH_PROMISE frame. A 783 PUSH_PROMISE frame reserves an idle stream by associating the 784 stream with an open stream that was initiated by the remote peer 785 (see Section 8.2). 787 In this state, only the following transitions are possible: 789 * The endpoint can send a HEADERS frame. This causes the stream 790 to open in a "half-closed (remote)" state. 792 * Either endpoint can send a RST_STREAM frame to cause the stream 793 to become "closed". This releases the stream reservation. 795 An endpoint MUST NOT send any type of frame other than HEADERS, 796 RST_STREAM, or PRIORITY in this state. 798 A PRIORITY or WINDOW_UPDATE frame MAY be received in this state. 799 Receiving any type of frame other than RST_STREAM, PRIORITY, or 800 WINDOW_UPDATE on a stream in this state MUST be treated as a 801 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 803 reserved (remote): A stream in the "reserved (remote)" state has 804 been reserved by a remote peer. 806 In this state, only the following transitions are possible: 808 * Receiving a HEADERS frame causes the stream to transition to 809 "half-closed (local)". 811 * Either endpoint can send a RST_STREAM frame to cause the stream 812 to become "closed". This releases the stream reservation. 814 An endpoint MAY send a PRIORITY frame in this state to 815 reprioritize the reserved stream. An endpoint MUST NOT send any 816 type of frame other than RST_STREAM, WINDOW_UPDATE, or PRIORITY in 817 this state. 819 Receiving any type of frame other than HEADERS, RST_STREAM, or 820 PRIORITY on a stream in this state MUST be treated as a connection 821 error (Section 5.4.1) of type PROTOCOL_ERROR. 823 open: A stream in the "open" state may be used by both peers to send 824 frames of any type. In this state, sending peers observe 825 advertised stream-level flow-control limits (Section 5.2). 827 From this state, either endpoint can send a frame with an 828 END_STREAM flag set, which causes the stream to transition into 829 one of the "half-closed" states. An endpoint sending an 830 END_STREAM flag causes the stream state to become "half-closed 831 (local)"; an endpoint receiving an END_STREAM flag causes the 832 stream state to become "half-closed (remote)". 834 Either endpoint can send a RST_STREAM frame from this state, 835 causing it to transition immediately to "closed". 837 half-closed (local): A stream that is in the "half-closed (local)" 838 state cannot be used for sending frames other than WINDOW_UPDATE, 839 PRIORITY, and RST_STREAM. 841 A stream transitions from this state to "closed" when a frame that 842 contains an END_STREAM flag is received or when either peer sends 843 a RST_STREAM frame. 845 An endpoint can receive any type of frame in this state. 846 Providing flow-control credit using WINDOW_UPDATE frames is 847 necessary to continue receiving flow-controlled frames. In this 848 state, a receiver can ignore WINDOW_UPDATE frames, which might 849 arrive for a short period after a frame bearing the END_STREAM 850 flag is sent. 852 PRIORITY frames received in this state are used to reprioritize 853 streams that depend on the identified stream. 855 half-closed (remote): A stream that is "half-closed (remote)" is no 856 longer being used by the peer to send frames. In this state, an 857 endpoint is no longer obligated to maintain a receiver flow- 858 control window. 860 If an endpoint receives additional frames, other than 861 WINDOW_UPDATE, PRIORITY, or RST_STREAM, for a stream that is in 862 this state, it MUST respond with a stream error (Section 5.4.2) of 863 type STREAM_CLOSED. 865 A stream that is "half-closed (remote)" can be used by the 866 endpoint to send frames of any type. In this state, the endpoint 867 continues to observe advertised stream-level flow-control limits 868 (Section 5.2). 870 A stream can transition from this state to "closed" by sending a 871 frame that contains an END_STREAM flag or when either peer sends a 872 RST_STREAM frame. 874 closed: The "closed" state is the terminal state. 876 An endpoint MUST NOT send frames other than PRIORITY on a closed 877 stream. An endpoint that receives any frame other than PRIORITY 878 after receiving a RST_STREAM MUST treat that as a stream error 879 (Section 5.4.2) of type STREAM_CLOSED. Similarly, an endpoint 880 that receives any frames after receiving a frame with the 881 END_STREAM flag set MUST treat that as a connection error 882 (Section 5.4.1) of type STREAM_CLOSED, unless the frame is 883 permitted as described below. 885 WINDOW_UPDATE or RST_STREAM frames can be received in this state 886 for a short period after a DATA or HEADERS frame containing an 887 END_STREAM flag is sent. Until the remote peer receives and 888 processes RST_STREAM or the frame bearing the END_STREAM flag, it 889 might send frames of these types. Endpoints MUST ignore 890 WINDOW_UPDATE or RST_STREAM frames received in this state, though 891 endpoints MAY choose to treat frames that arrive a significant 892 time after sending END_STREAM as a connection error 893 (Section 5.4.1) of type PROTOCOL_ERROR. 895 PRIORITY frames can be sent on closed streams to prioritize 896 streams that are dependent on the closed stream. Endpoints SHOULD 897 process PRIORITY frames, though they can be ignored if the stream 898 has been removed from the dependency tree (see Section 5.3.4). 900 If this state is reached as a result of sending a RST_STREAM 901 frame, the peer that receives the RST_STREAM might have already 902 sent -- or enqueued for sending -- frames on the stream that 903 cannot be withdrawn. An endpoint MUST ignore frames that it 904 receives on closed streams after it has sent a RST_STREAM frame. 905 An endpoint MAY choose to limit the period over which it ignores 906 frames and treat frames that arrive after this time as being in 907 error. 909 Flow-controlled frames (i.e., DATA) received after sending 910 RST_STREAM are counted toward the connection flow-control window. 911 Even though these frames might be ignored, because they are sent 912 before the sender receives the RST_STREAM, the sender will 913 consider the frames to count against the flow-control window. 915 An endpoint might receive a PUSH_PROMISE frame after it sends 916 RST_STREAM. PUSH_PROMISE causes a stream to become "reserved" 917 even if the associated stream has been reset. Therefore, a 918 RST_STREAM is needed to close an unwanted promised stream. 920 In the absence of more specific guidance elsewhere in this document, 921 implementations SHOULD treat the receipt of a frame that is not 922 expressly permitted in the description of a state as a connection 923 error (Section 5.4.1) of type PROTOCOL_ERROR. Note that PRIORITY can 924 be sent and received in any stream state. Frames of unknown types 925 are ignored. 927 An example of the state transitions for an HTTP request/response 928 exchange can be found in Section 8.1. An example of the state 929 transitions for server push can be found in Sections 8.2.1 and 8.2.2. 931 5.1.1. Stream Identifiers 933 Streams are identified with an unsigned 31-bit integer. Streams 934 initiated by a client MUST use odd-numbered stream identifiers; those 935 initiated by the server MUST use even-numbered stream identifiers. A 936 stream identifier of zero (0x0) is used for connection control 937 messages; the stream identifier of zero cannot be used to establish a 938 new stream. 940 HTTP/1.1 requests that are upgraded to HTTP/2 (see Section 3.2) are 941 responded to with a stream identifier of one (0x1). After the 942 upgrade completes, stream 0x1 is "half-closed (local)" to the client. 943 Therefore, stream 0x1 cannot be selected as a new stream identifier 944 by a client that upgrades from HTTP/1.1. 946 The identifier of a newly established stream MUST be numerically 947 greater than all streams that the initiating endpoint has opened or 948 reserved. This governs streams that are opened using a HEADERS frame 949 and streams that are reserved using PUSH_PROMISE. An endpoint that 950 receives an unexpected stream identifier MUST respond with a 951 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 953 The first use of a new stream identifier implicitly closes all 954 streams in the "idle" state that might have been initiated by that 955 peer with a lower-valued stream identifier. For example, if a client 956 sends a HEADERS frame on stream 7 without ever sending a frame on 957 stream 5, then stream 5 transitions to the "closed" state when the 958 first frame for stream 7 is sent or received. 960 Stream identifiers cannot be reused. Long-lived connections can 961 result in an endpoint exhausting the available range of stream 962 identifiers. A client that is unable to establish a new stream 963 identifier can establish a new connection for new streams. A server 964 that is unable to establish a new stream identifier can send a GOAWAY 965 frame so that the client is forced to open a new connection for new 966 streams. 968 5.1.2. Stream Concurrency 970 A peer can limit the number of concurrently active streams using the 971 SETTINGS_MAX_CONCURRENT_STREAMS parameter (see Section 6.5.2) within 972 a SETTINGS frame. The maximum concurrent streams setting is specific 973 to each endpoint and applies only to the peer that receives the 974 setting. That is, clients specify the maximum number of concurrent 975 streams the server can initiate, and servers specify the maximum 976 number of concurrent streams the client can initiate. 978 Streams that are in the "open" state or in either of the "half- 979 closed" states count toward the maximum number of streams that an 980 endpoint is permitted to open. Streams in any of these three states 981 count toward the limit advertised in the 982 SETTINGS_MAX_CONCURRENT_STREAMS setting. Streams in either of the 983 "reserved" states do not count toward the stream limit. 985 Endpoints MUST NOT exceed the limit set by their peer. An endpoint 986 that receives a HEADERS frame that causes its advertised concurrent 987 stream limit to be exceeded MUST treat this as a stream error 988 (Section 5.4.2) of type PROTOCOL_ERROR or REFUSED_STREAM. The choice 989 of error code determines whether the endpoint wishes to enable 990 automatic retry (see Section 8.1.4) for details). 992 An endpoint that wishes to reduce the value of 993 SETTINGS_MAX_CONCURRENT_STREAMS to a value that is below the current 994 number of open streams can either close streams that exceed the new 995 value or allow streams to complete. 997 5.2. Flow Control 999 Using streams for multiplexing introduces contention over use of the 1000 TCP connection, resulting in blocked streams. A flow-control scheme 1001 ensures that streams on the same connection do not destructively 1002 interfere with each other. Flow control is used for both individual 1003 streams and for the connection as a whole. 1005 HTTP/2 provides for flow control through use of the WINDOW_UPDATE 1006 frame (Section 6.9). 1008 5.2.1. Flow-Control Principles 1010 HTTP/2 stream flow control aims to allow a variety of flow-control 1011 algorithms to be used without requiring protocol changes. Flow 1012 control in HTTP/2 has the following characteristics: 1014 1. Flow control is specific to a connection. Both types of flow 1015 control are between the endpoints of a single hop and not over 1016 the entire end-to-end path. 1018 2. Flow control is based on WINDOW_UPDATE frames. Receivers 1019 advertise how many octets they are prepared to receive on a 1020 stream and for the entire connection. This is a credit-based 1021 scheme. 1023 3. Flow control is directional with overall control provided by the 1024 receiver. A receiver MAY choose to set any window size that it 1025 desires for each stream and for the entire connection. A sender 1026 MUST respect flow-control limits imposed by a receiver. Clients, 1027 servers, and intermediaries all independently advertise their 1028 flow-control window as a receiver and abide by the flow-control 1029 limits set by their peer when sending. 1031 4. The initial value for the flow-control window is 65,535 octets 1032 for both new streams and the overall connection. 1034 5. The frame type determines whether flow control applies to a 1035 frame. Of the frames specified in this document, only DATA 1036 frames are subject to flow control; all other frame types do not 1037 consume space in the advertised flow-control window. This 1038 ensures that important control frames are not blocked by flow 1039 control. 1041 6. Flow control cannot be disabled. 1043 7. HTTP/2 defines only the format and semantics of the WINDOW_UPDATE 1044 frame (Section 6.9). This document does not stipulate how a 1045 receiver decides when to send this frame or the value that it 1046 sends, nor does it specify how a sender chooses to send packets. 1047 Implementations are able to select any algorithm that suits their 1048 needs. 1050 Implementations are also responsible for managing how requests and 1051 responses are sent based on priority, choosing how to avoid head-of- 1052 line blocking for requests, and managing the creation of new streams. 1053 Algorithm choices for these could interact with any flow-control 1054 algorithm. 1056 5.2.2. Appropriate Use of Flow Control 1058 Flow control is defined to protect endpoints that are operating under 1059 resource constraints. For example, a proxy needs to share memory 1060 between many connections and also might have a slow upstream 1061 connection and a fast downstream one. Flow-control addresses cases 1062 where the receiver is unable to process data on one stream yet wants 1063 to continue to process other streams in the same connection. 1065 Deployments that do not require this capability can advertise a flow- 1066 control window of the maximum size (2^(31)-1) and can maintain this 1067 window by sending a WINDOW_UPDATE frame when any data is received. 1068 This effectively disables flow control for that receiver. 1069 Conversely, a sender is always subject to the flow-control window 1070 advertised by the receiver. 1072 Deployments with constrained resources (for example, memory) can 1073 employ flow control to limit the amount of memory a peer can consume. 1074 Note, however, that this can lead to suboptimal use of available 1075 network resources if flow control is enabled without knowledge of the 1076 bandwidth-delay product (see [RFC7323]). 1078 Even with full awareness of the current bandwidth-delay product, 1079 implementation of flow control can be difficult. When using flow 1080 control, the receiver MUST read from the TCP receive buffer in a 1081 timely fashion. Failure to do so could lead to a deadlock when 1082 critical frames, such as WINDOW_UPDATE, are not read and acted upon. 1084 5.3. Stream Priority 1086 A client can assign a priority for a new stream by including 1087 prioritization information in the HEADERS frame (Section 6.2) that 1088 opens the stream. At any other time, the PRIORITY frame 1089 (Section 6.3) can be used to change the priority of a stream. 1091 The purpose of prioritization is to allow an endpoint to express how 1092 it would prefer its peer to allocate resources when managing 1093 concurrent streams. Most importantly, priority can be used to select 1094 streams for transmitting frames when there is limited capacity for 1095 sending. 1097 Streams can be prioritized by marking them as dependent on the 1098 completion of other streams (Section 5.3.1). Each dependency is 1099 assigned a relative weight, a number that is used to determine the 1100 relative proportion of available resources that are assigned to 1101 streams dependent on the same stream. 1103 Explicitly setting the priority for a stream is input to a 1104 prioritization process. It does not guarantee any particular 1105 processing or transmission order for the stream relative to any other 1106 stream. An endpoint cannot force a peer to process concurrent 1107 streams in a particular order using priority. Expressing priority is 1108 therefore only a suggestion. 1110 Prioritization information can be omitted from messages. Defaults 1111 are used prior to any explicit values being provided (Section 5.3.5). 1113 The information that an endpoint maintains for stream priority is 1114 separate from other state. Importantly, this includes stream states 1115 (Section 5.1). A stream in any state can have its priority changed 1116 with a PRIORITY frame. The state of a stream is not changed as a 1117 result of changing its priority. The number of streams for which 1118 state is remembered is at the discretion of an endpoint, see 1119 Section 5.3.4 for details. 1121 5.3.1. Stream Dependencies 1123 Each stream can be given an explicit dependency on another stream. 1124 Including a dependency expresses a preference to allocate resources 1125 to the identified stream rather than to the dependent stream. 1127 A stream that is not dependent on any other stream is given a stream 1128 dependency of 0x0. In other words, the non-existent stream 0 forms 1129 the root of the tree. 1131 A stream that depends on another stream is a dependent stream. The 1132 stream upon which a stream is dependent is a parent stream. A 1133 dependency on a stream that is not currently in the tree -- such as a 1134 stream in the "idle" state -- results in that stream being given a 1135 default priority (Section 5.3.5). 1137 When assigning a dependency on another stream, the stream is added as 1138 a new dependency of the parent stream. Dependent streams that share 1139 the same parent are not ordered with respect to each other. For 1140 example, if streams B and C are dependent on stream A, and if stream 1141 D is created with a dependency on stream A, this results in a 1142 dependency order of A followed by B, C, and D in any order. 1144 A A 1145 / \ ==> /|\ 1146 B C B D C 1148 Figure 3: Example of Default Dependency Creation 1150 An exclusive flag allows for the insertion of a new level of 1151 dependencies. The exclusive flag causes the stream to become the 1152 sole dependency of its parent stream, causing other dependencies to 1153 become dependent on the exclusive stream. In the previous example, 1154 if stream D is created with an exclusive dependency on stream A, this 1155 results in D becoming the dependency parent of B and C. 1157 A 1158 A | 1159 / \ ==> D 1160 B C / \ 1161 B C 1163 Figure 4: Example of Exclusive Dependency Creation 1165 Inside the dependency tree, a dependent stream SHOULD only be 1166 allocated resources if either all of the streams that it depends on 1167 (the chain of parent streams up to 0x0) are closed or it is not 1168 possible to make progress on them. 1170 A stream cannot depend on itself. An endpoint MUST treat this as a 1171 stream error (Section 5.4.2) of type PROTOCOL_ERROR. 1173 5.3.2. Dependency Weighting 1175 All dependent streams are allocated an integer weight between 1 and 1176 256 (inclusive). 1178 Streams with the same parent SHOULD be allocated resources 1179 proportionally based on their weight. Thus, if stream B depends on 1180 stream A with weight 4, stream C depends on stream A with weight 12, 1181 and no progress can be made on stream A, stream B ideally receives 1182 one-third of the resources allocated to stream C. 1184 5.3.3. Reprioritization 1186 Stream priorities are changed using the PRIORITY frame. Setting a 1187 dependency causes a stream to become dependent on the identified 1188 parent stream. 1190 Dependent streams move with their parent stream if the parent is 1191 reprioritized. Setting a dependency with the exclusive flag for a 1192 reprioritized stream causes all the dependencies of the new parent 1193 stream to become dependent on the reprioritized stream. 1195 If a stream is made dependent on one of its own dependencies, the 1196 formerly dependent stream is first moved to be dependent on the 1197 reprioritized stream's previous parent. The moved dependency retains 1198 its weight. 1200 For example, consider an original dependency tree where B and C 1201 depend on A, D and E depend on C, and F depends on D. If A is made 1202 dependent on D, then D takes the place of A. All other dependency 1203 relationships stay the same, except for F, which becomes dependent on 1204 A if the reprioritization is exclusive. 1206 x x x x 1207 | / \ | | 1208 A D A D D 1209 / \ / / \ / \ | 1210 B C ==> F B C ==> F A OR A 1211 / \ | / \ /|\ 1212 D E E B C B C F 1213 | | | 1214 F E E 1215 (intermediate) (non-exclusive) (exclusive) 1217 Figure 5: Example of Dependency Reordering 1219 5.3.4. Prioritization State Management 1221 When a stream is removed from the dependency tree, its dependencies 1222 can be moved to become dependent on the parent of the closed stream. 1223 The weights of new dependencies are recalculated by distributing the 1224 weight of the dependency of the closed stream proportionally based on 1225 the weights of its dependencies. 1227 Streams that are removed from the dependency tree cause some 1228 prioritization information to be lost. Resources are shared between 1229 streams with the same parent stream, which means that if a stream in 1230 that set closes or becomes blocked, any spare capacity allocated to a 1231 stream is distributed to the immediate neighbors of the stream. 1232 However, if the common dependency is removed from the tree, those 1233 streams share resources with streams at the next highest level. 1235 For example, assume streams A and B share a parent, and streams C and 1236 D both depend on stream A. Prior to the removal of stream A, if 1237 streams A and D are unable to proceed, then stream C receives all the 1238 resources dedicated to stream A. If stream A is removed from the 1239 tree, the weight of stream A is divided between streams C and D. If 1240 stream D is still unable to proceed, this results in stream C 1241 receiving a reduced proportion of resources. For equal starting 1242 weights, C receives one third, rather than one half, of available 1243 resources. 1245 It is possible for a stream to become closed while prioritization 1246 information that creates a dependency on that stream is in transit. 1247 If a stream identified in a dependency has no associated priority 1248 information, then the dependent stream is instead assigned a default 1249 priority (Section 5.3.5). This potentially creates suboptimal 1250 prioritization, since the stream could be given a priority that is 1251 different from what is intended. 1253 To avoid these problems, an endpoint SHOULD retain stream 1254 prioritization state for a period after streams become closed. The 1255 longer state is retained, the lower the chance that streams are 1256 assigned incorrect or default priority values. 1258 Similarly, streams that are in the "idle" state can be assigned 1259 priority or become a parent of other streams. This allows for the 1260 creation of a grouping node in the dependency tree, which enables 1261 more flexible expressions of priority. Idle streams begin with a 1262 default priority (Section 5.3.5). 1264 The retention of priority information for streams that are not 1265 counted toward the limit set by SETTINGS_MAX_CONCURRENT_STREAMS could 1266 create a large state burden for an endpoint. Therefore, the amount 1267 of prioritization state that is retained MAY be limited. 1269 The amount of additional state an endpoint maintains for 1270 prioritization could be dependent on load; under high load, 1271 prioritization state can be discarded to limit resource commitments. 1272 In extreme cases, an endpoint could even discard prioritization state 1273 for active or reserved streams. If a limit is applied, endpoints 1274 SHOULD maintain state for at least as many streams as allowed by 1275 their setting for SETTINGS_MAX_CONCURRENT_STREAMS. Implementations 1276 SHOULD also attempt to retain state for streams that are in active 1277 use in the priority tree. 1279 If it has retained enough state to do so, an endpoint receiving a 1280 PRIORITY frame that changes the priority of a closed stream SHOULD 1281 alter the dependencies of the streams that depend on it. 1283 5.3.5. Default Priorities 1285 All streams are initially assigned a non-exclusive dependency on 1286 stream 0x0. Pushed streams (Section 8.2) initially depend on their 1287 associated stream. In both cases, streams are assigned a default 1288 weight of 16. 1290 5.4. Error Handling 1292 HTTP/2 framing permits two classes of error: 1294 * An error condition that renders the entire connection unusable is 1295 a connection error. 1297 * An error in an individual stream is a stream error. 1299 A list of error codes is included in Section 7. 1301 5.4.1. Connection Error Handling 1303 A connection error is any error that prevents further processing of 1304 the frame layer or corrupts any connection state. 1306 An endpoint that encounters a connection error SHOULD first send a 1307 GOAWAY frame (Section 6.8) with the stream identifier of the last 1308 stream that it successfully received from its peer. The GOAWAY frame 1309 includes an error code that indicates why the connection is 1310 terminating. After sending the GOAWAY frame for an error condition, 1311 the endpoint MUST close the TCP connection. 1313 It is possible that the GOAWAY will not be reliably received by the 1314 receiving endpoint (Section 6.6 of [RFC7230] describes how an 1315 immediate connection close can result in data loss). In the event of 1316 a connection error, GOAWAY only provides a best-effort attempt to 1317 communicate with the peer about why the connection is being 1318 terminated. 1320 An endpoint can end a connection at any time. In particular, an 1321 endpoint MAY choose to treat a stream error as a connection error. 1322 Endpoints SHOULD send a GOAWAY frame when ending a connection, 1323 providing that circumstances permit it. 1325 5.4.2. Stream Error Handling 1327 A stream error is an error related to a specific stream that does not 1328 affect processing of other streams. 1330 An endpoint that detects a stream error sends a RST_STREAM frame 1331 (Section 6.4) that contains the stream identifier of the stream where 1332 the error occurred. The RST_STREAM frame includes an error code that 1333 indicates the type of error. 1335 A RST_STREAM is the last frame that an endpoint can send on a stream. 1336 The peer that sends the RST_STREAM frame MUST be prepared to receive 1337 any frames that were sent or enqueued for sending by the remote peer. 1338 These frames can be ignored, except where they modify connection 1339 state (such as the state maintained for header compression 1340 (Section 4.3) or flow control). 1342 Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame 1343 for any stream. However, an endpoint MAY send additional RST_STREAM 1344 frames if it receives frames on a closed stream after more than a 1345 round-trip time. This behavior is permitted to deal with misbehaving 1346 implementations. 1348 To avoid looping, an endpoint MUST NOT send a RST_STREAM in response 1349 to a RST_STREAM frame. 1351 5.4.3. Connection Termination 1353 If the TCP connection is closed or reset while streams remain in 1354 "open" or "half-closed" state, then the affected streams cannot be 1355 automatically retried (see Section 8.1.4 for details). 1357 5.5. Extending HTTP/2 1359 HTTP/2 permits extension of the protocol. Within the limitations 1360 described in this section, protocol extensions can be used to provide 1361 additional services or alter any aspect of the protocol. Extensions 1362 are effective only within the scope of a single HTTP/2 connection. 1364 This applies to the protocol elements defined in this document. This 1365 does not affect the existing options for extending HTTP, such as 1366 defining new methods, status codes, or header fields. 1368 Extensions are permitted to use new frame types (Section 4.1), new 1369 settings (Section 6.5.2), or new error codes (Section 7). Registries 1370 are established for managing these extension points: frame types 1371 (Section 11.2), settings (Section 11.3), and error codes 1372 (Section 11.4). 1374 Implementations MUST ignore unknown or unsupported values in all 1375 extensible protocol elements. Implementations MUST discard frames 1376 that have unknown or unsupported types. This means that any of these 1377 extension points can be safely used by extensions without prior 1378 arrangement or negotiation. However, extension frames that appear in 1379 the middle of a header block (Section 4.3) are not permitted; these 1380 MUST be treated as a connection error (Section 5.4.1) of type 1381 PROTOCOL_ERROR. 1383 Extensions that could change the semantics of existing protocol 1384 components MUST be negotiated before being used. For example, an 1385 extension that changes the layout of the HEADERS frame cannot be used 1386 until the peer has given a positive signal that this is acceptable. 1387 In this case, it could also be necessary to coordinate when the 1388 revised layout comes into effect. Note that treating any frames 1389 other than DATA frames as flow controlled is such a change in 1390 semantics and can only be done through negotiation. 1392 This document doesn't mandate a specific method for negotiating the 1393 use of an extension but notes that a setting (Section 6.5.2) could be 1394 used for that purpose. If both peers set a value that indicates 1395 willingness to use the extension, then the extension can be used. If 1396 a setting is used for extension negotiation, the initial value MUST 1397 be defined in such a fashion that the extension is initially 1398 disabled. 1400 6. Frame Definitions 1402 This specification defines a number of frame types, each identified 1403 by a unique 8-bit type code. Each frame type serves a distinct 1404 purpose in the establishment and management either of the connection 1405 as a whole or of individual streams. 1407 The transmission of specific frame types can alter the state of a 1408 connection. If endpoints fail to maintain a synchronized view of the 1409 connection state, successful communication within the connection will 1410 no longer be possible. Therefore, it is important that endpoints 1411 have a shared comprehension of how the state is affected by the use 1412 any given frame. 1414 6.1. DATA 1416 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 1417 octets associated with a stream. One or more DATA frames are used, 1418 for instance, to carry HTTP request or response payloads. 1420 DATA frames MAY also contain padding. Padding can be added to DATA 1421 frames to obscure the size of messages. Padding is a security 1422 feature; see Section 10.7. 1424 +---------------+ 1425 |Pad Length? (8)| 1426 +---------------+-----------------------------------------------+ 1427 | Data (*) ... 1428 +---------------------------------------------------------------+ 1429 | Padding (*) ... 1430 +---------------------------------------------------------------+ 1432 Figure 6: DATA Frame Payload 1434 The DATA frame contains the following fields: 1436 Pad Length: An 8-bit field containing the length of the frame 1437 padding in units of octets. This field is conditional (as 1438 signified by a "?" in the diagram) and is only present if the 1439 PADDED flag is set. 1441 Data: Application data. The amount of data is the remainder of the 1442 frame payload after subtracting the length of the other fields 1443 that are present. 1445 Padding: Padding octets that contain no application semantic value. 1447 Padding octets MUST be set to zero when sending. A receiver is 1448 not obligated to verify padding but MAY treat non-zero padding as 1449 a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1451 The DATA frame defines the following flags: 1453 END_STREAM (0x1): When set, bit 0 indicates that this frame is the 1454 last that the endpoint will send for the identified stream. 1455 Setting this flag causes the stream to enter one of the 1456 "half-closed" states or the "closed" state (Section 5.1). 1458 PADDED (0x8): When set, bit 3 indicates that the Pad Length field 1459 and any padding that it describes are present. 1461 DATA frames MUST be associated with a stream. If a DATA frame is 1462 received whose stream identifier field is 0x0, the recipient MUST 1463 respond with a connection error (Section 5.4.1) of type 1464 PROTOCOL_ERROR. 1466 DATA frames are subject to flow control and can only be sent when a 1467 stream is in the "open" or "half-closed (remote)" state. The entire 1468 DATA frame payload is included in flow control, including the Pad 1469 Length and Padding fields if present. If a DATA frame is received 1470 whose stream is not in "open" or "half-closed (local)" state, the 1471 recipient MUST respond with a stream error (Section 5.4.2) of type 1472 STREAM_CLOSED. 1474 The total number of padding octets is determined by the value of the 1475 Pad Length field. If the length of the padding is the length of the 1476 frame payload or greater, the recipient MUST treat this as a 1477 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1479 | Note: A frame can be increased in size by one octet by 1480 | including a Pad Length field with a value of zero. 1482 6.2. HEADERS 1484 The HEADERS frame (type=0x1) is used to open a stream (Section 5.1), 1485 and additionally carries a header block fragment. HEADERS frames can 1486 be sent on a stream in the "idle", "reserved (local)", "open", or 1487 "half-closed (remote)" state. 1489 +---------------+ 1490 |Pad Length? (8)| 1491 +-+-------------+-----------------------------------------------+ 1492 |E| Stream Dependency? (31) | 1493 +-+-------------+-----------------------------------------------+ 1494 | Weight? (8) | 1495 +-+-------------+-----------------------------------------------+ 1496 | Header Block Fragment (*) ... 1497 +---------------------------------------------------------------+ 1498 | Padding (*) ... 1499 +---------------------------------------------------------------+ 1501 Figure 7: HEADERS Frame Payload 1503 The HEADERS frame payload has the following fields: 1505 Pad Length: An 8-bit field containing the length of the frame 1506 padding in units of octets. This field is only present if the 1507 PADDED flag is set. 1509 E: A single-bit flag indicating that the stream dependency is 1510 exclusive (see Section 5.3). This field is only present if the 1511 PRIORITY flag is set. 1513 Stream Dependency: A 31-bit stream identifier for the stream that 1514 this stream depends on (see Section 5.3). This field is only 1515 present if the PRIORITY flag is set. 1517 Weight: An unsigned 8-bit integer representing a priority weight for 1518 the stream (see Section 5.3). Add one to the value to obtain a 1519 weight between 1 and 256. This field is only present if the 1520 PRIORITY flag is set. 1522 Header Block Fragment: A header block fragment (Section 4.3). 1524 Padding: Padding octets. 1526 The HEADERS frame defines the following flags: 1528 END_STREAM (0x1): When set, bit 0 indicates that the header block 1529 (Section 4.3) is the last that the endpoint will send for the 1530 identified stream. 1532 A HEADERS frame carries the END_STREAM flag that signals the end 1533 of a stream. However, a HEADERS frame with the END_STREAM flag 1534 set can be followed by CONTINUATION frames on the same stream. 1535 Logically, the CONTINUATION frames are part of the HEADERS frame. 1537 END_HEADERS (0x4): When set, bit 2 indicates that this frame 1538 contains an entire header block (Section 4.3) and is not followed 1539 by any CONTINUATION frames. 1541 A HEADERS frame without the END_HEADERS flag set MUST be followed 1542 by a CONTINUATION frame for the same stream. A receiver MUST 1543 treat the receipt of any other type of frame or a frame on a 1544 different stream as a connection error (Section 5.4.1) of type 1545 PROTOCOL_ERROR. 1547 PADDED (0x8): When set, bit 3 indicates that the Pad Length field 1548 and any padding that it describes are present. 1550 PRIORITY (0x20): When set, bit 5 indicates that the Exclusive Flag 1551 (E), Stream Dependency, and Weight fields are present; see 1552 Section 5.3. 1554 The payload of a HEADERS frame contains a header block fragment 1555 (Section 4.3). A header block that does not fit within a HEADERS 1556 frame is continued in a CONTINUATION frame (Section 6.10). 1558 HEADERS frames MUST be associated with a stream. If a HEADERS frame 1559 is received whose stream identifier field is 0x0, the recipient MUST 1560 respond with a connection error (Section 5.4.1) of type 1561 PROTOCOL_ERROR. 1563 The HEADERS frame changes the connection state as described in 1564 Section 4.3. 1566 The HEADERS frame can include padding. Padding fields and flags are 1567 identical to those defined for DATA frames (Section 6.1). Padding 1568 that exceeds the size remaining for the header block fragment MUST be 1569 treated as a PROTOCOL_ERROR. 1571 Prioritization information in a HEADERS frame is logically equivalent 1572 to a separate PRIORITY frame, but inclusion in HEADERS avoids the 1573 potential for churn in stream prioritization when new streams are 1574 created. Prioritization fields in HEADERS frames subsequent to the 1575 first on a stream reprioritize the stream (Section 5.3.3). 1577 6.3. PRIORITY 1579 The PRIORITY frame (type=0x2) specifies the sender-advised priority 1580 of a stream (Section 5.3). It can be sent in any stream state, 1581 including idle or closed streams. 1583 +-+-------------------------------------------------------------+ 1584 |E| Stream Dependency (31) | 1585 +-+-------------+-----------------------------------------------+ 1586 | Weight (8) | 1587 +-+-------------+ 1589 Figure 8: PRIORITY Frame Payload 1591 The payload of a PRIORITY frame contains the following fields: 1593 E: A single-bit flag indicating that the stream dependency is 1594 exclusive (see Section 5.3). 1596 Stream Dependency: A 31-bit stream identifier for the stream that 1597 this stream depends on (see Section 5.3). 1599 Weight: An unsigned 8-bit integer representing a priority weight for 1600 the stream (see Section 5.3). Add one to the value to obtain a 1601 weight between 1 and 256. 1603 The PRIORITY frame does not define any flags. 1605 The PRIORITY frame always identifies a stream. If a PRIORITY frame 1606 is received with a stream identifier of 0x0, the recipient MUST 1607 respond with a connection error (Section 5.4.1) of type 1608 PROTOCOL_ERROR. 1610 Sending or receiving a PRIORITY frame does not affect the state of 1611 any stream (Section 5.1), only the priority of streams is altered. 1613 The PRIORITY frame can be sent on a stream in any state, though it 1614 cannot be sent between consecutive frames that comprise a single 1615 header block (Section 4.3). Note that this frame could arrive after 1616 processing or frame sending has completed, which would cause it to 1617 have no effect on the identified stream. For a stream that is in the 1618 "half-closed (remote)" or "closed" state, this frame can only affect 1619 processing of the identified stream and its dependent streams; it 1620 does not affect frame transmission on that stream. 1622 The PRIORITY frame can be sent for a stream in the "idle" or "closed" 1623 state. This allows for the reprioritization of a group of dependent 1624 streams by altering the priority of an unused or closed parent 1625 stream. 1627 A PRIORITY frame with a length other than 5 octets MUST be treated as 1628 a stream error (Section 5.4.2) of type FRAME_SIZE_ERROR. 1630 6.4. RST_STREAM 1632 The RST_STREAM frame (type=0x3) allows for immediate termination of a 1633 stream. RST_STREAM is sent to request cancellation of a stream or to 1634 indicate that an error condition has occurred. 1636 +---------------------------------------------------------------+ 1637 | Error Code (32) | 1638 +---------------------------------------------------------------+ 1640 Figure 9: RST_STREAM Frame Payload 1642 The RST_STREAM frame contains a single unsigned, 32-bit integer 1643 identifying the error code (Section 7). The error code indicates why 1644 the stream is being terminated. 1646 The RST_STREAM frame does not define any flags. 1648 The RST_STREAM frame fully terminates the referenced stream and 1649 causes it to enter the "closed" state. After receiving a RST_STREAM 1650 on a stream, the receiver MUST NOT send additional frames for that 1651 stream, with the exception of PRIORITY. However, after sending the 1652 RST_STREAM, the sending endpoint MUST be prepared to receive and 1653 process additional frames sent on the stream that might have been 1654 sent by the peer prior to the arrival of the RST_STREAM. 1656 RST_STREAM frames MUST be associated with a stream. If a RST_STREAM 1657 frame is received with a stream identifier of 0x0, the recipient MUST 1658 treat this as a connection error (Section 5.4.1) of type 1659 PROTOCOL_ERROR. 1661 RST_STREAM frames MUST NOT be sent for a stream in the "idle" state. 1662 If a RST_STREAM frame identifying an idle stream is received, the 1663 recipient MUST treat this as a connection error (Section 5.4.1) of 1664 type PROTOCOL_ERROR. 1666 A RST_STREAM frame with a length other than 4 octets MUST be treated 1667 as a connection error (Section 5.4.1) of type FRAME_SIZE_ERROR. 1669 6.5. SETTINGS 1671 The SETTINGS frame (type=0x4) conveys configuration parameters that 1672 affect how endpoints communicate, such as preferences and constraints 1673 on peer behavior. The SETTINGS frame is also used to acknowledge the 1674 receipt of those parameters. Individually, a SETTINGS parameter can 1675 also be referred to as a "setting". 1677 SETTINGS parameters are not negotiated; they describe characteristics 1678 of the sending peer, which are used by the receiving peer. Different 1679 values for the same parameter can be advertised by each peer. For 1680 example, a client might set a high initial flow-control window, 1681 whereas a server might set a lower value to conserve resources. 1683 A SETTINGS frame MUST be sent by both endpoints at the start of a 1684 connection and MAY be sent at any other time by either endpoint over 1685 the lifetime of the connection. Implementations MUST support all of 1686 the parameters defined by this specification. 1688 Each parameter in a SETTINGS frame replaces any existing value for 1689 that parameter. Parameters are processed in the order in which they 1690 appear, and a receiver of a SETTINGS frame does not need to maintain 1691 any state other than the current value of its parameters. Therefore, 1692 the value of a SETTINGS parameter is the last value that is seen by a 1693 receiver. 1695 SETTINGS parameters are acknowledged by the receiving peer. To 1696 enable this, the SETTINGS frame defines the following flag: 1698 ACK (0x1): When set, bit 0 indicates that this frame acknowledges 1699 receipt and application of the peer's SETTINGS frame. When this 1700 bit is set, the payload of the SETTINGS frame MUST be empty. 1701 Receipt of a SETTINGS frame with the ACK flag set and a length 1702 field value other than 0 MUST be treated as a connection error 1703 (Section 5.4.1) of type FRAME_SIZE_ERROR. For more information, 1704 see Section 6.5.3 ("Settings Synchronization"). 1706 SETTINGS frames always apply to a connection, never a single stream. 1707 The stream identifier for a SETTINGS frame MUST be zero (0x0). If an 1708 endpoint receives a SETTINGS frame whose stream identifier field is 1709 anything other than 0x0, the endpoint MUST respond with a connection 1710 error (Section 5.4.1) of type PROTOCOL_ERROR. 1712 The SETTINGS frame affects connection state. A badly formed or 1713 incomplete SETTINGS frame MUST be treated as a connection error 1714 (Section 5.4.1) of type PROTOCOL_ERROR. 1716 A SETTINGS frame with a length other than a multiple of 6 octets MUST 1717 be treated as a connection error (Section 5.4.1) of type 1718 FRAME_SIZE_ERROR. 1720 6.5.1. SETTINGS Format 1722 The payload of a SETTINGS frame consists of zero or more parameters, 1723 each consisting of an unsigned 16-bit setting identifier and an 1724 unsigned 32-bit value. 1726 +-------------------------------+ 1727 | Identifier (16) | 1728 +-------------------------------+-------------------------------+ 1729 | Value (32) | 1730 +---------------------------------------------------------------+ 1732 Figure 10: Setting Format 1734 6.5.2. Defined SETTINGS Parameters 1736 The following parameters are defined: 1738 SETTINGS_HEADER_TABLE_SIZE (0x1): Allows the sender to inform the 1739 remote endpoint of the maximum size of the header compression 1740 table used to decode header blocks, in octets. The encoder can 1741 select any size equal to or less than this value by using 1742 signaling specific to the header compression format inside a 1743 header block (see [COMPRESSION]). The initial value is 4,096 1744 octets. 1746 SETTINGS_ENABLE_PUSH (0x2): This setting can be used to disable 1747 server push (Section 8.2). An endpoint MUST NOT send a 1748 PUSH_PROMISE frame if it receives this parameter set to a value of 1749 0. An endpoint that has both set this parameter to 0 and had it 1750 acknowledged MUST treat the receipt of a PUSH_PROMISE frame as a 1751 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1753 The initial value is 1, which indicates that server push is 1754 permitted. Any value other than 0 or 1 MUST be treated as a 1755 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1757 SETTINGS_MAX_CONCURRENT_STREAMS (0x3): Indicates the maximum number 1758 of concurrent streams that the sender will allow. This limit is 1759 directional: it applies to the number of streams that the sender 1760 permits the receiver to create. Initially, there is no limit to 1761 this value. It is recommended that this value be no smaller than 1762 100, so as to not unnecessarily limit parallelism. 1764 A value of 0 for SETTINGS_MAX_CONCURRENT_STREAMS SHOULD NOT be 1765 treated as special by endpoints. A zero value does prevent the 1766 creation of new streams; however, this can also happen for any 1767 limit that is exhausted with active streams. Servers SHOULD only 1768 set a zero value for short durations; if a server does not wish to 1769 accept requests, closing the connection is more appropriate. 1771 SETTINGS_INITIAL_WINDOW_SIZE (0x4): Indicates the sender's initial 1772 window size (in octets) for stream-level flow control. The 1773 initial value is 2^(16)-1 (65,535) octets. 1775 This setting affects the window size of all streams (see 1776 Section 6.9.2). 1778 Values above the maximum flow-control window size of 2^(31)-1 MUST 1779 be treated as a connection error (Section 5.4.1) of type 1780 FLOW_CONTROL_ERROR. 1782 SETTINGS_MAX_FRAME_SIZE (0x5): Indicates the size of the largest 1783 frame payload that the sender is willing to receive, in octets. 1785 The initial value is 2^(14) (16,384) octets. The value advertised 1786 by an endpoint MUST be between this initial value and the maximum 1787 allowed frame size (2^(24)-1 or 16,777,215 octets), inclusive. 1788 Values outside this range MUST be treated as a connection error 1789 (Section 5.4.1) of type PROTOCOL_ERROR. 1791 SETTINGS_MAX_HEADER_LIST_SIZE (0x6): This advisory setting informs a 1792 peer of the maximum size of header list that the sender is 1793 prepared to accept, in octets. The value is based on the 1794 uncompressed size of header fields, including the length of the 1795 name and value in octets plus an overhead of 32 octets for each 1796 header field. 1798 For any given request, a lower limit than what is advertised MAY 1799 be enforced. The initial value of this setting is unlimited. 1801 An endpoint that receives a SETTINGS frame with any unknown or 1802 unsupported identifier MUST ignore that setting. 1804 6.5.3. Settings Synchronization 1806 Most values in SETTINGS benefit from or require an understanding of 1807 when the peer has received and applied the changed parameter values. 1808 In order to provide such synchronization timepoints, the recipient of 1809 a SETTINGS frame in which the ACK flag is not set MUST apply the 1810 updated parameters as soon as possible upon receipt. 1812 The values in the SETTINGS frame MUST be processed in the order they 1813 appear, with no other frame processing between values. Unsupported 1814 parameters MUST be ignored. Once all values have been processed, the 1815 recipient MUST immediately emit a SETTINGS frame with the ACK flag 1816 set. Upon receiving a SETTINGS frame with the ACK flag set, the 1817 sender of the altered parameters can rely on the setting having been 1818 applied. 1820 If the sender of a SETTINGS frame does not receive an acknowledgement 1821 within a reasonable amount of time, it MAY issue a connection error 1822 (Section 5.4.1) of type SETTINGS_TIMEOUT. 1824 6.6. PUSH_PROMISE 1826 The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint 1827 in advance of streams the sender intends to initiate. The 1828 PUSH_PROMISE frame includes the unsigned 31-bit identifier of the 1829 stream the endpoint plans to create along with a set of headers that 1830 provide additional context for the stream. Section 8.2 contains a 1831 thorough description of the use of PUSH_PROMISE frames. 1833 +---------------+ 1834 |Pad Length? (8)| 1835 +-+-------------+-----------------------------------------------+ 1836 |R| Promised Stream ID (31) | 1837 +-+-----------------------------+-------------------------------+ 1838 | Header Block Fragment (*) ... 1839 +---------------------------------------------------------------+ 1840 | Padding (*) ... 1841 +---------------------------------------------------------------+ 1843 Figure 11: PUSH_PROMISE Payload Format 1845 The PUSH_PROMISE frame payload has the following fields: 1847 Pad Length: An 8-bit field containing the length of the frame 1848 padding in units of octets. This field is only present if the 1849 PADDED flag is set. 1851 R: A single reserved bit. 1853 Promised Stream ID: An unsigned 31-bit integer that identifies the 1854 stream that is reserved by the PUSH_PROMISE. The promised stream 1855 identifier MUST be a valid choice for the next stream sent by the 1856 sender (see "new stream identifier" in Section 5.1.1). 1858 Header Block Fragment: A header block fragment (Section 4.3) 1859 containing request header fields. 1861 Padding: Padding octets. 1863 The PUSH_PROMISE frame defines the following flags: 1865 END_HEADERS (0x4): When set, bit 2 indicates that this frame 1866 contains an entire header block (Section 4.3) and is not followed 1867 by any CONTINUATION frames. 1869 A PUSH_PROMISE frame without the END_HEADERS flag set MUST be 1870 followed by a CONTINUATION frame for the same stream. A receiver 1871 MUST treat the receipt of any other type of frame or a frame on a 1872 different stream as a connection error (Section 5.4.1) of type 1873 PROTOCOL_ERROR. 1875 PADDED (0x8): When set, bit 3 indicates that the Pad Length field 1876 and any padding that it describes are present. 1878 PUSH_PROMISE frames MUST only be sent on a peer-initiated stream that 1879 is in either the "open" or "half-closed (remote)" state. The stream 1880 identifier of a PUSH_PROMISE frame indicates the stream it is 1881 associated with. If the stream identifier field specifies the value 1882 0x0, a recipient MUST respond with a connection error (Section 5.4.1) 1883 of type PROTOCOL_ERROR. 1885 Promised streams are not required to be used in the order they are 1886 promised. The PUSH_PROMISE only reserves stream identifiers for 1887 later use. 1889 PUSH_PROMISE MUST NOT be sent if the SETTINGS_ENABLE_PUSH setting of 1890 the peer endpoint is set to 0. An endpoint that has set this setting 1891 and has received acknowledgement MUST treat the receipt of a 1892 PUSH_PROMISE frame as a connection error (Section 5.4.1) of type 1893 PROTOCOL_ERROR. 1895 Recipients of PUSH_PROMISE frames can choose to reject promised 1896 streams by returning a RST_STREAM referencing the promised stream 1897 identifier back to the sender of the PUSH_PROMISE. 1899 A PUSH_PROMISE frame modifies the connection state in two ways. 1900 First, the inclusion of a header block (Section 4.3) potentially 1901 modifies the state maintained for header compression. Second, 1902 PUSH_PROMISE also reserves a stream for later use, causing the 1903 promised stream to enter the "reserved" state. A sender MUST NOT 1904 send a PUSH_PROMISE on a stream unless that stream is either "open" 1905 or "half-closed (remote)"; the sender MUST ensure that the promised 1906 stream is a valid choice for a new stream identifier (Section 5.1.1) 1907 (that is, the promised stream MUST be in the "idle" state). 1909 Since PUSH_PROMISE reserves a stream, ignoring a PUSH_PROMISE frame 1910 causes the stream state to become indeterminate. A receiver MUST 1911 treat the receipt of a PUSH_PROMISE on a stream that is neither 1912 "open" nor "half-closed (local)" as a connection error 1913 (Section 5.4.1) of type PROTOCOL_ERROR. However, an endpoint that 1914 has sent RST_STREAM on the associated stream MUST handle PUSH_PROMISE 1915 frames that might have been created before the RST_STREAM frame is 1916 received and processed. 1918 A receiver MUST treat the receipt of a PUSH_PROMISE that promises an 1919 illegal stream identifier (Section 5.1.1) as a connection error 1920 (Section 5.4.1) of type PROTOCOL_ERROR. Note that an illegal stream 1921 identifier is an identifier for a stream that is not currently in the 1922 "idle" state. 1924 The PUSH_PROMISE frame can include padding. Padding fields and flags 1925 are identical to those defined for DATA frames (Section 6.1). 1927 6.7. PING 1929 The PING frame (type=0x6) is a mechanism for measuring a minimal 1930 round-trip time from the sender, as well as determining whether an 1931 idle connection is still functional. PING frames can be sent from 1932 any endpoint. 1934 +---------------------------------------------------------------+ 1935 | | 1936 | Opaque Data (64) | 1937 | | 1938 +---------------------------------------------------------------+ 1940 Figure 12: PING Payload Format 1942 In addition to the frame header, PING frames MUST contain 8 octets of 1943 opaque data in the payload. A sender can include any value it 1944 chooses and use those octets in any fashion. 1946 Receivers of a PING frame that does not include an ACK flag MUST send 1947 a PING frame with the ACK flag set in response, with an identical 1948 payload. PING responses SHOULD be given higher priority than any 1949 other frame. 1951 The PING frame defines the following flags: 1953 ACK (0x1): When set, bit 0 indicates that this PING frame is a PING 1954 response. An endpoint MUST set this flag in PING responses. An 1955 endpoint MUST NOT respond to PING frames containing this flag. 1957 PING frames are not associated with any individual stream. If a PING 1958 frame is received with a stream identifier field value other than 1959 0x0, the recipient MUST respond with a connection error 1960 (Section 5.4.1) of type PROTOCOL_ERROR. 1962 Receipt of a PING frame with a length field value other than 8 MUST 1963 be treated as a connection error (Section 5.4.1) of type 1964 FRAME_SIZE_ERROR. 1966 6.8. GOAWAY 1968 The GOAWAY frame (type=0x7) is used to initiate shutdown of a 1969 connection or to signal serious error conditions. GOAWAY allows an 1970 endpoint to gracefully stop accepting new streams while still 1971 finishing processing of previously established streams. This enables 1972 administrative actions, like server maintenance. 1974 There is an inherent race condition between an endpoint starting new 1975 streams and the remote sending a GOAWAY frame. To deal with this 1976 case, the GOAWAY contains the stream identifier of the last peer- 1977 initiated stream that was or might be processed on the sending 1978 endpoint in this connection. For instance, if the server sends a 1979 GOAWAY frame, the identified stream is the highest-numbered stream 1980 initiated by the client. 1982 Once sent, the sender will ignore frames sent on streams initiated by 1983 the receiver if the stream has an identifier higher than the included 1984 last stream identifier. Receivers of a GOAWAY frame MUST NOT open 1985 additional streams on the connection, although a new connection can 1986 be established for new streams. 1988 If the receiver of the GOAWAY has sent data on streams with a higher 1989 stream identifier than what is indicated in the GOAWAY frame, those 1990 streams are not or will not be processed. The receiver of the GOAWAY 1991 frame can treat the streams as though they had never been created at 1992 all, thereby allowing those streams to be retried later on a new 1993 connection. 1995 Endpoints SHOULD always send a GOAWAY frame before closing a 1996 connection so that the remote peer can know whether a stream has been 1997 partially processed or not. For example, if an HTTP client sends a 1998 POST at the same time that a server closes a connection, the client 1999 cannot know if the server started to process that POST request if the 2000 server does not send a GOAWAY frame to indicate what streams it might 2001 have acted on. 2003 An endpoint might choose to close a connection without sending a 2004 GOAWAY for misbehaving peers. 2006 A GOAWAY frame might not immediately precede closing of the 2007 connection; a receiver of a GOAWAY that has no more use for the 2008 connection SHOULD still send a GOAWAY frame before terminating the 2009 connection. 2011 +-+-------------------------------------------------------------+ 2012 |R| Last-Stream-ID (31) | 2013 +-+-------------------------------------------------------------+ 2014 | Error Code (32) | 2015 +---------------------------------------------------------------+ 2016 | Additional Debug Data (*) | 2017 +---------------------------------------------------------------+ 2019 Figure 13: GOAWAY Payload Format 2021 The GOAWAY frame does not define any flags. 2023 The GOAWAY frame applies to the connection, not a specific stream. 2024 An endpoint MUST treat a GOAWAY frame with a stream identifier other 2025 than 0x0 as a connection error (Section 5.4.1) of type 2026 PROTOCOL_ERROR. 2028 The last stream identifier in the GOAWAY frame contains the highest- 2029 numbered stream identifier for which the sender of the GOAWAY frame 2030 might have taken some action on or might yet take action on. All 2031 streams up to and including the identified stream might have been 2032 processed in some way. The last stream identifier can be set to 0 if 2033 no streams were processed. 2035 | Note: In this context, "processed" means that some data from 2036 | the stream was passed to some higher layer of software that 2037 | might have taken some action as a result. 2039 If a connection terminates without a GOAWAY frame, the last stream 2040 identifier is effectively the highest possible stream identifier. 2042 On streams with lower- or equal-numbered identifiers that were not 2043 closed completely prior to the connection being closed, reattempting 2044 requests, transactions, or any protocol activity is not possible, 2045 with the exception of idempotent actions like HTTP GET, PUT, or 2046 DELETE. Any protocol activity that uses higher-numbered streams can 2047 be safely retried using a new connection. 2049 Activity on streams numbered lower or equal to the last stream 2050 identifier might still complete successfully. The sender of a GOAWAY 2051 frame might gracefully shut down a connection by sending a GOAWAY 2052 frame, maintaining the connection in an "open" state until all in- 2053 progress streams complete. 2055 An endpoint MAY send multiple GOAWAY frames if circumstances change. 2056 For instance, an endpoint that sends GOAWAY with NO_ERROR during 2057 graceful shutdown could subsequently encounter a condition that 2058 requires immediate termination of the connection. The last stream 2059 identifier from the last GOAWAY frame received indicates which 2060 streams could have been acted upon. Endpoints MUST NOT increase the 2061 value they send in the last stream identifier, since the peers might 2062 already have retried unprocessed requests on another connection. 2064 A client that is unable to retry requests loses all requests that are 2065 in flight when the server closes the connection. This is especially 2066 true for intermediaries that might not be serving clients using 2067 HTTP/2. A server that is attempting to gracefully shut down a 2068 connection SHOULD send an initial GOAWAY frame with the last stream 2069 identifier set to 2^(31)-1 and a NO_ERROR code. This signals to the 2070 client that a shutdown is imminent and that initiating further 2071 requests is prohibited. After allowing time for any in-flight stream 2072 creation (at least one round-trip time), the server can send another 2073 GOAWAY frame with an updated last stream identifier. This ensures 2074 that a connection can be cleanly shut down without losing requests. 2076 After sending a GOAWAY frame, the sender can discard frames for 2077 streams initiated by the receiver with identifiers higher than the 2078 identified last stream. However, any frames that alter connection 2079 state cannot be completely ignored. For instance, HEADERS, 2080 PUSH_PROMISE, and CONTINUATION frames MUST be minimally processed to 2081 ensure the state maintained for header compression is consistent (see 2082 Section 4.3); similarly, DATA frames MUST be counted toward the 2083 connection flow-control window. Failure to process these frames can 2084 cause flow control or header compression state to become 2085 unsynchronized. 2087 The GOAWAY frame also contains a 32-bit error code (Section 7) that 2088 contains the reason for closing the connection. 2090 Endpoints MAY append opaque data to the payload of any GOAWAY frame. 2091 Additional debug data is intended for diagnostic purposes only and 2092 carries no semantic value. Debug information could contain security- 2093 or privacy-sensitive data. Logged or otherwise persistently stored 2094 debug data MUST have adequate safeguards to prevent unauthorized 2095 access. 2097 6.9. WINDOW_UPDATE 2099 The WINDOW_UPDATE frame (type=0x8) is used to implement flow control; 2100 see Section 5.2 for an overview. 2102 Flow control operates at two levels: on each individual stream and on 2103 the entire connection. 2105 Both types of flow control are hop by hop, that is, only between the 2106 two endpoints. Intermediaries do not forward WINDOW_UPDATE frames 2107 between dependent connections. However, throttling of data transfer 2108 by any receiver can indirectly cause the propagation of flow-control 2109 information toward the original sender. 2111 Flow control only applies to frames that are identified as being 2112 subject to flow control. Of the frame types defined in this 2113 document, this includes only DATA frames. Frames that are exempt 2114 from flow control MUST be accepted and processed, unless the receiver 2115 is unable to assign resources to handling the frame. A receiver MAY 2116 respond with a stream error (Section 5.4.2) or connection error 2117 (Section 5.4.1) of type FLOW_CONTROL_ERROR if it is unable to accept 2118 a frame. 2120 +-+-------------------------------------------------------------+ 2121 |R| Window Size Increment (31) | 2122 +-+-------------------------------------------------------------+ 2124 Figure 14: WINDOW_UPDATE Payload Format 2126 The payload of a WINDOW_UPDATE frame is one reserved bit plus an 2127 unsigned 31-bit integer indicating the number of octets that the 2128 sender can transmit in addition to the existing flow-control window. 2129 The legal range for the increment to the flow-control window is 1 to 2130 2^(31)-1 (2,147,483,647) octets. 2132 The WINDOW_UPDATE frame does not define any flags. 2134 The WINDOW_UPDATE frame can be specific to a stream or to the entire 2135 connection. In the former case, the frame's stream identifier 2136 indicates the affected stream; in the latter, the value "0" indicates 2137 that the entire connection is the subject of the frame. 2139 A receiver MUST treat the receipt of a WINDOW_UPDATE frame with an 2140 flow-control window increment of 0 as a stream error (Section 5.4.2) 2141 of type PROTOCOL_ERROR; errors on the connection flow-control window 2142 MUST be treated as a connection error (Section 5.4.1). 2144 WINDOW_UPDATE can be sent by a peer that has sent a frame bearing the 2145 END_STREAM flag. This means that a receiver could receive a 2146 WINDOW_UPDATE frame on a "half-closed (remote)" or "closed" stream. 2147 A receiver MUST NOT treat this as an error (see Section 5.1). 2149 A receiver that receives a flow-controlled frame MUST always account 2150 for its contribution against the connection flow-control window, 2151 unless the receiver treats this as a connection error 2152 (Section 5.4.1). This is necessary even if the frame is in error. 2154 The sender counts the frame toward the flow-control window, but if 2155 the receiver does not, the flow-control window at the sender and 2156 receiver can become different. 2158 A WINDOW_UPDATE frame with a length other than 4 octets MUST be 2159 treated as a connection error (Section 5.4.1) of type 2160 FRAME_SIZE_ERROR. 2162 6.9.1. The Flow-Control Window 2164 Flow control in HTTP/2 is implemented using a window kept by each 2165 sender on every stream. The flow-control window is a simple integer 2166 value that indicates how many octets of data the sender is permitted 2167 to transmit; as such, its size is a measure of the buffering capacity 2168 of the receiver. 2170 Two flow-control windows are applicable: the stream flow-control 2171 window and the connection flow-control window. The sender MUST NOT 2172 send a flow-controlled frame with a length that exceeds the space 2173 available in either of the flow-control windows advertised by the 2174 receiver. Frames with zero length with the END_STREAM flag set (that 2175 is, an empty DATA frame) MAY be sent if there is no available space 2176 in either flow-control window. 2178 For flow-control calculations, the 9-octet frame header is not 2179 counted. 2181 After sending a flow-controlled frame, the sender reduces the space 2182 available in both windows by the length of the transmitted frame. 2184 The receiver of a frame sends a WINDOW_UPDATE frame as it consumes 2185 data and frees up space in flow-control windows. Separate 2186 WINDOW_UPDATE frames are sent for the stream- and connection-level 2187 flow-control windows. 2189 A sender that receives a WINDOW_UPDATE frame updates the 2190 corresponding window by the amount specified in the frame. 2192 A sender MUST NOT allow a flow-control window to exceed 2^(31)-1 2193 octets. If a sender receives a WINDOW_UPDATE that causes a flow- 2194 control window to exceed this maximum, it MUST terminate either the 2195 stream or the connection, as appropriate. For streams, the sender 2196 sends a RST_STREAM with an error code of FLOW_CONTROL_ERROR; for the 2197 connection, a GOAWAY frame with an error code of FLOW_CONTROL_ERROR 2198 is sent. 2200 Flow-controlled frames from the sender and WINDOW_UPDATE frames from 2201 the receiver are completely asynchronous with respect to each other. 2202 This property allows a receiver to aggressively update the window 2203 size kept by the sender to prevent streams from stalling. 2205 6.9.2. Initial Flow-Control Window Size 2207 When an HTTP/2 connection is first established, new streams are 2208 created with an initial flow-control window size of 65,535 octets. 2209 The connection flow-control window is also 65,535 octets. Both 2210 endpoints can adjust the initial window size for new streams by 2211 including a value for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS 2212 frame that forms part of the connection preface. The connection 2213 flow-control window can only be changed using WINDOW_UPDATE frames. 2215 Prior to receiving a SETTINGS frame that sets a value for 2216 SETTINGS_INITIAL_WINDOW_SIZE, an endpoint can only use the default 2217 initial window size when sending flow-controlled frames. Similarly, 2218 the connection flow-control window is set to the default initial 2219 window size until a WINDOW_UPDATE frame is received. 2221 In addition to changing the flow-control window for streams that are 2222 not yet active, a SETTINGS frame can alter the initial flow-control 2223 window size for streams with active flow-control windows (that is, 2224 streams in the "open" or "half-closed (remote)" state). When the 2225 value of SETTINGS_INITIAL_WINDOW_SIZE changes, a receiver MUST adjust 2226 the size of all stream flow-control windows that it maintains by the 2227 difference between the new value and the old value. 2229 A change to SETTINGS_INITIAL_WINDOW_SIZE can cause the available 2230 space in a flow-control window to become negative. A sender MUST 2231 track the negative flow-control window and MUST NOT send new flow- 2232 controlled frames until it receives WINDOW_UPDATE frames that cause 2233 the flow-control window to become positive. 2235 For example, if the client sends 60 KB immediately on connection 2236 establishment and the server sets the initial window size to be 16 2237 KB, the client will recalculate the available flow-control window to 2238 be -44 KB on receipt of the SETTINGS frame. The client retains a 2239 negative flow-control window until WINDOW_UPDATE frames restore the 2240 window to being positive, after which the client can resume sending. 2242 A SETTINGS frame cannot alter the connection flow-control window. 2244 An endpoint MUST treat a change to SETTINGS_INITIAL_WINDOW_SIZE that 2245 causes any flow-control window to exceed the maximum size as a 2246 connection error (Section 5.4.1) of type FLOW_CONTROL_ERROR. 2248 6.9.3. Reducing the Stream Window Size 2250 A receiver that wishes to use a smaller flow-control window than the 2251 current size can send a new SETTINGS frame. However, the receiver 2252 MUST be prepared to receive data that exceeds this window size, since 2253 the sender might send data that exceeds the lower limit prior to 2254 processing the SETTINGS frame. 2256 After sending a SETTINGS frame that reduces the initial flow-control 2257 window size, a receiver MAY continue to process streams that exceed 2258 flow-control limits. Allowing streams to continue does not allow the 2259 receiver to immediately reduce the space it reserves for flow-control 2260 windows. Progress on these streams can also stall, since 2261 WINDOW_UPDATE frames are needed to allow the sender to resume 2262 sending. The receiver MAY instead send a RST_STREAM with an error 2263 code of FLOW_CONTROL_ERROR for the affected streams. 2265 6.10. CONTINUATION 2267 The CONTINUATION frame (type=0x9) is used to continue a sequence of 2268 header block fragments (Section 4.3). Any number of CONTINUATION 2269 frames can be sent, as long as the preceding frame is on the same 2270 stream and is a HEADERS, PUSH_PROMISE, or CONTINUATION frame without 2271 the END_HEADERS flag set. 2273 +---------------------------------------------------------------+ 2274 | Header Block Fragment (*) ... 2275 +---------------------------------------------------------------+ 2277 Figure 15: CONTINUATION Frame Payload 2279 The CONTINUATION frame payload contains a header block fragment 2280 (Section 4.3). 2282 The CONTINUATION frame defines the following flag: 2284 END_HEADERS (0x4): When set, bit 2 indicates that this frame ends a 2285 header block (Section 4.3). 2287 If the END_HEADERS bit is not set, this frame MUST be followed by 2288 another CONTINUATION frame. A receiver MUST treat the receipt of 2289 any other type of frame or a frame on a different stream as a 2290 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 2292 The CONTINUATION frame changes the connection state as defined in 2293 Section 4.3. 2295 CONTINUATION frames MUST be associated with a stream. If a 2296 CONTINUATION frame is received whose stream identifier field is 0x0, 2297 the recipient MUST respond with a connection error (Section 5.4.1) of 2298 type PROTOCOL_ERROR. 2300 A CONTINUATION frame MUST be preceded by a HEADERS, PUSH_PROMISE or 2301 CONTINUATION frame without the END_HEADERS flag set. A recipient 2302 that observes violation of this rule MUST respond with a connection 2303 error (Section 5.4.1) of type PROTOCOL_ERROR. 2305 7. Error Codes 2307 Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY 2308 frames to convey the reasons for the stream or connection error. 2310 Error codes share a common code space. Some error codes apply only 2311 to either streams or the entire connection and have no defined 2312 semantics in the other context. 2314 The following error codes are defined: 2316 NO_ERROR (0x0): The associated condition is not a result of an 2317 error. For example, a GOAWAY might include this code to indicate 2318 graceful shutdown of a connection. 2320 PROTOCOL_ERROR (0x1): The endpoint detected an unspecific protocol 2321 error. This error is for use when a more specific error code is 2322 not available. 2324 INTERNAL_ERROR (0x2): The endpoint encountered an unexpected 2325 internal error. 2327 FLOW_CONTROL_ERROR (0x3): The endpoint detected that its peer 2328 violated the flow-control protocol. 2330 SETTINGS_TIMEOUT (0x4): The endpoint sent a SETTINGS frame but did 2331 not receive a response in a timely manner. See Section 6.5.3 2332 ("Settings Synchronization"). 2334 STREAM_CLOSED (0x5): The endpoint received a frame after a stream 2335 was half-closed. 2337 FRAME_SIZE_ERROR (0x6): The endpoint received a frame with an 2338 invalid size. 2340 REFUSED_STREAM (0x7): The endpoint refused the stream prior to 2341 performing any application processing (see Section 8.1.4 for 2342 details). 2344 CANCEL (0x8): Used by the endpoint to indicate that the stream is no 2345 longer needed. 2347 COMPRESSION_ERROR (0x9): The endpoint is unable to maintain the 2348 header compression context for the connection. 2350 CONNECT_ERROR (0xa): The connection established in response to a 2351 CONNECT request (Section 8.3) was reset or abnormally closed. 2353 ENHANCE_YOUR_CALM (0xb): The endpoint detected that its peer is 2354 exhibiting a behavior that might be generating excessive load. 2356 INADEQUATE_SECURITY (0xc): The underlying transport has properties 2357 that do not meet minimum security requirements (see Section 9.2). 2359 HTTP_1_1_REQUIRED (0xd): The endpoint requires that HTTP/1.1 be used 2360 instead of HTTP/2. 2362 Unknown or unsupported error codes MUST NOT trigger any special 2363 behavior. These MAY be treated by an implementation as being 2364 equivalent to INTERNAL_ERROR. 2366 8. HTTP Message Exchanges 2368 HTTP/2 is intended to be as compatible as possible with current uses 2369 of HTTP. This means that, from the application perspective, the 2370 features of the protocol are largely unchanged. To achieve this, all 2371 request and response semantics are preserved, although the syntax of 2372 conveying those semantics has changed. 2374 Thus, the specification and requirements of HTTP/1.1 Semantics and 2375 Content [RFC7231], Conditional Requests [RFC7232], Range Requests 2376 [RFC7233], Caching [RFC7234], and Authentication [RFC7235] are 2377 applicable to HTTP/2. Selected portions of HTTP/1.1 Message Syntax 2378 and Routing [RFC7230], such as the HTTP and HTTPS URI schemes, are 2379 also applicable in HTTP/2, but the expression of those semantics for 2380 this protocol are defined in the sections below. 2382 8.1. HTTP Request/Response Exchange 2384 A client sends an HTTP request on a new stream, using a previously 2385 unused stream identifier (Section 5.1.1). A server sends an HTTP 2386 response on the same stream as the request. 2388 An HTTP message (request or response) consists of: 2390 1. for a response only, zero or more HEADERS frames (each followed 2391 by zero or more CONTINUATION frames) containing the message 2392 headers of informational (1xx) HTTP responses (see Section 3.2 of 2393 [RFC7230] and Section 6.2 of [RFC7231]), 2395 2. one HEADERS frame (followed by zero or more CONTINUATION frames) 2396 containing the message headers (see Section 3.2 of [RFC7230]), 2398 3. zero or more DATA frames containing the payload body (see 2399 Section 3.3 of [RFC7230]), and 2401 4. optionally, one HEADERS frame, followed by zero or more 2402 CONTINUATION frames containing the trailer-part, if present (see 2403 Section 4.1.2 of [RFC7230]). 2405 The last frame in the sequence bears an END_STREAM flag, noting that 2406 a HEADERS frame bearing the END_STREAM flag can be followed by 2407 CONTINUATION frames that carry any remaining portions of the header 2408 block. 2410 Other frames (from any stream) MUST NOT occur between the HEADERS 2411 frame and any CONTINUATION frames that might follow. 2413 HTTP/2 uses DATA frames to carry message payloads. The "chunked" 2414 transfer encoding defined in Section 4.1 of [RFC7230] MUST NOT be 2415 used in HTTP/2. 2417 Trailing header fields are carried in a header block that also 2418 terminates the stream. Such a header block is a sequence starting 2419 with a HEADERS frame, followed by zero or more CONTINUATION frames, 2420 where the HEADERS frame bears an END_STREAM flag. Header blocks 2421 after the first that do not terminate the stream are not part of an 2422 HTTP request or response. 2424 A HEADERS frame (and associated CONTINUATION frames) can only appear 2425 at the start or end of a stream. An endpoint that receives a HEADERS 2426 frame without the END_STREAM flag set after receiving a final (non- 2427 informational) status code MUST treat the corresponding request or 2428 response as malformed (Section 8.1.2.6). 2430 An HTTP request/response exchange fully consumes a single stream. A 2431 request starts with the HEADERS frame that puts the stream into an 2432 "open" state. The request ends with a frame bearing END_STREAM, 2433 which causes the stream to become "half-closed (local)" for the 2434 client and "half-closed (remote)" for the server. A response starts 2435 with a HEADERS frame and ends with a frame bearing END_STREAM, which 2436 places the stream in the "closed" state. 2438 An HTTP response is complete after the server sends -- or the client 2439 receives -- a frame with the END_STREAM flag set (including any 2440 CONTINUATION frames needed to complete a header block). A server can 2441 send a complete response prior to the client sending an entire 2442 request if the response does not depend on any portion of the request 2443 that has not been sent and received. When this is true, a server MAY 2444 request that the client abort transmission of a request without error 2445 by sending a RST_STREAM with an error code of NO_ERROR after sending 2446 a complete response (i.e., a frame with the END_STREAM flag). 2447 Clients MUST NOT discard responses as a result of receiving such a 2448 RST_STREAM, though clients can always discard responses at their 2449 discretion for other reasons. 2451 8.1.1. Upgrading from HTTP/2 2453 HTTP/2 removes support for the 101 (Switching Protocols) 2454 informational status code (Section 6.2.2 of [RFC7231]). 2456 The semantics of 101 (Switching Protocols) aren't applicable to a 2457 multiplexed protocol. Alternative protocols are able to use the same 2458 mechanisms that HTTP/2 uses to negotiate their use (see Section 3). 2460 8.1.2. HTTP Header Fields 2462 HTTP header fields carry information as a series of key-value pairs. 2463 For a listing of registered HTTP headers, see the "Message Header 2464 Field" registry maintained at https://www.iana.org/assignments/ 2465 message-headers. 2467 Just as in HTTP/1.x, header field names are strings of ASCII 2468 characters that are compared in a case-insensitive fashion. However, 2469 header field names MUST be converted to lowercase prior to their 2470 encoding in HTTP/2. A request or response containing uppercase 2471 header field names MUST be treated as malformed (Section 8.1.2.6). 2473 8.1.2.1. Pseudo-Header Fields 2475 While HTTP/1.x used the message start-line (see Section 3.1 of 2476 [RFC7230]) to convey the target URI, the method of the request, and 2477 the status code for the response, HTTP/2 uses special pseudo-header 2478 fields beginning with ':' character (ASCII 0x3a) for this purpose. 2480 Pseudo-header fields are not HTTP header fields. Endpoints MUST NOT 2481 generate pseudo-header fields other than those defined in this 2482 document. 2484 Pseudo-header fields are only valid in the context in which they are 2485 defined. Pseudo-header fields defined for requests MUST NOT appear 2486 in responses; pseudo-header fields defined for responses MUST NOT 2487 appear in requests. Pseudo-header fields MUST NOT appear in 2488 trailers. Endpoints MUST treat a request or response that contains 2489 undefined or invalid pseudo-header fields as malformed 2490 (Section 8.1.2.6). 2492 All pseudo-header fields MUST appear in the header block before 2493 regular header fields. Any request or response that contains a 2494 pseudo-header field that appears in a header block after a regular 2495 header field MUST be treated as malformed (Section 8.1.2.6). 2497 8.1.2.2. Connection-Specific Header Fields 2499 HTTP/2 does not use the "Connection" header field to indicate 2500 connection-specific header fields; in this protocol, connection- 2501 specific metadata is conveyed by other means. An endpoint MUST NOT 2502 generate an HTTP/2 message containing connection-specific header 2503 fields; any message containing connection-specific header fields MUST 2504 be treated as malformed (Section 8.1.2.6). 2506 The only exception to this is the TE header field, which MAY be 2507 present in an HTTP/2 request; when it is, it MUST NOT contain any 2508 value other than "trailers". 2510 This means that an intermediary transforming an HTTP/1.x message to 2511 HTTP/2 will need to remove any header fields nominated by the 2512 Connection header field, along with the Connection header field 2513 itself. Such intermediaries SHOULD also remove other connection- 2514 specific header fields, such as Keep-Alive, Proxy-Connection, 2515 Transfer-Encoding, and Upgrade, even if they are not nominated by the 2516 Connection header field. 2518 | Note: HTTP/2 purposefully does not support upgrade to another 2519 | protocol. The handshake methods described in Section 3 are 2520 | believed sufficient to negotiate the use of alternative 2521 | protocols. 2523 8.1.2.3. Request Pseudo-Header Fields 2525 The following pseudo-header fields are defined for HTTP/2 requests: 2527 * The ":method" pseudo-header field includes the HTTP method 2528 (Section 4 of [RFC7231]). 2530 * The ":scheme" pseudo-header field includes the scheme portion of 2531 the target URI (Section 3.1 of [RFC3986]). 2533 ":scheme" is not restricted to "http" and "https" schemed URIs. A 2534 proxy or gateway can translate requests for non-HTTP schemes, 2535 enabling the use of HTTP to interact with non-HTTP services. 2537 * The ":authority" pseudo-header field includes the authority 2538 portion of the target URI (Section 3.2 of [RFC3986]). The 2539 authority MUST NOT include the deprecated "userinfo" subcomponent 2540 for "http" or "https" schemed URIs. 2542 To ensure that the HTTP/1.1 request line can be reproduced 2543 accurately, this pseudo-header field MUST be omitted when 2544 translating from an HTTP/1.1 request that has a request target in 2545 origin or asterisk form (see Section 5.3 of [RFC7230]). Clients 2546 that generate HTTP/2 requests directly SHOULD use the ":authority" 2547 pseudo-header field instead of the "Host" header field. An 2548 intermediary that converts an HTTP/2 request to HTTP/1.1 MUST 2549 create a "Host" header field if one is not present in a request by 2550 copying the value of the ":authority" pseudo-header field. 2552 * The ":path" pseudo-header field includes the path and query parts 2553 of the target URI (the "path-absolute" production and optionally a 2554 '?' character followed by the "query" production (see Sections 3.3 2555 and 3.4 of [RFC3986]). A request in asterisk form includes the 2556 value '*' for the ":path" pseudo-header field. 2558 This pseudo-header field MUST NOT be empty for "http" or "https" 2559 URIs; "http" or "https" URIs that do not contain a path component 2560 MUST include a value of '/'. The exception to this rule is an 2561 OPTIONS request for an "http" or "https" URI that does not include 2562 a path component; these MUST include a ":path" pseudo-header field 2563 with a value of '*' (see Section 5.3.4 of [RFC7230]). 2565 All HTTP/2 requests MUST include exactly one valid value for the 2566 ":method", ":scheme", and ":path" pseudo-header fields, unless it is 2567 a CONNECT request (Section 8.3). An HTTP request that omits 2568 mandatory pseudo-header fields is malformed (Section 8.1.2.6). 2570 HTTP/2 does not define a way to carry the version identifier that is 2571 included in the HTTP/1.1 request line. 2573 8.1.2.4. Response Pseudo-Header Fields 2575 For HTTP/2 responses, a single ":status" pseudo-header field is 2576 defined that carries the HTTP status code field (see Section 6 of 2577 [RFC7231]). This pseudo-header field MUST be included in all 2578 responses; otherwise, the response is malformed (Section 8.1.2.6). 2580 HTTP/2 does not define a way to carry the version or reason phrase 2581 that is included in an HTTP/1.1 status line. 2583 8.1.2.5. Compressing the Cookie Header Field 2585 The Cookie header field [COOKIE] uses a semi-colon (";") to delimit 2586 cookie-pairs (or "crumbs"). This header field doesn't follow the 2587 list construction rules in HTTP (see Section 3.2.2 of [RFC7230]), 2588 which prevents cookie-pairs from being separated into different name- 2589 value pairs. This can significantly reduce compression efficiency as 2590 individual cookie-pairs are updated. 2592 To allow for better compression efficiency, the Cookie header field 2593 MAY be split into separate header fields, each with one or more 2594 cookie-pairs. If there are multiple Cookie header fields after 2595 decompression, these MUST be concatenated into a single octet string 2596 using the two-octet delimiter of 0x3B, 0x20 (the ASCII string "; ") 2597 before being passed into a non-HTTP/2 context, such as an HTTP/1.1 2598 connection, or a generic HTTP server application. 2600 Therefore, the following two lists of Cookie header fields are 2601 semantically equivalent. 2603 cookie: a=b; c=d; e=f 2605 cookie: a=b 2606 cookie: c=d 2607 cookie: e=f 2609 8.1.2.6. Malformed Requests and Responses 2611 A malformed request or response is one that is an otherwise valid 2612 sequence of HTTP/2 frames but is invalid due to the presence of 2613 extraneous frames, prohibited header fields, the absence of mandatory 2614 header fields, or the inclusion of uppercase header field names. 2616 A request or response that includes a payload body can include a 2617 "content-length" header field. A request or response is also 2618 malformed if the value of a "content-length" header field does not 2619 equal the sum of the DATA frame payload lengths that form the body. 2620 A response that is defined to have no payload, as described in 2621 [RFC7230], can have a non-zero "content-length" header field, even 2622 though no content is included in DATA frames. 2624 Intermediaries that process HTTP requests or responses (i.e., any 2625 intermediary not acting as a tunnel) MUST NOT forward a malformed 2626 request or response. Malformed requests or responses that are 2627 detected MUST be treated as a stream error (Section 5.4.2) of type 2628 PROTOCOL_ERROR. 2630 For malformed requests, a server MAY send an HTTP response prior to 2631 closing or resetting the stream. Clients MUST NOT accept a malformed 2632 response. Note that these requirements are intended to protect 2633 against several types of common attacks against HTTP; they are 2634 deliberately strict because being permissive can expose 2635 implementations to these vulnerabilities. 2637 8.1.3. Examples 2639 This section shows HTTP/1.1 requests and responses, with 2640 illustrations of equivalent HTTP/2 requests and responses. 2642 An HTTP GET request includes request header fields and no payload 2643 body and is therefore transmitted as a single HEADERS frame, followed 2644 by zero or more CONTINUATION frames containing the serialized block 2645 of request header fields. The HEADERS frame in the following has 2646 both the END_HEADERS and END_STREAM flags set; no CONTINUATION frames 2647 are sent. 2649 GET /resource HTTP/1.1 HEADERS 2650 Host: example.org ==> + END_STREAM 2651 Accept: image/jpeg + END_HEADERS 2652 :method = GET 2653 :scheme = https 2654 :path = /resource 2655 host = example.org 2656 accept = image/jpeg 2658 Similarly, a response that includes only response header fields is 2659 transmitted as a HEADERS frame (again, followed by zero or more 2660 CONTINUATION frames) containing the serialized block of response 2661 header fields. 2663 HTTP/1.1 304 Not Modified HEADERS 2664 ETag: "xyzzy" ==> + END_STREAM 2665 Expires: Thu, 23 Jan ... + END_HEADERS 2666 :status = 304 2667 etag = "xyzzy" 2668 expires = Thu, 23 Jan ... 2670 An HTTP POST request that includes request header fields and payload 2671 data is transmitted as one HEADERS frame, followed by zero or more 2672 CONTINUATION frames containing the request header fields, followed by 2673 one or more DATA frames, with the last CONTINUATION (or HEADERS) 2674 frame having the END_HEADERS flag set and the final DATA frame having 2675 the END_STREAM flag set: 2677 POST /resource HTTP/1.1 HEADERS 2678 Host: example.org ==> - END_STREAM 2679 Content-Type: image/jpeg - END_HEADERS 2680 Content-Length: 123 :method = POST 2681 :path = /resource 2682 {binary data} :scheme = https 2684 CONTINUATION 2685 + END_HEADERS 2686 content-type = image/jpeg 2687 host = example.org 2688 content-length = 123 2690 DATA 2691 + END_STREAM 2692 {binary data} 2694 Note that data contributing to any given header field could be spread 2695 between header block fragments. The allocation of header fields to 2696 frames in this example is illustrative only. 2698 A response that includes header fields and payload data is 2699 transmitted as a HEADERS frame, followed by zero or more CONTINUATION 2700 frames, followed by one or more DATA frames, with the last DATA frame 2701 in the sequence having the END_STREAM flag set: 2703 HTTP/1.1 200 OK HEADERS 2704 Content-Type: image/jpeg ==> - END_STREAM 2705 Content-Length: 123 + END_HEADERS 2706 :status = 200 2707 {binary data} content-type = image/jpeg 2708 content-length = 123 2710 DATA 2711 + END_STREAM 2712 {binary data} 2714 An informational response using a 1xx status code other than 101 is 2715 transmitted as a HEADERS frame, followed by zero or more CONTINUATION 2716 frames. 2718 Trailing header fields are sent as a header block after both the 2719 request or response header block and all the DATA frames have been 2720 sent. The HEADERS frame starting the trailers header block has the 2721 END_STREAM flag set. 2723 The following example includes both a 100 (Continue) status code, 2724 which is sent in response to a request containing a "100-continue" 2725 token in the Expect header field, and trailing header fields: 2727 HTTP/1.1 100 Continue HEADERS 2728 Extension-Field: bar ==> - END_STREAM 2729 + END_HEADERS 2730 :status = 100 2731 extension-field = bar 2733 HTTP/1.1 200 OK HEADERS 2734 Content-Type: image/jpeg ==> - END_STREAM 2735 Transfer-Encoding: chunked + END_HEADERS 2736 Trailer: Foo :status = 200 2737 content-length = 123 2738 123 content-type = image/jpeg 2739 {binary data} trailer = Foo 2740 0 2741 Foo: bar DATA 2742 - END_STREAM 2743 {binary data} 2745 HEADERS 2746 + END_STREAM 2747 + END_HEADERS 2748 foo = bar 2750 8.1.4. Request Reliability Mechanisms in HTTP/2 2752 In HTTP/1.1, an HTTP client is unable to retry a non-idempotent 2753 request when an error occurs because there is no means to determine 2754 the nature of the error. It is possible that some server processing 2755 occurred prior to the error, which could result in undesirable 2756 effects if the request were reattempted. 2758 HTTP/2 provides two mechanisms for providing a guarantee to a client 2759 that a request has not been processed: 2761 * The GOAWAY frame indicates the highest stream number that might 2762 have been processed. Requests on streams with higher numbers are 2763 therefore guaranteed to be safe to retry. 2765 * The REFUSED_STREAM error code can be included in a RST_STREAM 2766 frame to indicate that the stream is being closed prior to any 2767 processing having occurred. Any request that was sent on the 2768 reset stream can be safely retried. 2770 Requests that have not been processed have not failed; clients MAY 2771 automatically retry them, even those with non-idempotent methods. 2773 A server MUST NOT indicate that a stream has not been processed 2774 unless it can guarantee that fact. If frames that are on a stream 2775 are passed to the application layer for any stream, then 2776 REFUSED_STREAM MUST NOT be used for that stream, and a GOAWAY frame 2777 MUST include a stream identifier that is greater than or equal to the 2778 given stream identifier. 2780 In addition to these mechanisms, the PING frame provides a way for a 2781 client to easily test a connection. Connections that remain idle can 2782 become broken as some middleboxes (for instance, network address 2783 translators or load balancers) silently discard connection bindings. 2784 The PING frame allows a client to safely test whether a connection is 2785 still active without sending a request. 2787 8.2. Server Push 2789 HTTP/2 allows a server to pre-emptively send (or "push") responses 2790 (along with corresponding "promised" requests) to a client in 2791 association with a previous client-initiated request. This can be 2792 useful when the server knows the client will need to have those 2793 responses available in order to fully process the response to the 2794 original request. 2796 A client can request that server push be disabled, though this is 2797 negotiated for each hop independently. The SETTINGS_ENABLE_PUSH 2798 setting can be set to 0 to indicate that server push is disabled. 2800 Promised requests MUST be cacheable (see Section 4.2.3 of [RFC7231]), 2801 MUST be safe (see Section 4.2.1 of [RFC7231]), and MUST NOT include a 2802 request body. Clients that receive a promised request that is not 2803 cacheable, that is not known to be safe, or that indicates the 2804 presence of a request body MUST reset the promised stream with a 2805 stream error (Section 5.4.2) of type PROTOCOL_ERROR. Note this could 2806 result in the promised stream being reset if the client does not 2807 recognize a newly defined method as being safe. 2809 Pushed responses that are cacheable (see Section 3 of [RFC7234]) can 2810 be stored by the client, if it implements an HTTP cache. Pushed 2811 responses are considered successfully validated on the origin server 2812 (e.g., if the "no-cache" cache response directive is present; see 2813 Section 5.2.2 of [RFC7234]) while the stream identified by the 2814 promised stream ID is still open. 2816 Pushed responses that are not cacheable MUST NOT be stored by any 2817 HTTP cache. They MAY be made available to the application 2818 separately. 2820 The server MUST include a value in the ":authority" pseudo-header 2821 field for which the server is authoritative (see Section 10.1). A 2822 client MUST treat a PUSH_PROMISE for which the server is not 2823 authoritative as a stream error (Section 5.4.2) of type 2824 PROTOCOL_ERROR. 2826 An intermediary can receive pushes from the server and choose not to 2827 forward them on to the client. In other words, how to make use of 2828 the pushed information is up to that intermediary. Equally, the 2829 intermediary might choose to make additional pushes to the client, 2830 without any action taken by the server. 2832 A client cannot push. Thus, servers MUST treat the receipt of a 2833 PUSH_PROMISE frame as a connection error (Section 5.4.1) of type 2834 PROTOCOL_ERROR. Clients MUST reject any attempt to change the 2835 SETTINGS_ENABLE_PUSH setting to a value other than 0 by treating the 2836 message as a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 2838 8.2.1. Push Requests 2840 Server push is semantically equivalent to a server responding to a 2841 request; however, in this case, that request is also sent by the 2842 server, as a PUSH_PROMISE frame. 2844 The PUSH_PROMISE frame includes a header block that contains a 2845 complete set of request header fields that the server attributes to 2846 the request. It is not possible to push a response to a request that 2847 includes a request body. 2849 Promised requests are always associated with an explicit request from 2850 the client. The PUSH_PROMISE frames sent by the server are sent on 2851 that explicit request's stream. The PUSH_PROMISE frame also includes 2852 a promised stream identifier, chosen from the stream identifiers 2853 available to the server (see Section 5.1.1). 2855 The header fields in PUSH_PROMISE and any subsequent CONTINUATION 2856 frames MUST be a valid and complete set of request header fields 2857 (Section 8.1.2.3). The server MUST include a method in the ":method" 2858 pseudo-header field that is safe and cacheable. If a client receives 2859 a PUSH_PROMISE that does not include a complete and valid set of 2860 header fields or the ":method" pseudo-header field identifies a 2861 method that is not safe, it MUST respond with a stream error 2862 (Section 5.4.2) of type PROTOCOL_ERROR. 2864 The server SHOULD send PUSH_PROMISE (Section 6.6) frames prior to 2865 sending any frames that reference the promised responses. This 2866 avoids a race where clients issue requests prior to receiving any 2867 PUSH_PROMISE frames. 2869 For example, if the server receives a request for a document 2870 containing embedded links to multiple image files and the server 2871 chooses to push those additional images to the client, sending 2872 PUSH_PROMISE frames before the DATA frames that contain the image 2873 links ensures that the client is able to see that a resource will be 2874 pushed before discovering embedded links. Similarly, if the server 2875 pushes responses referenced by the header block (for instance, in 2876 Link header fields), sending a PUSH_PROMISE before sending the header 2877 block ensures that clients do not request those resources. 2879 PUSH_PROMISE frames MUST NOT be sent by the client. 2881 PUSH_PROMISE frames can be sent by the server in response to any 2882 client-initiated stream, but the stream MUST be in either the "open" 2883 or "half-closed (remote)" state with respect to the server. 2884 PUSH_PROMISE frames are interspersed with the frames that comprise a 2885 response, though they cannot be interspersed with HEADERS and 2886 CONTINUATION frames that comprise a single header block. 2888 Sending a PUSH_PROMISE frame creates a new stream and puts the stream 2889 into the "reserved (local)" state for the server and the "reserved 2890 (remote)" state for the client. 2892 8.2.2. Push Responses 2894 After sending the PUSH_PROMISE frame, the server can begin delivering 2895 the pushed response as a response (Section 8.1.2.4) on a server- 2896 initiated stream that uses the promised stream identifier. The 2897 server uses this stream to transmit an HTTP response, using the same 2898 sequence of frames as defined in Section 8.1. This stream becomes 2899 "half-closed" to the client (Section 5.1) after the initial HEADERS 2900 frame is sent. 2902 Once a client receives a PUSH_PROMISE frame and chooses to accept the 2903 pushed response, the client SHOULD NOT issue any requests for the 2904 promised response until after the promised stream has closed. 2906 If the client determines, for any reason, that it does not wish to 2907 receive the pushed response from the server or if the server takes 2908 too long to begin sending the promised response, the client can send 2909 a RST_STREAM frame, using either the CANCEL or REFUSED_STREAM code 2910 and referencing the pushed stream's identifier. 2912 A client can use the SETTINGS_MAX_CONCURRENT_STREAMS setting to limit 2913 the number of responses that can be concurrently pushed by a server. 2914 Advertising a SETTINGS_MAX_CONCURRENT_STREAMS value of zero disables 2915 server push by preventing the server from creating the necessary 2916 streams. This does not prohibit a server from sending PUSH_PROMISE 2917 frames; clients need to reset any promised streams that are not 2918 wanted. 2920 Clients receiving a pushed response MUST validate that either the 2921 server is authoritative (see Section 10.1) or the proxy that provided 2922 the pushed response is configured for the corresponding request. For 2923 example, a server that offers a certificate for only the 2924 "example.com" DNS-ID or Common Name is not permitted to push a 2925 response for "https://www.example.org/doc". 2927 The response for a PUSH_PROMISE stream begins with a HEADERS frame, 2928 which immediately puts the stream into the "half-closed (remote)" 2929 state for the server and "half-closed (local)" state for the client, 2930 and ends with a frame bearing END_STREAM, which places the stream in 2931 the "closed" state. 2933 | Note: The client never sends a frame with the END_STREAM flag 2934 | for a server push. 2936 8.3. The CONNECT Method 2938 In HTTP/1.x, the pseudo-method CONNECT (Section 4.3.6 of [RFC7231]) 2939 is used to convert an HTTP connection into a tunnel to a remote host. 2940 CONNECT is primarily used with HTTP proxies to establish a TLS 2941 session with an origin server for the purposes of interacting with 2942 "https" resources. 2944 In HTTP/2, the CONNECT method is used to establish a tunnel over a 2945 single HTTP/2 stream to a remote host for similar purposes. The HTTP 2946 header field mapping works as defined in Section 8.1.2.3 ("Request 2947 Pseudo-Header Fields"), with a few differences. Specifically: 2949 * The ":method" pseudo-header field is set to "CONNECT". 2951 * The ":scheme" and ":path" pseudo-header fields MUST be omitted. 2953 * The ":authority" pseudo-header field contains the host and port to 2954 connect to (equivalent to the authority-form of the request-target 2955 of CONNECT requests (see Section 5.3 of [RFC7230])). 2957 A CONNECT request that does not conform to these restrictions is 2958 malformed (Section 8.1.2.6). 2960 A proxy that supports CONNECT establishes a TCP connection [TCP] to 2961 the server identified in the ":authority" pseudo-header field. Once 2962 this connection is successfully established, the proxy sends a 2963 HEADERS frame containing a 2xx series status code to the client, as 2964 defined in Section 4.3.6 of [RFC7231]. 2966 After the initial HEADERS frame sent by each peer, all subsequent 2967 DATA frames correspond to data sent on the TCP connection. The 2968 payload of any DATA frames sent by the client is transmitted by the 2969 proxy to the TCP server; data received from the TCP server is 2970 assembled into DATA frames by the proxy. Frame types other than DATA 2971 or stream management frames (RST_STREAM, WINDOW_UPDATE, and PRIORITY) 2972 MUST NOT be sent on a connected stream and MUST be treated as a 2973 stream error (Section 5.4.2) if received. 2975 The TCP connection can be closed by either peer. The END_STREAM flag 2976 on a DATA frame is treated as being equivalent to the TCP FIN bit. A 2977 client is expected to send a DATA frame with the END_STREAM flag set 2978 after receiving a frame bearing the END_STREAM flag. A proxy that 2979 receives a DATA frame with the END_STREAM flag set sends the attached 2980 data with the FIN bit set on the last TCP segment. A proxy that 2981 receives a TCP segment with the FIN bit set sends a DATA frame with 2982 the END_STREAM flag set. Note that the final TCP segment or DATA 2983 frame could be empty. 2985 A TCP connection error is signaled with RST_STREAM. A proxy treats 2986 any error in the TCP connection, which includes receiving a TCP 2987 segment with the RST bit set, as a stream error (Section 5.4.2) of 2988 type CONNECT_ERROR. Correspondingly, a proxy MUST send a TCP segment 2989 with the RST bit set if it detects an error with the stream or the 2990 HTTP/2 connection. 2992 9. Additional HTTP Requirements/Considerations 2994 This section outlines attributes of the HTTP protocol that improve 2995 interoperability, reduce exposure to known security vulnerabilities, 2996 or reduce the potential for implementation variation. 2998 9.1. Connection Management 3000 HTTP/2 connections are persistent. For best performance, it is 3001 expected that clients will not close connections until it is 3002 determined that no further communication with a server is necessary 3003 (for example, when a user navigates away from a particular web page) 3004 or until the server closes the connection. 3006 Clients SHOULD NOT open more than one HTTP/2 connection to a given 3007 host and port pair, where the host is derived from a URI, a selected 3008 alternative service [ALT-SVC], or a configured proxy. 3010 A client can create additional connections as replacements, either to 3011 replace connections that are near to exhausting the available stream 3012 identifier space (Section 5.1.1), to refresh the keying material for 3013 a TLS connection, or to replace connections that have encountered 3014 errors (Section 5.4.1). 3016 A client MAY open multiple connections to the same IP address and TCP 3017 port using different Server Name Indication [TLS-EXT] values or to 3018 provide different TLS client certificates but SHOULD avoid creating 3019 multiple connections with the same configuration. 3021 Servers are encouraged to maintain open connections for as long as 3022 possible but are permitted to terminate idle connections if 3023 necessary. When either endpoint chooses to close the transport-layer 3024 TCP connection, the terminating endpoint SHOULD first send a GOAWAY 3025 (Section 6.8) frame so that both endpoints can reliably determine 3026 whether previously sent frames have been processed and gracefully 3027 complete or terminate any necessary remaining tasks. 3029 9.1.1. Connection Reuse 3031 Connections that are made to an origin server, either directly or 3032 through a tunnel created using the CONNECT method (Section 8.3), MAY 3033 be reused for requests with multiple different URI authority 3034 components. A connection can be reused as long as the origin server 3035 is authoritative (Section 10.1). For TCP connections without TLS, 3036 this depends on the host having resolved to the same IP address. 3038 For "https" resources, connection reuse additionally depends on 3039 having a certificate that is valid for the host in the URI. The 3040 certificate presented by the server MUST satisfy any checks that the 3041 client would perform when forming a new TLS connection for the host 3042 in the URI. 3044 An origin server might offer a certificate with multiple 3045 "subjectAltName" attributes or names with wildcards, one of which is 3046 valid for the authority in the URI. For example, a certificate with 3047 a "subjectAltName" of "*.example.com" might permit the use of the 3048 same connection for requests to URIs starting with 3049 "https://a.example.com/" and "https://b.example.com/". 3051 In some deployments, reusing a connection for multiple origins can 3052 result in requests being directed to the wrong origin server. For 3053 example, TLS termination might be performed by a middlebox that uses 3054 the TLS Server Name Indication (SNI) [TLS-EXT] extension to select an 3055 origin server. This means that it is possible for clients to send 3056 confidential information to servers that might not be the intended 3057 target for the request, even though the server is otherwise 3058 authoritative. 3060 A server that does not wish clients to reuse connections can indicate 3061 that it is not authoritative for a request by sending a 421 3062 (Misdirected Request) status code in response to the request (see 3063 Section 9.1.2). 3065 A client that is configured to use a proxy over HTTP/2 directs 3066 requests to that proxy through a single connection. That is, all 3067 requests sent via a proxy reuse the connection to the proxy. 3069 9.1.2. The 421 (Misdirected Request) Status Code 3071 The 421 (Misdirected Request) status code indicates that the request 3072 was directed at a server that is not able to produce a response. 3073 This can be sent by a server that is not configured to produce 3074 responses for the combination of scheme and authority that are 3075 included in the request URI. 3077 Clients receiving a 421 (Misdirected Request) response from a server 3078 MAY retry the request -- whether the request method is idempotent or 3079 not -- over a different connection. This is possible if a connection 3080 is reused (Section 9.1.1) or if an alternative service is selected 3081 [ALT-SVC]. 3083 This status code MUST NOT be generated by proxies. 3085 A 421 response is cacheable by default, i.e., unless otherwise 3086 indicated by the method definition or explicit cache controls (see 3087 Section 4.2.2 of [RFC7234]). However, it is likely that caching is 3088 not desireable as a 421 response is connection-specific, which is not 3089 part of a cache key. 421 responses SHOULD therefore be marked as 3090 uncacheable. 3092 9.2. Use of TLS Features 3094 Implementations of HTTP/2 MUST use TLS version 1.2 [TLS12] or higher 3095 for HTTP/2 over TLS. The general TLS usage guidance in [TLSBCP] 3096 SHOULD be followed, with some additional restrictions that are 3097 specific to HTTP/2. 3099 The TLS implementation MUST support the Server Name Indication (SNI) 3100 [TLS-EXT] extension to TLS. HTTP/2 clients MUST indicate the target 3101 domain name when negotiating TLS. 3103 Deployments of HTTP/2 that negotiate TLS 1.3 or higher need only 3104 support and use the SNI extension; deployments of TLS 1.2 are subject 3105 to the requirements in the following sections. Implementations are 3106 encouraged to provide defaults that comply, but it is recognized that 3107 deployments are ultimately responsible for compliance. 3109 9.2.1. TLS 1.2 Features 3111 This section describes restrictions on the TLS 1.2 feature set that 3112 can be used with HTTP/2. Due to deployment limitations, it might not 3113 be possible to fail TLS negotiation when these restrictions are not 3114 met. An endpoint MAY immediately terminate an HTTP/2 connection that 3115 does not meet these TLS requirements with a connection error 3116 (Section 5.4.1) of type INADEQUATE_SECURITY. 3118 A deployment of HTTP/2 over TLS 1.2 MUST disable compression. TLS 3119 compression can lead to the exposure of information that would not 3120 otherwise be revealed [RFC3749]. Generic compression is unnecessary 3121 since HTTP/2 provides compression features that are more aware of 3122 context and therefore likely to be more appropriate for use for 3123 performance, security, or other reasons. 3125 A deployment of HTTP/2 over TLS 1.2 MUST disable renegotiation. An 3126 endpoint MUST treat a TLS renegotiation as a connection error 3127 (Section 5.4.1) of type PROTOCOL_ERROR. Note that disabling 3128 renegotiation can result in long-lived connections becoming unusable 3129 due to limits on the number of messages the underlying cipher suite 3130 can encipher. 3132 An endpoint MAY use renegotiation to provide confidentiality 3133 protection for client credentials offered in the handshake, but any 3134 renegotiation MUST occur prior to sending the connection preface. A 3135 server SHOULD request a client certificate if it sees a renegotiation 3136 request immediately after establishing a connection. 3138 This effectively prevents the use of renegotiation in response to a 3139 request for a specific protected resource. A future specification 3140 might provide a way to support this use case. Alternatively, a 3141 server might use an error (Section 5.4) of type HTTP_1_1_REQUIRED to 3142 request the client use a protocol that supports renegotiation. 3144 Implementations MUST support ephemeral key exchange sizes of at least 3145 2048 bits for cipher suites that use ephemeral finite field Diffie- 3146 Hellman (DHE) [TLS12] and 224 bits for cipher suites that use 3147 ephemeral elliptic curve Diffie-Hellman (ECDHE) [RFC4492]. Clients 3148 MUST accept DHE sizes of up to 4096 bits. Endpoints MAY treat 3149 negotiation of key sizes smaller than the lower limits as a 3150 connection error (Section 5.4.1) of type INADEQUATE_SECURITY. 3152 9.2.2. TLS 1.2 Cipher Suites 3154 A deployment of HTTP/2 over TLS 1.2 SHOULD NOT use any of the cipher 3155 suites that are listed in the list of prohibited cipher suites 3156 (Appendix A). 3158 Endpoints MAY choose to generate a connection error (Section 5.4.1) 3159 of type INADEQUATE_SECURITY if one of the prohibited cipher suites is 3160 negotiated. A deployment that chooses to use a prohibited cipher 3161 suite risks triggering a connection error unless the set of potential 3162 peers is known to accept that cipher suite. 3164 Implementations MUST NOT generate this error in reaction to the 3165 negotiation of a cipher suite that is not prohibited. Consequently, 3166 when clients offer a cipher suite that is not prohibited, they have 3167 to be prepared to use that cipher suite with HTTP/2. 3169 The list of prohibited cipher suites includes the cipher suite that 3170 TLS 1.2 makes mandatory, which means that TLS 1.2 deployments could 3171 have non-intersecting sets of permitted cipher suites. To avoid this 3172 problem causing TLS handshake failures, deployments of HTTP/2 that 3173 use TLS 1.2 MUST support TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 3174 [TLS-ECDHE] with the P-256 elliptic curve [FIPS186]. 3176 Note that clients might advertise support of cipher suites that are 3177 prohibited in order to allow for connection to servers that do not 3178 support HTTP/2. This allows servers to select HTTP/1.1 with a cipher 3179 suite that is prohibited in HTTP/2. However, this can result in 3180 HTTP/2 being negotiated with a prohibited cipher suite if the 3181 application protocol and cipher suite are independently selected. 3183 10. Security Considerations 3185 10.1. Server Authority 3187 HTTP/2 relies on the HTTP/1.1 definition of authority for determining 3188 whether a server is authoritative in providing a given response (see 3189 Section 9.1 of [RFC7230]). This relies on local name resolution for 3190 the "http" URI scheme and the authenticated server identity for the 3191 "https" scheme (see Section 3 of [RFC2818]). 3193 10.2. Cross-Protocol Attacks 3195 In a cross-protocol attack, an attacker causes a client to initiate a 3196 transaction in one protocol toward a server that understands a 3197 different protocol. An attacker might be able to cause the 3198 transaction to appear as a valid transaction in the second protocol. 3199 In combination with the capabilities of the web context, this can be 3200 used to interact with poorly protected servers in private networks. 3202 Completing a TLS handshake with an ALPN identifier for HTTP/2 can be 3203 considered sufficient protection against cross-protocol attacks. 3204 ALPN provides a positive indication that a server is willing to 3205 proceed with HTTP/2, which prevents attacks on other TLS-based 3206 protocols. 3208 The encryption in TLS makes it difficult for attackers to control the 3209 data that could be used in a cross-protocol attack on a cleartext 3210 protocol. 3212 The cleartext version of HTTP/2 has minimal protection against cross- 3213 protocol attacks. The connection preface (Section 3.5) contains a 3214 string that is designed to confuse HTTP/1.1 servers, but no special 3215 protection is offered for other protocols. A server that is willing 3216 to ignore parts of an HTTP/1.1 request containing an Upgrade header 3217 field in addition to the client connection preface could be exposed 3218 to a cross-protocol attack. 3220 10.3. Intermediary Encapsulation Attacks 3222 The HTTP/2 header field encoding allows the expression of names that 3223 are not valid field names in the Internet Message Syntax used by 3224 HTTP/1.1. Requests or responses containing invalid header field 3225 names MUST be treated as malformed (Section 8.1.2.6). An 3226 intermediary therefore cannot translate an HTTP/2 request or response 3227 containing an invalid field name into an HTTP/1.1 message. 3229 Similarly, HTTP/2 allows header field values that are not valid. 3230 While most of the values that can be encoded will not alter header 3231 field parsing, carriage return (CR, ASCII 0xd), line feed (LF, ASCII 3232 0xa), and the zero character (NUL, ASCII 0x0) might be exploited by 3233 an attacker if they are translated verbatim. Any request or response 3234 that contains a character not permitted in a header field value MUST 3235 be treated as malformed (Section 8.1.2.6). Valid characters are 3236 defined by the "field-content" ABNF rule in Section 3.2 of [RFC7230]. 3238 10.4. Cacheability of Pushed Responses 3240 Pushed responses do not have an explicit request from the client; the 3241 request is provided by the server in the PUSH_PROMISE frame. 3243 Caching responses that are pushed is possible based on the guidance 3244 provided by the origin server in the Cache-Control header field. 3245 However, this can cause issues if a single server hosts more than one 3246 tenant. For example, a server might offer multiple users each a 3247 small portion of its URI space. 3249 Where multiple tenants share space on the same server, that server 3250 MUST ensure that tenants are not able to push representations of 3251 resources that they do not have authority over. Failure to enforce 3252 this would allow a tenant to provide a representation that would be 3253 served out of cache, overriding the actual representation that the 3254 authoritative tenant provides. 3256 Pushed responses for which an origin server is not authoritative (see 3257 Section 10.1) MUST NOT be used or cached. 3259 10.5. Denial-of-Service Considerations 3261 An HTTP/2 connection can demand a greater commitment of resources to 3262 operate than an HTTP/1.1 connection. The use of header compression 3263 and flow control depend on a commitment of resources for storing a 3264 greater amount of state. Settings for these features ensure that 3265 memory commitments for these features are strictly bounded. 3267 The number of PUSH_PROMISE frames is not constrained in the same 3268 fashion. A client that accepts server push SHOULD limit the number 3269 of streams it allows to be in the "reserved (remote)" state. An 3270 excessive number of server push streams can be treated as a stream 3271 error (Section 5.4.2) of type ENHANCE_YOUR_CALM. 3273 Processing capacity cannot be guarded as effectively as state 3274 capacity. 3276 The SETTINGS frame can be abused to cause a peer to expend additional 3277 processing time. This might be done by pointlessly changing SETTINGS 3278 parameters, setting multiple undefined parameters, or changing the 3279 same setting multiple times in the same frame. WINDOW_UPDATE or 3280 PRIORITY frames can be abused to cause an unnecessary waste of 3281 resources. 3283 Large numbers of small or empty frames can be abused to cause a peer 3284 to expend time processing frame headers. Note, however, that some 3285 uses are entirely legitimate, such as the sending of an empty DATA or 3286 CONTINUATION frame at the end of a stream. 3288 Header compression also offers some opportunities to waste processing 3289 resources; see Section 7 of [COMPRESSION] for more details on 3290 potential abuses. 3292 Limits in SETTINGS parameters cannot be reduced instantaneously, 3293 which leaves an endpoint exposed to behavior from a peer that could 3294 exceed the new limits. In particular, immediately after establishing 3295 a connection, limits set by a server are not known to clients and 3296 could be exceeded without being an obvious protocol violation. 3298 All these features -- i.e., SETTINGS changes, small frames, header 3299 compression -- have legitimate uses. These features become a burden 3300 only when they are used unnecessarily or to excess. 3302 An endpoint that doesn't monitor this behavior exposes itself to a 3303 risk of denial-of-service attack. Implementations SHOULD track the 3304 use of these features and set limits on their use. An endpoint MAY 3305 treat activity that is suspicious as a connection error 3306 (Section 5.4.1) of type ENHANCE_YOUR_CALM. 3308 10.5.1. Limits on Header Block Size 3310 A large header block (Section 4.3) can cause an implementation to 3311 commit a large amount of state. Header fields that are critical for 3312 routing can appear toward the end of a header block, which prevents 3313 streaming of header fields to their ultimate destination. This 3314 ordering and other reasons, such as ensuring cache correctness, mean 3315 that an endpoint might need to buffer the entire header block. Since 3316 there is no hard limit to the size of a header block, some endpoints 3317 could be forced to commit a large amount of available memory for 3318 header fields. 3320 An endpoint can use the SETTINGS_MAX_HEADER_LIST_SIZE to advise peers 3321 of limits that might apply on the size of header blocks. This 3322 setting is only advisory, so endpoints MAY choose to send header 3323 blocks that exceed this limit and risk having the request or response 3324 being treated as malformed. This setting is specific to a 3325 connection, so any request or response could encounter a hop with a 3326 lower, unknown limit. An intermediary can attempt to avoid this 3327 problem by passing on values presented by different peers, but they 3328 are not obligated to do so. 3330 A server that receives a larger header block than it is willing to 3331 handle can send an HTTP 431 (Request Header Fields Too Large) status 3332 code [RFC6585]. A client can discard responses that it cannot 3333 process. The header block MUST be processed to ensure a consistent 3334 connection state, unless the connection is closed. 3336 10.5.2. CONNECT Issues 3338 The CONNECT method can be used to create disproportionate load on an 3339 proxy, since stream creation is relatively inexpensive when compared 3340 to the creation and maintenance of a TCP connection. A proxy might 3341 also maintain some resources for a TCP connection beyond the closing 3342 of the stream that carries the CONNECT request, since the outgoing 3343 TCP connection remains in the TIME_WAIT state. Therefore, a proxy 3344 cannot rely on SETTINGS_MAX_CONCURRENT_STREAMS alone to limit the 3345 resources consumed by CONNECT requests. 3347 10.6. Use of Compression 3349 Compression can allow an attacker to recover secret data when it is 3350 compressed in the same context as data under attacker control. 3351 HTTP/2 enables compression of header fields (Section 4.3); the 3352 following concerns also apply to the use of HTTP compressed content- 3353 codings (Section 3.1.2.1 of [RFC7231]). 3355 There are demonstrable attacks on compression that exploit the 3356 characteristics of the web (e.g., [BREACH]). The attacker induces 3357 multiple requests containing varying plaintext, observing the length 3358 of the resulting ciphertext in each, which reveals a shorter length 3359 when a guess about the secret is correct. 3361 Implementations communicating on a secure channel MUST NOT compress 3362 content that includes both confidential and attacker-controlled data 3363 unless separate compression dictionaries are used for each source of 3364 data. Compression MUST NOT be used if the source of data cannot be 3365 reliably determined. Generic stream compression, such as that 3366 provided by TLS, MUST NOT be used with HTTP/2 (see Section 9.2). 3368 Further considerations regarding the compression of header fields are 3369 described in [COMPRESSION]. 3371 10.7. Use of Padding 3373 Padding within HTTP/2 is not intended as a replacement for general 3374 purpose padding, such as might be provided by TLS [TLS12]. Redundant 3375 padding could even be counterproductive. Correct application can 3376 depend on having specific knowledge of the data that is being padded. 3378 To mitigate attacks that rely on compression, disabling or limiting 3379 compression might be preferable to padding as a countermeasure. 3381 Padding can be used to obscure the exact size of frame content and is 3382 provided to mitigate specific attacks within HTTP, for example, 3383 attacks where compressed content includes both attacker-controlled 3384 plaintext and secret data (e.g., [BREACH]). 3386 Use of padding can result in less protection than might seem 3387 immediately obvious. At best, padding only makes it more difficult 3388 for an attacker to infer length information by increasing the number 3389 of frames an attacker has to observe. Incorrectly implemented 3390 padding schemes can be easily defeated. In particular, randomized 3391 padding with a predictable distribution provides very little 3392 protection; similarly, padding payloads to a fixed size exposes 3393 information as payload sizes cross the fixed-sized boundary, which 3394 could be possible if an attacker can control plaintext. 3396 Intermediaries SHOULD retain padding for DATA frames but MAY drop 3397 padding for HEADERS and PUSH_PROMISE frames. A valid reason for an 3398 intermediary to change the amount of padding of frames is to improve 3399 the protections that padding provides. 3401 10.8. Privacy Considerations 3403 Several characteristics of HTTP/2 provide an observer an opportunity 3404 to correlate actions of a single client or server over time. These 3405 include the value of settings, the manner in which flow-control 3406 windows are managed, the way priorities are allocated to streams, the 3407 timing of reactions to stimulus, and the handling of any features 3408 that are controlled by settings. 3410 As far as these create observable differences in behavior, they could 3411 be used as a basis for fingerprinting a specific client, as defined 3412 in Section 1.8 of [HTML5]. 3414 HTTP/2's preference for using a single TCP connection allows 3415 correlation of a user's activity on a site. Reusing connections for 3416 different origins allows tracking across those origins. 3418 Because the PING and SETTINGS frames solicit immediate responses, 3419 they can be used by an endpoint to measure latency to their peer. 3420 This might have privacy implications in certain scenarios. 3422 11. IANA Considerations 3424 A string for identifying HTTP/2 is entered into the "Application- 3425 Layer Protocol Negotiation (ALPN) Protocol IDs" registry established 3426 in [TLS-ALPN]. 3428 This document establishes a registry for frame types, settings, and 3429 error codes. These new registries appear in the new "Hypertext 3430 Transfer Protocol version 2 (HTTP/2) Parameters" section. 3432 This document registers the "HTTP2-Settings" header field for use in 3433 HTTP; it also registers the 421 (Misdirected Request) status code. 3435 This document registers the "PRI" method for use in HTTP to avoid 3436 collisions with the connection preface (Section 3.5). 3438 11.1. Registration of HTTP/2 Identification Strings 3440 This document creates two registrations for the identification of 3441 HTTP/2 (see Section 3.3) in the "Application-Layer Protocol 3442 Negotiation (ALPN) Protocol IDs" registry established in [TLS-ALPN]. 3444 The "h2" string identifies HTTP/2 when used over TLS: 3446 Protocol: HTTP/2 over TLS 3448 Identification Sequence: 0x68 0x32 ("h2") 3450 Specification: This document 3452 The "h2c" string identifies HTTP/2 when used over cleartext TCP: 3454 Protocol: HTTP/2 over TCP 3456 Identification Sequence: 0x68 0x32 0x63 ("h2c") 3458 Specification: This document 3460 11.2. Frame Type Registry 3462 This document establishes a registry for HTTP/2 frame type codes. 3463 The "HTTP/2 Frame Type" registry manages an 8-bit space. The "HTTP/2 3464 Frame Type" registry operates under either of the "IETF Review" or 3465 "IESG Approval" policies [RFC5226] for values between 0x00 and 0xef, 3466 with values between 0xf0 and 0xff being reserved for Experimental 3467 Use. 3469 New entries in this registry require the following information: 3471 Frame Type: A name or label for the frame type. 3473 Code: The 8-bit code assigned to the frame type. 3475 Specification: A reference to a specification that includes a 3476 description of the frame layout, its semantics, and flags that the 3477 frame type uses, including any parts of the frame that are 3478 conditionally present based on the value of flags. 3480 The entries in the following table are registered by this document. 3482 +===============+======+==============+ 3483 | Frame Type | Code | Section | 3484 +===============+======+==============+ 3485 | DATA | 0x0 | Section 6.1 | 3486 +---------------+------+--------------+ 3487 | HEADERS | 0x1 | Section 6.2 | 3488 +---------------+------+--------------+ 3489 | PRIORITY | 0x2 | Section 6.3 | 3490 +---------------+------+--------------+ 3491 | RST_STREAM | 0x3 | Section 6.4 | 3492 +---------------+------+--------------+ 3493 | SETTINGS | 0x4 | Section 6.5 | 3494 +---------------+------+--------------+ 3495 | PUSH_PROMISE | 0x5 | Section 6.6 | 3496 +---------------+------+--------------+ 3497 | PING | 0x6 | Section 6.7 | 3498 +---------------+------+--------------+ 3499 | GOAWAY | 0x7 | Section 6.8 | 3500 +---------------+------+--------------+ 3501 | WINDOW_UPDATE | 0x8 | Section 6.9 | 3502 +---------------+------+--------------+ 3503 | CONTINUATION | 0x9 | Section 6.10 | 3504 +---------------+------+--------------+ 3506 Table 1 3508 11.3. Settings Registry 3510 This document establishes a registry for HTTP/2 settings. The 3511 "HTTP/2 Settings" registry manages a 16-bit space. The "HTTP/2 3512 Settings" registry operates under the "Expert Review" policy 3513 [RFC5226] for values in the range from 0x0000 to 0xefff, with values 3514 between and 0xf000 and 0xffff being reserved for Experimental Use. 3516 New registrations are advised to provide the following information: 3518 Name: A symbolic name for the setting. Specifying a setting name is 3519 optional. 3521 Code: The 16-bit code assigned to the setting. 3523 Initial Value: An initial value for the setting. 3525 Specification: An optional reference to a specification that 3526 describes the use of the setting. 3528 The entries in the following table are registered by this document. 3530 +========================+======+===============+===============+ 3531 | Name | Code | Initial Value | Specification | 3532 +========================+======+===============+===============+ 3533 | HEADER_TABLE_SIZE | 0x1 | 4096 | Section 6.5.2 | 3534 +------------------------+------+---------------+---------------+ 3535 | ENABLE_PUSH | 0x2 | 1 | Section 6.5.2 | 3536 +------------------------+------+---------------+---------------+ 3537 | MAX_CONCURRENT_STREAMS | 0x3 | (infinite) | Section 6.5.2 | 3538 +------------------------+------+---------------+---------------+ 3539 | INITIAL_WINDOW_SIZE | 0x4 | 65535 | Section 6.5.2 | 3540 +------------------------+------+---------------+---------------+ 3541 | MAX_FRAME_SIZE | 0x5 | 16384 | Section 6.5.2 | 3542 +------------------------+------+---------------+---------------+ 3543 | MAX_HEADER_LIST_SIZE | 0x6 | (infinite) | Section 6.5.2 | 3544 +------------------------+------+---------------+---------------+ 3546 Table 2 3548 11.4. Error Code Registry 3550 This document establishes a registry for HTTP/2 error codes. The 3551 "HTTP/2 Error Code" registry manages a 32-bit space. The "HTTP/2 3552 Error Code" registry operates under the "Expert Review" policy 3553 [RFC5226]. 3555 Registrations for error codes are required to include a description 3556 of the error code. An expert reviewer is advised to examine new 3557 registrations for possible duplication with existing error codes. 3558 Use of existing registrations is to be encouraged, but not mandated. 3560 New registrations are advised to provide the following information: 3562 Name: A name for the error code. Specifying an error code name is 3563 optional. 3565 Code: The 32-bit error code value. 3567 Description: A brief description of the error code semantics, longer 3568 if no detailed specification is provided. 3570 Specification: An optional reference for a specification that 3571 defines the error code. 3573 The entries in the following table are registered by this document. 3575 +=====================+======+======================+===============+ 3576 | Name | Code | Description | Specification | 3577 +=====================+======+======================+===============+ 3578 | NO_ERROR | 0x0 | Graceful shutdown | Section 7 | 3579 +---------------------+------+----------------------+---------------+ 3580 | PROTOCOL_ERROR | 0x1 | Protocol error | Section 7 | 3581 | | | detected | | 3582 +---------------------+------+----------------------+---------------+ 3583 | INTERNAL_ERROR | 0x2 | Implementation | Section 7 | 3584 | | | fault | | 3585 +---------------------+------+----------------------+---------------+ 3586 | FLOW_CONTROL_ERROR | 0x3 | Flow-control | Section 7 | 3587 | | | limits exceeded | | 3588 +---------------------+------+----------------------+---------------+ 3589 | SETTINGS_TIMEOUT | 0x4 | Settings not | Section 7 | 3590 | | | acknowledged | | 3591 +---------------------+------+----------------------+---------------+ 3592 | STREAM_CLOSED | 0x5 | Frame received | Section 7 | 3593 | | | for closed stream | | 3594 +---------------------+------+----------------------+---------------+ 3595 | FRAME_SIZE_ERROR | 0x6 | Frame size | Section 7 | 3596 | | | incorrect | | 3597 +---------------------+------+----------------------+---------------+ 3598 | REFUSED_STREAM | 0x7 | Stream not | Section 7 | 3599 | | | processed | | 3600 +---------------------+------+----------------------+---------------+ 3601 | CANCEL | 0x8 | Stream cancelled | Section 7 | 3602 +---------------------+------+----------------------+---------------+ 3603 | COMPRESSION_ERROR | 0x9 | Compression state | Section 7 | 3604 | | | not updated | | 3605 +---------------------+------+----------------------+---------------+ 3606 | CONNECT_ERROR | 0xa | TCP connection | Section 7 | 3607 | | | error for CONNECT | | 3608 | | | method | | 3609 +---------------------+------+----------------------+---------------+ 3610 | ENHANCE_YOUR_CALM | 0xb | Processing | Section 7 | 3611 | | | capacity exceeded | | 3612 +---------------------+------+----------------------+---------------+ 3613 | INADEQUATE_SECURITY | 0xc | Negotiated TLS | Section 7 | 3614 | | | parameters not | | 3615 | | | acceptable | | 3616 +---------------------+------+----------------------+---------------+ 3617 | HTTP_1_1_REQUIRED | 0xd | Use HTTP/1.1 for | Section 7 | 3618 | | | the request | | 3619 +---------------------+------+----------------------+---------------+ 3621 Table 3 3623 11.5. HTTP2-Settings Header Field Registration 3625 This section registers the "HTTP2-Settings" header field in the 3626 "Permanent Message Header Field Names" registry [BCP90]. 3628 Header field name: HTTP2-Settings 3630 Applicable protocol: http 3632 Status: standard 3634 Author/Change controller: IETF 3636 Specification document(s): Section 3.2.1 of this document 3638 Related information: This header field is only used by an HTTP/2 3639 client for Upgrade-based negotiation. 3641 11.6. PRI Method Registration 3643 This section registers the "PRI" method in the "HTTP Method Registry" 3644 (Section 8.1 of [RFC7231]). 3646 Method Name: PRI 3648 Safe: Yes 3650 Idempotent: Yes 3652 Specification document(s): Section 3.5 of this document 3654 Related information: This method is never used by an actual client. 3655 This method will appear to be used when an HTTP/1.1 server or 3656 intermediary attempts to parse an HTTP/2 connection preface. 3658 11.7. The 421 (Misdirected Request) HTTP Status Code 3660 This document registers the 421 (Misdirected Request) HTTP status 3661 code in the "HTTP Status Codes" registry (Section 8.2 of [RFC7231]). 3663 Status Code: 421 3665 Short Description: Misdirected Request 3667 Specification: Section 9.1.2 of this document 3669 11.8. The h2c Upgrade Token 3671 This document registers the "h2c" upgrade token in the "HTTP Upgrade 3672 Tokens" registry (Section 8.6 of [RFC7230]). 3674 Value: h2c 3676 Description: Hypertext Transfer Protocol version 2 (HTTP/2) 3678 Expected Version Tokens: None 3680 Reference: Section 3.2 of this document 3682 12. References 3684 12.1. Normative References 3686 [COMPRESSION] 3687 Peon, R. and H. Ruellan, "HPACK: Header Compression for 3688 HTTP/2", RFC 7541, May 2015, 3689 . 3691 [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, 3692 April 2011, . 3694 [FIPS186] NIST, "Digital Signature Standard (DSS)", FIPS PUB 186-4, 3695 July 2013, . 3697 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3698 Requirement Levels", BCP 14, RFC 2119, March 1997, 3699 . 3701 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000, 3702 . 3704 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3705 Resource Identifier (URI): Generic Syntax", STD 66, 3706 RFC 3986, January 2005, 3707 . 3709 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 3710 Encodings", RFC 4648, October 2006, 3711 . 3713 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 3714 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 3715 May 2008, . 3717 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 3718 Specifications: ABNF", STD 68, RFC 5234, January 2008, 3719 . 3721 [RFC7230] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 3722 Transfer Protocol (HTTP/1.1): Message Syntax and Routing", 3723 RFC 7230, June 2014, 3724 . 3726 [RFC7231] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 3727 Transfer Protocol (HTTP/1.1): Semantics and Content", 3728 RFC 7231, June 2014, 3729 . 3731 [RFC7232] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 3732 Transfer Protocol (HTTP/1.1): Conditional Requests", 3733 RFC 7232, June 2014, 3734 . 3736 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. F. Reschke, Ed., 3737 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 3738 RFC 7233, June 2014, 3739 . 3741 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, 3742 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 3743 RFC 7234, June 2014, 3744 . 3746 [RFC7235] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 3747 Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, 3748 June 2014, . 3750 [TCP] Postel, J., "Transmission Control Protocol", STD 7, 3751 RFC 793, September 1981, 3752 . 3754 [TLS-ALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan, 3755 "Transport Layer Security (TLS) Application-Layer Protocol 3756 Negotiation Extension", RFC 7301, July 2014, 3757 . 3759 [TLS-ECDHE] 3760 Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- 3761 256/384 and AES Galois Counter Mode (GCM)", RFC 5289, 3762 August 2008, . 3764 [TLS-EXT] Eastlake 3rd, D., "Transport Layer Security (TLS) 3765 Extensions: Extension Definitions", RFC 6066, January 3766 2011, . 3768 [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer Security 3769 (TLS) Protocol Version 1.2", RFC 5246, August 2008, 3770 . 3772 12.2. Informative References 3774 [ALT-SVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP 3775 Alternative Services", Work in Progress, Internet-Draft, 3776 draft-ietf-httpbis-alt-svc-06, February 2015, 3777 . 3780 [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration 3781 Procedures for Message Header Fields", BCP 90, RFC 3864, 3782 September 2004, . 3784 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 3785 CRIME Attack", 12 July 2013, 3786 . 3789 [HTML5] Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Doyle 3790 Navara, E., O'Connor, E., and S. Pfeiffer, "HTML5", W3C 3791 Recommendation REC-html5-20141028, 28 October 2014, 3792 . 3794 [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol 3795 Compression Methods", RFC 3749, May 2004, 3796 . 3798 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 3799 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 3800 for Transport Layer Security (TLS)", RFC 4492, May 2006, 3801 . 3803 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 3804 Codes", RFC 6585, April 2012, 3805 . 3807 [RFC7323] Borman, D., Braden, B., Jacobson, V., and R. 3808 Scheffenegger, Ed., "TCP Extensions for High Performance", 3809 RFC 7323, September 2014, 3810 . 3812 [TALKING] Huang, L., Chen, E., Barth, A., Rescorla, E., and C. 3813 Jackson, "Talking to Yourself for Fun and Profit", 2011, 3814 . 3816 [TLSBCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 3817 "Recommendations for Secure Use of Transport Layer 3818 Security (TLS) and Datagram Transport Layer Security 3819 (DTLS)", BCP 195, RFC 7525, May 2015, 3820 . 3822 Appendix A. Prohibited TLS 1.2 Cipher Suites 3824 An HTTP/2 implementation MAY treat the negotiation of any of the 3825 following cipher suites with TLS 1.2 as a connection error 3826 (Section 5.4.1) of type INADEQUATE_SECURITY: 3828 * TLS_NULL_WITH_NULL_NULL 3829 * TLS_RSA_WITH_NULL_MD5 3830 * TLS_RSA_WITH_NULL_SHA 3831 * TLS_RSA_EXPORT_WITH_RC4_40_MD5 3832 * TLS_RSA_WITH_RC4_128_MD5 3833 * TLS_RSA_WITH_RC4_128_SHA 3834 * TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 3835 * TLS_RSA_WITH_IDEA_CBC_SHA 3836 * TLS_RSA_EXPORT_WITH_DES40_CBC_SHA 3837 * TLS_RSA_WITH_DES_CBC_SHA 3838 * TLS_RSA_WITH_3DES_EDE_CBC_SHA 3839 * TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA 3840 * TLS_DH_DSS_WITH_DES_CBC_SHA 3841 * TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA 3842 * TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA 3843 * TLS_DH_RSA_WITH_DES_CBC_SHA 3844 * TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA 3845 * TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA 3846 * TLS_DHE_DSS_WITH_DES_CBC_SHA 3847 * TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA 3848 * TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA 3849 * TLS_DHE_RSA_WITH_DES_CBC_SHA 3850 * TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA 3851 * TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 3852 * TLS_DH_anon_WITH_RC4_128_MD5 3853 * TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA 3854 * TLS_DH_anon_WITH_DES_CBC_SHA 3855 * TLS_DH_anon_WITH_3DES_EDE_CBC_SHA 3856 * TLS_KRB5_WITH_DES_CBC_SHA 3857 * TLS_KRB5_WITH_3DES_EDE_CBC_SHA 3858 * TLS_KRB5_WITH_RC4_128_SHA 3859 * TLS_KRB5_WITH_IDEA_CBC_SHA 3860 * TLS_KRB5_WITH_DES_CBC_MD5 3861 * TLS_KRB5_WITH_3DES_EDE_CBC_MD5 3862 * TLS_KRB5_WITH_RC4_128_MD5 3863 * TLS_KRB5_WITH_IDEA_CBC_MD5 3864 * TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA 3865 * TLS_KRB5_EXPORT_WITH_RC2_CBC_40_SHA 3866 * TLS_KRB5_EXPORT_WITH_RC4_40_SHA 3867 * TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5 3868 * TLS_KRB5_EXPORT_WITH_RC2_CBC_40_MD5 3869 * TLS_KRB5_EXPORT_WITH_RC4_40_MD5 3870 * TLS_PSK_WITH_NULL_SHA 3871 * TLS_DHE_PSK_WITH_NULL_SHA 3872 * TLS_RSA_PSK_WITH_NULL_SHA 3873 * TLS_RSA_WITH_AES_128_CBC_SHA 3874 * TLS_DH_DSS_WITH_AES_128_CBC_SHA 3875 * TLS_DH_RSA_WITH_AES_128_CBC_SHA 3876 * TLS_DHE_DSS_WITH_AES_128_CBC_SHA 3877 * TLS_DHE_RSA_WITH_AES_128_CBC_SHA 3878 * TLS_DH_anon_WITH_AES_128_CBC_SHA 3879 * TLS_RSA_WITH_AES_256_CBC_SHA 3880 * TLS_DH_DSS_WITH_AES_256_CBC_SHA 3881 * TLS_DH_RSA_WITH_AES_256_CBC_SHA 3882 * TLS_DHE_DSS_WITH_AES_256_CBC_SHA 3883 * TLS_DHE_RSA_WITH_AES_256_CBC_SHA 3884 * TLS_DH_anon_WITH_AES_256_CBC_SHA 3885 * TLS_RSA_WITH_NULL_SHA256 3886 * TLS_RSA_WITH_AES_128_CBC_SHA256 3887 * TLS_RSA_WITH_AES_256_CBC_SHA256 3888 * TLS_DH_DSS_WITH_AES_128_CBC_SHA256 3889 * TLS_DH_RSA_WITH_AES_128_CBC_SHA256 3890 * TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 3891 * TLS_RSA_WITH_CAMELLIA_128_CBC_SHA 3892 * TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA 3893 * TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA 3894 * TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA 3895 * TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA 3896 * TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA 3897 * TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 3898 * TLS_DH_DSS_WITH_AES_256_CBC_SHA256 3899 * TLS_DH_RSA_WITH_AES_256_CBC_SHA256 3900 * TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 3901 * TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 3902 * TLS_DH_anon_WITH_AES_128_CBC_SHA256 3903 * TLS_DH_anon_WITH_AES_256_CBC_SHA256 3904 * TLS_RSA_WITH_CAMELLIA_256_CBC_SHA 3905 * TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA 3906 * TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA 3907 * TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA 3908 * TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA 3909 * TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA 3910 * TLS_PSK_WITH_RC4_128_SHA 3911 * TLS_PSK_WITH_3DES_EDE_CBC_SHA 3912 * TLS_PSK_WITH_AES_128_CBC_SHA 3913 * TLS_PSK_WITH_AES_256_CBC_SHA 3914 * TLS_DHE_PSK_WITH_RC4_128_SHA 3915 * TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA 3916 * TLS_DHE_PSK_WITH_AES_128_CBC_SHA 3917 * TLS_DHE_PSK_WITH_AES_256_CBC_SHA 3918 * TLS_RSA_PSK_WITH_RC4_128_SHA 3919 * TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA 3920 * TLS_RSA_PSK_WITH_AES_128_CBC_SHA 3921 * TLS_RSA_PSK_WITH_AES_256_CBC_SHA 3922 * TLS_RSA_WITH_SEED_CBC_SHA 3923 * TLS_DH_DSS_WITH_SEED_CBC_SHA 3924 * TLS_DH_RSA_WITH_SEED_CBC_SHA 3925 * TLS_DHE_DSS_WITH_SEED_CBC_SHA 3926 * TLS_DHE_RSA_WITH_SEED_CBC_SHA 3927 * TLS_DH_anon_WITH_SEED_CBC_SHA 3928 * TLS_RSA_WITH_AES_128_GCM_SHA256 3929 * TLS_RSA_WITH_AES_256_GCM_SHA384 3930 * TLS_DH_RSA_WITH_AES_128_GCM_SHA256 3931 * TLS_DH_RSA_WITH_AES_256_GCM_SHA384 3932 * TLS_DH_DSS_WITH_AES_128_GCM_SHA256 3933 * TLS_DH_DSS_WITH_AES_256_GCM_SHA384 3934 * TLS_DH_anon_WITH_AES_128_GCM_SHA256 3935 * TLS_DH_anon_WITH_AES_256_GCM_SHA384 3936 * TLS_PSK_WITH_AES_128_GCM_SHA256 3937 * TLS_PSK_WITH_AES_256_GCM_SHA384 3938 * TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 3939 * TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 3940 * TLS_PSK_WITH_AES_128_CBC_SHA256 3941 * TLS_PSK_WITH_AES_256_CBC_SHA384 3942 * TLS_PSK_WITH_NULL_SHA256 3943 * TLS_PSK_WITH_NULL_SHA384 3944 * TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 3945 * TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 3946 * TLS_DHE_PSK_WITH_NULL_SHA256 3947 * TLS_DHE_PSK_WITH_NULL_SHA384 3948 * TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 3949 * TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 3950 * TLS_RSA_PSK_WITH_NULL_SHA256 3951 * TLS_RSA_PSK_WITH_NULL_SHA384 3952 * TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 3953 * TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA256 3954 * TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA256 3955 * TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA256 3956 * TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 3957 * TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA256 3958 * TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 3959 * TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA256 3960 * TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA256 3961 * TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA256 3962 * TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 3963 * TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA256 3964 * TLS_EMPTY_RENEGOTIATION_INFO_SCSV 3965 * TLS_ECDH_ECDSA_WITH_NULL_SHA 3966 * TLS_ECDH_ECDSA_WITH_RC4_128_SHA 3967 * TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA 3968 * TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA 3969 * TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA 3970 * TLS_ECDHE_ECDSA_WITH_NULL_SHA 3971 * TLS_ECDHE_ECDSA_WITH_RC4_128_SHA 3972 * TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA 3973 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 3974 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 3975 * TLS_ECDH_RSA_WITH_NULL_SHA 3976 * TLS_ECDH_RSA_WITH_RC4_128_SHA 3977 * TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA 3978 * TLS_ECDH_RSA_WITH_AES_128_CBC_SHA 3979 * TLS_ECDH_RSA_WITH_AES_256_CBC_SHA 3980 * TLS_ECDHE_RSA_WITH_NULL_SHA 3981 * TLS_ECDHE_RSA_WITH_RC4_128_SHA 3982 * TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA 3983 * TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 3984 * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 3985 * TLS_ECDH_anon_WITH_NULL_SHA 3986 * TLS_ECDH_anon_WITH_RC4_128_SHA 3987 * TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA 3988 * TLS_ECDH_anon_WITH_AES_128_CBC_SHA 3989 * TLS_ECDH_anon_WITH_AES_256_CBC_SHA 3990 * TLS_SRP_SHA_WITH_3DES_EDE_CBC_SHA 3991 * TLS_SRP_SHA_RSA_WITH_3DES_EDE_CBC_SHA 3992 * TLS_SRP_SHA_DSS_WITH_3DES_EDE_CBC_SHA 3993 * TLS_SRP_SHA_WITH_AES_128_CBC_SHA 3994 * TLS_SRP_SHA_RSA_WITH_AES_128_CBC_SHA 3995 * TLS_SRP_SHA_DSS_WITH_AES_128_CBC_SHA 3996 * TLS_SRP_SHA_WITH_AES_256_CBC_SHA 3997 * TLS_SRP_SHA_RSA_WITH_AES_256_CBC_SHA 3998 * TLS_SRP_SHA_DSS_WITH_AES_256_CBC_SHA 3999 * TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 4000 * TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 4001 * TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 4002 * TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 4003 * TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 4004 * TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 4005 * TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 4006 * TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 4007 * TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 4008 * TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 4009 * TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 4010 * TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 4011 * TLS_ECDHE_PSK_WITH_RC4_128_SHA 4012 * TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA 4013 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA 4014 * TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA 4015 * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 4016 * TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 4017 * TLS_ECDHE_PSK_WITH_NULL_SHA 4018 * TLS_ECDHE_PSK_WITH_NULL_SHA256 4019 * TLS_ECDHE_PSK_WITH_NULL_SHA384 4020 * TLS_RSA_WITH_ARIA_128_CBC_SHA256 4021 * TLS_RSA_WITH_ARIA_256_CBC_SHA384 4022 * TLS_DH_DSS_WITH_ARIA_128_CBC_SHA256 4023 * TLS_DH_DSS_WITH_ARIA_256_CBC_SHA384 4024 * TLS_DH_RSA_WITH_ARIA_128_CBC_SHA256 4025 * TLS_DH_RSA_WITH_ARIA_256_CBC_SHA384 4026 * TLS_DHE_DSS_WITH_ARIA_128_CBC_SHA256 4027 * TLS_DHE_DSS_WITH_ARIA_256_CBC_SHA384 4028 * TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256 4029 * TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384 4030 * TLS_DH_anon_WITH_ARIA_128_CBC_SHA256 4031 * TLS_DH_anon_WITH_ARIA_256_CBC_SHA384 4032 * TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256 4033 * TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384 4034 * TLS_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256 4035 * TLS_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384 4036 * TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256 4037 * TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384 4038 * TLS_ECDH_RSA_WITH_ARIA_128_CBC_SHA256 4039 * TLS_ECDH_RSA_WITH_ARIA_256_CBC_SHA384 4040 * TLS_RSA_WITH_ARIA_128_GCM_SHA256 4041 * TLS_RSA_WITH_ARIA_256_GCM_SHA384 4042 * TLS_DH_RSA_WITH_ARIA_128_GCM_SHA256 4043 * TLS_DH_RSA_WITH_ARIA_256_GCM_SHA384 4044 * TLS_DH_DSS_WITH_ARIA_128_GCM_SHA256 4045 * TLS_DH_DSS_WITH_ARIA_256_GCM_SHA384 4046 * TLS_DH_anon_WITH_ARIA_128_GCM_SHA256 4047 * TLS_DH_anon_WITH_ARIA_256_GCM_SHA384 4048 * TLS_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256 4049 * TLS_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384 4050 * TLS_ECDH_RSA_WITH_ARIA_128_GCM_SHA256 4051 * TLS_ECDH_RSA_WITH_ARIA_256_GCM_SHA384 4052 * TLS_PSK_WITH_ARIA_128_CBC_SHA256 4053 * TLS_PSK_WITH_ARIA_256_CBC_SHA384 4054 * TLS_DHE_PSK_WITH_ARIA_128_CBC_SHA256 4055 * TLS_DHE_PSK_WITH_ARIA_256_CBC_SHA384 4056 * TLS_RSA_PSK_WITH_ARIA_128_CBC_SHA256 4057 * TLS_RSA_PSK_WITH_ARIA_256_CBC_SHA384 4058 * TLS_PSK_WITH_ARIA_128_GCM_SHA256 4059 * TLS_PSK_WITH_ARIA_256_GCM_SHA384 4060 * TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256 4061 * TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384 4062 * TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256 4063 * TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384 4064 * TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 4065 * TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 4066 * TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 4067 * TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 4068 * TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 4069 * TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 4070 * TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256 4071 * TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384 4072 * TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256 4073 * TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384 4074 * TLS_DH_RSA_WITH_CAMELLIA_128_GCM_SHA256 4075 * TLS_DH_RSA_WITH_CAMELLIA_256_GCM_SHA384 4076 * TLS_DH_DSS_WITH_CAMELLIA_128_GCM_SHA256 4077 * TLS_DH_DSS_WITH_CAMELLIA_256_GCM_SHA384 4078 * TLS_DH_anon_WITH_CAMELLIA_128_GCM_SHA256 4079 * TLS_DH_anon_WITH_CAMELLIA_256_GCM_SHA384 4080 * TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 4081 * TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 4082 * TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256 4083 * TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384 4084 * TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 4085 * TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 4086 * TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256 4087 * TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384 4088 * TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256 4089 * TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 4090 * TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 4091 * TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 4092 * TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 4093 * TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 4094 * TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 4095 * TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 4096 * TLS_RSA_WITH_AES_128_CCM 4097 * TLS_RSA_WITH_AES_256_CCM 4098 * TLS_RSA_WITH_AES_128_CCM_8 4099 * TLS_RSA_WITH_AES_256_CCM_8 4100 * TLS_PSK_WITH_AES_128_CCM 4101 * TLS_PSK_WITH_AES_256_CCM 4102 * TLS_PSK_WITH_AES_128_CCM_8 4103 * TLS_PSK_WITH_AES_256_CCM_8 4105 | Note: This list was assembled from the set of registered TLS 4106 | cipher suites at the time of writing. This list includes those 4107 | cipher suites that do not offer an ephemeral key exchange and 4108 | those that are based on the TLS null, stream, or block cipher 4109 | type (as defined in Section 6.2.3 of [TLS12]). Additional 4110 | cipher suites with these properties could be defined; these 4111 | would not be explicitly prohibited. 4113 Appendix B. Changes from RFC 7540 4115 This revision makes only editorial updates. 4117 Contributors 4119 The previous version of this document was authored by Mike Belshe and 4120 Roberto Peon. 4122 Acknowledgements 4124 This document includes substantial input from the following 4125 individuals: 4127 * Adam Langley, Wan-Teh Chang, Jim Morrison, Mark Nottingham, Alyssa 4128 Wilk, Costin Manolache, William Chan, Vitaliy Lvin, Joe Chan, Adam 4129 Barth, Ryan Hamilton, Gavin Peters, Kent Alstad, Kevin Lindsay, 4130 Paul Amer, Fan Yang, and Jonathan Leighton (SPDY contributors). 4132 * Gabriel Montenegro and Willy Tarreau (Upgrade mechanism). 4134 * William Chan, Salvatore Loreto, Osama Mazahir, Gabriel Montenegro, 4135 Jitu Padhye, Roberto Peon, and Rob Trace (Flow control). 4137 * Mike Bishop (Extensibility). 4139 * Mark Nottingham, Julian Reschke, James Snell, Jeff Pinner, Mike 4140 Bishop, and Herve Ruellan (Substantial editorial contributions). 4142 * Kari Hurtta, Tatsuhiro Tsujikawa, Greg Wilkins, Poul-Henning Kamp, 4143 and Jonathan Thackray. 4145 * Alexey Melnikov, who was an editor of this document in 2013. 4147 A substantial proportion of Martin's contribution was supported by 4148 Microsoft during his employment there. 4150 The Japanese HTTP/2 community provided invaluable contributions, 4151 including a number of implementations as well as numerous technical 4152 and editorial contributions. 4154 Author's Address 4156 Martin Thomson (editor) 4157 Mozilla 4158 Australia 4160 Email: mt@lowentropy.net