idnits 2.17.1 draft-ietf-httpbis-digest-headers-05.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Some digest-algorithms, although registered, rely on vulnerable algorithms and MUST not be used: -- The document date (13 April 2021) is 1110 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-15 -- 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-15 -- 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 (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP R. Polli 3 Internet-Draft Team Digitale, Italian Government 4 Obsoletes: 3230 (if approved) L. Pardue 5 Intended status: Standards Track Cloudflare 6 Expires: 15 October 2021 13 April 2021 8 Digest Headers 9 draft-ietf-httpbis-digest-headers-05 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 15 October 2021. 50 Copyright Notice 52 Copyright (c) 2021 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 . . . . . . . . . . . . . . . . . 6 71 2. Representation Digest . . . . . . . . . . . . . . . . . . . . 6 72 3. The Digest Field . . . . . . . . . . . . . . . . . . . . . . 7 73 4. The Want-Digest Field . . . . . . . . . . . . . . . . . . . . 8 74 5. Digest Algorithm Values . . . . . . . . . . . . . . . . . . . 8 75 6. Use of Digest when acting on resources . . . . . . . . . . . 11 76 6.1. Digest and PATCH . . . . . . . . . . . . . . . . . . . . 11 77 7. Deprecate Negotiation of Content-MD5 . . . . . . . . . . . . 11 78 8. Obsolete Digest Field Parameters . . . . . . . . . . . . . . 12 79 9. Relationship to Subresource Integrity (SRI) . . . . . . . . . 12 80 9.1. Supporting Both SRI and Representation Digest . . . . . . 13 81 10. Examples of Unsolicited Digest . . . . . . . . . . . . . . . 13 82 10.1. Server Returns Full Representation Data . . . . . . . . 13 83 10.2. Server Returns No Representation Data . . . . . . . . . 14 84 10.3. Server Returns Partial Representation Data . . . . . . . 14 85 10.4. Client and Server Provide Full Representation Data . . . 15 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. . . . . . . . . . . . . . . . . . . . 16 90 10.7. POST Response does not Reference the Request URI . . . . 17 91 10.8. POST Response Describes the Request Status . . . . . . . 18 92 10.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . 18 93 10.10. Error responses . . . . . . . . . . . . . . . . . . . . 19 94 10.11. Use with Trailer Fields and Transfer Coding . . . . . . 20 95 11. Examples of Want-Digest Solicited Digest . . . . . . . . . . 21 96 11.1. Server Selects Client's Least Preferred Algorithm . . . 21 97 11.2. Server Selects Algorithm Unsupported by Client . . . . . 22 98 11.3. Server Does Not Support Client Algorithm and Returns an 99 Error . . . . . . . . . . . . . . . . . . . . . . . . . 22 100 12. Security Considerations . . . . . . . . . . . . . . . . . . . 22 101 12.1. Digest Does Not Protect the Full HTTP Message . . . . . 22 102 12.2. Broken Cryptographic Algorithms . . . . . . . . . . . . 23 103 12.3. Other Deprecated Algorithms . . . . . . . . . . . . . . 23 104 12.4. Digest for End-to-End Integrity . . . . . . . . . . . . 23 105 12.5. Digest and Content-Location in Responses . . . . . . . . 23 106 12.6. Usage in Signatures . . . . . . . . . . . . . . . . . . 24 107 12.7. Usage in Trailer Fields . . . . . . . . . . . . . . . . 24 108 12.8. Usage with Encryption . . . . . . . . . . . . . . . . . 25 109 12.9. Algorithm Agility . . . . . . . . . . . . . . . . . . . 25 110 12.9.1. Duplicate digest-algorithm in field value . . . . . 25 111 12.10. Resource exhaustion . . . . . . . . . . . . . . . . . . 26 112 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 113 13.1. Establish the HTTP Digest Algorithm Values Registry . . 26 114 13.2. The "status" Field in the HTTP Digest Algorithm Values 115 Registry . . . . . . . . . . . . . . . . . . . . . . . 26 116 13.3. Deprecate "MD5" Digest Algorithm . . . . . . . . . . . . 26 117 13.4. Update "UNIXsum" Digest Algorithm . . . . . . . . . . . 26 118 13.5. Update "UNIXcksum" Digest Algorithm . . . . . . . . . . 27 119 13.6. Update "CRC32c" Digest Algorithm . . . . . . . . . . . . 27 120 13.7. Deprecate "SHA" Digest Algorithm . . . . . . . . . . . . 27 121 13.8. Obsolete "ADLER32" Digest Algorithm . . . . . . . . . . 28 122 13.9. Obsolete "contentMD5" token in Digest Algorithm . . . . 28 123 13.10. The "id-sha-256" Digest Algorithm . . . . . . . . . . . 28 124 13.11. The "id-sha-512" Digest Algorithm . . . . . . . . . . . 29 125 13.12. Changes Compared to RFC5843 . . . . . . . . . . . . . . 29 126 13.13. Want-Digest Field Registration . . . . . . . . . . . . . 29 127 13.14. Digest Field Registration . . . . . . . . . . . . . . . 29 128 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 129 14.1. Normative References . . . . . . . . . . . . . . . . . . 30 130 14.2. Informative References . . . . . . . . . . . . . . . . . 31 131 Appendix A. Resource Representation and Representation-Data . . 33 132 Appendix B. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 35 133 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 36 134 Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 36 135 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 136 Since draft-ietf-httpbis-digest-headers-04 . . . . . . . . . . 38 137 Since draft-ietf-httpbis-digest-headers-03 . . . . . . . . . . 38 138 Since draft-ietf-httpbis-digest-headers-02 . . . . . . . . . . 38 139 Since draft-ietf-httpbis-digest-headers-01 . . . . . . . . . . 38 140 Since draft-ietf-httpbis-digest-headers-00 . . . . . . . . . . 39 141 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 143 1. Introduction 145 The core specification of HTTP does not define a means to protect the 146 integrity of resources. When HTTP messages are transferred between 147 endpoints, the protocol might choose to make use of features of the 148 lower layer in order to provide some integrity protection; for 149 instance TCP checksums or TLS records [RFC2818]. 151 However, there are cases where relying on this alone is insufficient. 152 An HTTP-level integrity mechanism that operates independent of 153 transfer can be used to detect programming errors and/or corruption 154 of data in flight or at rest, be used across multiple hops in order 155 to provide end-to-end integrity guarantees, can aid fault diagnosis 156 across hops and system boundaries, and can be used to validate 157 integrity when reconstructing a resource fetched using different HTTP 158 connections. 160 This document defines a mechanism that acts on HTTP representation- 161 data. It can be combined with other mechanisms that protect 162 representation-metadata, such as digital signatures, in order to 163 protect the desired parts of an HTTP exchange in whole or in part. 165 1.1. A Brief History of HTTP Integrity Fields 167 The Content-MD5 header field was originally introduced to provide 168 integrity, but HTTP/1.1 ([RFC7231], Appendix B) obsoleted it: 170 The Content-MD5 header field has been removed because it was 171 inconsistently implemented with respect to partial responses. 173 [RFC3230] provided a more flexible solution introducing the concept 174 of "instance", and the fields "Digest" and "Want-Digest". 176 1.2. This Proposal 178 The concept of "selected representation" defined in Section 3.2 of 179 [SEMANTICS] makes [RFC3230] definitions inconsistent with current 180 HTTP semantics. This document updates the "Digest" and "Want-Digest" 181 field definitions to align with [SEMANTICS] concepts. 183 Basing "Digest" on the selected representation makes it 184 straightforward to apply it to use-cases where the transferred data 185 does require some sort of manipulation to be considered a 186 representation, or conveys a partial representation of a resource eg. 187 Range Requests (see Section 14.2 of [SEMANTICS]). 189 This document replaces [RFC3230] to better align with [SEMANTICS] and 190 to provide more detailed description of "Digest" usage in request and 191 response cases. Changes are intended to be semantically compatible 192 with existing implementations but note that negotiation of "Content- 193 MD5" is deprecated Section 7, "Digest" field parameters are obsoleted 194 Section 8, "md5" and "sha" digest-algorithms are obsoleted 195 Section 12.2 and the "adler32" algorithm is deprecated Section 12.3. 197 The value of "Digest" is calculated on selected representation, which 198 is tied to the value contained in any "Content-Encoding" or "Content- 199 Type" header fields. Therefore, a given resource may have multiple 200 different digest values. 202 To allow both parties to exchange a Digest of a representation with 203 no content codings (see Section 8.4.1 of [SEMANTICS]) two more 204 digest-algorithms are added ("id-sha-256" and "id-sha-512"). 206 1.3. Goals 208 The goals of this proposal are: 210 1. Digest coverage for either the resource's "representation data" 211 or "selected representation data" communicated via HTTP. 213 2. Support for multiple digest-algorithms. 215 3. Negotiation of the use of digests. 217 The goals do not include: 219 HTTP message integrity: Digest mechanisms do not cover the full HTTP 220 message nor its semantic, as representation metadata is not 221 included in the checksum. 223 HTTP field integrity: Digest mechanisms cover only representation 224 and selected representation data, and do not protect the integrity 225 of associated representation metadata or other message fields. 227 Authentication: Digest mechanisms do not support authentication of 228 the source of a digest, message or anything else. These 229 mechanisms, therefore, are not a sufficient defense against many 230 kinds of malicious attacks. 232 Privacy: Digest mechanisms do not provide message privacy. 234 Authorization: Digest mechanisms do not support authorization or 235 other kinds of access controls. 237 1.4. Notational Conventions 239 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 240 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 241 "OPTIONAL" in this document are to be interpreted as described in 242 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 243 capitals, as shown here. 245 This document uses the Augmented BNF defined in [RFC5234] and updated 246 by [RFC7405] along with the "#rule" extension defined in 247 Section 5.6.1 of [SEMANTICS]. 249 The definitions "representation", "selected representation", 250 "representation data", "representation metadata", and "content" in 251 this document are to be interpreted as described in [SEMANTICS]. 253 Algorithm names respect the casing used in their definition document 254 (eg. SHA-1, CRC32c) whereas digest-algorithm tokens are quoted (eg. 255 "sha", "crc32c"). 257 2. Representation Digest 259 The representation digest is an integrity mechanism for HTTP 260 resources which uses a checksum that is calculated independently of 261 the content (see Section 6.4 of [SEMANTICS]). It uses the 262 representation data (see Section 8.1 of [SEMANTICS]), that can be 263 fully or partially contained in the content, or not contained at all: 265 representation-data := Content-Encoding( Content-Type( bits ) ) 267 This takes into account the effect of the HTTP semantics on the 268 messages; for example, the content can be affected by Range Requests 269 or methods such as HEAD, while the way the content is transferred "on 270 the wire" is dependent on other transformations (e.g. transfer 271 codings for HTTP/1.1 - see Section 6.1 of [HTTP11]). To help 272 illustrate how such things affect "Digest", several examples are 273 provided in Appendix A. 275 A representation digest consists of the value of a checksum computed 276 on the entire selected "representation data" (see Section 8.1 of 277 [SEMANTICS]) of a resource identified according to Section 6.4.2 of 278 [SEMANTICS] together with an indication of the algorithm used: 280 representation-data-digest = digest-algorithm "=" 281 283 When a message has no representation data it is still possible to 284 assert that no representation data was sent computing the 285 representation digest on an empty string (see Section 12.6). 287 The checksum is computed using one of the digest-algorithms listed in 288 Section 5 and then encoded in the associated format. 290 The example below shows the "sha-256" digest-algorithm that uses 291 base64 encoding. 293 sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 295 3. The Digest Field 297 The "Digest" field contains a list of one or more representation 298 digest values as defined in Section 2. It can be used in both 299 requests and responses. 301 Digest = 1#representation-data-digest 303 For example: 305 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 306 AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 308 The relationship between "Content-Location" (see Section 8.7 of 309 [SEMANTICS]) and "Digest" is demonstrated in Section 10.7. A 310 comprehensive set of examples showing the impacts of representation 311 metadata, payload transformations and HTTP methods on Digest is 312 provided in Section 10 and Section 11. 314 A "Digest" field MAY contain multiple representation-data-digest 315 values. For example, a server may provide representation-data-digest 316 values using different algorithms, allowing it to support a 317 population of clients with different evolving capabilities; this is 318 particularly useful in support of transitioning away from weaker 319 algorithms should the need arise (see Section 12.9). 321 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 322 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 324 A recipient MAY ignore any or all of the representation-data-digests 325 in a Digest field. This allows the recipient to choose which digest- 326 algorithm(s) to use for validation instead of verifying every 327 received representation-data-digest. 329 A sender MAY send a representation-data-digest using a digest- 330 algorithm without knowing whether the recipient supports the digest- 331 algorithm, or even knowing that the recipient will ignore it. 333 "Digest" can be sent in a trailer section. When an incremental 334 digest-algorithms is used, the sender and the receiver can 335 dynamically compute the digest value while streaming the content. 337 4. The Want-Digest Field 339 The "Want-Digest" field indicates the sender's desire to receive a 340 representation digest on messages associated with the request URI and 341 representation metadata. 343 Want-Digest = 1#want-digest-value 344 want-digest-value = digest-algorithm [ ";" "q" "=" qvalue] 345 qvalue = ( "0"  [ "."  0*1DIGIT ] ) / 346   ( "1"  [ "."  0*1( "0" ) ] ) 348 If a digest-algorithm is not accompanied by a "qvalue", it is treated 349 as if its associated "qvalue" were 1.0. 351 The sender is willing to accept a digest-algorithm if and only if it 352 is listed in a "Want-Digest" field of a message, and its "qvalue" is 353 non-zero. 355 If multiple acceptable digest-algorithm values are given, the 356 sender's preferred digest-algorithm is the one (or ones) with the 357 highest "qvalue". 359 Two examples of its use are: 361 Want-Digest: sha-256 362 Want-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0 364 5. Digest Algorithm Values 366 Digest-algorithm values are used to indicate a specific digest 367 computation. 369 digest-algorithm = token 371 All digest-algorithm values are case-insensitive but lower case is 372 preferred. 374 The Internet Assigned Numbers Authority (IANA) acts as a registry for 375 digest-algorithm values. The registry contains the tokens listed 376 below. 378 Some digest-algorithms, although registered, rely on vulnerable 379 algorithms and MUST not be used: 381 * "md5", see [CMU-836068] and [NO-MD5]; 383 * "sha", see [IACR-2020-014] and [NO-SHA1]. 385 See the references above for further information. 387 sha-256 388 * Description: The SHA-256 algorithm [RFC6234]. The output of 389 this algorithm is encoded using the base64 encoding [RFC4648]. 391 * Reference: [RFC6234], [RFC4648], this document. 393 * Status: standard 395 sha-512 396 * Description: The SHA-512 algorithm [RFC6234]. The output of 397 this algorithm is encoded using the base64 encoding [RFC4648]. 399 * Reference: [RFC6234], [RFC4648], this document. 401 * Status: standard 403 md5 404 * Description: The MD5 algorithm, as specified in [RFC1321]. The 405 output of this algorithm is encoded using the base64 encoding 406 [RFC4648]. This digest-algorithm MUST NOT be used as it's now 407 vulnerable to collision attacks. See [NO-MD5] and 408 [CMU-836068]. 410 * Reference: [RFC1321], [RFC4648], this document. 412 * Status: deprecated 414 sha 415 * Description: The SHA-1 algorithm [RFC3174]. The output of this 416 algorithm is encoded using the base64 encoding [RFC4648]. This 417 digest-algorithm MUST NOT be used as it's now vulnerable to 418 collision attacks. See [NO-SHA1] and [IACR-2020-014]. 420 * Reference: [RFC3174], [RFC6234], [RFC4648], this document. 422 * Status: deprecated 424 unixsum 425 * Description: The algorithm computed by the UNIX "sum" command, 426 as defined by the Single UNIX Specification, Version 2 [UNIX]. 427 The output of this algorithm is an ASCII decimal-digit string 428 representing the 16-bit checksum, which is the first word of 429 the output of the UNIX "sum" command. 431 * Reference: [UNIX], this document. 433 * Status: standard 435 unixcksum 436 * Description: The algorithm computed by the UNIX "cksum" 437 command, as defined by the Single UNIX Specification, Version 2 438 [UNIX]. The output of this algorithm is an ASCII digit string 439 representing the 32-bit CRC, which is the first word of the 440 output of the UNIX "cksum" command. 442 * Reference: [UNIX], this document. 444 * Status: standard 446 To allow sender and recipient to provide a checksum which is 447 independent from "Content-Encoding", the following additional digest- 448 algorithms are defined: 450 id-sha-512 451 * Description: The sha-512 digest of the representation-data of 452 the resource when no content coding is applied 454 * Reference: [RFC6234], [RFC4648], this document. 456 * Status: standard 458 id-sha-256 459 * Description: The sha-256 digest of the representation-data of 460 the resource when no content coding is applied 462 * Reference: [RFC6234], [RFC4648], this document. 464 * Status: standard 466 If other digest-algorithm values are defined, the associated encoding 467 MUST either be represented as a quoted string or MUST NOT include ";" 468 or "," in the character sets used for the encoding. 470 6. Use of Digest when acting on resources 472 POST and PATCH requests can appear to convey partial representations 473 but are semantically acting on resources. The enclosed 474 representation, including its metadata, refers to that action. 476 In these requests the representation digest MUST be computed on the 477 representation-data of that action. This is the only possible choice 478 because representation digest requires complete representation 479 metadata (see Section 2). 481 In responses, 483 * if the representation describes the status of the request, 484 "Digest" MUST be computed on the enclosed representation (see 485 Section 10.8 ); 487 * if there is a referenced resource "Digest" MUST be computed on the 488 selected representation of the referenced resource even if that is 489 different from the target resource. That might or might not 490 result in computing "Digest" on the enclosed representation. 492 The latter case might be done according to the HTTP semantics of the 493 given method, for example using the "Content-Location" header field. 494 In contrast, the "Location" header field does not affect "Digest" 495 because it is not representation metadata. 497 6.1. Digest and PATCH 499 In PATCH requests, the representation digest MUST be computed on the 500 patch document because the representation metadata refers to the 501 patch document and not to the target resource (see Section 2 of 502 [PATCH]). 504 In PATCH responses, the representation digest MUST be computed on the 505 selected representation of the patched resource. 507 "Digest" usage with PATCH is thus very similar to POST, but with the 508 resource's own semantic partly implied by the method and by the patch 509 document. 511 7. Deprecate Negotiation of Content-MD5 513 This RFC deprecates the negotiation of Content-MD5 as it has been 514 obsoleted by [RFC7231]. The "contentMD5" token defined in Section 5 515 of [RFC3230] MUST NOT be used as a digest-algorithm. 517 8. Obsolete Digest Field Parameters 519 Section 4.1.1 and 4.2 of [RFC3230] defined field parameters. This 520 document obsoletes the usage of parameters with "Digest" because this 521 feature has not been widely deployed and complicates field-value 522 processing. 524 [RFC3230] intended field parameters to provide a common way to attach 525 additional information to a representation-data-digest. However, if 526 parameters are used as an input to validate the checksum, an attacker 527 could alter them to steer the validation behavior. 529 A digest-algorithm can still be parameterized by defining its own way 530 to encode parameters into the representation-data-digest, in such a 531 way as to mitigate security risks related to its computation. 533 9. Relationship to Subresource Integrity (SRI) 535 Subresource Integrity [SRI] is an integrity mechanism that shares 536 some similarities to the present document's mechanism. However, 537 there are differences in motivating factors, threat model and 538 specification of integrity digest generation, signalling and 539 validation. 541 SRI allows a first-party authority to declare an integrity assertion 542 on a resource served by a first or third party authority. This is 543 done via the "integrity" attribute that can be added to "script" or 544 "link" HTML elements. Therefore, the integrity assertion is always 545 made out-of-band to the resource fetch. In contrast, the "Digest" 546 field is supplied in-band alongside the selected representation, 547 meaning that an authority can only declare an integrity assertion for 548 itself. Methods to improve the security properties of representation 549 digests are presented in Section 12. This contrast is interesting 550 because on one hand self-assertion is less likely to be affected by 551 coordination problems such as the first-party holding stale 552 information about the third party, but on the other hand the self- 553 assertion is only as trustworthy as the authority that provided it. 555 The SRI "integrity" attribute contains a cryptographic hash algorithm 556 and digest value which is similar to "representation-data-digest" 557 (see Section 2). The major differences are in serialization format. 559 SRI does not specify handling of partial representation data (e.g. 560 Range requests). In contrast, this document specifies handling in 561 terms that are fully compatible with core HTTP concepts (an example 562 is provided in Section 10.3). 564 SRI specifies strong requirements on the selection of algorithm for 565 generation and validation of digests. In contrast, the requirements 566 in this document are weaker. 568 SRI defines no method for a client to declare an integrity assertion 569 on resources it transfers to a server. In contrast, the "Digest" 570 field can appear on requests. 572 9.1. Supporting Both SRI and Representation Digest 574 The SRI and Representation Digest mechanisms are different and 575 complementary but one is not capable of replacing the other because 576 they have different threat, security and implementation properties. 578 A user agent that supports both mechanisms is expected to apply the 579 rules specified for each but since the two mechanisms are 580 independent, the ordering is not important. However, a user agent 581 supporting both could benefit from performing representation digest 582 validation first because it does not always require a conversion into 583 identity encoding. 585 There is a chance that a user agent supporting both mechanisms may 586 find one validates successfully while the other fails. This document 587 specifies no requirements or guidance for user agents that experience 588 such cases. 590 10. Examples of Unsolicited Digest 592 The following examples demonstrate interactions where a server 593 responds with a "Digest" field even though the client did not solicit 594 one using "Want-Digest". 596 Some examples include JSON objects in the content. For presentation 597 purposes, objects that fit completely within the line-length limits 598 are presented on a single line using compact notation with no leading 599 space. Objects that would exceed line-length limits are presented 600 across multiple lines (one line per key-value pair) with 2 spaced of 601 leading indentation. 603 "Digest" is media-type agnostic and does not provide canonicalization 604 algorithms for specific formats. Examples of "Digest" are calculated 605 inclusive of any space. 607 10.1. Server Returns Full Representation Data 609 Request: 611 GET /items/123 HTTP/1.1 612 Host: foo.example 614 Response: 616 HTTP/1.1 200 OK 617 Content-Type: application/json 618 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 620 {"hello": "world"} 622 10.2. Server Returns No Representation Data 624 In this example, a HEAD request is used to retrieve the checksum of a 625 resource. 627 The response "Digest" field-value is calculated over the JSON object 628 "{"hello": "world"}", which is not shown because there is no payload 629 data. 631 Request: 633 HEAD /items/123 HTTP/1.1 634 Host: foo.example 636 Response: 638 HTTP/1.1 200 OK 639 Content-Type: application/json 640 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 642 10.3. Server Returns Partial Representation Data 644 In this example, the client makes a range request and the server 645 responds with partial content. The "Digest" field-value represents 646 the entire JSON object "{"hello": "world"}". 648 Request: 650 GET /items/123 HTTP/1.1 651 Host: foo.example 652 Range: bytes=1-7 654 Response: 656 HTTP/1.1 206 Partial Content 657 Content-Type: application/json 658 Content-Range: bytes 1-7/18 659 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 661 "hello" 663 10.4. Client and Server Provide Full Representation Data 665 The request contains a "Digest" field-value calculated on the 666 enclosed representation. It also includes an "Accept-Encoding: br" 667 header field that advertises the client supports brotli encoding. 669 The response includes a "Content-Encoding: br" that indicates the 670 selected representation is brotli encoded. The "Digest" field-value 671 is therefore different compared to the request. 673 For presentation purposes, the response body is displayed as a 674 base64-encoded string because it contains non-printable characters. 676 Request: 678 PUT /items/123 HTTP/1.1 679 Host: foo.example 680 Content-Type: application/json 681 Accept-Encoding: br 682 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 684 {"hello": "world"} 686 Response: 688 HTTP/1.1 200 Ok 689 Content-Type: application/json 690 Content-Location: /items/123 691 Content-Encoding: br 692 Content-Length: 22 693 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 695 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 697 10.5. Client Provides Full Representation Data, Server Provides No 698 Representation Data 700 The request "Digest" field-value is calculated on the enclosed 701 payload. 703 The response "Digest" field-value depends on the representation 704 metadata header fields, including "Content-Encoding: br" even when 705 the response does not contain content. 707 Request: 709 PUT /items/123 HTTP/1.1 710 Host: foo.example 711 Content-Type: application/json 712 Content-Length: 18 713 Accept-Encoding: br 714 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 716 {"hello": "world"} 718 Response: 720 HTTP/1.1 204 No Content 721 Content-Type: application/json 722 Content-Encoding: br 723 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 725 10.6. Client and Server Provide Full Representation Data, Client Uses 726 id-sha-256. 728 The response contains two digest values: 730 * one with no content coding applied, which in this case 731 accidentally matches the unencoded digest-value sent in the 732 request; 734 * one taking into account the "Content-Encoding". 736 As the response body contains non-printable characters, it is 737 displayed as a base64-encoded string. 739 Request: 741 PUT /items/123 HTTP/1.1 742 Host: foo.example 743 Content-Type: application/json 744 Accept-Encoding: br 745 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 747 {"hello": "world"} 749 Response: 751 HTTP/1.1 200 OK 752 Content-Type: application/json 753 Content-Encoding: br 754 Content-Location: /items/123 755 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 756 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 758 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 760 10.7. POST Response does not Reference the Request URI 762 The request "Digest" field-value is computed on the enclosed 763 representation (see Section 6). 765 The representation enclosed in the response refers to the resource 766 identified by "Content-Location" (see [SEMANTICS], Section 6.4.2). 767 "Digest" is thus computed on the enclosed representation. 769 Request: 771 POST /books HTTP/1.1 772 Host: foo.example 773 Content-Type: application/json 774 Accept: application/json 775 Accept-Encoding: identity 776 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 778 {"title": "New Title"} 780 Response: 782 HTTP/1.1 201 Created 783 Content-Type: application/json 784 Content-Location: /books/123 785 Location: /books/123 786 Digest: id-sha-256=yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE= 788 { 789 "id": "123", 790 "title": "New Title" 791 } 793 Note that a "204 No Content" response without content but with the 794 same "Digest" field-value would have been legitimate too. 796 10.8. POST Response Describes the Request Status 798 The request "Digest" field-value is computed on the enclosed 799 representation (see Section 6). 801 The representation enclosed in the response describes the status of 802 the request, so "Digest" is computed on that enclosed representation. 804 Response "Digest" has no explicit relation with the resource 805 referenced by "Location". 807 Request: 809 POST /books HTTP/1.1 810 Host: foo.example 811 Content-Type: application/json 812 Accept: application/json 813 Accept-Encoding: identity 814 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 815 Location: /books/123 817 {"title": "New Title"} 819 Response: 821 HTTP/1.1 201 Created 822 Content-Type: application/json 823 Digest: id-sha-256=2LBp5RKZGpsSNf8BPXlXrX4Td4Tf5R5bZ9z7kdi5VvY= 824 Location: /books/123 826 { 827 "status": "created", 828 "id": "123", 829 "ts": 1569327729, 830 "instance": "/books/123" 831 } 833 10.9. Digest with PATCH 835 This case is analogous to a POST request where the target resource 836 reflects the effective request URI. 838 The PATCH request uses the "application/merge-patch+json" media type 839 defined in [RFC7396]. 841 "Digest" is calculated on the enclosed payload, which corresponds to 842 the patch document. 844 The response "Digest" field-value is computed on the complete 845 representation of the patched resource. 847 Request: 849 PATCH /books/123 HTTP/1.1 850 Host: foo.example 851 Content-Type: application/merge-patch+json 852 Accept: application/json 853 Accept-Encoding: identity 854 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 856 {"title": "New Title"} 858 Response: 860 HTTP/1.1 200 OK 861 Content-Type: application/json 862 Digest: id-sha-256=yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE= 864 { 865 "id": "123", 866 "title": "New Title" 867 } 869 Note that a "204 No Content" response without content but with the 870 same "Digest" field-value would have been legitimate too. 872 10.10. Error responses 874 In error responses, the representation-data does not necessarily 875 refer to the target resource. Instead, it refers to the 876 representation of the error. 878 In the following example a client attempts to patch the resource 879 located at /books/123. However, the resource does not exist and the 880 server generates a 404 response with a body that describes the error 881 in accordance with [RFC7807]. 883 The response "Digest" field-value is computed on this enclosed 884 representation. 886 Request: 888 PATCH /books/123 HTTP/1.1 889 Host: foo.example 890 Content-Type: application/merge-patch+json 891 Accept: application/json 892 Accept-Encoding: identity 893 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 895 {"title": "New Title"} 897 Response: 899 HTTP/1.1 404 Not Found 900 Content-Type: application/problem+json 901 Digest: sha-256=KPqhVXAT25LLitV1w0O167unHmVQusu+fpxm65zAsvk= 903 { 904 "title": "Not Found", 905 "detail": "Cannot PATCH a non-existent resource", 906 "status": 404 907 } 909 10.11. Use with Trailer Fields and Transfer Coding 911 An origin server sends "Digest" as trailer field, so it can calculate 912 digest-value while streaming content and thus mitigate resource 913 consumption. The "Digest" field-value is the same as in Section 10.1 914 because "Digest" is designed to be independent from the use of one or 915 more transfer codings (see Section 2). 917 Request: 919 GET /items/123 HTTP/1.1 920 Host: foo.example 922 Response: 924 HTTP/1.1 200 OK 925 Content-Type: application/json 926 Transfer-Encoding: chunked 927 Trailer: Digest 929 8\r\n 930 {"hello"\r\n 931 8 932 : "world\r\n 933 2\r\n 934 "}\r\n 935 0\r\n 936 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 938 11. Examples of Want-Digest Solicited Digest 940 The following examples demonstrate interactions where a client 941 solicits a "Digest" using "Want-Digest". 943 Some examples include JSON objects in the content. For presentation 944 purposes, objects that fit completely within the line-length limits 945 are presented on a single line using compact notation with no leading 946 space. Objects that would exceed line-length limits are presented 947 across multiple lines (one line per key-value pair) with 2 spaced of 948 leading indentation. 950 "Digest" is media-type agnostic and does not provide canonicalization 951 algorithms for specific formats. Examples of "Digest" are calculated 952 inclusive of any space. 954 11.1. Server Selects Client's Least Preferred Algorithm 956 The client requests a digest, preferring "sha". The server is free 957 to reply with "sha-256" anyway. 959 Request: 961 GET /items/123 HTTP/1.1 962 Host: foo.example 963 Want-Digest: sha-256;q=0.3, sha;q=1 965 Response: 967 HTTP/1.1 200 OK 968 Content-Type: application/json 969 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 971 {"hello": "world"} 973 11.2. Server Selects Algorithm Unsupported by Client 975 The client requests a "sha" digest only. The server is currently 976 free to reply with a Digest containing an unsupported algorithm. 978 Request: 980 GET /items/123 HTTP/1.1 981 Host: foo.example 982 Want-Digest: sha;q=1 984 Response: 986 HTTP/1.1 200 OK 987 Content-Type: application/json 988 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 989 +AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 991 {"hello": "world"} 993 11.3. Server Does Not Support Client Algorithm and Returns an Error 995 The client requests a "sha" Digest, the server advises "sha-256" and 996 "sha-512". 998 Request: 1000 GET /items/123 HTTP/1.1 1001 Host: foo.example 1002 Want-Digest: sha;q=1 1004 Response: 1006 HTTP/1.1 400 Bad Request 1007 Want-Digest: sha-256, sha-512 1009 12. Security Considerations 1011 12.1. Digest Does Not Protect the Full HTTP Message 1013 This document specifies a data integrity mechanism that protects HTTP 1014 "representation data", but not HTTP "representation metadata" fields, 1015 from certain kinds of accidental corruption. 1017 "Digest" is not intended to be a general protection against malicious 1018 tampering with HTTP messages. This can be achieved by combining it 1019 with other approaches such as transport-layer security or digital 1020 signatures. 1022 12.2. Broken Cryptographic Algorithms 1024 Cryptographic algorithms are intended to provide a proof of integrity 1025 suited towards cryptographic constructions such as signatures. 1027 However, these rely on collision-resistance for their security proofs 1028 [CMU-836068]. The "md5" and "sha" digest-algorithms are vulnerable 1029 to collisions attacks, so they MUST NOT be used with "Digest". 1031 12.3. Other Deprecated Algorithms 1033 The ADLER32 algorithm defined in [RFC1950] has been deprecated by 1034 [RFC3309] because, under certain conditions, it provides weak 1035 detection of errors. It is now NOT RECOMMENDED for use with 1036 "Digest". 1038 12.4. Digest for End-to-End Integrity 1040 "Digest" only covers the "representation data" and not the 1041 "representation metadata". "Digest" could help protect the 1042 "representation data" from buggy manipulation, undesired 1043 "transforming proxies" (see Section 7.7 of [SEMANTICS]) or other 1044 actions as the data passes across multiple hops or system boundaries. 1045 Even a simple mechanism for end-to-end "representation data" 1046 integrity is valuable because user-agent can validate that resource 1047 retrieval succeeded before handing off to a HTML parser, video player 1048 etc. for parsing. 1050 Identity digest-algorithms (e.g. "id-sha-256" and "id-sha-512") are 1051 particularly useful for end-to-end integrity because they allow 1052 piecing together a resource from different sources with different 1053 HTTP messaging characteristics. For example, different servers that 1054 apply different content codings. 1056 Note that using "Digest" alone does not provide end-to-end integrity 1057 of HTTP messages over multiple hops, since metadata could be 1058 manipulated at any stage. Methods to protect metadata are discussed 1059 in Section 12.6. 1061 12.5. Digest and Content-Location in Responses 1063 When a state-changing method returns the "Content-Location" header 1064 field, the enclosed representation refers to the resource identified 1065 by its value and "Digest" is computed accordingly. 1067 12.6. Usage in Signatures 1069 Digital signatures are widely used together with checksums to provide 1070 the certain identification of the origin of a message [NIST800-32]. 1071 Such signatures can protect one or more HTTP fields and there are 1072 additional considerations when "Digest" is included in this set. 1074 Since the "Digest" field is a hash of a resource representation, it 1075 explicitly depends on the "representation metadata" (eg. the values 1076 of "Content-Type", "Content-Encoding" etc). A signature that 1077 protects "Digest" but not other "representation metadata" can expose 1078 the communication to tampering. For example, an actor could 1079 manipulate the "Content-Type" field-value and cause a digest 1080 validation failure at the recipient, preventing the application from 1081 accessing the representation. Such an attack consumes the resources 1082 of both endpoints. See also Section 12.5. 1084 "Digest" SHOULD always be used over a connection that provides 1085 integrity at the transport layer that protects HTTP fields. 1087 A "Digest" field using NOT RECOMMENDED digest-algorithms SHOULD NOT 1088 be used in signatures. 1090 Using signatures to protect the "Digest" of an empty representation 1091 allows receiving endpoints to detect if an eventual payload has been 1092 stripped or added. 1094 Any mangling of "Digest", including de-duplication of representation- 1095 data-digest values or combining different field values (see 1096 Section 5.2 of [SEMANTICS]) might affect signature validation. 1098 12.7. Usage in Trailer Fields 1100 When "Digest" is used in trailer fields, the receiver gets the digest 1101 value after the content and may thus be tempted to process the data 1102 before validating the digest value. It is prefereable that data is 1103 only be processed after validating the Digest. 1105 If received in trailers, "Digest" MUST NOT be discarded; instead, it 1106 MAY be merged in the header section (See Section 6.5.1 of 1107 [SEMANTICS]). 1109 Not every digest-algorithm is suitable for use in the trailer 1110 section, some may require to pre-process the whole payload before 1111 sending a message (eg. see [I-D.thomson-http-mice]). 1113 12.8. Usage with Encryption 1115 "Digest" may expose details of encrypted payload when the checksum is 1116 computed on the unencrypted data. For example, the use of the "id- 1117 sha-256" digest-algorithm in conjunction with the encrypted content- 1118 coding [RFC8188]. 1120 The representation-data-digest of an encrypted payload can change 1121 between different messages depending on the encryption algorithm 1122 used; in those cases its value could not be used to provide a proof 1123 of integrity "at rest" unless the whole (e.g. encoded) content is 1124 persisted. 1126 12.9. Algorithm Agility 1128 The security properties of digest-algorithms are not fixed. 1129 Algorithm Agility (see [RFC7696]) is achieved by providing 1130 implementations with flexibility choose digest-algorithms from the 1131 IANA Digest Algorithm Values registry in Section 13.1. 1133 To help endpoints understand weaker algorithms from stronger ones, 1134 this document adds to the IANA Digest Algorithm Values registry a new 1135 "Status" field containing the most-recent appraisal of the digest- 1136 algorithm; the allowed values are specified in Section 13.2. 1138 An endpoint might have a preference for algorithms, such as 1139 preferring "standard" algorithms over "deprecated" ones. Transition 1140 from weak algorithms is supported by negotiation of digest-algorithm 1141 using "Want-Digest" (see Section 4) or by sending multiple 1142 representation-data-digest values from which the receiver chooses. 1143 Endpoints are advised that sending multiple values consumes 1144 resources, which may be wasted if the receiver ignores them (see 1145 Section 3). 1147 12.9.1. Duplicate digest-algorithm in field value 1149 An endpoint might receive multiple representation-data-digest values 1150 (see Section 3) that use the same digest-algorithm with different or 1151 identical digest-values. For example: 1153 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=, 1154 sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= 1156 A receiver is permitted to ignore any representation-data-digest 1157 value, so validation of duplicates is left as an implementation 1158 decision. Endpoints might select all, some or none of the values for 1159 checksum comparison and, based on the intersection of those results, 1160 conditionally pass or fail digest validation. 1162 12.10. Resource exhaustion 1164 "Digest" validation consumes computational resources. In order to 1165 avoid resource exhaustion, implementations can restrict validation of 1166 the algorithm types, number of validations, or the size of content. 1168 13. IANA Considerations 1170 13.1. Establish the HTTP Digest Algorithm Values Registry 1172 This memo sets this specification to be the establishing document for 1173 the HTTP Digest Algorithm Values (https://www.iana.org/assignments/ 1174 http-dig-alg/http-dig-alg.xhtml) registry. 1176 13.2. The "status" Field in the HTTP Digest Algorithm Values Registry 1178 This memo adds the field "Status" to the HTTP Digest Algorithm Values 1179 (https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml) 1180 registry. The allowed values for the "Status" fields are described 1181 below. 1183 Status 1184 * "standard" for standardized algorithms without known problems; 1186 * "experimental", "obsoleted" or some other appropriate value - 1187 e.g. according to the type and status of the primary document 1188 in which the algorithm is defined; 1190 * "deprecated" when the algorithm is insecure or otherwise 1191 undesirable. 1193 13.3. Deprecate "MD5" Digest Algorithm 1195 This memo updates the "MD5" digest-algorithm in the HTTP Digest 1196 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1197 dig-alg.xhtml) registry: 1199 * Digest Algorithm: md5 1201 * Description: As specified in Section 5. 1203 * Status: As specified in Section 5. 1205 13.4. Update "UNIXsum" Digest Algorithm 1207 This memo updates the "UNIXsum" digest-algorithm in the HTTP Digest 1208 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1209 dig-alg.xhtml) registry: 1211 * Digest Algorithm: As specified in Section 5. 1213 * Description: As specified in Section 5. 1215 * Status: As specified in Section 5. 1217 13.5. Update "UNIXcksum" Digest Algorithm 1219 This memo updates the "UNIXcksum" digest-algorithm in the HTTP Digest 1220 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1221 dig-alg.xhtml) registry: 1223 * Digest Algorithm: As specified in Section 5. 1225 * Description: As specified in Section 5. 1227 * Status: As specified in Section 5. 1229 13.6. Update "CRC32c" Digest Algorithm 1231 This memo updates the "CRC32c" digest-algorithm in the HTTP Digest 1232 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1233 dig-alg.xhtml) registry: 1235 * Digest Algorithm: crc32c 1237 * Description: The CRC32c algorithm is a 32-bit cyclic redundancy 1238 check. It achieves a better hamming distance (for better error- 1239 detection performance) than many other 32-bit CRC functions. 1240 Other places it is used include iSCSI and SCTP. The 32-bit output 1241 is encoded in hexadecimal (using between 1 and 8 ASCII characters 1242 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 1243 crc32c=0a72a4df and crc32c=A72A4DF are both valid checksums for 1244 the 3-byte message "dog". 1246 * Reference: [RFC4960] appendix B, this document. 1248 * Status: standard. 1250 13.7. Deprecate "SHA" Digest Algorithm 1252 This memo updates the "SHA" digest-algorithm in the HTTP Digest 1253 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1254 dig-alg.xhtml) registry: 1256 * Digest Algorithm: sha 1258 * Description: As specified in Section 5. 1260 * Status: As specified in Section 5. 1262 13.8. Obsolete "ADLER32" Digest Algorithm 1264 This memo updates the "ADLER32" digest-algorithm in the HTTP Digest 1265 Algorithm Values (https://www.iana.org/assignments/http-dig-alg/http- 1266 dig-alg.xhtml) registry: 1268 * Digest Algorithm: adler32 1270 * Description: The ADLER32 algorithm is a checksum specified in 1271 [RFC1950] "ZLIB Compressed Data Format". The 32-bit output is 1272 encoded in hexadecimal (using between 1 and 8 ASCII characters 1273 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 1274 adler32=03da0195 and adler32=3DA0195 are both valid checksums for 1275 the 4-byte message "Wiki". This algorithm is obsoleted and SHOULD 1276 NOT be used. 1278 * Status: obsoleted 1280 13.9. Obsolete "contentMD5" token in Digest Algorithm 1282 This memo adds the "contentMD5" token in the HTTP Digest Algorithm 1283 Values (https://www.iana.org/assignments/http-dig-alg/http-dig- 1284 alg.xhtml) registry: 1286 * Digest Algorithm: contentMD5 1288 * Description: Section 5 of [RFC3230] defined the "contentMD5" token 1289 to be used only in Want-Digest. This token is obsoleted and MUST 1290 NOT be used. 1292 * Reference: Section 13.9 of this document, Section 5 of [RFC3230]. 1294 * Status: obsoleted 1296 13.10. The "id-sha-256" Digest Algorithm 1298 This memo registers the "id-sha-256" digest-algorithm in the HTTP 1299 Digest Algorithm Values (https://www.iana.org/assignments/http-dig- 1300 alg/http-dig-alg.xhtml) registry: 1302 * Digest Algorithm: id-sha-256 1304 * Description: As specified in Section 5. 1306 * Status: As specified in Section 5. 1308 13.11. The "id-sha-512" Digest Algorithm 1310 This memo registers the "id-sha-512" digest-algorithm in the HTTP 1311 Digest Algorithm Values (https://www.iana.org/assignments/http-dig- 1312 alg/http-dig-alg.xhtml) registry: 1314 * Digest Algorithm: id-sha-512 1316 * Description: As specified in Section 5. 1318 * Status: As specified in Section 5. 1320 13.12. Changes Compared to RFC5843 1322 The digest-algorithm values for "MD5", "SHA", "SHA-256", "SHA-512", 1323 "UNIXcksum", "UNIXsum", "ADLER32" and "CRC32c" have been updated to 1324 lowercase. 1326 The status of "MD5" has been updated to "deprecated", and its 1327 description states that this algorithm MUST NOT be used. 1329 The status of "SHA" has been updated to "deprecated", and its 1330 description states that this algorithm MUST NOT be used. 1332 The status for "CRC2c", "UNIXsum" and "UNIXcksum" has been updated to 1333 "standard". 1335 The "id-sha-256" and "id-sha-512" algorithms have been added to the 1336 registry. 1338 13.13. Want-Digest Field Registration 1340 This section registers the "Want-Digest" field in the "Hypertext 1341 Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. 1343 Field name: "Want-Digest" 1345 Status: permanent 1347 Specification document(s): Section 4 of this document 1349 13.14. Digest Field Registration 1351 This section registers the "Digest" field in the "Hypertext Transfer 1352 Protocol (HTTP) Field Name Registry" [SEMANTICS]. 1354 Field name: "Digest" 1355 Status: permanent 1357 Specification document(s): Section 3 of this document 1359 14. References 1361 14.1. Normative References 1363 [CMU-836068] 1364 Carnagie Mellon University, Software Engineering 1365 Institute, "MD5 Vulnerable to collision attacks", 31 1366 December 2008, . 1368 [IACR-2020-014] 1369 Leurent, G. and T. Peyrin, "SHA-1 is a Shambles", 5 1370 January 2020, . 1372 [NIST800-32] 1373 National Institute of Standards and Technology, U.S. 1374 Department of Commerce, "Introduction to Public Key 1375 Technology and the Federal PKI Infrastructure", February 1376 2001, . 1379 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 1380 DOI 10.17487/RFC1321, April 1992, 1381 . 1383 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 1384 Specification version 3.3", RFC 1950, 1385 DOI 10.17487/RFC1950, May 1996, 1386 . 1388 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1389 Requirement Levels", BCP 14, RFC 2119, 1390 DOI 10.17487/RFC2119, March 1997, 1391 . 1393 [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 1394 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, 1395 . 1397 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 1398 RFC 3230, DOI 10.17487/RFC3230, January 2002, 1399 . 1401 [RFC3309] Stone, J., Stewart, R., and D. Otis, "Stream Control 1402 Transmission Protocol (SCTP) Checksum Change", RFC 3309, 1403 DOI 10.17487/RFC3309, September 2002, 1404 . 1406 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1407 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1408 . 1410 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1411 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1412 . 1414 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1415 Specifications: ABNF", STD 68, RFC 5234, 1416 DOI 10.17487/RFC5234, January 2008, 1417 . 1419 [RFC5843] Bryan, A., "Additional Hash Algorithms for HTTP Instance 1420 Digests", RFC 5843, DOI 10.17487/RFC5843, April 2010, 1421 . 1423 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 1424 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 1425 DOI 10.17487/RFC6234, May 2011, 1426 . 1428 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 1429 RFC 7405, DOI 10.17487/RFC7405, December 2014, 1430 . 1432 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1433 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1434 May 2017, . 1436 [SEMANTICS] 1437 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 1438 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1439 httpbis-semantics-15, 30 March 2021, 1440 . 1443 [UNIX] The Open Group, "The Single UNIX Specification, Version 2 1444 - 6 Vol Set for UNIX 98", February 1997. 1446 14.2. Informative References 1448 [HTTP11] Fielding, R. T., Nottingham, M., and J. Reschke, 1449 "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf- 1450 httpbis-messaging-15, 30 March 2021, 1451 . 1454 [I-D.ietf-httpbis-header-structure] 1455 Nottingham, M. and P. Kamp, "Structured Field Values for 1456 HTTP", Work in Progress, Internet-Draft, draft-ietf- 1457 httpbis-header-structure-19, 3 June 2020, 1458 . 1461 [I-D.thomson-http-mice] 1462 Thomson, M. and J. Yasskin, "Merkle Integrity Content 1463 Encoding", Work in Progress, Internet-Draft, draft- 1464 thomson-http-mice-03, 13 August 2018, 1465 . 1467 [NO-MD5] Turner, S. and L. Chen, "Updated Security Considerations 1468 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 1469 RFC 6151, DOI 10.17487/RFC6151, March 2011, 1470 . 1472 [NO-SHA1] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security 1473 Considerations for the SHA-0 and SHA-1 Message-Digest 1474 Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011, 1475 . 1477 [PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 1478 RFC 5789, DOI 10.17487/RFC5789, March 2010, 1479 . 1481 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 1482 DOI 10.17487/RFC2818, May 2000, 1483 . 1485 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1486 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1487 DOI 10.17487/RFC7231, June 2014, 1488 . 1490 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 1491 DOI 10.17487/RFC7396, October 2014, 1492 . 1494 [RFC7696] Housley, R., "Guidelines for Cryptographic Algorithm 1495 Agility and Selecting Mandatory-to-Implement Algorithms", 1496 BCP 201, RFC 7696, DOI 10.17487/RFC7696, November 2015, 1497 . 1499 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 1500 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 1501 . 1503 [RFC8188] Thomson, M., "Encrypted Content-Encoding for HTTP", 1504 RFC 8188, DOI 10.17487/RFC8188, June 2017, 1505 . 1507 [SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger, 1508 "Subresource Integrity", W3C Recommendation REC-SRI- 1509 20160623, 23 June 2016, 1510 . 1512 Appendix A. Resource Representation and Representation-Data 1514 The following examples show how representation metadata, payload 1515 transformations and method impacts on the message and content. When 1516 the content contains non-printable characters (eg. when it is 1517 compressed) it is shown as base64-encoded string. 1519 A request with a JSON object without any content coding. 1521 Request: 1523 PUT /entries/1234 HTTP/1.1 1524 Host: foo.example 1525 Content-Type: application/json 1527 {"hello": "world"} 1529 Here is a gzip-compressed JSON object using a content coding. 1531 Request: 1533 PUT /entries/1234 HTTP/1.1 1534 Host: foo.example 1535 Content-Type: application/json 1536 Content-Encoding: gzip 1538 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 1540 Now the same content conveys a malformed JSON object. 1542 Request: 1544 PUT /entries/1234 HTTP/1.1 1545 Host: foo.example 1546 Content-Type: application/json 1548 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 1550 A Range-Request alters the content, conveying a partial 1551 representation. 1553 Request: 1555 GET /entries/1234 HTTP/1.1 1556 Host: foo.example 1557 Range: bytes=1-7 1559 Response: 1561 HTTP/1.1 206 Partial Content 1562 Content-Encoding: gzip 1563 Content-Type: application/json 1564 Content-Range: bytes 1-7/18 1566 iwgAla3RXA== 1568 Now the method too alters the content. 1570 Request: 1572 HEAD /entries/1234 HTTP/1.1 1573 Host: foo.example 1574 Accept: application/json 1575 Accept-Encoding: gzip 1577 Response: 1579 HTTP/1.1 200 OK 1580 Content-Type: application/json 1581 Content-Encoding: gzip 1583 Finally the semantics of an HTTP response might decouple the 1584 effective request URI from the enclosed representation. In the 1585 example response below, the "Content-Location" header field indicates 1586 that the enclosed representation refers to the resource available at 1587 "/authors/123". 1589 Request: 1591 POST /authors/ HTTP/1.1 1592 Host: foo.example 1593 Accept: application/json 1594 Content-Type: application/json 1596 {"author": "Camilleri"} 1598 Response: 1600 HTTP/1.1 201 Created 1601 Content-Type: application/json 1602 Content-Location: /authors/123 1603 Location: /authors/123 1605 {"id": "123", "author": "Camilleri"} 1607 Appendix B. FAQ 1609 1. Why remove all references to content-md5? 1611 Those were unnecessary to understanding and using this 1612 specification. 1614 2. Why remove references to instance manipulation? 1616 Those were unnecessary for correctly using and applying the 1617 specification. An example with Range Request is more than 1618 enough. This document uses the term "partial representation" 1619 which should group all those cases. 1621 3. How to use "Digest" with "PATCH" method? 1623 See Section 6. 1625 4. Why remove references to delta-encoding? 1627 Unnecessary for a correct implementation of this specification. 1628 The revised specification can be nicely adapted to "delta 1629 encoding", but all the references here to delta encoding don't 1630 add anything to this RFC. Another job would be to refresh delta 1631 encoding. 1633 5. Why remove references to Digest Authentication? 1635 This specification seems to me completely unrelated to Digest 1636 Authentication but for the word "Digest". 1638 6. What changes in "Want-Digest"? 1639 The contentMD5 token defined in Section 5 of [RFC3230] is 1640 deprecated by Section 7. 1642 To clarify that "Digest" and "Want-Digest" can be used in both 1643 requests and responses - [RFC3230] carefully uses "sender" and 1644 "receiver" in their definition - we added examples on using 1645 "Want-Digest" in responses to advertise the supported digest- 1646 algorithms and the inability to accept requests with unsupported 1647 digest-algorithms. 1649 7. Does this specification change supported algorithms? 1651 Yes. This RFC updates [RFC5843] which is still delegated for all 1652 algorithms updates, and adds two more algorithms: "id-sha-256" 1653 and "id-sha-512" which allows to send a checksum of a resource 1654 representation with no content codings applied. To simplify a 1655 future transition to Structured Fields 1656 [I-D.ietf-httpbis-header-structure] we suggest to use lowercase 1657 for digest-algorithms. 1659 8. What about mid-stream trailer fields? 1661 While mid-stream trailer fields (https://github.com/httpwg/http- 1662 core/issues/313#issuecomment-584389706) are interesting, since 1663 this specification is a rewrite of [RFC3230] we do not think we 1664 should face that. As a first thought, nothing in this document 1665 precludes future work that would find a use for mid-stream 1666 trailers, for example an incremental digest-algorithm. A 1667 document defining such a digest-algorithm is best positioned to 1668 describe how it is used. 1670 Acknowledgements 1672 The vast majority of this document is inherited from [RFC3230], so 1673 thanks to J. Mogul and A. Van Hoff for their great work. The 1674 original idea of refreshing this document arose from an interesting 1675 discussion with M. Nottingham, J. Yasskin and M. Thomson when 1676 reviewing the MICE content coding. 1678 Code Samples 1680 _RFC Editor: Please remove this section before publication._ 1682 How can I generate and validate the "Digest" values shown in the 1683 examples throughout this document? 1684 The following python3 code can be used to generate digests for JSON 1685 objects using SHA algorithms for a range of encodings. Note that 1686 these are formatted as base64. This function could be adapted to 1687 other algorithms and should take into account their specific 1688 formatting rules. 1690 import base64, json, hashlib, brotli, logging 1691 log = logging.getLogger() 1693 def encode_item(item, encoding=lambda x: x): 1694 indent = 2 if isinstance(item, dict) and len(item) > 1 else None 1695 json_bytes = json.dumps(item, indent=indent).encode() 1696 return encoding(json_bytes) 1698 def digest_bytes(bytes_, algorithm=hashlib.sha256): 1699 checksum_bytes = algorithm(bytes_).digest() 1700 log.warning("Log bytes: \n[%r]", bytes_) 1701 return base64.encodebytes(checksum_bytes).strip() 1703 def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): 1704 content_encoded = encode_item(item, encoding) 1705 return digest_bytes(content_encoded, algorithm) 1707 item = {"hello": "world"} 1709 print("Encoding | digest-algorithm | digest-value") 1710 print("Identity | sha256 |", digest(item)) 1711 # Encoding | digest-algorithm | digest-value 1712 # Identity | sha256 | X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1714 print("Encoding | digest-algorithm | digest-value") 1715 print("Brotli | sha256 |", digest(item, encoding=brotli.compress)) 1716 # Encoding | digest-algorithm | digest-value 1717 # Brotli | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1719 print("Encoding | digest-algorithm | digest-value") 1720 print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512)) 1721 # Encoding | digest-algorithm | digest-value 1722 # Identity | sha512 | b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm' 1723 # '+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==' 1725 Changes 1727 _RFC Editor: Please remove this section before publication._ 1729 Since draft-ietf-httpbis-digest-headers-04 1731 * Improve SRI section #1354 1733 * About duplicate digest-algorithms #1221 1735 * Improve security considerations #852 1737 * md5 and sha deprecation references #1392 1739 * Obsolete 3230 #1395 1741 * Editorial #1362 1743 Since draft-ietf-httpbis-digest-headers-03 1745 * Reference semantics-12 1747 * Detail encryption quirks 1749 * Details on Algorithm agility #1250 1751 * Obsolete parameters #850 1753 Since draft-ietf-httpbis-digest-headers-02 1755 * Deprecate SHA-1 #1154 1757 * Avoid id-* with encrypted content 1759 * Digest is independent from MESSAGING and HTTP/1.1 is not normative 1760 #1215 1762 * Identity is not a valid field value for content-encoding #1223 1764 * Mention trailers #1157 1766 * Reference httpbis-semantics #1156 1768 * Add contentMD5 as an obsoleted digest-algorithm #1249 1770 * Use lowercase digest-algorithms names in the doc and in the 1771 digest-algorithm IANA table. 1773 Since draft-ietf-httpbis-digest-headers-01 1775 * Digest of error responses is computed on the error representation- 1776 data #1004 1778 * Effect of HTTP semantics on payload and message body moved to 1779 appendix #1122 1781 * Editorial refactoring, moving headers sections up. #1109-#1112, 1782 #1116, #1117, #1122-#1124 1784 Since draft-ietf-httpbis-digest-headers-00 1786 * Align title with document name 1788 * Add id-sha-* algorithm examples #880 1790 * Reference [RFC6234] and [RFC3174] instead of FIPS-1 1792 * Deprecate MD5 1794 * Obsolete ADLER-32 but don't forbid it #828 1796 * Update CRC32C value in IANA table #828 1798 * Use when acting on resources (POST, PATCH) #853 1800 * Added Relationship with SRI, draft Use Cases #868, #971 1802 * Warn about the implications of "Content-Location" 1804 Authors' Addresses 1806 Roberto Polli 1807 Team Digitale, Italian Government 1808 Italy 1810 Email: robipolli@gmail.com 1812 Lucas Pardue 1813 Cloudflare 1815 Email: lucaspardue.24.7@gmail.com