Maintaining HTTP Integrity Fields in Cached and Cache-Generated Responses

Introduction HTTP Integrity fields associate digest values with specific kinds of data. Content-Digest applies to the content of an HTTP message, while Repr-Digest applies to the complete selected representation data . Unencoded-Digest applies to complete selected representation data after content codings have been removed . The distinctions matter when a cache changes the relationship between stored metadata and bytes. For example: a 304 Not Modified response has no content, but its fields can update a stored 200 OK response that has content; a HEAD response has no content, but RFC 9111 permits its fields to freshen a stored GET response; multiple stored 206 Partial Content responses can be combined into a complete response or a larger partial response; a cache can construct a 206 response from a stored complete response; and an intermediary can transform content coding while preserving some representation metadata. RFC 9111 defines generic field-copying and stored-response maintenance rules. Applying those rules without regard to the input defined for an Integrity field can detach a digest value from that input. A cache could then serve correct bytes with a digest value for empty content, one constituent range, a complete response rather than a generated range, or a differently coded representation. This document adds a narrow, field-specific exception to the RFC 9111 cache state machine. It does not change the data covered by any Integrity field and does not require a cache to implement a digest algorithm. Removal is always the conservative fallback when a cache cannot establish the required association.

Scope This document specifies cache behavior for: updating stored response fields, including updates performed after 304 validation and HEAD freshening; combining partial responses; constructing 304, HEAD, and 206 responses from stored state; transforming content coding; and resolving dictionary-member conflicts created by those operations. This document does not: redefine Content-Digest, Repr-Digest, or Unencoded-Digest; change when a response can be stored, selected, validated, combined, or reused; define validator-free proof that two representations have identical data; define new digest algorithms or require support for any particular digest algorithm; define message authentication, authorization, or HTTP Message Signature processing; or generalize these rules to fields other than the three named Integrity fields.

Conventions and Terminology 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 when, and only when, they appear in all capitals, as shown here. Terms defined by HTTP Semantics , HTTP Caching , Digest Fields , Structured Fields , and HTTP Unencoded Digest are used as defined by those specifications.

Covered Integrity field: One of Content-Digest, Repr-Digest, or Unencoded-Digest.
Integrity member: One algorithm-keyed dictionary member of a covered Integrity field after the field value has been combined and parsed according to its defining specification.
Defined input: The sequence of octets to which the defining specification applies an Integrity member's digest algorithm. The defined input depends on the field, as described in .
Association: The relationship between an Integrity member and the defined input to which that field occurrence applies. Preserving association means preserving that relationship through a cache operation. It does not prove that the sender calculated the member correctly or that the member authenticates the data.
Association witness: Information sufficient under this document to establish that a member's defined input is unchanged across a cache operation.
Representation-selection context: The target resource and selected stored response, including applicable secondary cache-key selection, already determined by the RFC 9111 operation. This document does not broaden that context or make a validator applicable to another resource or variant.
Participating source: A stored or received response whose fields RFC 9111 would use in the cache update, combination, or response-construction operation being performed.

Integrity Association Requirement When a cache operation would retain, install, or emit an Integrity member, the cache MUST do one of the following: establish that the member remains associated with the resulting response's defined input using an association witness permitted for that field; calculate the member over the resulting response's defined input; or remove the member. If no members remain in a covered Integrity field after applying this requirement, the cache MUST remove that field. A cache that does not implement or support a member's digest algorithm can comply by removing the member; it is not required to calculate or validate a digest. This requirement is member-specific. One algorithm member can be retained while another member in the same field is removed. Different covered Integrity fields are evaluated independently because they can have different defined inputs. Association is distinct from digest correctness. A cache can preserve a member received from a sender without validating it when the defined input is unchanged. Conversely, a digest value that happens to be correct for some other input cannot be moved to the resulting response merely because its syntax and algorithm are valid.

Field Inputs and Association Witnesses

Content-Digest Content-Digest applies to the actual content of the message in which the field occurs . Its permitted association witnesses are: direct calculation or validation over the exact resulting message content; or proof that the resulting message content consists of exactly the same octets, in the same order, as the content to which the retained member applied. A shared strong entity tag is neither necessary nor sufficient as a Content-Digest association witness. The same selected representation can be conveyed in messages having different content, including a complete response, a range response, and a response with no content.

Repr-Digest Repr-Digest applies to the complete coded selected representation data . Its permitted association witnesses are: direct calculation or validation over the exact complete selected representation data; or within one RFC 9111 stored-response update, partial-response combination, or cache response-construction operation, the same strong entity tag on the source and resulting selected representations, compared using the strong comparison function defined in Section 8.8.3.2 of RFC 9110 . The strong-validator witness applies only within the same representation selection context used by the cache operation. It does not make entity tags portable between unrelated resources or representation-selection contexts. An entity tag retained for upstream validation after a cache operation that changed the complete coded selected representation data is not a Repr-Digest association witness for the changed data. That restriction applies to later stored-response updates, partial-response combinations, and response construction. The witness becomes available again only when the cache directly establishes that the resulting complete coded representation data are the data identified by the tag. A direct digest calculation or validation over the resulting data remains sufficient independently of the tag. A weak entity tag, a modification date, a content length, or a validator-free freshening path is not an association witness for installing a new Repr-Digest member. Those signals do not establish octet-for-octet identity of the complete coded selected representation data.

Unencoded-Digest Unencoded-Digest applies to the complete selected representation data after all content codings have been removed . Its permitted association witnesses are: direct calculation or validation over the exact decoded representation data; or a permitted Repr-Digest association witness plus an identical effective, ordered Content-Encoding decoding chain on the source and resulting responses. The effective decoding chain includes every input that the definition of each content coding says can affect the decoded octets, including parameters carried in other response fields or supplied by applicable context. Content-coding names are compared case-insensitively and their order remains significant, but equal names and order are not sufficient when a coding has additional decoding inputs. If the cache cannot identify and compare the complete effective decoding configuration, this witness is unavailable. Absence of Content-Encoding in the resulting stored response represents an empty decoding chain. Omission of Content-Encoding or of a coding's auxiliary input from an updating response is not, by itself, evidence of an empty or unchanged chain; the cache first applies the ordinary HTTP field update rules to determine the resulting metadata. A shared strong entity tag alone is not sufficient. Representation data can remain the same while response metadata changes how that data is decoded.

Updating Stored Response Fields This section adds a field-semantics exception to the field-update requirements in Section 3.2 of RFC 9111. A cache MUST apply the requirements in this section whenever fields from a new response would add to or replace fields in a stored response. The cache MUST determine the source field value using the field-update precedence of RFC 9111 before applying the member-level association rules in this document. If an updating response omits a covered field, ordinary HTTP rules determine whether the stored field remains. If the updating response contains a covered field, its parsed dictionary key set replaces the stored key set. A key omitted from that present dictionary is withdrawn and MUST NOT be restored from the replaced stored field. An incoming member that lacks a required association witness is recalculated or removed; removing it does not revive a replaced member. The cache MUST determine the resulting response and the defined input for each covered Integrity field before it installs or retains that field's members. Generic add-or-replace processing MUST NOT override the association requirement in .

Updating Content-Digest When an update retains stored message content: when the updating response omits Content-Digest, a previously stored member can be retained when ordinary HTTP update rules retain the field and the member remains associated with that exact content; when the updating response contains Content-Digest, a member from that field MUST NOT be installed unless the updating message content and retained content are exactly the same octets, or the cache recalculates or validates the member over the retained content; and otherwise, the cache MUST remove the member. In particular, a Content-Digest member for the empty content of a 304 or HEAD response does not apply to non-empty content retained from a stored GET response.

Updating Repr-Digest When an update retains complete selected representation data and the updating response omits Repr-Digest, a cache can retain an already-associated stored member when ordinary HTTP update rules retain the field. When the updating response contains Repr-Digest, the cache can install a member from that field only when: the cache directly establishes the exact complete representation data; or the stored and updating responses have the same strong entity tag under strong comparison in the representation-selection context of the update, and the tag is eligible under . If neither condition is satisfied, the cache MUST recalculate or remove the incoming member. It MUST NOT revive a replaced stored member or install the updating member based only on a weak entity tag, modification date, content length, or validator-free match.

Updating Unencoded-Digest The Repr-Digest update rules apply to the complete coded representation-data part of the Unencoded-Digest witness. In addition, the cache MUST establish that the effective ordered content-coding decoding chain is unchanged, or it MUST directly establish the exact decoded representation data. If it cannot do so, it MUST follow the field-source precedence above and recalculate or remove the applicable member. It MUST NOT revive a replaced stored member or install the updating member using a strong entity tag alone.

Freshening Stored Responses

Freshening upon Validation with 304 When a cache uses a 304 Not Modified response to update one or more stored responses as described in Section 4.3.4 of RFC 9111, it MUST apply separately to each stored response being updated. The 304 response's message content is empty. Therefore, a Content-Digest member in that response is associated with empty content and MUST NOT replace a stored member associated with non-empty retained content. For Repr-Digest and Unencoded-Digest, the cache applies the whole-representation witnesses in and the conflict rules in . The selection of stored responses to update remains governed by RFC 9111. This document constrains only the covered Integrity members installed or retained after that selection.

Freshening with HEAD When a cache uses a HEAD response to update or invalidate a stored GET response as described in Section 4.3.5 of RFC 9111, it MUST apply . A HEAD response has no message content. A Content-Digest member associated with its empty content MUST NOT replace a stored member associated with non-empty GET response content. For Repr-Digest, an eligible matching strong entity tag under provides a whole-representation association witness. A weak entity tag, matching Last-Modified, matching Content-Length, or a validator-free HEAD path does not provide that witness for installing a new member. For Unencoded-Digest, the cache additionally needs an unchanged complete effective decoding configuration or direct decoded-data proof. If HEAD response metadata changes that configuration, or the cache cannot identify all inputs to it, a shared strong entity tag alone is insufficient. This document does not change RFC 9111's conditions for using HEAD to update or invalidate a stored response.

Combining Partial Content This section adds requirements for covered Integrity fields to Section 3.4 of RFC 9111. It applies when a cache combines stored partial responses into a complete response or into a larger partial response. The existing RFC 9111 requirement that the partial responses share the same strong validator remains necessary. It is not sufficient for every covered Integrity field. For the combined response: a constituent Content-Digest member MUST NOT be copied onto the combined content unless the constituent content is exactly the resulting content; the cache MUST instead recalculate the member over the resulting content or remove it; a Repr-Digest member can be retained when the eligible shared strong entity tag and representation-selection context provide the witness in ; and an Unencoded-Digest member can be retained only when the same witness plus the effective ordered content-coding requirement in is satisfied. These requirements apply whether the result is a complete 200 response or a larger 206 response. They do not change range-set combination, completeness, or storage eligibility.

Constructing Responses from Stored State A cache that constructs a response from stored state is the sender of that response for the purpose of selecting which stored fields to emit. It MUST apply the association requirement to the response actually sent.

Generated 304 and HEAD Responses When a cache generates a 304 response or a response to HEAD from a stored response: it MUST NOT copy a Content-Digest member for stored GET content onto the generated response; it can omit Content-Digest or calculate it over the generated response's empty content, subject to the field's defining rules; and it can emit an already-associated Repr-Digest or Unencoded-Digest member when the selected representation and, for Unencoded-Digest, decoding-chain association remain applicable. This section does not require a cache to add a field that the applicable HTTP response semantics permit it to omit.

Generated 206 Responses When a cache generates a 206 Partial Content response from a stored complete or partial response: Content-Digest applies to the actual single-range or multipart message content generated by the cache; the cache MUST calculate a member over that exact content or remove it; Repr-Digest can retain a member associated with the complete selected representation data; and Unencoded-Digest can retain a member associated with the complete decoded selected representation data when its decoding-chain witness remains applicable. For a multipart response, the Content-Digest input includes the multipart serialization actually sent, including its boundaries and per-part fields. A digest for a complete stored response or for one range is not a digest for a different generated range or multipart serialization.

Content-Coding Transformations When a cache transforms content coding while storing a response or constructing a response from stored state, it MUST evaluate each covered Integrity field against the transformed response: if the actual outgoing message content changes, Content-Digest MUST be recalculated over that content or removed; if the complete coded selected representation data changes, Repr-Digest MUST be recalculated over that data or removed; and Unencoded-Digest can be retained only when the cache establishes that the complete decoded representation data are unchanged; otherwise, it MUST be recalculated or removed. A strong entity tag does not override these requirements. In particular, it does not prove that a Content-Digest remains applicable across a generated range or that an Unencoded-Digest remains applicable across a changed decoding chain. When a transformation changes the complete coded selected representation data, an upstream entity tag retained for validation MUST NOT later be used as a Repr-Digest association witness for the transformed data. The cache MUST retain this restriction for as long as it retains the transformed state. If the required transformation provenance is unavailable, including after a restart or restoration of stored state, the strong-validator witness is unavailable and the cache MUST use direct proof, recalculate the member, or remove it. This document does not change the transformation controls in HTTP, including Cache-Control: no-transform.

Dictionary Members and Conflicts Covered Integrity fields are dictionaries. A cache MUST apply the following rules independently to each algorithm key after parsing the field according to its defining specification and applying the field-source precedence in . These rules do not union algorithm keys from a field value that RFC 9111 replaces. The cache applies these rules: After a present updating field replaces a stored field under , members from the replaced stored field are not participating sources for purposes of this section. If only one participating source supplies a member and the cache has the field-specific association witness, the cache can retain that member. If multiple participating sources supply identical member values for the same algorithm key and the cache has the required association witness, the cache can retain one such member. If participating sources supply different member values for the same algorithm key while claiming the same defined input, the cache MUST recalculate that member or remove it. It MUST NOT select one merely because it was received most recently. Absence of the entire field from an updating response follows ordinary HTTP update rules and is not, by itself, a member conflict. When the updating response contains the field, absence of an algorithm key from its parsed dictionary withdraws that key from the resulting field. Members with different algorithm keys are independent. A cache that cannot parse a covered field sufficiently to apply these rules MUST remove that field when the cache operation would otherwise move it to a different defined input. This document does not change the defining specification's handling of malformed fields on an otherwise unmodified response. An unsupported algorithm is not itself an association failure. A cache can carry an unsupported member through an operation that preserves its defined input. If the input changes or cannot be established, the cache MUST remove the unsupported member because recomputation is unavailable.

Trailer Fields RFC 9111 requires trailer fields to be stored separately from header fields or discarded. This document does not change that rule. Field placement does not change a covered Integrity field's defined input. During initial storage and every stored-response update, a cache MUST keep a retained trailer field separate from stored header fields or discard it. The association and conflict rules in this document do not authorize a merger in stored state. If a cache applies an update to separately stored trailer state, it MUST apply the same field-source, association, and conflict rules within that trailer state without merging the two sections. When constructing a new outgoing response, a cache MAY merge a retained trailer field into the outgoing header section only when the HTTP version, response status, and covered field's defining specification permit that placement and define the merger. The cache MUST apply the same association and conflict rules that would apply without the merger. A generated 304 response has no trailer section. This output-only permission does not change the storage rule in Section 3.1 of RFC 9111.

Examples The examples use sha-256 members and small content solely to make every defined input independently checkable. They use the line-wrapping convention from RFC 8792 ; the backslash and following indentation are not part of the field value.

Bodyless Update Suppose a cache stores the content abcdef with:

The cache later receives:

The member on the 304 applies to empty message content and cannot be installed on the retained abcdef content. Because the updating response contains Content-Digest, its parsed key set replaces the stored key set. The cache therefore recalculates the sha-256 member over abcdef or removes it. Recalculation produces the value previously stored, but the cache does not retain that previous member merely as a fallback. The same result applies when the bodyless update is a HEAD response used under Section 4.3.5 of RFC 9111.

Combining Two Partial Responses Suppose a cache receives two combinable partial responses with content abc and def. The Content-Digest value on the abc response is:

The value on the def response is:

Neither member applies to the combined content abcdef. If the cache emits a combined response with Content-Digest, it calculates:

Otherwise, it removes the member. A nonconflicting Repr-Digest for the complete selected representation can remain when the shared strong-validator witness applies.

Generating a Range Response Suppose a cache stores abcdef and generates a single-range 206 containing abc. The complete response's Content-Digest member for abcdef cannot be copied. If the generated 206 carries Content-Digest, its member is the digest of abc:

A whole-representation Repr-Digest or Unencoded-Digest can remain when its field-specific witness applies.

Implementation and Test Considerations An implementation can comply without implementing any digest algorithm by tracking the source and defined-input class of covered members and removing a member whenever an allowed witness is unavailable. A minimum test corpus ought to exercise: 304 and HEAD updates with absent, identical, and conflicting members; empty-content Content-Digest members applied to retained non-empty content; strong, weak, date-based, and validator-free update paths; combination into complete and larger partial responses; cache-generated single-range and multipart 206 responses; cache-generated HEAD and 304 responses; identity-to-coded, coded-to-identity, and coding-to-coding transformations; a transformed stored response followed by an upstream 304 carrying the retained entity tag and a pre-transformation Repr-Digest; identical coding names with changed or unavailable auxiliary decoder inputs; identical, conflicting, withdrawn, malformed, and unsupported algorithm members; and fields received in headers and trailers, including separate stored placement and a permitted output-only merger. Tests need to compare the final field values with the exact message content, complete coded representation data, and complete decoded representation data as applicable. Status codes and cache-hit indicators alone are insufficient to establish correct association.

Deployment Question Section 4.3.5 of RFC 9111 permits a cache to update or invalidate stored GET responses after receiving a successful response to HEAD. A cache that invalidates the stored response or obtains a complete response using GET does not exercise the metadata-update path governed by . The author is not aware of a documented deployed implementation that uses a successful HEAD response to update a stored GET response while retaining its content. Implementation reports for that path are requested. This absence does not change the requirements for a cache that chooses the update path and does not imply that the path is unused in all deployments.

Security Considerations Digest fields do not provide authenticity by themselves. The security considerations of RFC 9530 and HTTP Unencoded Digest continue to apply. Recalculating, removing, or changing an Integrity field can cause an HTTP Message Signature that covers that field to fail validation. This document does not change signature processing under RFC 9421 . Detaching an Integrity member from its defined input can cause a recipient to reject correct content, accept an assertion about different data as though it described the received data, or make different implementations reach incompatible verification results. The association requirement prevents a cache from creating those outcomes through field maintenance or response construction. Removal is conservative with respect to association, but it can remove an integrity signal on which an application expected to rely. Applications that require an Integrity field need to treat its absence according to the field's defining specification and their own security policy. This document does not turn field presence into an authorization or authentication decision. Recalculation can consume CPU and memory, especially for large representations or multipart responses. A cache can always choose removal instead. An implementation SHOULD bound buffering and digest work according to its resource policy and MUST NOT weaken ordinary cache isolation, authorization, or representation-selection boundaries to obtain an association witness. A shared strong entity tag is used only as the narrow whole-representation witness defined in this document. It does not authenticate the response, prove the sender's digest calculation, authorize cross-resource reuse, or justify carrying Content-Digest across messages with different content. An upstream tag retained after transformation is likewise not positive evidence that the transformed representation data are unchanged. An updating response that contains a covered dictionary controls the algorithm keys retained from that field. Treating an omitted key as withdrawn prevents a cache from silently extending the sender's algorithm set with an older member. This is distinct from an update that omits the entire field, which remains governed by the ordinary HTTP field-update rules.

IANA Considerations This document requests no IANA action.

Updates to RFC 9111 This document updates RFC 9111 in the following places: Section 3.2 gains the exception for covered Integrity fields in ; Section 3.4 gains the combination requirements in ; Sections 4.3.4 and 4.3.5 gain the freshening requirements in ; and cache response construction, including Section 4 and Section 4.3.2, gains the generated-response requirements in . RFC 9111 Sections 3.1 and 3.3 remain inputs to these rules but are not otherwise changed. This document does not alter when incomplete responses can be stored, combined, selected, validated, or reused.

Summary of Required Outcomes The following table is non-normative. The preceding sections define the requirements. Cache operation Content-Digest Repr-Digest Unencoded-Digest 304 or HEAD updates stored GET If the field is omitted, preserve an associated stored member; if present, apply its key set and recalculate or remove inapplicable members; do not install an empty-content member on non-empty content If the field is omitted, preserve an associated stored member; an updater member requires direct proof or an eligible strong validator with no intervening input-changing transformation Repr proof plus the complete unchanged decoding configuration, or direct decoded-data proof; present-field key replacement also applies Combine partial responses Recompute over combined content or remove Retain with whole-representation witness and no conflict Repr proof plus the complete unchanged decoding configuration and no conflict Generate HEAD or 304 Omit or calculate over empty content; do not copy GET-content member Retain associated whole-representation member Retain associated whole-decoded-representation member Generate 206 Recompute over exact single-range or multipart content, or remove Retain associated whole-representation member Retain associated whole-decoded-representation member Transform content coding Recompute over outgoing content or remove Recompute over resulting coded representation data or remove; a retained upstream tag is not a later witness Retain only with exact decoded-data proof; otherwise recompute or remove

Change Log This is the initial -00 revision.