Internet Engineering Task Force R. Hewitt Internet-Draft Akamai Technologies Inc. Intended status: Informational 10 October 2023 Expires: 12 April 2024 The qpack_static_table_version TLS extension draft-hewitt-ietf-qpack-static-table-version-01 Abstract This document specifies a new "qpack_static_table_version" TLS extension to enable clients and servers to agree upon the version of the HTTP/3 QPACK Static Table to use for communications between them. It also defines a new IANA registry to be used for documenting and publishing the entries in the QPACK static table. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 12 April 2024. Copyright Notice Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Hewitt Expires 12 April 2024 [Page 1] Internet-Draft QSTV TLS extension October 2023 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 2. QPACK Static Table Background . . . . . . . . . . . . . . . . 3 3. QPACK Static Table Additions . . . . . . . . . . . . . . . . 4 3.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. QPACK Static Table support . . . . . . . . . . . . . . . . . 7 5. The qpack_static_table_version TLS extension . . . . . . . . 8 6. Processing Examples . . . . . . . . . . . . . . . . . . . . . 10 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 9.1. Normative References . . . . . . . . . . . . . . . . . . 14 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 1. Introduction HTTP/3 uses QPACK [RFC9204] for compression of the header and trailer sections. QPACK reuses core concepts from the HPACK algorithm used for HTTP/2, but as noted in its design "[...]is redesigned to allow correctness in the presence of out-of-order delivery, with flexibility for implementations to balance between resilience against head-of-line blocking and optimal compression ratio." A central feature of QPACK is the use of a 'static table' which contains a predefined list of frequently-used field names or field name/value combinations (generically "field strings"), each of which is identified by a unique, unchanging index in the table, enabling excellent compression of the HTTP fields. Less frequently-used field strings are defined as ASCII text in the QPACK 'dynamic table'. Because of the optimal compression, defining field strings in the static table is significantly desirable over passing them in the dynamic table. When the static table was originally defined, the entries it contained were calculated by determining the relative frequency with which each field string was found in a representative sampling of web traffic. However, as new HTTP fields become more frequently-used over time, it makes sense that they be added as additional entries to the static table to retain the high level of compression. This specification defines a new TLS extension which can be passed by both client and server to identify and agree on the version (size) of the static table that they will both use. Because the size of the Hewitt Expires 12 April 2024 [Page 2] Internet-Draft QSTV TLS extension October 2023 static table must be known prior to any HTTP requests passing between the client and server, this information must be passed during the TLS handshake. This specification also defines a new IANA registry where the entries in the QPACK static table will be published and updated. Additional related registries will be created over time. 1.1. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. The following terms are used in this document: * *HTTP fields*: Metadata sent as part of an HTTP message. The term encompasses both header and trailer fields. Colloquially, the term "headers" has often been used to refer to HTTP header fields and trailer fields; this document uses "fields" for generality. * *HTTP field line*: A name-value pair sent as part of an HTTP field section. See Sections 6.3 and 6.5 of [RFC9110]. * *HTTP field value*: Data associated with a field name, composed from all field line values with that field name in that section, concatenated together with comma separators. * *HTTP field string*: A field name or field name/value combination, as stored in the QPACK static table. Note that QPACK is a name, not an abbreviation. 2. QPACK Static Table Background The original QPACK static table [RFC9204] contains 99 entries (starting at entry 0, ending at entry 98), as follows: Hewitt Expires 12 April 2024 [Page 3] Internet-Draft QSTV TLS extension October 2023 +==========+==============================+===================+ | Entry | Value | Notes | +==========+==============================+===================+ | 0 (first | :authority | Field name only | | entry) | | | +----------+------------------------------+-------------------+ | 1 | :path / | Field name and | | | | value combination | +----------+------------------------------+-------------------+ | 2 | Age 0 | Field name and | | | | value combination | +----------+------------------------------+-------------------+ | ...2 - 97... | +----------+------------------------------+-------------------+ | 98 (last | x-frame-options sameorigin | Field name and | | entry) | | value combination | +----------+------------------------------+-------------------+ Table 1 The table was generated by analyzing actual Internet traffic in 2018 and including the most common header fields, after filtering out some unsupported and non-standard values. Due to this methodology, some of the entries may be inconsistent or appear multiple times with similar but not identical values. The order of the entries is optimized to encode the most common header fields with the smallest number of bytes. 3. QPACK Static Table Additions A registry called *QPACK Static Table Version 1* will be created and maintained by IANA in which the initial QPACK static table will be published. See Section 7 for more details. Over time, subsequent related registries using a naming convention of *QPACK Static Table Version N* (where *N* is an integer incremented by 1 from the prior registry) will be created to contain a re-ordered copy of the table that is defined in the prior registry. Each registry will have two 'attributes' that are used by clients and servers during TLS negotiation - a *Version* (part of the registry name) and a *Length* (the number of entries in the registry). In this document, a registry may be referred to using the shorthand of "Version, Length" - for example "1,99". Hewitt Expires 12 April 2024 [Page 4] Internet-Draft QSTV TLS extension October 2023 The initial registry (Version 1) will have 99 entries (Length 99), shorthandedly known as 1,99. These values match the initial value of the QPACK static table as defined in the QPACK RFC [RFC9204]. Every subsequent registry will have a Length value greater than or equal to 99. Periodically (see Section 7 for proposed periods), IESG designated experts will re-sample actual internet traffic and as new field strings are found to have become more prevalent than the current last entry in the registry with the highest Version, the new field strings will be ordered by prevalence with one another (if more than one field string) and appended as new entries to that registry. Periodically (see Section 7 for proposed periods), a new *QPACK Static Table Version N* registry will be created (where N is incremented by 1 from the prior registry Version). This registry will contain all the entries in the prior registry Version, but they will all be re-ordered, to ensure that the most commonly-found header lines are near the start of the table. When a new *QPACK Static Table Version N* registry is published, all prior registries are 'locked' and will not be changed; new entries will not be appended to them. Thus at any time, there may be multiple concurrently-published QPACK Static Table registries, each with a different Version. 3.1. Example *Note that with the exception of the initial length of the QPACK Static Table Version 1 registry, this section is hypothetical* Initially the *QPACK Static Table Version 1* registry is published and contains 99 entries. This is the table that is defined in the QPACK RFC. After a certain period of time, web traffic is re-sampled and it is found that 12 new field strings exist which are more common than "x- frame-options: sameorigin" (entry 99 in the Version 1 registry). These 12 field strings are ordered by prevalence relative to each other and appended as entries 100-111 to the *QPACK Static Table Version 1* registry. After another period of time, internet traffic is re-sampled again and it is found that 5 new field strings exist which are more common than entry 111 in the Version 1 registry. Again, these 5 field strings are ordered by prevalence relative to each other and appended to the *QPACK Static Table Version 1* registry. Hewitt Expires 12 April 2024 [Page 5] Internet-Draft QSTV TLS extension October 2023 At the same time, a new registry, *QPACK Static Table Version 2*, is published. This registry contains all 116 entries from the *QPACK Static Table Version 1* registry, re-ordered in order of total prevalence. The *QPACK Static Table Version 1* registry is locked. There are now *two* registries: * *QPACK Static Table Version 1* containing 116 entries: [LOCKED] Entries 0-98 are in the same order as the initial QPACK table. Entries 99-111 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-98. Entries 112-116 are ordered by prevalence with one another but not with any prevalence relative to entries 0-111. * *QPACK Static Table Version 2* containing 116 entries: All entries are ordered by prevalence compared to one another. After a period of time, 3 new field strings exist which are more common than entry 116 in *QPACK Static Table Version 2*. These 3 field strings are ordered by prevalence relative to each other and appended to the *QPACK Static Table Version 2* registry. At this point there are still *two* registries: - the Version 1 registry is locked and the Version 2 registry has changed: * *QPACK Static Table Version 1* containing 116 entries: [LOCKED] Entries 0-98 are in the same order as the initial QPACK table. Entries 99-111 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-98. Entries 112-116 are ordered by prevalence with one another but not with any prevalence relative to entries 0-111. * *QPACK Static Table Version 2* containing 119 entries: Entries 0-116 are ordered by prevalence compared to one another. Entries 117-119 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-116. After a period of time, 4 new field strings exist which are more common than entry 119 in *QPACK Static Table Version 2*. These 4 field strings are ordered by prevalence relative to each other and appended to the *QPACK Static Table Version 2* registry. At the same time, a new registry, *QPACK Static Table Version 3*, is published. This contains all the entries from the Version 2 registry, re-ordered in order of total prevalence. The *QPACK Static Table Version 2* registry is locked. There are now *three* registries: Hewitt Expires 12 April 2024 [Page 6] Internet-Draft QSTV TLS extension October 2023 * *QPACK Static Table Version 1* containing 116 entries: [LOCKED] Entries 0-98 are in the same order as the initial QPACK table. Entries 99-111 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-98. Entries 112-116 are ordered by prevalence with one another but not with any prevalence relative to entries 0-111. * *QPACK Static Table Version 2* containing 123 entries [LOCKED]: Entries 0-116 are ordered by prevalence compared to one another. Entries 117-119 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-116. Entries 120-123 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-119. * *QPACK Static Table Version 3* containing 123 entries: All entries are ordered by prevalence compared to one another. This process continues, with new header lines periodically being appended to the latest registry Version and a new registry Version of the table periodically being created. 4. QPACK Static Table support HTTP/3-supporting clients and servers MUST always support *QPACK Static Table Version 1*. They MAY also support other registry Versions as long as they support all intermediate Versions between Version 1 and the Version for which they advertise support in qpack_static_table_version. This allows both client and server to downgrade to a shared supported Version without the client needing to advertise multiple supported Versions. HTTP/3-supporting clients and servers MUST encode into their software a maximum Length (number of entries) in each supported registry Version. This can be any value from the number of entries when that registry Version was created up to the number of entries when it was locked due to the creation of a new registry, inclusive. This ensures that if a sender (maliciously or otherwise) specifies that it supports a registry Version prior to that supported by the receiver, but also specifies a number of entries for that registry Version that is higher than the maximum value for that Version as stored by the receiver (for instance, if the sender announces support for Version 1, with Length 105), the receiver can correctly identify that this is an invalid combination. In this scenario, the receiver MUST ignore the invalid Length field passed by the sender and use the lower of the maximum Length supported by the receiver or 99. See Example 10 in Section 6 for an example of this. Hewitt Expires 12 April 2024 [Page 7] Internet-Draft QSTV TLS extension October 2023 5. The qpack_static_table_version TLS extension The *qpack_static_table_version* TLS extension is a structure which represents the Version and Length of the static table supported by the sender. It is OPTIONAL and MAY be sent by either client or server or both or neither. The extension_data for the qpack_static_table_version extension is described below using the syntax defined in [RFC8446]: struct { uint8 StaticTableSupportedVersion; uint8 StaticTableSupportedLength; } qpack_static_table_version; Figure 1 The StaticTableSupportedVersion field must be a positive integer and indicates the highest registry Version supported. A negative value or a value of 0 is invalid and the receiver MUST treat this as if a value of 1 was passed by the sender. The StaticTableSupportedLength field must be a positive integer. A negative value or a value of 0 is invalid and the receiver MUST treat this as if a value of 99 was passed by the sender. A value that is lower than the current length of the registry identified by the StaticTableSupportedVersion field is valid; this allows a client or server which may have very limited memory and/or which expects to send/receive only a few known headers to specify a low Length e.g. 1,30, indicating that they support only the first 30 entries in the *QPACK Static Table Version 1* registry and any other header lines must be specified in the dynamic table. The qpack_static_table_version extension MAY be passed by a client to a server in the ClientHello, to indicate the Version/Length of the registry that the client supports. If the qpack_static_table_version extension is not present in the ClientHello, the server MUST assume that the client implicitly supports *QPACK Static Table Version 1* up to 99 entries. If the ClientHello includes the qpack_static_table_version extension, the server MAY respond in the ServerHello with its own copy of the qpack_static_table_version extension. Hewitt Expires 12 April 2024 [Page 8] Internet-Draft QSTV TLS extension October 2023 If either the ClientHello or the ServerHello do not include the qpack_static_table_version extension, or if an invalid value is specified for either of its component fields, then both client and server must fall back to use *QPACK Static Table Version 1* up to 99 entries. If both the client and the server pass the qpack_static_table_version extension with valid values, the lower Version and Length MUST be used by both client and server, thus ensuring that both client and server only reference entries in their static table up to the shared maximum length of the registry. Note that the chosen Version and Length may be separately derived from either client or server. See example 9 in Section 6 for an example of this. If either client or server passes a StaticTableSupportedLength field which is higher than the number of entries in the registry indicated by the StaticTableSupportedVersion field, the receiver MUST fall back to using 99 entries (or the maximum Length supported by the receiver if lower than 99) in the registry indicated by the StaticTableSupportedVersion field (or the highest Version registry supported by the receiver if lower). As noted in Section 4, this means that clients and servers must encode into their software a maximum allowed Length for each Version. Sample pseudocode processing for client and server: Initialize variable CV to supported Version value Initialize variable CL to supported Length value Include qpack_static_table_version with values CV,CL in ClientHello if (ServerHello does not contain qpack_static_table_version or if qpack_static_table_version contains invalid values) { set CV to 1 set CL to lesser of 99 and CL } else { save qpack_static_table_version from ServerHello as SV,SL set SL_max to maximum valid entries for specified SV if (SV < CV) { set CV to SV } if (SL < CL) { if (SL > SL_max) { set CL to lesser of 99 and CL } else { set CL to SL } } } use CV,CL for static table index processing Hewitt Expires 12 April 2024 [Page 9] Internet-Draft QSTV TLS extension October 2023 Figure 2: Client processing Initialize variable SV to supported Version value Initialize variable SL to supported Length value if (ClientHello does not contain qpack_static_table_version or if qpack_static_table_version contains invalid values) { set SV to 1 set SL to lesser of 99 and SL } else { save qpack_static_table_version from ClientHello as CV,CL set CL_max to maximum valid entries for specified CV if (CV < SV) { set SV to CV } if (CL < SL) { if (CL > CL_max) { set SL to lesser of 99 and SL } else { set SL to CL } } Include qpack_static_table_version with values SV,SL in ServerHello } Use SV,SL for static table index processing Figure 3: Server processing 6. Processing Examples Example published registries (after some time has passed and multiple registries have been created): +=========+========+ | Version | Length | +=========+========+ | 1 | 116 | +---------+--------+ | 2 | 123 | +---------+--------+ | 3 | 123 | +---------+--------+ Table 2 Example values passed for the qpack_static_table_version: Hewitt Expires 12 April 2024 [Page 10] Internet-Draft QSTV TLS extension October 2023 +=========+==========+==========+==========+========================+ | Example | Client | Server | Version/ | Notes | | | Version/ | Version/ | Length | | | | Length | Length | used | | | | passed | passed | | | +=========+==========+==========+==========+========================+ | 1 | not | not | 1,99 | Neither client nor | | | passed | passed | | server passed the | | | | | | extension, so both | | | | | | use the default | | | | | | Version 1 registry, | | | | | | up to 99 entries. | +---------+----------+----------+----------+------------------------+ | 2 | not | 2,116 | 1,99 | The client did not | | | passed | | | pass the extension, | | | | | | so both use the | | | | | | default Version 1 | | | | | | registry, up to 99 | | | | | | entries. | +---------+----------+----------+----------+------------------------+ | 3 | 1,114 | not | 1,99 | The server did not | | | | passed | | pass the extension, | | | | | | so both use the | | | | | | default Version 1 | | | | | | registry, up to 99 | | | | | | entries. | +---------+----------+----------+----------+------------------------+ | 4 | 1,99 | 1,116 | 1,99 | The client passed the | | | | | | same Version (Version | | | | | | 1) as server, but a | | | | | | lower Length, so the | | | | | | client Length (99 | | | | | | entries) is used. | +---------+----------+----------+----------+------------------------+ | 5 | 1,116 | 1,101 | 1,101 | The server passed the | | | | | | same Version (Version | | | | | | 1) as the client, but | | | | | | a lower Length, so | | | | | | the server Length | | | | | | (101 entries) is | | | | | | used. | +---------+----------+----------+----------+------------------------+ | 6 | 1,99 | 2,116 | 1,99 | The client passed a | | | | | | lower Version than | | | | | | the server, so the | | | | | | client Version is | | | | | | used, up to 99 | | | | | | entries. | Hewitt Expires 12 April 2024 [Page 11] Internet-Draft QSTV TLS extension October 2023 +---------+----------+----------+----------+------------------------+ | 7 | 3,123 | 2,116 | 2,116 | The server passed a | | | | | | lower Version than | | | | | | the client, so the | | | | | | server Version is | | | | | | used, up to 116 | | | | | | entries. | +---------+----------+----------+----------+------------------------+ | 8 | 1,50 | 3,123 | 1,50 | The client passed a | | | | | | lower Version than | | | | | | the server, so the | | | | | | client Version is | | | | | | used, up to only 50 | | | | | | entries. | +---------+----------+----------+----------+------------------------+ | 9 | 1,99 | 3,80 | 1,80 | The client passed a | | | | | | lower Version than | | | | | | the server, so the | | | | | | client Version is | | | | | | used. The server | | | | | | passed a lower Length | | | | | | than the client, so | | | | | | the server Length (80 | | | | | | entries) is used. | +---------+----------+----------+----------+------------------------+ | 10 | 1,101 | 3,123 | 1,99 | The client passed a | | | | | | lower Version than | | | | | | the server, so the | | | | | | client Version is | | | | | | used. The client | | | | | | passed an invalidly | | | | | | high Length for the | | | | | | specified Version, so | | | | | | only 99 entries are | | | | | | used. | +---------+----------+----------+----------+------------------------+ Table 3 7. IANA Considerations This memo requests that IANA creates a registry for the QPACK static table, to be periodically updated and supserseded by IESG-appointed Designated Expert(s). The registry name is *QPACK Static Table Version 1* and is part of the *Transport Layer Security (TLS)* registry grouping. The registration policy is *Expert Review*. Hewitt Expires 12 April 2024 [Page 12] Internet-Draft QSTV TLS extension October 2023 The registry will contain a copy of the QPACK static table ("table"). Each entry in the table consists of the following three fields: +=======+==========+=======================================+ | Field | Type | Notes | +=======+==========+=======================================+ | Index | Unsigned | First entry has Index 0, then 1, 2 | | | Integer | etc. | +-------+----------+---------------------------------------+ | Name | String | Field name - follows field name | | | | validation specified in Section 5.1 | | | | of [RFC9110]. Case-insensitive, but | | | | per convention, specify in lower-case | +-------+----------+---------------------------------------+ | Value | String | Field value - follows field value | | | | validation specified in Section 5.5 | | | | of [RFC9110]. Case-sensitive. MAY | | | | BE BLANK | +-------+----------+---------------------------------------+ Table 4 The initial set of entries in the registry will be copied directly from the entries in the QPACK static table defined in Appendix A in [RFC9204]. As per the technical information in this document, on a periodic basis, the Designated Expert(s) will sample HTTP/3 web traffic and may, as a result, append new entries to the registry. It is suggested that the sampling process occurs approximately *once every year*, but the decision of whether to append new entries to the registry may occur at a slower rate, since it depends entirely on the rate at which new fields become sufficiently prevalent in HTTP/3 web traffic. On a separate periodic basis, a new registry will be created using the same format as the above registry, but will be named *QPACK Static Table Version N* (where *N* is an integer incremented by 1 from the prior registry). This new registry will be a re-ordered copy of the prior registry. When a new QPACK Static Table registry is created, all prior registry versions must be locked and no new entries can be appended to them. It is suggested that this process happens approximately *once every three years*, but again, it depends on the results of the HTTP/3 web traffic sampling. The intention is that any appending of new entries to the registry and/or the creation of a new QPACK Static Table registry will be accompanied by a published RFC. But in order to allow for the Hewitt Expires 12 April 2024 [Page 13] Internet-Draft QSTV TLS extension October 2023 allocation of values prior to the RFC being approved for publication, the Designated Expert can undertake either action once it seems clear that an RFC will be published. The Designated expert will post a request to the HTTP WG mailing list (or a successor designated by the Area Director) for comment and review, including an Internet-Draft. 8. Security Considerations This document should not affect the security of the Internet. 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC9204] Krasic, C., Bishop, M., and A. Frindell, Ed., "QPACK: Field Compression for HTTP/3", RFC 9204, DOI 10.17487/RFC9204, June 2022, . [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . Acknowledgements Many thanks to Rich Salz and Mike Bishop at Akamai for their invaluable help. Author's Address Rory Hewitt Akamai Technologies Inc. Email: rhewitt@akamai.com Hewitt Expires 12 April 2024 [Page 14]