Content-Digest

The HTTP Content-Digest request and response header provides a digest calculated using a hashing algorithm applied to the message content. A recipient can use the Content-Digest to validate the HTTP message content for integrity purposes.

The Want-Content-Digest field lets a sender request a Content-Digest along with their hashing algorithm preferences. A content digest will differ based on Content-Encoding and Content-Range, but not Transfer-Encoding.

In certain cases, a Repr-Digest can be used to validate the integrity of partial or multipart messages against the full representation. For example, in range requests, a Repr-Digest will always have the same value if only the requested byte ranges differ, whereas the content digest will be different for each part. For this reason, a Content-Digest is identical to a Repr-Digest when a representation is sent in a single message.

Syntax

Content-Digest: <digest-algorithm>=<digest-value>

// Multiple digest algorithms
Content-Digest: <digest-algorithm>=<digest-value>,<digest-algorithm>=<digest-value>, …

Directives

<digest-algorithm>

The algorithm used to create a digest of the message content. Only two registered digest algorithms are considered secure: sha-512 and sha-256. The insecure (legacy) registered digest algorithms are: md5, sha (SHA-1), unixsum, unixcksum, adler (ADLER32) and crc32c.

<digest-value>

The digest in bytes of the message content using the <digest-algorithm>. The choice of digest algorithm also determines the encoding to use: sha-512 and sha-256 use base64 encoding, while some legacy digest algorithms such as unixsum use a decimal integer. In contrast to earlier drafts of the specification, the standard base64-encoded digest bytes are wrapped in colons (:, ASCII 0x3A) as part of the dictionary syntax.

Description

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.

Examples

User-agent request for a SHA-256 Content-Digest

In the following 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:

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/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:

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 whole resource is sent in one message:

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:

GET /items/123 HTTP/1.1
Host: example.com

The Repr-Digest value will be the same as before, but there is no message body, so a different Content-Digest would be sent by the server:

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 the following 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:

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.

Specifications

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.

See also

• Want-Content-Digest header to request a content digest
• Repr-Digest, Want-Repr-Digest representation digest headers
• ETag
• Digital Signatures for APIs SDK guide uses Content-Digests for digital signatures in HTTP calls (developer.ebay.com)