idnits 2.17.1 draft-ietf-httpbis-digest-headers-03.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. -- The abstract seems to indicate that this document obsoletes RFC3230, but the header doesn't have an 'Obsoletes:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (September 07, 2020) is 1327 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) -- Looks like a reference, but probably isn't: '1' on line 1352 -- Looks like a reference, but probably isn't: '2' on line 1354 -- Looks like a reference, but probably isn't: '3' on line 1356 -- Looks like a reference, but probably isn't: '4' on line 1358 -- Looks like a reference, but probably isn't: '5' on line 1360 -- Looks like a reference, but probably isn't: '6' on line 1362 -- Looks like a reference, but probably isn't: '7' on line 1364 -- Looks like a reference, but probably isn't: '8' on line 1366 -- Looks like a reference, but probably isn't: '9' on line 1368 -- Looks like a reference, but probably isn't: '10' on line 1370 -- Looks like a reference, but probably isn't: '11' on line 1372 -- Looks like a reference, but probably isn't: '12' on line 1374 -- Looks like a reference, but probably isn't: '13' on line 1376 -- Looks like a reference, but probably isn't: '14' on line 1523 -- 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 ** Obsolete normative reference: RFC 3230 (Obsoleted by RFC 9530) ** Obsolete normative reference: RFC 3309 (Obsoleted by RFC 4960) ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) ** Downref: Normative reference to an Informational RFC: RFC 5843 ** Downref: Normative reference to an Informational RFC: RFC 6234 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-11 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNIX' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-11 -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7807 (Obsoleted by RFC 9457) Summary: 9 errors (**), 0 flaws (~~), 4 warnings (==), 25 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 Intended status: Standards Track L. Pardue 5 Expires: March 11, 2021 Cloudflare 6 September 07, 2020 8 Digest Headers 9 draft-ietf-httpbis-digest-headers-03 11 Abstract 13 This document defines the HTTP Digest and Want-Digest fields, thus 14 allowing client and server to negotiate an integrity checksum of the 15 exchanged resource representation data. 17 This document obsoletes RFC 3230. It replaces the term "instance" 18 with "representation", which makes it consistent with the HTTP 19 Semantic and Context defined in draft-ietf-httpbis-semantics. 21 Note to Readers 23 _RFC EDITOR: please remove this section before publication_ 25 Discussion of this draft takes place on the HTTP working group 26 mailing list (ietf-http-wg@w3.org), which is archived at 27 https://lists.w3.org/Archives/Public/ietf-http-wg/ [1]. 29 The source code and issues list for this draft can be found at 30 https://github.com/httpwg/http-extensions [2]. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on March 11, 2021. 49 Copyright Notice 51 Copyright (c) 2020 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (https://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. A Brief History of HTTP Integrity Fields . . . . . . . . 4 68 1.2. This Proposal . . . . . . . . . . . . . . . . . . . . . . 4 69 1.3. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 5 71 2. Representation Digest . . . . . . . . . . . . . . . . . . . . 6 72 3. The Digest Field . . . . . . . . . . . . . . . . . . . . . . 6 73 4. The Want-Digest Field . . . . . . . . . . . . . . . . . . . . 7 74 5. Digest Algorithm Values . . . . . . . . . . . . . . . . . . . 8 75 6. Use of Digest when acting on resources . . . . . . . . . . . 10 76 6.1. Digest and PATCH . . . . . . . . . . . . . . . . . . . . 11 77 7. Deprecate Negotiation of Content-MD5 . . . . . . . . . . . . 11 78 8. Relationship to Subresource Integrity (SRI) . . . . . . . . . 11 79 8.1. Supporting Both SRI and Representation Digest . . . . . . 12 80 9. Examples of Unsolicited Digest . . . . . . . . . . . . . . . 13 81 9.1. Server Returns Full Representation Data . . . . . . . . . 13 82 9.2. Server Returns No Representation Data . . . . . . . . . . 13 83 9.3. Server Returns Partial Representation Data . . . . . . . 13 84 9.4. Client and Server Provide Full Representation Data . . . 14 85 9.5. Client Provides Full Representation Data, Server Provides 86 No Representation Data . . . . . . . . . . . . . . . . . 15 87 9.6. Client and Server Provide Full Representation Data, 88 Client Uses id-sha-256. . . . . . . . . . . . . . . . . . 15 89 9.7. POST Response does not Reference the Request URI . . . . 16 90 9.8. POST Response Describes the Request Status . . . . . . . 16 91 9.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . . 17 92 9.10. Error responses . . . . . . . . . . . . . . . . . . . . . 18 93 9.11. Use with trailers and transfer coding . . . . . . . . . . 19 94 10. Examples of Want-Digest Solicited Digest . . . . . . . . . . 19 95 10.1. Server Selects Client's Least Preferred Algorithm . . . 20 96 10.2. Server Selects Algorithm Unsupported by Client . . . . . 20 97 10.3. Server Does Not Support Client Algorithm and Returns an 98 Error . . . . . . . . . . . . . . . . . . . . . . . . . 20 99 11. Security Considerations . . . . . . . . . . . . . . . . . . . 21 100 11.1. Digest Does Not Protect the Full HTTP Message . . . . . 21 101 11.2. Broken Cryptographic Algorithms . . . . . . . . . . . . 21 102 11.3. Other Deprecated Algorithms . . . . . . . . . . . . . . 21 103 11.4. Digest for End-to-End Integrity . . . . . . . . . . . . 21 104 11.5. Digest and Content-Location in responses . . . . . . . . 22 105 11.6. Usage in signatures . . . . . . . . . . . . . . . . . . 22 106 11.7. Usage in trailers . . . . . . . . . . . . . . . . . . . 22 107 11.8. Usage with encryption . . . . . . . . . . . . . . . . . 23 108 11.9. Algorithm Agility . . . . . . . . . . . . . . . . . . . 23 109 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 110 12.1. Establish the HTTP Digest Algorithm Values . . . . . . . 23 111 12.2. The "status" Field in the HTTP Digest Algorithm Values . 23 112 12.3. Deprecate "MD5" Digest Algorithm . . . . . . . . . . . . 23 113 12.4. Update "UNIXsum" Digest Algorithm . . . . . . . . . . . 24 114 12.5. Update "UNIXcksum" Digest Algorithm . . . . . . . . . . 24 115 12.6. Update "CRC32c" Digest Algorithm . . . . . . . . . . . . 24 116 12.7. Obsolete "SHA" Digest Algorithm . . . . . . . . . . . . 24 117 12.8. Obsolete "ADLER32" Digest Algorithm . . . . . . . . . . 25 118 12.9. Obsolete "contentMD5" token in Digest Algorithm . . . . 25 119 12.10. The "id-sha-256" Digest Algorithm . . . . . . . . . . . 25 120 12.11. The "id-sha-512" Digest Algorithm . . . . . . . . . . . 26 121 12.12. Changes compared to RFC5843 . . . . . . . . . . . . . . 26 122 12.13. Want-Digest Field Registration . . . . . . . . . . . . . 26 123 12.14. Digest Header Field Registration . . . . . . . . . . . . 26 124 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 125 13.1. Normative References . . . . . . . . . . . . . . . . . . 27 126 13.2. Informative References . . . . . . . . . . . . . . . . . 28 127 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 29 128 Appendix A. Resource Representation and Representation-Data . . 30 129 Appendix B. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 32 130 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 33 131 Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 33 132 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 133 E.1. Since draft-ietf-httpbis-digest-headers-00 . . . . . . . 34 134 E.2. Since draft-ietf-httpbis-digest-headers-01 . . . . . . . 35 135 E.3. Since draft-ietf-httpbis-digest-headers-02 . . . . . . . 35 136 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 138 1. Introduction 140 The core specification of HTTP does not define a means to protect the 141 integrity of resources. When HTTP messages are transferred between 142 endpoints, the protocol might choose to make use of features of the 143 lower layer in order to provide some integrity protection; for 144 instance TCP checksums or TLS records [RFC2818]. 146 However, there are cases where relying on this alone is insufficient. 147 An HTTP-level integrity mechanism that operates independent of 148 transfer can be used to detect programming errors and/or corruption 149 of data at rest, be used across multiple hops in order to provide 150 end-to-end integrity guarantees, aid fault diagnosis across hops and 151 system boundaries, and can be used to validate integrity when 152 reconstructing a resource fetched using different HTTP connections. 154 This document defines a mechanism that acts on HTTP representation- 155 data. It can be combined with other mechanisms that protect 156 representation-metadata, such as digital signatures, in order to 157 protect the desired parts of an HTTP exchange in whole or in part. 159 1.1. A Brief History of HTTP Integrity Fields 161 The Content-MD5 header field was originally introduced to provide 162 integrity, but HTTP/1.1 ([RFC7231], Appendix B) obsoleted it: 164 The Content-MD5 header field has been removed because it was 165 inconsistently implemented with respect to partial responses. 167 [RFC3230] provided a more flexible solution introducing the concept 168 of "instance", and the fields "Digest" and "Want-Digest". 170 1.2. This Proposal 172 The concept of "selected representation" defined in Section 7 of 173 [SEMANTICS] makes [RFC3230] definitions inconsistent with current 174 HTTP semantics. This document updates the "Digest" and "Want-Digest" 175 field definitions to align with [SEMANTICS] concepts. 177 Basing "Digest" on the selected representation makes it 178 straightforward to apply it to use-cases where the transferred data 179 does require some sort of manipulation to be considered a 180 representation, or conveys a partial representation of a resource eg. 181 Range Requests (see Section 9.3 of [SEMANTICS]). 183 Changes are semantically compatible with existing implementations and 184 better cover both the request and response cases. 186 The value of "Digest" is calculated on selected representation, which 187 is tied to the value contained in any "Content-Encoding" or "Content- 188 Type" header fields. Therefore, a given resource may have multiple 189 different digest values. 191 To allow both parties to exchange a Digest of a representation with 192 no content codings (see Section 7.1.2 of [SEMANTICS]) two more 193 digest-algorithms are added ("id-sha-256" and "id-sha-512"). 195 1.3. Goals 197 The goals of this proposal are: 199 1. Digest coverage for either the resource's "representation data" 200 or "selected representation data" communicated via HTTP. 202 2. Support for multiple digest-algorithms. 204 3. Negotiation of the use of digests. 206 The goals do not include: 208 HTTP message integrity: The digest mechanism described here does not 209 cover the full HTTP message nor its semantic, as representation 210 metadata are not included in the checksum. 212 HTTP field integrity: The digest mechanisms described here cover 213 only representation and selected representation data, and do not 214 protect the integrity of associated representation metadata or 215 other message fields. 217 Authentication: The digest mechanisms described here are not meant 218 to support authentication of the source of a digest or of a 219 message or anything else. These mechanisms, therefore, are not a 220 sufficient defense against many kinds of malicious attacks. 222 Privacy: Digest mechanisms do not provide message privacy. 224 Authorization: The digest mechanisms described here are not meant to 225 support authorization or other kinds of access controls. 227 1.4. Notational Conventions 229 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 230 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 231 "OPTIONAL" in this document are to be interpreted as described in BCP 232 14 ([RFC2119] and [RFC8174]) when, and only when, they appear in all 233 capitals, as shown here. 235 This document uses the Augmented BNF defined in [RFC5234] and updated 236 by [RFC7405] along with the "#rule" extension defined in Section 5 of 237 [SEMANTICS]. 239 The definitions "representation", "selected representation", 240 "representation data", "representation metadata", and "payload body" 241 in this document are to be interpreted as described in [SEMANTICS]. 243 Algorithm names respect the casing used in their definition document 244 (eg. SHA-1, CRC32c) whereas digest-algorithm tokens are quoted (eg. 245 "sha", "crc32c"). 247 2. Representation Digest 249 The representation digest is an integrity mechanism for HTTP 250 resources which uses a checksum that is calculated independently of 251 the payload body (see Section 7.3.3 of [SEMANTICS]). It uses the 252 representation data (see Section 7.1 of [SEMANTICS]), that can be 253 fully or partially contained in the payload body, or not contained at 254 all: 256 representation-data := Content-Encoding( Content-Type( bits ) ) 258 This takes into account the effect of the HTTP semantics on the 259 messages; for example the payload body can be affected by Range 260 Requests or methods such as HEAD, while the way the payload body is 261 transferred "on the wire" is dependent on other transformations (eg. 262 transfer codings for HTTP/1.1 see 6.1 of [HTTP11]): Appendix A 263 contains several examples to help illustrate those effects. 265 A representation digest consists of the value of a checksum computed 266 on the entire selected "representation data" (see Section 7 of 267 [SEMANTICS]) of a resource identified according to Section 7.3.2 of 268 [SEMANTICS] together with an indication of the algorithm used (and 269 any parameters) 271 representation-data-digest = digest-algorithm "=" 272 274 The checksum is computed using one of the digest-algorithms listed in 275 Section 5 and then encoded in the associated format. 277 The example below shows the "sha-256" digest-algorithm which uses 278 base64 encoding. 280 sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 282 3. The Digest Field 284 The "Digest" field contains a list of one or more representation 285 digest values as defined in Section 2. It can be used in both 286 request and response. 288 Digest = "Digest" ":" OWS 1#representation-data-digest 290 The relationship between "Content-Location" (see Section 7.2.5 of 291 [SEMANTICS]) and "Digest" is demonstrated in Section 9.7. A 292 comprehensive set of examples showing the impacts of representation 293 metadata, payload transformations and HTTP methods on Digest is 294 provided in Section 9 and Section 10. 296 A "Digest" field MAY contain multiple representation-data-digest 297 values. This could be useful for responses expected to reside in 298 caches shared by users with different browsers, for example. 300 A recipient MAY ignore any or all of the representation-data-digests 301 in a Digest field. This allows the recipient to choose which digest- 302 algorithm(s) to use for validation instead of verifying every 303 received representation-data-digest. 305 A sender MAY send a representation-data-digest using a digest- 306 algorithm without knowing whether the recipient supports the digest- 307 algorithm, or even knowing that the recipient will ignore it. 309 "Digest" can be sent in a trailer section. When using incremental 310 digest-algorithms this allows the sender and the receiver to 311 dynamically compute the digest value while streaming the content. 313 Two examples of its use are 315 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 316 AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 318 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 319 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 321 4. The Want-Digest Field 323 The "Want-Digest" field indicates the sender's desire to receive a 324 representation digest on messages associated with the request URI and 325 representation metadata. 327 Want-Digest = "Want-Digest" ":" OWS 1#want-digest-value 328 want-digest-value = digest-algorithm [ ";" "q" "=" qvalue] 329 qvalue = ( "0" [ "." 0*1DIGIT ] ) / 330 ( "1" [ "." 0*1( "0" ) ] ) 332 If a digest-algorithm is not accompanied by a "qvalue", it is treated 333 as if its associated "qvalue" were 1.0. 335 The sender is willing to accept a digest-algorithm if and only if it 336 is listed in a "Want-Digest" field of a message, and its "qvalue" is 337 non-zero. 339 If multiple acceptable digest-algorithm values are given, the 340 sender's preferred digest-algorithm is the one (or ones) with the 341 highest "qvalue". 343 Two examples of its use are 345 Want-Digest: sha-256 346 Want-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0 348 5. Digest Algorithm Values 350 Digest-algorithm values are used to indicate a specific digest 351 computation. For some digest-algorithms, one or more parameters can 352 be supplied. 354 digest-algorithm = token 356 The BNF for "parameter" is defined in Section 5.4.1.4 of [SEMANTICS]. 357 All digest-algorithm values are case-insensitive but the lower case 358 is preferred. 360 The Internet Assigned Numbers Authority (IANA) acts as a registry for 361 digest-algorithm values. The registry contains the tokens listed 362 below. 364 Some digest-algorithms, although registered, rely on vulnerable 365 algorithms: the "md5" digest-algorithm MUST NOT be used due to 366 collision attacks [CMU-836068] and the "sha" digest-algorithm MUST 367 NOT be used due to collision attacks [IACR-2020-014]. 369 sha-256 371 * Description: The SHA-256 algorithm [RFC6234]. The output of 372 this algorithm is encoded using the base64 encoding [RFC4648]. 374 * Reference: [RFC6234], [RFC4648], this document. 376 * Status: standard 378 sha-512 380 * Description: The SHA-512 algorithm [RFC6234]. The output of 381 this algorithm is encoded using the base64 encoding [RFC4648]. 383 * Reference: [RFC6234], [RFC4648], this document. 385 * Status: standard 387 md5 389 * Description: The MD5 algorithm, as specified in [RFC1321]. The 390 output of this algorithm is encoded using the base64 encoding 391 [RFC4648]. This digest-algorithm MUST NOT be used as it's now 392 vulnerable to collision attacks [CMU-836068]. 394 * Reference: [RFC1321], [RFC4648], this document. 396 * Status: deprecated 398 sha 400 * Description: The SHA-1 algorithm [RFC3174]. The output of this 401 algorithm is encoded using the base64 encoding [RFC4648]. This 402 digest-algorithm MUST NOT be used as it's now vulnerable to 403 collision attacks [IACR-2020-014]. 405 * Reference: [RFC3174], [RFC6234], [RFC4648], this document. 407 * Status: deprecated 409 unixsum 411 * Description: The algorithm computed by the UNIX "sum" command, 412 as defined by the Single UNIX Specification, Version 2 [UNIX]. 413 The output of this algorithm is an ASCII decimal-digit string 414 representing the 16-bit checksum, which is the first word of 415 the output of the UNIX "sum" command. 417 * Reference: [UNIX], this document. 419 * Status: standard 421 unixcksum 423 * Description: The algorithm computed by the UNIX "cksum" 424 command, as defined by the Single UNIX Specification, Version 2 425 [UNIX]. The output of this algorithm is an ASCII digit string 426 representing the 32-bit CRC, which is the first word of the 427 output of the UNIX "cksum" command. 429 * Reference: [UNIX], this document. 431 * Status: standard 433 To allow sender and recipient to provide a checksum which is 434 independent from "Content-Encoding", the following additional digest- 435 algorithms are defined: 437 id-sha-512 439 * Description: The sha-512 digest of the representation-data of 440 the resource when no content coding is applied 442 * Reference: [RFC6234], [RFC4648], this document. 444 * Status: standard 446 id-sha-256 448 * Description: The sha-256 digest of the representation-data of 449 the resource when no content coding is applied 451 * Reference: [RFC6234], [RFC4648], this document. 453 * Status: standard 455 If other digest-algorithm values are defined, the associated encoding 456 MUST either be represented as a quoted string, or MUST NOT include 457 ";" or "," in the character sets used for the encoding. 459 6. Use of Digest when acting on resources 461 POST and PATCH requests can appear to convey partial representations 462 but are semantically acting on resources. The enclosed 463 representation, including its metadata refers to that action. 465 In these requests the representation digest MUST be computed on the 466 representation-data of that action. This is the only possible choice 467 because representation digest requires complete representation 468 metadata (see Section 2). 470 In responses, 472 o if the representation describes the status of the request, 473 "Digest" MUST be computed on the enclosed representation (see 474 Section 9.8 ); 476 o if there is a referenced resource "Digest" MUST be computed on the 477 selected representation of the referenced resource even if that is 478 different from the target resource. That might or might not 479 result in computing "Digest" on the enclosed representation. 481 The latter case might be done according to the HTTP semantics of the 482 given method, for example using the "Content-Location" header field. 483 In contrast, the "Location" header field does not affect "Digest" 484 because it is not representation metadata. 486 6.1. Digest and PATCH 488 In PATCH requests the representation digest MUST be computed on the 489 patch document because the representation metadata refers to the 490 patch document and not to the target resource (see Section 2 of 491 [RFC5789]). 493 In PATCH responses the representation digest MUST be computed on the 494 selected representation of the patched resource. 496 "Digest" usage with PATCH is thus very similar to the POST one, but 497 with the resource's own semantic partly implied by the method and by 498 the patch document. 500 7. Deprecate Negotiation of Content-MD5 502 This RFC deprecates the negotiation of Content-MD5 as it has been 503 obsoleted by [RFC7231]. The "contentMD5" token defined in Section 5 504 of [RFC3230] MUST NOT be used as a digest-algorithm. 506 8. Relationship to Subresource Integrity (SRI) 508 Subresource Integrity [SRI] is an integrity mechanism that shares 509 some similarities to the present document's mechanism. However, 510 there are differences in motivating factors, threat model and 511 specification of integrity digest generation, signalling and 512 validation. 514 SRI allows a first-party authority to declare an integrity assertion 515 on a resource served by a first or third party authority. This is 516 done via the "integrity" attribute that can be added to "script" or 517 "link" HTML elements. Therefore, the integrity assertion is always 518 made out-of-band to the resource fetch. In contrast, the "Digest" 519 field is supplied in-band alongside the selected representation, 520 meaning that an authority can only declare an integrity assertion for 521 itself. Methods to improve the security properties of representation 522 digests are presented in Section 11. This contrast is interesting 523 because on one hand self-assertion is less likely to be affected by 524 coordination problems such as the first-party holding stale 525 information about the third party, but on the other hand the self- 526 assertion is only as trustworthy as the authority that provided it. 528 The SRI "integrity" attribute contains a cryptographic hash algorithm 529 and digest value which is similar to "representation-data-digest" 530 (see Section 2). The major differences are in serialization format. 532 The SRI digest value is calculated over the identity encoding of the 533 resource, not the selected representation (as specified for 534 "representation-data-digest" in this document). Section 3.4.5 of 535 [SRI] describes the benefit of the identity approach - the SRI 536 "integrity" attribute can contain multiple algorithm-value pairs 537 where each applies to a different identity encoded payload. This 538 allows for protection of distinct resources sharing a URL. However, 539 this is a contrast to the design of representation digests, where 540 multiple "Digest" field-values all protect the same representation. 542 SRI does not specify handling of partial representation data (e.g. 543 Range requests). In contrast, this document specifies handling in 544 terms that are fully compatible with core HTTP concepts (an example 545 is provided in Section 9.3). 547 SRI specifies strong requirements on the selection of algorithm for 548 generation and validation of digests. In contrast, the requirements 549 in this document are weaker. 551 SRI defines no method for a client to declare an integrity assertion 552 on resources it transfers to a server. In contrast, the "Digest" 553 field can appear on requests. 555 8.1. Supporting Both SRI and Representation Digest 557 The SRI and Representation Digest mechanisms are different and 558 complementary but one is not capable of replacing the other because 559 they have different threat, security and implementation properties. 561 A user agent that supports both mechanisms is expected to apply the 562 rules specified for each but since the two mechanisms are 563 independent, the ordering is not important. However, a user agent 564 supporting both could benefit from performing representation digest 565 validation first because it does not always require a conversion into 566 identity encoding. 568 There is a chance that a user agent supporting both mechanisms may 569 find one validates successfully while the other fails. This document 570 specifies no requirements or guidance for user agents that experience 571 such cases. 573 9. Examples of Unsolicited Digest 575 The following examples demonstrate interactions where a server 576 responds with a "Digest" field even though the client did not solicit 577 one using "Want-Digest". 579 9.1. Server Returns Full Representation Data 581 Request: 583 GET /items/123 585 Response: 587 HTTP/1.1 200 OK 588 Content-Type: application/json 589 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 591 {"hello": "world"} 593 9.2. Server Returns No Representation Data 595 Requests without a payload body can still send a "Digest" field 596 applying the digest-algorithm to an empty representation. 598 As there is no content coding applied, the "sha-256" and the "id-sha- 599 256" digest-values in the response are the same. 601 Request: 603 HEAD /items/123 HTTP/1.1 604 Digest: sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= 606 Response: 608 HTTP/1.1 200 OK 609 Content-Type: application/json 610 Digest: id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 612 9.3. Server Returns Partial Representation Data 614 Request: 616 GET /items/123 617 Range: bytes=1-7 619 Response: 621 HTTP/1.1 206 Partial Content 622 Content-Type: application/json 623 Content-Range: bytes 1-7/18 624 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 626 "hello" 628 9.4. Client and Server Provide Full Representation Data 630 The request contains a "Digest" field calculated on the enclosed 631 representation. 633 It also includes an "Accept-Encoding: br" header field that 634 advertises the client supports brotli encoding. 636 The response includes a "Content-Encoding: br" that indicates the 637 selected representation is brotli encoded. The "Digest" field-value 638 is therefore different compared to the request. 640 The response body is displayed as a base64-encoded string because it 641 contains non-printable characters. 643 Request: 645 PUT /items/123 646 Content-Type: application/json 647 Accept-Encoding: br 648 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 650 {"hello": "world"} 652 Response: 654 Content-Type: application/json 655 Content-Encoding: br 656 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 658 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 660 9.5. Client Provides Full Representation Data, Server Provides No 661 Representation Data 663 Request "Digest" value is calculated on the enclosed payload. 664 Response "Digest" value depends on the representation metadata header 665 fields, including "Content-Encoding: br" even when the response does 666 not contain a payload body. 668 Request: 670 PUT /items/123 671 Content-Type: application/json 672 Content-Length: 18 673 Accept-Encoding: br 674 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 676 {"hello": "world"} 678 Response: 680 HTTP/1.1 204 No Content 681 Content-Type: application/json 682 Content-Encoding: br 683 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 685 9.6. Client and Server Provide Full Representation Data, Client Uses 686 id-sha-256. 688 The response contains two digest values: 690 o one with no content coding applied, which in this case 691 accidentally matches the unencoded digest-value sent in the 692 request; 694 o one taking into account the "Content-Encoding". 696 As the response body contains non-printable characters, it is 697 displayed as a base64-encoded string. 699 Request: 701 PUT /items/123 HTTP/1.1 702 Content-Type: application/json 703 Accept-Encoding: br 704 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 706 {"hello": "world"} 707 Response: 709 HTTP/1.1 200 OK 710 Content-Type: application/json 711 Content-Encoding: br 712 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 713 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 715 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 717 9.7. POST Response does not Reference the Request URI 719 Request "Digest" value is computed on the enclosed representation 720 (see Section 6). 722 The representation enclosed in the response refers to the resource 723 identified by "Content-Location" (see [SEMANTICS], Section 7.3.2). 725 "Digest" is thus computed on the enclosed representation. 727 Request: 729 POST /books HTTP/1.1 730 Content-Type: application/json 731 Accept: application/json 732 Accept-Encoding: identity 733 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 735 {"title": "New Title"} 737 Response 739 HTTP/1.1 201 Created 740 Content-Type: application/json 741 Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc= 742 Content-Location: /books/123 744 {"id": "123", "title": "New Title"} 746 Note that a "204 No Content" response without a payload body but with 747 the same "Digest" field-value would have been legitimate too. 749 9.8. POST Response Describes the Request Status 751 Request "Digest" value is computed on the enclosed representation 752 (see Section 6). 754 The representation enclosed in the response describes the status of 755 the request, so "Digest" is computed on that enclosed representation. 757 Response "Digest" has no explicit relation with the resource 758 referenced by "Location". 760 Request: 762 POST /books HTTP/1.1 763 Content-Type: application/json 764 Accept: application/json 765 Accept-Encoding: identity 766 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 767 Location: /books/123 769 {"title": "New Title"} 771 Response 773 HTTP/1.1 201 Created 774 Content-Type: application/json 775 Digest: id-sha-256=0o/WKwSfnmIoSlop2LV/ISaBDth05IeW27zzNMUh5l8= 776 Location: /books/123 778 { 779 "status": "created", 780 "id": "123", 781 "ts": 1569327729, 782 "instance": "/books/123" 783 } 785 9.9. Digest with PATCH 787 This case is analogous to a POST request where the target resource 788 reflects the effective request URI. 790 The PATCH request uses the "application/merge-patch+json" media type 791 defined in [RFC7396]. 793 "Digest" is calculated on the enclosed payload, which corresponds to 794 the patch document. 796 The response "Digest" is computed on the complete representation of 797 the patched resource. 799 Request: 801 PATCH /books/123 HTTP/1.1 802 Content-Type: application/merge-patch+json 803 Accept: application/json 804 Accept-Encoding: identity 805 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 807 {"title": "New Title"} 809 Response: 811 HTTP/1.1 200 OK 812 Content-Type: application/json 813 Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc= 815 {"id": "123", "title": "New Title"} 817 Note that a "204 No Content" response without a payload body but with 818 the same "Digest" field-value would have been legitimate too. 820 9.10. Error responses 822 In error responses, the representation-data does not necessarily 823 refer to the target resource. Instead it refers to the 824 representation of the error. 826 In the following example a client attempts to patch the resource 827 located at /books/123. However, the resource does not exist and the 828 server generates a 404 response with a body that describes the error 829 in accordance with [RFC7807]. 831 The digest of the response is computed on this enclosed 832 representation. 834 Request: 836 PATCH /books/123 HTTP/1.1 837 Content-Type: application/merge-patch+json 838 Accept: application/json 839 Accept-Encoding: identity 840 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 842 {"title": "New Title"} 844 Response: 846 HTTP/1.1 404 Not Found 847 Content-Type: application/problem+json 848 Digest: sha-256=UJSojgEzqUe4UoHzmNl5d2xkmrW3BOdmvsvWu1uFeu0= 850 { 851 "title": "Not Found", 852 "detail": "Cannot PATCH a non-existent resource", 853 "status": 404 854 } 856 9.11. Use with trailers and transfer coding 858 An origin server sends "Digest" in the HTTP trailer, so it can 859 calculate digest-value while streaming content and thus mitigate 860 resource consumption. The field value is the same as in Section 9.1 861 because "Digest" is designed to be independent from the use of one or 862 more transfer codings (see Section 2). 864 Request: 866 GET /items/123 868 Response: 870 HTTP/1.1 200 OK 871 Content-Type: application/json 872 Transfer-Encoding: chunked 873 Trailer: Digest 875 8\r\n 876 {"hello"\r\n 877 8 878 : "world\r\n 879 2\r\n 880 "}\r\n 881 0\r\n 882 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 884 10. Examples of Want-Digest Solicited Digest 886 The following examples demonstrate interactions where a client 887 solicits a "Digest" using "Want-Digest". 889 10.1. Server Selects Client's Least Preferred Algorithm 891 The client requests a digest, preferring "sha". The server is free 892 to reply with "sha-256" anyway. 894 Request: 896 GET /items/123 HTTP/1.1 897 Want-Digest: sha-256;q=0.3, sha;q=1 899 Response: 901 HTTP/1.1 200 OK 902 Content-Type: application/json 903 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 905 {"hello": "world"} 907 10.2. Server Selects Algorithm Unsupported by Client 909 The client requests a sha digest only. The server is currently free 910 to reply with a Digest containing an unsupported algorithm. 912 Request: 914 GET /items/123 915 Want-Digest: sha;q=1 917 Response: 919 HTTP/1.1 200 OK 920 Content-Type: application/json 921 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 922 +AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 924 {"hello": "world"} 926 10.3. Server Does Not Support Client Algorithm and Returns an Error 928 The client requests a sha Digest, the server advises for sha-256 and 929 sha-512 931 Request: 933 GET /items/123 934 Want-Digest: sha;q=1 936 Response: 938 HTTP/1.1 400 Bad Request 939 Want-Digest: sha-256, sha-512 941 11. Security Considerations 943 11.1. Digest Does Not Protect the Full HTTP Message 945 This document specifies a data integrity mechanism that protects HTTP 946 "representation data", but not HTTP "representation metadata" fields, 947 from certain kinds of accidental corruption. 949 "Digest" is not intended as general protection against malicious 950 tampering with HTTP messages, this can be achieved by combining it 951 with other approaches such as transport-layer security or digital 952 signatures. 954 11.2. Broken Cryptographic Algorithms 956 Cryptographic algorithms are intended to provide a proof of integrity 957 suited towards cryptographic constructions such as signatures. 959 However, these rely on collision-resistance for their security proofs 960 [CMU-836068]. The "MD5" and "SHA-1" digest algorithms are vulnerable 961 to collisions attacks, so they MUST NOT be used with "Digest". 963 11.3. Other Deprecated Algorithms 965 The ADLER32 algorithm defined in [RFC1950] has been deprecated by 966 [RFC3309] because under certain conditions it provides weak detection 967 of errors and is now NOT RECOMMENDED for use with "Digest". 969 11.4. Digest for End-to-End Integrity 971 "Digest" alone does not provide end-to-end integrity of HTTP messages 972 over multiple hops, as it just covers the "representation data" and 973 not the "representation metadata". 975 Besides, it allows to protect "representation data" from buggy 976 manipulation, buggy compression, etc. 978 Moreover identity digest algorithms (eg. "id-sha-256" and "id-sha- 979 512") allow piecing together a resource from different sources (e.g. 980 different servers that perhaps apply different content codings) 981 enabling the user-agent to detect that the application-layer tasks 982 completed properly, before handing off to say the HTML parser, video 983 player etc. 985 Even a simple mechanism for end-to-end validation is thus valuable. 987 11.5. Digest and Content-Location in responses 989 When a state-changing method returns the "Content-Location" header 990 field, the enclosed representation refers to the resource identified 991 by its value and "Digest" is computed accordingly. 993 11.6. Usage in signatures 995 Digital signatures are widely used together with checksums to provide 996 the certain identification of the origin of a message [NIST800-32]. 997 Such signatures can protect one or more HTTP fields and there are 998 additional considerations when "Digest" is included in this set. 1000 Since the "Digest" field is a hash of a resource representation, it 1001 explicitly depends on the "representation metadata" (eg. the values 1002 of "Content-Type", "Content-Encoding" etc). A signature that 1003 protects "Digest" but not other "representation metadata" can expose 1004 the communication to tampering. For example, an actor could 1005 manipulate the "Content-Type" field-value and cause a digest 1006 validation failure at the recipient, preventing the application from 1007 accessing the representation. Such an attack consumes the resources 1008 of both endpoints. See also Section 11.5. 1010 "Digest" SHOULD always be used over a connection which provides 1011 integrity at the transport layer that protects HTTP fields. 1013 A "Digest" field using NOT RECOMMENDED digest-algorithms SHOULD NOT 1014 be used in signatures. 1016 Using signatures to protect the "Digest" of an empty representation 1017 allows receiving endpoints to detect if an eventual payload has been 1018 stripped or added. 1020 11.7. Usage in trailers 1022 When used in trailers, the receiver gets the digest value after the 1023 payload body and may thus be tempted to process the data before 1024 validating the digest value. Instead, data should only be processed 1025 after validating the Digest. 1027 If received in trailers, "Digest" MUST NOT be discarded; instead it 1028 MAY be merged in the header section (See Section 5.6.2 of 1029 [SEMANTICS]). 1031 Not every digest-algorithm is suitable for trailers, as they may 1032 require to pre-process the whole payload before sending a message 1033 (eg. see [I-D.thomson-http-mice]). 1035 11.8. Usage with encryption 1037 "Digest" may expose information details of encrypted payload when the 1038 checksum is computed on the unencrypted data. An example of that is 1039 the use of the "id-sha-256" digest algorithm in conjuction with the 1040 encrypted content-coding [RFC8188]. 1042 11.9. Algorithm Agility 1044 ... 1046 12. IANA Considerations 1048 12.1. Establish the HTTP Digest Algorithm Values 1050 This memo sets this spec to be the establishing document for the HTTP 1051 Digest Algorithm Values [3] 1053 12.2. The "status" Field in the HTTP Digest Algorithm Values 1055 This memo adds the field "Status" to the HTTP Digest Algorithm Values 1056 [4] registry. The allowed values for the "Status" fields are 1057 described below. 1059 Status Specify "standard", "experimental", "historic", "obsoleted", 1060 or "deprecated" according to the type and status of the primary 1061 document in which the algorithm is defined. 1063 12.3. Deprecate "MD5" Digest Algorithm 1065 This memo updates the "MD5" digest-algorithm in the HTTP Digest 1066 Algorithm Values [5] registry: 1068 o Digest Algorithm: md5 1070 o Description: As specified in Section 5. 1072 o Status: As specified in Section 5. 1074 12.4. Update "UNIXsum" Digest Algorithm 1076 This memo updates the "UNIXsum" digest algorithm in the HTTP Digest 1077 Algorithm Values [6] registry: 1079 o Digest Algorithm: As specified in Section 5. 1081 o Description: As specified in Section 5. 1083 o Status: As specified in Section 5. 1085 12.5. Update "UNIXcksum" Digest Algorithm 1087 This memo updates the "UNIXcksum" digest algorithm in the HTTP Digest 1088 Algorithm Values [7] registry: 1090 o Digest Algorithm: As specified in Section 5. 1092 o Description: As specified in Section 5. 1094 o Status: As specified in Section 5. 1096 12.6. Update "CRC32c" Digest Algorithm 1098 This memo updates the "CRC32c" digest-algorithm in the HTTP Digest 1099 Algorithm Values [8] registry: 1101 o Digest Algorithm: crc32c 1103 o Description: The CRC32c algorithm is a 32-bit cyclic redundancy 1104 check. It achieves a better hamming distance (for better error- 1105 detection performance) than many other 32-bit CRC functions. 1106 Other places it is used include iSCSI and SCTP. The 32-bit output 1107 is encoded in hexadecimal (using between 1 and 8 ASCII characters 1108 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 1109 crc32c=0a72a4df and crc32c=A72A4DF are both valid checksums for 1110 the 3-byte message "dog". 1112 o Reference: [RFC4960] appendix B, this document. 1114 o Status: standard. 1116 12.7. Obsolete "SHA" Digest Algorithm 1118 This memo updates the "SHA" digest-algorithm in the HTTP Digest 1119 Algorithm Values [9] registry: 1121 o Digest Algorithm: sha 1122 o Description: As specified in Section 5. 1124 o Status: As specified in Section 5. 1126 12.8. Obsolete "ADLER32" Digest Algorithm 1128 This memo updates the "ADLER32" digest-algorithm in the HTTP Digest 1129 Algorithm Values [10] registry: 1131 o Digest Algorithm: adler32 1133 o Description: The ADLER32 algorithm is a checksum specified in 1134 [RFC1950] "ZLIB Compressed Data Format". The 32-bit output is 1135 encoded in hexadecimal (using between 1 and 8 ASCII characters 1136 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 1137 adler32=03da0195 and adler32=3DA0195 are both valid checksums for 1138 the 4-byte message "Wiki". This algorithm is obsoleted and SHOULD 1139 NOT be used. 1141 o Status: obsoleted 1143 12.9. Obsolete "contentMD5" token in Digest Algorithm 1145 This memo adds the "contentMD5" token in the HTTP Digest Algorithm 1146 Values [11] registry: 1148 o Digest Algorithm: contentMD5 1150 o Description: Section 5 of [RFC3230] defined the "contentMD5" token 1151 to be used only in Want-Digest. This token is obsoleted and MUST 1152 NOT be used. 1154 o Reference: Section 12.9 of this document, Section 5 of [RFC3230]. 1156 o Status: obsoleted 1158 12.10. The "id-sha-256" Digest Algorithm 1160 This memo registers the "id-sha-256" digest algorithm in the HTTP 1161 Digest Algorithm Values [12] registry: 1163 o Digest Algorithm: id-sha-256 1165 o Description: As specified in Section 5. 1167 o Status: As specified in Section 5. 1169 12.11. The "id-sha-512" Digest Algorithm 1171 This memo registers the "id-sha-512" digest algorithm in the HTTP 1172 Digest Algorithm Values [13] registry: 1174 o Digest Algorithm: id-sha-512 1176 o Description: As specified in Section 5. 1178 o Status: As specified in Section 5. 1180 12.12. Changes compared to RFC5843 1182 The digest-algorithm values for "MD5", "SHA", "SHA-256", "SHA-512", 1183 "UNIXcksum", "UNIXsum", "ADLER32" and "CRC32c" have been updated to 1184 lowercase. 1186 The status of "MD5" has been updated to "deprecated", and its 1187 description states that this algorithm MUST NOT be used. 1189 The status of "SHA" has been updated to "deprecated", and its 1190 description states that this algorithm MUST NOT be used. 1192 The status for "CRC2c", "UNIXsum" and "UNIXcksum" has been updated to 1193 "standard". 1195 The "id-sha-256" and "id-sha-512" algorithms have been added to the 1196 registry. 1198 12.13. Want-Digest Field Registration 1200 This section registers the "Want-Digest" field in the "Hypertext 1201 Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. 1203 Field name: "Want-Digest" 1205 Status: permanent 1207 Specification document(s): Section 4 of this document 1209 12.14. Digest Header Field Registration 1211 This section registers the "Digest" field in the "Hypertext Transfer 1212 Protocol (HTTP) Field Name Registry" [SEMANTICS]. 1214 Field name: "Digest" 1216 Status: permanent 1217 Specification document(s): Section 3 of this document 1219 13. References 1221 13.1. Normative References 1223 [CMU-836068] 1224 Carnagie Mellon University, Software Engineering 1225 Institute, "MD5 Vulnerable to collision attacks", December 1226 2008, . 1228 [IACR-2020-014] 1229 Leurent, G. and T. Peyrin, "SHA-1 is a Shambles", January 1230 2020, . 1232 [NIST800-32] 1233 National Institute of Standards and Technology, U.S. 1234 Department of Commerce, "Introduction to Public Key 1235 Technology and the Federal PKI Infrastructure", February 1236 2001, . 1239 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 1240 DOI 10.17487/RFC1321, April 1992, 1241 . 1243 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 1244 Specification version 3.3", RFC 1950, 1245 DOI 10.17487/RFC1950, May 1996, 1246 . 1248 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1249 Requirement Levels", BCP 14, RFC 2119, 1250 DOI 10.17487/RFC2119, March 1997, 1251 . 1253 [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 1254 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, 1255 . 1257 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 1258 RFC 3230, DOI 10.17487/RFC3230, January 2002, 1259 . 1261 [RFC3309] Stone, J., Stewart, R., and D. Otis, "Stream Control 1262 Transmission Protocol (SCTP) Checksum Change", RFC 3309, 1263 DOI 10.17487/RFC3309, September 2002, 1264 . 1266 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1267 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1268 . 1270 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1271 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1272 . 1274 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1275 Specifications: ABNF", STD 68, RFC 5234, 1276 DOI 10.17487/RFC5234, January 2008, 1277 . 1279 [RFC5843] Bryan, A., "Additional Hash Algorithms for HTTP Instance 1280 Digests", RFC 5843, DOI 10.17487/RFC5843, April 2010, 1281 . 1283 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 1284 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 1285 DOI 10.17487/RFC6234, May 2011, 1286 . 1288 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 1289 RFC 7405, DOI 10.17487/RFC7405, December 2014, 1290 . 1292 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1293 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1294 May 2017, . 1296 [SEMANTICS] 1297 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 1298 Semantics", draft-ietf-httpbis-semantics-11 (work in 1299 progress), August 2020. 1301 [UNIX] The Open Group, "The Single UNIX Specification, Version 2 1302 - 6 Vol Set for UNIX 98", February 1997. 1304 13.2. Informative References 1306 [HTTP11] Fielding, R., Nottingham, M., and J. Reschke, "HTTP/1.1 1307 Messaging", draft-ietf-httpbis-messaging-11 (work in 1308 progress), August 2020. 1310 [I-D.ietf-httpbis-header-structure] 1311 Nottingham, M. and P. Kamp, "Structured Field Values for 1312 HTTP", draft-ietf-httpbis-header-structure-19 (work in 1313 progress), June 2020. 1315 [I-D.thomson-http-mice] 1316 Thomson, M. and J. Yasskin, "Merkle Integrity Content 1317 Encoding", draft-thomson-http-mice-03 (work in progress), 1318 August 2018. 1320 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 1321 DOI 10.17487/RFC2818, May 2000, 1322 . 1324 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1325 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1326 . 1328 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1329 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1330 DOI 10.17487/RFC7231, June 2014, 1331 . 1333 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 1334 DOI 10.17487/RFC7396, October 2014, 1335 . 1337 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 1338 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 1339 . 1341 [RFC8188] Thomson, M., "Encrypted Content-Encoding for HTTP", 1342 RFC 8188, DOI 10.17487/RFC8188, June 2017, 1343 . 1345 [SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger, 1346 "Subresource Integrity", W3C Recommendation REC-SRI- 1347 20160623, June 2016, 1348 . 1350 13.3. URIs 1352 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 1354 [2] https://github.com/httpwg/http-extensions 1356 [3] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1358 [4] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1360 [5] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1362 [6] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1364 [7] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1366 [8] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1368 [9] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1370 [10] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1372 [11] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1374 [12] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1376 [13] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1378 [14] https://github.com/httpwg/http-core/ 1379 issues/313#issuecomment-584389706 1381 Appendix A. Resource Representation and Representation-Data 1383 The following examples show how representation metadata, payload 1384 transformations and method impacts on the message and payload body. 1385 When the payload body contains non-printable characters (eg. when it 1386 is compressed) it is shown as base64-encoded string. 1388 A request with a json object without any content coding. 1390 Request: 1392 PUT /entries/1234 HTTP/1.1 1393 Content-Type: application/json 1395 {"hello": "world"} 1397 Here is a gzip-compressed json object using a content coding. 1399 Request: 1401 PUT /entries/1234 HTTP/1.1 1402 Content-Type: application/json 1403 Content-Encoding: gzip 1405 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 1407 Now the same payload body conveys a malformed json object. 1409 Request: 1411 PUT /entries/1234 HTTP/1.1 1412 Content-Type: application/json 1414 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 1416 A Range-Request alters the payload body, conveying a partial 1417 representation. 1419 Request: 1421 GET /entries/1234 HTTP/1.1 1422 Range: bytes=1-7 1424 Response: 1426 HTTP/1.1 206 Partial Content 1427 Content-Encoding: gzip 1428 Content-Type: application/json 1429 Content-Range: bytes 1-7/18 1431 iwgAla3RXA== 1433 Now the method too alters the payload body. 1435 Request: 1437 HEAD /entries/1234 HTTP/1.1 1438 Accept: application/json 1439 Accept-Encoding: gzip 1441 Response: 1443 HTTP/1.1 200 OK 1444 Content-Type: application/json 1445 Content-Encoding: gzip 1447 Finally the semantics of an HTTP response might decouple the 1448 effective request URI from the enclosed representation. In the 1449 example response below, the "Content-Location" header field indicates 1450 that the enclosed representation refers to the resource available at 1451 "/authors/123". 1453 Request: 1455 POST /authors/ HTTP/1.1 1456 Accept: application/json 1457 Content-Type: application/json 1459 {"author": "Camilleri"} 1461 Response: 1463 HTTP/1.1 201 Created 1464 Content-Type: application/json 1465 Content-Location: /authors/123 1466 Location: /authors/123 1468 {"id": "123", "author": "Camilleri"} 1470 Appendix B. FAQ 1472 1. Why remove all references to content-md5? 1474 Those were unnecessary to understanding and using this spec. 1476 2. Why remove references to instance manipulation? 1478 Those were unnecessary for correctly using and applying the spec. 1479 An example with Range Request is more than enough. This doc uses 1480 the term "partial representation" which should group all those 1481 cases. 1483 3. How to use "Digest" with "PATCH" method? 1485 See Section 6. 1487 4. Why remove references to delta-encoding? 1489 Unnecessary for a correct implementation of this spec. The 1490 revised spec can be nicely adapted to "delta encoding", but all 1491 the references here to delta encoding don't add anything to this 1492 RFC. Another job would be to refresh delta encoding. 1494 5. Why remove references to Digest Authentication? 1496 This RFC seems to me completely unrelated to Digest 1497 Authentication but for the word "Digest". 1499 6. What changes in "Want-Digest"? 1501 The contentMD5 token defined in Section 5 of [RFC3230] is 1502 deprecated by Section 7. 1504 To clarify that "Digest" and "Want-Digest" can be used in both 1505 requests and responses - [RFC3230] carefully uses "sender" and 1506 "receiver" in their definition - we added examples on using 1507 "Want-Digest" in responses to advertise the supported digest- 1508 algorithms and the inability to accept requests with unsupported 1509 digest-algorithms. 1511 7. Does this spec changes supported algorithms? 1513 This RFC updates [RFC5843] which is still delegated for all 1514 algorithms updates, and adds two more algorithms: "id-sha-256" 1515 and "id-sha-512" which allows to send a checksum of a resource 1516 representation with no content codings applied. To simplify a 1517 future transition to Structured Fields 1518 [I-D.ietf-httpbis-header-structure] we suggest to use lowercase 1519 for digest-algorithms. 1521 8. What about mid-stream trailers? 1523 While mid-stream trailers [14] are interesting, since this 1524 specification is a rewrite of [RFC3230] we do not think we should 1525 face that. As a first thought, nothing in this document 1526 precludes future work that would find a use for mid-stream 1527 trailers, for example an incremental digest-algorithm. A 1528 document defining such a digest-algorithm is best positioned to 1529 describe how it is used. 1531 Acknowledgements 1533 The vast majority of this document is inherited from [RFC3230], so 1534 thanks to J. Mogul and A. Van Hoff for their great work. The 1535 original idea of refreshing this document arose from an interesting 1536 discussion with M. Nottingham, J. Yasskin and M. Thomson when 1537 reviewing the MICE content coding. 1539 Code Samples 1541 _RFC Editor: Please remove this section before publication._ 1543 How can I generate and validate the "Digest" values shown in the 1544 examples throughout this document? 1546 The following python3 code can be used to generate digests for json 1547 objects using SHA algorithms for a range of encodings. Note that 1548 these are formatted as base64. This function could be adapted to 1549 other algorithms and should take into account their specific 1550 formatting rules. 1552 import base64, json, hashlib, brotli 1554 def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): 1555 json_bytes = json.dumps(item).encode() 1556 content_encoded = encoding(json_bytes) 1557 checksum_bytes = algorithm(content_encoded).digest() 1558 return base64.encodebytes(checksum_bytes).strip() 1560 item = {"hello": "world"} 1562 print("Encoding | digest-algorithm | digest-value") 1563 print("Identity | sha256 |", digest(item)) 1564 # Encoding | digest-algorithm | digest-value 1565 # Identity | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1567 print("Encoding | digest-algorithm | digest-value") 1568 print("Brotli | sha256 |", digest(item, encoding=brotli.compress)) 1569 # Encoding | digest-algorithm | digest-value 1570 # Brotli , sha256 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1572 print("Encoding | digest-algorithm | digest-value") 1573 print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512)) 1574 # Encoding | digest-algorithm | digest-value 1575 # Identity | sha512 | b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2s 1576 vX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==\n' 1578 Changes 1580 _RFC Editor: Please remove this section before publication._ 1582 E.1. Since draft-ietf-httpbis-digest-headers-00 1584 o Align title with document name 1586 o Add id-sha-* algorithm examples #880 1588 o Reference [RFC6234] and [RFC3174] instead of FIPS-1 1590 o Deprecate MD5 1592 o Obsolete ADLER-32 but don't forbid it #828 1594 o Update CRC32C value in IANA table #828 1596 o Use when acting on resources (POST, PATCH) #853 1597 o Added Relationship with SRI, draft Use Cases #868, #971 1599 o Warn about the implications of "Content-Location" 1601 E.2. Since draft-ietf-httpbis-digest-headers-01 1603 o Digest of error responses is computed on the error representation- 1604 data #1004 1606 o Effect of HTTP semantics on payload and message body moved to 1607 appendix #1122 1609 o Editorial refactoring, moving headers sections up. #1109-#1112, 1610 #1116, #1117, #1122-#1124 1612 E.3. Since draft-ietf-httpbis-digest-headers-02 1614 o Deprecate SHA-1 #1154 1616 o Avoid id-* with encrypted content 1618 o Digest is independent from MESSAGING and HTTP/1.1 is not normative 1619 #1215 1621 o Identity is not a valid field value for content-encoding #1223 1623 o Mention trailers #1157 1625 o Reference httpbis-semantics #1156 1627 o Add contentMD5 as an obsoleted digest-algorithm #1249 1629 o Use lowercase digest-algorithms names in the doc and in the 1630 digest-algorithm IANA table. 1632 Authors' Addresses 1634 Roberto Polli 1635 Team Digitale, Italian Government 1637 Email: robipolli@gmail.com 1639 Lucas Pardue 1640 Cloudflare 1642 Email: lucaspardue.24.7@gmail.com