From a8f881645d776d1303a0a25bd884f95e1b2805e1 Mon Sep 17 00:00:00 2001 From: Brian Smith Date: Mon, 25 Nov 2024 10:00:06 +0100 Subject: [PATCH] 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 * 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 --------- Co-authored-by: Hamish Willee --- files/en-us/_redirects.txt | 2 + files/en-us/_wikihistory.json | 8 -- files/en-us/glossary/quality_values/index.md | 2 +- .../glossary/representation_header/index.md | 5 +- .../macros/commonly_used_macros/index.md | 2 +- .../page_types/aria_page_template/index.md | 2 +- .../web/http/headers/content-digest/index.md | 126 +++++++++++++--- files/en-us/web/http/headers/digest/index.md | 81 ----------- files/en-us/web/http/headers/index.md | 6 - .../web/http/headers/repr-digest/index.md | 41 +++++- .../web/http/headers/want-digest/index.md | 136 ------------------ 11 files changed, 150 insertions(+), 261 deletions(-) delete mode 100644 files/en-us/web/http/headers/digest/index.md delete mode 100644 files/en-us/web/http/headers/want-digest/index.md diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index bf2b4099989edf6..5a32e4155f3125e 100644 --- a/files/en-us/_redirects.txt +++ b/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 diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index d4a8c8b1b1509d1..aa4e7911a32b797 100644 --- a/files/en-us/_wikihistory.json +++ b/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"] diff --git a/files/en-us/glossary/quality_values/index.md b/files/en-us/glossary/quality_values/index.md index 2afeff504922a5d..9bf79e2aeeaf791 100644 --- a/files/en-us/glossary/quality_values/index.md +++ b/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) diff --git a/files/en-us/glossary/representation_header/index.md b/files/en-us/glossary/representation_header/index.md index 183574e19fac551..423ee9f172bcb45 100644 --- a/files/en-us/glossary/representation_header/index.md +++ b/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}} diff --git a/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md b/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md index 17500669ec2fac6..cef410e3683fd26 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/macros/commonly_used_macros/index.md +++ b/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 diff --git a/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md b/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md index b4eca1a751ce669..ed1bd7e7c0854ea 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/page_types/aria_page_template/index.md +++ b/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/) diff --git a/files/en-us/web/http/headers/content-digest/index.md b/files/en-us/web/http/headers/content-digest/index.md index d63e06bf52aaa6e..b64760b96e41160 100644 --- a/files/en-us/web/http/headers/content-digest/index.md +++ b/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. @@ -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: =::, ... -Content-Digest: =, ... +Content-Digest: = + +// Multiple digest algorithms +Content-Digest: =,=, … ``` ## Directives -For permissible digest algorithms see {{HTTPHeader("Repr-Digest")}}. +- `` + - : 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`. +- `` + - : The digest in bytes of the message content using the ``. + 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) diff --git a/files/en-us/web/http/headers/digest/index.md b/files/en-us/web/http/headers/digest/index.md deleted file mode 100644 index 783dbd9e9ffd0cb..000000000000000 --- a/files/en-us/web/http/headers/digest/index.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Digest -slug: Web/HTTP/Headers/Digest -page-type: http-header -status: - - deprecated - - non-standard -browser-compat: http.headers.Digest ---- - -{{HTTPSidebar}}{{Deprecated_Header}}{{non-standard_header}} - -> [!NOTE] -> This header was removed from the specification in [draft 8](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-digest-headers-08). -> Use {{HTTPHeader("Content-Digest")}} instead. -> For `id-*` digest algorithms, use {{HTTPHeader("Repr-Digest")}}. - -The HTTP **`Digest`** {{Glossary("request header")}} and {{Glossary("response header")}} provides the recipient with a {{Glossary("digest")}} of the {{HTTPHeader("Content-Encoding")}}-encoded _selected representation_. -It can be requested by using the {{HTTPHeader("Want-Digest")}} header. - -Representations are different forms of a particular resource that might be returned from a request: for example, the same resource might be formatted in a particular media type such as XML or JSON, localized to a particular written language or geographical region, and/or compressed or otherwise encoded for transmission. -The _selected representation_ is a resource returned following [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation), and can be determined from the response's {{Glossary("Representation header","Representation headers")}}. - -The digest applies to the whole representation of a resource, not to a particular message. -It can be used to verify that the representation data has not been modified during transmission. - -> [!NOTE] -> While a representation may be fully contained in the message body of a single response, it can also be sent using multiple messages in response to a [range request](/en-US/docs/Web/HTTP/Range_requests), or omitted altogether in response to a {{HTTPMethod("HEAD")}} request. - -
- - - - - - - - - - -
Header type{{Glossary("Response header")}}, {{Glossary("Request header")}}
{{Glossary("Forbidden header name")}}No
- -## Syntax - -```http -Digest: = -Digest: =,= -``` - -## Directives - -- `` - - : Digest algorithm values are defined in [6. Digest Algorithm Values](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-digest-headers-07#name-digest-algorithm-values). - - Permitted digest algorithm values are: `sha-512` and `sha-256` - - Permitted insecure digest algorithm values are: `md5`, `sha`, `unixsum`, `unixcksum`, `adler32` and `crc32c` - - Deprecated digest algorithm values include: `id-sha-256`, `id-sha-512` -- `` - - : The result of applying the digest algorithm to the resource representation and encoding the result (for non-`id-*` digest algorithm values). - The choice of digest algorithm also determines the encoding to use: for example SHA-256 uses base64 encoding, whilst unixsum is represented by a decimal integer. - -## Examples - -```http -Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= -Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=,unixsum=30637 -Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=,id-sha-256=0KJL0PvNLH5UbYZLTT7DBFuSyxKpnjyadrWx5E90E/z= -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTTPHeader("Want-Digest")}} -- [HTTP range requests](/en-US/docs/Web/HTTP/Range_requests) -- {{HTTPStatus("206", "206 Partial Content")}} diff --git a/files/en-us/web/http/headers/index.md b/files/en-us/web/http/headers/index.md index a5a557791d51554..80930c93da6f119 100644 --- a/files/en-us/web/http/headers/index.md +++ b/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")}}. diff --git a/files/en-us/web/http/headers/repr-digest/index.md b/files/en-us/web/http/headers/repr-digest/index.md index e71299d244c113c..ec85527ff89bc67 100644 --- a/files/en-us/web/http/headers/repr-digest/index.md +++ b/files/en-us/web/http/headers/repr-digest/index.md @@ -8,12 +8,13 @@ spec-urls: https://datatracker.ietf.org/doc/html/rfc9530 {{HTTPSidebar}} The HTTP **`Repr-Digest`** {{Glossary("Request header", "request")}} and {{Glossary("Response header", "response header")}} provides a {{Glossary("digest")}} 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. The _selected representation_ is the specific format of a resource chosen through [content negotiation](/en-US/docs/Web/HTTP/Content_negotiation). -Details about this representation can be determined from the response's {{Glossary("Representation header", "representation headers")}}, such as {{HTTPHeader("Content-Language")}}, {{HTTPHeader("Content-Type")}}, and {{HTTPHeader("Content-Encoding")}}. +Details about the representation can be determined from {{Glossary("Representation header", "representation headers")}}, such as {{HTTPHeader("Content-Language")}}, {{HTTPHeader("Content-Type")}}, and {{HTTPHeader("Content-Encoding")}}. -The representation digest applies to the whole resource rather than the encoding or chunking of the messages that are used to send it. -This differs from {{HTTPHeader("Content-Digest")}} which applies to the content of a particular message, and is therefore is affected by the {{HTTPHeader("Content-Encoding")}} and {{HTTPHeader("Content-Range")}} of each message. +The representation digest applies to the whole representation rather than the encoding or chunking of the messages that are used to send it. +A {{HTTPHeader("Content-Digest")}} applies to the content of a specific message, and will have different values based on the {{HTTPHeader("Content-Encoding")}} and {{HTTPHeader("Content-Range")}} of each message. @@ -49,10 +50,37 @@ Repr-Digest: =,= 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). 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 legacy {{HTTPHeader("Digest")}} header and not understand this specification), consider omitting a `Repr-Digest` instead of including one with an insecure digest algorithm. +Unless working with legacy systems (which is unlikely since most will expect the deprecated `Digest` header and not understand this specification), consider omitting a `Repr-Digest` instead of including one with an insecure digest algorithm. + +## 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 +### 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 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. + ### HTTP response where `Repr-Digest` and `Content-Digest` coincide An HTTP server may send the whole representation unencoded in a single message. @@ -130,7 +158,7 @@ Content-Digest: sha-256=:2IBI7hQn83oTCgB3Z/6apOl91WGoctRfRj/F9gkvVo8=: ### Unsuccessful HTTP request-response employing `Repr-Digest` -In the following message, a client requests a resource with a specific sha-256 digest: +In the following message, a user-agent requests a resource with a specific sha-256 digest: ```http GET /api/last-transaction HTTP/1.1 @@ -140,7 +168,7 @@ Repr-Digest: sha-256=:2IBI7hQn83oTCgB3Z/6apOl91WGoctRfRj/F9gkvVo8=: ``` A {{HTTPStatus("406", "406 Not Acceptable")}} is returned by the server to indicate the operation failed given a specific digest for the resource. -A `Repr-Digest` header is included with the SHA-256 digest value that would result in a successful response if the client repeated the request with that value: +A `Repr-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 HTTP/1.1 406 Not Acceptable @@ -162,3 +190,4 @@ Developers can set and get HTTP headers using `fetch()` in order to provide appl - {{HTTPHeader("Content-Digest")}}, {{HTTPHeader("Want-Content-Digest")}}, {{HTTPHeader("Want-Repr-Digest")}} - {{HTTPHeader("ETag")}} - {{HTTPHeader("Content-Encoding")}} +- [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) diff --git a/files/en-us/web/http/headers/want-digest/index.md b/files/en-us/web/http/headers/want-digest/index.md deleted file mode 100644 index e3a9f85b58bd250..000000000000000 --- a/files/en-us/web/http/headers/want-digest/index.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Want-Digest -slug: Web/HTTP/Headers/Want-Digest -page-type: http-header -status: - - deprecated - - non-standard -browser-compat: http.headers.Want-Digest ---- - -{{HTTPSidebar}}{{Deprecated_Header}}{{non-standard_header}} - -> [!NOTE] -> This header was removed from the specification in [draft 8](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-digest-headers-08). -> Use {{HTTPHeader("Want-Content-Digest")}} instead. -> For `id-*` digest algorithms, use {{HTTPHeader("Want-Repr-Digest")}}. - -The **`Want-Digest`** request or response HTTP header requests the other side to provide a {{Glossary("digest")}} using the {{HTTPHeader("Digest")}} header. - -The header contains identifiers for one or more digest algorithms that the sender wishes the server to use to create the digest. -The request may use {{Glossary("quality values")}} to indicate its preference/order for particular digest algorithms. - -If `Want-Digest` does not include any digest algorithms that the server supports, the server may respond with: - -- a digest calculated using a different digest algorithm, or -- a [`400 Bad Request`](/en-US/docs/Web/HTTP/Status/400) error, and include another `Want-Digest` header with that response, listing the algorithms that it does support. - -See also the {{HTTPHeader("Digest")}} header. - -
- - - - - - - - - - -
Header type - {{Glossary("Request header")}}, - {{Glossary("Response header")}} -
{{Glossary("Forbidden header name")}}no
- -## Syntax - -```http -Want-Digest: - -// Multiple algorithms, weighted with the quality value syntax: -Want-Digest: , -``` - -## Directives - -- \ - - : Digest algorithms are defined in [Digest Headers](https://datatracker.ietf.org/doc/draft-ietf-httpbis-digest-headers/). - - Permitted digest algorithms values include: `unixsum`, `unixcksum`, `crc32c`, `sha-256` and `sha-512`, `id-sha-256`, `id-sha-512` - - Deprecated algorithms values include: `md5`, `sha`, `adler32`. -- \ - - : The [quality value](/en-US/docs/Glossary/Quality_values) to apply to that - option. - -## Examples - -```http -Want-Digest: sha-256 -Want-Digest: SHA-512;q=0.3, sha-256;q=1, md5;q=0 -``` - -### Basic operation - -The sender provides a list of digests which it is prepared to accept, and the server -uses one of them: - -Request: - -```http -GET /item -Want-Digest: sha-256;q=0.3, sha;q=1 -``` - -Response: - -```http -HTTP/1.1 200 Ok -Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= -``` - -### Unsupported digests - -The server does not support any of the requested digest algorithms, so uses a different algorithm: - -Request: - -```http -GET /item -Want-Digest: sha;q=1 -``` - -Response: - -```http -HTTP/1.1 200 Ok -Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= -``` - -The server does not support any of the requested digest algorithms. -In this case it responds with a 400 error and includes another `Want-Digest` header, listing the algorithms that it does support: - -Request: - -```http -GET /item -Want-Digest: sha;q=1 -``` - -Response: - -```http -HTTP/1.1 400 Bad Request -Want-Digest: sha-256, sha-512 -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- {{HTTPHeader("Digest")}}