The HTTPContent-Digestrequest andresponse header provides adigest calculated using a hashing algorithm applied to the message content.A recipient can use theContent-Digest to validate the HTTP message content for integrity purposes.

TheWant-Content-Digest field lets a sender request aContent-Digest along with their hashing algorithm preferences.A content digest will differ based onContent-Encoding andContent-Range, but notTransfer-Encoding.

In certain cases, aRepr-Digest can be used to validate the integrity of partial or multipart messages against the full representation.For example, inrange requests, aRepr-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, aContent-Digest is identical to aRepr-Digest when a representation is sent in a single message.

Syntax

Content-Digest: <digest-algorithm>=<digest-value>// Multiple digest algorithmsContent-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 andsha-256.The insecure (legacy) registered digest algorithms are:md5,sha (SHA-1),unixsum,unixcksum,adler (ADLER32) andcrc32c.

<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 andsha-256 usebase64 encoding, while some legacy digest algorithms such asunixsum 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 thedictionary syntax.

Description

ADigest 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 andRepr-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.1Host: example.comWant-Content-Digest: sha-256=10, sha=3

The server responds with aContent-Digest of the message content using the SHA-256 algorithm:

HTTP/1.1 200 OKContent-Type: application/jsonContent-Digest: sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:{"hello": "world"}

Identical Content-Digest and Repr-Digest values

A user-agent requests a resource without aWant-Content-Digest field:

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

The server is configured to send unsolicited digest headers in responses.TheRepr-Digest andContent-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 OKContent-Type: application/jsonContent-Length: 19Content-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 aHEAD method instead of aGET, theRepr-Digest andContent-Digest fields will be different:

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

TheRepr-Digest value will be the same as before, but there is no message body, so a differentContent-Digest would be sent by the server:

HTTP/1.1 200 OKContent-Type: application/jsonContent-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 aContent-Digest and aRepr-Digest, which differ from each other because of theContent-Encoding:

POST /bank_transfer HTTP/1.1Host: example.comContent-Encoding: zstdContent-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 theContent-Digest orRepr-Digest headers to validate the message integrity.In requests like the example above, theRepr-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 usingfetch() 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 usesContent-Digests for digital signatures in HTTP calls (developer.ebay.com)