Issues on Content-Digest page

[LPardue]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Digest

What specific section or headline is this issue about?

No response

What information was incorrect, unhelpful, or incomplete?

There are several cases on this page that seem problematic. Below are some high-level points but also low-level issues related to the actual digest values. My blog post https://lucaspardue.com/2026/08/08/http-integrity/ may help with some more understanding of the low-level issues.

There is some overlap with the Repr-Digest MDN page but I'll open a separate issue for that.

1. A general observation: there is syntax section omits that the field is a Structured Header. Personally I find this omission a problem as it may imply some other syntax rules. See (2) for an example.

2. Under directives the following statement is problematic:

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.

Content-Digest is defined as a Structured Fields Dictionary where the value is Byte Sequence. Therefore, Content-Digest values are always base64 encoded. The language in https://www.rfc-editor.org/info/rfc9651/#section-3.3.5 explains the format of Byte Sequence and the URL it links to is good but the label "dictionary syntax" is inaccurate - Dictionary can hold any value type.

The "In contrast to earlier drafts ..." sentence seems noisy and somewhat distracting so I would strike that and focus the text a bit more on Byte Sequence.

3. The description discusses the now obsolete Digest header. This seems like a distraction. Since Digest was not widely used, consider dropping any mention of it. If you want to keep something, I think converting it to a very short note at the end of the first section would suffice.

4. The examples https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Digest#user-agent_request_for_a_sha-256_content-digest and https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Digest#identical_content-digest_and_repr-digest_values are problematic because it is unclear over what bytes the digest is calculated.

It seems this example uses the value {"hello": "world"} and digest value :RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:, which seems copied from RFC 9530 (i.e. https://www.rfc-editor.org/info/rfc9530/#appendix-B.1). RFC 9530 makes it very clear that.

Content-Digest and Repr-Digest are both computed over the JSON object {"hello": "world"} followed by an LF

The MDN example does not make that clear, therefore it is hard for a reader to reproduce the digest correctly.

Furthermore, the second example includes Content-Length: 19 which doesn't make sense unless knowledge of the LF is available.

5. The example https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Digest#diverging_content-digest_and_repr-digest_values seems overly complicated because it doesn't explain that the Content-Digest included in the message is hash of an empty string. This again seems lifted from RFC 9530 and I'm not sure it really helps demonstrate the concepts well.

It might be better to have two different examples. One to show just the Content-Digest of a response to a HEAD request that includes the digest of an empty string (while also highlighting that omitting Content-Digest is also fine if there is not content). A second example to demonstrate differences between Content-Digest and Repr-Digest due to range requests; a 206 partial response can contain a subset of the resource as content triggering different values for Content-Digest and Repr-Digest.

6. The example https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Digest#user-agent_sending_a_content-digest_in_requests is fundamentally broken. It states

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:

This is wrong. The example POST request includes the the full, encoded, object. Therefore Content-Digest and Repr-Digest will be identical.

The statement:

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.

Is strange. Either recipient of Content-Digest or Repr-Digest can do validation. Making this comment in this example doesn't seem useful - its probably something that should be mentioned at the top of the page. The second paragraph is outright wrong, Repr-Digest is calculated over the representation i.e., the encoded object.

The use of fake digest values is problematic:

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
}

Generally, any examples that are provided should make it abundantly clear what the digest input is, and use actual calculated digest values that can be verified by readers. In the absence of that, readers can be left confused.

What did you expect to see?

Exaplained above

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

No response

MDN metadata

Page report details

• Folder: en-us/web/http/reference/headers/content-digest
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Digest
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/http/reference/headers/content-digest/index.md
• Last commit: 7ed7b73
• Document last modified: 2026-07-28T05:29:56.000Z