idnits 2.17.1 draft-ietf-quic-qpack-19.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 == Line 1869 has weird spacing: '...thority www.e...' == Line 1884 has weird spacing: '...thority www.e...' == Line 1892 has weird spacing: '...thority www.e...' == Line 1909 has weird spacing: '...thority www.e...' == Line 1912 has weird spacing: '...tom-key custo...' == (14 more instances...) -- The document date (20 October 2020) is 1283 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-32 == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-32 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-12 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 0 errors (**), 0 flaws (~~), 11 warnings (==), 4 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: 23 April 2021 Akamai Technologies 6 A. Frindell, Ed. 7 Facebook 8 20 October 2020 10 QPACK: Header Compression for HTTP/3 11 draft-ietf-quic-qpack-19 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 23 April 2021. 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 . . . . . . . . . . . . . 18 94 4.3.3. Insert With Literal Name . . . . . . . . . . . . . . 18 95 4.3.4. Duplicate . . . . . . . . . . . . . . . . . . . . . . 19 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 With Literal Name . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . 32 119 8.1. Settings Registration . . . . . . . . . . . . . . . . . . 32 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. Encoding and Decoding Examples . . . . . . . . . . . 39 127 B.1. Literal Field Line With Name Reference . . . . . . . . . 39 128 B.2. Dynamic Table . . . . . . . . . . . . . . . . . . . . . . 40 129 B.3. Speculative Insert . . . . . . . . . . . . . . . . . . . 41 130 B.4. Duplicate Instruction, Stream Cancellation . . . . . . . 42 131 B.5. Dynamic Table Insert, Eviction . . . . . . . . . . . . . 43 132 Appendix C. Sample One Pass Encoding Algorithm . . . . . . . . . 44 133 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 45 134 D.1. Since draft-ietf-quic-qpack-18 . . . . . . . . . . . . . 45 135 D.2. Since draft-ietf-quic-qpack-17 . . . . . . . . . . . . . 45 136 D.3. Since draft-ietf-quic-qpack-16 . . . . . . . . . . . . . 45 137 D.4. Since draft-ietf-quic-qpack-15 . . . . . . . . . . . . . 45 138 D.5. Since draft-ietf-quic-qpack-14 . . . . . . . . . . . . . 46 139 D.6. Since draft-ietf-quic-qpack-13 . . . . . . . . . . . . . 46 140 D.7. Since draft-ietf-quic-qpack-12 . . . . . . . . . . . . . 46 141 D.8. Since draft-ietf-quic-qpack-11 . . . . . . . . . . . . . 46 142 D.9. Since draft-ietf-quic-qpack-10 . . . . . . . . . . . . . 46 143 D.10. Since draft-ietf-quic-qpack-09 . . . . . . . . . . . . . 46 144 D.11. Since draft-ietf-quic-qpack-08 . . . . . . . . . . . . . 46 145 D.12. Since draft-ietf-quic-qpack-06 . . . . . . . . . . . . . 46 146 D.13. Since draft-ietf-quic-qpack-05 . . . . . . . . . . . . . 46 147 D.14. Since draft-ietf-quic-qpack-04 . . . . . . . . . . . . . 47 148 D.15. Since draft-ietf-quic-qpack-03 . . . . . . . . . . . . . 47 149 D.16. Since draft-ietf-quic-qpack-02 . . . . . . . . . . . . . 47 150 D.17. Since draft-ietf-quic-qpack-01 . . . . . . . . . . . . . 47 151 D.18. Since draft-ietf-quic-qpack-00 . . . . . . . . . . . . . 47 152 D.19. Since draft-ietf-quic-qcram-00 . . . . . . . . . . . . . 48 153 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 48 154 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49 156 1. Introduction 158 The QUIC transport protocol ([QUIC-TRANSPORT]) is designed to support 159 HTTP semantics, and its design subsumes many of the features of 160 HTTP/2 ([RFC7540]). HTTP/2 uses HPACK ([RFC7541]) for compression of 161 the header and trailer sections. If HPACK were used for HTTP/3 162 ([HTTP3]), it would induce head-of-line blocking for field sections 163 due to built-in assumptions of a total ordering across frames on all 164 streams. 166 QPACK reuses core concepts from HPACK, but is redesigned to allow 167 correctness in the presence of out-of-order delivery, with 168 flexibility for implementations to balance between resilience against 169 head-of-line blocking and optimal compression ratio. The design 170 goals are to closely approach the compression ratio of HPACK with 171 substantially less head-of-line blocking under the same loss 172 conditions. 174 1.1. Conventions and Definitions 176 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 177 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 178 "OPTIONAL" in this document are to be interpreted as described in 179 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 180 capitals, as shown here. 182 Definitions of terms that are used in this document: 184 HTTP fields: Metadata sent as part of an HTTP message. The term 185 encompasses both header and trailer fields. Colloquially, the 186 term "headers" has often been used to refer to HTTP header fields 187 and trailer fields; this document uses "fields" for generality. 189 HTTP field line: A name-value pair sent as part of an HTTP field 190 section. See Section 5.4 and Section 5.6 of [SEMANTICS]. 192 HTTP field value: Data associated with a field name, composed from 193 all field line values with that field name in that section, 194 concatenated together and separated with commas. 196 Field section: An ordered collection of HTTP field lines associated 197 with an HTTP message. A field section can contain multiple field 198 lines with the same name. It can also contain duplicate field 199 lines. An HTTP message can include both header field and trailer 200 field sections. 202 Representation: An instruction that represents a field line, 203 possibly by reference to the dynamic and static tables. 205 Encoder: An implementation that encodes field sections. 207 Decoder: An implementation that decodes encoded field sections. 209 Absolute Index: A unique index for each entry in the dynamic table. 211 Base: A reference point for relative and post-base indices. 212 Representations that reference dynamic table entries are relative 213 to a Base. 215 Insert Count: The total number of entries inserted in the dynamic 216 table. 218 QPACK is a name, not an acronym. 220 1.2. Notational Conventions 222 Diagrams use the format described in Section 3.1 of [RFC2360], with 223 the following additional conventions: 225 x (A) Indicates that x is A bits long 227 x (A+) Indicates that x uses the prefixed integer encoding defined 228 in Section 4.1.1, beginning with an A-bit prefix. 230 x ... Indicates that x is variable-length and extends to the end of 231 the region. 233 2. Compression Process Overview 235 Like HPACK, QPACK uses two tables for associating field lines 236 ("headers") to indices. The static table (Section 3.1) is predefined 237 and contains common header field lines (some of them with an empty 238 value). The dynamic table (Section 3.2) is built up over the course 239 of the connection and can be used by the encoder to index both header 240 and trailer field lines in the encoded field sections. 242 QPACK defines unidirectional streams for sending instructions from 243 encoder to decoder and vice versa. 245 2.1. Encoder 247 An encoder converts a header or trailer field section into a series 248 of representations by emitting either an indexed or a literal 249 representation for each field line in the list; see Section 4.5. 250 Indexed representations achieve high compression by replacing the 251 literal name and possibly the value with an index to either the 252 static or dynamic table. References to the static table and literal 253 representations do not require any dynamic state and never risk head- 254 of-line blocking. References to the dynamic table risk head-of-line 255 blocking if the encoder has not received an acknowledgement 256 indicating the entry is available at the decoder. 258 An encoder MAY insert any entry in the dynamic table it chooses; it 259 is not limited to field lines it is compressing. 261 QPACK preserves the ordering of field lines within each field 262 section. An encoder MUST emit field representations in the order 263 they appear in the input field section. 265 QPACK is designed to contain the more complex state tracking to the 266 encoder, while the decoder is relatively simple. 268 2.1.1. Limits on Dynamic Table Insertions 270 Inserting entries into the dynamic table might not be possible if the 271 table contains entries that cannot be evicted. 273 A dynamic table entry cannot be evicted immediately after insertion, 274 even if it has never been referenced. Once the insertion of a 275 dynamic table entry has been acknowledged and there are no 276 outstanding references to the entry in unacknowledged 277 representations, the entry becomes evictable. Note that references 278 on the encoder stream never preclude the eviction of an entry, 279 because those references are guaranteed to be processed before the 280 instruction evicting the entry. 282 If the dynamic table does not contain enough room for a new entry 283 without evicting other entries, and the entries that would be evicted 284 are not evictable, the encoder MUST NOT insert that entry into the 285 dynamic table (including duplicates of existing entries). In order 286 to avoid this, an encoder that uses the dynamic table has to keep 287 track of each dynamic table entry referenced by each field section 288 until those representations are acknowledged by the decoder; see 289 Section 4.4.1. 291 2.1.1.1. Avoiding Prohibited Insertions 293 To ensure that the encoder is not prevented from adding new entries, 294 the encoder can avoid referencing entries that are close to eviction. 295 Rather than reference such an entry, the encoder can emit a Duplicate 296 instruction (Section 4.3.4), and reference the duplicate instead. 298 Determining which entries are too close to eviction to reference is 299 an encoder preference. One heuristic is to target a fixed amount of 300 available space in the dynamic table: either unused space or space 301 that can be reclaimed by evicting non-blocking entries. To achieve 302 this, the encoder can maintain a draining index, which is the 303 smallest absolute index (Section 3.2.4) in the dynamic table that it 304 will emit a reference for. As new entries are inserted, the encoder 305 increases the draining index to maintain the section of the table 306 that it will not reference. If the encoder does not create new 307 references to entries with an absolute index lower than the draining 308 index, the number of unacknowledged references to those entries will 309 eventually become zero, allowing them to be evicted. 311 +--------+---------------------------------+----------+ 312 | Unused | Referenceable | Draining | 313 | Space | Entries | Entries | 314 +--------+---------------------------------+----------+ 315 ^ ^ ^ 316 | | | 317 Insertion Point Draining Index Dropping 318 Point 320 Figure 1: Draining Dynamic Table Entries 322 2.1.2. Blocked Streams 324 Because QUIC does not guarantee order between data on different 325 streams, a decoder might encounter a representation that references a 326 dynamic table entry that it has not yet received. 328 Each encoded field section contains a Required Insert Count 329 (Section 4.5.1), the lowest possible value for the Insert Count with 330 which the field section can be decoded. For a field section encoded 331 using references to the dynamic table, the Required Insert Count is 332 one larger than the largest absolute index of all referenced dynamic 333 table entries. For a field section encoded with no references to the 334 dynamic table, the Required Insert Count is zero. 336 When the decoder receives an encoded field section with a Required 337 Insert Count greater than its own Insert Count, the stream cannot be 338 processed immediately, and is considered "blocked"; see 339 Section 2.2.1. 341 The decoder specifies an upper bound on the number of streams that 342 can be blocked using the SETTINGS_QPACK_BLOCKED_STREAMS setting; see 343 Section 5. An encoder MUST limit the number of streams that could 344 become blocked to the value of SETTINGS_QPACK_BLOCKED_STREAMS at all 345 times. If a decoder encounters more blocked streams than it promised 346 to support, it MUST treat this as a connection error of type 347 QPACK_DECOMPRESSION_FAILED. 349 Note that the decoder might not become blocked on every stream that 350 risks becoming blocked. 352 An encoder can decide whether to risk having a stream become blocked. 353 If permitted by the value of SETTINGS_QPACK_BLOCKED_STREAMS, 354 compression efficiency can often be improved by referencing dynamic 355 table entries that are still in transit, but if there is loss or 356 reordering the stream can become blocked at the decoder. An encoder 357 can avoid the risk of blocking by only referencing dynamic table 358 entries that have been acknowledged, but this could mean using 359 literals. Since literals make the encoded field section larger, this 360 can result in the encoder becoming blocked on congestion or flow 361 control limits. 363 2.1.3. Avoiding Flow Control Deadlocks 365 Writing instructions on streams that are limited by flow control can 366 produce deadlocks. 368 A decoder might stop issuing flow control credit on the stream that 369 carries an encoded field section until the necessary updates are 370 received on the encoder stream. If the granting of flow control 371 credit on the encoder stream (or the connection as a whole) depends 372 on the consumption and release of data on the stream carrying the 373 encoded field section, a deadlock might result. 375 More generally, a stream containing a large instruction can become 376 deadlocked if the decoder withholds flow control credit until the 377 instruction is completely received. 379 To avoid these deadlocks, an encoder SHOULD avoid writing an 380 instruction unless sufficient stream and connection flow control 381 credit is available for the entire instruction. 383 2.1.4. Known Received Count 385 The Known Received Count is the total number of dynamic table 386 insertions and duplications acknowledged by the decoder. The encoder 387 tracks the Known Received Count in order to identify which dynamic 388 table entries can be referenced without potentially blocking a 389 stream. The decoder tracks the Known Received Count in order to be 390 able to send Insert Count Increment instructions. 392 A Section Acknowledgement instruction (Section 4.4.1) implies that 393 the decoder has received all dynamic table state necessary to decode 394 the field section. If the Required Insert Count of the acknowledged 395 field section is greater than the current Known Received Count, Known 396 Received Count is updated to the value of the Required Insert Count. 398 An Insert Count Increment instruction (Section 4.4.3) increases the 399 Known Received Count by its Increment parameter. See Section 2.2.2.3 400 for guidance. 402 2.2. Decoder 404 As in HPACK, the decoder processes a series of representations and 405 emits the corresponding field sections. It also processes 406 instructions received on the encoder stream that modify the dynamic 407 table. Note that encoded field sections and encoder stream 408 instructions arrive on separate streams. This is unlike HPACK, where 409 encoded field sections (header blocks) can contain instructions that 410 modify the dynamic table, and there is no dedicated stream of HPACK 411 instructions. 413 The decoder MUST emit field lines in the order their representations 414 appear in the encoded field section. 416 2.2.1. Blocked Decoding 418 Upon receipt of an encoded field section, the decoder examines the 419 Required Insert Count. When the Required Insert Count is less than 420 or equal to the decoder's Insert Count, the field section can be 421 processed immediately. Otherwise, the stream on which the field 422 section was received becomes blocked. 424 While blocked, encoded field section data SHOULD remain in the 425 blocked stream's flow control window. A stream becomes unblocked 426 when the Insert Count becomes greater than or equal to the Required 427 Insert Count for all encoded field sections the decoder has started 428 reading from the stream. 430 When processing encoded field sections, the decoder expects the 431 Required Insert Count to equal the lowest possible value for the 432 Insert Count with which the field section can be decoded, as 433 prescribed in Section 2.1.2. If it encounters a Required Insert 434 Count smaller than expected, it MUST treat this as a connection error 435 of type QPACK_DECOMPRESSION_FAILED; see Section 2.2.3. If it 436 encounters a Required Insert Count larger than expected, it MAY treat 437 this as a connection error of type QPACK_DECOMPRESSION_FAILED. 439 2.2.2. State Synchronization 441 The decoder signals the following events by emitting decoder 442 instructions (Section 4.4) on the decoder stream. 444 2.2.2.1. Completed Processing of a Field Section 446 After the decoder finishes decoding a field section encoded using 447 representations containing dynamic table references, it MUST emit a 448 Section Acknowledgement instruction (Section 4.4.1). A stream may 449 carry multiple field sections in the case of intermediate responses, 450 trailers, and pushed requests. The encoder interprets each 451 Section Acknowledgement instruction as acknowledging the earliest 452 unacknowledged field section containing dynamic table references sent 453 on the given stream. 455 2.2.2.2. Abandonment of a Stream 457 When an endpoint receives a stream reset before the end of a stream 458 or before all encoded field sections are processed on that stream, or 459 when it abandons reading of a stream, it generates a Stream 460 Cancellation instruction; see Section 4.4.2. This signals to the 461 encoder that all references to the dynamic table on that stream are 462 no longer outstanding. A decoder with a maximum dynamic table 463 capacity (Section 3.2.3) equal to zero MAY omit sending Stream 464 Cancellations, because the encoder cannot have any dynamic table 465 references. An encoder cannot infer from this instruction that any 466 updates to the dynamic table have been received. 468 The Section Acknowledgement and Stream Cancellation instructions 469 permit the encoder to remove references to entries in the dynamic 470 table. When an entry with absolute index lower than the Known 471 Received Count has zero references, then it is considered evictable; 472 see Section 2.1.1. 474 2.2.2.3. New Table Entries 476 After receiving new table entries on the encoder stream, the decoder 477 chooses when to emit Insert Count Increment instructions; see 478 Section 4.4.3. Emitting this instruction after adding each new 479 dynamic table entry will provide the timeliest feedback to the 480 encoder, but could be redundant with other decoder feedback. By 481 delaying an Insert Count Increment instruction, the decoder might be 482 able to coalesce multiple Insert Count Increment instructions, or 483 replace them entirely with Section Acknowledgements; see 484 Section 4.4.1. However, delaying too long may lead to compression 485 inefficiencies if the encoder waits for an entry to be acknowledged 486 before using it. 488 2.2.3. Invalid References 490 If the decoder encounters a reference in a field line representation 491 to a dynamic table entry that has already been evicted or that has an 492 absolute index greater than or equal to the declared Required Insert 493 Count (Section 4.5.1), it MUST treat this as a connection error of 494 type QPACK_DECOMPRESSION_FAILED. 496 If the decoder encounters a reference in an encoder instruction to a 497 dynamic table entry that has already been evicted, it MUST treat this 498 as a connection error of type QPACK_ENCODER_STREAM_ERROR. 500 3. Reference Tables 502 Unlike in HPACK, entries in the QPACK static and dynamic tables are 503 addressed separately. The following sections describe how entries in 504 each table are addressed. 506 3.1. Static Table 508 The static table consists of a predefined list of field lines, each 509 of which has a fixed index over time. Its entries are defined in 510 Appendix A. 512 All entries in the static table have a name and a value. However, 513 values can be empty (that is, have a length of 0). Each entry is 514 identified by a unique index. 516 Note that the QPACK static table is indexed from 0, whereas the HPACK 517 static table is indexed from 1. 519 When the decoder encounters an invalid static table index in a field 520 line representation it MUST treat this as a connection error of type 521 QPACK_DECOMPRESSION_FAILED. If this index is received on the encoder 522 stream, this MUST be treated as a connection error of type 523 QPACK_ENCODER_STREAM_ERROR. 525 3.2. Dynamic Table 527 The dynamic table consists of a list of field lines maintained in 528 first-in, first-out order. Each HTTP/3 endpoint holds a dynamic 529 table that is initially empty. Entries are added by encoder 530 instructions received on the encoder stream; see Section 4.3. 532 The dynamic table can contain duplicate entries (i.e., entries with 533 the same name and same value). Therefore, duplicate entries MUST NOT 534 be treated as an error by the decoder. 536 Dynamic table entries can have empty values. 538 3.2.1. Dynamic Table Size 540 The size of the dynamic table is the sum of the size of its entries. 542 The size of an entry is the sum of its name's length in bytes, its 543 value's length in bytes, and 32. The size of an entry is calculated 544 using the length of its name and value without Huffman encoding 545 applied. 547 3.2.2. Dynamic Table Capacity and Eviction 549 The encoder sets the capacity of the dynamic table, which serves as 550 the upper limit on its size. The initial capacity of the dynamic 551 table is zero. The encoder sends a Set Dynamic Table Capacity 552 instruction (Section 4.3.1) with a non-zero capacity to begin using 553 the dynamic table. 555 Before a new entry is added to the dynamic table, entries are evicted 556 from the end of the dynamic table until the size of the dynamic table 557 is less than or equal to (table capacity - size of new entry). The 558 encoder MUST NOT cause a dynamic table entry to be evicted unless 559 that entry is evictable; see Section 2.1.1. The new entry is then 560 added to the table. It is an error if the encoder attempts to add an 561 entry that is larger than the dynamic table capacity; the decoder 562 MUST treat this as a connection error of type 563 QPACK_ENCODER_STREAM_ERROR. 565 A new entry can reference an entry in the dynamic table that will be 566 evicted when adding this new entry into the dynamic table. 567 Implementations are cautioned to avoid deleting the referenced name 568 or value if the referenced entry is evicted from the dynamic table 569 prior to inserting the new entry. 571 Whenever the dynamic table capacity is reduced by the encoder 572 (Section 4.3.1), entries are evicted from the end of the dynamic 573 table until the size of the dynamic table is less than or equal to 574 the new table capacity. This mechanism can be used to completely 575 clear entries from the dynamic table by setting a capacity of 0, 576 which can subsequently be restored. 578 3.2.3. Maximum Dynamic Table Capacity 580 To bound the memory requirements of the decoder, the decoder limits 581 the maximum value the encoder is permitted to set for the dynamic 582 table capacity. In HTTP/3, this limit is determined by the value of 583 SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder; see Section 5. 584 The encoder MUST NOT set a dynamic table capacity that exceeds this 585 maximum, but it can choose to use a lower dynamic table capacity; see 586 Section 4.3.1. 588 For clients using 0-RTT data in HTTP/3, the server's maximum table 589 capacity is the remembered value of the setting, or zero if the value 590 was not previously sent. When the client's 0-RTT value of the 591 SETTING is zero, the server MAY set it to a non-zero value in its 592 SETTINGS frame. If the remembered value is non-zero, the server MUST 593 send the same non-zero value in its SETTINGS frame. If it specifies 594 any other value, or omits SETTINGS_QPACK_MAX_TABLE_CAPACITY from 595 SETTINGS, the encoder must treat this as a connection error of type 596 QPACK_DECODER_STREAM_ERROR. 598 For HTTP/3 servers and HTTP/3 clients when 0-RTT is not attempted or 599 is rejected, the maximum table capacity is 0 until the encoder 600 processes a SETTINGS frame with a non-zero value of 601 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 603 When the maximum table capacity is zero, the encoder MUST NOT insert 604 entries into the dynamic table, and MUST NOT send any encoder 605 instructions on the encoder stream. 607 3.2.4. Absolute Indexing 609 Each entry possesses an absolute index that is fixed for the lifetime 610 of that entry. The first entry inserted has an absolute index of 611 "0"; indices increase by one with each insertion. 613 3.2.5. Relative Indexing 615 Relative indices begin at zero and increase in the opposite direction 616 from the absolute index. Determining which entry has a relative 617 index of "0" depends on the context of the reference. 619 In encoder instructions (Section 4.3), a relative index of "0" refers 620 to the most recently inserted value in the dynamic table. Note that 621 this means the entry referenced by a given relative index will change 622 while interpreting instructions on the encoder stream. 624 +-----+---------------+-------+ 625 | n-1 | ... | d | Absolute Index 626 + - - +---------------+ - - - + 627 | 0 | ... | n-d-1 | Relative Index 628 +-----+---------------+-------+ 629 ^ | 630 | V 631 Insertion Point Dropping Point 633 n = count of entries inserted 634 d = count of entries dropped 636 Figure 2: Example Dynamic Table Indexing - Encoder Stream 638 Unlike in encoder instructions, relative indices in field line 639 representations are relative to the Base at the beginning of the 640 encoded field section; see Section 4.5.1. This ensures that 641 references are stable even if encoded field sections and dynamic 642 table updates are processed out of order. 644 In a field line representation, a relative index of "0" refers to the 645 entry with absolute index equal to Base - 1. 647 Base 648 | 649 V 650 +-----+-----+-----+-----+-------+ 651 | n-1 | n-2 | n-3 | ... | d | Absolute Index 652 +-----+-----+ - +-----+ - + 653 | 0 | ... | n-d-3 | Relative Index 654 +-----+-----+-------+ 656 n = count of entries inserted 657 d = count of entries dropped 658 In this example, Base = n - 2 659 Figure 3: Example Dynamic Table Indexing - Relative Index in 660 Representation 662 3.2.6. Post-Base Indexing 664 Post-Base indices are used in field line representations for entries 665 with absolute indices greater than or equal to Base, starting at 0 666 for the entry with absolute index equal to Base, and increasing in 667 the same direction as the absolute index. 669 Post-Base indices allow an encoder to process a field section in a 670 single pass and include references to entries added while processing 671 this (or other) field sections. 673 Base 674 | 675 V 676 +-----+-----+-----+-----+-----+ 677 | n-1 | n-2 | n-3 | ... | d | Absolute Index 678 +-----+-----+-----+-----+-----+ 679 | 1 | 0 | Post-Base Index 680 +-----+-----+ 682 n = count of entries inserted 683 d = count of entries dropped 684 In this example, Base = n - 2 686 Figure 4: Example Dynamic Table Indexing - Post-Base Index in 687 Representation 689 4. Wire Format 691 4.1. Primitives 693 4.1.1. Prefixed Integers 695 The prefixed integer from Section 5.1 of [RFC7541] is used heavily 696 throughout this document. The format from [RFC7541] is used 697 unmodified. Note, however, that QPACK uses some prefix sizes not 698 actually used in HPACK. 700 QPACK implementations MUST be able to decode integers up to and 701 including 62 bits long. 703 4.1.2. String Literals 705 The string literal defined by Section 5.2 of [RFC7541] is also used 706 throughout. This string format includes optional Huffman encoding. 708 HPACK defines string literals to begin on a byte boundary. They 709 begin with a single bit flag, denoted as 'H' in this document 710 (indicating whether the string is Huffman-coded), followed by the 711 Length encoded as a 7-bit prefix integer, and finally Length bytes of 712 data. When Huffman encoding is enabled, the Huffman table from 713 Appendix B of [RFC7541] is used without modification and Length 714 indicates the size of the string after encoding. 716 This document expands the definition of string literals by permitting 717 them to begin other than on a byte boundary. An "N-bit prefix string 718 literal" begins mid-byte, with the first (8-N) bits allocated to a 719 previous field. The string uses one bit for the Huffman flag, 720 followed by the Length encoded as an (N-1)-bit prefix integer. The 721 prefix size, N, can have a value between 2 and 8 inclusive. The 722 remainder of the string literal is unmodified. 724 A string literal without a prefix length noted is an 8-bit prefix 725 string literal and follows the definitions in [RFC7541] without 726 modification. 728 4.2. Encoder and Decoder Streams 730 QPACK defines two unidirectional stream types: 732 * An encoder stream is a unidirectional stream of type 0x02. It 733 carries an unframed sequence of encoder instructions from encoder 734 to decoder. 736 * A decoder stream is a unidirectional stream of type 0x03. It 737 carries an unframed sequence of decoder instructions from decoder 738 to encoder. 740 HTTP/3 endpoints contain a QPACK encoder and decoder. Each endpoint 741 MUST initiate at most one encoder stream and at most one decoder 742 stream. Receipt of a second instance of either stream type MUST be 743 treated as a connection error of type H3_STREAM_CREATION_ERROR. 744 These streams MUST NOT be closed. Closure of either unidirectional 745 stream type MUST be treated as a connection error of type 746 H3_CLOSED_CRITICAL_STREAM. 748 An endpoint MAY avoid creating an encoder stream if it will not be 749 used (for example if its encoder does not wish to use the dynamic 750 table, or if the maximum size of the dynamic table permitted by the 751 peer is zero). 753 An endpoint MAY avoid creating a decoder stream if its decoder sets 754 the maximum capacity of the dynamic table to zero. 756 An endpoint MUST allow its peer to create an encoder stream and a 757 decoder stream even if the connection's settings prevent their use. 759 4.3. Encoder Instructions 761 An encoder sends encoder instructions on the encoder stream to set 762 the capacity of the dynamic table and add dynamic table entries. 763 Instructions adding table entries can use existing entries to avoid 764 transmitting redundant information. The name can be transmitted as a 765 reference to an existing entry in the static or the dynamic table or 766 as a string literal. For entries that already exist in the dynamic 767 table, the full entry can also be used by reference, creating a 768 duplicate entry. 770 4.3.1. Set Dynamic Table Capacity 772 An encoder informs the decoder of a change to the dynamic table 773 capacity using an instruction that begins with the '001' three-bit 774 pattern. This is followed by the new dynamic table capacity 775 represented as an integer with a 5-bit prefix; see Section 4.1.1. 777 0 1 2 3 4 5 6 7 778 +---+---+---+---+---+---+---+---+ 779 | 0 | 0 | 1 | Capacity (5+) | 780 +---+---+---+-------------------+ 782 Figure 5: Set Dynamic Table Capacity 784 The new capacity MUST be lower than or equal to the limit described 785 in Section 3.2.3. In HTTP/3, this limit is the value of the 786 SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter (Section 5) received from 787 the decoder. The decoder MUST treat a new dynamic table capacity 788 value that exceeds this limit as a connection error of type 789 QPACK_ENCODER_STREAM_ERROR. 791 Reducing the dynamic table capacity can cause entries to be evicted; 792 see Section 3.2.2. This MUST NOT cause the eviction of entries that 793 are not evictable; see Section 2.1.1. Changing the capacity of the 794 dynamic table is not acknowledged as this instruction does not insert 795 an entry. 797 4.3.2. Insert With Name Reference 799 An encoder adds an entry to the dynamic table where the field name 800 matches the field name of an entry stored in the static or the 801 dynamic table using an instruction that starts with the '1' one-bit 802 pattern. The second ('T') bit indicates whether the reference is to 803 the static or dynamic table. The 6-bit prefix integer 804 (Section 4.1.1) that follows is used to locate the table entry for 805 the field name. When T=1, the number represents the static table 806 index; when T=0, the number is the relative index of the entry in the 807 dynamic table. 809 The field name reference is followed by the field value represented 810 as a string literal; see Section 4.1.2. 812 0 1 2 3 4 5 6 7 813 +---+---+---+---+---+---+---+---+ 814 | 1 | T | Name Index (6+) | 815 +---+---+-----------------------+ 816 | H | Value Length (7+) | 817 +---+---------------------------+ 818 | Value String (Length bytes) | 819 +-------------------------------+ 821 Figure 6: Insert Field Line -- Indexed Name 823 4.3.3. Insert With Literal Name 825 An encoder adds an entry to the dynamic table where both the field 826 name and the field value are represented as string literals using an 827 instruction that starts with the '01' two-bit pattern. 829 This is followed by the name represented as a 6-bit prefix string 830 literal, and the value represented as an 8-bit prefix string literal; 831 see Section 4.1.2. 833 0 1 2 3 4 5 6 7 834 +---+---+---+---+---+---+---+---+ 835 | 0 | 1 | H | Name Length (5+) | 836 +---+---+---+-------------------+ 837 | Name String (Length bytes) | 838 +---+---------------------------+ 839 | H | Value Length (7+) | 840 +---+---------------------------+ 841 | Value String (Length bytes) | 842 +-------------------------------+ 844 Figure 7: Insert Field Line -- New Name 846 4.3.4. Duplicate 848 An encoder duplicates an existing entry in the dynamic table using an 849 instruction that begins with the '000' three-bit pattern. This is 850 followed by the relative index of the existing entry represented as 851 an integer with a 5-bit prefix; see Section 4.1.1. 853 0 1 2 3 4 5 6 7 854 +---+---+---+---+---+---+---+---+ 855 | 0 | 0 | 0 | Index (5+) | 856 +---+---+---+-------------------+ 858 Figure 8: Duplicate 860 The existing entry is re-inserted into the dynamic table without 861 resending either the name or the value. This is useful to avoid 862 adding a reference to an older entry, which might block inserting new 863 entries. 865 4.4. Decoder Instructions 867 A decoder sends decoder instructions on the decoder stream to inform 868 the encoder about the processing of field sections and table updates 869 to ensure consistency of the dynamic table. 871 4.4.1. Section Acknowledgement 873 After processing an encoded field section whose declared Required 874 Insert Count is not zero, the decoder emits a Section Acknowledgement 875 instruction. The instruction begins with the '1' one-bit pattern, 876 followed by the field section's associated stream ID encoded as a 877 7-bit prefix integer; see Section 4.1.1. 879 This instruction is used as described in Section 2.1.4 and in 880 Section 2.2.2. 882 0 1 2 3 4 5 6 7 883 +---+---+---+---+---+---+---+---+ 884 | 1 | Stream ID (7+) | 885 +---+---------------------------+ 887 Figure 9: Section Acknowledgement 889 If an encoder receives a Section Acknowledgement instruction 890 referring to a stream on which every encoded field section with a 891 non-zero Required Insert Count has already been acknowledged, this 892 MUST be treated as a connection error of type 893 QPACK_DECODER_STREAM_ERROR. 895 The Section Acknowledgement instruction might increase the Known 896 Received Count; see Section 2.1.4. 898 4.4.2. Stream Cancellation 900 When a stream is reset or reading is abandoned, the decoder emits a 901 Stream Cancellation instruction. The instruction begins with the 902 '01' two-bit pattern, followed by the stream ID of the affected 903 stream encoded as a 6-bit prefix integer. 905 This instruction is used as described in Section 2.2.2. 907 0 1 2 3 4 5 6 7 908 +---+---+---+---+---+---+---+---+ 909 | 0 | 1 | Stream ID (6+) | 910 +---+---+-----------------------+ 912 Figure 10: Stream Cancellation 914 4.4.3. Insert Count Increment 916 The Insert Count Increment instruction begins with the '00' two-bit 917 pattern, followed by the Increment encoded as a 6-bit prefix integer. 918 This instruction increases the Known Received Count (Section 2.1.4) 919 by the value of the Increment parameter. The decoder should send an 920 Increment value that increases the Known Received Count to the total 921 number of dynamic table insertions and duplications processed so far. 923 0 1 2 3 4 5 6 7 924 +---+---+---+---+---+---+---+---+ 925 | 0 | 0 | Increment (6+) | 926 +---+---+-----------------------+ 928 Figure 11: Insert Count Increment 930 An encoder that receives an Increment field equal to zero, or one 931 that increases the Known Received Count beyond what the encoder has 932 sent MUST treat this as a connection error of type 933 QPACK_DECODER_STREAM_ERROR. 935 4.5. Field Line Representations 937 An encoded field section consists of a prefix and a possibly empty 938 sequence of representations defined in this section. Each 939 representation corresponds to a single field line. These 940 representations reference the static table or the dynamic table in a 941 particular state, but do not modify that state. 943 Encoded field sections are carried in frames on streams defined by 944 the enclosing protocol. 946 4.5.1. Encoded Field Section Prefix 948 Each encoded field section is prefixed with two integers. The 949 Required Insert Count is encoded as an integer with an 8-bit prefix 950 using the encoding described in Section 4.5.1.1. The Base is encoded 951 as a sign bit ('S') and a Delta Base value with a 7-bit prefix; see 952 Section 4.5.1.2. 954 0 1 2 3 4 5 6 7 955 +---+---+---+---+---+---+---+---+ 956 | Required Insert Count (8+) | 957 +---+---------------------------+ 958 | S | Delta Base (7+) | 959 +---+---------------------------+ 960 | Encoded Field Lines ... 961 +-------------------------------+ 963 Figure 12: Encoded Field Section 965 4.5.1.1. Required Insert Count 967 Required Insert Count identifies the state of the dynamic table 968 needed to process the encoded field section. Blocking decoders use 969 the Required Insert Count to determine when it is safe to process the 970 rest of the field section. 972 The encoder transforms the Required Insert Count as follows before 973 encoding: 975 if ReqInsertCount == 0: 976 EncInsertCount = 0 977 else: 978 EncInsertCount = (ReqInsertCount mod (2 * MaxEntries)) + 1 980 Here "MaxEntries" is the maximum number of entries that the dynamic 981 table can have. The smallest entry has empty name and value strings 982 and has the size of 32. Hence "MaxEntries" is calculated as 984 MaxEntries = floor( MaxTableCapacity / 32 ) 986 "MaxTableCapacity" is the maximum capacity of the dynamic table as 987 specified by the decoder; see Section 3.2.3. 989 This encoding limits the length of the prefix on long-lived 990 connections. 992 The decoder can reconstruct the Required Insert Count using an 993 algorithm such as the following. If the decoder encounters a value 994 of EncodedInsertCount that could not have been produced by a 995 conformant encoder, it MUST treat this as a connection error of type 996 QPACK_DECOMPRESSION_FAILED. 998 TotalNumberOfInserts is the total number of inserts into the 999 decoder's dynamic table. 1001 FullRange = 2 * MaxEntries 1002 if EncodedInsertCount == 0: 1003 ReqInsertCount = 0 1004 else: 1005 if EncodedInsertCount > FullRange: 1006 Error 1007 MaxValue = TotalNumberOfInserts + MaxEntries 1009 # MaxWrapped is the largest possible value of 1010 # ReqInsertCount that is 0 mod 2*MaxEntries 1011 MaxWrapped = floor(MaxValue / FullRange) * FullRange 1012 ReqInsertCount = MaxWrapped + EncodedInsertCount - 1 1014 # If ReqInsertCount exceeds MaxValue, the Encoder's value 1015 # must have wrapped one fewer time 1016 if ReqInsertCount > MaxValue: 1017 if ReqInsertCount <= FullRange: 1018 Error 1019 ReqInsertCount -= FullRange 1021 # Value of 0 must be encoded as 0. 1022 if ReqInsertCount == 0: 1023 Error 1025 For example, if the dynamic table is 100 bytes, then the Required 1026 Insert Count will be encoded modulo 6. If a decoder has received 10 1027 inserts, then an encoded value of 4 indicates that the Required 1028 Insert Count is 9 for the field section. 1030 4.5.1.2. Base 1032 The Base is used to resolve references in the dynamic table as 1033 described in Section 3.2.5. 1035 To save space, the Base is encoded relative to the Required Insert 1036 Count using a one-bit sign ('S') and the Delta Base value. A sign 1037 bit of 0 indicates that the Base is greater than or equal to the 1038 value of the Required Insert Count; the decoder adds the value of 1039 Delta Base to the Required Insert Count to determine the value of the 1040 Base. A sign bit of 1 indicates that the Base is less than the 1041 Required Insert Count; the decoder subtracts the value of Delta Base 1042 from the Required Insert Count and also subtracts one to determine 1043 the value of the Base. That is: 1045 if S == 0: 1046 Base = ReqInsertCount + DeltaBase 1047 else: 1048 Base = ReqInsertCount - DeltaBase - 1 1050 A single-pass encoder determines the Base before encoding a field 1051 section. If the encoder inserted entries in the dynamic table while 1052 encoding the field section and is referencing them, Required Insert 1053 Count will be greater than the Base, so the encoded difference is 1054 negative and the sign bit is set to 1. If the field section was not 1055 encoded using representations that reference the most recent entry in 1056 the table and did not insert any new entries, the Base will be 1057 greater than the Required Insert Count, so the delta will be positive 1058 and the sign bit is set to 0. 1060 An encoder that produces table updates before encoding a field 1061 section might set Base to the value of Required Insert Count. In 1062 such case, both the sign bit and the Delta Base will be set to zero. 1064 A field section that was encoded without references to the dynamic 1065 table can use any value for the Base; setting Delta Base to zero is 1066 one of the most efficient encodings. 1068 For example, with a Required Insert Count of 9, a decoder receives an 1069 S bit of 1 and a Delta Base of 2. This sets the Base to 6 and 1070 enables post-base indexing for three entries. In this example, a 1071 relative index of 1 refers to the 5th entry that was added to the 1072 table; a post-base index of 1 refers to the 8th entry. 1074 4.5.2. Indexed Field Line 1076 An indexed field line representation identifies an entry in the 1077 static table, or an entry in the dynamic table with an absolute index 1078 less than the value of the Base. 1080 0 1 2 3 4 5 6 7 1081 +---+---+---+---+---+---+---+---+ 1082 | 1 | T | Index (6+) | 1083 +---+---+-----------------------+ 1085 Figure 13: Indexed Field Line 1087 This representation starts with the '1' 1-bit pattern, followed by 1088 the 'T' bit indicating whether the reference is into the static or 1089 dynamic table. The 6-bit prefix integer (Section 4.1.1) that follows 1090 is used to locate the table entry for the field line. When T=1, the 1091 number represents the static table index; when T=0, the number is the 1092 relative index of the entry in the dynamic table. 1094 4.5.3. Indexed Field Line With Post-Base Index 1096 An indexed field line with post-base index representation identifies 1097 an entry in the dynamic table with an absolute index greater than or 1098 equal to the value of the Base. 1100 0 1 2 3 4 5 6 7 1101 +---+---+---+---+---+---+---+---+ 1102 | 0 | 0 | 0 | 1 | Index (4+) | 1103 +---+---+---+---+---------------+ 1105 Figure 14: Indexed Field Line with Post-Base Index 1107 This representation starts with the '0001' 4-bit pattern. This is 1108 followed by the post-base index (Section 3.2.6) of the matching field 1109 line, represented as an integer with a 4-bit prefix; see 1110 Section 4.1.1. 1112 4.5.4. Literal Field Line With Name Reference 1114 A literal field line with name reference representation encodes a 1115 field line where the field name matches the field name of an entry in 1116 the static table, or the field name of an entry in the dynamic table 1117 with an absolute index less than the value of the Base. 1119 0 1 2 3 4 5 6 7 1120 +---+---+---+---+---+---+---+---+ 1121 | 0 | 1 | N | T |Name Index (4+)| 1122 +---+---+---+---+---------------+ 1123 | H | Value Length (7+) | 1124 +---+---------------------------+ 1125 | Value String (Length bytes) | 1126 +-------------------------------+ 1128 Figure 15: Literal Field Line With Name Reference 1130 This representation starts with the '01' two-bit pattern. The 1131 following bit, 'N', indicates whether an intermediary is permitted to 1132 add this field line to the dynamic table on subsequent hops. When 1133 the 'N' bit is set, the encoded field line MUST always be encoded 1134 with a literal representation. In particular, when a peer sends a 1135 field line that it received represented as a literal field line with 1136 the 'N' bit set, it MUST use a literal representation to forward this 1137 field line. This bit is intended for protecting field values that 1138 are not to be put at risk by compressing them; see Section 7 for more 1139 details. 1141 The fourth ('T') bit indicates whether the reference is to the static 1142 or dynamic table. The 4-bit prefix integer (Section 4.1.1) that 1143 follows is used to locate the table entry for the field name. When 1144 T=1, the number represents the static table index; when T=0, the 1145 number is the relative index of the entry in the dynamic table. 1147 Only the field name is taken from the dynamic table entry; the field 1148 value is encoded as an 8-bit prefix string literal; see 1149 Section 4.1.2. 1151 4.5.5. Literal Field Line With Post-Base Name Reference 1153 A literal field line with post-base name reference representation 1154 encodes a field line where the field name matches the field name of a 1155 dynamic table entry with an absolute index greater than or equal to 1156 the value of the Base. 1158 0 1 2 3 4 5 6 7 1159 +---+---+---+---+---+---+---+---+ 1160 | 0 | 0 | 0 | 0 | N |NameIdx(3+)| 1161 +---+---+---+---+---+-----------+ 1162 | H | Value Length (7+) | 1163 +---+---------------------------+ 1164 | Value String (Length bytes) | 1165 +-------------------------------+ 1167 Figure 16: Literal Field Line With Post-Base Name Reference 1169 This representation starts with the '0000' four-bit pattern. The 1170 fifth bit is the 'N' bit as described in Section 4.5.4. This is 1171 followed by a post-base index of the dynamic table entry 1172 (Section 3.2.6) encoded as an integer with a 3-bit prefix; see 1173 Section 4.1.1. 1175 Only the field name is taken from the dynamic table entry; the field 1176 value is encoded as an 8-bit prefix string literal; see 1177 Section 4.1.2. 1179 4.5.6. Literal Field Line With Literal Name 1181 The literal field line with literal name representation encodes a 1182 field name and a field value as string literals. 1184 0 1 2 3 4 5 6 7 1185 +---+---+---+---+---+---+---+---+ 1186 | 0 | 0 | 1 | N | H |NameLen(3+)| 1187 +---+---+---+---+---+-----------+ 1188 | Name String (Length bytes) | 1189 +---+---------------------------+ 1190 | H | Value Length (7+) | 1191 +---+---------------------------+ 1192 | Value String (Length bytes) | 1193 +-------------------------------+ 1195 Figure 17: Literal Field Line With Literal Name 1197 This representation begins with the '001' three-bit pattern. The 1198 fourth bit is the 'N' bit as described in Section 4.5.4. The name 1199 follows, represented as a 4-bit prefix string literal, then the 1200 value, represented as an 8-bit prefix string literal; see 1201 Section 4.1.2. 1203 5. Configuration 1205 QPACK defines two settings for the HTTP/3 SETTINGS frame: 1207 SETTINGS_QPACK_MAX_TABLE_CAPACITY (0x1): The default value is zero. 1208 See Section 3.2 for usage. This is the equivalent of the 1209 SETTINGS_HEADER_TABLE_SIZE from HTTP/2. 1211 SETTINGS_QPACK_BLOCKED_STREAMS (0x7): The default value is zero. 1212 See Section 2.1.2. 1214 6. Error Handling 1216 The following error codes are defined for HTTP/3 to indicate failures 1217 of QPACK that prevent the stream or connection from continuing: 1219 QPACK_DECOMPRESSION_FAILED (0x200): The decoder failed to interpret 1220 an encoded field section and is not able to continue decoding that 1221 field section. 1223 QPACK_ENCODER_STREAM_ERROR (0x201): The decoder failed to interpret 1224 an encoder instruction received on the encoder stream. 1226 QPACK_DECODER_STREAM_ERROR (0x202): The encoder failed to interpret 1227 a decoder instruction received on the decoder stream. 1229 7. Security Considerations 1231 This section describes potential areas of security concern with 1232 QPACK: 1234 * Use of compression as a length-based oracle for verifying guesses 1235 about secrets that are compressed into a shared compression 1236 context. 1238 * Denial of service resulting from exhausting processing or memory 1239 capacity at a decoder. 1241 7.1. Probing Dynamic Table State 1243 QPACK reduces the encoded size of field sections by exploiting the 1244 redundancy inherent in protocols like HTTP. The ultimate goal of 1245 this is to reduce the amount of data that is required to send HTTP 1246 requests or responses. 1248 The compression context used to encode header and trailer fields can 1249 be probed by an attacker who can both define fields to be encoded and 1250 transmitted and observe the length of those fields once they are 1251 encoded. When an attacker can do both, they can adaptively modify 1252 requests in order to confirm guesses about the dynamic table state. 1253 If a guess is compressed into a shorter length, the attacker can 1254 observe the encoded length and infer that the guess was correct. 1256 This is possible even over the Transport Layer Security Protocol 1257 (TLS, see [TLS]), because while TLS provides confidentiality 1258 protection for content, it only provides a limited amount of 1259 protection for the length of that content. 1261 Note: Padding schemes only provide limited protection against an 1262 attacker with these capabilities, potentially only forcing an 1263 increased number of guesses to learn the length associated with a 1264 given guess. Padding schemes also work directly against 1265 compression by increasing the number of bits that are transmitted. 1267 Attacks like CRIME ([CRIME]) demonstrated the existence of these 1268 general attacker capabilities. The specific attack exploited the 1269 fact that DEFLATE ([RFC1951]) removes redundancy based on prefix 1270 matching. This permitted the attacker to confirm guesses a character 1271 at a time, reducing an exponential-time attack into a linear-time 1272 attack. 1274 7.2. Applicability to QPACK and HTTP 1276 QPACK mitigates but does not completely prevent attacks modeled on 1277 CRIME ([CRIME]) by forcing a guess to match an entire field line, 1278 rather than individual characters. An attacker can only learn 1279 whether a guess is correct or not, so is reduced to a brute force 1280 guess for the field values associated with a given field name. 1282 The viability of recovering specific field values therefore depends 1283 on the entropy of values. As a result, values with high entropy are 1284 unlikely to be recovered successfully. However, values with low 1285 entropy remain vulnerable. 1287 Attacks of this nature are possible any time that two mutually 1288 distrustful entities control requests or responses that are placed 1289 onto a single HTTP/3 connection. If the shared QPACK compressor 1290 permits one entity to add entries to the dynamic table, and the other 1291 to access those entries, then the state of the table can be learned. 1293 Having requests or responses from mutually distrustful entities 1294 occurs when an intermediary either: 1296 * sends requests from multiple clients on a single connection toward 1297 an origin server, or 1299 * takes responses from multiple origin servers and places them on a 1300 shared connection toward a client. 1302 Web browsers also need to assume that requests made on the same 1303 connection by different web origins ([RFC6454]) are made by mutually 1304 distrustful entities. 1306 7.3. Mitigation 1308 Users of HTTP that require confidentiality for header or trailer 1309 fields can use values with entropy sufficient to make guessing 1310 infeasible. However, this is impractical as a general solution 1311 because it forces all users of HTTP to take steps to mitigate 1312 attacks. It would impose new constraints on how HTTP is used. 1314 Rather than impose constraints on users of HTTP, an implementation of 1315 QPACK can instead constrain how compression is applied in order to 1316 limit the potential for dynamic table probing. 1318 An ideal solution segregates access to the dynamic table based on the 1319 entity that is constructing the message. Field values that are added 1320 to the table are attributed to an entity, and only the entity that 1321 created a particular value can extract that value. 1323 To improve compression performance of this option, certain entries 1324 might be tagged as being public. For example, a web browser might 1325 make the values of the Accept-Encoding header field available in all 1326 requests. 1328 An encoder without good knowledge of the provenance of field values 1329 might instead introduce a penalty for many field lines with the same 1330 field name and different values. This penalty could cause a large 1331 number of attempts to guess a field value to result in the field not 1332 being compared to the dynamic table entries in future messages, 1333 effectively preventing further guesses. 1335 Note: Simply removing entries corresponding to the field from the 1336 dynamic table can be ineffectual if the attacker has a reliable 1337 way of causing values to be reinstalled. For example, a request 1338 to load an image in a web browser typically includes the Cookie 1339 header field (a potentially highly valued target for this sort of 1340 attack), and web sites can easily force an image to be loaded, 1341 thereby refreshing the entry in the dynamic table. 1343 This response might be made inversely proportional to the length of 1344 the field value. Disabling access to the dynamic table for a given 1345 field name might occur for shorter values more quickly or with higher 1346 probability than for longer values. 1348 7.4. Never-Indexed Literals 1350 Implementations can also choose to protect sensitive fields by not 1351 compressing them and instead encoding their value as literals. 1353 Refusing to insert a field line into the dynamic table is only 1354 effective if doing so is avoided on all hops. The never-indexed 1355 literal bit (see Section 4.5.4) can be used to signal to 1356 intermediaries that a particular value was intentionally sent as a 1357 literal. 1359 An intermediary MUST NOT re-encode a value that uses a literal 1360 representation with the 'N' bit set with another representation that 1361 would index it. If QPACK is used for re-encoding, a literal 1362 representation with the 'N' bit set MUST be used. If HPACK is used 1363 for re-encoding, the never-indexed literal representation (see 1364 Section 6.2.3 of [RFC7541]) MUST be used. 1366 The choice to mark that a field value should never be indexed depends 1367 on several factors. Since QPACK does not protect against guessing an 1368 entire field value, short or low-entropy values are more readily 1369 recovered by an adversary. Therefore, an encoder might choose not to 1370 index values with low entropy. 1372 An encoder might also choose not to index values for fields that are 1373 considered to be highly valuable or sensitive to recovery, such as 1374 the Cookie or Authorization header fields. 1376 On the contrary, an encoder might prefer indexing values for fields 1377 that have little or no value if they were exposed. For instance, a 1378 User-Agent header field does not commonly vary between requests and 1379 is sent to any server. In that case, confirmation that a particular 1380 User-Agent value has been used provides little value. 1382 Note that these criteria for deciding to use a never-indexed literal 1383 representation will evolve over time as new attacks are discovered. 1385 7.5. Static Huffman Encoding 1387 There is no currently known attack against a static Huffman encoding. 1388 A study has shown that using a static Huffman encoding table created 1389 an information leakage, however this same study concluded that an 1390 attacker could not take advantage of this information leakage to 1391 recover any meaningful amount of information (see [PETAL]). 1393 7.6. Memory Consumption 1395 An attacker can try to cause an endpoint to exhaust its memory. 1396 QPACK is designed to limit both the peak and stable amounts of memory 1397 allocated by an endpoint. 1399 The amount of memory used by the encoder is limited by the protocol 1400 using QPACK through the definition of the maximum size of the dynamic 1401 table, and the maximum number of blocking streams. In HTTP/3, these 1402 values are controlled by the decoder through the settings parameters 1403 SETTINGS_QPACK_MAX_TABLE_CAPACITY and SETTINGS_QPACK_BLOCKED_STREAMS, 1404 respectively (see Section 3.2.3 and Section 2.1.2). The limit on the 1405 size of the dynamic table takes into account the size of the data 1406 stored in the dynamic table, plus a small allowance for overhead. 1407 The limit on the number of blocked streams is only a proxy for the 1408 maximum amount of memory required by the decoder. The actual maximum 1409 amount of memory will depend on how much memory the decoder uses to 1410 track each blocked stream. 1412 A decoder can limit the amount of state memory used for the dynamic 1413 table by setting an appropriate value for the maximum size of the 1414 dynamic table. In HTTP/3, this is realized by setting an appropriate 1415 value for the SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter. An 1416 encoder can limit the amount of state memory it uses by signaling a 1417 lower dynamic table size than the decoder allows (see Section 3.2.2). 1419 A decoder can limit the amount of state memory used for blocked 1420 streams by setting an appropriate value for the maximum number of 1421 blocked streams. In HTTP/3, this is realized by setting an 1422 appropriate value for the QPACK_BLOCKED_STREAMS parameter. Streams 1423 which risk becoming blocked consume no additional state memory on the 1424 encoder. 1426 An encoder allocates memory to track all dynamic table references in 1427 unacknowledged field sections. An implementation can directly limit 1428 the amount of state memory by only using as many references to the 1429 dynamic table as it wishes to track; no signaling to the decoder is 1430 required. However, limiting references to the dynamic table will 1431 reduce compression effectiveness. 1433 The amount of temporary memory consumed by an encoder or decoder can 1434 be limited by processing field lines sequentially. A decoder 1435 implementation does not need to retain a complete list of field lines 1436 while decoding a field section. An encoder implementation does not 1437 need to retain a complete list of field lines while encoding a field 1438 section if it is using a single-pass algorithm. Note that it might 1439 be necessary for an application to retain a complete list of field 1440 lines for other reasons; even if QPACK does not force this to occur, 1441 application constraints might make this necessary. 1443 While the negotiated limit on the dynamic table size accounts for 1444 much of the memory that can be consumed by a QPACK implementation, 1445 data that cannot be immediately sent due to flow control is not 1446 affected by this limit. Implementations should limit the size of 1447 unsent data, especially on the decoder stream where flexibility to 1448 choose what to send is limited. Possible responses to an excess of 1449 unsent data might include limiting the ability of the peer to open 1450 new streams, reading only from the encoder stream, or closing the 1451 connection. 1453 7.7. Implementation Limits 1455 An implementation of QPACK needs to ensure that large values for 1456 integers, long encoding for integers, or long string literals do not 1457 create security weaknesses. 1459 An implementation has to set a limit for the values it accepts for 1460 integers, as well as for the encoded length; see Section 4.1.1. In 1461 the same way, it has to set a limit to the length it accepts for 1462 string literals; see Section 4.1.2. 1464 8. IANA Considerations 1466 8.1. Settings Registration 1468 This document specifies two settings. The entries in the following 1469 table are registered in the "HTTP/3 Settings" registry established in 1470 [HTTP3]. 1472 +==========================+======+===============+=========+ 1473 | Setting Name | Code | Specification | Default | 1474 +==========================+======+===============+=========+ 1475 | QPACK_MAX_TABLE_CAPACITY | 0x1 | Section 5 | 0 | 1476 +--------------------------+------+---------------+---------+ 1477 | QPACK_BLOCKED_STREAMS | 0x7 | Section 5 | 0 | 1478 +--------------------------+------+---------------+---------+ 1480 Table 1 1482 8.2. Stream Type Registration 1484 This document specifies two stream types. The entries in the 1485 following table are registered in the "HTTP/3 Stream Type" registry 1486 established in [HTTP3]. 1488 +======================+======+===============+========+ 1489 | Stream Type | Code | Specification | Sender | 1490 +======================+======+===============+========+ 1491 | QPACK Encoder Stream | 0x02 | Section 4.2 | Both | 1492 +----------------------+------+---------------+--------+ 1493 | QPACK Decoder Stream | 0x03 | Section 4.2 | Both | 1494 +----------------------+------+---------------+--------+ 1496 Table 2 1498 8.3. Error Code Registration 1500 This document specifies three error codes. The entries in the 1501 following table are registered in the "HTTP/3 Error Code" registry 1502 established in [HTTP3]. 1504 +============================+=======+=============+===============+ 1505 | Name | Code | Description | Specification | 1506 +============================+=======+=============+===============+ 1507 | QPACK_DECOMPRESSION_FAILED | 0x200 | Decoding of | Section 6 | 1508 | | | a field | | 1509 | | | section | | 1510 | | | failed | | 1511 +----------------------------+-------+-------------+---------------+ 1512 | QPACK_ENCODER_STREAM_ERROR | 0x201 | Error on | Section 6 | 1513 | | | the encoder | | 1514 | | | stream | | 1515 +----------------------------+-------+-------------+---------------+ 1516 | QPACK_DECODER_STREAM_ERROR | 0x202 | Error on | Section 6 | 1517 | | | the decoder | | 1518 | | | stream | | 1519 +----------------------------+-------+-------------+---------------+ 1521 Table 3 1523 9. References 1525 9.1. Normative References 1527 [HTTP3] Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 1528 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 1529 quic-http-32, 20 October 2020, 1530 . 1532 [QUIC-TRANSPORT] 1533 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 1534 Multiplexed and Secure Transport", Work in Progress, 1535 Internet-Draft, draft-ietf-quic-transport-32, 20 October 1536 2020, . 1539 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1540 Requirement Levels", BCP 14, RFC 2119, 1541 DOI 10.17487/RFC2119, March 1997, 1542 . 1544 [RFC2360] Scott, G., "Guide for Internet Standards Writers", BCP 22, 1545 RFC 2360, DOI 10.17487/RFC2360, June 1998, 1546 . 1548 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 1549 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 1550 . 1552 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1553 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1554 May 2017, . 1556 [SEMANTICS] 1557 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 1558 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1559 httpbis-semantics-12, 2 October 2020, 1560 . 1563 9.2. Informative References 1565 [CRIME] Wikipedia, "CRIME", May 2015, . 1568 [PETAL] Tan, J. and J. Nahata, "PETAL: Preset Encoding 1569 Table Information Leakage", April 2013, 1570 . 1573 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1574 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 1575 . 1577 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1578 DOI 10.17487/RFC6454, December 2011, 1579 . 1581 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1582 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1583 DOI 10.17487/RFC7540, May 2015, 1584 . 1586 [TLS] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1587 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1588 . 1590 Appendix A. Static Table 1592 This table was generated by analyzing actual Internet traffic in 2018 1593 and including the most common header fields, after filtering out some 1594 unsupported and non-standard values. Due to this methodology, some 1595 of the entries may be inconsistent or appear multiple times with 1596 similar but not identical values. The order of the entries is 1597 optimized to encode the most common header fields with the smallest 1598 number of bytes. 1600 +=======+==================================+=======================+ 1601 | Index | Name | Value | 1602 +=======+==================================+=======================+ 1603 | 0 | :authority | | 1604 +-------+----------------------------------+-----------------------+ 1605 | 1 | :path | / | 1606 +-------+----------------------------------+-----------------------+ 1607 | 2 | age | 0 | 1608 +-------+----------------------------------+-----------------------+ 1609 | 3 | content-disposition | | 1610 +-------+----------------------------------+-----------------------+ 1611 | 4 | content-length | 0 | 1612 +-------+----------------------------------+-----------------------+ 1613 | 5 | cookie | | 1614 +-------+----------------------------------+-----------------------+ 1615 | 6 | date | | 1616 +-------+----------------------------------+-----------------------+ 1617 | 7 | etag | | 1618 +-------+----------------------------------+-----------------------+ 1619 | 8 | if-modified-since | | 1620 +-------+----------------------------------+-----------------------+ 1621 | 9 | if-none-match | | 1622 +-------+----------------------------------+-----------------------+ 1623 | 10 | last-modified | | 1624 +-------+----------------------------------+-----------------------+ 1625 | 11 | link | | 1626 +-------+----------------------------------+-----------------------+ 1627 | 12 | location | | 1628 +-------+----------------------------------+-----------------------+ 1629 | 13 | referer | | 1630 +-------+----------------------------------+-----------------------+ 1631 | 14 | set-cookie | | 1632 +-------+----------------------------------+-----------------------+ 1633 | 15 | :method | CONNECT | 1634 +-------+----------------------------------+-----------------------+ 1635 | 16 | :method | DELETE | 1636 +-------+----------------------------------+-----------------------+ 1637 | 17 | :method | GET | 1638 +-------+----------------------------------+-----------------------+ 1639 | 18 | :method | HEAD | 1640 +-------+----------------------------------+-----------------------+ 1641 | 19 | :method | OPTIONS | 1642 +-------+----------------------------------+-----------------------+ 1643 | 20 | :method | POST | 1644 +-------+----------------------------------+-----------------------+ 1645 | 21 | :method | PUT | 1646 +-------+----------------------------------+-----------------------+ 1647 | 22 | :scheme | http | 1648 +-------+----------------------------------+-----------------------+ 1649 | 23 | :scheme | https | 1650 +-------+----------------------------------+-----------------------+ 1651 | 24 | :status | 103 | 1652 +-------+----------------------------------+-----------------------+ 1653 | 25 | :status | 200 | 1654 +-------+----------------------------------+-----------------------+ 1655 | 26 | :status | 304 | 1656 +-------+----------------------------------+-----------------------+ 1657 | 27 | :status | 404 | 1658 +-------+----------------------------------+-----------------------+ 1659 | 28 | :status | 503 | 1660 +-------+----------------------------------+-----------------------+ 1661 | 29 | accept | */* | 1662 +-------+----------------------------------+-----------------------+ 1663 | 30 | accept | application/dns- | 1664 | | | message | 1665 +-------+----------------------------------+-----------------------+ 1666 | 31 | accept-encoding | gzip, deflate, br | 1667 +-------+----------------------------------+-----------------------+ 1668 | 32 | accept-ranges | bytes | 1669 +-------+----------------------------------+-----------------------+ 1670 | 33 | access-control-allow-headers | cache-control | 1671 +-------+----------------------------------+-----------------------+ 1672 | 34 | access-control-allow-headers | content-type | 1673 +-------+----------------------------------+-----------------------+ 1674 | 35 | access-control-allow-origin | * | 1675 +-------+----------------------------------+-----------------------+ 1676 | 36 | cache-control | max-age=0 | 1677 +-------+----------------------------------+-----------------------+ 1678 | 37 | cache-control | max-age=2592000 | 1679 +-------+----------------------------------+-----------------------+ 1680 | 38 | cache-control | max-age=604800 | 1681 +-------+----------------------------------+-----------------------+ 1682 | 39 | cache-control | no-cache | 1683 +-------+----------------------------------+-----------------------+ 1684 | 40 | cache-control | no-store | 1685 +-------+----------------------------------+-----------------------+ 1686 | 41 | cache-control | public, max- | 1687 | | | age=31536000 | 1688 +-------+----------------------------------+-----------------------+ 1689 | 42 | content-encoding | br | 1690 +-------+----------------------------------+-----------------------+ 1691 | 43 | content-encoding | gzip | 1692 +-------+----------------------------------+-----------------------+ 1693 | 44 | content-type | application/dns- | 1694 | | | message | 1695 +-------+----------------------------------+-----------------------+ 1696 | 45 | content-type | application/ | 1697 | | | javascript | 1698 +-------+----------------------------------+-----------------------+ 1699 | 46 | content-type | application/json | 1700 +-------+----------------------------------+-----------------------+ 1701 | 47 | content-type | application/x-www- | 1702 | | | form-urlencoded | 1703 +-------+----------------------------------+-----------------------+ 1704 | 48 | content-type | image/gif | 1705 +-------+----------------------------------+-----------------------+ 1706 | 49 | content-type | image/jpeg | 1707 +-------+----------------------------------+-----------------------+ 1708 | 50 | content-type | image/png | 1709 +-------+----------------------------------+-----------------------+ 1710 | 51 | content-type | text/css | 1711 +-------+----------------------------------+-----------------------+ 1712 | 52 | content-type | text/html; | 1713 | | | charset=utf-8 | 1714 +-------+----------------------------------+-----------------------+ 1715 | 53 | content-type | text/plain | 1716 +-------+----------------------------------+-----------------------+ 1717 | 54 | content-type | text/ | 1718 | | | plain;charset=utf-8 | 1719 +-------+----------------------------------+-----------------------+ 1720 | 55 | range | bytes=0- | 1721 +-------+----------------------------------+-----------------------+ 1722 | 56 | strict-transport-security | max-age=31536000 | 1723 +-------+----------------------------------+-----------------------+ 1724 | 57 | strict-transport-security | max-age=31536000; | 1725 | | | includesubdomains | 1726 +-------+----------------------------------+-----------------------+ 1727 | 58 | strict-transport-security | max-age=31536000; | 1728 | | | includesubdomains; | 1729 | | | preload | 1730 +-------+----------------------------------+-----------------------+ 1731 | 59 | vary | accept-encoding | 1732 +-------+----------------------------------+-----------------------+ 1733 | 60 | vary | origin | 1734 +-------+----------------------------------+-----------------------+ 1735 | 61 | x-content-type-options | nosniff | 1736 +-------+----------------------------------+-----------------------+ 1737 | 62 | x-xss-protection | 1; mode=block | 1738 +-------+----------------------------------+-----------------------+ 1739 | 63 | :status | 100 | 1740 +-------+----------------------------------+-----------------------+ 1741 | 64 | :status | 204 | 1742 +-------+----------------------------------+-----------------------+ 1743 | 65 | :status | 206 | 1744 +-------+----------------------------------+-----------------------+ 1745 | 66 | :status | 302 | 1746 +-------+----------------------------------+-----------------------+ 1747 | 67 | :status | 400 | 1748 +-------+----------------------------------+-----------------------+ 1749 | 68 | :status | 403 | 1750 +-------+----------------------------------+-----------------------+ 1751 | 69 | :status | 421 | 1752 +-------+----------------------------------+-----------------------+ 1753 | 70 | :status | 425 | 1754 +-------+----------------------------------+-----------------------+ 1755 | 71 | :status | 500 | 1756 +-------+----------------------------------+-----------------------+ 1757 | 72 | accept-language | | 1758 +-------+----------------------------------+-----------------------+ 1759 | 73 | access-control-allow-credentials | FALSE | 1760 +-------+----------------------------------+-----------------------+ 1761 | 74 | access-control-allow-credentials | TRUE | 1762 +-------+----------------------------------+-----------------------+ 1763 | 75 | access-control-allow-headers | * | 1764 +-------+----------------------------------+-----------------------+ 1765 | 76 | access-control-allow-methods | get | 1766 +-------+----------------------------------+-----------------------+ 1767 | 77 | access-control-allow-methods | get, post, options | 1768 +-------+----------------------------------+-----------------------+ 1769 | 78 | access-control-allow-methods | options | 1770 +-------+----------------------------------+-----------------------+ 1771 | 79 | access-control-expose-headers | content-length | 1772 +-------+----------------------------------+-----------------------+ 1773 | 80 | access-control-request-headers | content-type | 1774 +-------+----------------------------------+-----------------------+ 1775 | 81 | access-control-request-method | get | 1776 +-------+----------------------------------+-----------------------+ 1777 | 82 | access-control-request-method | post | 1778 +-------+----------------------------------+-----------------------+ 1779 | 83 | alt-svc | clear | 1780 +-------+----------------------------------+-----------------------+ 1781 | 84 | authorization | | 1782 +-------+----------------------------------+-----------------------+ 1783 | 85 | content-security-policy | script-src 'none'; | 1784 | | | object-src 'none'; | 1785 | | | base-uri 'none' | 1786 +-------+----------------------------------+-----------------------+ 1787 | 86 | early-data | 1 | 1788 +-------+----------------------------------+-----------------------+ 1789 | 87 | expect-ct | | 1790 +-------+----------------------------------+-----------------------+ 1791 | 88 | forwarded | | 1792 +-------+----------------------------------+-----------------------+ 1793 | 89 | if-range | | 1794 +-------+----------------------------------+-----------------------+ 1795 | 90 | origin | | 1796 +-------+----------------------------------+-----------------------+ 1797 | 91 | purpose | prefetch | 1798 +-------+----------------------------------+-----------------------+ 1799 | 92 | server | | 1800 +-------+----------------------------------+-----------------------+ 1801 | 93 | timing-allow-origin | * | 1802 +-------+----------------------------------+-----------------------+ 1803 | 94 | upgrade-insecure-requests | 1 | 1804 +-------+----------------------------------+-----------------------+ 1805 | 95 | user-agent | | 1806 +-------+----------------------------------+-----------------------+ 1807 | 96 | x-forwarded-for | | 1808 +-------+----------------------------------+-----------------------+ 1809 | 97 | x-frame-options | deny | 1810 +-------+----------------------------------+-----------------------+ 1811 | 98 | x-frame-options | sameorigin | 1812 +-------+----------------------------------+-----------------------+ 1814 Table 4 1816 Appendix B. Encoding and Decoding Examples 1818 The following examples represent a series of exchanges between an 1819 encoder and a decoder. The exchanges are designed to exercise most 1820 QPACK instructions, and highlight potentially common patterns and 1821 their impact on dynamic table state. The encoder sends three encoded 1822 field sections containing one field line each, as wells as two 1823 speculative inserts that are not referenced. 1825 The state of the encoder's dynamic table is shown, along with its 1826 current size. Each entry is shown with the Absolute Index of the 1827 entry (Abs), the current number of outstanding encoded field sections 1828 with references to that entry (Ref), along with the name and value. 1829 Entries above the 'acknowledged' line have been acknowledged by the 1830 decoder. 1832 B.1. Literal Field Line With Name Reference 1834 The encoder sends an encoded field section containing a literal 1835 representation of a field with a static name reference. 1837 Data | Interpretation 1838 | Encoder's Dynamic Table 1840 Stream: 0 1841 0000 | Required Insert Count = 0, Base = 0 1842 510b 2f69 6e64 6578 | Literal Field Line with Name Reference 1843 2e68 746d 6c | Static Table, Index=1 1844 | (:path=/index.html) 1846 Abs Ref Name Value 1847 ^-- acknowledged --^ 1848 Size=0 1850 B.2. Dynamic Table 1852 The encoder sets the dynamic table capacity, inserts a header with a 1853 dynamic name reference, then sends a potentially blocking, encoded 1854 field section referencing this new entry. The decoder acknowledges 1855 processing the encoded field section, which implicitly acknowledges 1856 all dynamic table insertions up to the Required Insert Count. 1858 Stream: Encoder 1859 3fbd01 | Set Dynamic Table Capacity=220 1860 c00f 7777 772e 6578 | Insert With Name Reference 1861 616d 706c 652e 636f | Static Table, Index=0 1862 6d | (:authority=www.example.com) 1863 c10c 2f73 616d 706c | Insert With Name Reference 1864 652f 7061 7468 | Static Table, Index=1 1865 | (:path=/sample/path) 1867 Abs Ref Name Value 1868 ^-- acknowledged --^ 1869 1 0 :authority www.example.com 1870 2 0 :path /sample/path 1871 Size=106 1873 Stream: 4 1874 0381 | Required Insert Count = 2, Base = 0 1875 10 | Indexed Field Line With Post-Base Index 1876 | Absolute Index = Base(0) + Index(0) + 1 = 1 1877 | (:authority=www.example.com) 1878 11 | Indexed Field Line With Post-Base Index 1879 | Absolute Index = Base(0) + Index(1) + 1 = 2 1880 | (:path=/sample/path) 1882 Abs Ref Name Value 1883 ^-- acknowledged --^ 1884 1 1 :authority www.example.com 1885 2 1 :path /sample/path 1886 Size=106 1888 Stream: Decoder 1889 84 | Section Acknowledgement (stream=4) 1891 Abs Ref Name Value 1892 1 0 :authority www.example.com 1893 2 0 :path /sample/path 1894 ^-- acknowledged --^ 1895 Size=106 1897 B.3. Speculative Insert 1899 The encoder inserts a header into the dynamic table with a literal 1900 name. The decoder acknowledges receipt of the entry. The encoder 1901 does not send any encoded field sections. 1903 Stream: Encoder 1904 4a63 7573 746f 6d2d | Insert With Literal Name 1905 6b65 790c 6375 7374 | (custom-key=custom-value) 1906 6f6d 2d76 616c 7565 | 1908 Abs Ref Name Value 1909 1 0 :authority www.example.com 1910 2 0 :path /sample/path 1911 ^-- acknowledged --^ 1912 3 0 custom-key custom-value 1913 Size=160 1915 Stream: Decoder 1916 01 | Insert Count Increment (1) 1918 Abs Ref Name Value 1919 1 0 :authority www.example.com 1920 2 0 :path /sample/path 1921 3 0 custom-key custom-value 1922 ^-- acknowledged --^ 1923 Size=160 1925 B.4. Duplicate Instruction, Stream Cancellation 1927 The encoder duplicates an existing entry in the dynamic table, then 1928 sends an encoded field section referencing the dynamic table entries 1929 including the duplicated entry. The packet containing the encoder 1930 stream data is delayed. Before the packet arrives, the decoder 1931 cancels the stream and notifies the encoder that the encoded field 1932 section was not processed. 1934 Stream: Encoder 1935 02 | Duplicate (Relative Index=2) 1937 Abs Ref Name Value 1938 1 0 :authority www.example.com 1939 2 0 :path /sample/path 1940 3 0 custom-key custom-value 1941 ^-- acknowledged --^ 1942 4 0 :authority www.example.com 1943 Size=217 1945 Stream: 8 1946 0500 | Required Insert Count = 4, Base = 4 1947 80 | Indexed Field Line, Dynamic Table 1948 | Absolute Index = Base(4) - Index(0) = 4 1949 | (:authority=www.example.com) 1950 c1 | Indexed Field Line, Static Table Index = 1 1951 | (:path=/) 1952 81 | Indexed Field Line, Dynamic Table 1953 | Absolute Index = Base(4) - Index(1) = 3 1954 | (custom-key=custom-value) 1956 Abs Ref Name Value 1957 1 0 :authority www.example.com 1958 2 0 :path /sample/path 1959 3 1 custom-key custom-value 1960 ^-- acknowledged --^ 1961 4 1 :authority www.example.com 1962 Size=217 1964 Stream: Decoder 1965 48 | Stream Cancellation (Stream=8) 1967 Abs Ref Name Value 1968 1 0 :authority www.example.com 1969 2 0 :path /sample/path 1970 3 0 custom-key custom-value 1971 ^-- acknowledged --^ 1972 4 0 :authority www.example.com 1973 Size=215 1975 B.5. Dynamic Table Insert, Eviction 1977 The encoder inserts another header into the dynamic table, which 1978 evicts the oldest entry. The encoder does not send any encoded field 1979 sections. 1981 Stream: Encoder 1982 810d 6375 7374 6f6d | Insert With Name Reference 1983 2d76 616c 7565 32 | Dynamic Table, Absolute Index=2 1984 | (custom-key=custom-value2) 1986 Abs Ref Name Value 1987 2 0 :path /sample/path 1988 3 0 custom-key custom-value 1989 ^-- acknowledged --^ 1990 4 0 :authority www.example.com 1991 5 0 custom-key custom-value2 1992 Size=215 1994 Appendix C. Sample One Pass Encoding Algorithm 1996 Pseudo-code for single pass encoding, excluding handling of 1997 duplicates, non-blocking mode, available encoder stream flow control 1998 and reference tracking. 2000 base = dynamicTable.getInsertCount() 2001 requiredInsertCount = 0 2002 for line in field_lines: 2003 staticIndex = staticTable.findIndex(line) 2004 if staticIndex is not None: 2005 encodeIndexReference(streamBuffer, staticIndex) 2006 continue 2008 dynamicIndex = dynamicTable.findIndex(line) 2009 if dynamicIndex is None: 2010 # No matching entry. Either insert+index or encode literal 2011 staticNameIndex = staticTable.findName(line.name) 2012 if staticNameIndex is None: 2013 dynamicNameIndex = dynamicTable.findName(line.name) 2015 if shouldIndex(line) and dynamicTable.canIndex(line): 2016 encodeInsert(encoderBuffer, staticNameIndex, 2017 dynamicNameIndex, line) 2018 dynamicIndex = dynamicTable.add(line) 2020 if dynamicIndex is None: 2021 # Could not index it, literal 2022 if dynamicNameIndex is not None: 2023 # Encode literal with dynamic name, possibly above base 2024 encodeDynamicLiteral(streamBuffer, dynamicNameIndex, 2025 base, line) 2026 requiredInsertCount = max(requiredInsertCount, 2027 dynamicNameIndex) 2028 else: 2030 # Encodes a literal with a static name or literal name 2031 encodeLiteral(streamBuffer, staticNameIndex, line) 2032 else: 2033 # Dynamic index reference 2034 assert(dynamicIndex is not None) 2035 requiredInsertCount = max(requiredInsertCount, dynamicIndex) 2036 # Encode dynamicIndex, possibly above base 2037 encodeDynamicIndexReference(streamBuffer, dynamicIndex, base) 2039 # encode the prefix 2040 if requiredInsertCount == 0: 2041 encodeIndexReference(prefixBuffer, 0, 0, 8) 2042 encodeIndexReference(prefixBuffer, 0, 0, 7) 2043 else: 2044 wireRIC = ( 2045 requiredInsertCount 2046 % (2 * getMaxEntries(maxTableCapacity)) 2047 ) + 1; 2048 encodeInteger(prefixBuffer, 0x00, wireRIC, 8) 2049 if base >= requiredInsertCount: 2050 encodeInteger(prefixBuffer, 0, base - requiredInsertCount, 7) 2051 else: 2052 encodeInteger(prefixBuffer, 0x80, 2053 requiredInsertCount - base - 1, 7) 2055 return encoderBuffer, prefixBuffer + streamBuffer 2057 Appendix D. Change Log 2059 *RFC Editor's Note:* Please remove this section prior to 2060 publication of a final version of this document. 2062 D.1. Since draft-ietf-quic-qpack-18 2064 Editorial changes only 2066 D.2. Since draft-ietf-quic-qpack-17 2068 Editorial changes only 2070 D.3. Since draft-ietf-quic-qpack-16 2072 Editorial changes only 2074 D.4. Since draft-ietf-quic-qpack-15 2076 No changes 2078 D.5. Since draft-ietf-quic-qpack-14 2080 Added security considerations 2082 D.6. Since draft-ietf-quic-qpack-13 2084 No changes 2086 D.7. Since draft-ietf-quic-qpack-12 2088 Editorial changes only 2090 D.8. Since draft-ietf-quic-qpack-11 2092 Editorial changes only 2094 D.9. Since draft-ietf-quic-qpack-10 2096 Editorial changes only 2098 D.10. Since draft-ietf-quic-qpack-09 2100 * Decoders MUST emit Header Acknowledgements (#2939) 2102 * Updated error code for multiple encoder or decoder streams (#2970) 2104 * Added explicit defaults for new SETTINGS (#2974) 2106 D.11. Since draft-ietf-quic-qpack-08 2108 * Endpoints are permitted to create encoder and decoder streams even 2109 if they can't use them (#2100, #2529) 2111 * Maximum values for settings removed (#2766, #2767) 2113 D.12. Since draft-ietf-quic-qpack-06 2115 * Clarify initial dynamic table capacity maximums (#2276, #2330, 2116 #2330) 2118 D.13. Since draft-ietf-quic-qpack-05 2120 * Introduced the terms dynamic table capacity and maximum dynamic 2121 table capacity. 2123 * Renamed SETTINGS_HEADER_TABLE_SIZE to 2124 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 2126 D.14. Since draft-ietf-quic-qpack-04 2128 * Changed calculation of Delta Base Index to avoid an illegal value 2129 (#2002, #2005) 2131 D.15. Since draft-ietf-quic-qpack-03 2133 * Change HTTP settings defaults (#2038) 2135 * Substantial editorial reorganization 2137 D.16. Since draft-ietf-quic-qpack-02 2139 * Largest Reference encoded modulo MaxEntries (#1763) 2141 * New Static Table (#1355) 2143 * Table Size Update with Insert Count=0 is a connection error 2144 (#1762) 2146 * Stream Cancellations are optional when 2147 SETTINGS_HEADER_TABLE_SIZE=0 (#1761) 2149 * Implementations must handle 62 bit integers (#1760) 2151 * Different error types for each QPACK stream, other changes to 2152 error handling (#1726) 2154 * Preserve header field order (#1725) 2156 * Initial table size is the maximum permitted when table is first 2157 usable (#1642) 2159 D.17. Since draft-ietf-quic-qpack-01 2161 * Only header blocks that reference the dynamic table are 2162 acknowledged (#1603, #1605) 2164 D.18. Since draft-ietf-quic-qpack-00 2166 * Renumbered instructions for consistency (#1471, #1472) 2168 * Decoder is allowed to validate largest reference (#1404, #1469) 2170 * Header block acknowledgments also acknowledge the associated 2171 largest reference (#1370, #1400) 2173 * Added an acknowledgment for unread streams (#1371, #1400) 2174 * Removed framing from encoder stream (#1361,#1467) 2176 * Control streams use typed unidirectional streams rather than fixed 2177 stream IDs (#910,#1359) 2179 D.19. Since draft-ietf-quic-qcram-00 2181 * Separate instruction sets for table updates and header blocks 2182 (#1235, #1142, #1141) 2184 * Reworked indexing scheme (#1176, #1145, #1136, #1130, #1125, 2185 #1314) 2187 * Added mechanisms that support one-pass encoding (#1138, #1320) 2189 * Added a setting to control the number of blocked decoders (#238, 2190 #1140, #1143) 2192 * Moved table updates and acknowledgments to dedicated streams 2193 (#1121, #1122, #1238) 2195 Acknowledgments 2197 The IETF QUIC Working Group received an enormous amount of support 2198 from many people. 2200 The compression design team did substantial work exploring the 2201 problem space and influencing the initial draft. The contributions 2202 of design team members Roberto Peon, Martin Thomson, and Dmitri 2203 Tikhonov are gratefully acknowledged. 2205 The following people also provided substantial contributions to this 2206 document: 2208 * Bence Beky 2210 * Alessandro Ghedini 2212 * Ryan Hamilton 2214 * Robin Marx 2216 * Patrick McManus 2218 * 奥 一穂 (Kazuho Oku) 2220 * Lucas Pardue 2221 * Biren Roy 2223 * Ian Swett 2225 This draft draws heavily on the text of [RFC7541]. The indirect 2226 input of those authors is also gratefully acknowledged. 2228 Buck's contribution was supported by Google during his employment 2229 there. 2231 A portion of Mike's contribution was supported by Microsoft during 2232 his employment there. 2234 Authors' Addresses 2236 Charles 'Buck' Krasic 2237 Netflix 2239 Email: ckrasic@netflix.com 2241 Mike Bishop 2242 Akamai Technologies 2244 Email: mbishop@evequefou.be 2246 Alan Frindell (editor) 2247 Facebook 2249 Email: afrind@fb.com