idnits 2.17.1 draft-ietf-quic-qpack-16.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: To bound the memory requirements of the decoder, the decoder limits the maximum value the encoder is permitted to set for the dynamic table capacity. In HTTP/3, this limit is determined by the value of SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder; see Section 5. The encoder MUST not set a dynamic table capacity that exceeds this maximum, but it can choose to use a lower dynamic table capacity; see Section 4.3.1. -- The document date (9 June 2020) is 1414 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-29 == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-29 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-08 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 QUIC C. Krasic 3 Internet-Draft Netflix 4 Intended status: Standards Track M. Bishop 5 Expires: 11 December 2020 Akamai Technologies 6 A. Frindell, Ed. 7 Facebook 8 9 June 2020 10 QPACK: Header Compression for HTTP/3 11 draft-ietf-quic-qpack-16 13 Abstract 15 This specification defines QPACK, a compression format for 16 efficiently representing HTTP fields, to be used in HTTP/3. This is 17 a variation of HPACK compression that seeks to reduce head-of-line 18 blocking. 20 Note to Readers 22 Discussion of this draft takes place on the QUIC working group 23 mailing list (quic@ietf.org (mailto:quic@ietf.org)), which is 24 archived at https://mailarchive.ietf.org/arch/ 25 search/?email_list=quic. 27 Working Group information can be found at https://github.com/quicwg; 28 source code and issues list for this draft can be found at 29 https://github.com/quicwg/base-drafts/labels/-qpack. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on 11 December 2020. 48 Copyright Notice 50 Copyright (c) 2020 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 55 license-info) in effect on the date of publication of this document. 56 Please review these documents carefully, as they describe your rights 57 and restrictions with respect to this document. Code Components 58 extracted from this document must include Simplified BSD License text 59 as described in Section 4.e of the Trust Legal Provisions and are 60 provided without warranty as described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 65 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 4 66 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 5 67 2. Compression Process Overview . . . . . . . . . . . . . . . . 5 68 2.1. Encoder . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 2.1.1. Limits on Dynamic Table Insertions . . . . . . . . . 6 70 2.1.2. Blocked Streams . . . . . . . . . . . . . . . . . . . 7 71 2.1.3. Avoiding Flow Control Deadlocks . . . . . . . . . . . 8 72 2.1.4. Known Received Count . . . . . . . . . . . . . . . . 9 73 2.2. Decoder . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 2.2.1. Blocked Decoding . . . . . . . . . . . . . . . . . . 9 75 2.2.2. State Synchronization . . . . . . . . . . . . . . . . 10 76 2.2.3. Invalid References . . . . . . . . . . . . . . . . . 11 77 3. Reference Tables . . . . . . . . . . . . . . . . . . . . . . 11 78 3.1. Static Table . . . . . . . . . . . . . . . . . . . . . . 11 79 3.2. Dynamic Table . . . . . . . . . . . . . . . . . . . . . . 12 80 3.2.1. Dynamic Table Size . . . . . . . . . . . . . . . . . 12 81 3.2.2. Dynamic Table Capacity and Eviction . . . . . . . . . 12 82 3.2.3. Maximum Dynamic Table Capacity . . . . . . . . . . . 13 83 3.2.4. Absolute Indexing . . . . . . . . . . . . . . . . . . 13 84 3.2.5. Relative Indexing . . . . . . . . . . . . . . . . . . 14 85 3.2.6. Post-Base Indexing . . . . . . . . . . . . . . . . . 15 86 4. Wire Format . . . . . . . . . . . . . . . . . . . . . . . . . 15 87 4.1. Primitives . . . . . . . . . . . . . . . . . . . . . . . 15 88 4.1.1. Prefixed Integers . . . . . . . . . . . . . . . . . . 15 89 4.1.2. String Literals . . . . . . . . . . . . . . . . . . . 15 90 4.2. Encoder and Decoder Streams . . . . . . . . . . . . . . . 16 91 4.3. Encoder Instructions . . . . . . . . . . . . . . . . . . 17 92 4.3.1. Set Dynamic Table Capacity . . . . . . . . . . . . . 17 93 4.3.2. Insert With Name Reference . . . . . . . . . . . . . 17 94 4.3.3. Insert Without Name Reference . . . . . . . . . . . . 18 95 4.3.4. Duplicate . . . . . . . . . . . . . . . . . . . . . . 18 97 4.4. Decoder Instructions . . . . . . . . . . . . . . . . . . 19 98 4.4.1. Section Acknowledgement . . . . . . . . . . . . . . . 19 99 4.4.2. Stream Cancellation . . . . . . . . . . . . . . . . . 20 100 4.4.3. Insert Count Increment . . . . . . . . . . . . . . . 20 101 4.5. Field Line Representations . . . . . . . . . . . . . . . 20 102 4.5.1. Encoded Field Section Prefix . . . . . . . . . . . . 21 103 4.5.2. Indexed Field Line . . . . . . . . . . . . . . . . . 23 104 4.5.3. Indexed Field Line With Post-Base Index . . . . . . . 24 105 4.5.4. Literal Field Line With Name Reference . . . . . . . 24 106 4.5.5. Literal Field Line With Post-Base Name Reference . . 25 107 4.5.6. Literal Field Line Without Name Reference . . . . . . 25 108 5. Configuration . . . . . . . . . . . . . . . . . . . . . . . . 26 109 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 26 110 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 111 7.1. Probing Dynamic Table State . . . . . . . . . . . . . . . 27 112 7.2. Applicability to QPACK and HTTP . . . . . . . . . . . . . 28 113 7.3. Mitigation . . . . . . . . . . . . . . . . . . . . . . . 28 114 7.4. Never Indexed Literals . . . . . . . . . . . . . . . . . 29 115 7.5. Static Huffman Encoding . . . . . . . . . . . . . . . . . 30 116 7.6. Memory Consumption . . . . . . . . . . . . . . . . . . . 30 117 7.7. Implementation Limits . . . . . . . . . . . . . . . . . . 31 118 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 119 8.1. Settings Registration . . . . . . . . . . . . . . . . . . 31 120 8.2. Stream Type Registration . . . . . . . . . . . . . . . . 32 121 8.3. Error Code Registration . . . . . . . . . . . . . . . . . 32 122 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 123 9.1. Normative References . . . . . . . . . . . . . . . . . . 33 124 9.2. Informative References . . . . . . . . . . . . . . . . . 34 125 Appendix A. Static Table . . . . . . . . . . . . . . . . . . . . 34 126 Appendix B. Sample One Pass Encoding Algorithm . . . . . . . . . 39 127 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 40 128 C.1. Since draft-ietf-quic-qpack-15 . . . . . . . . . . . . . 40 129 C.2. Since draft-ietf-quic-qpack-14 . . . . . . . . . . . . . 41 130 C.3. Since draft-ietf-quic-qpack-13 . . . . . . . . . . . . . 41 131 C.4. Since draft-ietf-quic-qpack-12 . . . . . . . . . . . . . 41 132 C.5. Since draft-ietf-quic-qpack-11 . . . . . . . . . . . . . 41 133 C.6. Since draft-ietf-quic-qpack-10 . . . . . . . . . . . . . 41 134 C.7. Since draft-ietf-quic-qpack-09 . . . . . . . . . . . . . 41 135 C.8. Since draft-ietf-quic-qpack-08 . . . . . . . . . . . . . 41 136 C.9. Since draft-ietf-quic-qpack-06 . . . . . . . . . . . . . 41 137 C.10. Since draft-ietf-quic-qpack-05 . . . . . . . . . . . . . 41 138 C.11. Since draft-ietf-quic-qpack-04 . . . . . . . . . . . . . 42 139 C.12. Since draft-ietf-quic-qpack-03 . . . . . . . . . . . . . 42 140 C.13. Since draft-ietf-quic-qpack-02 . . . . . . . . . . . . . 42 141 C.14. Since draft-ietf-quic-qpack-01 . . . . . . . . . . . . . 42 142 C.15. Since draft-ietf-quic-qpack-00 . . . . . . . . . . . . . 42 143 C.16. Since draft-ietf-quic-qcram-00 . . . . . . . . . . . . . 43 144 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 43 145 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 44 147 1. Introduction 149 The QUIC transport protocol [QUIC-TRANSPORT] is designed to support 150 HTTP semantics, and its design subsumes many of the features of 151 HTTP/2 [RFC7540]. HTTP/2 uses HPACK [RFC7541] for compression of the 152 header and trailer sections. If HPACK were used for HTTP/3 [HTTP3], 153 it would induce head-of-line blocking for field sections due to 154 built-in assumptions of a total ordering across frames on all 155 streams. 157 QPACK reuses core concepts from HPACK, but is redesigned to allow 158 correctness in the presence of out-of-order delivery, with 159 flexibility for implementations to balance between resilience against 160 head-of-line blocking and optimal compression ratio. The design 161 goals are to closely approach the compression ratio of HPACK with 162 substantially less head-of-line blocking under the same loss 163 conditions. 165 1.1. Conventions and Definitions 167 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 168 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 169 "OPTIONAL" in this document are to be interpreted as described in 170 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 171 capitals, as shown here. 173 Definitions of terms that are used in this document: 175 HTTP fields: Metadata sent as part of an HTTP message. The term 176 encompasses both header and trailer fields. Colloquially, the 177 term "headers" has often been used to refer to HTTP header fields 178 and trailer fields; this document uses "fields" for generality. 180 HTTP field line: A name-value pair sent as part of an HTTP field 181 section. See Section 4 of [SEMANTICS]. 183 HTTP field value: Data associated with a field name, composed from 184 all field line values with that field name in that section, 185 concatenated together and separated with commas. 187 Field section: An ordered collection of HTTP field lines associated 188 with an HTTP message. A field section can contain multiple field 189 lines with the same name. It can also contain duplicate field 190 lines. An HTTP message can include both header field and trailer 191 field sections. 193 Representation: An instruction which represents a field line, 194 possibly by reference to the dynamic and static tables. 196 Encoder: An implementation which encodes field sections. 198 Decoder: An implementation which decodes encoded field sections. 200 Absolute Index: A unique index for each entry in the dynamic table. 202 Base: A reference point for relative and post-base indices. 203 Representations which reference dynamic table entries are relative 204 to a Base. 206 Insert Count: The total number of entries inserted in the dynamic 207 table. 209 QPACK is a name, not an acronym. 211 1.2. Notational Conventions 213 Diagrams use the format described in Section 3.1 of [RFC2360], with 214 the following additional conventions: 216 x (A) Indicates that x is A bits long 218 x (A+) Indicates that x uses the prefixed integer encoding defined 219 in Section 4.1.1, beginning with an A-bit prefix. 221 x ... Indicates that x is variable-length and extends to the end of 222 the region. 224 2. Compression Process Overview 226 Like HPACK, QPACK uses two tables for associating field lines 227 ("headers") to indices. The static table (Section 3.1) is predefined 228 and contains common header field lines (some of them with an empty 229 value). The dynamic table (Section 3.2) is built up over the course 230 of the connection and can be used by the encoder to index both header 231 and trailer field lines in the encoded field sections. 233 QPACK defines unidirectional streams for sending instructions from 234 encoder to decoder and vice versa. 236 2.1. Encoder 238 An encoder converts a header or trailer field section into a series 239 of representations by emitting either an indexed or a literal 240 representation for each field line in the list; see Section 4.5. 241 Indexed representations achieve high compression by replacing the 242 literal name and possibly the value with an index to either the 243 static or dynamic table. References to the static table and literal 244 representations do not require any dynamic state and never risk head- 245 of-line blocking. References to the dynamic table risk head-of-line 246 blocking if the encoder has not received an acknowledgement 247 indicating the entry is available at the decoder. 249 An encoder MAY insert any entry in the dynamic table it chooses; it 250 is not limited to field lines it is compressing. 252 QPACK preserves the ordering of field lines within each field 253 section. An encoder MUST emit field representations in the order 254 they appear in the input field section. 256 QPACK is designed to contain the more complex state tracking to the 257 encoder, while the decoder is relatively simple. 259 2.1.1. Limits on Dynamic Table Insertions 261 Inserting entries into the dynamic table might not be possible if the 262 table contains entries which cannot be evicted. 264 A dynamic table entry cannot be evicted immediately after insertion, 265 even if it has never been referenced. Once the insertion of a 266 dynamic table entry has been acknowledged and there are no 267 outstanding references to the entry in unacknowledged 268 representations, the entry becomes evictable. Note that references 269 on the encoder stream never preclude the eviction of an entry, 270 because those references are guaranteed to be processed before the 271 instruction evicting the entry. 273 If the dynamic table does not contain enough room for a new entry 274 without evicting other entries, and the entries which would be 275 evicted are not evictable, the encoder MUST NOT insert that entry 276 into the dynamic table (including duplicates of existing entries). 277 In order to avoid this, an encoder that uses the dynamic table has to 278 keep track of each dynamic table entry referenced by each field 279 section until those representations are acknowledged by the decoder; 280 see Section 4.4.1. 282 2.1.1.1. Avoiding Prohibited Insertions 284 To ensure that the encoder is not prevented from adding new entries, 285 the encoder can avoid referencing entries that are close to eviction. 286 Rather than reference such an entry, the encoder can emit a Duplicate 287 instruction (Section 4.3.4), and reference the duplicate instead. 289 Determining which entries are too close to eviction to reference is 290 an encoder preference. One heuristic is to target a fixed amount of 291 available space in the dynamic table: either unused space or space 292 that can be reclaimed by evicting non-blocking entries. To achieve 293 this, the encoder can maintain a draining index, which is the 294 smallest absolute index (Section 3.2.4) in the dynamic table that it 295 will emit a reference for. As new entries are inserted, the encoder 296 increases the draining index to maintain the section of the table 297 that it will not reference. If the encoder does not create new 298 references to entries with an absolute index lower than the draining 299 index, the number of unacknowledged references to those entries will 300 eventually become zero, allowing them to be evicted. 302 +--------+---------------------------------+----------+ 303 | Unused | Referenceable | Draining | 304 | Space | Entries | Entries | 305 +--------+---------------------------------+----------+ 306 ^ ^ ^ 307 | | | 308 Insertion Point Draining Index Dropping 309 Point 311 Figure 1: Draining Dynamic Table Entries 313 2.1.2. Blocked Streams 315 Because QUIC does not guarantee order between data on different 316 streams, a decoder might encounter a representation that references a 317 dynamic table entry that it has not yet received. 319 Each encoded field section contains a Required Insert Count 320 (Section 4.5.1), the lowest possible value for the Insert Count with 321 which the field section can be decoded. For a field section encoded 322 using references to the dynamic table, the Required Insert Count is 323 one larger than the largest absolute index of all referenced dynamic 324 table entries. For a field section encoded with no references to the 325 dynamic table, the Required Insert Count is zero. 327 When the decoder receives an encoded field section with a Required 328 Insert Count greater than its own Insert Count, the stream cannot be 329 processed immediately, and is considered "blocked"; see 330 Section 2.2.1. 332 The decoder specifies an upper bound on the number of streams which 333 can be blocked using the SETTINGS_QPACK_BLOCKED_STREAMS setting; see 334 Section 5. An encoder MUST limit the number of streams which could 335 become blocked to the value of SETTINGS_QPACK_BLOCKED_STREAMS at all 336 times. If a decoder encounters more blocked streams than it promised 337 to support, it MUST treat this as a connection error of type 338 QPACK_DECOMPRESSION_FAILED. 340 Note that the decoder might not become blocked on every stream which 341 risks becoming blocked. 343 An encoder can decide whether to risk having a stream become blocked. 344 If permitted by the value of SETTINGS_QPACK_BLOCKED_STREAMS, 345 compression efficiency can often be improved by referencing dynamic 346 table entries that are still in transit, but if there is loss or 347 reordering the stream can become blocked at the decoder. An encoder 348 can avoid the risk of blocking by only referencing dynamic table 349 entries which have been acknowledged, but this could mean using 350 literals. Since literals make the encoded field section larger, this 351 can result in the encoder becoming blocked on congestion or flow 352 control limits. 354 2.1.3. Avoiding Flow Control Deadlocks 356 Writing instructions on streams that are limited by flow control can 357 produce deadlocks. 359 A decoder might stop issuing flow control credit on the stream that 360 carries an encoded field section until the necessary updates are 361 received on the encoder stream. If the granting of flow control 362 credit on the encoder stream (or the connection as a whole) depends 363 on the consumption and release of data on the stream carrying the 364 encoded field section, a deadlock might result. 366 More generally, a stream containing a large instruction can become 367 deadlocked if the decoder withholds flow control credit until the 368 instruction is completely received. 370 To avoid these deadlocks, an encoder SHOULD avoid writing an 371 instruction unless sufficient stream and connection flow control 372 credit is available for the entire instruction. 374 2.1.4. Known Received Count 376 The Known Received Count is the total number of dynamic table 377 insertions and duplications acknowledged by the decoder. The encoder 378 tracks the Known Received Count in order to identify which dynamic 379 table entries can be referenced without potentially blocking a 380 stream. The decoder tracks the Known Received Count in order to be 381 able to send Insert Count Increment instructions. 383 A Section Acknowledgement instruction (Section 4.4.1) implies that 384 the decoder has received all dynamic table state necessary to decode 385 the field section. If the Required Insert Count of the acknowledged 386 field section is greater than the current Known Received Count, Known 387 Received Count is updated to the value of the Required Insert Count. 389 An Insert Count Increment instruction Section 4.4.3 increases the 390 Known Received Count by its Increment parameter. See Section 2.2.2.3 391 for guidance. 393 2.2. Decoder 395 As in HPACK, the decoder processes a series of representations and 396 emits the corresponding field sections. It also processes 397 instructions received on the encoder stream that modify the dynamic 398 table. Note that encoded field sections and encoder stream 399 instructions arrive on separate streams. This is unlike HPACK, where 400 encoded field sections (header blocks) can contain instructions that 401 modify the dynamic table, and there is no dedicated stream of HPACK 402 instructions. 404 The decoder MUST emit field lines in the order their representations 405 appear in the encoded field section. 407 2.2.1. Blocked Decoding 409 Upon receipt of an encoded field section, the decoder examines the 410 Required Insert Count. When the Required Insert Count is less than 411 or equal to the decoder's Insert Count, the field section can be 412 processed immediately. Otherwise, the stream on which the field 413 section was received becomes blocked. 415 While blocked, encoded field section data SHOULD remain in the 416 blocked stream's flow control window. A stream becomes unblocked 417 when the Insert Count becomes greater than or equal to the Required 418 Insert Count for all encoded field sections the decoder has started 419 reading from the stream. 421 When processing encoded field sections, the decoder expects the 422 Required Insert Count to equal the lowest possible value for the 423 Insert Count with which the field section can be decoded, as 424 prescribed in Section 2.1.2. If it encounters a Required Insert 425 Count smaller than expected, it MUST treat this as a connection error 426 of type QPACK_DECOMPRESSION_FAILED; see Section 2.2.3. If it 427 encounters a Required Insert Count larger than expected, it MAY treat 428 this as a connection error of type QPACK_DECOMPRESSION_FAILED. 430 2.2.2. State Synchronization 432 The decoder signals the following events by emitting decoder 433 instructions (Section 4.4) on the decoder stream. 435 2.2.2.1. Completed Processing of a Field Section 437 After the decoder finishes decoding a field section encoded using 438 representations containing dynamic table references, it MUST emit a 439 Section Acknowledgement instruction (Section 4.4.1). A stream may 440 carry multiple field sections in the case of intermediate responses, 441 trailers, and pushed requests. The encoder interprets each 442 Section Acknowledgement instruction as acknowledging the earliest 443 unacknowledged field section containing dynamic table references sent 444 on the given stream. 446 2.2.2.2. Abandonment of a Stream 448 When an endpoint receives a stream reset before the end of a stream 449 or before all encoded field sections are processed on that stream, or 450 when it abandons reading of a stream, it generates a Stream 451 Cancellation instruction; see Section 4.4.2. This signals to the 452 encoder that all references to the dynamic table on that stream are 453 no longer outstanding. A decoder with a maximum dynamic table 454 capacity (Section 3.2.3) equal to zero MAY omit sending Stream 455 Cancellations, because the encoder cannot have any dynamic table 456 references. An encoder cannot infer from this instruction that any 457 updates to the dynamic table have been received. 459 The Section Acknowledgement and Stream Cancellation instructions 460 permit the encoder to remove references to entries in the dynamic 461 table. When an entry with absolute index lower than the Known 462 Received Count has zero references, then it is considered evictable; 463 see Section 2.1.1. 465 2.2.2.3. New Table Entries 467 After receiving new table entries on the encoder stream, the decoder 468 chooses when to emit Insert Count Increment instructions; see 469 Section 4.4.3. Emitting this instruction after adding each new 470 dynamic table entry will provide the timeliest feedback to the 471 encoder, but could be redundant with other decoder feedback. By 472 delaying an Insert Count Increment instruction, the decoder might be 473 able to coalesce multiple Insert Count Increment instructions, or 474 replace them entirely with Section Acknowledgements; see 475 Section 4.4.1. However, delaying too long may lead to compression 476 inefficiencies if the encoder waits for an entry to be acknowledged 477 before using it. 479 2.2.3. Invalid References 481 If the decoder encounters a reference in a field line representation 482 to a dynamic table entry which has already been evicted or which has 483 an absolute index greater than or equal to the declared Required 484 Insert Count (Section 4.5.1), it MUST treat this as a connection 485 error of type QPACK_DECOMPRESSION_FAILED. 487 If the decoder encounters a reference in an encoder instruction to a 488 dynamic table entry which has already been evicted, it MUST treat 489 this as a connection error of type QPACK_ENCODER_STREAM_ERROR. 491 3. Reference Tables 493 Unlike in HPACK, entries in the QPACK static and dynamic tables are 494 addressed separately. The following sections describe how entries in 495 each table are addressed. 497 3.1. Static Table 499 The static table consists of a predefined static list of field lines, 500 each of which has a fixed index over time. Its entries are defined 501 in Appendix A. 503 All entries in the static table have a name and a value. However, 504 values can be empty (that is, have a length of 0). Each entry is 505 identified by a unique index. 507 Note that the QPACK static table is indexed from 0, whereas the HPACK 508 static table is indexed from 1. 510 When the decoder encounters an invalid static table index in a field 511 line representation it MUST treat this as a connection error of type 512 QPACK_DECOMPRESSION_FAILED. If this index is received on the encoder 513 stream, this MUST be treated as a connection error of type 514 QPACK_ENCODER_STREAM_ERROR. 516 3.2. Dynamic Table 518 The dynamic table consists of a list of field lines maintained in 519 first-in, first-out order. Each HTTP/3 endpoint holds a dynamic 520 table that is initially empty. Entries are added by encoder 521 instructions received on the encoder stream; see Section 4.3. 523 The dynamic table can contain duplicate entries (i.e., entries with 524 the same name and same value). Therefore, duplicate entries MUST NOT 525 be treated as an error by the decoder. 527 Dynamic table entries can have empty values. 529 3.2.1. Dynamic Table Size 531 The size of the dynamic table is the sum of the size of its entries. 533 The size of an entry is the sum of its name's length in bytes, its 534 value's length in bytes, and 32. The size of an entry is calculated 535 using the length of its name and value without Huffman encoding 536 applied. 538 3.2.2. Dynamic Table Capacity and Eviction 540 The encoder sets the capacity of the dynamic table, which serves as 541 the upper limit on its size. The initial capacity of the dynamic 542 table is zero. The encoder sends a Set Dynamic Table Capacity 543 instruction (Section 4.3.1) with a non-zero capacity to begin using 544 the dynamic table. 546 Before a new entry is added to the dynamic table, entries are evicted 547 from the end of the dynamic table until the size of the dynamic table 548 is less than or equal to (table capacity - size of new entry). The 549 encoder MUST NOT cause a dynamic table entry to be evicted unless 550 that entry is evictable; see Section 2.1.1. The new entry is then 551 added to the table. It is an error if the encoder attempts to add an 552 entry that is larger than the dynamic table capacity; the decoder 553 MUST treat this as a connection error of type 554 QPACK_ENCODER_STREAM_ERROR. 556 A new entry can reference an entry in the dynamic table that will be 557 evicted when adding this new entry into the dynamic table. 558 Implementations are cautioned to avoid deleting the referenced name 559 or value if the referenced entry is evicted from the dynamic table 560 prior to inserting the new entry. 562 Whenever the dynamic table capacity is reduced by the encoder 563 (Section 4.3.1), entries are evicted from the end of the dynamic 564 table until the size of the dynamic table is less than or equal to 565 the new table capacity. This mechanism can be used to completely 566 clear entries from the dynamic table by setting a capacity of 0, 567 which can subsequently be restored. 569 3.2.3. Maximum Dynamic Table Capacity 571 To bound the memory requirements of the decoder, the decoder limits 572 the maximum value the encoder is permitted to set for the dynamic 573 table capacity. In HTTP/3, this limit is determined by the value of 574 SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder; see Section 5. 575 The encoder MUST not set a dynamic table capacity that exceeds this 576 maximum, but it can choose to use a lower dynamic table capacity; see 577 Section 4.3.1. 579 For clients using 0-RTT data in HTTP/3, the server's maximum table 580 capacity is the remembered value of the setting, or zero if the value 581 was not previously sent. When the client's 0-RTT value of the 582 SETTING is zero, the server MAY set it to a non-zero value in its 583 SETTINGS frame. If the remembered value is non-zero, the server MUST 584 send the same non-zero value in its SETTINGS frame. If it specifies 585 any other value, or omits SETTINGS_QPACK_MAX_TABLE_CAPACITY from 586 SETTINGS, the encoder must treat this as a connection error of type 587 QPACK_DECODER_STREAM_ERROR. 589 For HTTP/3 servers and HTTP/3 clients when 0-RTT is not attempted or 590 is rejected, the maximum table capacity is 0 until the encoder 591 processes a SETTINGS frame with a non-zero value of 592 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 594 When the maximum table capacity is zero, the encoder MUST NOT insert 595 entries into the dynamic table, and MUST NOT send any encoder 596 instructions on the encoder stream. 598 3.2.4. Absolute Indexing 600 Each entry possesses an absolute index which is fixed for the 601 lifetime of that entry. The first entry inserted has an absolute 602 index of "0"; indices increase by one with each insertion. 604 3.2.5. Relative Indexing 606 Relative indices begin at zero and increase in the opposite direction 607 from the absolute index. Determining which entry has a relative 608 index of "0" depends on the context of the reference. 610 In encoder instructions (Section 4.3), a relative index of "0" refers 611 to the most recently inserted value in the dynamic table. Note that 612 this means the entry referenced by a given relative index will change 613 while interpreting instructions on the encoder stream. 615 +-----+---------------+-------+ 616 | n-1 | ... | d | Absolute Index 617 + - - +---------------+ - - - + 618 | 0 | ... | n-d-1 | Relative Index 619 +-----+---------------+-------+ 620 ^ | 621 | V 622 Insertion Point Dropping Point 624 n = count of entries inserted 625 d = count of entries dropped 627 Figure 2: Example Dynamic Table Indexing - Encoder Stream 629 Unlike in encoder instructions, relative indices in field line 630 representations are relative to the Base at the beginning of the 631 encoded field section; see Section 4.5.1. This ensures that 632 references are stable even if encoded field sections and dynamic 633 table updates are processed out of order. 635 In a field line representation, a relative index of "0" refers to the 636 entry with absolute index equal to Base - 1. 638 Base 639 | 640 V 641 +-----+-----+-----+-----+-------+ 642 | n-1 | n-2 | n-3 | ... | d | Absolute Index 643 +-----+-----+ - +-----+ - + 644 | 0 | ... | n-d-3 | Relative Index 645 +-----+-----+-------+ 647 n = count of entries inserted 648 d = count of entries dropped 649 In this example, Base = n - 2 650 Figure 3: Example Dynamic Table Indexing - Relative Index in 651 Representation 653 3.2.6. Post-Base Indexing 655 Post-Base indices are used in field line representations for entries 656 with absolute indices greater than or equal to Base, starting at 0 657 for the entry with absolute index equal to Base, and increasing in 658 the same direction as the absolute index. 660 Post-Base indices allow an encoder to process a field section in a 661 single pass and include references to entries added while processing 662 this (or other) field sections. 664 Base 665 | 666 V 667 +-----+-----+-----+-----+-----+ 668 | n-1 | n-2 | n-3 | ... | d | Absolute Index 669 +-----+-----+-----+-----+-----+ 670 | 1 | 0 | Post-Base Index 671 +-----+-----+ 673 n = count of entries inserted 674 d = count of entries dropped 675 In this example, Base = n - 2 677 Figure 4: Example Dynamic Table Indexing - Post-Base Index in 678 Representation 680 4. Wire Format 682 4.1. Primitives 684 4.1.1. Prefixed Integers 686 The prefixed integer from Section 5.1 of [RFC7541] is used heavily 687 throughout this document. The format from [RFC7541] is used 688 unmodified. Note, however, that QPACK uses some prefix sizes not 689 actually used in HPACK. 691 QPACK implementations MUST be able to decode integers up to and 692 including 62 bits long. 694 4.1.2. String Literals 696 The string literal defined by Section 5.2 of [RFC7541] is also used 697 throughout. This string format includes optional Huffman encoding. 699 HPACK defines string literals to begin on a byte boundary. They 700 begin with a single bit flag, denoted as 'H' in this document 701 (indicating whether the string is Huffman-coded), followed by the 702 Length encoded as a 7-bit prefix integer, and finally Length bytes of 703 data. When Huffman encoding is enabled, the Huffman table from 704 Appendix B of [RFC7541] is used without modification. 706 This document expands the definition of string literals and permits 707 them to begin other than on a byte boundary. An "N-bit prefix string 708 literal" begins with the same Huffman flag, followed by the length 709 encoded as an (N-1)-bit prefix integer. The prefix size, N, can have 710 a value between 2 and 8 inclusive. The remainder of the string 711 literal is unmodified. 713 A string literal without a prefix length noted is an 8-bit prefix 714 string literal and follows the definitions in [RFC7541] without 715 modification. 717 4.2. Encoder and Decoder Streams 719 QPACK defines two unidirectional stream types: 721 * An encoder stream is a unidirectional stream of type 0x02. It 722 carries an unframed sequence of encoder instructions from encoder 723 to decoder. 725 * A decoder stream is a unidirectional stream of type 0x03. It 726 carries an unframed sequence of decoder instructions from decoder 727 to encoder. 729 HTTP/3 endpoints contain a QPACK encoder and decoder. Each endpoint 730 MUST initiate at most one encoder stream and at most one decoder 731 stream. Receipt of a second instance of either stream type MUST be 732 treated as a connection error of type H3_STREAM_CREATION_ERROR. 733 These streams MUST NOT be closed. Closure of either unidirectional 734 stream type MUST be treated as a connection error of type 735 H3_CLOSED_CRITICAL_STREAM. 737 An endpoint MAY avoid creating an encoder stream if it's not going to 738 be used (for example if its encoder doesn't wish to use the dynamic 739 table, or if the maximum size of the dynamic table permitted by the 740 peer is zero). 742 An endpoint MAY avoid creating a decoder stream if its decoder sets 743 the maximum capacity of the dynamic table to zero. 745 An endpoint MUST allow its peer to create an encoder stream and a 746 decoder stream even if the connection's settings prevent their use. 748 4.3. Encoder Instructions 750 An encoder sends encoder instructions on the encoder stream to set 751 the capacity of the dynamic table and add dynamic table entries. 752 Instructions adding table entries can use existing entries to avoid 753 transmitting redundant information. The name can be transmitted as a 754 reference to an existing entry in the static or the dynamic table or 755 as a string literal. For entries which already exist in the dynamic 756 table, the full entry can also be used by reference, creating a 757 duplicate entry. 759 This section specifies the following encoder instructions. 761 4.3.1. Set Dynamic Table Capacity 763 An encoder informs the decoder of a change to the dynamic table 764 capacity using an instruction which begins with the '001' three-bit 765 pattern. This is followed by the new dynamic table capacity 766 represented as an integer with a 5-bit prefix; see Section 4.1.1. 768 0 1 2 3 4 5 6 7 769 +---+---+---+---+---+---+---+---+ 770 | 0 | 0 | 1 | Capacity (5+) | 771 +---+---+---+-------------------+ 773 Figure 5: Set Dynamic Table Capacity 775 The new capacity MUST be lower than or equal to the limit described 776 in Section 3.2.3. In HTTP/3, this limit is the value of the 777 SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter (Section 5) received from 778 the decoder. The decoder MUST treat a new dynamic table capacity 779 value that exceeds this limit as a connection error of type 780 QPACK_ENCODER_STREAM_ERROR. 782 Reducing the dynamic table capacity can cause entries to be evicted; 783 see Section 3.2.2. This MUST NOT cause the eviction of entries which 784 are not evictable; see Section 2.1.1. Changing the capacity of the 785 dynamic table is not acknowledged as this instruction does not insert 786 an entry. 788 4.3.2. Insert With Name Reference 790 An encoder adds an entry to the dynamic table where the field name 791 matches the field name of an entry stored in the static or the 792 dynamic table using an instruction that starts with the '1' one-bit 793 pattern. The second ('T') bit indicates whether the reference is to 794 the static or dynamic table. The 6-bit prefix integer 795 (Section 4.1.1) that follows is used to locate the table entry for 796 the field name. When T=1, the number represents the static table 797 index; when T=0, the number is the relative index of the entry in the 798 dynamic table. 800 The field name reference is followed by the field value represented 801 as a string literal; see Section 4.1.2. 803 0 1 2 3 4 5 6 7 804 +---+---+---+---+---+---+---+---+ 805 | 1 | T | Name Index (6+) | 806 +---+---+-----------------------+ 807 | H | Value Length (7+) | 808 +---+---------------------------+ 809 | Value String (Length bytes) | 810 +-------------------------------+ 812 Figure 6: Insert Field Line -- Indexed Name 814 4.3.3. Insert Without Name Reference 816 An encoder adds an entry to the dynamic table where both the field 817 name and the field value are represented as string literals using an 818 instruction that starts with the '01' two-bit pattern. 820 This is followed by the name represented as a 6-bit prefix string 821 literal, and the value represented as an 8-bit prefix string literal; 822 see Section 4.1.2. 824 0 1 2 3 4 5 6 7 825 +---+---+---+---+---+---+---+---+ 826 | 0 | 1 | H | Name Length (5+) | 827 +---+---+---+-------------------+ 828 | Name String (Length bytes) | 829 +---+---------------------------+ 830 | H | Value Length (7+) | 831 +---+---------------------------+ 832 | Value String (Length bytes) | 833 +-------------------------------+ 835 Figure 7: Insert Field Line -- New Name 837 4.3.4. Duplicate 839 An encoder duplicates an existing entry in the dynamic table using an 840 instruction that begins with the '000' three-bit pattern. This is 841 followed by the relative index of the existing entry represented as 842 an integer with a 5-bit prefix; see Section 4.1.1. 844 0 1 2 3 4 5 6 7 845 +---+---+---+---+---+---+---+---+ 846 | 0 | 0 | 0 | Index (5+) | 847 +---+---+---+-------------------+ 849 Figure 8: Duplicate 851 The existing entry is re-inserted into the dynamic table without 852 resending either the name or the value. This is useful to avoid 853 adding a reference to an older entry, which might block inserting new 854 entries. 856 4.4. Decoder Instructions 858 A decoder sends decoder instructions on the decoder stream to inform 859 the encoder about the processing of field sections and table updates 860 to ensure consistency of the dynamic table. 862 This section specifies the following decoder instructions. 864 4.4.1. Section Acknowledgement 866 After processing an encoded field section whose declared Required 867 Insert Count is not zero, the decoder emits a Section Acknowledgement 868 instruction. The instruction begins with the '1' one-bit pattern 869 which is followed by the field section's associated stream ID encoded 870 as a 7-bit prefix integer; see Section 4.1.1. 872 This instruction is used as described in Section 2.1.4 and in 873 Section 2.2.2. 875 0 1 2 3 4 5 6 7 876 +---+---+---+---+---+---+---+---+ 877 | 1 | Stream ID (7+) | 878 +---+---------------------------+ 880 Figure 9: Section Acknowledgement 882 If an encoder receives a Section Acknowledgement instruction 883 referring to a stream on which every encoded field section with a 884 non-zero Required Insert Count has already been acknowledged, that 885 MUST be treated as a connection error of type 886 QPACK_DECODER_STREAM_ERROR. 888 The Section Acknowledgement instruction might increase the Known 889 Received Count; see Section 2.1.4. 891 4.4.2. Stream Cancellation 893 When a stream is reset or reading is abandoned, the decoder emits a 894 Stream Cancellation instruction. The instruction begins with the 895 '01' two-bit pattern, which is followed by the stream ID of the 896 affected stream encoded as a 6-bit prefix integer. 898 This instruction is used as described in Section 2.2.2. 900 0 1 2 3 4 5 6 7 901 +---+---+---+---+---+---+---+---+ 902 | 0 | 1 | Stream ID (6+) | 903 +---+---+-----------------------+ 905 Figure 10: Stream Cancellation 907 4.4.3. Insert Count Increment 909 The Insert Count Increment instruction begins with the '00' two-bit 910 pattern, followed by the Increment encoded as a 6-bit prefix integer. 911 This instruction increases the Known Received Count (Section 2.1.4) 912 by the value of the Increment parameter. The decoder should send an 913 Increment value that increases the Known Received Count to the total 914 number of dynamic table insertions and duplications processed so far. 916 0 1 2 3 4 5 6 7 917 +---+---+---+---+---+---+---+---+ 918 | 0 | 0 | Increment (6+) | 919 +---+---+-----------------------+ 921 Figure 11: Insert Count Increment 923 An encoder that receives an Increment field equal to zero, or one 924 that increases the Known Received Count beyond what the encoder has 925 sent MUST treat this as a connection error of type 926 QPACK_DECODER_STREAM_ERROR. 928 4.5. Field Line Representations 930 An encoded field section consists of a prefix and a possibly empty 931 sequence of representations defined in this section. Each 932 representation corresponds to a single field line. These 933 representations reference the static table or the dynamic table in a 934 particular state, but do not modify that state. 936 Encoded field sections are carried in frames on streams defined by 937 the enclosing protocol. 939 4.5.1. Encoded Field Section Prefix 941 Each encoded field section is prefixed with two integers. The 942 Required Insert Count is encoded as an integer with an 8-bit prefix 943 after the encoding described in Section 4.5.1.1). The Base is 944 encoded as a sign bit ('S') and a Delta Base value with a 7-bit 945 prefix; see Section 4.5.1.2. 947 0 1 2 3 4 5 6 7 948 +---+---+---+---+---+---+---+---+ 949 | Required Insert Count (8+) | 950 +---+---------------------------+ 951 | S | Delta Base (7+) | 952 +---+---------------------------+ 953 | Encoded Field Lines ... 954 +-------------------------------+ 956 Figure 12: Encoded Field Section 958 4.5.1.1. Required Insert Count 960 Required Insert Count identifies the state of the dynamic table 961 needed to process the encoded field section. Blocking decoders use 962 the Required Insert Count to determine when it is safe to process the 963 rest of the field section. 965 The encoder transforms the Required Insert Count as follows before 966 encoding: 968 if ReqInsertCount == 0: 969 EncInsertCount = 0 970 else: 971 EncInsertCount = (ReqInsertCount mod (2 * MaxEntries)) + 1 973 Here "MaxEntries" is the maximum number of entries that the dynamic 974 table can have. The smallest entry has empty name and value strings 975 and has the size of 32. Hence "MaxEntries" is calculated as 977 MaxEntries = floor( MaxTableCapacity / 32 ) 979 "MaxTableCapacity" is the maximum capacity of the dynamic table as 980 specified by the decoder; see Section 3.2.3. 982 This encoding limits the length of the prefix on long-lived 983 connections. 985 The decoder can reconstruct the Required Insert Count using an 986 algorithm such as the following. If the decoder encounters a value 987 of EncodedInsertCount that could not have been produced by a 988 conformant encoder, it MUST treat this as a connection error of type 989 QPACK_DECOMPRESSION_FAILED. 991 TotalNumberOfInserts is the total number of inserts into the 992 decoder's dynamic table. 994 FullRange = 2 * MaxEntries 995 if EncodedInsertCount == 0: 996 ReqInsertCount = 0 997 else: 998 if EncodedInsertCount > FullRange: 999 Error 1000 MaxValue = TotalNumberOfInserts + MaxEntries 1002 # MaxWrapped is the largest possible value of 1003 # ReqInsertCount that is 0 mod 2*MaxEntries 1004 MaxWrapped = floor(MaxValue / FullRange) * FullRange 1005 ReqInsertCount = MaxWrapped + EncodedInsertCount - 1 1007 # If ReqInsertCount exceeds MaxValue, the Encoder's value 1008 # must have wrapped one fewer time 1009 if ReqInsertCount > MaxValue: 1010 if ReqInsertCount <= FullRange: 1011 Error 1012 ReqInsertCount -= FullRange 1014 # Value of 0 must be encoded as 0. 1015 if ReqInsertCount == 0: 1016 Error 1018 For example, if the dynamic table is 100 bytes, then the Required 1019 Insert Count will be encoded modulo 6. If a decoder has received 10 1020 inserts, then an encoded value of 4 indicates that the Required 1021 Insert Count is 9 for the field section. 1023 4.5.1.2. Base 1025 The Base is used to resolve references in the dynamic table as 1026 described in Section 3.2.5. 1028 To save space, the Base is encoded relative to the Required Insert 1029 Count using a one-bit sign ('S') and the Delta Base value. A sign 1030 bit of 0 indicates that the Base is greater than or equal to the 1031 value of the Required Insert Count; the decoder adds the value of 1032 Delta Base to the Required Insert Count to determine the value of the 1033 Base. A sign bit of 1 indicates that the Base is less than the 1034 Required Insert Count; the decoder subtracts the value of Delta Base 1035 from the Required Insert Count and also subtracts one to determine 1036 the value of the Base. That is: 1038 if S == 0: 1039 Base = ReqInsertCount + DeltaBase 1040 else: 1041 Base = ReqInsertCount - DeltaBase - 1 1043 A single-pass encoder determines the Base before encoding a field 1044 section. If the encoder inserted entries in the dynamic table while 1045 encoding the field section, Required Insert Count will be greater 1046 than the Base, so the encoded difference is negative and the sign bit 1047 is set to 1. If the field section was not encoded using 1048 representations which reference the most recent entry in the table 1049 and did not insert any new entries, the Base will be greater than the 1050 Required Insert Count, so the delta will be positive and the sign bit 1051 is set to 0. 1053 An encoder that produces table updates before encoding a field 1054 section might set Base to the value of Required Insert Count. In 1055 such case, both the sign bit and the Delta Base will be set to zero. 1057 A field section that was encoded without references to the dynamic 1058 table can use any value for the Base; setting Delta Base to zero is 1059 one of the most efficient encodings. 1061 For example, with a Required Insert Count of 9, a decoder receives an 1062 S bit of 1 and a Delta Base of 2. This sets the Base to 6 and 1063 enables post-base indexing for three entries. In this example, a 1064 relative index of 1 refers to the 5th entry that was added to the 1065 table; a post-base index of 1 refers to the 8th entry. 1067 4.5.2. Indexed Field Line 1069 An indexed field line representation identifies an entry in the 1070 static table, or an entry in the dynamic table with an absolute index 1071 less than the value of the Base. 1073 0 1 2 3 4 5 6 7 1074 +---+---+---+---+---+---+---+---+ 1075 | 1 | T | Index (6+) | 1076 +---+---+-----------------------+ 1078 Figure 13: Indexed Field Line 1080 This representation starts with the '1' 1-bit pattern, followed by 1081 the 'T' bit indicating whether the reference is into the static or 1082 dynamic table. The 6-bit prefix integer (Section 4.1.1) that follows 1083 is used to locate the table entry for the field line. When T=1, the 1084 number represents the static table index; when T=0, the number is the 1085 relative index of the entry in the dynamic table. 1087 4.5.3. Indexed Field Line With Post-Base Index 1089 An indexed field line with post-base index representation identifies 1090 an entry in the dynamic table with an absolute index greater than or 1091 equal to the value of the Base. 1093 0 1 2 3 4 5 6 7 1094 +---+---+---+---+---+---+---+---+ 1095 | 0 | 0 | 0 | 1 | Index (4+) | 1096 +---+---+---+---+---------------+ 1098 Figure 14: Indexed Field Line with Post-Base Index 1100 This representation starts with the '0001' 4-bit pattern. This is 1101 followed by the post-base index (Section 3.2.6) of the matching field 1102 line, represented as an integer with a 4-bit prefix; see 1103 Section 4.1.1. 1105 4.5.4. Literal Field Line With Name Reference 1107 A literal field line with name reference representation encodes a 1108 field line where the field name matches the field name of an entry in 1109 the static table, or the field name of an entry in the dynamic table 1110 with an absolute index less than the value of the Base. 1112 0 1 2 3 4 5 6 7 1113 +---+---+---+---+---+---+---+---+ 1114 | 0 | 1 | N | T |Name Index (4+)| 1115 +---+---+---+---+---------------+ 1116 | H | Value Length (7+) | 1117 +---+---------------------------+ 1118 | Value String (Length bytes) | 1119 +-------------------------------+ 1121 Figure 15: Literal Field Line With Name Reference 1123 This representation starts with the '01' two-bit pattern. The 1124 following bit, 'N', indicates whether an intermediary is permitted to 1125 add this field line to the dynamic table on subsequent hops. When 1126 the 'N' bit is set, the encoded field line MUST always be encoded 1127 with a literal representation. In particular, when a peer sends a 1128 field line that it received represented as a literal field line with 1129 the 'N' bit set, it MUST use a literal representation to forward this 1130 field line. This bit is intended for protecting field values that 1131 are not to be put at risk by compressing them; see Section 7 for more 1132 details. 1134 The fourth ('T') bit indicates whether the reference is to the static 1135 or dynamic table. The 4-bit prefix integer (Section 4.1.1) that 1136 follows is used to locate the table entry for the field name. When 1137 T=1, the number represents the static table index; when T=0, the 1138 number is the relative index of the entry in the dynamic table. 1140 Only the field name is taken from the dynamic table entry; the field 1141 value is encoded as an 8-bit prefix string literal; see 1142 Section 4.1.2. 1144 4.5.5. Literal Field Line With Post-Base Name Reference 1146 A literal field line with post-base name reference representation 1147 encodes a field line where the field name matches the field name of a 1148 dynamic table entry with an absolute index greater than or equal to 1149 the value of the Base. 1151 0 1 2 3 4 5 6 7 1152 +---+---+---+---+---+---+---+---+ 1153 | 0 | 0 | 0 | 0 | N |NameIdx(3+)| 1154 +---+---+---+---+---+-----------+ 1155 | H | Value Length (7+) | 1156 +---+---------------------------+ 1157 | Value String (Length bytes) | 1158 +-------------------------------+ 1160 Figure 16: Literal Field Line With Post-Base Name Reference 1162 This representation starts with the '0000' four-bit pattern. The 1163 fifth bit is the 'N' bit as described in Section 4.5.4. This is 1164 followed by a post-base index of the dynamic table entry 1165 (Section 3.2.6) encoded as an integer with a 3-bit prefix; see 1166 Section 4.1.1. 1168 Only the field name is taken from the dynamic table entry; the field 1169 value is encoded as an 8-bit prefix string literal; see 1170 Section 4.1.2. 1172 4.5.6. Literal Field Line Without Name Reference 1174 The literal field line without name reference representation encodes 1175 a field name and a field value as string literals. 1177 0 1 2 3 4 5 6 7 1178 +---+---+---+---+---+---+---+---+ 1179 | 0 | 0 | 1 | N | H |NameLen(3+)| 1180 +---+---+---+---+---+-----------+ 1181 | Name String (Length bytes) | 1182 +---+---------------------------+ 1183 | H | Value Length (7+) | 1184 +---+---------------------------+ 1185 | Value String (Length bytes) | 1186 +-------------------------------+ 1188 Figure 17: Literal Field Line Without Name Reference 1190 This representation begins with the '001' three-bit pattern. The 1191 fourth bit is the 'N' bit as described in Section 4.5.4. The name 1192 follows, represented as a 4-bit prefix string literal, then the 1193 value, represented as an 8-bit prefix string literal; see 1194 Section 4.1.2. 1196 5. Configuration 1198 QPACK defines two settings which are included in the HTTP/3 SETTINGS 1199 frame. 1201 SETTINGS_QPACK_MAX_TABLE_CAPACITY (0x1): The default value is zero. 1202 See Section 3.2 for usage. This is the equivalent of the 1203 SETTINGS_HEADER_TABLE_SIZE from HTTP/2. 1205 SETTINGS_QPACK_BLOCKED_STREAMS (0x7): The default value is zero. 1206 See Section 2.1.2. 1208 6. Error Handling 1210 The following error codes are defined for HTTP/3 to indicate failures 1211 of QPACK which prevent the connection from continuing: 1213 QPACK_DECOMPRESSION_FAILED (0x200): The decoder failed to interpret 1214 an encoded field section and is not able to continue decoding that 1215 field section. 1217 QPACK_ENCODER_STREAM_ERROR (0x201): The decoder failed to interpret 1218 an encoder instruction received on the encoder stream. 1220 QPACK_DECODER_STREAM_ERROR (0x202): The encoder failed to interpret 1221 a decoder instruction received on the decoder stream. 1223 7. Security Considerations 1225 This section describes potential areas of security concern with 1226 QPACK: 1228 * Use of compression as a length-based oracle for verifying guesses 1229 about secrets that are compressed into a shared compression 1230 context. 1232 * Denial of service resulting from exhausting processing or memory 1233 capacity at a decoder. 1235 7.1. Probing Dynamic Table State 1237 QPACK reduces the length of header field encodings by exploiting the 1238 redundancy inherent in protocols like HTTP. The ultimate goal of 1239 this is to reduce the amount of data that is required to send HTTP 1240 requests or responses. 1242 The compression context used to encode header fields can be probed by 1243 an attacker who can both define header fields to be encoded and 1244 transmitted and observe the length of those fields once they are 1245 encoded. When an attacker can do both, they can adaptively modify 1246 requests in order to confirm guesses about the dynamic table state. 1247 If a guess is compressed into a shorter length, the attacker can 1248 observe the encoded length and infer that the guess was correct. 1250 This is possible even over the Transport Layer Security Protocol 1251 (TLS, see [RFC5246]), because while TLS provides confidentiality 1252 protection for content, it only provides a limited amount of 1253 protection for the length of that content. 1255 Note: Padding schemes only provide limited protection against an 1256 attacker with these capabilities, potentially only forcing an 1257 increased number of guesses to learn the length associated with a 1258 given guess. Padding schemes also work directly against 1259 compression by increasing the number of bits that are transmitted. 1261 Attacks like CRIME [CRIME] demonstrated the existence of these 1262 general attacker capabilities. The specific attack exploited the 1263 fact that DEFLATE [RFC1951] removes redundancy based on prefix 1264 matching. This permitted the attacker to confirm guesses a character 1265 at a time, reducing an exponential-time attack into a linear-time 1266 attack. 1268 7.2. Applicability to QPACK and HTTP 1270 QPACK mitigates but does not completely prevent attacks modeled on 1271 CRIME [CRIME] by forcing a guess to match an entire header field 1272 value, rather than individual characters. An attacker can only learn 1273 whether a guess is correct or not, so is reduced to a brute force 1274 guess for the header field values. 1276 The viability of recovering specific header field values therefore 1277 depends on the entropy of values. As a result, values with high 1278 entropy are unlikely to be recovered successfully. However, values 1279 with low entropy remain vulnerable. 1281 Attacks of this nature are possible any time that two mutually 1282 distrustful entities control requests or responses that are placed 1283 onto a single HTTP/3 connection. If the shared QPACK compressor 1284 permits one entity to add entries to the dynamic table, and the other 1285 to access those entries, then the state of the table can be learned. 1287 Having requests or responses from mutually distrustful entities 1288 occurs when an intermediary either: 1290 * sends requests from multiple clients on a single connection toward 1291 an origin server, or 1293 * takes responses from multiple origin servers and places them on a 1294 shared connection toward a client. 1296 Web browsers also need to assume that requests made on the same 1297 connection by different web origins [RFC6454] are made by mutually 1298 distrustful entities. 1300 7.3. Mitigation 1302 Users of HTTP that require confidentiality for header fields can use 1303 values with entropy sufficient to make guessing infeasible. However, 1304 this is impractical as a general solution because it forces all users 1305 of HTTP to take steps to mitigate attacks. It would impose new 1306 constraints on how HTTP is used. 1308 Rather than impose constraints on users of HTTP, an implementation of 1309 QPACK can instead constrain how compression is applied in order to 1310 limit the potential for dynamic table probing. 1312 An ideal solution segregates access to the dynamic table based on the 1313 entity that is constructing header fields. Header field values that 1314 are added to the table are attributed to an entity, and only the 1315 entity that created a particular value can extract that value. 1317 To improve compression performance of this option, certain entries 1318 might be tagged as being public. For example, a web browser might 1319 make the values of the Accept-Encoding header field available in all 1320 requests. 1322 An encoder without good knowledge of the provenance of header fields 1323 might instead introduce a penalty for a header field with many 1324 different values, such that a large number of attempts to guess a 1325 header field value results in the header field not being compared to 1326 the dynamic table entries in future messages, effectively preventing 1327 further guesses. 1329 Note: Simply removing entries corresponding to the header field from 1330 the dynamic table can be ineffectual if the attacker has a 1331 reliable way of causing values to be reinstalled. For example, a 1332 request to load an image in a web browser typically includes the 1333 Cookie header field (a potentially highly valued target for this 1334 sort of attack), and web sites can easily force an image to be 1335 loaded, thereby refreshing the entry in the dynamic table. 1337 This response might be made inversely proportional to the length of 1338 the header field value. Disabling access to the dynamic table for a 1339 header field might occur for shorter values more quickly or with 1340 higher probability than for longer values. 1342 7.4. Never Indexed Literals 1344 Implementations can also choose to protect sensitive header fields by 1345 not compressing them and instead encoding their value as literals. 1347 Refusing to insert a header field into the dynamic table is only 1348 effective if doing so is avoided on all hops. The never indexed 1349 literal bit (see Section 4.5.4) can be used to signal to 1350 intermediaries that a particular value was intentionally sent as a 1351 literal. 1353 An intermediary MUST NOT re-encode a value that uses a literal 1354 representation with the 'N' bit set with another representation that 1355 would index it. If QPACK is used for re-encoding, a literal 1356 representation with the 'N' bit set MUST be used. If HPACK is used 1357 for re-encoding, the never indexed literal representation (see 1358 Section 6.2.3 of [RFC7541]) MUST be used. 1360 The choice to mark that a header field should never be indexed 1361 depends on several factors. Since QPACK doesn't protect against 1362 guessing an entire header field value, short or low-entropy values 1363 are more readily recovered by an adversary. Therefore, an encoder 1364 might choose not to index values with low entropy. 1366 An encoder might also choose not to index values for header fields 1367 that are considered to be highly valuable or sensitive to recovery, 1368 such as the Cookie or Authorization header fields. 1370 On the contrary, an encoder might prefer indexing values for header 1371 fields that have little or no value if they were exposed. For 1372 instance, a User-Agent header field does not commonly vary between 1373 requests and is sent to any server. In that case, confirmation that 1374 a particular User-Agent value has been used provides little value. 1376 Note that these criteria for deciding to use a never indexed literal 1377 representation will evolve over time as new attacks are discovered. 1379 7.5. Static Huffman Encoding 1381 There is no currently known attack against a static Huffman encoding. 1382 A study has shown that using a static Huffman encoding table created 1383 an information leakage, however this same study concluded that an 1384 attacker could not take advantage of this information leakage to 1385 recover any meaningful amount of information (see [PETAL]). 1387 7.6. Memory Consumption 1389 An attacker can try to cause an endpoint to exhaust its memory. 1390 QPACK is designed to limit both the peak and stable amounts of memory 1391 allocated by an endpoint. 1393 The amount of memory used by the encoder is limited by the protocol 1394 using QPACK through the definition of the maximum size of the dynamic 1395 table, and the maximum number of blocking streams. In HTTP/3, these 1396 values are controlled by the decoder through the settings parameters 1397 SETTINGS_QPACK_MAX_TABLE_CAPACITY and SETTINGS_QPACK_BLOCKED_STREAMS, 1398 respectively (see Section 3.2.3 and Section 2.1.2). The limit on the 1399 size of the dynamic table takes into account the size of the data 1400 stored in the dynamic table, plus a small allowance for overhead. 1401 The limit on the number of blocked streams is only a proxy for the 1402 maximum amount of memory required by the decoder. The actual maximum 1403 amount of memory will depend on how much memory the decoder uses to 1404 track each blocked stream. 1406 A decoder can limit the amount of state memory used for the dynamic 1407 table by setting an appropriate value for the maximum size of the 1408 dynamic table. In HTTP/3, this is realized by setting an appropriate 1409 value for the SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter. An 1410 encoder can limit the amount of state memory it uses by signaling a 1411 lower dynamic table size than the decoder allows (see Section 3.2.2). 1413 A decoder can limit the amount of state memory used for blocked 1414 streams by setting an appropriate value for the maximum number of 1415 blocked streams. In HTTP/3, this is realized by setting an 1416 appropriate value for the QPACK_BLOCKED_STREAMS parameter. An 1417 encoder can limit the amount of state memory by only using as many 1418 blocked streams as it wishes to support; no signaling to the decoder 1419 is required. 1421 The amount of temporary memory consumed by an encoder or decoder can 1422 be limited by processing header fields sequentially. A decoder 1423 implementation does not need to retain a complete list of header 1424 fields while decoding a header block. An encoder implementation does 1425 not need to retain a complete list of header fields while encoding a 1426 header block if it is using a single-pass algorithm. Note that it 1427 might be necessary for an application to retain a complete header 1428 list for other reasons; even if QPACK does not force this to occur, 1429 application constraints might make this necessary. 1431 While the negotiated limit on the dynamic table size accounts for 1432 much of the memory that can be consumed by a QPACK implementation, 1433 data which cannot be immediately sent due to flow control is not 1434 affected by this limit. Implementations should limit the size of 1435 unsent data, especially on the decoder stream where flexibility to 1436 choose what to send is limited. Possible responses to an excess of 1437 unsent data might include limiting the ability of the peer to open 1438 new streams, reading only from the encoder stream, or closing the 1439 connection. 1441 7.7. Implementation Limits 1443 An implementation of QPACK needs to ensure that large values for 1444 integers, long encoding for integers, or long string literals do not 1445 create security weaknesses. 1447 An implementation has to set a limit for the values it accepts for 1448 integers, as well as for the encoded length (see Section 4.1.1). In 1449 the same way, it has to set a limit to the length it accepts for 1450 string literals (see Section 4.1.2). 1452 8. IANA Considerations 1454 8.1. Settings Registration 1456 This document specifies two settings. The entries in the following 1457 table are registered in the "HTTP/3 Settings" registry established in 1458 [HTTP3]. 1460 +--------------------------+------+---------------+---------+ 1461 | Setting Name | Code | Specification | Default | 1462 +==========================+======+===============+=========+ 1463 | QPACK_MAX_TABLE_CAPACITY | 0x1 | Section 5 | 0 | 1464 +--------------------------+------+---------------+---------+ 1465 | QPACK_BLOCKED_STREAMS | 0x7 | Section 5 | 0 | 1466 +--------------------------+------+---------------+---------+ 1468 Table 1 1470 8.2. Stream Type Registration 1472 This document specifies two stream types. The entries in the 1473 following table are registered in the "HTTP/3 Stream Type" registry 1474 established in [HTTP3]. 1476 +----------------------+------+---------------+--------+ 1477 | Stream Type | Code | Specification | Sender | 1478 +======================+======+===============+========+ 1479 | QPACK Encoder Stream | 0x02 | Section 4.2 | Both | 1480 +----------------------+------+---------------+--------+ 1481 | QPACK Decoder Stream | 0x03 | Section 4.2 | Both | 1482 +----------------------+------+---------------+--------+ 1484 Table 2 1486 8.3. Error Code Registration 1488 This document specifies three error codes. The entries in the 1489 following table are registered in the "HTTP/3 Error Code" registry 1490 established in [HTTP3]. 1492 +----------------------------+-------+-------------+---------------+ 1493 | Name | Code | Description | Specification | 1494 +============================+=======+=============+===============+ 1495 | QPACK_DECOMPRESSION_FAILED | 0x200 | Decoding of | Section 6 | 1496 | | | a field | | 1497 | | | section | | 1498 | | | failed | | 1499 +----------------------------+-------+-------------+---------------+ 1500 | QPACK_ENCODER_STREAM_ERROR | 0x201 | Error on | Section 6 | 1501 | | | the encoder | | 1502 | | | stream | | 1503 +----------------------------+-------+-------------+---------------+ 1504 | QPACK_DECODER_STREAM_ERROR | 0x202 | Error on | Section 6 | 1505 | | | the decoder | | 1506 | | | stream | | 1507 +----------------------------+-------+-------------+---------------+ 1509 Table 3 1511 9. References 1513 9.1. Normative References 1515 [HTTP3] Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 1516 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 1517 quic-http-29, 9 June 2020, 1518 . 1520 [QUIC-TRANSPORT] 1521 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 1522 Multiplexed and Secure Transport", Work in Progress, 1523 Internet-Draft, draft-ietf-quic-transport-29, 9 June 2020, 1524 . 1527 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1528 Requirement Levels", BCP 14, RFC 2119, 1529 DOI 10.17487/RFC2119, March 1997, 1530 . 1532 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 1533 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 1534 . 1536 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1537 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1538 May 2017, . 1540 [SEMANTICS] 1541 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 1542 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1543 httpbis-semantics-08, 26 May 2020, . 1546 9.2. Informative References 1548 [CRIME] Wikipedia, "CRIME", May 2015, . 1551 [PETAL] Tan, J. and J. Nahata, "PETAL: Preset Encoding 1552 Table Information Leakage", April 2013, 1553 . 1556 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1557 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 1558 . 1560 [RFC2360] Scott, G., "Guide for Internet Standards Writers", BCP 22, 1561 RFC 2360, DOI 10.17487/RFC2360, June 1998, 1562 . 1564 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1565 (TLS) Protocol Version 1.2", RFC 5246, 1566 DOI 10.17487/RFC5246, August 2008, 1567 . 1569 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1570 DOI 10.17487/RFC6454, December 2011, 1571 . 1573 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1574 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1575 DOI 10.17487/RFC7540, May 2015, 1576 . 1578 Appendix A. Static Table 1580 This table was generated by analyzing actual internet traffic in 2018 1581 and including the most common headers, after filtering out some 1582 unsupported and non-standard values. Due to this methodology, some 1583 of the entries may be inconsistent or appear multiple times with 1584 similar but not identical values. The order of the entries is 1585 optimized to encode the most common headers with the smallest number 1586 of bytes. 1588 +-------+----------------------------------+-----------------------+ 1589 | Index | Name | Value | 1590 +=======+==================================+=======================+ 1591 | 0 | :authority | | 1592 +-------+----------------------------------+-----------------------+ 1593 | 1 | :path | / | 1594 +-------+----------------------------------+-----------------------+ 1595 | 2 | age | 0 | 1596 +-------+----------------------------------+-----------------------+ 1597 | 3 | content-disposition | | 1598 +-------+----------------------------------+-----------------------+ 1599 | 4 | content-length | 0 | 1600 +-------+----------------------------------+-----------------------+ 1601 | 5 | cookie | | 1602 +-------+----------------------------------+-----------------------+ 1603 | 6 | date | | 1604 +-------+----------------------------------+-----------------------+ 1605 | 7 | etag | | 1606 +-------+----------------------------------+-----------------------+ 1607 | 8 | if-modified-since | | 1608 +-------+----------------------------------+-----------------------+ 1609 | 9 | if-none-match | | 1610 +-------+----------------------------------+-----------------------+ 1611 | 10 | last-modified | | 1612 +-------+----------------------------------+-----------------------+ 1613 | 11 | link | | 1614 +-------+----------------------------------+-----------------------+ 1615 | 12 | location | | 1616 +-------+----------------------------------+-----------------------+ 1617 | 13 | referer | | 1618 +-------+----------------------------------+-----------------------+ 1619 | 14 | set-cookie | | 1620 +-------+----------------------------------+-----------------------+ 1621 | 15 | :method | CONNECT | 1622 +-------+----------------------------------+-----------------------+ 1623 | 16 | :method | DELETE | 1624 +-------+----------------------------------+-----------------------+ 1625 | 17 | :method | GET | 1626 +-------+----------------------------------+-----------------------+ 1627 | 18 | :method | HEAD | 1628 +-------+----------------------------------+-----------------------+ 1629 | 19 | :method | OPTIONS | 1630 +-------+----------------------------------+-----------------------+ 1631 | 20 | :method | POST | 1632 +-------+----------------------------------+-----------------------+ 1633 | 21 | :method | PUT | 1634 +-------+----------------------------------+-----------------------+ 1635 | 22 | :scheme | http | 1636 +-------+----------------------------------+-----------------------+ 1637 | 23 | :scheme | https | 1638 +-------+----------------------------------+-----------------------+ 1639 | 24 | :status | 103 | 1640 +-------+----------------------------------+-----------------------+ 1641 | 25 | :status | 200 | 1642 +-------+----------------------------------+-----------------------+ 1643 | 26 | :status | 304 | 1644 +-------+----------------------------------+-----------------------+ 1645 | 27 | :status | 404 | 1646 +-------+----------------------------------+-----------------------+ 1647 | 28 | :status | 503 | 1648 +-------+----------------------------------+-----------------------+ 1649 | 29 | accept | */* | 1650 +-------+----------------------------------+-----------------------+ 1651 | 30 | accept | application/dns- | 1652 | | | message | 1653 +-------+----------------------------------+-----------------------+ 1654 | 31 | accept-encoding | gzip, deflate, br | 1655 +-------+----------------------------------+-----------------------+ 1656 | 32 | accept-ranges | bytes | 1657 +-------+----------------------------------+-----------------------+ 1658 | 33 | access-control-allow-headers | cache-control | 1659 +-------+----------------------------------+-----------------------+ 1660 | 34 | access-control-allow-headers | content-type | 1661 +-------+----------------------------------+-----------------------+ 1662 | 35 | access-control-allow-origin | * | 1663 +-------+----------------------------------+-----------------------+ 1664 | 36 | cache-control | max-age=0 | 1665 +-------+----------------------------------+-----------------------+ 1666 | 37 | cache-control | max-age=2592000 | 1667 +-------+----------------------------------+-----------------------+ 1668 | 38 | cache-control | max-age=604800 | 1669 +-------+----------------------------------+-----------------------+ 1670 | 39 | cache-control | no-cache | 1671 +-------+----------------------------------+-----------------------+ 1672 | 40 | cache-control | no-store | 1673 +-------+----------------------------------+-----------------------+ 1674 | 41 | cache-control | public, max- | 1675 | | | age=31536000 | 1676 +-------+----------------------------------+-----------------------+ 1677 | 42 | content-encoding | br | 1678 +-------+----------------------------------+-----------------------+ 1679 | 43 | content-encoding | gzip | 1680 +-------+----------------------------------+-----------------------+ 1681 | 44 | content-type | application/dns- | 1682 | | | message | 1683 +-------+----------------------------------+-----------------------+ 1684 | 45 | content-type | application/ | 1685 | | | javascript | 1686 +-------+----------------------------------+-----------------------+ 1687 | 46 | content-type | application/json | 1688 +-------+----------------------------------+-----------------------+ 1689 | 47 | content-type | application/x-www- | 1690 | | | form-urlencoded | 1691 +-------+----------------------------------+-----------------------+ 1692 | 48 | content-type | image/gif | 1693 +-------+----------------------------------+-----------------------+ 1694 | 49 | content-type | image/jpeg | 1695 +-------+----------------------------------+-----------------------+ 1696 | 50 | content-type | image/png | 1697 +-------+----------------------------------+-----------------------+ 1698 | 51 | content-type | text/css | 1699 +-------+----------------------------------+-----------------------+ 1700 | 52 | content-type | text/html; | 1701 | | | charset=utf-8 | 1702 +-------+----------------------------------+-----------------------+ 1703 | 53 | content-type | text/plain | 1704 +-------+----------------------------------+-----------------------+ 1705 | 54 | content-type | text/ | 1706 | | | plain;charset=utf-8 | 1707 +-------+----------------------------------+-----------------------+ 1708 | 55 | range | bytes=0- | 1709 +-------+----------------------------------+-----------------------+ 1710 | 56 | strict-transport-security | max-age=31536000 | 1711 +-------+----------------------------------+-----------------------+ 1712 | 57 | strict-transport-security | max-age=31536000; | 1713 | | | includesubdomains | 1714 +-------+----------------------------------+-----------------------+ 1715 | 58 | strict-transport-security | max-age=31536000; | 1716 | | | includesubdomains; | 1717 | | | preload | 1718 +-------+----------------------------------+-----------------------+ 1719 | 59 | vary | accept-encoding | 1720 +-------+----------------------------------+-----------------------+ 1721 | 60 | vary | origin | 1722 +-------+----------------------------------+-----------------------+ 1723 | 61 | x-content-type-options | nosniff | 1724 +-------+----------------------------------+-----------------------+ 1725 | 62 | x-xss-protection | 1; mode=block | 1726 +-------+----------------------------------+-----------------------+ 1727 | 63 | :status | 100 | 1728 +-------+----------------------------------+-----------------------+ 1729 | 64 | :status | 204 | 1730 +-------+----------------------------------+-----------------------+ 1731 | 65 | :status | 206 | 1732 +-------+----------------------------------+-----------------------+ 1733 | 66 | :status | 302 | 1734 +-------+----------------------------------+-----------------------+ 1735 | 67 | :status | 400 | 1736 +-------+----------------------------------+-----------------------+ 1737 | 68 | :status | 403 | 1738 +-------+----------------------------------+-----------------------+ 1739 | 69 | :status | 421 | 1740 +-------+----------------------------------+-----------------------+ 1741 | 70 | :status | 425 | 1742 +-------+----------------------------------+-----------------------+ 1743 | 71 | :status | 500 | 1744 +-------+----------------------------------+-----------------------+ 1745 | 72 | accept-language | | 1746 +-------+----------------------------------+-----------------------+ 1747 | 73 | access-control-allow-credentials | FALSE | 1748 +-------+----------------------------------+-----------------------+ 1749 | 74 | access-control-allow-credentials | TRUE | 1750 +-------+----------------------------------+-----------------------+ 1751 | 75 | access-control-allow-headers | * | 1752 +-------+----------------------------------+-----------------------+ 1753 | 76 | access-control-allow-methods | get | 1754 +-------+----------------------------------+-----------------------+ 1755 | 77 | access-control-allow-methods | get, post, options | 1756 +-------+----------------------------------+-----------------------+ 1757 | 78 | access-control-allow-methods | options | 1758 +-------+----------------------------------+-----------------------+ 1759 | 79 | access-control-expose-headers | content-length | 1760 +-------+----------------------------------+-----------------------+ 1761 | 80 | access-control-request-headers | content-type | 1762 +-------+----------------------------------+-----------------------+ 1763 | 81 | access-control-request-method | get | 1764 +-------+----------------------------------+-----------------------+ 1765 | 82 | access-control-request-method | post | 1766 +-------+----------------------------------+-----------------------+ 1767 | 83 | alt-svc | clear | 1768 +-------+----------------------------------+-----------------------+ 1769 | 84 | authorization | | 1770 +-------+----------------------------------+-----------------------+ 1771 | 85 | content-security-policy | script-src 'none'; | 1772 | | | object-src 'none'; | 1773 | | | base-uri 'none' | 1774 +-------+----------------------------------+-----------------------+ 1775 | 86 | early-data | 1 | 1776 +-------+----------------------------------+-----------------------+ 1777 | 87 | expect-ct | | 1778 +-------+----------------------------------+-----------------------+ 1779 | 88 | forwarded | | 1780 +-------+----------------------------------+-----------------------+ 1781 | 89 | if-range | | 1782 +-------+----------------------------------+-----------------------+ 1783 | 90 | origin | | 1784 +-------+----------------------------------+-----------------------+ 1785 | 91 | purpose | prefetch | 1786 +-------+----------------------------------+-----------------------+ 1787 | 92 | server | | 1788 +-------+----------------------------------+-----------------------+ 1789 | 93 | timing-allow-origin | * | 1790 +-------+----------------------------------+-----------------------+ 1791 | 94 | upgrade-insecure-requests | 1 | 1792 +-------+----------------------------------+-----------------------+ 1793 | 95 | user-agent | | 1794 +-------+----------------------------------+-----------------------+ 1795 | 96 | x-forwarded-for | | 1796 +-------+----------------------------------+-----------------------+ 1797 | 97 | x-frame-options | deny | 1798 +-------+----------------------------------+-----------------------+ 1799 | 98 | x-frame-options | sameorigin | 1800 +-------+----------------------------------+-----------------------+ 1802 Table 4 1804 Appendix B. Sample One Pass Encoding Algorithm 1806 Pseudo-code for single pass encoding, excluding handling of 1807 duplicates, non-blocking mode, available encoder stream flow control 1808 and reference tracking. 1810 base = dynamicTable.getInsertCount() 1811 requiredInsertCount = 0 1812 for line in field_lines: 1813 staticIndex = staticTable.findIndex(line) 1814 if staticIndex is not None: 1815 encodeIndexReference(streamBuffer, staticIndex) 1816 continue 1818 dynamicIndex = dynamicTable.findIndex(line) 1819 if dynamicIndex is None: 1820 # No matching entry. Either insert+index or encode literal 1821 staticNameIndex = staticTable.findName(line.name) 1822 if staticNameIndex is None: 1823 dynamicNameIndex = dynamicTable.findName(line.name) 1825 if shouldIndex(line) and dynamicTable.canIndex(line): 1826 encodeInsert(encoderBuffer, staticNameIndex, 1827 dynamicNameIndex, line) 1829 dynamicIndex = dynamicTable.add(line) 1831 if dynamicIndex is None: 1832 # Couldn't index it, literal 1833 if nameIndex is None or isStaticName: 1834 # Encodes a literal with a static name or literal name 1835 encodeLiteral(streamBuffer, nameIndex, line) 1836 else: 1837 # encode literal with dynamic name, possibly above base 1838 encodeDynamicLiteral(streamBuffer, nameIndex, base, line) 1839 requiredInsertCount = max(requiredInsertCount, nameIndex) 1840 else: 1841 # Dynamic index reference 1842 assert(dynamicIndex is not None) 1843 requiredInsertCount = max(requiredInsertCount, dynamicIndex) 1844 # Encode dynamicIndex, possibly above base 1845 encodeDynamicIndexReference(streamBuffer, dynamicIndex, base) 1847 # encode the prefix 1848 if requiredInsertCount == 0: 1849 encodeIndexReference(prefixBuffer, 0, 0, 8) 1850 encodeIndexReference(prefixBuffer, 0, 0, 7) 1851 else: 1852 wireRIC = ( 1853 requiredInsertCount 1854 % (2 * getMaxEntries(maxTableCapacity)) 1855 ) + 1; 1856 encodeInteger(prefixBuffer, 0x00, wireRIC, 8) 1857 if base >= requiredInsertCount: 1858 encodeInteger(prefixBuffer, 0, base - requiredInsertCount, 7) 1859 else: 1860 encodeInteger(prefixBuffer, 0x80, 1861 requiredInsertCount - base - 1, 7) 1863 return encoderBuffer, prefixBuffer + streamBuffer 1865 Appendix C. Change Log 1867 *RFC Editor's Note:* Please remove this section prior to 1868 publication of a final version of this document. 1870 C.1. Since draft-ietf-quic-qpack-15 1872 No changes 1874 C.2. Since draft-ietf-quic-qpack-14 1876 Added security considerations 1878 C.3. Since draft-ietf-quic-qpack-13 1880 No changes 1882 C.4. Since draft-ietf-quic-qpack-12 1884 Editorial changes only 1886 C.5. Since draft-ietf-quic-qpack-11 1888 Editorial changes only 1890 C.6. Since draft-ietf-quic-qpack-10 1892 Editorial changes only 1894 C.7. Since draft-ietf-quic-qpack-09 1896 * Decoders MUST emit Header Acknowledgements (#2939) 1898 * Updated error code for multiple encoder or decoder streams (#2970) 1900 * Added explicit defaults for new SETTINGS (#2974) 1902 C.8. Since draft-ietf-quic-qpack-08 1904 * Endpoints are permitted to create encoder and decoder streams even 1905 if they can't use them (#2100, #2529) 1907 * Maximum values for settings removed (#2766, #2767) 1909 C.9. Since draft-ietf-quic-qpack-06 1911 * Clarify initial dynamic table capacity maximums (#2276, #2330, 1912 #2330) 1914 C.10. Since draft-ietf-quic-qpack-05 1916 * Introduced the terms dynamic table capacity and maximum dynamic 1917 table capacity. 1919 * Renamed SETTINGS_HEADER_TABLE_SIZE to 1920 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 1922 C.11. Since draft-ietf-quic-qpack-04 1924 * Changed calculation of Delta Base Index to avoid an illegal value 1925 (#2002, #2005) 1927 C.12. Since draft-ietf-quic-qpack-03 1929 * Change HTTP settings defaults (#2038) 1931 * Substantial editorial reorganization 1933 C.13. Since draft-ietf-quic-qpack-02 1935 * Largest Reference encoded modulo MaxEntries (#1763) 1937 * New Static Table (#1355) 1939 * Table Size Update with Insert Count=0 is a connection error 1940 (#1762) 1942 * Stream Cancellations are optional when 1943 SETTINGS_HEADER_TABLE_SIZE=0 (#1761) 1945 * Implementations must handle 62 bit integers (#1760) 1947 * Different error types for each QPACK stream, other changes to 1948 error handling (#1726) 1950 * Preserve header field order (#1725) 1952 * Initial table size is the maximum permitted when table is first 1953 usable (#1642) 1955 C.14. Since draft-ietf-quic-qpack-01 1957 * Only header blocks that reference the dynamic table are 1958 acknowledged (#1603, #1605) 1960 C.15. Since draft-ietf-quic-qpack-00 1962 * Renumbered instructions for consistency (#1471, #1472) 1964 * Decoder is allowed to validate largest reference (#1404, #1469) 1966 * Header block acknowledgments also acknowledge the associated 1967 largest reference (#1370, #1400) 1969 * Added an acknowledgment for unread streams (#1371, #1400) 1970 * Removed framing from encoder stream (#1361,#1467) 1972 * Control streams use typed unidirectional streams rather than fixed 1973 stream IDs (#910,#1359) 1975 C.16. Since draft-ietf-quic-qcram-00 1977 * Separate instruction sets for table updates and header blocks 1978 (#1235, #1142, #1141) 1980 * Reworked indexing scheme (#1176, #1145, #1136, #1130, #1125, 1981 #1314) 1983 * Added mechanisms that support one-pass encoding (#1138, #1320) 1985 * Added a setting to control the number of blocked decoders (#238, 1986 #1140, #1143) 1988 * Moved table updates and acknowledgments to dedicated streams 1989 (#1121, #1122, #1238) 1991 Acknowledgments 1993 The IETF QUIC Working Group received an enormous amount of support 1994 from many people. 1996 The compression design team did substantial work exploring the 1997 problem space and influencing the initial draft. The contributions 1998 of design team members Roberto Peon, Martin Thomson, and Dmitri 1999 Tikhonov are gratefully acknowledged. 2001 The following people also provided substantial contributions to this 2002 document: 2004 * Bence Beky 2006 * Alessandro Ghedini 2008 * Ryan Hamilton 2010 * Robin Marx 2012 * Patrick McManus 2014 * 奥 一穂 (Kazuho Oku) 2016 * Lucas Pardue 2017 * Biren Roy 2019 * Ian Swett 2021 This draft draws heavily on the text of [RFC7541]. The indirect 2022 input of those authors is also gratefully acknowledged. 2024 Buck's contribution was supported by Google during his employment 2025 there. 2027 A portion of Mike's contribution was supported by Microsoft during 2028 his employment there. 2030 Authors' Addresses 2032 Charles 'Buck' Krasic 2033 Netflix 2035 Email: ckrasic@netflix.com 2037 Mike Bishop 2038 Akamai Technologies 2040 Email: mbishop@evequefou.be 2042 Alan Frindell (editor) 2043 Facebook 2045 Email: afrind@fb.com