idnits 2.17.00 (12 Aug 2021) /tmp/idnits5098/draft-ietf-httpbis-digest-headers-01.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 : ---------------------------------------------------------------------------- ** There are 9 instances of too long lines in the document, the longest one being 56 characters in excess of 72. ** 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 (November 03, 2019) is 930 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 1277 -- Looks like a reference, but probably isn't: '2' on line 1279 -- Looks like a reference, but probably isn't: '3' on line 1281 -- Looks like a reference, but probably isn't: '4' on line 1283 -- Looks like a reference, but probably isn't: '5' on line 1285 -- Looks like a reference, but probably isn't: '6' on line 1287 -- Looks like a reference, but probably isn't: '7' on line 1289 -- Looks like a reference, but probably isn't: '8' on line 1291 -- Looks like a reference, but probably isn't: '9' on line 1293 -- Looks like a reference, but probably isn't: '10' on line 1295 -- Looks like a reference, but probably isn't: '11' on line 1297 -- Possible downref: Non-RFC (?) normative reference: ref. 'CMU-836068' -- Possible downref: Non-RFC (?) normative reference: ref. 'IACR-2019-459' -- 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 3309 (Obsoleted by RFC 4960) ** Downref: Normative reference to an Informational RFC: RFC 5843 ** Downref: Normative reference to an Informational RFC: RFC 6234 -- Possible downref: Non-RFC (?) normative reference: ref. 'UNIX' Summary: 8 errors (**), 0 flaws (~~), 2 warnings (==), 18 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: May 6, 2020 Cloudflare 6 November 03, 2019 8 Digest Headers 9 draft-ietf-httpbis-digest-headers-01 11 Abstract 13 This document defines the Digest and Want-Digest header fields for 14 HTTP, thus allowing client and server to negotiate an integrity 15 checksum of the 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 RFC 7231. 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 May 6, 2020. 49 Copyright Notice 51 Copyright (c) 2019 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 Integrity Header Fields . . . . . . . 4 68 1.2. This Proposal . . . . . . . . . . . . . . . . . . . . . . 4 69 1.3. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 5 71 2. Resource Representation and Representation-Data . . . . . . . 6 72 3. Digest Algorithm Values . . . . . . . . . . . . . . . . . . . 7 73 3.1. Representation Digest . . . . . . . . . . . . . . . . . . 9 74 3.1.1. digest-algorithm Encoding Examples . . . . . . . . . 10 75 4. Header Field Specifications . . . . . . . . . . . . . . . . . 10 76 4.1. Want-Digest . . . . . . . . . . . . . . . . . . . . . . . 10 77 4.2. Digest . . . . . . . . . . . . . . . . . . . . . . . . . 10 78 5. Use of Digest when acting on resources . . . . . . . . . . . 11 79 5.1. Digest and PATCH . . . . . . . . . . . . . . . . . . . . 12 80 6. Deprecate Negotiation of Content-MD5 . . . . . . . . . . . . 12 81 7. Broken Cryptographic Algorithms . . . . . . . . . . . . . . . 12 82 8. Relationship to Subresource Integrity (SRI) . . . . . . . . . 13 83 8.1. Supporting Both SRI and Representation Digest . . . . . . 14 84 9. Examples of Unsolicited Digest . . . . . . . . . . . . . . . 14 85 9.1. Server Returns Full Representation Data . . . . . . . . . 14 86 9.2. Server Returns No Representation Data . . . . . . . . . . 15 87 9.3. Server Returns Partial Representation Data . . . . . . . 15 88 9.4. Client and Server Provide Full Representation Data . . . 15 89 9.5. Client Provides Full Representation Data, Server Provides 90 No Representation Data . . . . . . . . . . . . . . . . . 16 91 9.6. Client and Server Provide Full Representation Data, 92 Client Uses id-sha-256. . . . . . . . . . . . . . . . . . 17 93 9.7. POST Response does not Reference the Request URI . . . . 17 94 9.8. POST Response Describes the Request Status . . . . . . . 18 95 9.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . . 19 96 10. Examples of Want-Digest Solicited Digest . . . . . . . . . . 19 97 10.1. Server Selects Client's Least Preferred Algorithm . . . 20 98 10.2. Server Selects Algorithm Unsupported by Client . . . . . 20 99 10.3. Server Does Not Support Client Algorithm and Returns an 100 Error . . . . . . . . . . . . . . . . . . . . . . . . . 20 101 11. Security Considerations . . . . . . . . . . . . . . . . . . . 21 102 11.1. Digest Does Not Protect the Full HTTP Message . . . . . 21 103 11.2. Broken Cryptographic Algorithms . . . . . . . . . . . . 21 104 11.3. Other Deprecated Algorithms . . . . . . . . . . . . . . 21 105 11.4. Digest for End-to-End Integrity . . . . . . . . . . . . 21 106 11.5. Usage in Signatures . . . . . . . . . . . . . . . . . . 22 107 11.6. Message Truncation . . . . . . . . . . . . . . . . . . . 22 108 11.7. Algorithm Agility . . . . . . . . . . . . . . . . . . . 22 109 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 110 12.1. Establish the HTTP Digest Algorithm Values . . . . . . . 22 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 "CRC32C" Digest Algorithm . . . . . . . . . . . . 23 114 12.5. Obsolete "SHA" Digest Algorithm . . . . . . . . . . . . 23 115 12.6. Obsolete "ADLER32" Digest Algorithm . . . . . . . . . . 24 116 12.7. The "ID-SHA-256" Digest Algorithm . . . . . . . . . . . 24 117 12.8. The "ID-SHA-512" Digest Algorithm . . . . . . . . . . . 24 118 12.9. Changes compared to RFC5843 . . . . . . . . . . . . . . 24 119 12.10. Want-Digest Header Field Registration . . . . . . . . . 25 120 12.11. Digest Header Field Registration . . . . . . . . . . . . 25 121 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 122 13.1. Normative References . . . . . . . . . . . . . . . . . . 25 123 13.2. Informative References . . . . . . . . . . . . . . . . . 28 124 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 28 125 Appendix A. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 28 126 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 29 127 Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 30 128 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 129 D.1. Since draft-ietf-httpbis-digest-headers-00 . . . . . . . 30 130 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 132 1. Introduction 134 The core specification of HTTP does not define a means to protect the 135 integrity of resources. When HTTP messages are transferred between 136 endpoints, the protocol might choose to make use of features of the 137 lower layer in order to provide some integrity protection; for 138 instance TCP checksums or TLS records [RFC2818]. 140 However, there are cases where relying on this alone is insufficient. 141 An HTTP-level integrity mechanism that operates independent of 142 transfer can be used to detect programming errors and/or corruption 143 of data at rest, be used across multiple hops in order to provide 144 end-to-end integrity guarantees, aid fault diagnosis across hops and 145 system boundaries, and can be used to validate integrity when 146 reconstructing a resource fetched using different HTTP connections. 148 This document defines a mechanism that acts on HTTP representation- 149 data. It can be combined with other mechanisms that protect 150 representation-metadata, such as digital signatures, in order to 151 protect the desired parts of an HTTP exchange in whole or in part. 153 1.1. A Brief History of Integrity Header Fields 155 The Content-MD5 header field was originally introduced to provide 156 integrity, but HTTP/1.1 ([RFC7231], Appendix B) obsoleted it: 158 The Content-MD5 header field has been removed because it was 159 inconsistently implemented with respect to partial responses. 161 [RFC3230] provided a more flexible solution introducing the concept 162 of "instance", and the header fields "Digest" and "Want-Digest". 164 1.2. This Proposal 166 The concept of "selected representation" defined in [RFC7231] made 167 [RFC3230] definitions inconsistent with the current standard. A 168 refresh was then required. 170 This document updates the "Digest" and "Want-Digest" header field 171 definitions to align with [RFC7231] concepts. 173 This approach can be easily adapted to use-cases where the 174 transferred data does require some sort of manipulation to be 175 considered a representation or conveys a partial representation of a 176 resource (eg. Range Requests [RFC7233]). 178 Changes are semantically compatible with existing implementations and 179 better cover both the request and response cases. 181 The value of "Digest" is calculated on selected representation, which 182 is tied to the value contained in any "Content-Encoding" or "Content- 183 Type" header fields. Therefore, a given resource may have multiple 184 different digest values. 186 To allow both parties to exchange a Digest of a representation with 187 no content codings [3] two more algorithms are added ("ID-SHA-256" 188 and "ID-SHA-512"). 190 1.3. Goals 192 The goals of this proposal are: 194 1. Digest coverage for either the resource's "representation data" 195 or "selected representation data" communicated via HTTP. 197 2. Support for multiple digest algorithms. 199 3. Negotiation of the use of digests. 201 The goals do not include: 203 HTTP Message integrity: The digest mechanism described here does not 204 cover the full HTTP message nor its semantic, as representation 205 metadata are not included in the checksum. 207 Header field integrity: The digest mechanisms described here cover 208 only representation and selected representation data, and do not 209 protect the integrity of associated representation metadata or 210 other message header fields. 212 Authentication: The digest mechanisms described here are not meant 213 to support authentication of the source of a digest or of a 214 message or anything else. These mechanisms, therefore, are not a 215 sufficient defense against many kinds of malicious attacks. 217 Privacy: Digest mechanisms do not provide message privacy. 219 Authorization: The digest mechanisms described here are not meant to 220 support authorization or other kinds of access controls. 222 1.4. Notational Conventions 224 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 225 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 226 "OPTIONAL" in this document are to be interpreted as described in BCP 227 14 ([RFC2119] and [RFC8174]) when, and only when, they appear in all 228 capitals, as shown here. 230 This document uses the Augmented BNF defined in [RFC5234] and updated 231 by [RFC7405] along with the "#rule" extension defined in Section 7 of 232 [RFC7230]. 234 The definitions "representation", "selected representation", 235 "representation data", "representation metadata", and "payload body" 236 in this document are to be interpreted as described in [RFC7230] and 237 [RFC7231]. 239 The definition "validator" in this document is to be interpreted as 240 described in Section 7.2 of [RFC7231]. 242 2. Resource Representation and Representation-Data 244 To avoid inconsistencies, an integrity mechanism for HTTP messages 245 should decouple the checksum calculation from: 247 o the payload body - which may be altered by mechanism like Range 248 Requests [RFC7233] or the method (eg. HEAD); 250 o and the message body - which depends on "Transfer-Encoding" and 251 whatever transformations the intermediaries may apply. 253 The following examples show how representation metadata, payload 254 transformations and method impacts on the message and payload body. 256 Here is a gzip-compressed json object 258 Request: 260 PUT /entries/1234 HTTP/1.1 261 Content-Type: application/json 262 Content-Encoding: gzip 264 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 266 Now the same payload body conveys a malformed json object. 268 Request: 270 PUT /entries/1234 HTTP/1.1 271 Content-Type: application/json 273 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 275 A Range-Request alters the payload body, conveying a partial 276 representation. 278 Request: 280 GET /entries/1234 HTTP/1.1 281 Range: bytes=1-7 283 Response: 285 HTTP/1.1 206 Partial Content 286 Content-Encoding: gzip 287 Content-Type: application/json 288 Content-Range: bytes 1-7/18 290 iwgAla3RXA== 292 Now the method too alters the payload body. 294 Request: 296 HEAD /entries/1234 HTTP/1.1 297 Accept: application/json 298 Accept-Encoding: gzip 300 Response: 302 HTTP/1.1 200 OK 303 Content-Type: application/json 304 Content-Encoding: gzip 306 3. Digest Algorithm Values 308 Digest algorithm values are used to indicate a specific digest 309 computation. For some algorithms, one or more parameters may be 310 supplied. 312 digest-algorithm = token 314 The BNF for "parameter" is as is used in [RFC7230]. All digest- 315 algorithm values are case-insensitive. 317 The Internet Assigned Numbers Authority (IANA) acts as a registry for 318 digest-algorithm values. The registry contains the following tokens. 320 SHA-256: 322 * Description: The SHA-256 algorithm [RFC6234]. The output of 323 this algorithm is encoded using the base64 encoding [RFC4648]. 325 * Reference: [RFC6234], [RFC4648], this document. 327 * Status: standard 329 SHA-512: 331 * Description: The SHA-512 algorithm [RFC6234]. The output of 332 this algorithm is encoded using the base64 encoding [RFC4648]. 334 * Reference: [RFC6234], [RFC4648], this document. 336 * Status: standard 338 MD5: 340 * Description: The MD5 algorithm, as specified in [RFC1321]. The 341 output of this algorithm is encoded using the base64 encoding 342 [RFC4648]. The MD5 algorithm MUST NOT be used as it's now 343 vulnerable to collision attacks [CMU-836068]. 345 * Reference: [RFC1321], [RFC4648], this document. 347 * Status: deprecated 349 SHA: 351 * Description: The SHA-1 algorithm [RFC3174]. The output of this 352 algorithm is encoded using the base64 encoding [RFC4648]. The 353 SHA algorithm is NOT RECOMMENDED as it's now vulnerable to 354 collision attacks [IACR-2019-459]. 356 * Reference: [RFC3174], [RFC6234], [RFC4648], this document. 358 * Status: obsoleted 360 UNIXsum: 362 * Description: The algorithm computed by the UNIX "sum" command, 363 as defined by the Single UNIX Specification, Version 2 [UNIX]. 364 The output of this algorithm is an ASCII decimal-digit string 365 representing the 16-bit checksum, which is the first word of 366 the output of the UNIX "sum" command. 368 * Reference: [UNIX], this document. 370 * Status: standard 372 UNIXcksum: 374 * Description: The algorithm computed by the UNIX "cksum" 375 command, as defined by the Single UNIX Specification, Version 2 376 [UNIX]. The output of this algorithm is an ASCII digit string 377 representing the 32-bit CRC, which is the first word of the 378 output of the UNIX "cksum" command. 380 * Reference: [UNIX], this document. 382 * Status: standard 384 To allow sender and recipient to provide a checksum which is 385 independent from "Content-Encoding", the following additional 386 algorithms are defined: 388 ID-SHA-512: 390 * Description: The sha-512 digest of the representation-data of 391 the resource when no content coding is applied (eg. "Content- 392 Encoding: identity") 394 * Reference: [RFC6234], [RFC4648], this document. 396 * Status: standard 398 ID-SHA-256: 400 * Description: The sha-256 digest of the representation-data of 401 the resource when no content coding is applied (eg. "Content- 402 Encoding: identity") 404 * Reference: [RFC6234], [RFC4648], this document. 406 * Status: standard 408 If other digest-algorithm values are defined, the associated encoding 409 MUST either be represented as a quoted string, or MUST NOT include 410 ";" or "," in the character sets used for the encoding. 412 3.1. Representation Digest 414 A representation digest is the value of the output of a digest 415 algorithm, together with an indication of the algorithm used (and any 416 parameters). 418 representation-data-digest = digest-algorithm "=" 419 421 As explained in Section 2 the digest is computed on the entire 422 selected "representation data" of the resource defined in [RFC7231]: 424 representation-data := Content-Encoding( Content-Type( bits ) ) 426 The encoded digest output uses the encoding format defined for the 427 specific digest-algorithm. 429 3.1.1. digest-algorithm Encoding Examples 431 The "sha-256" digest-algorithm uses base64 encoding. Note that 432 digest-algorithm values are case insensitive. 434 sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 436 The "UNIXsum" digest-algorithm uses ASCII string of decimal digits. 438 UNIXsum=30637 440 4. Header Field Specifications 442 The following headers are defined 444 4.1. Want-Digest 446 The Want-Digest message header field indicates the sender's desire to 447 receive a representation digest on messages associated with the 448 request URI and representation metadata. 450 Want-Digest = "Want-Digest" ":" OWS 1#want-digest-value 451 want-digest-value = digest-algorithm [ ";" "q" "=" qvalue] 452 qvalue = ( "0" [ "." 0*1DIGIT ] ) / ( "1" [ "." 0*1( "0" ) ] ) 454 If a digest-algorithm is not accompanied by a qvalue, it is treated 455 as if its associated qvalue were 1.0. 457 The sender is willing to accept a digest-algorithm if and only if it 458 is listed in a Want-Digest header field of a message, and its qvalue 459 is non-zero. 461 If multiple acceptable digest-algorithm values are given, the 462 sender's preferred digest-algorithm is the one (or ones) with the 463 highest qvalue. 465 Two examples of its use are 467 Want-Digest: sha-256 468 Want-Digest: SHA-512;q=0.3, sha-256;q=1, md5;q=0 470 4.2. Digest 472 The Digest header field provides a digest of the representation data. 474 Digest = "Digest" ":" OWS 1#representation-data-digest 476 "Representation data" might be: 478 o fully contained in the message body, 480 o partially-contained in the message body, 482 o or not at all contained in the message body. 484 The resource is specified by the effective request URI and any 485 "validator" contained in the message. 487 For example, in a response to a HEAD request, the digest is 488 calculated using the representation data that would have been 489 enclosed in the payload body if the same request had been a GET. 491 Digest can be used in requests too. 493 The "Digest" value depends on the representation metadata. 495 A Digest header field MAY contain multiple representation-data-digest 496 values. This could be useful for responses expected to reside in 497 caches shared by users with different browsers, for example. 499 A recipient MAY ignore any or all of the representation-data-digests 500 in a Digest header field. This allows the recipient to chose which 501 digest-algorithm(s) to use for validation instead of verifying every 502 received representation-data-digest. 504 A sender MAY send a representation-data-digest using a digest- 505 algorithm without knowing whether the recipient supports the digest- 506 algorithm, or even knowing that the recipient will ignore it. 508 Two examples of its use are 510 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 511 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 513 5. Use of Digest when acting on resources 515 POST and PATCH requests may appear to convey partial representations 516 but are semantically acting on resources. The enclosed 517 representation, including its metadata refers to that action. 519 In these requests the representation digest MUST be computed on the 520 representation-data of that action. 522 This is the only possible choice because representation digest 523 requires complete representation metadata (see Section 3.1). 525 In responses, 526 o if the representation describes the status of the request, 527 "Digest" MUST be computed on the enclosed representation (see 528 Section 9.8 ); 530 o if there is a referenced resource "Digest" MUST be computed on the 531 selected representation of the referenced resource even if that is 532 different from the target resource. That may or may not result in 533 computing "Digest" on the enclosed representation. 535 The latter case might be done accordingly to the HTTP semantics of 536 the given method, for example using the "Content-Location" header 537 field. 539 Differently from "Content-Location", which is representation 540 metadata, the "Location" header field does not affect "Digest". 542 5.1. Digest and PATCH 544 In PATCH requests the representation digest MUST be computed on the 545 patch document. 547 This is because the representation metadata refers to the patch 548 document and not to the target resource (see Section 2 of [RFC5789]). 550 In PATCH responses the representation digest MUST be computed on the 551 selected representation of the patched resource. 553 "Digest" usage with PATCH is thus very similar to the POST one, but 554 with the resource's own semantic partly implied by the method and by 555 the patch document. 557 6. Deprecate Negotiation of Content-MD5 559 This RFC deprecates the negotiation of Content-MD5 as it has been 560 obsoleted by [RFC7231] 562 7. Broken Cryptographic Algorithms 564 The MD5 algorithm MUST NOT be used as it has been found vulnerable to 565 collision attacks [CMU-836068]. 567 The SHA algorithm is NOT RECOMMENDED as it has been found vulnerable 568 to collision attacks [IACR-2019-459]. 570 8. Relationship to Subresource Integrity (SRI) 572 Subresource Integrity [SRI] is an integrity mechanism that shares 573 some similarities to the present document's mechanism. However, 574 there are differences in motivating factors, threat model and 575 specification of integrity digest generation, signalling and 576 validation. 578 SRI allows a first-party authority to declare an integrity assertion 579 on a resource served by a first or third party authority. This is 580 done via the "integrity" attribute that can added to "script" or 581 "link" HTML elements. Therefore, the integrity assertion is always 582 made out-of-band to the resource fetch. In contrast, the "Digest" 583 header field is supplied in-band alongside the selected 584 representation, meaning that an authority can only declare an 585 integrity assertion for itself. Methods to improve the security 586 properties of representation digests are presented in Section 11. 587 This contrast is interesting because on one hand self-assertion is 588 less likely to be affected by coordination problems such as the 589 first-party holding stale information about the third party, but on 590 the other hand the self-assertion is only as trustworthy as the 591 authority that provided it. 593 The SRI "integrity" attribute contains a cryptographic hash algorithm 594 and digest value which is similar to "representation-data-digest" 595 (see Section 3.1). The major differences are in serialization 596 format. 598 The SRI digest value is calculated over the identity encoding of the 599 resource, not the selected representation (as specified for 600 "representation-data-digest" in this document). Section 3.4.5 of 601 [SRI] describes the benefit of the identity approach - the SRI 602 "integrity" attribute can contain multiple algorithm-value pairs 603 where each applies to a different identity encoded payload. This 604 allows for protection of distinct resources sharing a URL. However, 605 this is a contrast to the design of representation digests, where 606 multiple "Digest" field-values all protect the same representation. 608 SRI does not specify handling of partial representation data (e.g. 609 Range requests). In contrast, this document specifies handling in 610 terms that are fully compatible with core HTTP concepts (an example 611 is provided in Section 9.3). 613 SRI specifies strong requirements on the selection of algorithm for 614 generation and validation of digests. In contrast, the requirements 615 in this document are weaker. 617 SRI defines no method for a client to declare an integrity assertion 618 on resources it transfers to a server. In contrast, the "Digest" 619 header field can appear on requests. 621 8.1. Supporting Both SRI and Representation Digest 623 The SRI and Representation Digest mechanism are different and 624 complementary but one is not capable of replacing the other because 625 they have have different threat, security and implementation 626 properties. 628 A user agent that supports both mechanisms is expected to apply the 629 rules specified for each but since the two mechanisms are 630 independent, the ordering is not important. However, a user agent 631 supporting both could benefit from performing representation digest 632 validation first because the it does not require a conversion to into 633 identity encoding. 635 There is a chance that a user agent supporting both mechanisms may 636 find one validates successfully while the other fails. This document 637 specifies no requirements or guidance for user agents that experience 638 such cases. 640 9. Examples of Unsolicited Digest 642 The following examples demonstrate interactions where a server 643 responds with a "Digest" header field even though the client did not 644 solicit one using "Want-Digest". 646 9.1. Server Returns Full Representation Data 648 Request: 650 GET /items/123 652 Response: 654 HTTP/1.1 200 OK 655 Content-Type: application/json 656 Content-Encoding: identity 657 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 659 {"hello": "world"} 661 9.2. Server Returns No Representation Data 663 As there is no content coding applied, the "sha-256" and the "id-sha- 664 256" digest-values are the same. 666 Request: 668 HEAD /items/123 670 Response: 672 HTTP/1.1 200 OK 673 Content-Type: application/json 674 Content-Encoding: identity 675 Digest: id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 677 9.3. Server Returns Partial Representation Data 679 Request: 681 GET /items/123 682 Range: bytes=1-7 684 Response: 686 HTTP/1.1 206 Partial Content 687 Content-Type: application/json 688 Content-Encoding: identity 689 Content-Range: bytes 1-7/18 690 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 692 "hello" 694 9.4. Client and Server Provide Full Representation Data 696 The request contains a "Digest" header calculated on the enclosed 697 representation. 699 It also includes an "Accept-Encoding: br" header field that 700 advertises the client supports brotli encoding. 702 The response includes a "Content-Encoding: br" that indicates the 703 selected representation is brotli encoded. The "Digest" field-value 704 is therefore different compared to the request. 706 Request: 708 PUT /items/123 709 Content-Type: application/json 710 Content-Encoding: identity 711 Accept-Encoding: br 712 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 714 {"hello": "world"} 716 Response: 718 Content-Type: application/json 719 Content-Encoding: br 720 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 722 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 724 9.5. Client Provides Full Representation Data, Server Provides No 725 Representation Data 727 Request "Digest" value is calculated on the enclosed payload. 728 Response "Digest" value depends on the representation metadata header 729 fields, including "Content-Encoding: br" even when the response does 730 not contain a payload body. 732 Request: 734 PUT /items/123 735 Content-Type: application/json 736 Content-Encoding: identity 737 Content-Length: 18 738 Accept-Encoding: br 739 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 741 {"hello": "world"} 743 Response: 745 HTTP/1.1 204 No Content 746 Content-Type: application/json 747 Content-Encoding: br 748 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 750 9.6. Client and Server Provide Full Representation Data, Client Uses 751 id-sha-256. 753 The response contains two digest values: 755 o one with no content coding applied, which in this case 756 accidentally matches the unencoded digest-value sent in the 757 request; 759 o one taking into account the "Content-Encoding". 761 Request: 763 PUT /items/123 HTTP/1.1 764 Content-Type: application/json 765 Content-Encoding: identity 766 Accept-Encoding: br 767 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 769 {"hello": "world"} 771 Response: 773 HTTP/1.1 200 OK 774 Content-Type: application/json 775 Content-Encoding: br 776 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 778 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 780 9.7. POST Response does not Reference the Request URI 782 Request "Digest" value is computed on the enclosed representation 783 (see Section 5). 785 The representation enclosed in the response refers to the resource 786 identified by "Content-Location" (see [RFC7231] Section 3.1.4.2 and 787 Section 3.1.4.1 point 4). 789 "Digest" is thus computed on the enclosed representation. 791 Request: 793 POST /books HTTP/1.1 794 Content-Type: application/json 795 Accept: application/json 796 Accept-Encoding: identity 797 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 799 {"title": "New Title"} 801 Response 803 HTTP/1.1 201 Created 804 Content-Type: application/json 805 Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc= 806 Content-Location: /books/123 808 {"id": "123", "title": "New Title"} 810 Note that a "204 No Content" response without a payload body but with 811 the same "Digest" field-value would have been legitimate too. 813 9.8. POST Response Describes the Request Status 815 Request "Digest" value is computed on the enclosed representation 816 (see Section 5). 818 The representation enclosed in the response describes the status of 819 the request, so "Digest" is computed on that enclosed representation. 821 Response "Digest" has no explicit relation with the resource 822 referenced by "Location". 824 Request: 826 POST /books HTTP/1.1 827 Content-Type: application/json 828 Accept: application/json 829 Accept-Encoding: identity 830 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 831 Location: /books/123 833 {"title": "New Title"} 835 Response 837 HTTP/1.1 201 Created 838 Content-Type: application/json 839 Digest: id-sha-256=0o/WKwSfnmIoSlop2LV/ISaBDth05IeW27zzNMUh5l8= 840 Location: /books/123 842 {"status": "created", "id": "123", "ts": 1569327729, "instance": "/books/123"} 844 9.9. Digest with PATCH 846 This case is analogous to a POST request where the target resource 847 reflects the effective request URI. 849 The PATCH request uses the "application/merge-patch+json" media type 850 defined in [RFC7396]. 852 "Digest" is calculated on the enclosed payload, which corresponds to 853 the patch document. 855 The response "Digest" is computed on the complete representation of 856 the patched resource. 858 Request: 860 PATCH /books/123 HTTP/1.1 861 Content-Type: application/merge-patch+json 862 Accept: application/json 863 Accept-Encoding: identity 864 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 866 {"title": "New Title"} 868 Response: 870 HTTP/1.1 200 OK 871 Content-Type: application/json 872 Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc= 874 {"id": "123", "title": "New Title"} 876 Note that a "204 No Content" response without a payload body but with 877 the same "Digest" field-value would have been legitimate too. 879 10. Examples of Want-Digest Solicited Digest 881 The following examples demonstrate interactions where a client 882 solicits a "Digest" using "Want-Digest". 884 10.1. Server Selects Client's Least Preferred Algorithm 886 The client requests a digest, preferring sha. The server is free to 887 reply with sha-256 anyway. 889 Request: 891 GET /items/123 HTTP/1.1 892 Want-Digest: sha-256;q=0.3, sha;q=1 894 Response: 896 HTTP/1.1 200 OK 897 Content-Type: application/json 898 Content-Encoding: identity 899 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 901 {"hello": "world"} 903 10.2. Server Selects Algorithm Unsupported by Client 905 The client requests a sha digest only. The server is currently free 906 to reply with a Digest containing an unsupported algorithm. 908 Request: 910 GET /items/123 911 Want-Digest: sha;q=1 913 Response: 915 HTTP/1.1 200 OK 916 Content-Type: application/json 917 Content-Encoding: identity 918 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 920 {"hello": "world"} 922 10.3. Server Does Not Support Client Algorithm and Returns an Error 924 The client requests a sha Digest, the server advises for sha-256 and 925 sha-512 927 Request: 929 GET /items/123 930 Want-Digest: sha;q=1 932 Response: 934 HTTP/1.1 400 Bad Request 935 Want-Digest: sha-256, sha-512 937 11. Security Considerations 939 11.1. Digest Does Not Protect the Full HTTP Message 941 This document specifies a data integrity mechanism that protects HTTP 942 "representation data", but not HTTP "representation metadata" header 943 fields, from certain kinds of accidental corruption. 945 "Digest" is not intended as general protection against malicious 946 tampering with HTTP messages, this can be achieved by combining it 947 with other approaches such as transport-layer security or digital 948 signatures. 950 11.2. Broken Cryptographic Algorithms 952 Cryptographic algorithms are intended to provide a proof of integrity 953 suited towards cryptographic constructions such as signatures. 955 However, these rely on collision-resistance for their security proofs 956 [CMU-836068]. The MD5 and SHA-1 algorithms are vulnerable to 957 collisions attacks, so MD5 MUST NOT be used and SHA-1 is NOT 958 RECOMMENDED for use with "Digest". 960 11.3. Other Deprecated Algorithms 962 The ADLER32 algorithm defined in [RFC1950] has been deprecated by 963 [RFC3309] because under certain conditions it provides weak detection 964 of errors and is now NOT RECOMMENDED for use with "Digest". 966 11.4. Digest for End-to-End Integrity 968 "Digest" alone does not provide end-to-end integrity of HTTP messages 969 over multiple hops, as it just covers the "representation data" and 970 not the "representation metadata". 972 Besides, it allows to protect "representation data" from buggy 973 manipulation, buggy compression, etc. 975 Moreover identity digest algorithms (eg. ID-SHA-256 and ID-SHA-512) 976 allow piecing together a resource from different sources (e.g. 977 different servers that perhaps apply different content codings) 978 enabling the user-agent to detect that the application-layer tasks 979 completed properly, before handing off to say the HTML parser, video 980 player etc. 982 Even a simple mechanism for end-to-end validation is thus valuable. 984 11.5. Usage in Signatures 986 Digital signatures are widely used together with checksums to provide 987 the certain identification of the origin of a message [NIST800-32]. 988 Such signatures can protect one or more header fields and there are 989 additional considerations when "Digest" is included in this set. 991 Since the "Digest" header field is a hash of a resource 992 representation, it explicitly depends on the "representation 993 metadata" (eg. the values of "Content-Type", "Content-Encoding" etc). 994 A signature that protects "Digest" but not other "representation 995 metadata" may expose the communication to tampering. For example, an 996 actor could manipulate the "Content-Type" field-value and cause a 997 digest validation failure at the recipient, preventing the 998 application from accessing the representation. Such an attack 999 consumes the resources of both endpoints. 1001 "Digest" SHOULD always be used over a connection which provides 1002 integrity at transport layer that protects HTTP header fields. 1004 A "Digest" header field using NOT RECOMMENDED digest-algorithms 1005 SHOULD NOT be used in signatures. 1007 11.6. Message Truncation 1009 ... 1011 11.7. Algorithm Agility 1013 ... 1015 12. IANA Considerations 1017 12.1. Establish the HTTP Digest Algorithm Values 1019 This memo sets this spec to be the establishing document for the HTTP 1020 Digest Algorithm Values [4] 1022 12.2. The "status" Field in the HTTP Digest Algorithm Values 1024 This memo adds the field "Status" to the HTTP Digest Algorithm Values 1025 [5] registry. The allowed values for the "Status" fields are 1026 described below. 1028 Status Specify "standard", "experimental", "historic", "obsoleted", 1029 or "deprecated" according to the type and status of the primary 1030 document in which the algorithm is defined. 1032 12.3. Deprecate "MD5" Digest Algorithm 1034 This memo updates the "MD5" digest algorithm in the HTTP Digest 1035 Algorithm Values [6] registry: 1037 o Digest Algorithm: MD5 1039 o Description: As specified in Section 3. 1041 o Status: As specified in Section 3. 1043 12.4. Update "CRC32C" Digest Algorithm 1045 This memo updates the "CRC32c" digest algorithm in the HTTP Digest 1046 Algorithm Values [7] registry: 1048 o Digest Algorithm: CRC32c 1050 o Description: The CRC32c algorithm is a 32-bit cyclic redundancy 1051 check. It achieves a better hamming distance (for better error- 1052 detection performance) than many other 32-bit CRC functions. 1053 Other places it is used include iSCSI and SCTP. The 32-bit output 1054 is encoded in hexadecimal (using between 1 and 8 ASCII characters 1055 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 1056 CRC32c=0a72a4df and crc32c=A72A4DF are both valid checksums for 1057 the 3-byte message "dog". 1059 o Reference: [RFC4960] appendix B, this document. 1061 o Status: standard. 1063 12.5. Obsolete "SHA" Digest Algorithm 1065 This memo updates the "SHA" digest algorithm in the HTTP Digest 1066 Algorithm Values [8] registry: 1068 o Digest Algorithm: SHA 1069 o Description: As specified in Section 3. 1071 o Status: As specified in Section 3. 1073 12.6. Obsolete "ADLER32" Digest Algorithm 1075 This memo updates the "ADLER32" digest algorithm in the HTTP Digest 1076 Algorithm Values [9] registry: 1078 o Digest Algorithm: ADLER32 1080 o Description: The ADLER32 algorithm is a checksum specified in 1081 [RFC1950] "ZLIB Compressed Data Format". The 32-bit output is 1082 encoded in hexadecimal (using between 1 and 8 ASCII characters 1083 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 1084 ADLER32=03da0195 and ADLER32=3DA0195 are both valid checksums for 1085 the 4-byte message "Wiki". This algorithm is obsoleted and SHOULD 1086 NOT be used. 1088 o Status: obsoleted 1090 12.7. The "ID-SHA-256" Digest Algorithm 1092 This memo registers the "ID-SHA-256" digest algorithm in the HTTP 1093 Digest Algorithm Values [10] registry: 1095 o Digest Algorithm: ID-SHA-256 1097 o Description: As specified in Section 3. 1099 o Status: As specified in Section 3. 1101 12.8. The "ID-SHA-512" Digest Algorithm 1103 This memo registers the "ID-SHA-512" digest algorithm in the HTTP 1104 Digest Algorithm Values [11] registry: 1106 o Digest Algorithm: ID-SHA-512 1108 o Description: As specified in Section 3. 1110 o Status: As specified in Section 3. 1112 12.9. Changes compared to RFC5843 1114 The status of "MD5" has been updated to "deprecated", and its 1115 description states that this algorithm MUST NOT be used. 1117 The status of "SHA" has been updated to "obsoleted", and its 1118 description states that this algorithm is NOT RECOMMENDED. 1120 The status for "CRC32C" has been updated to "standard". 1122 The "ID-SHA-256" and "ID-SHA-512" algorithms have been added to the 1123 registry. 1125 12.10. Want-Digest Header Field Registration 1127 This section registers the "Want-Digest" header field in the 1128 "Permanent Message Header Field Names" registry ([RFC3864]). 1130 Header field name: "Want-Digest" 1132 Applicable protocol: http 1134 Status: standard 1136 Author/Change controller: IETF 1138 Specification document(s): Section 4.1 of this document 1140 12.11. Digest Header Field Registration 1142 This section registers the "Digest" header field in the "Permanent 1143 Message Header Field Names" registry ([RFC3864]). 1145 Header field name: "Digest" 1147 Applicable protocol: http 1149 Status: standard 1151 Author/Change controller: IETF 1153 Specification document(s): Section 4.2 of this document 1155 13. References 1157 13.1. Normative References 1159 [CMU-836068] 1160 Carnagie Mellon University, Software Engineering 1161 Institute, "MD5 Vulnerable to collision attacks", December 1162 2008, . 1164 [IACR-2019-459] 1165 Leurent, G. and T. Peyrin, "From Collisions to Chosen- 1166 Prefix Collisions Application to Full SHA-1", May 2019, 1167 . 1169 [NIST800-32] 1170 National Institute of Standards and Technology, U.S. 1171 Department of Commerce, "Introduction to Public Key 1172 Technology and the Federal PKI Infrastructure", February 1173 2001, . 1176 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 1177 DOI 10.17487/RFC1321, April 1992, 1178 . 1180 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 1181 Specification version 3.3", RFC 1950, 1182 DOI 10.17487/RFC1950, May 1996, 1183 . 1185 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1186 Requirement Levels", BCP 14, RFC 2119, 1187 DOI 10.17487/RFC2119, March 1997, 1188 . 1190 [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 1191 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, 1192 . 1194 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 1195 RFC 3230, DOI 10.17487/RFC3230, January 2002, 1196 . 1198 [RFC3309] Stone, J., Stewart, R., and D. Otis, "Stream Control 1199 Transmission Protocol (SCTP) Checksum Change", RFC 3309, 1200 DOI 10.17487/RFC3309, September 2002, 1201 . 1203 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1204 Procedures for Message Header Fields", BCP 90, RFC 3864, 1205 DOI 10.17487/RFC3864, September 2004, 1206 . 1208 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1209 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1210 . 1212 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1213 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1214 . 1216 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1217 Specifications: ABNF", STD 68, RFC 5234, 1218 DOI 10.17487/RFC5234, January 2008, 1219 . 1221 [RFC5843] Bryan, A., "Additional Hash Algorithms for HTTP Instance 1222 Digests", RFC 5843, DOI 10.17487/RFC5843, April 2010, 1223 . 1225 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 1226 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 1227 DOI 10.17487/RFC6234, May 2011, 1228 . 1230 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1231 Protocol (HTTP/1.1): Message Syntax and Routing", 1232 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1233 . 1235 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1236 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1237 DOI 10.17487/RFC7231, June 2014, 1238 . 1240 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 1241 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 1242 RFC 7233, DOI 10.17487/RFC7233, June 2014, 1243 . 1245 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 1246 RFC 7405, DOI 10.17487/RFC7405, December 2014, 1247 . 1249 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1250 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1251 May 2017, . 1253 [UNIX] The Open Group, "The Single UNIX Specification, Version 2 1254 - 6 Vol Set for UNIX 98", February 1997. 1256 13.2. Informative References 1258 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 1259 DOI 10.17487/RFC2818, May 2000, 1260 . 1262 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1263 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1264 . 1266 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 1267 DOI 10.17487/RFC7396, October 2014, 1268 . 1270 [SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger, 1271 "Subresource Integrity", W3C Recommendation REC-SRI- 1272 20160623, June 2016, 1273 . 1275 13.3. URIs 1277 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 1279 [2] https://github.com/httpwg/http-extensions 1281 [3] https://tools.ietf.org/html/rfc7231#section-3.1.2.1 1283 [4] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1285 [5] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1287 [6] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1289 [7] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1291 [8] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1293 [9] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1295 [10] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1297 [11] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1299 Appendix A. FAQ 1301 1. Why remove all references to content-md5? 1303 Those were unnecessary to understanding and using this spec. 1305 2. Why remove references to instance manipulation? 1307 Those were unnecessary for correctly using and applying the spec. 1308 An example with Range Request is more than enough. This doc uses 1309 the term "partial representation" which should group all those 1310 cases. 1312 3. How to use "Digest" with "PATCH" method? 1314 See Section 5. 1316 4. Why remove references to delta-encoding? 1318 Unnecessary for a correct implementation of this spec. The 1319 revised spec can be nicely adapted to "delta encoding", but all 1320 the references here to delta encoding don't add anything to this 1321 RFC. Another job would be to refresh delta encoding. 1323 5. Why remove references to Digest Authentication? 1325 This RFC seems to me completely unrelated to Digest 1326 Authentication but for the word "Digest". 1328 6. What changes in "Want-Digest"? 1330 We allow to use the "Want-Digest" in responses to advertise the 1331 supported digest-algorithms and the inability to accept requests 1332 with unsupported digest-algorithms. 1334 7. Does this spec changes supported algorithms? 1336 This RFC updates [RFC5843] which is still delegated for all 1337 algorithms updates, and adds two more algorithms: ID-SHA-256 and 1338 ID-SHA-512 which allows to send a checksum of a resource 1339 representation with no content codings applied. 1341 Acknowledgements 1343 The vast majority of this document is inherited from [RFC3230], so 1344 thanks to J. Mogul and A. Van Hoff for their great work. The 1345 original idea of refreshing this document arose from an interesting 1346 discussion with M. Nottingham, J. Yasskin and M. Thomson when 1347 reviewing the MICE content coding. 1349 Code Samples 1351 _RFC Editor: Please remove this section before publication._ 1353 How can I generate and validate the Digest values shown in the 1354 examples throughout this document? 1356 The following python3 code can be used to generate digests for json 1357 objects using SHA algorithms for a range of encodings. Note that 1358 these are formatted as base64. This function could be adapted to 1359 other algorithms and should take into account their specific 1360 formatting rules. 1362 import base64, json, hashlib, brotli 1364 def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): 1365 json_bytes = json.dumps(item).encode() 1366 content_encoded = encoding(json_bytes) 1367 checksum_bytes = algorithm(content_encoded).digest() 1368 return base64.encodebytes(checksum_bytes).strip() 1370 item = {"hello": "world"} 1372 print("Identity encoding, sha256", digest(item)) 1373 # Out: Identity encoding, sha256 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1375 print("Brotli encoding, sha256", digest(item, encoding=brotli.compress)) 1376 # Out: Brotli encoding, sha256 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1378 print("Identity encoding, sha512", digest(item, algorithm=hashlib.sha512)) 1379 # Out: Identity encoding, sha512 b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==\n' 1381 Changes 1383 _RFC Editor: Please remove this section before publication._ 1385 D.1. Since draft-ietf-httpbis-digest-headers-00 1387 o Align title with document name 1389 o Add id-sha-* algorithm examples #880 1391 o Reference [RFC6234] and [RFC3174] instead of FIPS-1 1393 o Deprecate MD5 1394 o Obsolete ADLER-32 but don't forbid it #828 1396 o Update CRC32C value in IANA table #828 1398 o Use when acting on resources (POST, PATCH) #853 1400 o Added Relationship with SRI, draft Use Cases #868, #971 1402 Authors' Addresses 1404 Roberto Polli 1405 Team Digitale, Italian Government 1407 Email: robipolli@gmail.com 1409 Lucas Pardue 1410 Cloudflare 1412 Email: lucaspardue.24.7@gmail.com