1.1.1.Version Upgrade

Using a previous version of a resource as a dictionary for a newer versionenables delivery of a delta-compressed version of the changes, usuallyresulting in significantly smaller responses than what can be achieved bycompression alone.¶

For example:¶

1.1.2.Common Content

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

For example:¶

2.1.1."match"

The "match" value of the "Use-As-Dictionary" response header is a String value thatprovides 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 avalid URL Pattern that does not use regular expressions and is for the sameOrigin (Section 4.3.1 of [HTTP]) as the dictionary. It will return TRUEfor a valid match pattern and FALSE for an invalid pattern thatMUST NOT beused.¶

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 struct" created by running the steps to "create aURL pattern" by setting input=MATCH and baseURL=URL (seeSection 1.4 of [URLPATTERN]).¶

4. If the result of running the "has regexp groups" steps for PATTERN returnsTRUE, then return FALSE (see the last list inSection 1.4 of [URLPATTERN]).¶

5. Return TRUE.¶

The "match" value is required andMUST 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 thepercent-encoded version of the URL path (seeSection 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" response header is an Inner List ofString values that provides a list of Fetch request destinations for thedictionary to match (see "RequestDestination" inSection 5.4 of [FETCH]).¶

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

For clients that do not support request destinations, the clientMUST treat itas 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" response header is a String value that specifiesa server identifier for the dictionary. If an "id" value is present and has astring length longer than zero, then itMUST be sent to the server in a"Dictionary-ID" request header when the client sends an "Available-Dictionary"request header for the same dictionary (seeSection 2.2).¶

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

The server identifierMUST NOT be relied upon by the server to guarantee thecontents of the dictionary. The dictionary hashMUST be validated before use.¶

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

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

2.1.4."type"

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

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

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

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

2.1.5.Examples

NOTE: '\' line wrapping per RFC 8792Use-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 resourceMUST be either fresh[HTTP-CACHING] or allowed to be served stale (see[RFC5861]).¶

2.2.2.Dictionary URL Matching

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

To see if an outbound request matches a given dictionary, the followingalgorithm 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, returnFALSE (seeSection 4.3.1 of [HTTP]).¶

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

6. Let PATTERN be a "URL pattern struct" created by running the steps to "create a URL pattern" by setting input=MATCH and baseURL=URL (seeSection 1.4 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 "Match" inSection 1.4 of [URLPATTERN]).¶

2.2.3.Multiple Matching Dictionaries

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

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

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

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

9.3.1.Cross-Origin Protection

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

9.3.2.Response Readability

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

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

In browser terms, that means either the dictionary and compressed response are same-origin to the context they are being fetched from or the response is cross-origin and passes the Cross-Origin Resource Sharing (CORS) check (seeSection 4.9 of [FETCH]).¶

9.3.3.Server Responsibility

As with any usage of compressed content in a secure context, a potentialtiming attack exists if the attacker can control any part of the dictionaryor if it can read the dictionary and control any part of the content beingcompressed while performing multiple requests that vary the dictionary orinjected content. Under such an attack, the changing size or processing timeof the response reveals information about the content, which might besufficient to read the supposedly secure response.¶

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

The following algorithm will return FALSE for cross-origin requests whereprecautions such as not using dictionary-based compression should beconsidered:¶

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

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

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

4. If the value of the "Sec-Fetch-Mode" request header is "navigate" or"same-origin", 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, return FALSE.¶

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

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

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

6. Return FALSE.¶