Content-Digest

<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.

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 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"}

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"}

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

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.

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.

• 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)