Summary

  • Want-Content-Digest and Want-Repr-Digest communicate algorithm preferences. They do not negotiate a binding obligation: the recipient can ignore the preference, choose another algorithm or omit the requested integrity field without creating a protocol error.
  • Integrity has four separate states: the preference that was sent, the field that actually returned, the HTTP object covered by that field, and the receiver's own calculation and policy result. Collapsing those states turns a useful signal into a false guarantee.
  • A digest detects a mismatch for the covered bytes; it does not authenticate the sender, authorize an operation, preserve privacy or protect unrelated message metadata. Those properties require separate controls, and signatures must explicitly cover the digest and relevant representation metadata.

A preference is not an exchange of promises

The most dangerous HTTP integrity failure may occur before anybody hashes a byte. It happens when an implementation treats a request for evidence as if the evidence had already been promised.

RFC9530 defines two preference fields. Want-Content-Digest asks for preferences concerning a digest of the message content. Want-Repr-Digest does the same for a digest of the selected representation. Both fields use a Structured Fields dictionary whose keys name digest algorithms and whose integer values express relative preference. The scale runs from 1, the least preferred, to 10, the most preferred; zero means not acceptable.

Those weights are rankings, not security grades and not validation results. A value of ten does not mean “ten units of integrity,” and it does not oblige the peer to use that algorithm. The receiver of a preference may ignore the field, return a digest using an algorithm absent from the preference list, or return no digest field. RFC9530 says that none of those outcomes is inherently a protocol error. An application can impose a stricter requirement, but that requirement comes from the application contract, not from the Want-* field alone.

The same distinction applies in the other direction. A response carrying Want-Content-Digest or Want-Repr-Digest tells the client which integrity fields the server would like on future requests. It does not describe a digest of the current response. This makes the preference fields useful for coordination while preventing them from masquerading as proof.

Appendix C of RFC9530 makes the operational freedom concrete. A server may choose a less-preferred supported algorithm, encounter only unsupported choices, or answer with an application-selected 4xx or 5xx response. The specification does not standardize one mandatory status code or problem format for every failure to satisfy a preference. A system that needs deterministic failure behaviour must define it locally and test it end to end.

Four states, not one “digest enabled” flag

Many dashboards and middleware settings reduce the feature to a Boolean: digest requested, digest enabled or digest valid. That representation hides the decisions that matter. A reliable receipt needs at least four distinct records.

First is the requested preference: which field was sent, which algorithms were named and what relative ordering was expressed. Second is the observed response: whether Content-Digest or Repr-Digest actually appeared, which members it contained and whether it arrived in a header or trailer. Third is the covered object: the message content as transferred in this HTTP message, or the selected representation defined by HTTP semantics. Fourth is the local result: which supported member the recipient calculated, whether the bytes matched, and what the application decided to do.

Only the final three states can support a claim about received evidence. Even then, the claim must be narrow. “The client preferred SHA-512” is not “the server returned SHA-512.” “The server returned sha-256” is not “the recipient calculated and matched it.” “A digest matched” is incomplete until the operator knows which field was used and which bytes it covered.

This separation also prevents a quiet compatibility outcome from being logged as an integrity success. If a recipient prefers one algorithm but accepts another, the event may be perfectly valid. It is nevertheless a policy decision worth preserving. If no digest arrives and the application continues, the correct record is an explicit absence accepted under local policy—not a successful validation with an empty detail field.

Content and representation are different evidence objects

RFC9530 replaces the ambiguous Digest terminology inherited from RFC3230 with two named fields. Content-Digest covers the actual message content. Repr-Digest covers the entire selected representation associated with the message under HTTP semantics. The difference is not cosmetic.

Message content is the content carried in one request or response after the relevant transfer framing has been handled. A selected representation is the resource representation chosen for the request context, including the effects of representation metadata. Partial transfers make the distinction especially visible, but it also matters whenever content codings or representation selection change the bytes under discussion.

An operator therefore cannot validate either field by hashing a convenient file without first identifying the covered object. Content-Type and Content-Encoding influence the representation and its interpretation. A resource can have multiple representations, and the same semantic resource can yield different octet sequences under different codings. RFC9530 also notes that representation digests on state-changing methods follow the representation metadata: a PATCH request may carry a patch document, while a response can describe the selected representation of the updated resource. Content-Location and Location do not provide interchangeable identities for that purpose.

These distinctions are why a generic “payload checksum” field in an internal API often proves too vague. The implementation should record whether it verified content or representation, the metadata used to select or decode that object and the point in processing at which the bytes were captured. Otherwise two systems can both report a correct digest while having calculated over different material.

Algorithm agility includes the right to reject

The current IANA registry lists SHA-512 and SHA-256 as active HTTP digest algorithms. Older entries such as MD5, SHA, UNIX sum variants, Adler-32 and CRC32C are deprecated. RFC9530 permits deprecated algorithms for some non-adversarial corruption-detection uses, but says they must not be used where an adversary or digital-signature context matters.

That registry status is a starting point, not a complete acceptance policy. A recipient may ignore any or all digest members and can constrain the algorithms and number of calculations it will perform. The reasons are both cryptographic and operational. Computing several digests over large content consumes time and memory bandwidth; allowing an unbounded set chosen by a peer creates an avoidable resource surface. Accepting every syntactically recognized algorithm, meanwhile, makes the weakest accepted member part of the system's security posture.

Algorithm agility does not itself prevent downgrade or substitution. Suppose a response includes both a strong and a deprecated member. If one component verifies the easiest supported member while another assumes the strongest preference was honoured, the two components have different integrity claims. The safe record is not “digest valid.” It is the exact algorithm selected by local policy, the exact field, the covered object and the match outcome.

Applications should therefore maintain separate lists for understood algorithms and acceptable algorithms. They should bound how many members they calculate, decide whether one acceptable match is enough, define what happens when only deprecated or unknown members arrive, and preserve that decision in telemetry. None of this requires a global HTTP authority to approve each transaction. It requires the participants to make their own acceptance rule explicit.

Arrival time is part of the evidence

Both integrity fields can appear in headers or trailers. Trailers are useful when the sender cannot know the digest until it has streamed the content. They also create a lifecycle problem: intermediaries can drop trailers, and an application can act on content before the trailer arrives.

A receiver that commits a state change, releases a file or forwards data before trailer validation cannot later describe the earlier action as integrity-gated. It may still validate for audit or corruption detection, but the timing must be recorded honestly. A trailer that never reaches the application is absence, not a successful check hidden by infrastructure.

Persistence introduces another boundary. A matching digest proves something about the covered bytes at the validation point. It is not continuing proof that storage remains unchanged unless the entire covered content is stored and checked again. Content codings and transformations can also produce multiple valid byte sequences for what users regard as the same material. An integrity receipt should therefore name the processing stage as well as the algorithm and field.

Digests do not protect the rest of HTTP

RFC9530 is explicit about the limits. Content-Digest and Repr-Digest do not protect the whole message. They do not bind the method, target URI, status code or every representation metadata field. They do not authenticate the party that supplied the value, authorize the request or conceal the content.

HTTP Message Signatures can cover digest fields, but the signer must explicitly include them and any relevant representation metadata in the signature base. Merely placing a digest beside a signature does not create that binding. The signature design also needs its own key, identity, time and replay policy. A digest mismatch can show that calculated bytes differ from the supplied value; it cannot by itself say who caused the difference or whether the operation was allowed.

This boundary is useful rather than disappointing. It lets digest fields remain focused, interoperable integrity evidence. Systems can then combine them with transport protection, authorization, signatures and storage controls according to the actual threat model. Trouble begins only when the small mechanism is advertised as the whole security outcome.

Sources and evidence boundary

This article interprets the standards and their governance implications. Transaction examples are hypothetical. It does not claim a measured deployment rate, incident count, attack frequency, processing cost or universally safe threshold.