Want-Content-Digest

Content integrity verification requires a hash of the transmitted bytes. The Want-Content-Digest request and response header signals preference for a Content-Digest hash, negotiating which algorithm the server uses.

Table of Contents

Usage
Directives
Example
Preferences, honestly weighted
See also

Usage

The Want-Content-Digest header indicates which hashing algorithms the client prefers and supports for content integrity verification. The server reads this header and decides whether to include a Content-Digest header in the response with a hash computed using one of the requested algorithms.

This header is part of the HTTP integrity framework, which replaced the older Want-Digest header. The Content-Digest field provides a hash of the HTTP message content, which reflects any content encodings applied. This differs from Repr-Digest, which hashes the entire selected representation, including its content coding, and stays stable across range requests where a message carries only part of the data.

Clients typically use this header when downloading files or receiving responses where data integrity matters. The server response includes the computed hash, and the client verifies the received content matches by computing its own hash and comparing values. When the hashes match, the content arrived without corruption or tampering during transmission.

The header uses a dictionary format where each algorithm name maps to a preference weight from 0 to 10. A weight of 10 indicates the highest preference, 1 indicates the lowest preference, and 0 means the algorithm is explicitly not acceptable.

Directives

The Want-Content-Digest header uses algorithm identifiers as keys and integer preference weights as values. Multiple algorithms are separated by commas.

sha-256

The sha-256 algorithm requests a SHA-256 hash digest. SHA-256 produces a 256-bit hash and is widely supported across HTTP implementations.

sha-512

The sha-512 algorithm requests a SHA-512 hash digest. SHA-512 produces a 512-bit hash and offers stronger collision resistance than SHA-256 at the cost of larger digest size.

Preference weights

Each algorithm is followed by an equals sign and an integer from 0 to 10. Higher values indicate stronger preference. A value of 0 signals the client does not accept the algorithm.

Example

A client requesting SHA-256 integrity verification with a preference weight of 10. The server includes a Content-Digest header in the response using the requested algorithm.

Want-Content-Digest: sha-256=10

A client expressing preference for SHA-256 with a fallback to SHA-512. The weight of 10 for SHA-256 and 3 for SHA-512 indicates SHA-256 is strongly preferred. The unixsum=0 entry explicitly rejects the legacy Unix checksum algorithm.

Want-Content-Digest: sha-512=3, sha-256=10, unixsum=0

A server responding with the requested content digest, computed using SHA-256 as requested by the client.

Request

Want-Content-Digest: sha-256=10

Response

Content-Digest: sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:

Preferences, honestly weighted

Values run from 0 to 10, where 0 marks an algorithm unacceptable, 1 the least preferred, and 10 the most. The numbers are integer preferences rather than quality values, and some references shorten the range to 0 through 9, against the specification's 0 through 10.

The field is a hint in the strictest sense. Ignoring a preference is not a protocol error, the receiver answers with any algorithm or none, and a request carrying the header creates no obligation. On a response the direction reverses, asking the client to attach digests to future requests, which is the subtle reading most integrations miss.

The registry behind the keys is thin on live options: sha-256 and sha-512 are the two active algorithms, with md5, sha, and the checksum-era entries deprecated, permitted against corruption and forbidden anywhere an adversary matters.

Deployment reality favors the assertion side over the negotiation side. Content-Digest earns production use as a signed component inside HTTP message signatures, covering request bodies for bot authentication, while the Want- negotiation fields see near-zero traffic. A digest states integrity, and integrity alone: without a signature over the digest, anyone rewriting the body rewrites the hash alongside.