chore(http): Delete "Digest" and "Want-Digest", improve digest pages (#…

…36879)

* chore(http): Add spec URLs for Digest headers

* chore(http): Minor edit to digest headers docs

* chore(http): Delete and redirect Digest and Want-Digest

* chore(http): Delete and redirect Digest and Want-Digest

* chore(http): Update Content-Digest and Repr-Digest pages

* chore(http): Improve language in Digest pages

* chore(http): Improve language in Digest pages

* chore(http): Fix redirects for HTTP digest headers

* Apply suggestions from code review

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

* chore(http): Improve language in Digest pages

* chore(http): Improve language in Digest pages

* Update files/en-us/web/http/headers/repr-digest/index.md

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

---------

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

files/en-us/_redirects.txt

@@ -12292,6 +12292,7 @@
 /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/referrer	/en-US/docs/Web/HTTP/Headers/Referrer-Policy
 /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-sri-for	/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
 /en-US/docs/Web/HTTP/Headers/Cookie2	/en-US/docs/Web/HTTP/Headers/Cookie
+/en-US/docs/Web/HTTP/Headers/Digest	/en-US/docs/Web/HTTP/Headers/Content-Digest
 /en-US/docs/Web/HTTP/Headers/Feature-Policy	/en-US/docs/Web/HTTP/Headers/Permissions-Policy
 /en-US/docs/Web/HTTP/Headers/Feature-Policy/accelerometer	/en-US/docs/Web/HTTP/Headers/Permissions-Policy/accelerometer
 /en-US/docs/Web/HTTP/Headers/Feature-Policy/ambient-light-sensor	/en-US/docs/Web/HTTP/Headers/Permissions-Policy/ambient-light-sensor
@@ -12337,6 +12338,7 @@
 /en-US/docs/Web/HTTP/Headers/Ranges	/en-US/docs/Web/HTTP/Headers/Range
 /en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite	/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value
 /en-US/docs/Web/HTTP/Headers/Set-Cookie2	/en-US/docs/Web/HTTP/Headers/Set-Cookie
+/en-US/docs/Web/HTTP/Headers/Want-Digest	/en-US/docs/Web/HTTP/Headers/Want-Content-Digest
 /en-US/docs/Web/HTTP/History_of_HTTP_versions	/en-US/docs/Web/HTTP/Evolution_of_HTTP
 /en-US/docs/Web/HTTP/Index	/en-US/docs/Web/HTTP
 /en-US/docs/Web/HTTP/Link_prefetching_FAQ	/en-US/docs/Glossary/Prefetch

files/en-us/_wikihistory.json

@@ -99613,10 +99613,6 @@
     "modified": "2020-10-15T22:23:16.957Z",
     "contributors": ["mfuji09", "darby", "bershanskiy"]
   },
-  "Web/HTTP/Headers/Digest": {
-    "modified": "2020-10-15T22:21:39.013Z",
-    "contributors": ["ioggstream", "wbamberg"]
-  },
   "Web/HTTP/Headers/ETag": {
     "modified": "2020-10-15T21:48:49.703Z",
     "contributors": [
@@ -100238,10 +100234,6 @@
       "teoli"
     ]
   },
-  "Web/HTTP/Headers/Want-Digest": {
-    "modified": "2020-10-15T22:21:41.704Z",
-    "contributors": ["wbamberg"]
-  },
   "Web/HTTP/Headers/Warning": {
     "modified": "2020-10-15T21:48:41.051Z",
     "contributors": ["chrisdavidmills", "janslow", "PotHix", "fscholz"]

files/en-us/glossary/quality_values/index.md

@@ -42,5 +42,5 @@ Some syntax, like the one of {{HTTPHeader("Accept")}}, allow additional specifie
 
 ## More information
 
-- [HTTP headers](/en-US/docs/Web/HTTP/Headers) using q-values in their syntax: {{HTTPHeader("Accept")}}, {{HTTPHeader("Accept-Encoding")}}, {{HTTPHeader("Accept-Language")}}, {{HTTPHeader("TE")}}, {{HTTPHeader("Want-Digest")}}.
+- [HTTP headers](/en-US/docs/Web/HTTP/Headers) using q-values in their syntax: {{HTTPHeader("Accept")}}, {{HTTPHeader("Accept-Encoding")}}, {{HTTPHeader("Accept-Language")}}, {{HTTPHeader("TE")}}.
 - [Header field definitions.](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)

files/en-us/glossary/representation_header/index.md

@@ -36,10 +36,9 @@ Representation headers are not mutually exclusive with {{Glossary("Content heade
 
 ## See also
 
-- [RFC 9110, section 3.2: Representations](https://httpwg.org/specs/rfc9110.html#representations)
-- [List of all HTTP headers](/en-US/docs/Web/HTTP/Headers)
 - Related glossary terms:
   - {{Glossary("Content header")}}
+- [RFC 9110, section 3.2: Representations](https://httpwg.org/specs/rfc9110.html#representations)
+- [List of all HTTP headers](/en-US/docs/Web/HTTP/Headers)
 - {{HTTPHeader("Repr-Digest")}}, {{HTTPHeader("Want-Repr-Digest")}}
 - {{HTTPHeader("Content-Digest")}}, {{HTTPHeader("Want-Content-Digest")}}
-- {{HTTPHeader("Digest")}} {{Deprecated_Inline}}, {{HTTPHeader("Want-Digest")}} {{Deprecated_Inline}}

files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md

@@ -271,7 +271,7 @@ The following macros are included on all reference pages, but are also supported
   - : Generates a [compatibility table](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables) for the feature passed as the parameter. If no parameter is included, it defaults to the features defined by `browser-compat` in the frontmatter. An optional depth parameter sets how deep sub features should be added to the table. The depth, if omitted, defaults to 1, meaning only the first level of sub feature data from BCD will be included.
 
 - `\{{Specifications}}` / `\{{Specifications(<feature>)}}`
-  - : Includes the specification for the feature specified in the parameter. If no parameter is passed, the specification listed is defined by the value for `spec_urls` in the frontmatter, if present, or from the specification listed in browser compatibility data defined by `browser-compat` in the frontmatter. The specification is rendered as an external link.
+  - : Includes the specification for the feature specified in the parameter. If no parameter is passed, the specification listed is defined by the value for `spec-urls` in the frontmatter, if present, or from the specification listed in browser compatibility data defined by `browser-compat` in the frontmatter. The specification is rendered as an external link.
 
 ## See also
 

files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md

@@ -25,7 +25,7 @@ To include the (appropriate) feature status key — [**experimental**](/en-US/do
 
 ### Specifications
 
-In the value of the `spec_urls` front matter metadata key, update the URLs to point to the fragment IDs for the correct sections from the following specifications:
+In the value of the `spec-urls` front matter metadata key, update the URLs to point to the fragment IDs for the correct sections from the following specifications:
 
 - [ARIA](https://w3c.github.io/aria/)
 - [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)

files/en-us/web/http/headers/content-digest/index.md

@@ -2,18 +2,20 @@
 title: Content-Digest
 slug: Web/HTTP/Headers/Content-Digest
 page-type: http-header
-spec-urls: https://datatracker.ietf.org/doc/html/rfc9530
+spec-urls: https://datatracker.ietf.org/doc/html/rfc9530#section-2
 ---
 
 {{HTTPSidebar}}
 
-The HTTP **`Content-Digest`** header provides a {{Glossary("digest")}} of the message content in an HTTP message.
-As such, `Content-Digest` is dependent on among other things {{HTTPHeader("Content-Encoding")}} and {{HTTPHeader("Content-Range")}}, but not dependent on, for example, HTTP/1.1's {{HTTPHeader("Transfer-Encoding")}}.
-`Content-Digest` may coincide with {{HTTPHeader("Repr-Digest")}} if a representation was sent in a single message.
+The HTTP **`Content-Digest`** {{Glossary("request header", "request")}} and {{Glossary("response header")}} provides a {{Glossary("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.
 
-In this setting, _content_ refers to a particular octet representation of the [selected representation](https://www.rfc-editor.org/rfc/rfc9110#section-6.4) of the target resource.
+The {{HTTPHeader("Want-Content-Digest")}} field lets a sender request a `Content-Digest` along with their hashing algorithm preferences.
+A content digest will differ based on {{HTTPHeader("Content-Encoding")}} and {{HTTPHeader("Content-Range")}}, but not {{HTTPHeader("Transfer-Encoding")}}.
 
-A client can request that a server emit a `Content-Digest` by issuing {{HTTPHeader("Want-Content-Digest")}}.
+In certain cases, a {{HTTPHeader("Repr-Digest")}} can be used to validate the integrity of partial or multipart messages against the full representation.
+For example, in [range requests](/en-US/docs/Web/HTTP/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 {{HTTPHeader("Repr-Digest")}} when a representation is sent in a single message.
 
 <table class="properties">
   <tbody>
@@ -30,27 +32,113 @@ A client can request that a server emit a `Content-Digest` by issuing {{HTTPHead
 
 ## Syntax
 
-`Content-Digest` describes an [RFC8941 dictionary](https://www.rfc-editor.org/rfc/rfc8941#section-3.2) with its keys being names of digest algorithms and its values being the digest in bytes (or an integer digest for legacy digest algorithms).
-
-> [!NOTE]
-> 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](https://www.rfc-editor.org/rfc/rfc8941#name-byte-sequences).
-
 ```http
-Content-Digest: <digest-algorithm>=:<standard-padded-base64-digest-value>:, ...
-Content-Digest: <digest-algorithm-integer-checksum>=<integer-checksum-value>, ...
+Content-Digest: <digest-algorithm>=<digest-value>
+
+// Multiple digest algorithms
+Content-Digest: <digest-algorithm>=<digest-value>,<digest-algorithm>=<digest-value>, …
 ```
 
 ## Directives
 
-For permissible digest algorithms see {{HTTPHeader("Repr-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 {{Glossary("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](https://www.rfc-editor.org/rfc/rfc8941#name-byte-sequences).
+
+## 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
 
-```plain
-Content-Digest: unixcksum=916142062
-Content-Digest: md5=:+thA//8pGVGk2VYuJkFNvA==:, unixsum=26869
+### 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:
+
+```http
+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
+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:
+
+```http
+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
+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 {{HTTPMethod("HEAD")}} method instead of a {{HTTPMethod("GET")}}, the `Repr-Digest` and `Content-Digest` fields will be different:
+
+```http
+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
+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`:
+
+```http
+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
 
 {{Specifications}}
@@ -62,5 +150,7 @@ Developers can set and get HTTP headers using `fetch()` in order to provide appl
 
 ## See also
 
-- {{HTTPHeader("Repr-Digest")}}, {{HTTPHeader("Want-Content-Digest")}}, {{HTTPHeader("Want-Repr-Digest")}}
+- {{HTTPHeader("Want-Content-Digest")}} header to request a content digest
+- {{HTTPHeader("Repr-Digest")}}, {{HTTPHeader("Want-Repr-Digest")}} representation digest headers
 - {{HTTPHeader("ETag")}}
+- [Digital Signatures for APIs](https://developer.ebay.com/develop/guides/digital-signatures-for-apis) SDK guide uses `Content-Digest`s for digital signatures in HTTP calls (developer.ebay.com)

files/en-us/web/http/headers/index.md

@@ -141,18 +141,12 @@ For more information, refer to the [CORS documentation](/en-US/docs/Web/HTTP/COR
 
 - {{HTTPHeader("Content-Digest")}} {{experimental_inline}}
   - : Provides a {{Glossary("digest")}} of the stream of octets framed in an HTTP message (the message content) dependent on {{HTTPHeader("Content-Encoding")}} and {{HTTPHeader("Content-Range")}}.
-- {{HTTPHeader("Digest")}} {{deprecated_inline}} {{non-standard_inline}}
-  - : Provides a {{Glossary("digest")}} of the a resource.
-    See {{HTTPHeader("Content-Digest")}} and {{HTTPHeader("Repr-Digest")}}.
 - {{HTTPHeader("Repr-Digest")}} {{experimental_inline}}
   - : Provides a {{Glossary("digest")}} of the selected representation of the target resource before transmission.
     Unlike the {{HTTPHeader("Content-Digest")}}, the digest does not consider {{HTTPHeader("Content-Encoding")}} or {{HTTPHeader("Content-Range")}}.
 - {{HTTPHeader("Want-Content-Digest")}} {{experimental_inline}}
   - : States the wish for a {{HTTPHeader("Content-Digest")}} header.
     It is the `Content-` analogue of {{HTTPHeader("Want-Repr-Digest")}}.
-- {{HTTPHeader("Want-Digest")}} {{deprecated_inline}} {{non-standard_inline}}
-  - : States the wish for a {{HTTPHeader("Digest")}} header.
-    See {{HTTPHeader("Want-Content-Digest")}} and {{HTTPHeader("Want-Repr-Digest")}} instead.
 - {{HTTPHeader("Want-Repr-Digest")}} {{experimental_inline}}
   - : States the wish for a {{HTTPHeader("Repr-Digest")}} header.
     It is the `Repr-` analogue of {{HTTPHeader("Want-Content-Digest")}}.