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