Compression Dictionary Transport

1.1.1. Version Upgrade

Using a previous version of a resource as a dictionary for a newer version enables delivery of a delta-compressed version of the changes, usually resulting in significantly smaller responses than can be achieved by compression alone.¶

For example:¶

1.1.2. Common Content

If several resources share common patterns in their responses then it can be useful to reference an external dictionary that contains those common patterns, effectively compressing them out of the responses. Some examples of this are common template HTML for similar pages across a site and common keys and values in API calls.¶

For example:¶

2.1.1. match

The "match" value of the Use-As-Dictionary header is a String value that provides the URL Pattern to use for request matching (see [URLPATTERN]).¶

The URL Pattern used for matching does not support using regular expressions.¶

The following algorithm is used to validate that a given String value is a valid URL Pattern that does not use regular expressions and is for the same Origin (Section 4.3.1 of [HTTP]) as the dictionary. It will return TRUE for a valid match pattern and FALSE for an invalid pattern that MUST NOT be used:¶

1. Let MATCH be the value of "match" for the given dictionary.¶

2. Let URL be the URL of the dictionary request.¶

3. Let PATTERN be a URL pattern created by running the steps to create a URL pattern by setting input=MATCH, and baseURL=URL (see Part "create" of [URLPATTERN]).¶

4. If the result of running the "has regexp groups" steps for PATTERN returns TRUE then return FALSE (see Part "has regexp groups" of [URLPATTERN]).¶

5. Return TRUE.¶

The "match" value is required and MUST be included in the Use-As-Dictionary response header for the dictionary to be considered valid.¶

Operating at the HTTP-level, the specified match patterns will operate on the percent-encoded version of the URL path (see Section 2 of [URL]).¶

For example the URL "http://www.example.com/düsseldorf" would be encoded as "http://www.example.com/d%C3%BCsseldorf" and a relevant match pattern would be:¶

Use-As-Dictionary: match="/d%C3%BCsseldorf"

2.1.2. match-dest

The "match-dest" value of the Use-As-Dictionary header is an Inner List of String values that provides a list of Fetch request destinations for the dictionary to match (see Part "destination" of [FETCH]).¶

An empty list for "match-dest" MUST match all destinations.¶

For clients that do not support request destinations, the client MUST treat it as an empty list and match all destinations.¶

The "match-dest" value is optional and defaults to an empty list.¶

2.1.3. id

The "id" value of the Use-As-Dictionary header is a String value that specifies a server identifier for the dictionary. If an "id" value is present and has a string length longer than zero then it MUST be sent to the server in a "Dictionary-ID" request header when the client sends an "Available-Dictionary" request header for the same dictionary (see Section 2.2).¶

The server identifier MUST be treated as an opaque string by the client.¶

The server identifier MUST NOT be relied upon by the server to guarantee the contents of the dictionary. The dictionary hash MUST be validated before use.¶

The "id" value string length (after any decoding) supports up to 1024 characters.¶

The "id" value is optional and defaults to the empty string.¶

2.1.4. type

The "type" value of the Use-As-Dictionary header is a Token value that describes the file format of the supplied dictionary.¶

"raw" is defined as a dictionary format which represents an unformatted blob of bytes suitable for any compression scheme to use.¶

If a client receives a dictionary with a type that it does not understand, it MUST NOT use the dictionary.¶

The "type" value is optional and defaults to "raw".¶

2.1.5. Examples

NOTE: '\' line wrapping per RFC 8792

Use-As-Dictionary: \
  match="/product/*", match-dest=("document")

Use-As-Dictionary: match="/app/*/main.js"

2.2.1. Dictionary freshness requirement

To be considered as a match, the dictionary resource MUST be either fresh [HTTP-CACHING] or allowed to be served stale (see eg [RFC5861]).¶

2.2.2. Dictionary URL matching

When a dictionary is stored as a result of a "Use-As-Dictionary" directive, it includes a "match" string and optional "match-dest" string that are used to match an outgoing request from a client to the available dictionaries.¶

To see if an outbound request matches a given dictionary, the following algorithm will return TRUE for a successful match and FALSE for no-match:¶

1. If the current client supports request destinations and a "match-dest" string was provided with the dictionary:¶

   • Let DEST be the value of "match-dest" for the given dictionary.¶

   • Let REQUEST_DEST be the value of the destination for the current request.¶

   • If DEST is not an empty list and if REQUEST_DEST is not in the DEST list of destinations, return FALSE¶

2. Let BASEURL be the URL of the dictionary request.¶

3. Let URL represent the URL of the outbound request being checked.¶

4. If the Origin of BASEURL and the Origin of URL are not the same, return FALSE (see Section 4.3.1 of [HTTP]).¶

5. Let MATCH be the value of "match" for the given dictionary.¶

6. Let PATTERN be a URL pattern created by running the steps to create a URL pattern by setting input=MATCH, and baseURL=URL (see Part "create" of [URLPATTERN]).¶

7. Return the result of running the "match" steps on PATTERN with input=URL which will check for a match between the request URL and the supplied "match" string (see Part "match" of [URLPATTERN]).¶

2.2.3. Multiple matching dictionaries

When there are multiple dictionaries that match a given request URL, the client MUST pick a single dictionary using the following rules:¶

1. For clients that support request destinations, a dictionary that specifies and matches a "match-dest" takes precedence over a match that does not use a destination.¶

2. Given equivalent destination precedence, the dictionary with the longest "match" takes precedence.¶

3. Given equivalent destination and match length precedence, the most recently fetched dictionary takes precedence.¶

9.3.1. Cross-origin protection

To make sure that a dictionary can only impact content from the same origin where the dictionary was served, the URL Pattern used for matching a dictionary to requests (Section 2.1.1) is guaranteed to be for the same origin that the dictionary is served from.¶

9.3.2. Response readability

For clients, like web browsers, that provide additional protection against the readability of the payload of a response and against user tracking, additional protections MUST be taken to make sure that the use of dictionary-based compression does not reveal information that would not otherwise be available.¶

In these cases, dictionary compression MUST only be used when both the dictionary and the compressed response are fully readable by the client.¶

In browser terms, that means that both are either same-origin to the context they are being fetched from or that the response is cross-origin and passes the CORS check (see Part "CORS check" of [FETCH]).¶

9.3.3. Server Responsibility

As with any usage of compressed content in a secure context, a potential timing attack exists if the attacker can control any part of the dictionary, or if it can read the dictionary and control any part of the content being compressed, while performing multiple requests that vary the dictionary or injected content. Under such an attack, the changing size or processing time of the response reveals information about the content, which might be sufficient to read the supposedly secure response.¶

In general, a server can mitigate such attacks by preventing variations per request, as in preventing active use of multiple dictionaries for the same content, disabling compression when any portion of the content comes from uncontrolled sources, and securing access and control over the dictionary content in the same way as the response content. In addition, the following requirements on a server are intended to disable dictionary-aware compression when the client provides CORS request header fields that indicate a cross-origin request context.¶

The following algorithm will return FALSE for cross-origin requests where precautions such as not using dictionary-based compression should be considered:¶

1. If there is no "Sec-Fetch-Site" request header then return TRUE.¶

2. if the value of the "Sec-Fetch-Site" request header is "same-origin" then return TRUE.¶

3. If there is no "Sec-Fetch-Mode" request header then return TRUE.¶

4. If the value of the "Sec-Fetch-Mode" request header is "navigate" or "same-origin" then return TRUE.¶

5. If the value of the "Sec-Fetch-Mode" request header is "cors":¶

   • If the response does not include an "Access-Control-Allow-Origin" response header then return FALSE.¶

   • If the request does not include an "Origin" request header then return FALSE.¶

   • If the value of the "Access-Control-Allow-Origin" response header is "*" then return TRUE.¶

   • If the value of the "Access-Control-Allow-Origin" response header matches the value of the "Origin" request header then return TRUE.¶

6. return FALSE.¶