idnits 2.17.1 draft-ietf-httpbis-digest-headers-04.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: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- 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 (17 October 2020) is 1287 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'CMU-836068' -- Possible downref: Non-RFC (?) normative reference: ref. 'IACR-2020-014' -- Possible downref: Non-RFC (?) normative reference: ref. 'NIST800-32' ** Downref: Normative reference to an Informational RFC: RFC 1321 ** Downref: Normative reference to an Informational RFC: RFC 1950 ** Downref: Normative reference to an Informational RFC: RFC 3174 ** Obsolete normative reference: RFC 3230 (Obsoleted by RFC 9530) ** Obsolete normative reference: RFC 3309 (Obsoleted by RFC 4960) ** Obsolete normative reference: RFC 4960 (Obsoleted by RFC 9260) ** Downref: Normative reference to an Informational RFC: RFC 5843 ** Downref: Normative reference to an Informational RFC: RFC 6234 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-12 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNIX' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-12 -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7807 (Obsoleted by RFC 9457) Summary: 8 errors (**), 0 flaws (~~), 5 warnings (==), 11 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: 20 April 2021 Cloudflare 6 17 October 2020 8 Digest Headers 9 draft-ietf-httpbis-digest-headers-04 11 Abstract 13 This document defines the HTTP Digest and Want-Digest fields, thus 14 allowing client and server to negotiate an integrity checksum of the 15 exchanged resource representation data. 17 This document obsoletes RFC 3230. It replaces the term "instance" 18 with "representation", which makes it consistent with the HTTP 19 Semantic and Context defined in draft-ietf-httpbis-semantics. 21 Note to Readers 23 _RFC EDITOR: please remove this section before publication_ 25 Discussion of this draft takes place on the HTTP working group 26 mailing list (ietf-http-wg@w3.org), which is archived at 27 https://lists.w3.org/Archives/Public/ietf-http-wg/ 28 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 30 The source code and issues list for this draft can be found at 31 https://github.com/httpwg/http-extensions (https://github.com/httpwg/ 32 http-extensions). 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on 20 April 2021. 50 Copyright Notice 52 Copyright (c) 2020 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 57 license-info) in effect on the date of publication of this document. 58 Please review these documents carefully, as they describe your rights 59 and restrictions with respect to this document. Code Components 60 extracted from this document must include Simplified BSD License text 61 as described in Section 4.e of the Trust Legal Provisions and are 62 provided without warranty as described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 67 1.1. A Brief History of HTTP Integrity Fields . . . . . . . . 4 68 1.2. This Proposal . . . . . . . . . . . . . . . . . . . . . . 4 69 1.3. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 5 71 2. Representation Digest . . . . . . . . . . . . . . . . . . . . 6 72 3. The Digest Field . . . . . . . . . . . . . . . . . . . . . . 7 73 4. The Want-Digest Field . . . . . . . . . . . . . . . . . . . . 7 74 5. Digest Algorithm Values . . . . . . . . . . . . . . . . . . . 8 75 6. Use of Digest when acting on resources . . . . . . . . . . . 10 76 6.1. Digest and PATCH . . . . . . . . . . . . . . . . . . . . 11 77 7. Deprecate Negotiation of Content-MD5 . . . . . . . . . . . . 11 78 8. Obsolete Digest Header Field Parameters . . . . . . . . . . . 11 79 9. Relationship to Subresource Integrity (SRI) . . . . . . . . . 11 80 9.1. Supporting Both SRI and Representation Digest . . . . . . 12 81 10. Examples of Unsolicited Digest . . . . . . . . . . . . . . . 13 82 10.1. Server Returns Full Representation Data . . . . . . . . 13 83 10.2. Server Returns No Representation Data . . . . . . . . . 13 84 10.3. Server Returns Partial Representation Data . . . . . . . 14 85 10.4. Client and Server Provide Full Representation Data . . . 14 86 10.5. Client Provides Full Representation Data, Server Provides 87 No Representation Data . . . . . . . . . . . . . . . . 15 88 10.6. Client and Server Provide Full Representation Data, Client 89 Uses id-sha-256. . . . . . . . . . . . . . . . . . . . 15 90 10.7. POST Response does not Reference the Request URI . . . . 16 91 10.8. POST Response Describes the Request Status . . . . . . . 17 92 10.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . 17 93 10.10. Error responses . . . . . . . . . . . . . . . . . . . . 18 94 10.11. Use with trailers and transfer coding . . . . . . . . . 19 95 11. Examples of Want-Digest Solicited Digest . . . . . . . . . . 19 96 11.1. Server Selects Client's Least Preferred Algorithm . . . 20 97 11.2. Server Selects Algorithm Unsupported by Client . . . . . 20 98 11.3. Server Does Not Support Client Algorithm and Returns an 99 Error . . . . . . . . . . . . . . . . . . . . . . . . . 20 100 12. Security Considerations . . . . . . . . . . . . . . . . . . . 21 101 12.1. Digest Does Not Protect the Full HTTP Message . . . . . 21 102 12.2. Broken Cryptographic Algorithms . . . . . . . . . . . . 21 103 12.3. Other Deprecated Algorithms . . . . . . . . . . . . . . 21 104 12.4. Digest for End-to-End Integrity . . . . . . . . . . . . 21 105 12.5. Digest and Content-Location in responses . . . . . . . . 22 106 12.6. Usage in signatures . . . . . . . . . . . . . . . . . . 22 107 12.7. Usage in trailers . . . . . . . . . . . . . . . . . . . 22 108 12.8. Usage with encryption . . . . . . . . . . . . . . . . . 23 109 12.9. Algorithm Agility . . . . . . . . . . . . . . . . . . . 23 110 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 111 13.1. Establish the HTTP Digest Algorithm Values . . . . . . . 23 112 13.2. The "status" Field in the HTTP Digest Algorithm 113 Values . . . . . . . . . . . . . . . . . . . . . . . . 23 114 13.3. Deprecate "MD5" Digest Algorithm . . . . . . . . . . . . 24 115 13.4. Update "UNIXsum" Digest Algorithm . . . . . . . . . . . 24 116 13.5. Update "UNIXcksum" Digest Algorithm . . . . . . . . . . 24 117 13.6. Update "CRC32c" Digest Algorithm . . . . . . . . . . . . 25 118 13.7. Deprecate "SHA" Digest Algorithm . . . . . . . . . . . . 25 119 13.8. Obsolete "ADLER32" Digest Algorithm . . . . . . . . . . 25 120 13.9. Obsolete "contentMD5" token in Digest Algorithm . . . . 26 121 13.10. The "id-sha-256" Digest Algorithm . . . . . . . . . . . 26 122 13.11. The "id-sha-512" Digest Algorithm . . . . . . . . . . . 26 123 13.12. Changes compared to RFC5843 . . . . . . . . . . . . . . 26 124 13.13. Want-Digest Field Registration . . . . . . . . . . . . . 27 125 13.14. Digest Header Field Registration . . . . . . . . . . . . 27 126 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 127 14.1. Normative References . . . . . . . . . . . . . . . . . . 27 128 14.2. Informative References . . . . . . . . . . . . . . . . . 29 129 Appendix A. Resource Representation and Representation-Data . . 30 130 Appendix B. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 32 131 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 34 132 Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 34 133 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 134 Since draft-ietf-httpbis-digest-headers-03 . . . . . . . . . . 35 135 Since draft-ietf-httpbis-digest-headers-02 . . . . . . . . . . 35 136 Since draft-ietf-httpbis-digest-headers-01 . . . . . . . . . . 36 137 Since draft-ietf-httpbis-digest-headers-00 . . . . . . . . . . 36 138 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 140 1. Introduction 142 The core specification of HTTP does not define a means to protect the 143 integrity of resources. When HTTP messages are transferred between 144 endpoints, the protocol might choose to make use of features of the 145 lower layer in order to provide some integrity protection; for 146 instance TCP checksums or TLS records [RFC2818]. 148 However, there are cases where relying on this alone is insufficient. 149 An HTTP-level integrity mechanism that operates independent of 150 transfer can be used to detect programming errors and/or corruption 151 of data at rest, be used across multiple hops in order to provide 152 end-to-end integrity guarantees, aid fault diagnosis across hops and 153 system boundaries, and can be used to validate integrity when 154 reconstructing a resource fetched using different HTTP connections. 156 This document defines a mechanism that acts on HTTP representation- 157 data. It can be combined with other mechanisms that protect 158 representation-metadata, such as digital signatures, in order to 159 protect the desired parts of an HTTP exchange in whole or in part. 161 1.1. A Brief History of HTTP Integrity Fields 163 The Content-MD5 header field was originally introduced to provide 164 integrity, but HTTP/1.1 ([RFC7231], Appendix B) obsoleted it: 166 The Content-MD5 header field has been removed because it was 167 inconsistently implemented with respect to partial responses. 169 [RFC3230] provided a more flexible solution introducing the concept 170 of "instance", and the fields "Digest" and "Want-Digest". 172 1.2. This Proposal 174 The concept of "selected representation" defined in Section 7 of 175 [SEMANTICS] makes [RFC3230] definitions inconsistent with current 176 HTTP semantics. This document updates the "Digest" and "Want-Digest" 177 field definitions to align with [SEMANTICS] concepts. 179 Basing "Digest" on the selected representation makes it 180 straightforward to apply it to use-cases where the transferred data 181 does require some sort of manipulation to be considered a 182 representation, or conveys a partial representation of a resource eg. 183 Range Requests (see Section 13.2 of [SEMANTICS]). 185 Changes are semantically compatible with existing implementations and 186 better cover both the request and response cases. 188 The value of "Digest" is calculated on selected representation, which 189 is tied to the value contained in any "Content-Encoding" or "Content- 190 Type" header fields. Therefore, a given resource may have multiple 191 different digest values. 193 To allow both parties to exchange a Digest of a representation with 194 no content codings (see Section 7.5.1 of [SEMANTICS]) two more 195 digest-algorithms are added ("id-sha-256" and "id-sha-512"). 197 1.3. Goals 199 The goals of this proposal are: 201 1. Digest coverage for either the resource's "representation data" 202 or "selected representation data" communicated via HTTP. 204 2. Support for multiple digest-algorithms. 206 3. Negotiation of the use of digests. 208 The goals do not include: 210 HTTP message integrity: The digest mechanism described here does not 211 cover the full HTTP message nor its semantic, as representation 212 metadata are not included in the checksum. 214 HTTP field integrity: The digest mechanisms described here cover 215 only representation and selected representation data, and do not 216 protect the integrity of associated representation metadata or 217 other message fields. 219 Authentication: The digest mechanisms described here are not meant 220 to support authentication of the source of a digest or of a 221 message or anything else. These mechanisms, therefore, are not a 222 sufficient defense against many kinds of malicious attacks. 224 Privacy: Digest mechanisms do not provide message privacy. 226 Authorization: The digest mechanisms described here are not meant to 227 support authorization or other kinds of access controls. 229 1.4. Notational Conventions 231 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 232 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 233 "OPTIONAL" in this document are to be interpreted as described in BCP 234 14 ([RFC2119] and [RFC8174]) when, and only when, they appear in all 235 capitals, as shown here. 237 This document uses the Augmented BNF defined in [RFC5234] and updated 238 by [RFC7405] along with the "#rule" extension defined in 239 Section 5.7.1 of [SEMANTICS]. 241 The definitions "representation", "selected representation", 242 "representation data", "representation metadata", and "payload body" 243 in this document are to be interpreted as described in [SEMANTICS]. 245 Algorithm names respect the casing used in their definition document 246 (eg. SHA-1, CRC32c) whereas digest-algorithm tokens are quoted (eg. 247 "sha", "crc32c"). 249 2. Representation Digest 251 The representation digest is an integrity mechanism for HTTP 252 resources which uses a checksum that is calculated independently of 253 the payload body (see Section 5.5.4 of [SEMANTICS]). It uses the 254 representation data (see Section 7.2 of [SEMANTICS]), that can be 255 fully or partially contained in the payload body, or not contained at 256 all: 258 representation-data := Content-Encoding( Content-Type( bits ) ) 260 This takes into account the effect of the HTTP semantics on the 261 messages; for example the payload body can be affected by Range 262 Requests or methods such as HEAD, while the way the payload body is 263 transferred "on the wire" is dependent on other transformations (eg. 264 transfer codings for HTTP/1.1 see 6.1 of [HTTP11]): Appendix A 265 contains several examples to help illustrate those effects. 267 A representation digest consists of the value of a checksum computed 268 on the entire selected "representation data" (see Section 7 of 269 [SEMANTICS]) of a resource identified according to Section 5.5.2 of 270 [SEMANTICS] together with an indication of the algorithm used 272 representation-data-digest = digest-algorithm "=" 273 275 The checksum is computed using one of the digest-algorithms listed in 276 Section 5 and then encoded in the associated format. 278 The example below shows the "sha-256" digest-algorithm which uses 279 base64 encoding. 281 sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 283 3. The Digest Field 285 The "Digest" field contains a list of one or more representation 286 digest values as defined in Section 2. It can be used in both 287 request and response. 289 Digest = "Digest" ":" OWS 1#representation-data-digest 291 The relationship between "Content-Location" (see Section 7.8 of 292 [SEMANTICS]) and "Digest" is demonstrated in Section 10.7. A 293 comprehensive set of examples showing the impacts of representation 294 metadata, payload transformations and HTTP methods on Digest is 295 provided in Section 10 and Section 11. 297 A "Digest" field MAY contain multiple representation-data-digest 298 values. For example, a server may provide representation-data-digest 299 values using different algorithms, allowing it to support a 300 population of clients with different evolving capabilities; this is 301 particularly useful in support of transitioning away from weaker 302 algorithms should the need arise (see Section 12.9). 304 A recipient MAY ignore any or all of the representation-data-digests 305 in a Digest field. This allows the recipient to choose which digest- 306 algorithm(s) to use for validation instead of verifying every 307 received representation-data-digest. 309 A sender MAY send a representation-data-digest using a digest- 310 algorithm without knowing whether the recipient supports the digest- 311 algorithm, or even knowing that the recipient will ignore it. 313 "Digest" can be sent in a trailer section. When using incremental 314 digest-algorithms this allows the sender and the receiver to 315 dynamically compute the digest value while streaming the content. 317 Two examples of its use are 319 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 320 AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 322 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 323 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 325 4. The Want-Digest Field 327 The "Want-Digest" field indicates the sender's desire to receive a 328 representation digest on messages associated with the request URI and 329 representation metadata. 331 Want-Digest = "Want-Digest" ":" OWS 1#want-digest-value 332 want-digest-value = digest-algorithm [ ";" "q" "=" qvalue] 333 qvalue = ( "0"  [ "."  0*1DIGIT ] ) / 334   ( "1"  [ "."  0*1( "0" ) ] ) 336 If a digest-algorithm is not accompanied by a "qvalue", it is treated 337 as if its associated "qvalue" were 1.0. 339 The sender is willing to accept a digest-algorithm if and only if it 340 is listed in a "Want-Digest" field of a message, and its "qvalue" is 341 non-zero. 343 If multiple acceptable digest-algorithm values are given, the 344 sender's preferred digest-algorithm is the one (or ones) with the 345 highest "qvalue". 347 Two examples of its use are 349 Want-Digest: sha-256 350 Want-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0 352 5. Digest Algorithm Values 354 Digest-algorithm values are used to indicate a specific digest 355 computation. 357 digest-algorithm = token 359 All digest-algorithm values are case-insensitive but the lower case 360 is preferred. 362 The Internet Assigned Numbers Authority (IANA) acts as a registry for 363 digest-algorithm values. The registry contains the tokens listed 364 below. 366 Some digest-algorithms, although registered, rely on vulnerable 367 algorithms: the "md5" digest-algorithm MUST NOT be used due to 368 collision attacks [CMU-836068] and the "sha" digest-algorithm MUST 369 NOT be used due to collision attacks [IACR-2020-014]. 371 sha-256 372 * Description: The SHA-256 algorithm [RFC6234]. The output of 373 this algorithm is encoded using the base64 encoding [RFC4648]. 375 * Reference: [RFC6234], [RFC4648], this document. 377 * Status: standard 379 sha-512 380 * Description: The SHA-512 algorithm [RFC6234]. The output of 381 this algorithm is encoded using the base64 encoding [RFC4648]. 383 * Reference: [RFC6234], [RFC4648], this document. 385 * Status: standard 387 md5 388 * Description: The MD5 algorithm, as specified in [RFC1321]. The 389 output of this algorithm is encoded using the base64 encoding 390 [RFC4648]. This digest-algorithm MUST NOT be used as it's now 391 vulnerable to collision attacks [CMU-836068]. 393 * Reference: [RFC1321], [RFC4648], this document. 395 * Status: deprecated 397 sha 398 * Description: The SHA-1 algorithm [RFC3174]. The output of this 399 algorithm is encoded using the base64 encoding [RFC4648]. This 400 digest-algorithm MUST NOT be used as it's now vulnerable to 401 collision attacks [IACR-2020-014]. 403 * Reference: [RFC3174], [RFC6234], [RFC4648], this document. 405 * Status: deprecated 407 unixsum 408 * Description: The algorithm computed by the UNIX "sum" command, 409 as defined by the Single UNIX Specification, Version 2 [UNIX]. 410 The output of this algorithm is an ASCII decimal-digit string 411 representing the 16-bit checksum, which is the first word of 412 the output of the UNIX "sum" command. 414 * Reference: [UNIX], this document. 416 * Status: standard 418 unixcksum 419 * Description: The algorithm computed by the UNIX "cksum" 420 command, as defined by the Single UNIX Specification, Version 2 421 [UNIX]. The output of this algorithm is an ASCII digit string 422 representing the 32-bit CRC, which is the first word of the 423 output of the UNIX "cksum" command. 425 * Reference: [UNIX], this document. 427 * Status: standard 429 To allow sender and recipient to provide a checksum which is 430 independent from "Content-Encoding", the following additional digest- 431 algorithms are defined: 433 id-sha-512 434 * Description: The sha-512 digest of the representation-data of 435 the resource when no content coding is applied 437 * Reference: [RFC6234], [RFC4648], this document. 439 * Status: standard 441 id-sha-256 442 * Description: The sha-256 digest of the representation-data of 443 the resource when no content coding is applied 445 * Reference: [RFC6234], [RFC4648], this document. 447 * Status: standard 449 If other digest-algorithm values are defined, the associated encoding 450 MUST either be represented as a quoted string, or MUST NOT include 451 ";" or "," in the character sets used for the encoding. 453 6. Use of Digest when acting on resources 455 POST and PATCH requests can appear to convey partial representations 456 but are semantically acting on resources. The enclosed 457 representation, including its metadata refers to that action. 459 In these requests the representation digest MUST be computed on the 460 representation-data of that action. This is the only possible choice 461 because representation digest requires complete representation 462 metadata (see Section 2). 464 In responses, 466 * if the representation describes the status of the request, 467 "Digest" MUST be computed on the enclosed representation (see 468 Section 10.8 ); 470 * if there is a referenced resource "Digest" MUST be computed on the 471 selected representation of the referenced resource even if that is 472 different from the target resource. That might or might not 473 result in computing "Digest" on the enclosed representation. 475 The latter case might be done according to the HTTP semantics of the 476 given method, for example using the "Content-Location" header field. 477 In contrast, the "Location" header field does not affect "Digest" 478 because it is not representation metadata. 480 6.1. Digest and PATCH 482 In PATCH requests the representation digest MUST be computed on the 483 patch document because the representation metadata refers to the 484 patch document and not to the target resource (see Section 2 of 485 [RFC5789]). 487 In PATCH responses the representation digest MUST be computed on the 488 selected representation of the patched resource. 490 "Digest" usage with PATCH is thus very similar to the POST one, but 491 with the resource's own semantic partly implied by the method and by 492 the patch document. 494 7. Deprecate Negotiation of Content-MD5 496 This RFC deprecates the negotiation of Content-MD5 as it has been 497 obsoleted by [RFC7231]. The "contentMD5" token defined in Section 5 498 of [RFC3230] MUST NOT be used as a digest-algorithm. 500 8. Obsolete Digest Header Field Parameters 502 This document obsoletes the usage of parameters with "Digest" 503 introduced in Section 4.1.1 and 4.2 of [RFC3230] because this feature 504 has not been widely deployed and complicates field-value processing. 506 Field parameters provided a common way to attach additional 507 information to a representation-data-digest, but if they are used as 508 an input to validate the checksum, an attacker could alter them to 509 steer the validation behavior. 511 A digest-algorithm can still be parameterized defining its own way to 512 encode parameters into the representation-data-digest in such a way 513 as to mitigate security risks related to its computation. 515 9. Relationship to Subresource Integrity (SRI) 517 Subresource Integrity [SRI] is an integrity mechanism that shares 518 some similarities to the present document's mechanism. However, 519 there are differences in motivating factors, threat model and 520 specification of integrity digest generation, signalling and 521 validation. 523 SRI allows a first-party authority to declare an integrity assertion 524 on a resource served by a first or third party authority. This is 525 done via the "integrity" attribute that can be added to "script" or 526 "link" HTML elements. Therefore, the integrity assertion is always 527 made out-of-band to the resource fetch. In contrast, the "Digest" 528 field is supplied in-band alongside the selected representation, 529 meaning that an authority can only declare an integrity assertion for 530 itself. Methods to improve the security properties of representation 531 digests are presented in Section 12. This contrast is interesting 532 because on one hand self-assertion is less likely to be affected by 533 coordination problems such as the first-party holding stale 534 information about the third party, but on the other hand the self- 535 assertion is only as trustworthy as the authority that provided it. 537 The SRI "integrity" attribute contains a cryptographic hash algorithm 538 and digest value which is similar to "representation-data-digest" 539 (see Section 2). The major differences are in serialization format. 541 The SRI digest value is calculated over the identity encoding of the 542 resource, not the selected representation (as specified for 543 "representation-data-digest" in this document). Section 3.4.5 of 544 [SRI] describes the benefit of the identity approach - the SRI 545 "integrity" attribute can contain multiple algorithm-value pairs 546 where each applies to a different identity encoded payload. This 547 allows for protection of distinct resources sharing a URL. However, 548 this is a contrast to the design of representation digests, where 549 multiple "Digest" field-values all protect the same representation. 551 SRI does not specify handling of partial representation data (e.g. 552 Range requests). In contrast, this document specifies handling in 553 terms that are fully compatible with core HTTP concepts (an example 554 is provided in Section 10.3). 556 SRI specifies strong requirements on the selection of algorithm for 557 generation and validation of digests. In contrast, the requirements 558 in this document are weaker. 560 SRI defines no method for a client to declare an integrity assertion 561 on resources it transfers to a server. In contrast, the "Digest" 562 field can appear on requests. 564 9.1. Supporting Both SRI and Representation Digest 566 The SRI and Representation Digest mechanisms are different and 567 complementary but one is not capable of replacing the other because 568 they have different threat, security and implementation properties. 570 A user agent that supports both mechanisms is expected to apply the 571 rules specified for each but since the two mechanisms are 572 independent, the ordering is not important. However, a user agent 573 supporting both could benefit from performing representation digest 574 validation first because it does not always require a conversion into 575 identity encoding. 577 There is a chance that a user agent supporting both mechanisms may 578 find one validates successfully while the other fails. This document 579 specifies no requirements or guidance for user agents that experience 580 such cases. 582 10. Examples of Unsolicited Digest 584 The following examples demonstrate interactions where a server 585 responds with a "Digest" field even though the client did not solicit 586 one using "Want-Digest". 588 10.1. Server Returns Full Representation Data 590 Request: 592 GET /items/123 594 Response: 596 HTTP/1.1 200 OK 597 Content-Type: application/json 598 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 600 {"hello": "world"} 602 10.2. Server Returns No Representation Data 604 Requests without a payload body can still send a "Digest" field 605 applying the digest-algorithm to an empty representation. 607 As there is no content coding applied, the "sha-256" and the "id-sha- 608 256" digest-values in the response are the same. 610 Request: 612 HEAD /items/123 HTTP/1.1 613 Digest: sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= 615 Response: 617 HTTP/1.1 200 OK 618 Content-Type: application/json 619 Digest: id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 621 10.3. Server Returns Partial Representation Data 623 Request: 625 GET /items/123 626 Range: bytes=1-7 628 Response: 630 HTTP/1.1 206 Partial Content 631 Content-Type: application/json 632 Content-Range: bytes 1-7/18 633 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 635 "hello" 637 10.4. Client and Server Provide Full Representation Data 639 The request contains a "Digest" field calculated on the enclosed 640 representation. 642 It also includes an "Accept-Encoding: br" header field that 643 advertises the client supports brotli encoding. 645 The response includes a "Content-Encoding: br" that indicates the 646 selected representation is brotli encoded. The "Digest" field-value 647 is therefore different compared to the request. 649 The response body is displayed as a base64-encoded string because it 650 contains non-printable characters. 652 Request: 654 PUT /items/123 655 Content-Type: application/json 656 Accept-Encoding: br 657 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 659 {"hello": "world"} 661 Response: 663 Content-Type: application/json 664 Content-Encoding: br 665 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 667 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 669 10.5. Client Provides Full Representation Data, Server Provides No 670 Representation Data 672 Request "Digest" value is calculated on the enclosed payload. 673 Response "Digest" value depends on the representation metadata header 674 fields, including "Content-Encoding: br" even when the response does 675 not contain a payload body. 677 Request: 679 PUT /items/123 680 Content-Type: application/json 681 Content-Length: 18 682 Accept-Encoding: br 683 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 685 {"hello": "world"} 687 Response: 689 HTTP/1.1 204 No Content 690 Content-Type: application/json 691 Content-Encoding: br 692 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 694 10.6. Client and Server Provide Full Representation Data, Client Uses 695 id-sha-256. 697 The response contains two digest values: 699 * one with no content coding applied, which in this case 700 accidentally matches the unencoded digest-value sent in the 701 request; 703 * one taking into account the "Content-Encoding". 705 As the response body contains non-printable characters, it is 706 displayed as a base64-encoded string. 708 Request: 710 PUT /items/123 HTTP/1.1 711 Content-Type: application/json 712 Accept-Encoding: br 713 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 715 {"hello": "world"} 717 Response: 719 HTTP/1.1 200 OK 720 Content-Type: application/json 721 Content-Encoding: br 722 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 723 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 725 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 727 10.7. POST Response does not Reference the Request URI 729 Request "Digest" value is computed on the enclosed representation 730 (see Section 6). 732 The representation enclosed in the response refers to the resource 733 identified by "Content-Location" (see [SEMANTICS], Section 5.5.2). 735 "Digest" is thus computed on the enclosed representation. 737 Request: 739 POST /books HTTP/1.1 740 Content-Type: application/json 741 Accept: application/json 742 Accept-Encoding: identity 743 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 745 {"title": "New Title"} 747 Response 749 HTTP/1.1 201 Created 750 Content-Type: application/json 751 Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc= 752 Content-Location: /books/123 754 {"id": "123", "title": "New Title"} 756 Note that a "204 No Content" response without a payload body but with 757 the same "Digest" field-value would have been legitimate too. 759 10.8. POST Response Describes the Request Status 761 Request "Digest" value is computed on the enclosed representation 762 (see Section 6). 764 The representation enclosed in the response describes the status of 765 the request, so "Digest" is computed on that enclosed representation. 767 Response "Digest" has no explicit relation with the resource 768 referenced by "Location". 770 Request: 772 POST /books HTTP/1.1 773 Content-Type: application/json 774 Accept: application/json 775 Accept-Encoding: identity 776 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 777 Location: /books/123 779 {"title": "New Title"} 781 Response 783 HTTP/1.1 201 Created 784 Content-Type: application/json 785 Digest: id-sha-256=0o/WKwSfnmIoSlop2LV/ISaBDth05IeW27zzNMUh5l8= 786 Location: /books/123 788 { 789 "status": "created", 790 "id": "123", 791 "ts": 1569327729, 792 "instance": "/books/123" 793 } 795 10.9. Digest with PATCH 797 This case is analogous to a POST request where the target resource 798 reflects the effective request URI. 800 The PATCH request uses the "application/merge-patch+json" media type 801 defined in [RFC7396]. 803 "Digest" is calculated on the enclosed payload, which corresponds to 804 the patch document. 806 The response "Digest" is computed on the complete representation of 807 the patched resource. 809 Request: 811 PATCH /books/123 HTTP/1.1 812 Content-Type: application/merge-patch+json 813 Accept: application/json 814 Accept-Encoding: identity 815 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 817 {"title": "New Title"} 819 Response: 821 HTTP/1.1 200 OK 822 Content-Type: application/json 823 Digest: id-sha-256=BZlF2v0IzjuxN01RQ97EUXriaNNLhtI8Chx8Eq+XYSc= 825 {"id": "123", "title": "New Title"} 827 Note that a "204 No Content" response without a payload body but with 828 the same "Digest" field-value would have been legitimate too. 830 10.10. Error responses 832 In error responses, the representation-data does not necessarily 833 refer to the target resource. Instead it refers to the 834 representation of the error. 836 In the following example a client attempts to patch the resource 837 located at /books/123. However, the resource does not exist and the 838 server generates a 404 response with a body that describes the error 839 in accordance with [RFC7807]. 841 The digest of the response is computed on this enclosed 842 representation. 844 Request: 846 PATCH /books/123 HTTP/1.1 847 Content-Type: application/merge-patch+json 848 Accept: application/json 849 Accept-Encoding: identity 850 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 852 {"title": "New Title"} 853 Response: 855 HTTP/1.1 404 Not Found 856 Content-Type: application/problem+json 857 Digest: sha-256=UJSojgEzqUe4UoHzmNl5d2xkmrW3BOdmvsvWu1uFeu0= 859 { 860 "title": "Not Found", 861 "detail": "Cannot PATCH a non-existent resource", 862 "status": 404 863 } 865 10.11. Use with trailers and transfer coding 867 An origin server sends "Digest" in the HTTP trailer, so it can 868 calculate digest-value while streaming content and thus mitigate 869 resource consumption. The field value is the same as in Section 10.1 870 because "Digest" is designed to be independent from the use of one or 871 more transfer codings (see Section 2). 873 Request: 875 GET /items/123 877 Response: 879 HTTP/1.1 200 OK 880 Content-Type: application/json 881 Transfer-Encoding: chunked 882 Trailer: Digest 884 8\r\n 885 {"hello"\r\n 886 8 887 : "world\r\n 888 2\r\n 889 "}\r\n 890 0\r\n 891 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 893 11. Examples of Want-Digest Solicited Digest 895 The following examples demonstrate interactions where a client 896 solicits a "Digest" using "Want-Digest". 898 11.1. Server Selects Client's Least Preferred Algorithm 900 The client requests a digest, preferring "sha". The server is free 901 to reply with "sha-256" anyway. 903 Request: 905 GET /items/123 HTTP/1.1 906 Want-Digest: sha-256;q=0.3, sha;q=1 908 Response: 910 HTTP/1.1 200 OK 911 Content-Type: application/json 912 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 914 {"hello": "world"} 916 11.2. Server Selects Algorithm Unsupported by Client 918 The client requests a sha digest only. The server is currently free 919 to reply with a Digest containing an unsupported algorithm. 921 Request: 923 GET /items/123 924 Want-Digest: sha;q=1 926 Response: 928 HTTP/1.1 200 OK 929 Content-Type: application/json 930 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 931 +AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 933 {"hello": "world"} 935 11.3. Server Does Not Support Client Algorithm and Returns an Error 937 The client requests a sha Digest, the server advises for sha-256 and 938 sha-512 940 Request: 942 GET /items/123 943 Want-Digest: sha;q=1 945 Response: 947 HTTP/1.1 400 Bad Request 948 Want-Digest: sha-256, sha-512 950 12. Security Considerations 952 12.1. Digest Does Not Protect the Full HTTP Message 954 This document specifies a data integrity mechanism that protects HTTP 955 "representation data", but not HTTP "representation metadata" fields, 956 from certain kinds of accidental corruption. 958 "Digest" is not intended as general protection against malicious 959 tampering with HTTP messages, this can be achieved by combining it 960 with other approaches such as transport-layer security or digital 961 signatures. 963 12.2. Broken Cryptographic Algorithms 965 Cryptographic algorithms are intended to provide a proof of integrity 966 suited towards cryptographic constructions such as signatures. 968 However, these rely on collision-resistance for their security proofs 969 [CMU-836068]. The "md5" and "sha" digest-algorithms are vulnerable 970 to collisions attacks, so they MUST NOT be used with "Digest". 972 12.3. Other Deprecated Algorithms 974 The ADLER32 algorithm defined in [RFC1950] has been deprecated by 975 [RFC3309] because under certain conditions it provides weak detection 976 of errors and is now NOT RECOMMENDED for use with "Digest". 978 12.4. Digest for End-to-End Integrity 980 "Digest" alone does not provide end-to-end integrity of HTTP messages 981 over multiple hops, as it just covers the "representation data" and 982 not the "representation metadata". 984 Besides, it allows to protect "representation data" from buggy 985 manipulation, buggy compression, etc. 987 Moreover identity digest-algorithms (eg. "id-sha-256" and "id-sha- 988 512") allow piecing together a resource from different sources (e.g. 989 different servers that perhaps apply different content codings) 990 enabling the user-agent to detect that the application-layer tasks 991 completed properly, before handing off to say the HTML parser, video 992 player etc. 994 Even a simple mechanism for end-to-end validation is thus valuable. 996 12.5. Digest and Content-Location in responses 998 When a state-changing method returns the "Content-Location" header 999 field, the enclosed representation refers to the resource identified 1000 by its value and "Digest" is computed accordingly. 1002 12.6. Usage in signatures 1004 Digital signatures are widely used together with checksums to provide 1005 the certain identification of the origin of a message [NIST800-32]. 1006 Such signatures can protect one or more HTTP fields and there are 1007 additional considerations when "Digest" is included in this set. 1009 Since the "Digest" field is a hash of a resource representation, it 1010 explicitly depends on the "representation metadata" (eg. the values 1011 of "Content-Type", "Content-Encoding" etc). A signature that 1012 protects "Digest" but not other "representation metadata" can expose 1013 the communication to tampering. For example, an actor could 1014 manipulate the "Content-Type" field-value and cause a digest 1015 validation failure at the recipient, preventing the application from 1016 accessing the representation. Such an attack consumes the resources 1017 of both endpoints. See also Section 12.5. 1019 "Digest" SHOULD always be used over a connection which provides 1020 integrity at the transport layer that protects HTTP fields. 1022 A "Digest" field using NOT RECOMMENDED digest-algorithms SHOULD NOT 1023 be used in signatures. 1025 Using signatures to protect the "Digest" of an empty representation 1026 allows receiving endpoints to detect if an eventual payload has been 1027 stripped or added. 1029 12.7. Usage in trailers 1031 When used in trailers, the receiver gets the digest value after the 1032 payload body and may thus be tempted to process the data before 1033 validating the digest value. Instead, data should only be processed 1034 after validating the Digest. 1036 If received in trailers, "Digest" MUST NOT be discarded; instead it 1037 MAY be merged in the header section (See Section 5.6.2 of 1038 [SEMANTICS]). 1040 Not every digest-algorithm is suitable for trailers, as they may 1041 require to pre-process the whole payload before sending a message 1042 (eg. see [I-D.thomson-http-mice]). 1044 12.8. Usage with encryption 1046 "Digest" may expose information details of encrypted payload when the 1047 checksum is computed on the unencrypted data. An example of that is 1048 the use of the "id-sha-256" digest-algorithm in conjunction with the 1049 encrypted content-coding [RFC8188]. 1051 The representation-data-digest of an encrypted payload can change 1052 between different messages depending on the encryption algorithm 1053 used; in those cases its value could not be used to provide a proof 1054 of integrity "at rest" unless the whole (e.g. encoded) payload body 1055 is persisted. 1057 12.9. Algorithm Agility 1059 The security properties of digest-algorithms are not fixed. 1060 Algorithm Agility (see [RFC7696]) is achieved by providing 1061 implementations flexibility in their choice of digest-algorithm from 1062 the IANA Digest Algorithm Values registry in Section 13.1. 1064 To help endpoints understand weaker algorithms from stronger ones, 1065 this document adds to the IANA Digest Algorithm Values registry a new 1066 "Status" field containing the most-recent appraisal of the digest- 1067 algorithm; the allowed values are specified in Section 13.2. 1069 An endpoint might have a preference for algorithms, such as 1070 preferring "standard" algorithms over "deprecated" ones. Transition 1071 from weak algorithms is supported by negotiation of digest-algorithm 1072 using "Want-Digest" (see Section 4) or by sending multiple 1073 representation-data-digest values from which the receiver chooses. 1074 Endpoints are advised that sending multiple values consumes 1075 resources, which may be wasted if the receiver ignores them (see 1076 Section 3). 1078 13. IANA Considerations 1080 13.1. Establish the HTTP Digest Algorithm Values 1082 This memo sets this spec to be the establishing document for the HTTP 1083 Digest Algorithm Values (https://www.iana.org/assignments/http-dig- 1084 alg/http-dig-alg.xhtml) 1086 13.2. The "status" Field in the HTTP Digest Algorithm Values 1088 This memo adds the field "Status" to the HTTP Digest Algorithm Values 1089 (https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml) 1090 registry. The allowed values for the "Status" fields are described 1091 below. 1093 Status 1094 * "standard" for standardized algorithms without known problems; 1096 * "experimental", "obsoleted" or some other appropriate value - 1097 e.g. according to the type and status of the primary document 1098 in which the algorithm is defined; 1100 * "deprecated" when the algorithm is insecure or otherwise 1101 undesirable. 1103 13.3. Deprecate "MD5" Digest Algorithm 1105 This memo updates the "MD5" digest-algorithm in the HTTP Digest 1106 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1107 dig-alg.xhtml) registry: 1109 * Digest Algorithm: md5 1111 * Description: As specified in Section 5. 1113 * Status: As specified in Section 5. 1115 13.4. Update "UNIXsum" Digest Algorithm 1117 This memo updates the "UNIXsum" digest-algorithm in the HTTP Digest 1118 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1119 dig-alg.xhtml) registry: 1121 * Digest Algorithm: As specified in Section 5. 1123 * Description: As specified in Section 5. 1125 * Status: As specified in Section 5. 1127 13.5. Update "UNIXcksum" Digest Algorithm 1129 This memo updates the "UNIXcksum" digest-algorithm in the HTTP Digest 1130 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1131 dig-alg.xhtml) registry: 1133 * Digest Algorithm: As specified in Section 5. 1135 * Description: As specified in Section 5. 1137 * Status: As specified in Section 5. 1139 13.6. Update "CRC32c" Digest Algorithm 1141 This memo updates the "CRC32c" digest-algorithm in the HTTP Digest 1142 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1143 dig-alg.xhtml) registry: 1145 * Digest Algorithm: crc32c 1147 * Description: The CRC32c algorithm is a 32-bit cyclic redundancy 1148 check. It achieves a better hamming distance (for better error- 1149 detection performance) than many other 32-bit CRC functions. 1150 Other places it is used include iSCSI and SCTP. The 32-bit output 1151 is encoded in hexadecimal (using between 1 and 8 ASCII characters 1152 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 1153 crc32c=0a72a4df and crc32c=A72A4DF are both valid checksums for 1154 the 3-byte message "dog". 1156 * Reference: [RFC4960] appendix B, this document. 1158 * Status: standard. 1160 13.7. Deprecate "SHA" Digest Algorithm 1162 This memo updates the "SHA" digest-algorithm in the HTTP Digest 1163 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1164 dig-alg.xhtml) registry: 1166 * Digest Algorithm: sha 1168 * Description: As specified in Section 5. 1170 * Status: As specified in Section 5. 1172 13.8. Obsolete "ADLER32" Digest Algorithm 1174 This memo updates the "ADLER32" digest-algorithm in the HTTP Digest 1175 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1176 dig-alg.xhtml) registry: 1178 * Digest Algorithm: adler32 1180 * Description: The ADLER32 algorithm is a checksum specified in 1181 [RFC1950] "ZLIB Compressed Data Format". The 32-bit output is 1182 encoded in hexadecimal (using between 1 and 8 ASCII characters 1183 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 1184 adler32=03da0195 and adler32=3DA0195 are both valid checksums for 1185 the 4-byte message "Wiki". This algorithm is obsoleted and SHOULD 1186 NOT be used. 1188 * Status: obsoleted 1190 13.9. Obsolete "contentMD5" token in Digest Algorithm 1192 This memo adds the "contentMD5" token in the HTTP Digest Algorithm 1193 Values (https://www.iana.org/assignments/http-dig-alg/http-dig- 1194 alg.xhtml) registry: 1196 * Digest Algorithm: contentMD5 1198 * Description: Section 5 of [RFC3230] defined the "contentMD5" token 1199 to be used only in Want-Digest. This token is obsoleted and MUST 1200 NOT be used. 1202 * Reference: Section 13.9 of this document, Section 5 of [RFC3230]. 1204 * Status: obsoleted 1206 13.10. The "id-sha-256" Digest Algorithm 1208 This memo registers the "id-sha-256" digest-algorithm in the HTTP 1209 Digest Algorithm Values (https://www.iana.org/assignments/http-dig- 1210 alg/http-dig-alg.xhtml) registry: 1212 * Digest Algorithm: id-sha-256 1214 * Description: As specified in Section 5. 1216 * Status: As specified in Section 5. 1218 13.11. The "id-sha-512" Digest Algorithm 1220 This memo registers the "id-sha-512" digest-algorithm in the HTTP 1221 Digest Algorithm Values (https://www.iana.org/assignments/http-dig- 1222 alg/http-dig-alg.xhtml) registry: 1224 * Digest Algorithm: id-sha-512 1226 * Description: As specified in Section 5. 1228 * Status: As specified in Section 5. 1230 13.12. Changes compared to RFC5843 1232 The digest-algorithm values for "MD5", "SHA", "SHA-256", "SHA-512", 1233 "UNIXcksum", "UNIXsum", "ADLER32" and "CRC32c" have been updated to 1234 lowercase. 1236 The status of "MD5" has been updated to "deprecated", and its 1237 description states that this algorithm MUST NOT be used. 1239 The status of "SHA" has been updated to "deprecated", and its 1240 description states that this algorithm MUST NOT be used. 1242 The status for "CRC2c", "UNIXsum" and "UNIXcksum" has been updated to 1243 "standard". 1245 The "id-sha-256" and "id-sha-512" algorithms have been added to the 1246 registry. 1248 13.13. Want-Digest Field Registration 1250 This section registers the "Want-Digest" field in the "Hypertext 1251 Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. 1253 Field name: "Want-Digest" 1255 Status: permanent 1257 Specification document(s): Section 4 of this document 1259 13.14. Digest Header Field Registration 1261 This section registers the "Digest" field in the "Hypertext Transfer 1262 Protocol (HTTP) Field Name Registry" [SEMANTICS]. 1264 Field name: "Digest" 1266 Status: permanent 1268 Specification document(s): Section 3 of this document 1270 14. References 1272 14.1. Normative References 1274 [CMU-836068] 1275 Carnagie Mellon University, Software Engineering 1276 Institute, "MD5 Vulnerable to collision attacks", 31 1277 December 2008, . 1279 [IACR-2020-014] 1280 Leurent, G. and T. Peyrin, "SHA-1 is a Shambles", 5 1281 January 2020, . 1283 [NIST800-32] 1284 National Institute of Standards and Technology, U.S. 1285 Department of Commerce, "Introduction to Public Key 1286 Technology and the Federal PKI Infrastructure", February 1287 2001, . 1290 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 1291 DOI 10.17487/RFC1321, April 1992, 1292 . 1294 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 1295 Specification version 3.3", RFC 1950, 1296 DOI 10.17487/RFC1950, May 1996, 1297 . 1299 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1300 Requirement Levels", BCP 14, RFC 2119, 1301 DOI 10.17487/RFC2119, March 1997, 1302 . 1304 [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 1305 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, 1306 . 1308 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 1309 RFC 3230, DOI 10.17487/RFC3230, January 2002, 1310 . 1312 [RFC3309] Stone, J., Stewart, R., and D. Otis, "Stream Control 1313 Transmission Protocol (SCTP) Checksum Change", RFC 3309, 1314 DOI 10.17487/RFC3309, September 2002, 1315 . 1317 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1318 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1319 . 1321 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1322 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1323 . 1325 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1326 Specifications: ABNF", STD 68, RFC 5234, 1327 DOI 10.17487/RFC5234, January 2008, 1328 . 1330 [RFC5843] Bryan, A., "Additional Hash Algorithms for HTTP Instance 1331 Digests", RFC 5843, DOI 10.17487/RFC5843, April 2010, 1332 . 1334 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 1335 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 1336 DOI 10.17487/RFC6234, May 2011, 1337 . 1339 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 1340 RFC 7405, DOI 10.17487/RFC7405, December 2014, 1341 . 1343 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1344 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1345 May 2017, . 1347 [SEMANTICS] 1348 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 1349 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1350 httpbis-semantics-12, 2 October 2020, 1351 . 1354 [UNIX] The Open Group, "The Single UNIX Specification, Version 2 1355 - 6 Vol Set for UNIX 98", February 1997. 1357 14.2. Informative References 1359 [HTTP11] Fielding, R., Nottingham, M., and J. Reschke, "HTTP/1.1 1360 Messaging", Work in Progress, Internet-Draft, draft-ietf- 1361 httpbis-messaging-12, 2 October 2020, 1362 . 1365 [I-D.ietf-httpbis-header-structure] 1366 Nottingham, M. and P. Kamp, "Structured Field Values for 1367 HTTP", Work in Progress, Internet-Draft, draft-ietf- 1368 httpbis-header-structure-19, 3 June 2020, 1369 . 1372 [I-D.thomson-http-mice] 1373 Thomson, M. and J. Yasskin, "Merkle Integrity Content 1374 Encoding", Work in Progress, Internet-Draft, draft- 1375 thomson-http-mice-03, 13 August 2018, 1376 . 1379 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 1380 DOI 10.17487/RFC2818, May 2000, 1381 . 1383 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1384 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1385 . 1387 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1388 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1389 DOI 10.17487/RFC7231, June 2014, 1390 . 1392 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 1393 DOI 10.17487/RFC7396, October 2014, 1394 . 1396 [RFC7696] Housley, R., "Guidelines for Cryptographic Algorithm 1397 Agility and Selecting Mandatory-to-Implement Algorithms", 1398 BCP 201, RFC 7696, DOI 10.17487/RFC7696, November 2015, 1399 . 1401 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 1402 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 1403 . 1405 [RFC8188] Thomson, M., "Encrypted Content-Encoding for HTTP", 1406 RFC 8188, DOI 10.17487/RFC8188, June 2017, 1407 . 1409 [SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger, 1410 "Subresource Integrity", W3C Recommendation REC-SRI- 1411 20160623, 23 June 2016, 1412 . 1414 Appendix A. Resource Representation and Representation-Data 1416 The following examples show how representation metadata, payload 1417 transformations and method impacts on the message and payload body. 1418 When the payload body contains non-printable characters (eg. when it 1419 is compressed) it is shown as base64-encoded string. 1421 A request with a json object without any content coding. 1423 Request: 1425 PUT /entries/1234 HTTP/1.1 1426 Content-Type: application/json 1428 {"hello": "world"} 1430 Here is a gzip-compressed json object using a content coding. 1432 Request: 1434 PUT /entries/1234 HTTP/1.1 1435 Content-Type: application/json 1436 Content-Encoding: gzip 1438 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 1440 Now the same payload body conveys a malformed json object. 1442 Request: 1444 PUT /entries/1234 HTTP/1.1 1445 Content-Type: application/json 1447 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 1449 A Range-Request alters the payload body, conveying a partial 1450 representation. 1452 Request: 1454 GET /entries/1234 HTTP/1.1 1455 Range: bytes=1-7 1457 Response: 1459 HTTP/1.1 206 Partial Content 1460 Content-Encoding: gzip 1461 Content-Type: application/json 1462 Content-Range: bytes 1-7/18 1464 iwgAla3RXA== 1466 Now the method too alters the payload body. 1468 Request: 1470 HEAD /entries/1234 HTTP/1.1 1471 Accept: application/json 1472 Accept-Encoding: gzip 1473 Response: 1475 HTTP/1.1 200 OK 1476 Content-Type: application/json 1477 Content-Encoding: gzip 1479 Finally the semantics of an HTTP response might decouple the 1480 effective request URI from the enclosed representation. In the 1481 example response below, the "Content-Location" header field indicates 1482 that the enclosed representation refers to the resource available at 1483 "/authors/123". 1485 Request: 1487 POST /authors/ HTTP/1.1 1488 Accept: application/json 1489 Content-Type: application/json 1491 {"author": "Camilleri"} 1493 Response: 1495 HTTP/1.1 201 Created 1496 Content-Type: application/json 1497 Content-Location: /authors/123 1498 Location: /authors/123 1500 {"id": "123", "author": "Camilleri"} 1502 Appendix B. FAQ 1504 1. Why remove all references to content-md5? 1506 Those were unnecessary to understanding and using this spec. 1508 2. Why remove references to instance manipulation? 1510 Those were unnecessary for correctly using and applying the spec. 1511 An example with Range Request is more than enough. This doc uses 1512 the term "partial representation" which should group all those 1513 cases. 1515 3. How to use "Digest" with "PATCH" method? 1517 See Section 6. 1519 4. Why remove references to delta-encoding? 1520 Unnecessary for a correct implementation of this spec. The 1521 revised spec can be nicely adapted to "delta encoding", but all 1522 the references here to delta encoding don't add anything to this 1523 RFC. Another job would be to refresh delta encoding. 1525 5. Why remove references to Digest Authentication? 1527 This RFC seems to me completely unrelated to Digest 1528 Authentication but for the word "Digest". 1530 6. What changes in "Want-Digest"? 1532 The contentMD5 token defined in Section 5 of [RFC3230] is 1533 deprecated by Section 7. 1535 To clarify that "Digest" and "Want-Digest" can be used in both 1536 requests and responses - [RFC3230] carefully uses "sender" and 1537 "receiver" in their definition - we added examples on using 1538 "Want-Digest" in responses to advertise the supported digest- 1539 algorithms and the inability to accept requests with unsupported 1540 digest-algorithms. 1542 7. Does this spec changes supported algorithms? 1544 This RFC updates [RFC5843] which is still delegated for all 1545 algorithms updates, and adds two more algorithms: "id-sha-256" 1546 and "id-sha-512" which allows to send a checksum of a resource 1547 representation with no content codings applied. To simplify a 1548 future transition to Structured Fields 1549 [I-D.ietf-httpbis-header-structure] we suggest to use lowercase 1550 for digest-algorithms. 1552 8. What about mid-stream trailers? 1554 While mid-stream trailers (https://github.com/httpwg/http-core/ 1555 issues/313#issuecomment-584389706) are interesting, since this 1556 specification is a rewrite of [RFC3230] we do not think we should 1557 face that. As a first thought, nothing in this document 1558 precludes future work that would find a use for mid-stream 1559 trailers, for example an incremental digest-algorithm. A 1560 document defining such a digest-algorithm is best positioned to 1561 describe how it is used. 1563 Acknowledgements 1565 The vast majority of this document is inherited from [RFC3230], so 1566 thanks to J. Mogul and A. Van Hoff for their great work. The 1567 original idea of refreshing this document arose from an interesting 1568 discussion with M. Nottingham, J. Yasskin and M. Thomson when 1569 reviewing the MICE content coding. 1571 Code Samples 1573 _RFC Editor: Please remove this section before publication._ 1575 How can I generate and validate the "Digest" values shown in the 1576 examples throughout this document? 1578 The following python3 code can be used to generate digests for json 1579 objects using SHA algorithms for a range of encodings. Note that 1580 these are formatted as base64. This function could be adapted to 1581 other algorithms and should take into account their specific 1582 formatting rules. 1584 import base64, json, hashlib, brotli 1586 def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): 1587 json_bytes = json.dumps(item).encode() 1588 content_encoded = encoding(json_bytes) 1589 checksum_bytes = algorithm(content_encoded).digest() 1590 return base64.encodebytes(checksum_bytes).strip() 1592 item = {"hello": "world"} 1594 print("Encoding | digest-algorithm | digest-value") 1595 print("Identity | sha256 |", digest(item)) 1596 # Encoding | digest-algorithm | digest-value 1597 # Identity | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1599 print("Encoding | digest-algorithm | digest-value") 1600 print("Brotli | sha256 |", digest(item, encoding=brotli.compress)) 1601 # Encoding | digest-algorithm | digest-value 1602 # Brotli , sha256 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1604 print("Encoding | digest-algorithm | digest-value") 1605 print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512)) 1606 # Encoding | digest-algorithm | digest-value 1607 # Identity | sha512 | b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2s 1608 vX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==\n' 1610 Changes 1612 _RFC Editor: Please remove this section before publication._ 1614 Since draft-ietf-httpbis-digest-headers-03 1616 * Reference semantics-12 1618 * Detail encryption quirks 1620 * Details on Algorithm agility #1250 1622 * Obsolete parameters #850 1624 Since draft-ietf-httpbis-digest-headers-02 1626 * Deprecate SHA-1 #1154 1628 * Avoid id-* with encrypted content 1629 * Digest is independent from MESSAGING and HTTP/1.1 is not normative 1630 #1215 1632 * Identity is not a valid field value for content-encoding #1223 1634 * Mention trailers #1157 1636 * Reference httpbis-semantics #1156 1638 * Add contentMD5 as an obsoleted digest-algorithm #1249 1640 * Use lowercase digest-algorithms names in the doc and in the 1641 digest-algorithm IANA table. 1643 Since draft-ietf-httpbis-digest-headers-01 1645 * Digest of error responses is computed on the error representation- 1646 data #1004 1648 * Effect of HTTP semantics on payload and message body moved to 1649 appendix #1122 1651 * Editorial refactoring, moving headers sections up. #1109-#1112, 1652 #1116, #1117, #1122-#1124 1654 Since draft-ietf-httpbis-digest-headers-00 1656 * Align title with document name 1658 * Add id-sha-* algorithm examples #880 1660 * Reference [RFC6234] and [RFC3174] instead of FIPS-1 1662 * Deprecate MD5 1664 * Obsolete ADLER-32 but don't forbid it #828 1666 * Update CRC32C value in IANA table #828 1668 * Use when acting on resources (POST, PATCH) #853 1670 * Added Relationship with SRI, draft Use Cases #868, #971 1672 * Warn about the implications of "Content-Location" 1674 Authors' Addresses 1675 Roberto Polli 1676 Team Digitale, Italian Government 1678 Email: robipolli@gmail.com 1680 Lucas Pardue 1681 Cloudflare 1683 Email: lucaspardue.24.7@gmail.com