The HTTPRepr-Digestrequest andresponse header provides adigest of the selected representation of the target resource.It can be used validate the integrity of the whole selected representation once it has been received and reconstructed.

Theselected representation is the specific format of a resource chosen throughcontent negotiation.Details about the representation can be determined fromrepresentation headers, such asContent-Language,Content-Type, andContent-Encoding.

The representation digest applies to the whole representation rather than the encoding or chunking of the messages that are used to send it.AContent-Digest applies to the content of a specific message, and will have different values based on theContent-Encoding andContent-Range of each message.

Syntax

Repr-Digest: <digest-algorithm>=<digest-value>// Multiple digest algorithmsRepr-Digest: <digest-algorithm>=<digest-value>,…,<digest-algorithmN>=<digest-valueN>

Directives

<digest-algorithm>

The algorithm used to create a digest of the representation.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 representation 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.

Usage of insecure digest algorithms is discouraged as collisions can realistically be forced, rendering the digest's usefulness weak.Unless working with legacy systems (which is unlikely since most will expect the deprecatedDigest header and not understand this specification), consider omitting aRepr-Digest instead of including one with an insecure digest algorithm.

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 sending a Repr-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.

HTTP response whereRepr-Digest andContent-Digest coincide

An HTTP server may send the whole representation unencoded in a single message.In this case,Repr-Digest andContent-Digest have equal values for the same digest algorithms:

…Repr-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=:Content-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=:…Content-Type: text/yamlContent-Encoding: brContent-Length: 38054Content-Range: 0-38053/38054…[message body]

HTTP responses whereRepr-Digest andContent-Digest diverge

A server may compress the content for sending.In this caseContent-Digest will depend on theContent-Encoding, and will therefore have a different value to theRepr-Digest header in a response:

…Repr-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=:, sha-512=:U59TCCaZPA9Qio3CzHJVAgDnIAut53t5Sgkj2Gv4BvDd0b+OX9QpIdgWkzdXLmBsmvBrf3t5PBt+UrVK6k5dkw==:Content-Digest: sha-256=:293wcr5IoFAsDCzdoDXR1Qppgf2yxOPO1bvQ3nZQtuI=:, unixsum=54809…Content-Type: text/html; charset=utf-8Content-Encoding: br…[message body]

In another response, the server uses a different compression method, resulting in a newContent-Digest, but the sameRepr-Digest digests:

…Repr-Digest: sha-256=:AEGPTgUMw5e96wxZuDtpfm23RBU3nFwtgY5fw4NYORo=:, sha-512=:U59TCCaZPA9Qio3CzHJVAgDnIAut53t5Sgkj2Gv4BvDd0b+OX9QpIdgWkzdXLmBsmvBrf3t5PBt+UrVK6k5dkw==:Content-Digest: sha-256=:rv9Jivc4TmcacLUshzN3OdX7Hz+ORnQRaiTaIKZQ0zk=:…Content-Type: text/html; charset=utf-8Content-Encoding: zstd…[message body]

Successful HTTP request-response employingWant-Repr-Digest,Repr-Digest, andContent-Digest

The followingPUT request includes aWant-Repr-Digest header, indicating that the server should include aRepr-Digest header with asha-256 digest if the operation is successful:

PUT /api/transact HTTP/1.1Want-Repr-Digest: sha-256=8Content-Type: text/json…[message body]

The server responds with a successful201 Created response, includingRepr-Digest andContent-Digest headers with sha-256 digests of the representation and content, respectively:

HTTP/1.1 201 CreatedRepr-Digest: sha-256=:W8oN3H3CmE/CBpV6ZPNozV2AIDzzQpWL7CCOXyDyDzI=:Content-Encoding: brContent-Digest: sha-256=:2IBI7hQn83oTCgB3Z/6apOl91WGoctRfRj/F9gkvVo8=:…[message body]

Unsuccessful HTTP request-response employingRepr-Digest

In the following message, a user-agent requests a resource with a specific sha-256 digest:

GET /api/last-transaction HTTP/1.1Accept: text/jsonRepr-Digest: sha-256=:2IBI7hQn83oTCgB3Z/6apOl91WGoctRfRj/F9gkvVo8=:…

A406 Not Acceptable is returned by the server to indicate the operation failed given a specific digest for the resource.ARepr-Digest header is included with the SHA-256 digest value that would result in a successful response if the user-agent repeated the request with that value:

HTTP/1.1 406 Not AcceptableRepr-Digest: sha-256=:W8oN3H3CmE/CBpV6ZPNozV2AIDzzQpWL7CCOXyDyDzI=:…

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

• Content-Digest,Want-Content-Digest,Want-Repr-Digest
• ETag
• Content-Encoding
• Digital Signatures for APIs SDK guide usesContent-Digests for digital signatures in HTTP calls (developer.ebay.com)