idnits 2.17.00 (12 Aug 2021) /tmp/idnits39989/draft-ietf-httpbis-digest-headers-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document date (21 March 2022) is 54 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'CMU-836068' -- Possible downref: Non-RFC (?) normative reference: ref. 'IACR-2020-014' -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST800-32' ** Downref: Normative reference to an Informational RFC: RFC 1321 ** Downref: Normative reference to an Informational RFC: RFC 1950 ** Downref: Normative reference to an Informational RFC: RFC 3174 ** Downref: Normative reference to an Informational RFC: RFC 6234 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNIX' Summary: 4 errors (**), 0 flaws (~~), 0 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP R. Polli 3 Internet-Draft Team Digitale, Italian Government 4 Obsoletes: 3230 (if approved) L. Pardue 5 Intended status: Standards Track Cloudflare 6 Expires: 22 September 2022 21 March 2022 8 Digest Fields 9 draft-ietf-httpbis-digest-headers-08 11 Abstract 13 This document defines HTTP fields that support integrity digests. 14 The Repr-Digest field can be used for the integrity of HTTP 15 representations. The Content-Digest field can be used for the 16 integrity of HTTP message content. Want-Repr-Digest and Want- 17 Content-Digest can be used to indicate a sender's interest and 18 preferences for receiving the respective Integrity fields. 20 This document obsoletes RFC 3230 and the Digest and Want-Digest HTTP 21 fields. 23 About This Document 25 This note is to be removed before publishing as an RFC. 27 Status information for this document may be found at 28 https://datatracker.ietf.org/doc/draft-ietf-httpbis-digest-headers/. 30 Discussion of this document takes place on the HTTP Working Group 31 mailing list (mailto:ietf-http-wg@w3.org), which is archived at 32 https://lists.w3.org/Archives/Public/ietf-http-wg/. Working Group 33 information can be found at https://httpwg.org/. 35 Source for this draft and an issue tracker can be found at 36 https://github.com/httpwg/http-extensions/labels/digest-headers. 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at https://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on 22 September 2022. 55 Copyright Notice 57 Copyright (c) 2022 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 62 license-info) in effect on the date of publication of this document. 63 Please review these documents carefully, as they describe your rights 64 and restrictions with respect to this document. Code Components 65 extracted from this document must include Revised BSD License text as 66 described in Section 4.e of the Trust Legal Provisions and are 67 provided without warranty as described in the Revised BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 72 1.1. Document Structure . . . . . . . . . . . . . . . . . . . 4 73 1.2. Concept Overview . . . . . . . . . . . . . . . . . . . . 4 74 1.3. Obsoleting RFC 3230 . . . . . . . . . . . . . . . . . . . 5 75 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 6 76 2. The Repr-Digest Field . . . . . . . . . . . . . . . . . . . . 7 77 2.1. Using Repr-Digest in State-Changing Requests . . . . . . 8 78 2.2. Repr-Digest and Content-Location in Responses . . . . . . 9 79 3. The Content-Digest Field . . . . . . . . . . . . . . . . . . 9 80 4. Integrity preference fields . . . . . . . . . . . . . . . . . 10 81 5. Hash Algorithms for HTTP Digest Fields Registry . . . . . . . 11 82 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 83 6.1. HTTP Messages Are Not Protected In Full . . . . . . . . . 13 84 6.2. End-to-End Integrity . . . . . . . . . . . . . . . . . . 13 85 6.3. Usage in Signatures . . . . . . . . . . . . . . . . . . . 13 86 6.4. Usage in Trailer Fields . . . . . . . . . . . . . . . . . 14 87 6.5. Usage with Encryption . . . . . . . . . . . . . . . . . . 14 88 6.6. Algorithm Agility . . . . . . . . . . . . . . . . . . . . 14 89 6.7. Resource exhaustion . . . . . . . . . . . . . . . . . . . 15 90 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 91 7.1. HTTP Field Name Registration . . . . . . . . . . . . . . 15 92 7.2. Establish the Hash Algorithms for HTTP Digest Fields 93 Registry . . . . . . . . . . . . . . . . . . . . . . . . 16 94 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 95 8.1. Normative References . . . . . . . . . . . . . . . . . . 16 96 8.2. Informative References . . . . . . . . . . . . . . . . . 18 97 Appendix A. Resource Representation and Representation Data . . 19 98 Appendix B. Examples of Unsolicited Digest . . . . . . . . . . . 21 99 B.1. Server Returns Full Representation Data . . . . . . . . . 21 100 B.2. Server Returns No Representation Data . . . . . . . . . . 22 101 B.3. Server Returns Partial Representation Data . . . . . . . 22 102 B.4. Client and Server Provide Full Representation Data . . . 23 103 B.5. Client Provides Full Representation Data, Server Provides 104 No Representation Data . . . . . . . . . . . . . . . . . 24 105 B.6. Client and Server Provide Full Representation Data . . . 25 106 B.7. POST Response does not Reference the Request URI . . . . 25 107 B.8. POST Response Describes the Request Status . . . . . . . 26 108 B.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . . 27 109 B.10. Error responses . . . . . . . . . . . . . . . . . . . . . 28 110 B.11. Use with Trailer Fields and Transfer Coding . . . . . . . 28 111 Appendix C. Examples of Want-Repr-Digest Solicited Digest . . . 29 112 C.1. Server Selects Client's Least Preferred Algorithm . . . . 29 113 C.2. Server Selects Algorithm Unsupported by Client . . . . . 30 114 C.3. Server Does Not Support Client Algorithm and Returns an 115 Error . . . . . . . . . . . . . . . . . . . . . . . . . . 30 116 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 31 117 Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 31 118 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 119 Since draft-ietf-httpbis-digest-headers-06 . . . . . . . . . . 32 120 Since draft-ietf-httpbis-digest-headers-05 . . . . . . . . . . 33 121 Since draft-ietf-httpbis-digest-headers-04 . . . . . . . . . . 33 122 Since draft-ietf-httpbis-digest-headers-03 . . . . . . . . . . 33 123 Since draft-ietf-httpbis-digest-headers-02 . . . . . . . . . . 33 124 Since draft-ietf-httpbis-digest-headers-01 . . . . . . . . . . 34 125 Since draft-ietf-httpbis-digest-headers-00 . . . . . . . . . . 34 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 128 1. Introduction 130 HTTP does not define the means to protect the data integrity of 131 representations or content. When HTTP messages are transferred 132 between endpoints, lower layer features or properties such as TCP 133 checksums or TLS records [RFC2818] can provide some integrity 134 protection. However, transport-oriented integrity provides a limited 135 utility because it is opaque to the application layer and only covers 136 the extent of a single connection. HTTP messages often travel over a 137 chain of separate connections, in between connections there is a 138 possibility for unintended or malicious data corruption. An HTTP 139 integrity mechanism can provide the means for endpoints, or 140 applications using HTTP, to detect data corruption and make a choice 141 about how to act on it. An example use case is to aid fault 142 detection and diagnosis across system boundaries. 144 This document defines two digest integrity mechanisms for HTTP. 145 First, representation data integrity, which acts on representation 146 data (Section 3.2 of [SEMANTICS]). This supports advanced use cases 147 such as validating the integrity of a resource that was reconstructed 148 from parts retrieved using multiple requests or connections. Second, 149 content integrity, which acts on conveyed content (Section 6.4 of 150 [SEMANTICS]). 152 This document obsoletes RFC 3230 and therefore the Digest and Want- 153 Digest HTTP fields; see Section 1.3. 155 1.1. Document Structure 157 This document is structured as follows: 159 * Section 2 defines the Repr-Digest request and response header and 160 trailer field, 162 * Section 3 defines the Content-Digest request and response header 163 and trailer field, 165 * Section 4 defines the Want-Repr-Digest and Want-Content-Digest 166 request and response header and trailer field, 168 * Section 5 describes algorithms and their relation to the fields 169 defined in this document, 171 * Section 2.1 details computing representation digests, 173 * Appendix B and Appendix C provide examples of using Repr-Digest 174 and Want-Repr-Digest. 176 1.2. Concept Overview 178 The HTTP fields defined in this document can be used for HTTP 179 integrity. Senders choose a hashing algorithm and calculate a digest 180 from an input related to the HTTP message, the algorithm identifier 181 and digest are transmitted in an HTTP field. Receivers can validate 182 the digest for integrity purposes. Hashing algorithms are registered 183 in the "Hash Algorithms for HTTP Digest Fields" (see Section 5). 185 Selecting the data on which digests are calculated depends on the use 186 case of HTTP messages. This document provides different headers for 187 HTTP representation data and HTTP content. 189 This document defines the Repr-Digest request and response header and 190 trailer field (Section 2) that contains a digest value computed by 191 applying a hashing algorithm to "selected representation data" 192 (Section 3.2 of [SEMANTICS]). Basing Repr-Digest on the selected 193 representation makes it straightforward to apply it to use-cases 194 where the transferred data requires some sort of manipulation to be 195 considered a representation or conveys a partial representation of a 196 resource, such as Range Requests (see Section 14.2 of [SEMANTICS]). 198 There are use-cases where a simple digest of the HTTP content bytes 199 is required. The Content-Digest request and response header and 200 trailer field is defined to support digests of content (Section 3.2 201 of [SEMANTICS]); see Section 3. 203 Repr-Digest and Content-Digest support hashing algorithm agility. 204 The Want-Repr-Digest and Want-Content-Digest fields allows endpoints 205 to express interest in Repr-Digest and Content-Digest respectively, 206 and preference of algorithms in either. 208 Repr-Digest and Content-Digest are collectively termed Integrity 209 fields. Want-Repr-Digest and Want-Content-Digestare collectively 210 termed Integrity preference fields. 212 Integrity fields are tied to the Content-Encoding and Content-Type 213 header fields. Therefore, a given resource may have multiple 214 different digest values when transferred with HTTP. 216 Integrity fields do not provide integrity for HTTP messages or 217 fields. However, they can be combined with other mechanisms that 218 protect metadata, such as digital signatures, in order to protect the 219 phases of an HTTP exchange in whole or in part. 221 This specification does not define means for authentication, 222 authorization or privacy. 224 1.3. Obsoleting RFC 3230 226 [RFC3230] defined the Digest and Want-Digest HTTP fields for HTTP 227 integrity. It also coined the term "instance" and "instance 228 manipulation" in order to explain concepts that are now more 229 universally defined, and implemented, as HTTP semantics such as 230 "selected representation data" (Section 3.2 of [SEMANTICS]). 232 Experience has shown that implementations of [RFC3230] have 233 interpreted the meaning of "instance" inconsistently, leading to 234 interoperability issues. The most common mistake being the 235 calculation of the digest using (what we now call) message content, 236 rather than using (what we now call) representation data as was 237 originally intended. Interestingly, time has also shown that a 238 digest of message content can be beneficial for some use cases. So 239 it is difficult to detect if non-conformance to [RFC3230] is 240 intentional or unintentional. 242 In order to address potential inconsistencies and ambiguity across 243 implementations of Digest and Want-Digest, this document obsoletes 244 [RFC3230]. The Integrity fields (Section 2 and Section 3) and 245 Integrity preference fields (Section 4) defined in this document are 246 better aligned with current HTTP semantics and have names that more 247 clearly articulate the intended usages. 249 1.4. Notational Conventions 251 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 252 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 253 "OPTIONAL" in this document are to be interpreted as described in 254 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 255 capitals, as shown here. 257 This document uses the Augmented BNF defined in [RFC5234] and updated 258 by [RFC7405]. 260 This document uses the Boolean, Byte Sequence, Dictionary, Integer 261 and List types from [STRUCTURED-FIELDS] along with the sf-dictionary 262 and sf-list ABNF rules. 264 The definitions "representation", "selected representation", 265 "representation data", "representation metadata", "user agent" and 266 "content" in this document are to be interpreted as described in 267 [SEMANTICS]. 269 Hashing algorithm names respect the casing used in their definition 270 document (e.g. SHA-1, CRC32c) whereas hashing algorithm keys are 271 quoted (e.g. "sha", "crc32c"). 273 The term "checksum" describes the output of the application of an 274 algorithm to a sequence of bytes, whereas "digest" is only used in 275 relation to the value contained in the fields. 277 Integrity fields: collective term for Repr-Digest and Content-Digest 278 Integrity preference fields: collective term for Want-Repr-Digest and 279 Want-Content-Digest 281 2. The Repr-Digest Field 283 The Repr-Digest HTTP field can be used in requests and responses to 284 communicate digests that are calculated using a hashing algorithm 285 applied to the entire "selected representation data" (see Section 8.1 286 of [SEMANTICS]). 288 Representations take into account the effect of the HTTP semantics on 289 messages. For example, the content can be affected by Range Requests 290 or methods such as HEAD, while the way the content is transferred "on 291 the wire" is dependent on other transformations (e.g. transfer 292 codings for HTTP/1.1 - see Section 6.1 of [HTTP11]). To help 293 illustrate HTTP representation concepts, several examples are 294 provided in Appendix A. 296 When a message has no "representation data" it is still possible to 297 assert that no "representation data" was sent by computing the digest 298 on an empty string (see Section 6.3). 300 Repr-Digest is a Structured Fields Dictionary (see Section 3.2 of 301 [STRUCTURED-FIELDS]) where: 303 * keys convey the hashing algorithm (see Section 5) used to compute 304 the digest; 306 * values MUST be of type Byte Sequence, which contain the output of 307 the digest calculation. 309 Repr-Digest = sf-dictionary 311 For example: 313 NOTE: '\' line wrapping per RFC 8792 315 Repr-Digest: \ 316 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 317 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 319 The Dictionary type can be used, for example, to attach multiple 320 digests calculated using different hashing algorithms in order to 321 support a population of endpoints with different or evolving 322 capabilities. Such an approach could support transitions away from 323 weaker algorithms (see Section 6.6). 325 NOTE: '\' line wrapping per RFC 8792 327 Repr-Digest: \ 328 sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=:,\ 329 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 330 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 332 A recipient MAY ignore any or all digests. This allows the recipient 333 to choose which hashing algorithm(s) to use for validation instead of 334 verifying every digest. 336 A sender MAY send a digest without knowing whether the recipient 337 supports a given hashing algorithm, or even knowing that the 338 recipient will ignore it. 340 Repr-Digest can be sent in a trailer section. In this case, Repr- 341 Digest MAY be merged into the header section; see Section 6.5.1 of 342 [SEMANTICS]. 344 2.1. Using Repr-Digest in State-Changing Requests 346 When the representation enclosed in a state-changing request does not 347 describe the target resource, the representation digest MUST be 348 computed on the representation data. This is the only possible 349 choice because representation digest requires complete representation 350 metadata (see Section 2). 352 In responses, 354 * if the representation describes the status of the request, Repr- 355 Digest MUST be computed on the enclosed representation (see 356 Appendix B.8 ); 358 * if there is a referenced resource Repr-Digest MUST be computed on 359 the selected representation of the referenced resource even if 360 that is different from the target resource. That might or might 361 not result in computing Repr-Digest on the enclosed 362 representation. 364 The latter case is done according to the HTTP semantics of the given 365 method, for example using the Content-Location header field (see 366 Section 8.7 of [SEMANTICS]). In contrast, the Location header field 367 does not affect Repr-Digest because it is not representation 368 metadata. 370 For example, in PATCH requests, the representation digest will be 371 computed on the patch document because the representation metadata 372 refers to the patch document and not to the target resource (see 373 Section 2 of [PATCH]). In responses, instead, the representation 374 digest will be computed on the selected representation of the patched 375 resource. 377 2.2. Repr-Digest and Content-Location in Responses 379 When a state-changing method returns the Content-Location header 380 field, the enclosed representation refers to the resource identified 381 by its value and Repr-Digest is computed accordingly. An example is 382 given in Appendix B.7. 384 3. The Content-Digest Field 386 The Content-Digest HTTP field can be used in requests and responses 387 to communicate digests that are calculated using a hashing algorithm 388 applied to the actual message content (see Section 6.4 of 389 [SEMANTICS]). It is a Structured Fields Dictionary (see Section 3.2 390 of [STRUCTURED-FIELDS]) where: 392 * keys convey the hashing algorithm (see Section 5) used to compute 393 the digest; 395 * values MUST be Byte Sequences (Section 3.3.5 of 396 [STRUCTURED-FIELDS]) containing the output of the digest 397 calculation. 399 Content-Digest = sf-dictionary 401 For example: 403 NOTE: '\' line wrapping per RFC 8792 405 Content-Digest: \ 406 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 407 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 409 The Dictionary type can be used, for example, to attach multiple 410 digests calculated using different hashing algorithms in order to 411 support a population of endpoints with different or evolving 412 capabilities. Such an approach could support transitions away from 413 weaker algorithms (see Section 6.6). 415 NOTE: '\' line wrapping per RFC 8792 417 Repr-Digest: \ 418 sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=:,\ 419 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 420 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 422 A recipient MAY ignore any or all digests. This allows the recipient 423 to choose which hashing algorithm(s) to use for validation instead of 424 verifying every digest. 426 A sender MAY send a digest without knowing whether the recipient 427 supports a given hashing algorithm, or even knowing that the 428 recipient will ignore it. 430 Content-Digest can be sent in a trailer section. In this case, 431 Content-Digest MAY be merged into the header section; see 432 Section 6.5.1 of [SEMANTICS]. 434 4. Integrity preference fields 436 Senders can indicate their interest in Integrity fields and hashing 437 algorithm preferences using the Want-Repr-Digest or Want-Content- 438 Digest fields. These can be used in both requests and responses. 440 Want-Repr-Digest indicates the sender's desire to receive a 441 representation digest on messages associated with the request URI and 442 representation metadata, using the Repr-Digest field. 444 Want-Content-Digest indicates the sender's desire to receive a 445 content digest on messages associated with the request URI and 446 representation metadata, using the Content-Digest field. 448 Want-Repr-Digest and Want-Content-Digest are Structured Fields 449 Dictionary (see Section 3.2 of [STRUCTURED-FIELDS]) where: 451 * keys convey the hashing algorithm (see Section 5); 453 * values MUST be of type Integer (Section 3.3.1 of 454 [STRUCTURED-FIELDS]) in the range 0 to 10 inclusive. 1 is the 455 least preferred, 10 is the most preferred, and a value of 0 means 456 "not acceptable". Values convey an ascending, relative, weighted 457 preference. 459 Want-Repr-Digest = sf-dictionary 460 Want-Content-Digest = sf-dictionary 462 Examples: 464 Want-Repr-Digest: sha-256=1 465 Want-Repr-Digest: sha-512=3, sha-256=10, unixsum=0 466 Want-Content-Digest: sha-256=1 467 Want-Content-Digest: sha-512=3, sha-256=10, unixsum=0 469 5. Hash Algorithms for HTTP Digest Fields Registry 471 The "Hash Algorithms for HTTP Digest Fields", maintained by IANA at 472 https://www.iana.org/assignments/http-dig-alg/ 473 (https://www.iana.org/assignments/http-dig-alg/), registers 474 algorithms for use with the Integrity and Integrity preference fields 475 defined in this document. 477 This registry uses the Specification Required policy (Section 4.6 of 478 [RFC8126]). 480 Registrations MUST include the following fields: 482 * Algorithm Key: the Structured Fields key value used in Repr- 483 Digest, Content-Digest, Want-Repr-Digest or Want-Content-Digest 484 field Dictionary member keys 486 * Status: the status of the algorithm. Use "standard" for 487 standardized algorithms without known problems; "experimental" or 488 some other appropriate value 490 - e.g. according to the type and status of the primary document 491 in which the algorithm is defined; "insecure" when the 492 algorithm is insecure; "reserved" when the algorithm references 493 a reserved token value 495 * Description: a short description of the algorithm 497 * Reference(s): a set of pointers to the primary documents defining 498 the algorithm and key 500 Insecure hashing algorithms MAY be used to preserve integrity against 501 corruption, but MUST NOT be used in a potentially adversarial 502 setting; for example, when signing Integrity fields' values for 503 authenticity. 505 The entries in Table 1 are registered by this document. 507 +===========+==========+============================+==============+ 508 | Algorithm | Status | Description | Reference(s) | 509 | Key | | | | 510 +===========+==========+============================+==============+ 511 | sha-512 | standard | The SHA-512 algorithm. | [RFC6234], | 512 | | | | [RFC4648], | 513 | | | | this | 514 | | | | document. | 515 +-----------+----------+----------------------------+--------------+ 516 | sha-256 | standard | The SHA-256 algorithm. | [RFC6234], | 517 | | | | [RFC4648], | 518 | | | | this | 519 | | | | document. | 520 +-----------+----------+----------------------------+--------------+ 521 | md5 | insecure | The MD5 algorithm. It is | [RFC1321], | 522 | | | vulnerable to collision | [RFC4648], | 523 | | | attacks; see [NO-MD5] and | this | 524 | | | [CMU-836068] | document. | 525 +-----------+----------+----------------------------+--------------+ 526 | sha | insecure | The SHA-1 algorithm. It | [RFC3174], | 527 | | | is vulnerable to collision | [RFC4648], | 528 | | | attacks; see [NO-SHA] and | [RFC6234] | 529 | | | [IACR-2020-014] | this | 530 | | | | document. | 531 +-----------+----------+----------------------------+--------------+ 532 | unixsum | insecure | The algorithm used by the | [RFC4648], | 533 | | | UNIX "sum" command. | [RFC6234], | 534 | | | | [UNIX], this | 535 | | | | document. | 536 +-----------+----------+----------------------------+--------------+ 537 | unixcksum | insecure | The algorithm used by the | [RFC4648], | 538 | | | UNIX "cksum" command. | [RFC6234], | 539 | | | | [UNIX], this | 540 | | | | document. | 541 +-----------+----------+----------------------------+--------------+ 542 | adler | insecure | The ADLER32 algorithm. | [RFC1950], | 543 | | | | this | 544 | | | | document. | 545 +-----------+----------+----------------------------+--------------+ 546 | crc32c | insecure | The CRC32c algorithm. | [RFC4960] | 547 | | | | appendix B, | 548 | | | | this | 549 | | | | document. | 550 +-----------+----------+----------------------------+--------------+ 552 Table 1: Initial Hash Algorithms 554 6. Security Considerations 556 6.1. HTTP Messages Are Not Protected In Full 558 This document specifies a data integrity mechanism that protects HTTP 559 "representation data" or content, but not HTTP header and trailer 560 fields, from certain kinds of corruption. 562 Integrity fields are not intended to be a general protection against 563 malicious tampering with HTTP messages. This can be achieved by 564 combining it with other approaches such as transport-layer security 565 or digital signatures. 567 6.2. End-to-End Integrity 569 Integrity fields can help detect "representation data" or content 570 modification due to implementation errors, undesired "transforming 571 proxies" (see Section 7.7 of [SEMANTICS]) or other actions as the 572 data passes across multiple hops or system boundaries. Even a simple 573 mechanism for end-to-end "representation data" integrity is valuable 574 because a user agent can validate that resource retrieval succeeded 575 before handing off to a HTML parser, video player etc. for parsing. 577 Note that using these mechanisms alone does not provide end-to-end 578 integrity of HTTP messages over multiple hops, since metadata could 579 be manipulated at any stage. Methods to protect metadata are 580 discussed in Section 6.3. 582 6.3. Usage in Signatures 584 Digital signatures are widely used together with checksums to provide 585 the certain identification of the origin of a message [NIST800-32]. 586 Such signatures can protect one or more HTTP fields and there are 587 additional considerations when Integrity fields are included in this 588 set. 590 Digests explicitly depend on the "representation metadata" (e.g. the 591 values of Content-Type, Content-Encoding etc). A signature that 592 protects Integrity fields but not other "representation metadata" can 593 expose the communication to tampering. For example, an actor could 594 manipulate the Content-Type field-value and cause a digest validation 595 failure at the recipient, preventing the application from accessing 596 the representation. Such an attack consumes the resources of both 597 endpoints. See also Section 2.2. 599 Signatures are likely to be deemed an adversarial setting when 600 applying Integrity fields; see Section 5. Using signatures to 601 protect the checksum of an empty representation allows receiving 602 endpoints to detect if an eventual payload has been stripped or 603 added. 605 Any mangling of Integrity fields, including digests' de-duplication 606 or combining different field values (see Section 5.2 of [SEMANTICS]) 607 might affect signature validation. 609 6.4. Usage in Trailer Fields 611 Before sending Integrity fields in a trailer section, the sender 612 should consider that intermediaries are explicitly allowed to drop 613 any trailer (see Section 6.5.2 of [SEMANTICS]). 615 When Integrity fields are used in a trailer section, the field-values 616 are received after the content. Eager processing of content before 617 the trailer section prevents digest validation, possibly leading to 618 processing of invalid data. 620 Not every hashing algorithm is suitable for use in the trailer 621 section, some may require to pre-process the whole payload before 622 sending a message (e.g. see [I-D.thomson-http-mice]). 624 6.5. Usage with Encryption 626 The checksum of an encrypted payload can change between different 627 messages depending on the encryption algorithm used; in those cases 628 its value could not be used to provide a proof of integrity "at rest" 629 unless the whole (e.g. encoded) content is persisted. 631 6.6. Algorithm Agility 633 The security properties of hashing algorithms are not fixed. 634 Algorithm Agility (see [RFC7696]) is achieved by providing 635 implementations with flexibility to choose hashing algorithms from 636 the IANA Hash Algorithms for HTTP Digest Fields registry; see 637 Section 7.2. 639 The "standard" algorithms listed in this document are suitable for 640 many purposes, including adversarial situations where hash functions 641 might need to provide resistance to collision, first-preimage and 642 second-preimage attacks. Algorithms listed as "insecure" either 643 provide none of these properties, or are known to be weak (see 644 [NO-MD5] and [NO-SHA]). 646 For adversarial situations, which of the "standard" algorithms are 647 acceptable will depend on the level of protection the circumstances 648 demand. As there is no negotiation, endpoints that depend on a 649 digest for security will be vulnerable to attacks on the weakest 650 algorithm they are willing to accept. 652 Transition from weak algorithms is supported by negotiation of 653 hashing algorithm using Want-Repr-Digest or Want-Content-Digest (see 654 Section 4) or by sending multiple digests from which the receiver 655 chooses. Endpoints are advised that sending multiple values consumes 656 resources, which may be wasted if the receiver ignores them (see 657 Section 2). 659 While algorithm agility allows the migration to stronger algorithms 660 it does not prevent the use of weaker algorithms. Integrity fields 661 do not provide any mitigiations for downgrade or substitution attacks 662 (see Section 1 of [RFC6211]) of the hashing algorithm. To protect 663 against such attacks, endpoints could restrict their set of supported 664 algorithms to stronger ones and protect the fields value by using TLS 665 and/or digital signatures. 667 6.7. Resource exhaustion 669 Integrity fields validation consumes computational resources. In 670 order to avoid resource exhaustion, implementations can restrict 671 validation of the algorithm types, number of validations, or the size 672 of content. 674 7. IANA Considerations 676 7.1. HTTP Field Name Registration 678 IANA is asked to update the "Hypertext Transfer Protocol (HTTP) Field 679 Name Registry" registry ([SEMANTICS]) according to the table below: 681 +=====================+===========+============================+ 682 | Field Name | Status | Reference | 683 +=====================+===========+============================+ 684 | Repr-Digest | permanent | Section 2 of this document | 685 +---------------------+-----------+----------------------------+ 686 | Content-Digest | permanent | Section 3 of this document | 687 +---------------------+-----------+----------------------------+ 688 | Want-Repr-Digest | permanent | Section 4 of this document | 689 +---------------------+-----------+----------------------------+ 690 | Want-Content-Digest | permanent | Section 4 of this document | 691 +---------------------+-----------+----------------------------+ 692 | Digest | obsoleted | [RFC3230], Section 1.3 of | 693 | | | this document | 694 +---------------------+-----------+----------------------------+ 695 | Want-Digest | obsoleted | [RFC3230], Section 1.3 of | 696 | | | this document | 697 +---------------------+-----------+----------------------------+ 699 Table 2 701 7.2. Establish the Hash Algorithms for HTTP Digest Fields Registry 703 This memo sets this specification to be the establishing document for 704 the Hash Algorithms for HTTP Digest Fields 705 (https://www.iana.org/assignments/http-structured-dig-alg/) registry 706 defined in Section 5. 708 IANA is asked to initialize the registry with the entries in Table 1. 710 8. References 712 8.1. Normative References 714 [CMU-836068] 715 Carnagie Mellon University, Software Engineering 716 Institute, "MD5 Vulnerable to collision attacks", 31 717 December 2008, . 719 [IACR-2020-014] 720 Leurent, G. and T. Peyrin, "SHA-1 is a Shambles", 5 721 January 2020, . 723 [NIST800-32] 724 National Institute of Standards and Technology, U.S. 725 Department of Commerce, "Introduction to Public Key 726 Technology and the Federal PKI Infrastructure", February 727 2001, . 730 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 731 DOI 10.17487/RFC1321, April 1992, 732 . 734 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 735 Specification version 3.3", RFC 1950, 736 DOI 10.17487/RFC1950, May 1996, 737 . 739 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 740 Requirement Levels", BCP 14, RFC 2119, 741 DOI 10.17487/RFC2119, March 1997, 742 . 744 [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 745 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, 746 . 748 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 749 RFC 3230, DOI 10.17487/RFC3230, January 2002, 750 . 752 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 753 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 754 . 756 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 757 RFC 4960, DOI 10.17487/RFC4960, September 2007, 758 . 760 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 761 Specifications: ABNF", STD 68, RFC 5234, 762 DOI 10.17487/RFC5234, January 2008, 763 . 765 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 766 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 767 DOI 10.17487/RFC6234, May 2011, 768 . 770 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 771 RFC 7405, DOI 10.17487/RFC7405, December 2014, 772 . 774 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 775 Writing an IANA Considerations Section in RFCs", BCP 26, 776 RFC 8126, DOI 10.17487/RFC8126, June 2017, 777 . 779 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 780 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 781 May 2017, . 783 [SEMANTICS] 784 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 785 Semantics", Work in Progress, Internet-Draft, draft-ietf- 786 httpbis-semantics-19, 12 September 2021, 787 . 790 [STRUCTURED-FIELDS] 791 Nottingham, M. and P-H. Kamp, "Structured Field Values for 792 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 793 . 795 [UNIX] The Open Group, "The Single UNIX Specification, Version 2 796 - 6 Vol Set for UNIX 98", February 1997. 798 8.2. Informative References 800 [HTTP11] Fielding, R. T., Nottingham, M., and J. Reschke, 801 "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf- 802 httpbis-messaging-19, 12 September 2021, 803 . 806 [I-D.thomson-http-mice] 807 Thomson, M. and J. Yasskin, "Merkle Integrity Content 808 Encoding", Work in Progress, Internet-Draft, draft- 809 thomson-http-mice-03, 13 August 2018, 810 . 813 [NO-MD5] Turner, S. and L. Chen, "Updated Security Considerations 814 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 815 RFC 6151, DOI 10.17487/RFC6151, March 2011, 816 . 818 [NO-SHA] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security 819 Considerations for the SHA-0 and SHA-1 Message-Digest 820 Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011, 821 . 823 [PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 824 RFC 5789, DOI 10.17487/RFC5789, March 2010, 825 . 827 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 828 DOI 10.17487/RFC2818, May 2000, 829 . 831 [RFC6211] Schaad, J., "Cryptographic Message Syntax (CMS) Algorithm 832 Identifier Protection Attribute", RFC 6211, 833 DOI 10.17487/RFC6211, April 2011, 834 . 836 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 837 DOI 10.17487/RFC7396, October 2014, 838 . 840 [RFC7696] Housley, R., "Guidelines for Cryptographic Algorithm 841 Agility and Selecting Mandatory-to-Implement Algorithms", 842 BCP 201, RFC 7696, DOI 10.17487/RFC7696, November 2015, 843 . 845 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 846 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 847 . 849 Appendix A. Resource Representation and Representation Data 851 The following examples show how representation metadata, payload 852 transformations and method impacts on the message and content. When 853 the content contains non-printable characters (e.g. when it is 854 compressed) it is shown as a Base64-encoded string. 856 PUT /entries/1234 HTTP/1.1 857 Host: foo.example 858 Content-Type: application/json 860 {"hello": "world"} 862 Figure 1: Request containing a JSON object without any content coding 864 PUT /entries/1234 HTTP/1.1 865 Host: foo.example 866 Content-Type: application/json 867 Content-Encoding: gzip 869 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 871 Figure 2: Request containing a gzip-encoded JSON object 873 Now the same content conveys a malformed JSON object, because the 874 request does not indicate a content coding. 876 PUT /entries/1234 HTTP/1.1 877 Host: foo.example 878 Content-Type: application/json 880 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 882 Figure 3: Request containing malformed JSON 884 A Range-Request alters the content, conveying a partial 885 representation. 887 GET /entries/1234 HTTP/1.1 888 Host: foo.example 889 Range: bytes=1-7 891 Figure 4: Request for partial content 893 HTTP/1.1 206 Partial Content 894 Content-Encoding: gzip 895 Content-Type: application/json 896 Content-Range: bytes 1-7/18 898 iwgAla3RXA== 900 Figure 5: Partial response from a gzip-encoded representation 902 The method can also alter the content. For example, the response to 903 a HEAD request does not carry content. 905 HEAD /entries/1234 HTTP/1.1 906 Host: foo.example 907 Accept: application/json 908 Accept-Encoding: gzip 910 Figure 6: HEAD request 912 HTTP/1.1 200 OK 913 Content-Type: application/json 914 Content-Encoding: gzip 916 Figure 7: Response to HEAD request (empty content) 918 Finally, the semantics of an HTTP response might decouple the 919 effective request URI from the enclosed representation. In the 920 example response below, the Content-Location header field indicates 921 that the enclosed representation refers to the resource available at 922 /authors/123, even though the request is directed to /authors/. 924 POST /authors/ HTTP/1.1 925 Host: foo.example 926 Accept: application/json 927 Content-Type: application/json 929 {"author": "Camilleri"} 931 Figure 8: POST request 933 HTTP/1.1 201 Created 934 Content-Type: application/json 935 Content-Location: /authors/123 936 Location: /authors/123 938 {"id": "123", "author": "Camilleri"} 940 Figure 9: Response with Content-Location header 942 Appendix B. Examples of Unsolicited Digest 944 The following examples demonstrate interactions where a server 945 responds with a Repr-Digest or Content-Digest fields even though the 946 client did not solicit one using Want-Repr-Digest or Want-Content- 947 Digest. 949 Some examples include JSON objects in the content. For presentation 950 purposes, objects that fit completely within the line-length limits 951 are presented on a single line using compact notation with no leading 952 space. Objects that would exceed line-length limits are presented 953 across multiple lines (one line per key-value pair) with 2 spaced of 954 leading indentation. 956 Checksum mechanisms defined in this document are media-type agnostic 957 and do not provide canonicalization algorithms for specific formats. 958 Examples are calculated inclusive of any space. While examples can 959 include both fields, Repr-Digest and Content-Digest can be returned 960 independently. 962 B.1. Server Returns Full Representation Data 964 In this example, the message content conveys complete representation 965 data. This means that in the response, Repr-Digest and Content- 966 Digest are both computed over the JSON object {"hello": "world"}, and 967 thus have the same value. 969 GET /items/123 HTTP/1.1 970 Host: foo.example 971 Figure 10: GET request for an item 973 NOTE: '\' line wrapping per RFC 8792 975 HTTP/1.1 200 OK 976 Content-Type: application/json 977 Repr-Digest: \ 978 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 979 Content-Digest: \ 980 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 982 {"hello": "world"} 984 Figure 11: Response with identical Repr-Digest and Content-Digest 986 B.2. Server Returns No Representation Data 988 In this example, a HEAD request is used to retrieve the checksum of a 989 resource. 991 The response Repr-Digest field-value is calculated over the JSON 992 object {"hello": "world"}, which is not shown because there is no 993 payload data. Content-Digest is computed on empty content. 995 HEAD /items/123 HTTP/1.1 996 Host: foo.example 998 Figure 12: HEAD request for an item 1000 NOTE: '\' line wrapping per RFC 8792 1002 HTTP/1.1 200 OK 1003 Content-Type: application/json 1004 Repr-Digest: \ 1005 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1006 Content-Digest: \ 1007 sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=: 1009 Figure 13: Response with both Content-Digest and Digest; empty 1010 content 1012 B.3. Server Returns Partial Representation Data 1014 In this example, the client makes a range request and the server 1015 responds with partial content. 1017 GET /items/123 HTTP/1.1 1018 Host: foo.example 1019 Range: bytes=1-7 1021 Figure 14: Request for partial content 1023 NOTE: '\' line wrapping per RFC 8792 1025 HTTP/1.1 206 Partial Content 1026 Content-Type: application/json 1027 Content-Range: bytes 1-7/18 1028 Repr-Digest: \ 1029 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1030 Content-Digest: \ 1031 sha-256=:Wqdirjg/u3J688ejbUlApbjECpiUUtIwT8lY/z81Tno=: 1033 "hello" 1035 Figure 15: Partial response with both Content-Digest and Repr-Digest 1037 In the response message above, note that the Repr-Digest and Content- 1038 Digests are different. The Repr-Digest field-value is calculated 1039 across the entire JSON object {"hello": "world"}, and the field is 1041 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1043 However, since the message content is constrained to bytes 1-7, the 1044 Content-Digest field-value is calculated over the byte sequence 1045 "hello", thus resulting in 1047 NOTE: '\' line wrapping per RFC 8792 1049 Content-Digest: \ 1050 sha-256=:Wqdirjg/u3J688ejbUlApbjECpiUUtIwT8lY/z81Tno=: 1052 B.4. Client and Server Provide Full Representation Data 1054 The request contains a Repr-Digest field-value calculated on the 1055 enclosed representation. It also includes an Accept-Encoding: br 1056 header field that advertises the client supports Brotli encoding. 1058 The response includes a Content-Encoding: br that indicates the 1059 selected representation is Brotli-encoded. The Repr-Digest field- 1060 value is therefore different compared to the request. 1062 For presentation purposes, the response body is displayed as a 1063 Base64-encoded string because it contains non-printable characters. 1065 PUT /items/123 HTTP/1.1 1066 Host: foo.example 1067 Content-Type: application/json 1068 Accept-Encoding: br 1069 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1071 {"hello": "world"} 1073 Figure 16: PUT Request with Digest 1075 HTTP/1.1 200 OK 1076 Content-Type: application/json 1077 Content-Location: /items/123 1078 Content-Encoding: br 1079 Content-Length: 22 1080 Repr-Digest: sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=: 1082 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 1084 Figure 17: Response with Digest of encoded response 1086 B.5. Client Provides Full Representation Data, Server Provides No 1087 Representation Data 1089 The request Repr-Digest field-value is calculated on the enclosed 1090 payload. 1092 The response Repr-Digest field-value depends on the representation 1093 metadata header fields, including Content-Encoding: br even when the 1094 response does not contain content. 1096 PUT /items/123 HTTP/1.1 1097 Host: foo.example 1098 Content-Type: application/json 1099 Content-Length: 18 1100 Accept-Encoding: br 1101 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1103 {"hello": "world"} 1105 HTTP/1.1 204 No Content 1106 Content-Type: application/json 1107 Content-Encoding: br 1108 Repr-Digest: sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=: 1110 Figure 18: Empty response with Digest 1112 B.6. Client and Server Provide Full Representation Data 1114 The response contains two digest values using different algorithms. 1116 As the response body contains non-printable characters, it is 1117 displayed as a base64-encoded string. 1119 PUT /items/123 HTTP/1.1 1120 Host: foo.example 1121 Content-Type: application/json 1122 Accept-Encoding: br 1123 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1125 {"hello": "world"} 1127 Figure 19: PUT Request with Digest 1129 NOTE: '\' line wrapping per RFC 8792 1131 HTTP/1.1 200 OK 1132 Content-Type: application/json 1133 Content-Encoding: br 1134 Content-Location: /items/123 1135 Repr-Digest: \ 1136 sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=:,\ 1137 sha-512=:pxo7aYzcGI88pnDnoSmAnaOEVys0MABhgvHY9+VI+ElE60jBCwnMPyA/\ 1138 s3NF3ZO5oIWA7lf8ukk+5KJzm3p5og==: 1140 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 1142 Figure 20: Response with Digest of Encoded Content 1144 B.7. POST Response does not Reference the Request URI 1146 The request Repr-Digest field-value is computed on the enclosed 1147 representation (see Section 2.1). 1149 The representation enclosed in the response refers to the resource 1150 identified by Content-Location (see Section 6.4.2 of [SEMANTICS]). 1151 Repr-Digest is thus computed on the enclosed representation. 1153 POST /books HTTP/1.1 1154 Host: foo.example 1155 Content-Type: application/json 1156 Accept: application/json 1157 Accept-Encoding: identity 1158 Repr-Digest: sha-256=:bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=: 1160 {"title": "New Title"} 1162 Figure 21: POST Request with Digest 1164 HTTP/1.1 201 Created 1165 Content-Type: application/json 1166 Content-Location: /books/123 1167 Location: /books/123 1168 Repr-Digest: sha-256=:yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE=: 1170 { 1171 "id": "123", 1172 "title": "New Title" 1173 } 1175 Figure 22: Response with Digest of Resource 1177 Note that a 204 No Content response without content but with the same 1178 Repr-Digest field-value would have been legitimate too. In that 1179 case, Content-Digest would have been computed on an empty content. 1181 B.8. POST Response Describes the Request Status 1183 The request Repr-Digest field-value is computed on the enclosed 1184 representation (see Section 2.1). 1186 The representation enclosed in the response describes the status of 1187 the request, so Repr-Digest is computed on that enclosed 1188 representation. 1190 Response Repr-Digest has no explicit relation with the resource 1191 referenced by Location. 1193 POST /books HTTP/1.1 1194 Host: foo.example 1195 Content-Type: application/json 1196 Accept: application/json 1197 Accept-Encoding: identity 1198 Repr-Digest: sha-256=:bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=: 1200 {"title": "New Title"} 1201 Figure 23: POST Request with Digest 1203 HTTP/1.1 201 Created 1204 Content-Type: application/json 1205 Repr-Digest: sha-256=:2LBp5RKZGpsSNf8BPXlXrX4Td4Tf5R5bZ9z7kdi5VvY=: 1206 Location: /books/123 1208 { 1209 "status": "created", 1210 "id": "123", 1211 "ts": 1569327729, 1212 "instance": "/books/123" 1213 } 1215 Figure 24: Response with Digest of Representation 1217 B.9. Digest with PATCH 1219 This case is analogous to a POST request where the target resource 1220 reflects the effective request URI. 1222 The PATCH request uses the application/merge-patch+json media type 1223 defined in [RFC7396]. 1225 Repr-Digest is calculated on the enclosed payload, which corresponds 1226 to the patch document. 1228 The response Repr-Digest field-value is computed on the complete 1229 representation of the patched resource. 1231 PATCH /books/123 HTTP/1.1 1232 Host: foo.example 1233 Content-Type: application/merge-patch+json 1234 Accept: application/json 1235 Accept-Encoding: identity 1236 Repr-Digest: sha-256=:bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=: 1238 {"title": "New Title"} 1240 Figure 25: PATCH Request with Digest 1242 HTTP/1.1 200 OK 1243 Content-Type: application/json 1244 Repr-Digest: sha-256=:yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE=: 1246 { 1247 "id": "123", 1248 "title": "New Title" 1249 } 1251 Figure 26: Response with Digest of Representation 1253 Note that a 204 No Content response without content but with the same 1254 Repr-Digest field-value would have been legitimate too. 1256 B.10. Error responses 1258 In error responses, the "representation data" does not necessarily 1259 refer to the target resource. Instead, it refers to the 1260 representation of the error. 1262 In the following example, a client sends the same request from 1263 Figure 25 to patch the resource located at /books/123. However, the 1264 resource does not exist and the server generates a 404 response with 1265 a body that describes the error in accordance with [RFC7807]. 1267 The response Repr-Digest field-value is computed on this enclosed 1268 representation. 1270 HTTP/1.1 404 Not Found 1271 Content-Type: application/problem+json 1272 Repr-Digest: sha-256=:KPqhVXAT25LLitV1w0O167unHmVQusu+fpxm65zAsvk=: 1274 { 1275 "title": "Not Found", 1276 "detail": "Cannot PATCH a non-existent resource", 1277 "status": 404 1278 } 1280 Figure 27: Response with Digest of Error Representation 1282 B.11. Use with Trailer Fields and Transfer Coding 1284 An origin server sends Repr-Digest as trailer field, so it can 1285 calculate digest-value while streaming content and thus mitigate 1286 resource consumption. The Repr-Digest field-value is the same as in 1287 Appendix B.1 because Repr-Digest is designed to be independent from 1288 the use of one or more transfer codings (see Section 2). 1290 GET /items/123 HTTP/1.1 1291 Host: foo.example 1293 Figure 28: GET Request 1295 HTTP/1.1 200 OK 1296 Content-Type: application/json 1297 Transfer-Encoding: chunked 1298 Trailer: Digest 1300 8\r\n 1301 {"hello"\r\n 1302 8 1303 : "world\r\n 1304 2\r\n 1305 "}\r\n 1306 0\r\n 1307 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1309 Figure 29: Chunked Response with Digest 1311 Appendix C. Examples of Want-Repr-Digest Solicited Digest 1313 The following examples demonstrate interactions where a client 1314 solicits a Repr-Digest using Want-Repr-Digest. The behavior of 1315 Content-Digest and Want-Content-Digest is identical. 1317 Some examples include JSON objects in the content. For presentation 1318 purposes, objects that fit completely within the line-length limits 1319 are presented on a single line using compact notation with no leading 1320 space. Objects that would exceed line-length limits are presented 1321 across multiple lines (one line per key-value pair) with 2 spaced of 1322 leading indentation. 1324 Checksum mechanisms described in this document are media-type 1325 agnostic and do not provide canonicalization algorithms for specific 1326 formats. Examples are calculated inclusive of any space. 1328 C.1. Server Selects Client's Least Preferred Algorithm 1330 The client requests a digest, preferring "sha". The server is free 1331 to reply with "sha-256" anyway. 1333 GET /items/123 HTTP/1.1 1334 Host: foo.example 1335 Want-Repr-Digest: sha-256=3, sha=10 1337 Figure 30: GET Request with Want-Repr-Digest 1339 HTTP/1.1 200 OK 1340 Content-Type: application/json 1341 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1343 {"hello": "world"} 1345 Figure 31: Response with Different Algorithm 1347 C.2. Server Selects Algorithm Unsupported by Client 1349 The client requests a "sha" digest because that is the only algorithm 1350 it supports. The server is not obliged to produce a response 1351 containing a "sha" digest, it instead uses a different algorithm. 1353 GET /items/123 HTTP/1.1 1354 Host: foo.example 1355 Want-Repr-Digest: sha=10 1357 Figure 32: GET Request with Want-Repr-Digest 1359 NOTE: '\' line wrapping per RFC 8792 1361 HTTP/1.1 200 OK 1362 Content-Type: application/json 1363 Repr-Digest: \ 1364 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 1365 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 1367 {"hello": "world"} 1369 Figure 33: Response with Unsupported Algorithm 1371 C.3. Server Does Not Support Client Algorithm and Returns an Error 1373 Appendix C.2 is an example where a server ignores the client's 1374 preferred digest algorithm. Alternatively a server can also reject 1375 the request and return an error. 1377 In this example, the client requests a "sha" Repr-Digest, and the 1378 server returns an error with problem details [RFC7807] contained in 1379 the content. The problem details contain a list of the hashing 1380 algorithms that the server supports. This is purely an example, this 1381 specification does not define any format or requirements for such 1382 content. 1384 GET /items/123 HTTP/1.1 1385 Host: foo.example 1386 Want-Repr-Digest: sha=10 1387 Figure 34: GET Request with Want-Repr-Digest 1389 HTTP/1.1 400 Bad Request 1390 Content-Type: application/problem+json 1392 { 1393 "title": "Bad Request", 1394 "detail": "Supported hashing algorithms: sha-256, sha-512", 1395 "status": 400 1396 } 1398 Figure 35: Response advertising the supported algorithms 1400 Acknowledgements 1402 This document is based on ideas from [RFC3230], so thanks to J. 1403 Mogul and A. Van Hoff for their great work. The original idea of 1404 refreshing RFC3230 arose from an interesting discussion with M. 1405 Nottingham, J. Yasskin and M. Thomson when reviewing the MICE 1406 content coding. 1408 Thanks to Julian Reschke for his valuable contributions to this 1409 document, and to the following contributors that have helped improve 1410 this specification by reporting bugs, asking smart questions, 1411 drafting or reviewing text, and evaluating open issues: Mike Bishop, 1412 Brian Campbell, Matthew Kerwin, James Manger, Tommy Pauly, Sean 1413 Turner, Justin Richer, and Erik Wilde. 1415 Code Samples 1417 _RFC Editor: Please remove this section before publication._ 1419 How can I generate and validate the Repr-Digest values shown in the 1420 examples throughout this document? 1422 The following python3 code can be used to generate digests for JSON 1423 objects using SHA algorithms for a range of encodings. Note that 1424 these are formatted as base64. This function could be adapted to 1425 other algorithms and should take into account their specific 1426 formatting rules. 1428 import base64, json, hashlib, brotli, logging 1429 log = logging.getLogger() 1431 def encode_item(item, encoding=lambda x: x): 1432 indent = 2 if isinstance(item, dict) and len(item) > 1 else None 1433 json_bytes = json.dumps(item, indent=indent).encode() 1434 return encoding(json_bytes) 1436 def digest_bytes(bytes_, algorithm=hashlib.sha256): 1437 checksum_bytes = algorithm(bytes_).digest() 1438 log.warning("Log bytes: \n[%r]", bytes_) 1439 return base64.encodebytes(checksum_bytes).strip() 1441 def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): 1442 content_encoded = encode_item(item, encoding) 1443 return digest_bytes(content_encoded, algorithm) 1445 item = {"hello": "world"} 1447 print("Encoding | hashing algorithm | digest-value") 1448 print("Identity | sha256 |", digest(item)) 1449 # Encoding | hashing algorithm | digest-value 1450 # Identity | sha256 | X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1452 print("Encoding | hashing algorithm | digest-value") 1453 print("Brotli | sha256 |", digest(item, encoding=brotli.compress)) 1454 # Encoding | hashing algorithm | digest-value 1455 # Brotli | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1457 print("Encoding | hashing algorithm | digest-value") 1458 print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512)) 1459 print("Brotli | sha512 |", digest(item, algorithm=hashlib.sha512, 1460 encoding=brotli.compress)) 1461 # Encoding | hashing algorithm | digest-value 1462 # Identity | sha512 |b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm' 1463 # '+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==' 1464 # Brotli | sha512 | b'pxo7aYzcGI88pnDnoSmAnaOEVys0MABhgvHY9+VI+ElE6' 1465 # '0jBCwnMPyA/s3NF3ZO5oIWA7lf8ukk+5KJzm3p5og==' 1467 Changes 1469 _RFC Editor: Please remove this section before publication._ 1471 Since draft-ietf-httpbis-digest-headers-06 1473 * Remove id-sha-256 and id-sha-512 from the list of supported 1474 algorithms #855 1476 Since draft-ietf-httpbis-digest-headers-05 1478 * Reboot digest-algorithm values registry #1567 1480 * Add Content-Digest #1542 1482 * Remove SRI section #1478 1484 Since draft-ietf-httpbis-digest-headers-04 1486 * Improve SRI section #1354 1488 * About duplicate digest-algorithms #1221 1490 * Improve security considerations #852 1492 * md5 and sha deprecation references #1392 1494 * Obsolete 3230 #1395 1496 * Editorial #1362 1498 Since draft-ietf-httpbis-digest-headers-03 1500 * Reference semantics-12 1502 * Detail encryption quirks 1504 * Details on Algorithm agility #1250 1506 * Obsolete parameters #850 1508 Since draft-ietf-httpbis-digest-headers-02 1510 * Deprecate SHA-1 #1154 1512 * Avoid id-* with encrypted content 1514 * Digest is independent from MESSAGING and HTTP/1.1 is not normative 1515 #1215 1517 * Identity is not a valid field value for content-encoding #1223 1519 * Mention trailers #1157 1521 * Reference httpbis-semantics #1156 1523 * Add contentMD5 as an obsoleted digest-algorithm #1249 1524 * Use lowercase digest-algorithms names in the doc and in the 1525 digest-algorithm IANA table. 1527 Since draft-ietf-httpbis-digest-headers-01 1529 * Digest of error responses is computed on the error representation- 1530 data #1004 1532 * Effect of HTTP semantics on payload and message body moved to 1533 appendix #1122 1535 * Editorial refactoring, moving headers sections up. #1109-#1112, 1536 #1116, #1117, #1122-#1124 1538 Since draft-ietf-httpbis-digest-headers-00 1540 * Align title with document name 1542 * Add id-sha-* algorithm examples #880 1544 * Reference [RFC6234] and [RFC3174] instead of FIPS-1 1546 * Deprecate MD5 1548 * Obsolete ADLER-32 but don't forbid it #828 1550 * Update CRC32C value in IANA table #828 1552 * Use when acting on resources (POST, PATCH) #853 1554 * Added Relationship with SRI, draft Use Cases #868, #971 1556 * Warn about the implications of Content-Location 1558 Authors' Addresses 1560 Roberto Polli 1561 Team Digitale, Italian Government 1562 Italy 1563 Email: robipolli@gmail.com 1565 Lucas Pardue 1566 Cloudflare 1567 Email: lucaspardue.24.7@gmail.com