idnits 2.17.1 draft-ietf-quic-qpack-20.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 1871 has weird spacing: '...thority www.e...' == Line 1886 has weird spacing: '...thority www.e...' == Line 1894 has weird spacing: '...thority www.e...' == Line 1911 has weird spacing: '...thority www.e...' == Line 1914 has weird spacing: '...tom-key custo...' == (14 more instances...) -- The document date (15 December 2020) is 1227 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-33 == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-33 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-13 -- 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: 18 June 2021 Akamai Technologies 6 A. Frindell, Ed. 7 Facebook 8 15 December 2020 10 QPACK: Header Compression for HTTP/3 11 draft-ietf-quic-qpack-20 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 18 June 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 . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . . 26 111 7.1. Probing Dynamic Table State . . . . . . . . . . . . . . . 27 112 7.1.1. Applicability to QPACK and HTTP . . . . . . . . . . . 27 113 7.1.2. Mitigation . . . . . . . . . . . . . . . . . . . . . 28 114 7.1.3. Never-Indexed Literals . . . . . . . . . . . . . . . 29 115 7.2. Static Huffman Encoding . . . . . . . . . . . . . . . . . 30 116 7.3. Memory Consumption . . . . . . . . . . . . . . . . . . . 30 117 7.4. 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-19 . . . . . . . . . . . . . 45 135 D.2. Since draft-ietf-quic-qpack-18 . . . . . . . . . . . . . 45 136 D.3. Since draft-ietf-quic-qpack-17 . . . . . . . . . . . . . 45 137 D.4. Since draft-ietf-quic-qpack-16 . . . . . . . . . . . . . 45 138 D.5. Since draft-ietf-quic-qpack-15 . . . . . . . . . . . . . 46 139 D.6. Since draft-ietf-quic-qpack-14 . . . . . . . . . . . . . 46 140 D.7. Since draft-ietf-quic-qpack-13 . . . . . . . . . . . . . 46 141 D.8. Since draft-ietf-quic-qpack-12 . . . . . . . . . . . . . 46 142 D.9. Since draft-ietf-quic-qpack-11 . . . . . . . . . . . . . 46 143 D.10. Since draft-ietf-quic-qpack-10 . . . . . . . . . . . . . 46 144 D.11. Since draft-ietf-quic-qpack-09 . . . . . . . . . . . . . 46 145 D.12. Since draft-ietf-quic-qpack-08 . . . . . . . . . . . . . 46 146 D.13. Since draft-ietf-quic-qpack-06 . . . . . . . . . . . . . 46 147 D.14. Since draft-ietf-quic-qpack-05 . . . . . . . . . . . . . 46 148 D.15. Since draft-ietf-quic-qpack-04 . . . . . . . . . . . . . 47 149 D.16. Since draft-ietf-quic-qpack-03 . . . . . . . . . . . . . 47 150 D.17. Since draft-ietf-quic-qpack-02 . . . . . . . . . . . . . 47 151 D.18. Since draft-ietf-quic-qpack-01 . . . . . . . . . . . . . 47 152 D.19. Since draft-ietf-quic-qpack-00 . . . . . . . . . . . . . 47 153 D.20. Since draft-ietf-quic-qcram-00 . . . . . . . . . . . . . 48 154 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 48 155 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49 157 1. Introduction 159 The QUIC transport protocol ([QUIC-TRANSPORT]) is designed to support 160 HTTP semantics, and its design subsumes many of the features of 161 HTTP/2 ([RFC7540]). HTTP/2 uses HPACK ([RFC7541]) for compression of 162 the header and trailer sections. If HPACK were used for HTTP/3 163 ([HTTP3]), it would induce head-of-line blocking for field sections 164 due to built-in assumptions of a total ordering across frames on all 165 streams. 167 QPACK reuses core concepts from HPACK, but is redesigned to allow 168 correctness in the presence of out-of-order delivery, with 169 flexibility for implementations to balance between resilience against 170 head-of-line blocking and optimal compression ratio. The design 171 goals are to closely approach the compression ratio of HPACK with 172 substantially less head-of-line blocking under the same loss 173 conditions. 175 1.1. Conventions and Definitions 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 179 "OPTIONAL" in this document are to be interpreted as described in 180 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 181 capitals, as shown here. 183 Definitions of terms that are used in this document: 185 HTTP fields: Metadata sent as part of an HTTP message. The term 186 encompasses both header and trailer fields. Colloquially, the 187 term "headers" has often been used to refer to HTTP header fields 188 and trailer fields; this document uses "fields" for generality. 190 HTTP field line: A name-value pair sent as part of an HTTP field 191 section. See Sections 6.3 and Section 6.5 of [SEMANTICS]. 193 HTTP field value: Data associated with a field name, composed from 194 all field line values with that field name in that section, 195 concatenated together and separated with commas. 197 Field section: An ordered collection of HTTP field lines associated 198 with an HTTP message. A field section can contain multiple field 199 lines with the same name. It can also contain duplicate field 200 lines. An HTTP message can include both header field and trailer 201 field sections. 203 Representation: An instruction that represents a field line, 204 possibly by reference to the dynamic and static tables. 206 Encoder: An implementation that encodes field sections. 208 Decoder: An implementation that decodes encoded field sections. 210 Absolute Index: A unique index for each entry in the dynamic table. 212 Base: A reference point for relative and post-base indices. 213 Representations that reference dynamic table entries are relative 214 to a Base. 216 Insert Count: The total number of entries inserted in the dynamic 217 table. 219 QPACK is a name, not an acronym. 221 1.2. Notational Conventions 223 Diagrams use the format described in Section 3.1 of [RFC2360], with 224 the following additional conventions: 226 x (A) Indicates that x is A bits long 228 x (A+) Indicates that x uses the prefixed integer encoding defined 229 in Section 4.1.1, beginning with an A-bit prefix. 231 x ... Indicates that x is variable-length and extends to the end of 232 the region. 234 2. Compression Process Overview 236 Like HPACK, QPACK uses two tables for associating field lines 237 ("headers") to indices. The static table (Section 3.1) is predefined 238 and contains common header field lines (some of them with an empty 239 value). The dynamic table (Section 3.2) is built up over the course 240 of the connection and can be used by the encoder to index both header 241 and trailer field lines in the encoded field sections. 243 QPACK defines unidirectional streams for sending instructions from 244 encoder to decoder and vice versa. 246 2.1. Encoder 248 An encoder converts a header or trailer field section into a series 249 of representations by emitting either an indexed or a literal 250 representation for each field line in the list; see Section 4.5. 251 Indexed representations achieve high compression by replacing the 252 literal name and possibly the value with an index to either the 253 static or dynamic table. References to the static table and literal 254 representations do not require any dynamic state and never risk head- 255 of-line blocking. References to the dynamic table risk head-of-line 256 blocking if the encoder has not received an acknowledgement 257 indicating the entry is available at the decoder. 259 An encoder MAY insert any entry in the dynamic table it chooses; it 260 is not limited to field lines it is compressing. 262 QPACK preserves the ordering of field lines within each field 263 section. An encoder MUST emit field representations in the order 264 they appear in the input field section. 266 QPACK is designed to contain the more complex state tracking to the 267 encoder, while the decoder is relatively simple. 269 2.1.1. Limits on Dynamic Table Insertions 271 Inserting entries into the dynamic table might not be possible if the 272 table contains entries that cannot be evicted. 274 A dynamic table entry cannot be evicted immediately after insertion, 275 even if it has never been referenced. Once the insertion of a 276 dynamic table entry has been acknowledged and there are no 277 outstanding references to the entry in unacknowledged 278 representations, the entry becomes evictable. Note that references 279 on the encoder stream never preclude the eviction of an entry, 280 because those references are guaranteed to be processed before the 281 instruction evicting the entry. 283 If the dynamic table does not contain enough room for a new entry 284 without evicting other entries, and the entries that would be evicted 285 are not evictable, the encoder MUST NOT insert that entry into the 286 dynamic table (including duplicates of existing entries). In order 287 to avoid this, an encoder that uses the dynamic table has to keep 288 track of each dynamic table entry referenced by each field section 289 until those representations are acknowledged by the decoder; see 290 Section 4.4.1. 292 2.1.1.1. Avoiding Prohibited Insertions 294 To ensure that the encoder is not prevented from adding new entries, 295 the encoder can avoid referencing entries that are close to eviction. 296 Rather than reference such an entry, the encoder can emit a Duplicate 297 instruction (Section 4.3.4), and reference the duplicate instead. 299 Determining which entries are too close to eviction to reference is 300 an encoder preference. One heuristic is to target a fixed amount of 301 available space in the dynamic table: either unused space or space 302 that can be reclaimed by evicting non-blocking entries. To achieve 303 this, the encoder can maintain a draining index, which is the 304 smallest absolute index (Section 3.2.4) in the dynamic table that it 305 will emit a reference for. As new entries are inserted, the encoder 306 increases the draining index to maintain the section of the table 307 that it will not reference. If the encoder does not create new 308 references to entries with an absolute index lower than the draining 309 index, the number of unacknowledged references to those entries will 310 eventually become zero, allowing them to be evicted. 312 +--------+---------------------------------+----------+ 313 | Unused | Referenceable | Draining | 314 | Space | Entries | Entries | 315 +--------+---------------------------------+----------+ 316 ^ ^ ^ 317 | | | 318 Insertion Point Draining Index Dropping 319 Point 321 Figure 1: Draining Dynamic Table Entries 323 2.1.2. Blocked Streams 325 Because QUIC does not guarantee order between data on different 326 streams, a decoder might encounter a representation that references a 327 dynamic table entry that it has not yet received. 329 Each encoded field section contains a Required Insert Count 330 (Section 4.5.1), the lowest possible value for the Insert Count with 331 which the field section can be decoded. For a field section encoded 332 using references to the dynamic table, the Required Insert Count is 333 one larger than the largest absolute index of all referenced dynamic 334 table entries. For a field section encoded with no references to the 335 dynamic table, the Required Insert Count is zero. 337 When the decoder receives an encoded field section with a Required 338 Insert Count greater than its own Insert Count, the stream cannot be 339 processed immediately, and is considered "blocked"; see 340 Section 2.2.1. 342 The decoder specifies an upper bound on the number of streams that 343 can be blocked using the SETTINGS_QPACK_BLOCKED_STREAMS setting; see 344 Section 5. An encoder MUST limit the number of streams that could 345 become blocked to the value of SETTINGS_QPACK_BLOCKED_STREAMS at all 346 times. If a decoder encounters more blocked streams than it promised 347 to support, it MUST treat this as a connection error of type 348 QPACK_DECOMPRESSION_FAILED. 350 Note that the decoder might not become blocked on every stream that 351 risks becoming blocked. 353 An encoder can decide whether to risk having a stream become blocked. 354 If permitted by the value of SETTINGS_QPACK_BLOCKED_STREAMS, 355 compression efficiency can often be improved by referencing dynamic 356 table entries that are still in transit, but if there is loss or 357 reordering the stream can become blocked at the decoder. An encoder 358 can avoid the risk of blocking by only referencing dynamic table 359 entries that have been acknowledged, but this could mean using 360 literals. Since literals make the encoded field section larger, this 361 can result in the encoder becoming blocked on congestion or flow 362 control limits. 364 2.1.3. Avoiding Flow Control Deadlocks 366 Writing instructions on streams that are limited by flow control can 367 produce deadlocks. 369 A decoder might stop issuing flow control credit on the stream that 370 carries an encoded field section until the necessary updates are 371 received on the encoder stream. If the granting of flow control 372 credit on the encoder stream (or the connection as a whole) depends 373 on the consumption and release of data on the stream carrying the 374 encoded field section, a deadlock might result. 376 More generally, a stream containing a large instruction can become 377 deadlocked if the decoder withholds flow control credit until the 378 instruction is completely received. 380 To avoid these deadlocks, an encoder SHOULD avoid writing an 381 instruction unless sufficient stream and connection flow control 382 credit is available for the entire instruction. 384 2.1.4. Known Received Count 386 The Known Received Count is the total number of dynamic table 387 insertions and duplications acknowledged by the decoder. The encoder 388 tracks the Known Received Count in order to identify which dynamic 389 table entries can be referenced without potentially blocking a 390 stream. The decoder tracks the Known Received Count in order to be 391 able to send Insert Count Increment instructions. 393 A Section Acknowledgement instruction (Section 4.4.1) implies that 394 the decoder has received all dynamic table state necessary to decode 395 the field section. If the Required Insert Count of the acknowledged 396 field section is greater than the current Known Received Count, Known 397 Received Count is updated to the value of the Required Insert Count. 399 An Insert Count Increment instruction (Section 4.4.3) increases the 400 Known Received Count by its Increment parameter. See Section 2.2.2.3 401 for guidance. 403 2.2. Decoder 405 As in HPACK, the decoder processes a series of representations and 406 emits the corresponding field sections. It also processes 407 instructions received on the encoder stream that modify the dynamic 408 table. Note that encoded field sections and encoder stream 409 instructions arrive on separate streams. This is unlike HPACK, where 410 encoded field sections (header blocks) can contain instructions that 411 modify the dynamic table, and there is no dedicated stream of HPACK 412 instructions. 414 The decoder MUST emit field lines in the order their representations 415 appear in the encoded field section. 417 2.2.1. Blocked Decoding 419 Upon receipt of an encoded field section, the decoder examines the 420 Required Insert Count. When the Required Insert Count is less than 421 or equal to the decoder's Insert Count, the field section can be 422 processed immediately. Otherwise, the stream on which the field 423 section was received becomes blocked. 425 While blocked, encoded field section data SHOULD remain in the 426 blocked stream's flow control window. A stream becomes unblocked 427 when the Insert Count becomes greater than or equal to the Required 428 Insert Count for all encoded field sections the decoder has started 429 reading from the stream. 431 When processing encoded field sections, the decoder expects the 432 Required Insert Count to equal the lowest possible value for the 433 Insert Count with which the field section can be decoded, as 434 prescribed in Section 2.1.2. If it encounters a Required Insert 435 Count smaller than expected, it MUST treat this as a connection error 436 of type QPACK_DECOMPRESSION_FAILED; see Section 2.2.3. If it 437 encounters a Required Insert Count larger than expected, it MAY treat 438 this as a connection error of type QPACK_DECOMPRESSION_FAILED. 440 2.2.2. State Synchronization 442 The decoder signals the following events by emitting decoder 443 instructions (Section 4.4) on the decoder stream. 445 2.2.2.1. Completed Processing of a Field Section 447 After the decoder finishes decoding a field section encoded using 448 representations containing dynamic table references, it MUST emit a 449 Section Acknowledgement instruction (Section 4.4.1). A stream may 450 carry multiple field sections in the case of intermediate responses, 451 trailers, and pushed requests. The encoder interprets each 452 Section Acknowledgement instruction as acknowledging the earliest 453 unacknowledged field section containing dynamic table references sent 454 on the given stream. 456 2.2.2.2. Abandonment of a Stream 458 When an endpoint receives a stream reset before the end of a stream 459 or before all encoded field sections are processed on that stream, or 460 when it abandons reading of a stream, it generates a Stream 461 Cancellation instruction; see Section 4.4.2. This signals to the 462 encoder that all references to the dynamic table on that stream are 463 no longer outstanding. A decoder with a maximum dynamic table 464 capacity (Section 3.2.3) equal to zero MAY omit sending Stream 465 Cancellations, because the encoder cannot have any dynamic table 466 references. An encoder cannot infer from this instruction that any 467 updates to the dynamic table have been received. 469 The Section Acknowledgement and Stream Cancellation instructions 470 permit the encoder to remove references to entries in the dynamic 471 table. When an entry with absolute index lower than the Known 472 Received Count has zero references, then it is considered evictable; 473 see Section 2.1.1. 475 2.2.2.3. New Table Entries 477 After receiving new table entries on the encoder stream, the decoder 478 chooses when to emit Insert Count Increment instructions; see 479 Section 4.4.3. Emitting this instruction after adding each new 480 dynamic table entry will provide the timeliest feedback to the 481 encoder, but could be redundant with other decoder feedback. By 482 delaying an Insert Count Increment instruction, the decoder might be 483 able to coalesce multiple Insert Count Increment instructions, or 484 replace them entirely with Section Acknowledgements; see 485 Section 4.4.1. However, delaying too long may lead to compression 486 inefficiencies if the encoder waits for an entry to be acknowledged 487 before using it. 489 2.2.3. Invalid References 491 If the decoder encounters a reference in a field line representation 492 to a dynamic table entry that has already been evicted or that has an 493 absolute index greater than or equal to the declared Required Insert 494 Count (Section 4.5.1), it MUST treat this as a connection error of 495 type QPACK_DECOMPRESSION_FAILED. 497 If the decoder encounters a reference in an encoder instruction to a 498 dynamic table entry that has already been evicted, it MUST treat this 499 as a connection error of type QPACK_ENCODER_STREAM_ERROR. 501 3. Reference Tables 503 Unlike in HPACK, entries in the QPACK static and dynamic tables are 504 addressed separately. The following sections describe how entries in 505 each table are addressed. 507 3.1. Static Table 509 The static table consists of a predefined list of field lines, each 510 of which has a fixed index over time. Its entries are defined in 511 Appendix A. 513 All entries in the static table have a name and a value. However, 514 values can be empty (that is, have a length of 0). Each entry is 515 identified by a unique index. 517 Note that the QPACK static table is indexed from 0, whereas the HPACK 518 static table is indexed from 1. 520 When the decoder encounters an invalid static table index in a field 521 line representation it MUST treat this as a connection error of type 522 QPACK_DECOMPRESSION_FAILED. If this index is received on the encoder 523 stream, this MUST be treated as a connection error of type 524 QPACK_ENCODER_STREAM_ERROR. 526 3.2. Dynamic Table 528 The dynamic table consists of a list of field lines maintained in 529 first-in, first-out order. Each HTTP/3 endpoint holds a dynamic 530 table that is initially empty. Entries are added by encoder 531 instructions received on the encoder stream; see Section 4.3. 533 The dynamic table can contain duplicate entries (i.e., entries with 534 the same name and same value). Therefore, duplicate entries MUST NOT 535 be treated as an error by the decoder. 537 Dynamic table entries can have empty values. 539 3.2.1. Dynamic Table Size 541 The size of the dynamic table is the sum of the size of its entries. 543 The size of an entry is the sum of its name's length in bytes, its 544 value's length in bytes, and 32. The size of an entry is calculated 545 using the length of its name and value without Huffman encoding 546 applied. 548 3.2.2. Dynamic Table Capacity and Eviction 550 The encoder sets the capacity of the dynamic table, which serves as 551 the upper limit on its size. The initial capacity of the dynamic 552 table is zero. The encoder sends a Set Dynamic Table Capacity 553 instruction (Section 4.3.1) with a non-zero capacity to begin using 554 the dynamic table. 556 Before a new entry is added to the dynamic table, entries are evicted 557 from the end of the dynamic table until the size of the dynamic table 558 is less than or equal to (table capacity - size of new entry). The 559 encoder MUST NOT cause a dynamic table entry to be evicted unless 560 that entry is evictable; see Section 2.1.1. The new entry is then 561 added to the table. It is an error if the encoder attempts to add an 562 entry that is larger than the dynamic table capacity; the decoder 563 MUST treat this as a connection error of type 564 QPACK_ENCODER_STREAM_ERROR. 566 A new entry can reference an entry in the dynamic table that will be 567 evicted when adding this new entry into the dynamic table. 568 Implementations are cautioned to avoid deleting the referenced name 569 or value if the referenced entry is evicted from the dynamic table 570 prior to inserting the new entry. 572 Whenever the dynamic table capacity is reduced by the encoder 573 (Section 4.3.1), entries are evicted from the end of the dynamic 574 table until the size of the dynamic table is less than or equal to 575 the new table capacity. This mechanism can be used to completely 576 clear entries from the dynamic table by setting a capacity of 0, 577 which can subsequently be restored. 579 3.2.3. Maximum Dynamic Table Capacity 581 To bound the memory requirements of the decoder, the decoder limits 582 the maximum value the encoder is permitted to set for the dynamic 583 table capacity. In HTTP/3, this limit is determined by the value of 584 SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder; see Section 5. 585 The encoder MUST NOT set a dynamic table capacity that exceeds this 586 maximum, but it can choose to use a lower dynamic table capacity; see 587 Section 4.3.1. 589 For clients using 0-RTT data in HTTP/3, the server's maximum table 590 capacity is the remembered value of the setting, or zero if the value 591 was not previously sent. When the client's 0-RTT value of the 592 SETTING is zero, the server MAY set it to a non-zero value in its 593 SETTINGS frame. If the remembered value is non-zero, the server MUST 594 send the same non-zero value in its SETTINGS frame. If it specifies 595 any other value, or omits SETTINGS_QPACK_MAX_TABLE_CAPACITY from 596 SETTINGS, the encoder must treat this as a connection error of type 597 QPACK_DECODER_STREAM_ERROR. 599 For HTTP/3 servers and HTTP/3 clients when 0-RTT is not attempted or 600 is rejected, the maximum table capacity is 0 until the encoder 601 processes a SETTINGS frame with a non-zero value of 602 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 604 When the maximum table capacity is zero, the encoder MUST NOT insert 605 entries into the dynamic table, and MUST NOT send any encoder 606 instructions on the encoder stream. 608 3.2.4. Absolute Indexing 610 Each entry possesses an absolute index that is fixed for the lifetime 611 of that entry. The first entry inserted has an absolute index of 0; 612 indices increase by one with each insertion. 614 3.2.5. Relative Indexing 616 Relative indices begin at zero and increase in the opposite direction 617 from the absolute index. Determining which entry has a relative 618 index of 0 depends on the context of the reference. 620 In encoder instructions (Section 4.3), a relative index of 0 refers 621 to the most recently inserted value in the dynamic table. Note that 622 this means the entry referenced by a given relative index will change 623 while interpreting instructions on the encoder stream. 625 +-----+---------------+-------+ 626 | n-1 | ... | d | Absolute Index 627 + - - +---------------+ - - - + 628 | 0 | ... | n-d-1 | Relative Index 629 +-----+---------------+-------+ 630 ^ | 631 | V 632 Insertion Point Dropping Point 634 n = count of entries inserted 635 d = count of entries dropped 637 Figure 2: Example Dynamic Table Indexing - Encoder Stream 639 Unlike in encoder instructions, relative indices in field line 640 representations are relative to the Base at the beginning of the 641 encoded field section; see Section 4.5.1. This ensures that 642 references are stable even if encoded field sections and dynamic 643 table updates are processed out of order. 645 In a field line representation, a relative index of 0 refers to the 646 entry with absolute index equal to Base - 1. 648 Base 649 | 650 V 651 +-----+-----+-----+-----+-------+ 652 | n-1 | n-2 | n-3 | ... | d | Absolute Index 653 +-----+-----+ - +-----+ - + 654 | 0 | ... | n-d-3 | Relative Index 655 +-----+-----+-------+ 657 n = count of entries inserted 658 d = count of entries dropped 659 In this example, Base = n - 2 660 Figure 3: Example Dynamic Table Indexing - Relative Index in 661 Representation 663 3.2.6. Post-Base Indexing 665 Post-Base indices are used in field line representations for entries 666 with absolute indices greater than or equal to Base, starting at 0 667 for the entry with absolute index equal to Base, and increasing in 668 the same direction as the absolute index. 670 Post-Base indices allow an encoder to process a field section in a 671 single pass and include references to entries added while processing 672 this (or other) field sections. 674 Base 675 | 676 V 677 +-----+-----+-----+-----+-----+ 678 | n-1 | n-2 | n-3 | ... | d | Absolute Index 679 +-----+-----+-----+-----+-----+ 680 | 1 | 0 | Post-Base Index 681 +-----+-----+ 683 n = count of entries inserted 684 d = count of entries dropped 685 In this example, Base = n - 2 687 Figure 4: Example Dynamic Table Indexing - Post-Base Index in 688 Representation 690 4. Wire Format 692 4.1. Primitives 694 4.1.1. Prefixed Integers 696 The prefixed integer from Section 5.1 of [RFC7541] is used heavily 697 throughout this document. The format from [RFC7541] is used 698 unmodified. Note, however, that QPACK uses some prefix sizes not 699 actually used in HPACK. 701 QPACK implementations MUST be able to decode integers up to and 702 including 62 bits long. 704 4.1.2. String Literals 706 The string literal defined by Section 5.2 of [RFC7541] is also used 707 throughout. This string format includes optional Huffman encoding. 709 HPACK defines string literals to begin on a byte boundary. They 710 begin with a single bit flag, denoted as 'H' in this document 711 (indicating whether the string is Huffman-coded), followed by the 712 Length encoded as a 7-bit prefix integer, and finally Length bytes of 713 data. When Huffman encoding is enabled, the Huffman table from 714 Appendix B of [RFC7541] is used without modification and Length 715 indicates the size of the string after encoding. 717 This document expands the definition of string literals by permitting 718 them to begin other than on a byte boundary. An "N-bit prefix string 719 literal" begins mid-byte, with the first (8-N) bits allocated to a 720 previous field. The string uses one bit for the Huffman flag, 721 followed by the Length encoded as an (N-1)-bit prefix integer. The 722 prefix size, N, can have a value between 2 and 8 inclusive. The 723 remainder of the string literal is unmodified. 725 A string literal without a prefix length noted is an 8-bit prefix 726 string literal and follows the definitions in [RFC7541] without 727 modification. 729 4.2. Encoder and Decoder Streams 731 QPACK defines two unidirectional stream types: 733 * An encoder stream is a unidirectional stream of type 0x02. It 734 carries an unframed sequence of encoder instructions from encoder 735 to decoder. 737 * A decoder stream is a unidirectional stream of type 0x03. It 738 carries an unframed sequence of decoder instructions from decoder 739 to encoder. 741 HTTP/3 endpoints contain a QPACK encoder and decoder. Each endpoint 742 MUST initiate at most one encoder stream and at most one decoder 743 stream. Receipt of a second instance of either stream type MUST be 744 treated as a connection error of type H3_STREAM_CREATION_ERROR. 746 These streams MUST NOT be closed. Closure of either unidirectional 747 stream type MUST be treated as a connection error of type 748 H3_CLOSED_CRITICAL_STREAM. 750 An endpoint MAY avoid creating an encoder stream if it will not be 751 used (for example if its encoder does not wish to use the dynamic 752 table, or if the maximum size of the dynamic table permitted by the 753 peer is zero). 755 An endpoint MAY avoid creating a decoder stream if its decoder sets 756 the maximum capacity of the dynamic table to zero. 758 An endpoint MUST allow its peer to create an encoder stream and a 759 decoder stream even if the connection's settings prevent their use. 761 4.3. Encoder Instructions 763 An encoder sends encoder instructions on the encoder stream to set 764 the capacity of the dynamic table and add dynamic table entries. 765 Instructions adding table entries can use existing entries to avoid 766 transmitting redundant information. The name can be transmitted as a 767 reference to an existing entry in the static or the dynamic table or 768 as a string literal. For entries that already exist in the dynamic 769 table, the full entry can also be used by reference, creating a 770 duplicate entry. 772 4.3.1. Set Dynamic Table Capacity 774 An encoder informs the decoder of a change to the dynamic table 775 capacity using an instruction that starts with the '001' 3-bit 776 pattern. This is followed by the new dynamic table capacity 777 represented as an integer with a 5-bit prefix; see Section 4.1.1. 779 0 1 2 3 4 5 6 7 780 +---+---+---+---+---+---+---+---+ 781 | 0 | 0 | 1 | Capacity (5+) | 782 +---+---+---+-------------------+ 784 Figure 5: Set Dynamic Table Capacity 786 The new capacity MUST be lower than or equal to the limit described 787 in Section 3.2.3. In HTTP/3, this limit is the value of the 788 SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter (Section 5) received from 789 the decoder. The decoder MUST treat a new dynamic table capacity 790 value that exceeds this limit as a connection error of type 791 QPACK_ENCODER_STREAM_ERROR. 793 Reducing the dynamic table capacity can cause entries to be evicted; 794 see Section 3.2.2. This MUST NOT cause the eviction of entries that 795 are not evictable; see Section 2.1.1. Changing the capacity of the 796 dynamic table is not acknowledged as this instruction does not insert 797 an entry. 799 4.3.2. Insert With Name Reference 801 An encoder adds an entry to the dynamic table where the field name 802 matches the field name of an entry stored in the static or the 803 dynamic table using an instruction that starts with the '1' 1-bit 804 pattern. The second ('T') bit indicates whether the reference is to 805 the static or dynamic table. The 6-bit prefix integer 806 (Section 4.1.1) that follows is used to locate the table entry for 807 the field name. When T=1, the number represents the static table 808 index; when T=0, the number is the relative index of the entry in the 809 dynamic table. 811 The field name reference is followed by the field value represented 812 as a string literal; see Section 4.1.2. 814 0 1 2 3 4 5 6 7 815 +---+---+---+---+---+---+---+---+ 816 | 1 | T | Name Index (6+) | 817 +---+---+-----------------------+ 818 | H | Value Length (7+) | 819 +---+---------------------------+ 820 | Value String (Length bytes) | 821 +-------------------------------+ 823 Figure 6: Insert Field Line -- Indexed Name 825 4.3.3. Insert With Literal Name 827 An encoder adds an entry to the dynamic table where both the field 828 name and the field value are represented as string literals using an 829 instruction that starts with the '01' 2-bit pattern. 831 This is followed by the name represented as a 6-bit prefix string 832 literal, and the value represented as an 8-bit prefix string literal; 833 see Section 4.1.2. 835 0 1 2 3 4 5 6 7 836 +---+---+---+---+---+---+---+---+ 837 | 0 | 1 | H | Name Length (5+) | 838 +---+---+---+-------------------+ 839 | Name String (Length bytes) | 840 +---+---------------------------+ 841 | H | Value Length (7+) | 842 +---+---------------------------+ 843 | Value String (Length bytes) | 844 +-------------------------------+ 846 Figure 7: Insert Field Line -- New Name 848 4.3.4. Duplicate 850 An encoder duplicates an existing entry in the dynamic table using an 851 instruction that starts with the '000' 3-bit pattern. This is 852 followed by the relative index of the existing entry represented as 853 an integer with a 5-bit prefix; see Section 4.1.1. 855 0 1 2 3 4 5 6 7 856 +---+---+---+---+---+---+---+---+ 857 | 0 | 0 | 0 | Index (5+) | 858 +---+---+---+-------------------+ 860 Figure 8: Duplicate 862 The existing entry is re-inserted into the dynamic table without 863 resending either the name or the value. This is useful to avoid 864 adding a reference to an older entry, which might block inserting new 865 entries. 867 4.4. Decoder Instructions 869 A decoder sends decoder instructions on the decoder stream to inform 870 the encoder about the processing of field sections and table updates 871 to ensure consistency of the dynamic table. 873 4.4.1. Section Acknowledgement 875 After processing an encoded field section whose declared Required 876 Insert Count is not zero, the decoder emits a Section Acknowledgement 877 instruction. The instruction starts with the '1' 1-bit pattern, 878 followed by the field section's associated stream ID encoded as a 879 7-bit prefix integer; see Section 4.1.1. 881 This instruction is used as described in Section 2.1.4 and in 882 Section 2.2.2. 884 0 1 2 3 4 5 6 7 885 +---+---+---+---+---+---+---+---+ 886 | 1 | Stream ID (7+) | 887 +---+---------------------------+ 889 Figure 9: Section Acknowledgement 891 If an encoder receives a Section Acknowledgement instruction 892 referring to a stream on which every encoded field section with a 893 non-zero Required Insert Count has already been acknowledged, this 894 MUST be treated as a connection error of type 895 QPACK_DECODER_STREAM_ERROR. 897 The Section Acknowledgement instruction might increase the Known 898 Received Count; see Section 2.1.4. 900 4.4.2. Stream Cancellation 902 When a stream is reset or reading is abandoned, the decoder emits a 903 Stream Cancellation instruction. The instruction starts with the 904 '01' 2-bit pattern, followed by the stream ID of the affected stream 905 encoded as a 6-bit prefix integer. 907 This instruction is used as described in Section 2.2.2. 909 0 1 2 3 4 5 6 7 910 +---+---+---+---+---+---+---+---+ 911 | 0 | 1 | Stream ID (6+) | 912 +---+---+-----------------------+ 914 Figure 10: Stream Cancellation 916 4.4.3. Insert Count Increment 918 The Insert Count Increment instruction starts with the '00' 2-bit 919 pattern, followed by the Increment encoded as a 6-bit prefix integer. 920 This instruction increases the Known Received Count (Section 2.1.4) 921 by the value of the Increment parameter. The decoder should send an 922 Increment value that increases the Known Received Count to the total 923 number of dynamic table insertions and duplications processed so far. 925 0 1 2 3 4 5 6 7 926 +---+---+---+---+---+---+---+---+ 927 | 0 | 0 | Increment (6+) | 928 +---+---+-----------------------+ 930 Figure 11: Insert Count Increment 932 An encoder that receives an Increment field equal to zero, or one 933 that increases the Known Received Count beyond what the encoder has 934 sent MUST treat this as a connection error of type 935 QPACK_DECODER_STREAM_ERROR. 937 4.5. Field Line Representations 939 An encoded field section consists of a prefix and a possibly empty 940 sequence of representations defined in this section. Each 941 representation corresponds to a single field line. These 942 representations reference the static table or the dynamic table in a 943 particular state, but do not modify that state. 945 Encoded field sections are carried in frames on streams defined by 946 the enclosing protocol. 948 4.5.1. Encoded Field Section Prefix 950 Each encoded field section is prefixed with two integers. The 951 Required Insert Count is encoded as an integer with an 8-bit prefix 952 using the encoding described in Section 4.5.1.1. The Base is encoded 953 as a sign bit ('S') and a Delta Base value with a 7-bit prefix; see 954 Section 4.5.1.2. 956 0 1 2 3 4 5 6 7 957 +---+---+---+---+---+---+---+---+ 958 | Required Insert Count (8+) | 959 +---+---------------------------+ 960 | S | Delta Base (7+) | 961 +---+---------------------------+ 962 | Encoded Field Lines ... 963 +-------------------------------+ 965 Figure 12: Encoded Field Section 967 4.5.1.1. Required Insert Count 969 Required Insert Count identifies the state of the dynamic table 970 needed to process the encoded field section. Blocking decoders use 971 the Required Insert Count to determine when it is safe to process the 972 rest of the field section. 974 The encoder transforms the Required Insert Count as follows before 975 encoding: 977 if ReqInsertCount == 0: 978 EncInsertCount = 0 979 else: 980 EncInsertCount = (ReqInsertCount mod (2 * MaxEntries)) + 1 982 Here "MaxEntries" is the maximum number of entries that the dynamic 983 table can have. The smallest entry has empty name and value strings 984 and has the size of 32. Hence "MaxEntries" is calculated as 986 MaxEntries = floor( MaxTableCapacity / 32 ) 988 "MaxTableCapacity" is the maximum capacity of the dynamic table as 989 specified by the decoder; see Section 3.2.3. 991 This encoding limits the length of the prefix on long-lived 992 connections. 994 The decoder can reconstruct the Required Insert Count using an 995 algorithm such as the following. If the decoder encounters a value 996 of EncodedInsertCount that could not have been produced by a 997 conformant encoder, it MUST treat this as a connection error of type 998 QPACK_DECOMPRESSION_FAILED. 1000 TotalNumberOfInserts is the total number of inserts into the 1001 decoder's dynamic table. 1003 FullRange = 2 * MaxEntries 1004 if EncodedInsertCount == 0: 1005 ReqInsertCount = 0 1006 else: 1007 if EncodedInsertCount > FullRange: 1008 Error 1009 MaxValue = TotalNumberOfInserts + MaxEntries 1011 # MaxWrapped is the largest possible value of 1012 # ReqInsertCount that is 0 mod 2*MaxEntries 1013 MaxWrapped = floor(MaxValue / FullRange) * FullRange 1014 ReqInsertCount = MaxWrapped + EncodedInsertCount - 1 1016 # If ReqInsertCount exceeds MaxValue, the Encoder's value 1017 # must have wrapped one fewer time 1018 if ReqInsertCount > MaxValue: 1019 if ReqInsertCount <= FullRange: 1020 Error 1021 ReqInsertCount -= FullRange 1023 # Value of 0 must be encoded as 0. 1024 if ReqInsertCount == 0: 1025 Error 1027 For example, if the dynamic table is 100 bytes, then the Required 1028 Insert Count will be encoded modulo 6. If a decoder has received 10 1029 inserts, then an encoded value of 4 indicates that the Required 1030 Insert Count is 9 for the field section. 1032 4.5.1.2. Base 1034 The Base is used to resolve references in the dynamic table as 1035 described in Section 3.2.5. 1037 To save space, the Base is encoded relative to the Required Insert 1038 Count using a one-bit sign ('S') and the Delta Base value. A sign 1039 bit of 0 indicates that the Base is greater than or equal to the 1040 value of the Required Insert Count; the decoder adds the value of 1041 Delta Base to the Required Insert Count to determine the value of the 1042 Base. A sign bit of 1 indicates that the Base is less than the 1043 Required Insert Count; the decoder subtracts the value of Delta Base 1044 from the Required Insert Count and also subtracts one to determine 1045 the value of the Base. That is: 1047 if S == 0: 1048 Base = ReqInsertCount + DeltaBase 1049 else: 1050 Base = ReqInsertCount - DeltaBase - 1 1052 A single-pass encoder determines the Base before encoding a field 1053 section. If the encoder inserted entries in the dynamic table while 1054 encoding the field section and is referencing them, Required Insert 1055 Count will be greater than the Base, so the encoded difference is 1056 negative and the sign bit is set to 1. If the field section was not 1057 encoded using representations that reference the most recent entry in 1058 the table and did not insert any new entries, the Base will be 1059 greater than the Required Insert Count, so the delta will be positive 1060 and the sign bit is set to 0. 1062 An encoder that produces table updates before encoding a field 1063 section might set Base to the value of Required Insert Count. In 1064 such case, both the sign bit and the Delta Base will be set to zero. 1066 A field section that was encoded without references to the dynamic 1067 table can use any value for the Base; setting Delta Base to zero is 1068 one of the most efficient encodings. 1070 For example, with a Required Insert Count of 9, a decoder receives an 1071 S bit of 1 and a Delta Base of 2. This sets the Base to 6 and 1072 enables post-base indexing for three entries. In this example, a 1073 relative index of 1 refers to the 5th entry that was added to the 1074 table; a post-base index of 1 refers to the 8th entry. 1076 4.5.2. Indexed Field Line 1078 An indexed field line representation identifies an entry in the 1079 static table, or an entry in the dynamic table with an absolute index 1080 less than the value of the Base. 1082 0 1 2 3 4 5 6 7 1083 +---+---+---+---+---+---+---+---+ 1084 | 1 | T | Index (6+) | 1085 +---+---+-----------------------+ 1087 Figure 13: Indexed Field Line 1089 This representation starts with the '1' 1-bit pattern, followed by 1090 the 'T' bit indicating whether the reference is into the static or 1091 dynamic table. The 6-bit prefix integer (Section 4.1.1) that follows 1092 is used to locate the table entry for the field line. When T=1, the 1093 number represents the static table index; when T=0, the number is the 1094 relative index of the entry in the dynamic table. 1096 4.5.3. Indexed Field Line With Post-Base Index 1098 An indexed field line with post-base index representation identifies 1099 an entry in the dynamic table with an absolute index greater than or 1100 equal to the value of the Base. 1102 0 1 2 3 4 5 6 7 1103 +---+---+---+---+---+---+---+---+ 1104 | 0 | 0 | 0 | 1 | Index (4+) | 1105 +---+---+---+---+---------------+ 1107 Figure 14: Indexed Field Line with Post-Base Index 1109 This representation starts with the '0001' 4-bit pattern. This is 1110 followed by the post-base index (Section 3.2.6) of the matching field 1111 line, represented as an integer with a 4-bit prefix; see 1112 Section 4.1.1. 1114 4.5.4. Literal Field Line With Name Reference 1116 A literal field line with name reference representation encodes a 1117 field line where the field name matches the field name of an entry in 1118 the static table, or the field name of an entry in the dynamic table 1119 with an absolute index less than the value of the Base. 1121 0 1 2 3 4 5 6 7 1122 +---+---+---+---+---+---+---+---+ 1123 | 0 | 1 | N | T |Name Index (4+)| 1124 +---+---+---+---+---------------+ 1125 | H | Value Length (7+) | 1126 +---+---------------------------+ 1127 | Value String (Length bytes) | 1128 +-------------------------------+ 1130 Figure 15: Literal Field Line With Name Reference 1132 This representation starts with the '01' 2-bit pattern. The 1133 following bit, 'N', indicates whether an intermediary is permitted to 1134 add this field line to the dynamic table on subsequent hops. When 1135 the 'N' bit is set, the encoded field line MUST always be encoded 1136 with a literal representation. In particular, when a peer sends a 1137 field line that it received represented as a literal field line with 1138 the 'N' bit set, it MUST use a literal representation to forward this 1139 field line. This bit is intended for protecting field values that 1140 are not to be put at risk by compressing them; see Section 7 for more 1141 details. 1143 The fourth ('T') bit indicates whether the reference is to the static 1144 or dynamic table. The 4-bit prefix integer (Section 4.1.1) that 1145 follows is used to locate the table entry for the field name. When 1146 T=1, the number represents the static table index; when T=0, the 1147 number is the relative index of the entry in the dynamic table. 1149 Only the field name is taken from the dynamic table entry; the field 1150 value is encoded as an 8-bit prefix string literal; see 1151 Section 4.1.2. 1153 4.5.5. Literal Field Line With Post-Base Name Reference 1155 A literal field line with post-base name reference representation 1156 encodes a field line where the field name matches the field name of a 1157 dynamic table entry with an absolute index greater than or equal to 1158 the value of the Base. 1160 0 1 2 3 4 5 6 7 1161 +---+---+---+---+---+---+---+---+ 1162 | 0 | 0 | 0 | 0 | N |NameIdx(3+)| 1163 +---+---+---+---+---+-----------+ 1164 | H | Value Length (7+) | 1165 +---+---------------------------+ 1166 | Value String (Length bytes) | 1167 +-------------------------------+ 1169 Figure 16: Literal Field Line With Post-Base Name Reference 1171 This representation starts with the '0000' 4-bit pattern. The fifth 1172 bit is the 'N' bit as described in Section 4.5.4. This is followed 1173 by a post-base index of the dynamic table entry (Section 3.2.6) 1174 encoded as an integer with a 3-bit prefix; see Section 4.1.1. 1176 Only the field name is taken from the dynamic table entry; the field 1177 value is encoded as an 8-bit prefix string literal; see 1178 Section 4.1.2. 1180 4.5.6. Literal Field Line With Literal Name 1182 The literal field line with literal name representation encodes a 1183 field name and a field value as string literals. 1185 0 1 2 3 4 5 6 7 1186 +---+---+---+---+---+---+---+---+ 1187 | 0 | 0 | 1 | N | H |NameLen(3+)| 1188 +---+---+---+---+---+-----------+ 1189 | Name String (Length bytes) | 1190 +---+---------------------------+ 1191 | H | Value Length (7+) | 1192 +---+---------------------------+ 1193 | Value String (Length bytes) | 1194 +-------------------------------+ 1196 Figure 17: Literal Field Line With Literal Name 1198 This representation starts with the '001' 3-bit pattern. The fourth 1199 bit is the 'N' bit as described in Section 4.5.4. The name follows, 1200 represented as a 4-bit prefix string literal, then the value, 1201 represented as an 8-bit prefix string literal; see 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.1.1. 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 to encode chosen field lines, then the 1292 attacker can learn the state of the table by observing the length of 1293 the encoded output. 1295 Having requests or responses from mutually distrustful entities 1296 occurs when an intermediary either: 1298 * sends requests from multiple clients on a single connection toward 1299 an origin server, or 1301 * takes responses from multiple origin servers and places them on a 1302 shared connection toward a client. 1304 Web browsers also need to assume that requests made on the same 1305 connection by different web origins ([RFC6454]) are made by mutually 1306 distrustful entities. 1308 7.1.2. Mitigation 1310 Users of HTTP that require confidentiality for header or trailer 1311 fields can use values with entropy sufficient to make guessing 1312 infeasible. However, this is impractical as a general solution 1313 because it forces all users of HTTP to take steps to mitigate 1314 attacks. It would impose new constraints on how HTTP is used. 1316 Rather than impose constraints on users of HTTP, an implementation of 1317 QPACK can instead constrain how compression is applied in order to 1318 limit the potential for dynamic table probing. 1320 An ideal solution segregates access to the dynamic table based on the 1321 entity that is constructing the message. Field values that are added 1322 to the table are attributed to an entity, and only the entity that 1323 created a particular value can extract that value. 1325 To improve compression performance of this option, certain entries 1326 might be tagged as being public. For example, a web browser might 1327 make the values of the Accept-Encoding header field available in all 1328 requests. 1330 An encoder without good knowledge of the provenance of field values 1331 might instead introduce a penalty for many field lines with the same 1332 field name and different values. This penalty could cause a large 1333 number of attempts to guess a field value to result in the field not 1334 being compared to the dynamic table entries in future messages, 1335 effectively preventing further guesses. 1337 Note: Simply removing entries corresponding to the field from the 1338 dynamic table can be ineffectual if the attacker has a reliable 1339 way of causing values to be reinstalled. For example, a request 1340 to load an image in a web browser typically includes the Cookie 1341 header field (a potentially highly valued target for this sort of 1342 attack), and web sites can easily force an image to be loaded, 1343 thereby refreshing the entry in the dynamic table. 1345 This response might be made inversely proportional to the length of 1346 the field value. Disabling access to the dynamic table for a given 1347 field name might occur for shorter values more quickly or with higher 1348 probability than for longer values. 1350 7.1.3. Never-Indexed Literals 1352 Implementations can also choose to protect sensitive fields by not 1353 compressing them and instead encoding their value as literals. 1355 Refusing to insert a field line into the dynamic table is only 1356 effective if doing so is avoided on all hops. The never-indexed 1357 literal bit (see Section 4.5.4) can be used to signal to 1358 intermediaries that a particular value was intentionally sent as a 1359 literal. 1361 An intermediary MUST NOT re-encode a value that uses a literal 1362 representation with the 'N' bit set with another representation that 1363 would index it. If QPACK is used for re-encoding, a literal 1364 representation with the 'N' bit set MUST be used. If HPACK is used 1365 for re-encoding, the never-indexed literal representation (see 1366 Section 6.2.3 of [RFC7541]) MUST be used. 1368 The choice to mark that a field value should never be indexed depends 1369 on several factors. Since QPACK does not protect against guessing an 1370 entire field value, short or low-entropy values are more readily 1371 recovered by an adversary. Therefore, an encoder might choose not to 1372 index values with low entropy. 1374 An encoder might also choose not to index values for fields that are 1375 considered to be highly valuable or sensitive to recovery, such as 1376 the Cookie or Authorization header fields. 1378 On the contrary, an encoder might prefer indexing values for fields 1379 that have little or no value if they were exposed. For instance, a 1380 User-Agent header field does not commonly vary between requests and 1381 is sent to any server. In that case, confirmation that a particular 1382 User-Agent value has been used provides little value. 1384 Note that these criteria for deciding to use a never-indexed literal 1385 representation will evolve over time as new attacks are discovered. 1387 7.2. Static Huffman Encoding 1389 There is no currently known attack against a static Huffman encoding. 1390 A study has shown that using a static Huffman encoding table created 1391 an information leakage, however this same study concluded that an 1392 attacker could not take advantage of this information leakage to 1393 recover any meaningful amount of information (see [PETAL]). 1395 7.3. Memory Consumption 1397 An attacker can try to cause an endpoint to exhaust its memory. 1398 QPACK is designed to limit both the peak and stable amounts of memory 1399 allocated by an endpoint. 1401 The amount of memory used by the encoder is limited by the protocol 1402 using QPACK through the definition of the maximum size of the dynamic 1403 table, and the maximum number of blocking streams. In HTTP/3, these 1404 values are controlled by the decoder through the settings parameters 1405 SETTINGS_QPACK_MAX_TABLE_CAPACITY and SETTINGS_QPACK_BLOCKED_STREAMS, 1406 respectively (see Section 3.2.3 and Section 2.1.2). The limit on the 1407 size of the dynamic table takes into account the size of the data 1408 stored in the dynamic table, plus a small allowance for overhead. 1409 The limit on the number of blocked streams is only a proxy for the 1410 maximum amount of memory required by the decoder. The actual maximum 1411 amount of memory will depend on how much memory the decoder uses to 1412 track each blocked stream. 1414 A decoder can limit the amount of state memory used for the dynamic 1415 table by setting an appropriate value for the maximum size of the 1416 dynamic table. In HTTP/3, this is realized by setting an appropriate 1417 value for the SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter. An 1418 encoder can limit the amount of state memory it uses by signaling a 1419 lower dynamic table size than the decoder allows (see Section 3.2.2). 1421 A decoder can limit the amount of state memory used for blocked 1422 streams by setting an appropriate value for the maximum number of 1423 blocked streams. In HTTP/3, this is realized by setting an 1424 appropriate value for the QPACK_BLOCKED_STREAMS parameter. Streams 1425 which risk becoming blocked consume no additional state memory on the 1426 encoder. 1428 An encoder allocates memory to track all dynamic table references in 1429 unacknowledged field sections. An implementation can directly limit 1430 the amount of state memory by only using as many references to the 1431 dynamic table as it wishes to track; no signaling to the decoder is 1432 required. However, limiting references to the dynamic table will 1433 reduce compression effectiveness. 1435 The amount of temporary memory consumed by an encoder or decoder can 1436 be limited by processing field lines sequentially. A decoder 1437 implementation does not need to retain a complete list of field lines 1438 while decoding a field section. An encoder implementation does not 1439 need to retain a complete list of field lines while encoding a field 1440 section if it is using a single-pass algorithm. Note that it might 1441 be necessary for an application to retain a complete list of field 1442 lines for other reasons; even if QPACK does not force this to occur, 1443 application constraints might make this necessary. 1445 While the negotiated limit on the dynamic table size accounts for 1446 much of the memory that can be consumed by a QPACK implementation, 1447 data that cannot be immediately sent due to flow control is not 1448 affected by this limit. Implementations should limit the size of 1449 unsent data, especially on the decoder stream where flexibility to 1450 choose what to send is limited. Possible responses to an excess of 1451 unsent data might include limiting the ability of the peer to open 1452 new streams, reading only from the encoder stream, or closing the 1453 connection. 1455 7.4. Implementation Limits 1457 An implementation of QPACK needs to ensure that large values for 1458 integers, long encoding for integers, or long string literals do not 1459 create security weaknesses. 1461 An implementation has to set a limit for the values it accepts for 1462 integers, as well as for the encoded length; see Section 4.1.1. In 1463 the same way, it has to set a limit to the length it accepts for 1464 string literals; see Section 4.1.2. 1466 8. IANA Considerations 1468 8.1. Settings Registration 1470 This document specifies two settings. The entries in the following 1471 table are registered in the "HTTP/3 Settings" registry established in 1472 [HTTP3]. 1474 +==========================+======+===============+=========+ 1475 | Setting Name | Code | Specification | Default | 1476 +==========================+======+===============+=========+ 1477 | QPACK_MAX_TABLE_CAPACITY | 0x1 | Section 5 | 0 | 1478 +--------------------------+------+---------------+---------+ 1479 | QPACK_BLOCKED_STREAMS | 0x7 | Section 5 | 0 | 1480 +--------------------------+------+---------------+---------+ 1482 Table 1 1484 8.2. Stream Type Registration 1486 This document specifies two stream types. The entries in the 1487 following table are registered in the "HTTP/3 Stream Type" registry 1488 established in [HTTP3]. 1490 +======================+======+===============+========+ 1491 | Stream Type | Code | Specification | Sender | 1492 +======================+======+===============+========+ 1493 | QPACK Encoder Stream | 0x02 | Section 4.2 | Both | 1494 +----------------------+------+---------------+--------+ 1495 | QPACK Decoder Stream | 0x03 | Section 4.2 | Both | 1496 +----------------------+------+---------------+--------+ 1498 Table 2 1500 8.3. Error Code Registration 1502 This document specifies three error codes. The entries in the 1503 following table are registered in the "HTTP/3 Error Code" registry 1504 established in [HTTP3]. 1506 +============================+=======+=============+===============+ 1507 | Name | Code | Description | Specification | 1508 +============================+=======+=============+===============+ 1509 | QPACK_DECOMPRESSION_FAILED | 0x200 | Decoding of | Section 6 | 1510 | | | a field | | 1511 | | | section | | 1512 | | | failed | | 1513 +----------------------------+-------+-------------+---------------+ 1514 | QPACK_ENCODER_STREAM_ERROR | 0x201 | Error on | Section 6 | 1515 | | | the encoder | | 1516 | | | stream | | 1517 +----------------------------+-------+-------------+---------------+ 1518 | QPACK_DECODER_STREAM_ERROR | 0x202 | Error on | Section 6 | 1519 | | | the decoder | | 1520 | | | stream | | 1521 +----------------------------+-------+-------------+---------------+ 1523 Table 3 1525 9. References 1527 9.1. Normative References 1529 [HTTP3] Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 1530 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 1531 quic-http-33, 15 December 2020, 1532 . 1534 [QUIC-TRANSPORT] 1535 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 1536 Multiplexed and Secure Transport", Work in Progress, 1537 Internet-Draft, draft-ietf-quic-transport-33, 15 December 1538 2020, . 1541 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1542 Requirement Levels", BCP 14, RFC 2119, 1543 DOI 10.17487/RFC2119, March 1997, 1544 . 1546 [RFC2360] Scott, G., "Guide for Internet Standards Writers", BCP 22, 1547 RFC 2360, DOI 10.17487/RFC2360, June 1998, 1548 . 1550 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 1551 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 1552 . 1554 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1555 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1556 May 2017, . 1558 [SEMANTICS] 1559 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 1560 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1561 httpbis-semantics-13, 14 December 2020, 1562 . 1565 9.2. Informative References 1567 [CRIME] Wikipedia, "CRIME", May 2015, . 1570 [PETAL] Tan, J. and J. Nahata, "PETAL: Preset Encoding 1571 Table Information Leakage", April 2013, 1572 . 1575 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1576 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 1577 . 1579 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1580 DOI 10.17487/RFC6454, December 2011, 1581 . 1583 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1584 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1585 DOI 10.17487/RFC7540, May 2015, 1586 . 1588 [TLS] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1589 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1590 . 1592 Appendix A. Static Table 1594 This table was generated by analyzing actual Internet traffic in 2018 1595 and including the most common header fields, after filtering out some 1596 unsupported and non-standard values. Due to this methodology, some 1597 of the entries may be inconsistent or appear multiple times with 1598 similar but not identical values. The order of the entries is 1599 optimized to encode the most common header fields with the smallest 1600 number of bytes. 1602 +=======+==================================+=======================+ 1603 | Index | Name | Value | 1604 +=======+==================================+=======================+ 1605 | 0 | :authority | | 1606 +-------+----------------------------------+-----------------------+ 1607 | 1 | :path | / | 1608 +-------+----------------------------------+-----------------------+ 1609 | 2 | age | 0 | 1610 +-------+----------------------------------+-----------------------+ 1611 | 3 | content-disposition | | 1612 +-------+----------------------------------+-----------------------+ 1613 | 4 | content-length | 0 | 1614 +-------+----------------------------------+-----------------------+ 1615 | 5 | cookie | | 1616 +-------+----------------------------------+-----------------------+ 1617 | 6 | date | | 1618 +-------+----------------------------------+-----------------------+ 1619 | 7 | etag | | 1620 +-------+----------------------------------+-----------------------+ 1621 | 8 | if-modified-since | | 1622 +-------+----------------------------------+-----------------------+ 1623 | 9 | if-none-match | | 1624 +-------+----------------------------------+-----------------------+ 1625 | 10 | last-modified | | 1626 +-------+----------------------------------+-----------------------+ 1627 | 11 | link | | 1628 +-------+----------------------------------+-----------------------+ 1629 | 12 | location | | 1630 +-------+----------------------------------+-----------------------+ 1631 | 13 | referer | | 1632 +-------+----------------------------------+-----------------------+ 1633 | 14 | set-cookie | | 1634 +-------+----------------------------------+-----------------------+ 1635 | 15 | :method | CONNECT | 1636 +-------+----------------------------------+-----------------------+ 1637 | 16 | :method | DELETE | 1638 +-------+----------------------------------+-----------------------+ 1639 | 17 | :method | GET | 1640 +-------+----------------------------------+-----------------------+ 1641 | 18 | :method | HEAD | 1642 +-------+----------------------------------+-----------------------+ 1643 | 19 | :method | OPTIONS | 1644 +-------+----------------------------------+-----------------------+ 1645 | 20 | :method | POST | 1646 +-------+----------------------------------+-----------------------+ 1647 | 21 | :method | PUT | 1648 +-------+----------------------------------+-----------------------+ 1649 | 22 | :scheme | http | 1650 +-------+----------------------------------+-----------------------+ 1651 | 23 | :scheme | https | 1652 +-------+----------------------------------+-----------------------+ 1653 | 24 | :status | 103 | 1654 +-------+----------------------------------+-----------------------+ 1655 | 25 | :status | 200 | 1656 +-------+----------------------------------+-----------------------+ 1657 | 26 | :status | 304 | 1658 +-------+----------------------------------+-----------------------+ 1659 | 27 | :status | 404 | 1660 +-------+----------------------------------+-----------------------+ 1661 | 28 | :status | 503 | 1662 +-------+----------------------------------+-----------------------+ 1663 | 29 | accept | */* | 1664 +-------+----------------------------------+-----------------------+ 1665 | 30 | accept | application/dns- | 1666 | | | message | 1667 +-------+----------------------------------+-----------------------+ 1668 | 31 | accept-encoding | gzip, deflate, br | 1669 +-------+----------------------------------+-----------------------+ 1670 | 32 | accept-ranges | bytes | 1671 +-------+----------------------------------+-----------------------+ 1672 | 33 | access-control-allow-headers | cache-control | 1673 +-------+----------------------------------+-----------------------+ 1674 | 34 | access-control-allow-headers | content-type | 1675 +-------+----------------------------------+-----------------------+ 1676 | 35 | access-control-allow-origin | * | 1677 +-------+----------------------------------+-----------------------+ 1678 | 36 | cache-control | max-age=0 | 1679 +-------+----------------------------------+-----------------------+ 1680 | 37 | cache-control | max-age=2592000 | 1681 +-------+----------------------------------+-----------------------+ 1682 | 38 | cache-control | max-age=604800 | 1683 +-------+----------------------------------+-----------------------+ 1684 | 39 | cache-control | no-cache | 1685 +-------+----------------------------------+-----------------------+ 1686 | 40 | cache-control | no-store | 1687 +-------+----------------------------------+-----------------------+ 1688 | 41 | cache-control | public, max- | 1689 | | | age=31536000 | 1690 +-------+----------------------------------+-----------------------+ 1691 | 42 | content-encoding | br | 1692 +-------+----------------------------------+-----------------------+ 1693 | 43 | content-encoding | gzip | 1694 +-------+----------------------------------+-----------------------+ 1695 | 44 | content-type | application/dns- | 1696 | | | message | 1697 +-------+----------------------------------+-----------------------+ 1698 | 45 | content-type | application/ | 1699 | | | javascript | 1700 +-------+----------------------------------+-----------------------+ 1701 | 46 | content-type | application/json | 1702 +-------+----------------------------------+-----------------------+ 1703 | 47 | content-type | application/x-www- | 1704 | | | form-urlencoded | 1705 +-------+----------------------------------+-----------------------+ 1706 | 48 | content-type | image/gif | 1707 +-------+----------------------------------+-----------------------+ 1708 | 49 | content-type | image/jpeg | 1709 +-------+----------------------------------+-----------------------+ 1710 | 50 | content-type | image/png | 1711 +-------+----------------------------------+-----------------------+ 1712 | 51 | content-type | text/css | 1713 +-------+----------------------------------+-----------------------+ 1714 | 52 | content-type | text/html; | 1715 | | | charset=utf-8 | 1716 +-------+----------------------------------+-----------------------+ 1717 | 53 | content-type | text/plain | 1718 +-------+----------------------------------+-----------------------+ 1719 | 54 | content-type | text/ | 1720 | | | plain;charset=utf-8 | 1721 +-------+----------------------------------+-----------------------+ 1722 | 55 | range | bytes=0- | 1723 +-------+----------------------------------+-----------------------+ 1724 | 56 | strict-transport-security | max-age=31536000 | 1725 +-------+----------------------------------+-----------------------+ 1726 | 57 | strict-transport-security | max-age=31536000; | 1727 | | | includesubdomains | 1728 +-------+----------------------------------+-----------------------+ 1729 | 58 | strict-transport-security | max-age=31536000; | 1730 | | | includesubdomains; | 1731 | | | preload | 1732 +-------+----------------------------------+-----------------------+ 1733 | 59 | vary | accept-encoding | 1734 +-------+----------------------------------+-----------------------+ 1735 | 60 | vary | origin | 1736 +-------+----------------------------------+-----------------------+ 1737 | 61 | x-content-type-options | nosniff | 1738 +-------+----------------------------------+-----------------------+ 1739 | 62 | x-xss-protection | 1; mode=block | 1740 +-------+----------------------------------+-----------------------+ 1741 | 63 | :status | 100 | 1742 +-------+----------------------------------+-----------------------+ 1743 | 64 | :status | 204 | 1744 +-------+----------------------------------+-----------------------+ 1745 | 65 | :status | 206 | 1746 +-------+----------------------------------+-----------------------+ 1747 | 66 | :status | 302 | 1748 +-------+----------------------------------+-----------------------+ 1749 | 67 | :status | 400 | 1750 +-------+----------------------------------+-----------------------+ 1751 | 68 | :status | 403 | 1752 +-------+----------------------------------+-----------------------+ 1753 | 69 | :status | 421 | 1754 +-------+----------------------------------+-----------------------+ 1755 | 70 | :status | 425 | 1756 +-------+----------------------------------+-----------------------+ 1757 | 71 | :status | 500 | 1758 +-------+----------------------------------+-----------------------+ 1759 | 72 | accept-language | | 1760 +-------+----------------------------------+-----------------------+ 1761 | 73 | access-control-allow-credentials | FALSE | 1762 +-------+----------------------------------+-----------------------+ 1763 | 74 | access-control-allow-credentials | TRUE | 1764 +-------+----------------------------------+-----------------------+ 1765 | 75 | access-control-allow-headers | * | 1766 +-------+----------------------------------+-----------------------+ 1767 | 76 | access-control-allow-methods | get | 1768 +-------+----------------------------------+-----------------------+ 1769 | 77 | access-control-allow-methods | get, post, options | 1770 +-------+----------------------------------+-----------------------+ 1771 | 78 | access-control-allow-methods | options | 1772 +-------+----------------------------------+-----------------------+ 1773 | 79 | access-control-expose-headers | content-length | 1774 +-------+----------------------------------+-----------------------+ 1775 | 80 | access-control-request-headers | content-type | 1776 +-------+----------------------------------+-----------------------+ 1777 | 81 | access-control-request-method | get | 1778 +-------+----------------------------------+-----------------------+ 1779 | 82 | access-control-request-method | post | 1780 +-------+----------------------------------+-----------------------+ 1781 | 83 | alt-svc | clear | 1782 +-------+----------------------------------+-----------------------+ 1783 | 84 | authorization | | 1784 +-------+----------------------------------+-----------------------+ 1785 | 85 | content-security-policy | script-src 'none'; | 1786 | | | object-src 'none'; | 1787 | | | base-uri 'none' | 1788 +-------+----------------------------------+-----------------------+ 1789 | 86 | early-data | 1 | 1790 +-------+----------------------------------+-----------------------+ 1791 | 87 | expect-ct | | 1792 +-------+----------------------------------+-----------------------+ 1793 | 88 | forwarded | | 1794 +-------+----------------------------------+-----------------------+ 1795 | 89 | if-range | | 1796 +-------+----------------------------------+-----------------------+ 1797 | 90 | origin | | 1798 +-------+----------------------------------+-----------------------+ 1799 | 91 | purpose | prefetch | 1800 +-------+----------------------------------+-----------------------+ 1801 | 92 | server | | 1802 +-------+----------------------------------+-----------------------+ 1803 | 93 | timing-allow-origin | * | 1804 +-------+----------------------------------+-----------------------+ 1805 | 94 | upgrade-insecure-requests | 1 | 1806 +-------+----------------------------------+-----------------------+ 1807 | 95 | user-agent | | 1808 +-------+----------------------------------+-----------------------+ 1809 | 96 | x-forwarded-for | | 1810 +-------+----------------------------------+-----------------------+ 1811 | 97 | x-frame-options | deny | 1812 +-------+----------------------------------+-----------------------+ 1813 | 98 | x-frame-options | sameorigin | 1814 +-------+----------------------------------+-----------------------+ 1816 Table 4 1818 Appendix B. Encoding and Decoding Examples 1820 The following examples represent a series of exchanges between an 1821 encoder and a decoder. The exchanges are designed to exercise most 1822 QPACK instructions, and highlight potentially common patterns and 1823 their impact on dynamic table state. The encoder sends three encoded 1824 field sections containing one field line each, as wells as two 1825 speculative inserts that are not referenced. 1827 The state of the encoder's dynamic table is shown, along with its 1828 current size. Each entry is shown with the Absolute Index of the 1829 entry (Abs), the current number of outstanding encoded field sections 1830 with references to that entry (Ref), along with the name and value. 1831 Entries above the 'acknowledged' line have been acknowledged by the 1832 decoder. 1834 B.1. Literal Field Line With Name Reference 1836 The encoder sends an encoded field section containing a literal 1837 representation of a field with a static name reference. 1839 Data | Interpretation 1840 | Encoder's Dynamic Table 1842 Stream: 0 1843 0000 | Required Insert Count = 0, Base = 0 1844 510b 2f69 6e64 6578 | Literal Field Line with Name Reference 1845 2e68 746d 6c | Static Table, Index=1 1846 | (:path=/index.html) 1848 Abs Ref Name Value 1849 ^-- acknowledged --^ 1850 Size=0 1852 B.2. Dynamic Table 1854 The encoder sets the dynamic table capacity, inserts a header with a 1855 dynamic name reference, then sends a potentially blocking, encoded 1856 field section referencing this new entry. The decoder acknowledges 1857 processing the encoded field section, which implicitly acknowledges 1858 all dynamic table insertions up to the Required Insert Count. 1860 Stream: Encoder 1861 3fbd01 | Set Dynamic Table Capacity=220 1862 c00f 7777 772e 6578 | Insert With Name Reference 1863 616d 706c 652e 636f | Static Table, Index=0 1864 6d | (:authority=www.example.com) 1865 c10c 2f73 616d 706c | Insert With Name Reference 1866 652f 7061 7468 | Static Table, Index=1 1867 | (:path=/sample/path) 1869 Abs Ref Name Value 1870 ^-- acknowledged --^ 1871 1 0 :authority www.example.com 1872 2 0 :path /sample/path 1873 Size=106 1875 Stream: 4 1876 0381 | Required Insert Count = 2, Base = 0 1877 10 | Indexed Field Line With Post-Base Index 1878 | Absolute Index = Base(0) + Index(0) + 1 = 1 1879 | (:authority=www.example.com) 1880 11 | Indexed Field Line With Post-Base Index 1881 | Absolute Index = Base(0) + Index(1) + 1 = 2 1882 | (:path=/sample/path) 1884 Abs Ref Name Value 1885 ^-- acknowledged --^ 1886 1 1 :authority www.example.com 1887 2 1 :path /sample/path 1888 Size=106 1890 Stream: Decoder 1891 84 | Section Acknowledgement (stream=4) 1893 Abs Ref Name Value 1894 1 0 :authority www.example.com 1895 2 0 :path /sample/path 1896 ^-- acknowledged --^ 1897 Size=106 1899 B.3. Speculative Insert 1901 The encoder inserts a header into the dynamic table with a literal 1902 name. The decoder acknowledges receipt of the entry. The encoder 1903 does not send any encoded field sections. 1905 Stream: Encoder 1906 4a63 7573 746f 6d2d | Insert With Literal Name 1907 6b65 790c 6375 7374 | (custom-key=custom-value) 1908 6f6d 2d76 616c 7565 | 1910 Abs Ref Name Value 1911 1 0 :authority www.example.com 1912 2 0 :path /sample/path 1913 ^-- acknowledged --^ 1914 3 0 custom-key custom-value 1915 Size=160 1917 Stream: Decoder 1918 01 | Insert Count Increment (1) 1920 Abs Ref Name Value 1921 1 0 :authority www.example.com 1922 2 0 :path /sample/path 1923 3 0 custom-key custom-value 1924 ^-- acknowledged --^ 1925 Size=160 1927 B.4. Duplicate Instruction, Stream Cancellation 1929 The encoder duplicates an existing entry in the dynamic table, then 1930 sends an encoded field section referencing the dynamic table entries 1931 including the duplicated entry. The packet containing the encoder 1932 stream data is delayed. Before the packet arrives, the decoder 1933 cancels the stream and notifies the encoder that the encoded field 1934 section was not processed. 1936 Stream: Encoder 1937 02 | Duplicate (Relative Index=2) 1939 Abs Ref Name Value 1940 1 0 :authority www.example.com 1941 2 0 :path /sample/path 1942 3 0 custom-key custom-value 1943 ^-- acknowledged --^ 1944 4 0 :authority www.example.com 1945 Size=217 1947 Stream: 8 1948 0500 | Required Insert Count = 4, Base = 4 1949 80 | Indexed Field Line, Dynamic Table 1950 | Absolute Index = Base(4) - Index(0) = 4 1951 | (:authority=www.example.com) 1952 c1 | Indexed Field Line, Static Table Index = 1 1953 | (:path=/) 1954 81 | Indexed Field Line, Dynamic Table 1955 | Absolute Index = Base(4) - Index(1) = 3 1956 | (custom-key=custom-value) 1958 Abs Ref Name Value 1959 1 0 :authority www.example.com 1960 2 0 :path /sample/path 1961 3 1 custom-key custom-value 1962 ^-- acknowledged --^ 1963 4 1 :authority www.example.com 1964 Size=217 1966 Stream: Decoder 1967 48 | Stream Cancellation (Stream=8) 1969 Abs Ref Name Value 1970 1 0 :authority www.example.com 1971 2 0 :path /sample/path 1972 3 0 custom-key custom-value 1973 ^-- acknowledged --^ 1974 4 0 :authority www.example.com 1975 Size=215 1977 B.5. Dynamic Table Insert, Eviction 1979 The encoder inserts another header into the dynamic table, which 1980 evicts the oldest entry. The encoder does not send any encoded field 1981 sections. 1983 Stream: Encoder 1984 810d 6375 7374 6f6d | Insert With Name Reference 1985 2d76 616c 7565 32 | Dynamic Table, Absolute Index=2 1986 | (custom-key=custom-value2) 1988 Abs Ref Name Value 1989 2 0 :path /sample/path 1990 3 0 custom-key custom-value 1991 ^-- acknowledged --^ 1992 4 0 :authority www.example.com 1993 5 0 custom-key custom-value2 1994 Size=215 1996 Appendix C. Sample One Pass Encoding Algorithm 1998 Pseudo-code for single pass encoding, excluding handling of 1999 duplicates, non-blocking mode, available encoder stream flow control 2000 and reference tracking. 2002 base = dynamicTable.getInsertCount() 2003 requiredInsertCount = 0 2004 for line in field_lines: 2005 staticIndex = staticTable.findIndex(line) 2006 if staticIndex is not None: 2007 encodeIndexReference(streamBuffer, staticIndex) 2008 continue 2010 dynamicIndex = dynamicTable.findIndex(line) 2011 if dynamicIndex is None: 2012 # No matching entry. Either insert+index or encode literal 2013 staticNameIndex = staticTable.findName(line.name) 2014 if staticNameIndex is None: 2015 dynamicNameIndex = dynamicTable.findName(line.name) 2017 if shouldIndex(line) and dynamicTable.canIndex(line): 2018 encodeInsert(encoderBuffer, staticNameIndex, 2019 dynamicNameIndex, line) 2020 dynamicIndex = dynamicTable.add(line) 2022 if dynamicIndex is None: 2023 # Could not index it, literal 2024 if dynamicNameIndex is not None: 2025 # Encode literal with dynamic name, possibly above base 2026 encodeDynamicLiteral(streamBuffer, dynamicNameIndex, 2027 base, line) 2028 requiredInsertCount = max(requiredInsertCount, 2029 dynamicNameIndex) 2030 else: 2032 # Encodes a literal with a static name or literal name 2033 encodeLiteral(streamBuffer, staticNameIndex, line) 2034 else: 2035 # Dynamic index reference 2036 assert(dynamicIndex is not None) 2037 requiredInsertCount = max(requiredInsertCount, dynamicIndex) 2038 # Encode dynamicIndex, possibly above base 2039 encodeDynamicIndexReference(streamBuffer, dynamicIndex, base) 2041 # encode the prefix 2042 if requiredInsertCount == 0: 2043 encodeIndexReference(prefixBuffer, 0, 0, 8) 2044 encodeIndexReference(prefixBuffer, 0, 0, 7) 2045 else: 2046 wireRIC = ( 2047 requiredInsertCount 2048 % (2 * getMaxEntries(maxTableCapacity)) 2049 ) + 1; 2050 encodeInteger(prefixBuffer, 0x00, wireRIC, 8) 2051 if base >= requiredInsertCount: 2052 encodeInteger(prefixBuffer, 0, base - requiredInsertCount, 7) 2053 else: 2054 encodeInteger(prefixBuffer, 0x80, 2055 requiredInsertCount - base - 1, 7) 2057 return encoderBuffer, prefixBuffer + streamBuffer 2059 Appendix D. Change Log 2061 *RFC Editor's Note:* Please remove this section prior to 2062 publication of a final version of this document. 2064 D.1. Since draft-ietf-quic-qpack-19 2066 Editorial changes only 2068 D.2. Since draft-ietf-quic-qpack-18 2070 Editorial changes only 2072 D.3. Since draft-ietf-quic-qpack-17 2074 Editorial changes only 2076 D.4. Since draft-ietf-quic-qpack-16 2078 Editorial changes only 2080 D.5. Since draft-ietf-quic-qpack-15 2082 No changes 2084 D.6. Since draft-ietf-quic-qpack-14 2086 Added security considerations 2088 D.7. Since draft-ietf-quic-qpack-13 2090 No changes 2092 D.8. Since draft-ietf-quic-qpack-12 2094 Editorial changes only 2096 D.9. Since draft-ietf-quic-qpack-11 2098 Editorial changes only 2100 D.10. Since draft-ietf-quic-qpack-10 2102 Editorial changes only 2104 D.11. Since draft-ietf-quic-qpack-09 2106 * Decoders MUST emit Header Acknowledgements (#2939) 2108 * Updated error code for multiple encoder or decoder streams (#2970) 2110 * Added explicit defaults for new SETTINGS (#2974) 2112 D.12. Since draft-ietf-quic-qpack-08 2114 * Endpoints are permitted to create encoder and decoder streams even 2115 if they can't use them (#2100, #2529) 2117 * Maximum values for settings removed (#2766, #2767) 2119 D.13. Since draft-ietf-quic-qpack-06 2121 * Clarify initial dynamic table capacity maximums (#2276, #2330, 2122 #2330) 2124 D.14. Since draft-ietf-quic-qpack-05 2126 * Introduced the terms dynamic table capacity and maximum dynamic 2127 table capacity. 2129 * Renamed SETTINGS_HEADER_TABLE_SIZE to 2130 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 2132 D.15. Since draft-ietf-quic-qpack-04 2134 * Changed calculation of Delta Base Index to avoid an illegal value 2135 (#2002, #2005) 2137 D.16. Since draft-ietf-quic-qpack-03 2139 * Change HTTP settings defaults (#2038) 2141 * Substantial editorial reorganization 2143 D.17. Since draft-ietf-quic-qpack-02 2145 * Largest Reference encoded modulo MaxEntries (#1763) 2147 * New Static Table (#1355) 2149 * Table Size Update with Insert Count=0 is a connection error 2150 (#1762) 2152 * Stream Cancellations are optional when 2153 SETTINGS_HEADER_TABLE_SIZE=0 (#1761) 2155 * Implementations must handle 62 bit integers (#1760) 2157 * Different error types for each QPACK stream, other changes to 2158 error handling (#1726) 2160 * Preserve header field order (#1725) 2162 * Initial table size is the maximum permitted when table is first 2163 usable (#1642) 2165 D.18. Since draft-ietf-quic-qpack-01 2167 * Only header blocks that reference the dynamic table are 2168 acknowledged (#1603, #1605) 2170 D.19. Since draft-ietf-quic-qpack-00 2172 * Renumbered instructions for consistency (#1471, #1472) 2174 * Decoder is allowed to validate largest reference (#1404, #1469) 2175 * Header block acknowledgments also acknowledge the associated 2176 largest reference (#1370, #1400) 2178 * Added an acknowledgment for unread streams (#1371, #1400) 2180 * Removed framing from encoder stream (#1361,#1467) 2182 * Control streams use typed unidirectional streams rather than fixed 2183 stream IDs (#910,#1359) 2185 D.20. Since draft-ietf-quic-qcram-00 2187 * Separate instruction sets for table updates and header blocks 2188 (#1235, #1142, #1141) 2190 * Reworked indexing scheme (#1176, #1145, #1136, #1130, #1125, 2191 #1314) 2193 * Added mechanisms that support one-pass encoding (#1138, #1320) 2195 * Added a setting to control the number of blocked decoders (#238, 2196 #1140, #1143) 2198 * Moved table updates and acknowledgments to dedicated streams 2199 (#1121, #1122, #1238) 2201 Acknowledgments 2203 The IETF QUIC Working Group received an enormous amount of support 2204 from many people. 2206 The compression design team did substantial work exploring the 2207 problem space and influencing the initial draft. The contributions 2208 of design team members Roberto Peon, Martin Thomson, and Dmitri 2209 Tikhonov are gratefully acknowledged. 2211 The following people also provided substantial contributions to this 2212 document: 2214 * Bence Beky 2216 * Alessandro Ghedini 2218 * Ryan Hamilton 2220 * Robin Marx 2222 * Patrick McManus 2223 * 奥 一穂 (Kazuho Oku) 2225 * Lucas Pardue 2227 * Biren Roy 2229 * Ian Swett 2231 This draft draws heavily on the text of [RFC7541]. The indirect 2232 input of those authors is also gratefully acknowledged. 2234 Buck's contribution was supported by Google during his employment 2235 there. 2237 A portion of Mike's contribution was supported by Microsoft during 2238 his employment there. 2240 Authors' Addresses 2242 Charles 'Buck' Krasic 2243 Netflix 2245 Email: ckrasic@netflix.com 2247 Mike Bishop 2248 Akamai Technologies 2250 Email: mbishop@evequefou.be 2252 Alan Frindell (editor) 2253 Facebook 2255 Email: afrind@fb.com