idnits 2.17.1 draft-ietf-httpbis-digest-headers-02.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 (March 09, 2020) is 1506 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 1259 -- Looks like a reference, but probably isn't: '2' on line 1261 -- Looks like a reference, but probably isn't: '3' on line 1263 -- Looks like a reference, but probably isn't: '4' on line 1265 -- Looks like a reference, but probably isn't: '5' on line 1267 -- Looks like a reference, but probably isn't: '6' on line 1269 -- Looks like a reference, but probably isn't: '7' on line 1271 -- Looks like a reference, but probably isn't: '8' on line 1273 -- Looks like a reference, but probably isn't: '9' on line 1275 -- Looks like a reference, but probably isn't: '10' on line 1277 -- Looks like a reference, but probably isn't: '11' on line 1279 -- 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 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 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7233 (Obsoleted by RFC 9110) -- Possible downref: Non-RFC (?) normative reference: ref. 'UNIX' -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7807 (Obsoleted by RFC 9457) Summary: 12 errors (**), 0 flaws (~~), 2 warnings (==), 20 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: September 10, 2020 Cloudflare 6 March 09, 2020 8 Digest Headers 9 draft-ietf-httpbis-digest-headers-02 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 September 10, 2020. 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 Integrity Header 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 Header Field . . . . . . . . . . . . . . . . . . . 6 73 4. The Want-Digest Header 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 . . . . . . . 17 91 9.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . . 17 92 9.10. Error responses . . . . . . . . . . . . . . . . . . . . . 18 93 10. Examples of Want-Digest Solicited Digest . . . . . . . . . . 19 94 10.1. Server Selects Client's Least Preferred Algorithm . . . 19 95 10.2. Server Selects Algorithm Unsupported by Client . . . . . 20 96 10.3. Server Does Not Support Client Algorithm and Returns an 97 Error . . . . . . . . . . . . . . . . . . . . . . . . . 20 98 11. Security Considerations . . . . . . . . . . . . . . . . . . . 20 99 11.1. Digest Does Not Protect the Full HTTP Message . . . . . 20 100 11.2. Broken Cryptographic Algorithms . . . . . . . . . . . . 21 101 11.3. Other Deprecated Algorithms . . . . . . . . . . . . . . 21 102 11.4. Digest for End-to-End Integrity . . . . . . . . . . . . 21 103 11.5. Digest and Content-Location in responses . . . . . . . . 21 104 11.6. Usage in signatures . . . . . . . . . . . . . . . . . . 21 105 11.7. Message Truncation . . . . . . . . . . . . . . . . . . . 22 106 11.8. Algorithm Agility . . . . . . . . . . . . . . . . . . . 22 107 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 108 12.1. Establish the HTTP Digest Algorithm Values . . . . . . . 22 109 12.2. The "status" Field in the HTTP Digest Algorithm Values . 22 110 12.3. Deprecate "MD5" Digest Algorithm . . . . . . . . . . . . 23 111 12.4. Update "CRC32C" Digest Algorithm . . . . . . . . . . . . 23 112 12.5. Obsolete "SHA" Digest Algorithm . . . . . . . . . . . . 23 113 12.6. Obsolete "ADLER32" Digest Algorithm . . . . . . . . . . 23 114 12.7. The "ID-SHA-256" Digest Algorithm . . . . . . . . . . . 24 115 12.8. The "ID-SHA-512" Digest Algorithm . . . . . . . . . . . 24 116 12.9. Changes compared to RFC5843 . . . . . . . . . . . . . . 24 117 12.10. Want-Digest Header Field Registration . . . . . . . . . 25 118 12.11. Digest Header Field Registration . . . . . . . . . . . . 25 119 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 120 13.1. Normative References . . . . . . . . . . . . . . . . . . 25 121 13.2. Informative References . . . . . . . . . . . . . . . . . 27 122 13.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 28 123 Appendix A. Resource Representation and Representation-Data . . 28 124 Appendix B. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 30 125 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 31 126 Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 31 127 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 128 E.1. Since draft-ietf-httpbis-digest-headers-00 . . . . . . . 32 129 E.2. Since draft-ietf-httpbis-digest-headers-01 . . . . . . . 33 130 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 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. Representation Digest 244 The representation digest is an integrity mechanism for HTTP 245 resources which uses a checksum that is calculated independently of 246 the payload body and message body. It uses the representation data 247 (see [RFC7231]), that can be fully or partially contained in the 248 message body, or not contained at all: 250 representation-data := Content-Encoding( Content-Type( bits ) ) 252 This takes into account the effect of the HTTP semantics on the 253 messages; for example the payload body can be affected by Range 254 Requests or methods such as HEAD, while the message body is dependent 255 on transfer codings and other transformations: Appendix A contains 256 several examples to help illustrate those effects. 258 A representation digest consists of the value of a checksum computed 259 on the entire selected "representation data" of a resource together 260 with an indication of the algorithm used (and any parameters) 262 representation-data-digest = digest-algorithm "=" 263 265 The checksum is computed using one of the "digest-algorithms" listed 266 in Section 5 and then encoded in the associated format. 268 The example below shows the "sha-256" digest-algorithm which uses 269 base64 encoding. 271 sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 273 3. The Digest Header Field 275 The Digest header field contains a list of one or more representation 276 digest values as defined in Section 2. It can be used in both 277 request and response. 279 Digest = "Digest" ":" OWS 1#representation-data-digest 281 The resource is specified by the effective request URI and any 282 "validator" contained in the message. 284 The relationship between Content-Location (see [RFC7231] 285 Section 3.1.4.2) and Digest is demonstrated in Section 9.7. A 286 comprehensive set of examples showing the impacts of representation 287 metadata, payload transformations and HTTP methods on digest is 288 provided in Section 9 and Section 10. 290 A Digest header field MAY contain multiple representation-data-digest 291 values. This could be useful for responses expected to reside in 292 caches shared by users with different browsers, for example. 294 A recipient MAY ignore any or all of the representation-data-digests 295 in a Digest header field. This allows the recipient to choose which 296 digest-algorithm(s) to use for validation instead of verifying every 297 received representation-data-digest. 299 A sender MAY send a representation-data-digest using a digest- 300 algorithm without knowing whether the recipient supports the digest- 301 algorithm, or even knowing that the recipient will ignore it. 303 Two examples of its use are 305 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 306 AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 308 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 309 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 311 4. The Want-Digest Header Field 313 The Want-Digest message header field indicates the sender's desire to 314 receive a representation digest on messages associated with the 315 request URI and representation metadata. 317 Want-Digest = "Want-Digest" ":" OWS 1#want-digest-value 318 want-digest-value = digest-algorithm [ ";" "q" "=" qvalue] 319 qvalue = ( "0" [ "." 0*1DIGIT ] ) / 320 ( "1" [ "." 0*1( "0" ) ] ) 322 If a digest-algorithm is not accompanied by a qvalue, it is treated 323 as if its associated qvalue were 1.0. 325 The sender is willing to accept a digest-algorithm if and only if it 326 is listed in a Want-Digest header field of a message, and its qvalue 327 is non-zero. 329 If multiple acceptable digest-algorithm values are given, the 330 sender's preferred digest-algorithm is the one (or ones) with the 331 highest qvalue. 333 Two examples of its use are 334 Want-Digest: sha-256 335 Want-Digest: SHA-512;q=0.3, sha-256;q=1, md5;q=0 337 5. Digest Algorithm Values 339 Digest algorithm values are used to indicate a specific digest 340 computation. For some algorithms, one or more parameters can be 341 supplied. 343 digest-algorithm = token 345 The BNF for "parameter" is as is used in [RFC7230]. All digest- 346 algorithm values are case-insensitive. 348 The Internet Assigned Numbers Authority (IANA) acts as a registry for 349 digest-algorithm values. The registry contains the tokens listed 350 below. 352 Some algorithms, although registered, have since been found 353 vulnerable: the MD5 algorithm MUST NOT be used due to collision 354 attacks [CMU-836068] and the SHA algorithm is NOT RECOMMENDED due to 355 collision attacks [IACR-2019-459]. 357 SHA-256 359 * Description: The SHA-256 algorithm [RFC6234]. The output of 360 this algorithm is encoded using the base64 encoding [RFC4648]. 362 * Reference: [RFC6234], [RFC4648], this document. 364 * Status: standard 366 SHA-512 368 * Description: The SHA-512 algorithm [RFC6234]. The output of 369 this algorithm is encoded using the base64 encoding [RFC4648]. 371 * Reference: [RFC6234], [RFC4648], this document. 373 * Status: standard 375 MD5 377 * Description: The MD5 algorithm, as specified in [RFC1321]. The 378 output of this algorithm is encoded using the base64 encoding 380 [RFC4648]. The MD5 algorithm MUST NOT be used as it's now 381 vulnerable to collision attacks [CMU-836068]. 383 * Reference: [RFC1321], [RFC4648], this document. 385 * Status: deprecated 387 SHA 389 * Description: The SHA-1 algorithm [RFC3174]. The output of this 390 algorithm is encoded using the base64 encoding [RFC4648]. The 391 SHA algorithm is NOT RECOMMENDED as it's now vulnerable to 392 collision attacks [IACR-2019-459]. 394 * Reference: [RFC3174], [RFC6234], [RFC4648], this document. 396 * Status: obsoleted 398 UNIXsum 400 * Description: The algorithm computed by the UNIX "sum" command, 401 as defined by the Single UNIX Specification, Version 2 [UNIX]. 402 The output of this algorithm is an ASCII decimal-digit string 403 representing the 16-bit checksum, which is the first word of 404 the output of the UNIX "sum" command. 406 * Reference: [UNIX], this document. 408 * Status: standard 410 UNIXcksum 412 * Description: The algorithm computed by the UNIX "cksum" 413 command, as defined by the Single UNIX Specification, Version 2 414 [UNIX]. The output of this algorithm is an ASCII digit string 415 representing the 32-bit CRC, which is the first word of the 416 output of the UNIX "cksum" command. 418 * Reference: [UNIX], this document. 420 * Status: standard 422 To allow sender and recipient to provide a checksum which is 423 independent from "Content-Encoding", the following additional 424 algorithms are defined: 426 ID-SHA-512 428 * Description: The sha-512 digest of the representation-data of 429 the resource when no content coding is applied (eg. "Content- 430 Encoding: identity") 432 * Reference: [RFC6234], [RFC4648], this document. 434 * Status: standard 436 ID-SHA-256 438 * Description: The sha-256 digest of the representation-data of 439 the resource when no content coding is applied (eg. "Content- 440 Encoding: identity") 442 * Reference: [RFC6234], [RFC4648], this document. 444 * Status: standard 446 If other digest-algorithm values are defined, the associated encoding 447 MUST either be represented as a quoted string, or MUST NOT include 448 ";" or "," in the character sets used for the encoding. 450 6. Use of Digest when acting on resources 452 POST and PATCH requests can appear to convey partial representations 453 but are semantically acting on resources. The enclosed 454 representation, including its metadata refers to that action. 456 In these requests the representation digest MUST be computed on the 457 representation-data of that action. This is the only possible choice 458 because representation digest requires complete representation 459 metadata (see Section 2). 461 In responses, 463 o if the representation describes the status of the request, 464 "Digest" MUST be computed on the enclosed representation (see 465 Section 9.8 ); 467 o if there is a referenced resource "Digest" MUST be computed on the 468 selected representation of the referenced resource even if that is 469 different from the target resource. That might or might not 470 result in computing "Digest" on the enclosed representation. 472 The latter case might be done according to the HTTP semantics of the 473 given method, for example using the "Content-Location" header field. 474 In contrast, the "Location" header field does not affect "Digest" 475 because it is not representation metadata. 477 6.1. Digest and PATCH 479 In PATCH requests the representation digest MUST be computed on the 480 patch document because the representation metadata refers to the 481 patch document and not to the target resource (see Section 2 of 482 [RFC5789]). 484 In PATCH responses the representation digest MUST be computed on the 485 selected representation of the patched resource. 487 "Digest" usage with PATCH is thus very similar to the POST one, but 488 with the resource's own semantic partly implied by the method and by 489 the patch document. 491 7. Deprecate Negotiation of Content-MD5 493 This RFC deprecates the negotiation of Content-MD5 as it has been 494 obsoleted by [RFC7231]. 496 8. Relationship to Subresource Integrity (SRI) 498 Subresource Integrity [SRI] is an integrity mechanism that shares 499 some similarities to the present document's mechanism. However, 500 there are differences in motivating factors, threat model and 501 specification of integrity digest generation, signalling and 502 validation. 504 SRI allows a first-party authority to declare an integrity assertion 505 on a resource served by a first or third party authority. This is 506 done via the "integrity" attribute that can be added to "script" or 507 "link" HTML elements. Therefore, the integrity assertion is always 508 made out-of-band to the resource fetch. In contrast, the "Digest" 509 header field is supplied in-band alongside the selected 510 representation, meaning that an authority can only declare an 511 integrity assertion for itself. Methods to improve the security 512 properties of representation digests are presented in Section 11. 513 This contrast is interesting because on one hand self-assertion is 514 less likely to be affected by coordination problems such as the 515 first-party holding stale information about the third party, but on 516 the other hand the self-assertion is only as trustworthy as the 517 authority that provided it. 519 The SRI "integrity" attribute contains a cryptographic hash algorithm 520 and digest value which is similar to "representation-data-digest" 521 (see Section 2). The major differences are in serialization format. 523 The SRI digest value is calculated over the identity encoding of the 524 resource, not the selected representation (as specified for 525 "representation-data-digest" in this document). Section 3.4.5 of 526 [SRI] describes the benefit of the identity approach - the SRI 527 "integrity" attribute can contain multiple algorithm-value pairs 528 where each applies to a different identity encoded payload. This 529 allows for protection of distinct resources sharing a URL. However, 530 this is a contrast to the design of representation digests, where 531 multiple "Digest" field-values all protect the same representation. 533 SRI does not specify handling of partial representation data (e.g. 534 Range requests). In contrast, this document specifies handling in 535 terms that are fully compatible with core HTTP concepts (an example 536 is provided in Section 9.3). 538 SRI specifies strong requirements on the selection of algorithm for 539 generation and validation of digests. In contrast, the requirements 540 in this document are weaker. 542 SRI defines no method for a client to declare an integrity assertion 543 on resources it transfers to a server. In contrast, the "Digest" 544 header field can appear on requests. 546 8.1. Supporting Both SRI and Representation Digest 548 The SRI and Representation Digest mechanisms are different and 549 complementary but one is not capable of replacing the other because 550 they have different threat, security and implementation properties. 552 A user agent that supports both mechanisms is expected to apply the 553 rules specified for each but since the two mechanisms are 554 independent, the ordering is not important. However, a user agent 555 supporting both could benefit from performing representation digest 556 validation first because it does not always require a conversion into 557 identity encoding. 559 There is a chance that a user agent supporting both mechanisms may 560 find one validates successfully while the other fails. This document 561 specifies no requirements or guidance for user agents that experience 562 such cases. 564 9. Examples of Unsolicited Digest 566 The following examples demonstrate interactions where a server 567 responds with a "Digest" header field even though the client did not 568 solicit one using "Want-Digest". 570 9.1. Server Returns Full Representation Data 572 Request: 574 GET /items/123 576 Response: 578 HTTP/1.1 200 OK 579 Content-Type: application/json 580 Content-Encoding: identity 581 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 583 {"hello": "world"} 585 9.2. Server Returns No Representation Data 587 As there is no content coding applied, the "sha-256" and the "id-sha- 588 256" digest-values are the same. 590 Request: 592 HEAD /items/123 594 Response: 596 HTTP/1.1 200 OK 597 Content-Type: application/json 598 Content-Encoding: identity 599 Digest: id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 601 9.3. Server Returns Partial Representation Data 603 Request: 605 GET /items/123 606 Range: bytes=1-7 607 Response: 609 HTTP/1.1 206 Partial Content 610 Content-Type: application/json 611 Content-Encoding: identity 612 Content-Range: bytes 1-7/18 613 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 615 "hello" 617 9.4. Client and Server Provide Full Representation Data 619 The request contains a "Digest" header calculated on the enclosed 620 representation. 622 It also includes an "Accept-Encoding: br" header field that 623 advertises the client supports brotli encoding. 625 The response includes a "Content-Encoding: br" that indicates the 626 selected representation is brotli encoded. The "Digest" field-value 627 is therefore different compared to the request. 629 The response body is displayed as a base64-encoded string because it 630 contains non-printable characters. 632 Request: 634 PUT /items/123 635 Content-Type: application/json 636 Content-Encoding: identity 637 Accept-Encoding: br 638 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 640 {"hello": "world"} 642 Response: 644 Content-Type: application/json 645 Content-Encoding: br 646 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 648 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 650 9.5. Client Provides Full Representation Data, Server Provides No 651 Representation Data 653 Request "Digest" value is calculated on the enclosed payload. 654 Response "Digest" value depends on the representation metadata header 655 fields, including "Content-Encoding: br" even when the response does 656 not contain a payload body. 658 Request: 660 PUT /items/123 661 Content-Type: application/json 662 Content-Encoding: identity 663 Content-Length: 18 664 Accept-Encoding: br 665 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 667 {"hello": "world"} 669 Response: 671 HTTP/1.1 204 No Content 672 Content-Type: application/json 673 Content-Encoding: br 674 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 676 9.6. Client and Server Provide Full Representation Data, Client Uses 677 id-sha-256. 679 The response contains two digest values: 681 o one with no content coding applied, which in this case 682 accidentally matches the unencoded digest-value sent in the 683 request; 685 o one taking into account the "Content-Encoding". 687 As the response body contains non-printable characters, it is 688 displayed as a base64-encoded string. 690 Request: 692 PUT /items/123 HTTP/1.1 693 Content-Type: application/json 694 Content-Encoding: identity 695 Accept-Encoding: br 696 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 698 {"hello": "world"} 700 Response: 702 HTTP/1.1 200 OK 703 Content-Type: application/json 704 Content-Encoding: br 705 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 706 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 708 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 710 9.7. POST Response does not Reference the Request URI 712 Request "Digest" value is computed on the enclosed representation 713 (see Section 6). 715 The representation enclosed in the response refers to the resource 716 identified by "Content-Location" (see [RFC7231] Section 3.1.4.2 and 717 Section 3.1.4.1 point 4). 719 "Digest" is thus computed on the enclosed representation. 721 Request: 723 POST /books HTTP/1.1 724 Content-Type: application/json 725 Accept: application/json 726 Accept-Encoding: identity 727 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 729 {"title": "New Title"} 731 Response 733 HTTP/1.1 201 Created 734 Content-Type: application/json 735 Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc= 736 Content-Location: /books/123 738 {"id": "123", "title": "New Title"} 739 Note that a "204 No Content" response without a payload body but with 740 the same "Digest" field-value would have been legitimate too. 742 9.8. POST Response Describes the Request Status 744 Request "Digest" value is computed on the enclosed representation 745 (see Section 6). 747 The representation enclosed in the response describes the status of 748 the request, so "Digest" is computed on that enclosed representation. 750 Response "Digest" has no explicit relation with the resource 751 referenced by "Location". 753 Request: 755 POST /books HTTP/1.1 756 Content-Type: application/json 757 Accept: application/json 758 Accept-Encoding: identity 759 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 760 Location: /books/123 762 {"title": "New Title"} 764 Response 766 HTTP/1.1 201 Created 767 Content-Type: application/json 768 Digest: id-sha-256=0o/WKwSfnmIoSlop2LV/ISaBDth05IeW27zzNMUh5l8= 769 Location: /books/123 771 { 772 "status": "created", 773 "id": "123", 774 "ts": 1569327729, 775 "instance": "/books/123" 776 } 778 9.9. Digest with PATCH 780 This case is analogous to a POST request where the target resource 781 reflects the effective request URI. 783 The PATCH request uses the "application/merge-patch+json" media type 784 defined in [RFC7396]. 786 "Digest" is calculated on the enclosed payload, which corresponds to 787 the patch document. 789 The response "Digest" is computed on the complete representation of 790 the patched resource. 792 Request: 794 PATCH /books/123 HTTP/1.1 795 Content-Type: application/merge-patch+json 796 Accept: application/json 797 Accept-Encoding: identity 798 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 800 {"title": "New Title"} 802 Response: 804 HTTP/1.1 200 OK 805 Content-Type: application/json 806 Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc= 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.10. Error responses 815 In error responses, the representation-data does not necessarily 816 refer to the target resource. Instead it refers to the 817 representation of the error. 819 In the following example a client attempts to patch the resource 820 located at /books/123. However, the resource does not exist and the 821 server generates a 404 response with a body that describes the error 822 in accordance with [RFC7807]. 824 The digest of the response is computed on this enclosed 825 representation. 827 Request: 829 PATCH /books/123 HTTP/1.1 830 Content-Type: application/merge-patch+json 831 Accept: application/json 832 Accept-Encoding: identity 833 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 835 {"title": "New Title"} 837 Response: 839 HTTP/1.1 404 Not Found 840 Content-Type: application/problem+json 841 Digest: sha-256=UJSojgEzqUe4UoHzmNl5d2xkmrW3BOdmvsvWu1uFeu0= 843 { 844 "title": "Not Found", 845 "detail": "Cannot PATCH a non-existent resource", 846 "status": 404 847 } 849 10. Examples of Want-Digest Solicited Digest 851 The following examples demonstrate interactions where a client 852 solicits a "Digest" using "Want-Digest". 854 10.1. Server Selects Client's Least Preferred Algorithm 856 The client requests a digest, preferring sha. The server is free to 857 reply with sha-256 anyway. 859 Request: 861 GET /items/123 HTTP/1.1 862 Want-Digest: sha-256;q=0.3, sha;q=1 864 Response: 866 HTTP/1.1 200 OK 867 Content-Type: application/json 868 Content-Encoding: identity 869 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 871 {"hello": "world"} 873 10.2. Server Selects Algorithm Unsupported by Client 875 The client requests a sha digest only. The server is currently free 876 to reply with a Digest containing an unsupported algorithm. 878 Request: 880 GET /items/123 881 Want-Digest: sha;q=1 883 Response: 885 HTTP/1.1 200 OK 886 Content-Type: application/json 887 Content-Encoding: identity 888 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 889 +AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 891 {"hello": "world"} 893 10.3. Server Does Not Support Client Algorithm and Returns an Error 895 The client requests a sha Digest, the server advises for sha-256 and 896 sha-512 898 Request: 900 GET /items/123 901 Want-Digest: sha;q=1 903 Response: 905 HTTP/1.1 400 Bad Request 906 Want-Digest: sha-256, sha-512 908 11. Security Considerations 910 11.1. Digest Does Not Protect the Full HTTP Message 912 This document specifies a data integrity mechanism that protects HTTP 913 "representation data", but not HTTP "representation metadata" header 914 fields, from certain kinds of accidental corruption. 916 "Digest" is not intended as general protection against malicious 917 tampering with HTTP messages, this can be achieved by combining it 918 with other approaches such as transport-layer security or digital 919 signatures. 921 11.2. Broken Cryptographic Algorithms 923 Cryptographic algorithms are intended to provide a proof of integrity 924 suited towards cryptographic constructions such as signatures. 926 However, these rely on collision-resistance for their security proofs 927 [CMU-836068]. The MD5 and SHA-1 algorithms are vulnerable to 928 collisions attacks, so MD5 MUST NOT be used and SHA-1 is NOT 929 RECOMMENDED for use with "Digest". 931 11.3. Other Deprecated Algorithms 933 The ADLER32 algorithm defined in [RFC1950] has been deprecated by 934 [RFC3309] because under certain conditions it provides weak detection 935 of errors and is now NOT RECOMMENDED for use with "Digest". 937 11.4. Digest for End-to-End Integrity 939 "Digest" alone does not provide end-to-end integrity of HTTP messages 940 over multiple hops, as it just covers the "representation data" and 941 not the "representation metadata". 943 Besides, it allows to protect "representation data" from buggy 944 manipulation, buggy compression, etc. 946 Moreover identity digest algorithms (eg. ID-SHA-256 and ID-SHA-512) 947 allow piecing together a resource from different sources (e.g. 948 different servers that perhaps apply different content codings) 949 enabling the user-agent to detect that the application-layer tasks 950 completed properly, before handing off to say the HTML parser, video 951 player etc. 953 Even a simple mechanism for end-to-end validation is thus valuable. 955 11.5. Digest and Content-Location in responses 957 When a state-changing method returns the "Content-Location" header 958 field, the enclosed representation refers to the resource identified 959 by its value and "Digest" is computed accordingly. 961 11.6. Usage in signatures 963 Digital signatures are widely used together with checksums to provide 964 the certain identification of the origin of a message [NIST800-32]. 966 Such signatures can protect one or more header fields and there are 967 additional considerations when "Digest" is included in this set. 969 Since the "Digest" header field is a hash of a resource 970 representation, it explicitly depends on the "representation 971 metadata" (eg. the values of "Content-Type", "Content-Encoding" etc). 972 A signature that protects "Digest" but not other "representation 973 metadata" can expose the communication to tampering. For example, an 974 actor could manipulate the "Content-Type" field-value and cause a 975 digest validation failure at the recipient, preventing the 976 application from accessing the representation. Such an attack 977 consumes the resources of both endpoints. See also Section 11.5. 979 "Digest" SHOULD always be used over a connection which provides 980 integrity at the transport layer that protects HTTP header fields. 982 A "Digest" header field using NOT RECOMMENDED digest-algorithms 983 SHOULD NOT be used in signatures. 985 11.7. Message Truncation 987 ... 989 11.8. Algorithm Agility 991 ... 993 12. IANA Considerations 995 12.1. Establish the HTTP Digest Algorithm Values 997 This memo sets this spec to be the establishing document for the HTTP 998 Digest Algorithm Values [4] 1000 12.2. The "status" Field in the HTTP Digest Algorithm Values 1002 This memo adds the field "Status" to the HTTP Digest Algorithm Values 1003 [5] registry. The allowed values for the "Status" fields are 1004 described below. 1006 Status Specify "standard", "experimental", "historic", "obsoleted", 1007 or "deprecated" according to the type and status of the primary 1008 document in which the algorithm is defined. 1010 12.3. Deprecate "MD5" Digest Algorithm 1012 This memo updates the "MD5" digest algorithm in the HTTP Digest 1013 Algorithm Values [6] registry: 1015 o Digest Algorithm: MD5 1017 o Description: As specified in Section 5. 1019 o Status: As specified in Section 5. 1021 12.4. Update "CRC32C" Digest Algorithm 1023 This memo updates the "CRC32c" digest algorithm in the HTTP Digest 1024 Algorithm Values [7] registry: 1026 o Digest Algorithm: CRC32c 1028 o Description: The CRC32c algorithm is a 32-bit cyclic redundancy 1029 check. It achieves a better hamming distance (for better error- 1030 detection performance) than many other 32-bit CRC functions. 1031 Other places it is used include iSCSI and SCTP. The 32-bit output 1032 is encoded in hexadecimal (using between 1 and 8 ASCII characters 1033 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 1034 CRC32c=0a72a4df and crc32c=A72A4DF are both valid checksums for 1035 the 3-byte message "dog". 1037 o Reference: [RFC4960] appendix B, this document. 1039 o Status: standard. 1041 12.5. Obsolete "SHA" Digest Algorithm 1043 This memo updates the "SHA" digest algorithm in the HTTP Digest 1044 Algorithm Values [8] registry: 1046 o Digest Algorithm: SHA 1048 o Description: As specified in Section 5. 1050 o Status: As specified in Section 5. 1052 12.6. Obsolete "ADLER32" Digest Algorithm 1054 This memo updates the "ADLER32" digest algorithm in the HTTP Digest 1055 Algorithm Values [9] registry: 1057 o Digest Algorithm: ADLER32 1058 o Description: The ADLER32 algorithm is a checksum specified in 1059 [RFC1950] "ZLIB Compressed Data Format". The 32-bit output is 1060 encoded in hexadecimal (using between 1 and 8 ASCII characters 1061 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 1062 ADLER32=03da0195 and ADLER32=3DA0195 are both valid checksums for 1063 the 4-byte message "Wiki". This algorithm is obsoleted and SHOULD 1064 NOT be used. 1066 o Status: obsoleted 1068 12.7. The "ID-SHA-256" Digest Algorithm 1070 This memo registers the "ID-SHA-256" digest algorithm in the HTTP 1071 Digest Algorithm Values [10] registry: 1073 o Digest Algorithm: ID-SHA-256 1075 o Description: As specified in Section 5. 1077 o Status: As specified in Section 5. 1079 12.8. The "ID-SHA-512" Digest Algorithm 1081 This memo registers the "ID-SHA-512" digest algorithm in the HTTP 1082 Digest Algorithm Values [11] registry: 1084 o Digest Algorithm: ID-SHA-512 1086 o Description: As specified in Section 5. 1088 o Status: As specified in Section 5. 1090 12.9. Changes compared to RFC5843 1092 The status of "MD5" has been updated to "deprecated", and its 1093 description states that this algorithm MUST NOT be used. 1095 The status of "SHA" has been updated to "obsoleted", and its 1096 description states that this algorithm is NOT RECOMMENDED. 1098 The status for "CRC32C" has been updated to "standard". 1100 The "ID-SHA-256" and "ID-SHA-512" algorithms have been added to the 1101 registry. 1103 12.10. Want-Digest Header Field Registration 1105 This section registers the "Want-Digest" header field in the 1106 "Permanent Message Header Field Names" registry ([RFC3864]). 1108 Header field name: "Want-Digest" 1110 Applicable protocol: http 1112 Status: standard 1114 Author/Change controller: IETF 1116 Specification document(s): Section 4 of this document 1118 12.11. Digest Header Field Registration 1120 This section registers the "Digest" header field in the "Permanent 1121 Message Header Field Names" registry ([RFC3864]). 1123 Header field name: "Digest" 1125 Applicable protocol: http 1127 Status: standard 1129 Author/Change controller: IETF 1131 Specification document(s): Section 3 of this document 1133 13. References 1135 13.1. Normative References 1137 [CMU-836068] 1138 Carnagie Mellon University, Software Engineering 1139 Institute, "MD5 Vulnerable to collision attacks", December 1140 2008, . 1142 [IACR-2019-459] 1143 Leurent, G. and T. Peyrin, "From Collisions to Chosen- 1144 Prefix Collisions Application to Full SHA-1", May 2019, 1145 . 1147 [NIST800-32] 1148 National Institute of Standards and Technology, U.S. 1149 Department of Commerce, "Introduction to Public Key 1150 Technology and the Federal PKI Infrastructure", February 1151 2001, . 1154 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 1155 DOI 10.17487/RFC1321, April 1992, 1156 . 1158 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 1159 Specification version 3.3", RFC 1950, 1160 DOI 10.17487/RFC1950, May 1996, 1161 . 1163 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1164 Requirement Levels", BCP 14, RFC 2119, 1165 DOI 10.17487/RFC2119, March 1997, 1166 . 1168 [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 1169 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, 1170 . 1172 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 1173 RFC 3230, DOI 10.17487/RFC3230, January 2002, 1174 . 1176 [RFC3309] Stone, J., Stewart, R., and D. Otis, "Stream Control 1177 Transmission Protocol (SCTP) Checksum Change", RFC 3309, 1178 DOI 10.17487/RFC3309, September 2002, 1179 . 1181 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1182 Procedures for Message Header Fields", BCP 90, RFC 3864, 1183 DOI 10.17487/RFC3864, September 2004, 1184 . 1186 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1187 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1188 . 1190 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1191 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1192 . 1194 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1195 Specifications: ABNF", STD 68, RFC 5234, 1196 DOI 10.17487/RFC5234, January 2008, 1197 . 1199 [RFC5843] Bryan, A., "Additional Hash Algorithms for HTTP Instance 1200 Digests", RFC 5843, DOI 10.17487/RFC5843, April 2010, 1201 . 1203 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 1204 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 1205 DOI 10.17487/RFC6234, May 2011, 1206 . 1208 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1209 Protocol (HTTP/1.1): Message Syntax and Routing", 1210 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1211 . 1213 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1214 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1215 DOI 10.17487/RFC7231, June 2014, 1216 . 1218 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 1219 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 1220 RFC 7233, DOI 10.17487/RFC7233, June 2014, 1221 . 1223 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 1224 RFC 7405, DOI 10.17487/RFC7405, December 2014, 1225 . 1227 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1228 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1229 May 2017, . 1231 [UNIX] The Open Group, "The Single UNIX Specification, Version 2 1232 - 6 Vol Set for UNIX 98", February 1997. 1234 13.2. Informative References 1236 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 1237 DOI 10.17487/RFC2818, May 2000, 1238 . 1240 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1241 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1242 . 1244 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 1245 DOI 10.17487/RFC7396, October 2014, 1246 . 1248 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 1249 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 1250 . 1252 [SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger, 1253 "Subresource Integrity", W3C Recommendation REC-SRI- 1254 20160623, June 2016, 1255 . 1257 13.3. URIs 1259 [1] https://lists.w3.org/Archives/Public/ietf-http-wg/ 1261 [2] https://github.com/httpwg/http-extensions 1263 [3] https://tools.ietf.org/html/rfc7231#section-3.1.2.1 1265 [4] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1267 [5] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1269 [6] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1271 [7] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1273 [8] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1275 [9] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1277 [10] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1279 [11] https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml 1281 Appendix A. Resource Representation and Representation-Data 1283 The following examples show how representation metadata, payload 1284 transformations and method impacts on the message and payload body. 1285 When the payload body contains non-printable characters (eg. when it 1286 is compressed) it is shown as base64-encoded string. 1288 Here is a gzip-compressed json object 1290 Request: 1292 PUT /entries/1234 HTTP/1.1 1293 Content-Type: application/json 1294 Content-Encoding: gzip 1296 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 1298 Now the same payload body conveys a malformed json object. 1300 Request: 1302 PUT /entries/1234 HTTP/1.1 1303 Content-Type: application/json 1305 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 1307 A Range-Request alters the payload body, conveying a partial 1308 representation. 1310 Request: 1312 GET /entries/1234 HTTP/1.1 1313 Range: bytes=1-7 1315 Response: 1317 HTTP/1.1 206 Partial Content 1318 Content-Encoding: gzip 1319 Content-Type: application/json 1320 Content-Range: bytes 1-7/18 1322 iwgAla3RXA== 1324 Now the method too alters the payload body. 1326 Request: 1328 HEAD /entries/1234 HTTP/1.1 1329 Accept: application/json 1330 Accept-Encoding: gzip 1332 Response: 1334 HTTP/1.1 200 OK 1335 Content-Type: application/json 1336 Content-Encoding: gzip 1338 Finally the semantics of an HTTP response might decouple the 1339 effective request URI from the enclosed representation. In the 1340 example response below, the "Content-Location" header field indicates 1341 that the enclosed representation refers to the resource available at 1342 "/authors/123". 1344 Request: 1346 POST /authors/ HTTP/1.1 1347 Accept: application/json 1348 Content-Type: application/json 1350 {"author": "Camilleri"} 1352 Response: 1354 HTTP/1.1 201 Created 1355 Content-Type: application/json 1356 Content-Location: /authors/123 1357 Location: /authors/123 1359 {"id": "123", "author": "Camilleri"} 1361 Appendix B. FAQ 1363 1. Why remove all references to content-md5? 1365 Those were unnecessary to understanding and using this spec. 1367 2. Why remove references to instance manipulation? 1369 Those were unnecessary for correctly using and applying the spec. 1370 An example with Range Request is more than enough. This doc uses 1371 the term "partial representation" which should group all those 1372 cases. 1374 3. How to use "Digest" with "PATCH" method? 1376 See Section 6. 1378 4. Why remove references to delta-encoding? 1379 Unnecessary for a correct implementation of this spec. The 1380 revised spec can be nicely adapted to "delta encoding", but all 1381 the references here to delta encoding don't add anything to this 1382 RFC. Another job would be to refresh delta encoding. 1384 5. Why remove references to Digest Authentication? 1386 This RFC seems to me completely unrelated to Digest 1387 Authentication but for the word "Digest". 1389 6. What changes in "Want-Digest"? 1391 We allow to use the "Want-Digest" in responses to advertise the 1392 supported digest-algorithms and the inability to accept requests 1393 with unsupported digest-algorithms. 1395 7. Does this spec changes supported algorithms? 1397 This RFC updates [RFC5843] which is still delegated for all 1398 algorithms updates, and adds two more algorithms: ID-SHA-256 and 1399 ID-SHA-512 which allows to send a checksum of a resource 1400 representation with no content codings applied. 1402 Acknowledgements 1404 The vast majority of this document is inherited from [RFC3230], so 1405 thanks to J. Mogul and A. Van Hoff for their great work. The 1406 original idea of refreshing this document arose from an interesting 1407 discussion with M. Nottingham, J. Yasskin and M. Thomson when 1408 reviewing the MICE content coding. 1410 Code Samples 1412 _RFC Editor: Please remove this section before publication._ 1414 How can I generate and validate the Digest values shown in the 1415 examples throughout this document? 1417 The following python3 code can be used to generate digests for json 1418 objects using SHA algorithms for a range of encodings. Note that 1419 these are formatted as base64. This function could be adapted to 1420 other algorithms and should take into account their specific 1421 formatting rules. 1423 import base64, json, hashlib, brotli 1425 def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): 1426 json_bytes = json.dumps(item).encode() 1427 content_encoded = encoding(json_bytes) 1428 checksum_bytes = algorithm(content_encoded).digest() 1429 return base64.encodebytes(checksum_bytes).strip() 1431 item = {"hello": "world"} 1433 print("Encoding | digest-algorithm | digest-value") 1434 print("Identity | sha256 |", digest(item)) 1435 # Encoding | digest-algorithm | digest-value 1436 # Identity | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1438 print("Encoding | digest-algorithm | digest-value") 1439 print("Brotli | sha256 |", digest(item, encoding=brotli.compress)) 1440 # Encoding | digest-algorithm | digest-value 1441 # Brotli , sha256 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1443 print("Encoding | digest-algorithm | digest-value") 1444 print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512)) 1445 # Encoding | digest-algorithm | digest-value 1446 # Identity | sha512 | b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2s 1447 vX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==\n' 1449 Changes 1451 _RFC Editor: Please remove this section before publication._ 1453 E.1. Since draft-ietf-httpbis-digest-headers-00 1455 o Align title with document name 1457 o Add id-sha-* algorithm examples #880 1459 o Reference [RFC6234] and [RFC3174] instead of FIPS-1 1461 o Deprecate MD5 1463 o Obsolete ADLER-32 but don't forbid it #828 1465 o Update CRC32C value in IANA table #828 1467 o Use when acting on resources (POST, PATCH) #853 1468 o Added Relationship with SRI, draft Use Cases #868, #971 1470 o Warn about the implications of "Content-Location" 1472 E.2. Since draft-ietf-httpbis-digest-headers-01 1474 o Digest of error responses is computed on the error representation- 1475 data #1004 1477 o Effect of HTTP semantics on payload and message body moved to 1478 appendix #1122 1480 o Editorial refactoring, moving headers sections up. #1109-#1112, 1481 #1116, #1117, #1122-#1124 1483 Authors' Addresses 1485 Roberto Polli 1486 Team Digitale, Italian Government 1488 Email: robipolli@gmail.com 1490 Lucas Pardue 1491 Cloudflare 1493 Email: lucaspardue.24.7@gmail.com