HTTP Headers
Content Digest
HTTP Header
The HTTP Content-Digest header in both request and response messages provides a cryptographic hash value generated from the message content. This digest can be used by recipients to verify the integrity of the message content, ensuring it has not been altered during transmission.
The Want-Content-Digest header allows a sender to request that the recipient include a Content-Digest with their preferred hashing algorithm.
The resulting content digest will vary based on factors such as Content-Encoding and Content-Range, but it is unaffected by Transfer-Encoding.
In certain contexts, a Repr-Digest can be used to verify the integrity of partial or multipart messages against the complete representation.
For example, in range requests, a Repr-Digest remains consistent if only specific byte ranges are requested; however, the Content-Digest will differ for each individual part.
Therefore, a Content-Digest matches a Repr-Digest when the entire representation is transmitted within a single message.
| Header type | Request header, Response header, Representation header |
|---|---|
| Forbidden request header | No |
Syntax
http
Content-Digest: <digest-algorithm>=<digest-value>
// Multiple digest algorithms
Content-Digest: <digest-algorithm>=<digest-value>,<digest-algorithm>=<digest-value>, …
Directives
A Digest header was defined in previous specifications, but it proved problematic as the scope of what the digest applied to was not clear.
Specifically, it was difficult to distinguish whether a digest applied to the entire resource representation or to the specific content of a HTTP message.
As such, two separate headers were specified (Content-Digest and Repr-Digest) to convey HTTP message content digests and resource representation digests, respectively.
In the following examples, various scenarios involving Content-Digest and Repr-Digest headers are demonstrated to illustrate their usage and behavior.
Note: In all examples, the content adheres to best practices for message integrity verification using digest headers.
User-agent request for a SHA-256 Content-Digest
In this example, a user-agent requests a digest of the message content with a preference for SHA-256, followed by SHA-1 at a lower preference:
HTTP request:
GET /items/123 HTTP/1.1
Host: example.com
Want-Content-Digest: sha-256=10, sha=3
The server responds with a Content-Digest of the message content using the SHA-256 algorithm: HTTP response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Digest: sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:
{"hello": "world"}
Identical Content-Digest and Repr-Digest values
A user-agent requests a resource without a Want-Content-Digest field:
HTTP request:
GET /items/123 HTTP/1.1
Host: example.com
The server is configured to send unsolicited digest headers in responses. The Repr-Digest and Content-Digest fields have matching values because they are using the same algorithm, and in this case, the entire resource is sent in one message:
HTTP response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 19
Content-Digest: sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:
Repr-Digest: sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:
{"hello": "world"}
Diverging Content-Digest and Repr-Digest values
If the same request is repeated as the previous example, but uses a HEAD method instead of a GET, the Repr-Digest and Content-Digest fields will be different:
HTTP request:
HEAD /items/123 HTTP/1.1
Host: example.com
The Repr-Digest value remains the same, but since there is no message body, the server would send a different Content-Digest:
HTTP response:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
Repr-Digest: sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:
User-agent sending a Content-Digest in requests
In this example, a user-agent sends a digest of the message content using SHA-512.
It sends both a Content-Digest and a Repr-Digest, which differ from each other because of the Content-Encoding:
HTTP request:
POST /bank_transfer HTTP/1.1
Host: example.com
Content-Encoding: zstd
Content-Digest: sha-512=:ABC…=:
Repr-Digest: sha-512=:DEF…=:
{
"recipient": "Alex",
"amount": 900000000
}
The server may calculate a digest of the content it has received and compare the result with the Content-Digest or Repr-Digest headers to validate the message integrity.
In requests like the example above, the Repr-Digest is more useful to the server as this is calculated over the decoded representation and would be more consistent in different scenarios.
Browser compatibility
This header has no specification-defined browser integration (“browser compatibility” does not apply).
Developers can set and get HTTP headers using fetch() in order to provide application-specific implementation behavior.
How to Modify Header using Requestly
Requestly is a powerful Chrome extension that allows you to modify HTTP headers, including the Content-Digest header. This helps you test how your server handles different content integrity checks or troubleshoot caching and validation issues. Steps to Modify the Content-Digest Header:
- Install and open the Requestly Chrome extension. You can find it on the Chrome Web Store.
- Create a new rule: Click on “Create Rule” and choose “Modify Headers” from the list of available rule types.
- Add a new header modification:
- Under “Action”, select “Add” or “Override”.
- In the “Header Name” field, enter Content-Digest.
- In the “Header Value” field, enter your preferred digest value (e.g., sha-256=:abc123def456=:).
- Set the URL condition: Specify the URL or pattern where this header change should apply (e.g., https://your-api.com/*).
- Save the rule.
Once set up, Requestly will inject the Content-Digest header into all matching requests, allowing you to simulate different content integrity scenarios or debug cache validation behaviors on your server. You might need to modify the Content-Digest header to test how your application handles content verification or hashing methods. This is useful to ensure data integrity and secure communication between clients and servers.
Table of Contents
- No headings found.
