idnits 2.17.00 (12 Aug 2021) /tmp/idnits9452/draft-ietf-httpbis-digest-headers-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (27 September 2021) is 236 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 ** Downref: Normative reference to an Informational RFC: RFC 5843 ** Downref: Normative reference to an Informational RFC: RFC 6234 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNIX' == Outdated reference: draft-ietf-httpbis-header-structure has been published as RFC 8941 Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 7 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: 31 March 2022 27 September 2021 8 Digest Fields 9 draft-ietf-httpbis-digest-headers-06 11 Abstract 13 This document defines HTTP fields that support integrity checksums. 14 The Digest field can be used for the integrity of HTTP 15 representations. The Content-Digest field can be used for the 16 integrity of HTTP message content. Want-Digest and Want-Content- 17 Digest can be used to indicate a sender's desire to receive integrity 18 fields respectively. 20 This document obsoletes RFC 3230. 22 Note to Readers 24 _RFC EDITOR: please remove this section before publication_ 26 Discussion of this draft takes place on the HTTP working group 27 mailing list (ietf-http-wg@w3.org), which is archived at 28 https://lists.w3.org/Archives/Public/ietf-http-wg/ 29 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 31 The source code and issues list for this draft can be found at 32 https://github.com/httpwg/http-extensions (https://github.com/httpwg/ 33 http-extensions). 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on 31 March 2022. 51 Copyright Notice 53 Copyright (c) 2021 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 58 license-info) in effect on the date of publication of this document. 59 Please review these documents carefully, as they describe your rights 60 and restrictions with respect to this document. Code Components 61 extracted from this document must include Simplified BSD License text 62 as described in Section 4.e of the Trust Legal Provisions and are 63 provided without warranty as described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.1. Document Structure . . . . . . . . . . . . . . . . . . . 4 69 1.2. Concept Overview . . . . . . . . . . . . . . . . . . . . 4 70 1.3. Replacing RFC 3230 . . . . . . . . . . . . . . . . . . . 5 71 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 6 72 2. Representation Digest . . . . . . . . . . . . . . . . . . . . 6 73 3. The Digest Field . . . . . . . . . . . . . . . . . . . . . . 7 74 4. The Content-Digest Field . . . . . . . . . . . . . . . . . . 8 75 5. Want-Digest and Want-Content-Digest Fields . . . . . . . . . 8 76 6. Digest Algorithm Values . . . . . . . . . . . . . . . . . . . 9 77 7. Using Digest in State-Changing Requests . . . . . . . . . . . 13 78 7.1. Digest and Content-Location in Responses . . . . . . . . 13 79 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 80 8.1. Digest Does Not Protect the Full HTTP Message . . . . . . 13 81 8.2. Digest for End-to-End Integrity . . . . . . . . . . . . . 14 82 8.3. Usage in Signatures . . . . . . . . . . . . . . . . . . . 14 83 8.4. Usage in Trailer Fields . . . . . . . . . . . . . . . . . 15 84 8.5. Usage with Encryption . . . . . . . . . . . . . . . . . . 15 85 8.6. Algorithm Agility . . . . . . . . . . . . . . . . . . . . 15 86 8.7. Duplicate digest-algorithm in field value . . . . . . . . 16 87 8.8. Resource exhaustion . . . . . . . . . . . . . . . . . . . 16 88 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 89 9.1. Establish the HTTP Digest Algorithm Values Registry . . . 16 90 9.2. Obsolete "contentMD5" token in Digest Algorithm . . . . . 17 91 9.3. Changes Compared to RFC3230 . . . . . . . . . . . . . . . 17 92 9.4. Changes Compared to RFC5843 . . . . . . . . . . . . . . . 17 93 9.5. Want-Digest Field Registration . . . . . . . . . . . . . 17 94 9.6. Digest Field Registration . . . . . . . . . . . . . . . . 18 95 9.7. Want-Content-Digest Field Registration . . . . . . . . . 18 96 9.8. Content-Digest Field Registration . . . . . . . . . . . . 18 98 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 99 10.1. Normative References . . . . . . . . . . . . . . . . . . 18 100 10.2. Informative References . . . . . . . . . . . . . . . . . 20 101 Appendix A. Resource Representation and Representation-Data . . 22 102 Appendix B. Examples of Unsolicited Digest . . . . . . . . . . . 24 103 B.1. Server Returns Full Representation Data . . . . . . . . . 24 104 B.2. Server Returns No Representation Data . . . . . . . . . . 24 105 B.3. Server Returns Partial Representation Data . . . . . . . 25 106 B.4. Client and Server Provide Full Representation Data . . . 25 107 B.5. Client Provides Full Representation Data, Server Provides 108 No Representation Data . . . . . . . . . . . . . . . . . 26 109 B.6. Client and Server Provide Full Representation Data, Client 110 Uses id-sha-256. . . . . . . . . . . . . . . . . . . . . 27 111 B.7. POST Response does not Reference the Request URI . . . . 27 112 B.8. POST Response Describes the Request Status . . . . . . . 28 113 B.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . . 29 114 B.10. Error responses . . . . . . . . . . . . . . . . . . . . . 30 115 B.11. Use with Trailer Fields and Transfer Coding . . . . . . . 30 116 Appendix C. Examples of Want-Digest Solicited Digest . . . . . . 31 117 C.1. Server Selects Client's Least Preferred Algorithm . . . . 31 118 C.2. Server Selects Algorithm Unsupported by Client . . . . . 32 119 C.3. Server Does Not Support Client Algorithm and Returns an 120 Error . . . . . . . . . . . . . . . . . . . . . . . . . . 32 121 Appendix D. Changes from RFC3230 . . . . . . . . . . . . . . . . 32 122 D.1. Deprecate Negotiation of Content-MD5 . . . . . . . . . . 33 123 D.2. Obsolete Digest Field Parameters . . . . . . . . . . . . 33 124 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 33 125 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 126 Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 35 127 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 128 Since draft-ietf-httpbis-digest-headers-05 . . . . . . . . . . 36 129 Since draft-ietf-httpbis-digest-headers-04 . . . . . . . . . . 37 130 Since draft-ietf-httpbis-digest-headers-03 . . . . . . . . . . 37 131 Since draft-ietf-httpbis-digest-headers-02 . . . . . . . . . . 37 132 Since draft-ietf-httpbis-digest-headers-01 . . . . . . . . . . 37 133 Since draft-ietf-httpbis-digest-headers-00 . . . . . . . . . . 38 134 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 136 1. Introduction 138 HTTP does not define a means to protect the integrity of 139 representations. When HTTP messages are transferred between 140 endpoints, the protocol might choose to make use of features of the 141 lower layer in order to provide some integrity protection; for 142 instance, TCP checksums or TLS records [RFC2818]. 144 This document defines two digest integrity mechanisms for HTTP. 145 First, representation data integrity, which acts on representation 146 data (Section 3.2 of [SEMANTICS]). Second, content digest integrity, 147 which acts on conveyed content (Section 6.4 of [SEMANTICS]). Both 148 mechanisms operate independent of transport integrity, offering the 149 potential to detect programming errors and corruption of data in 150 flight or at rest. They can be used across multiple hops in order to 151 provide end-to-end integrity guarantees, which can aid fault 152 diagnosis when resources are transferred across hops and system 153 boundaries. Finally, they can be used to validate integrity when 154 reconstructing a resource fetched using different HTTP connections. 156 This document obsoletes [RFC3230]. 158 1.1. Document Structure 160 This document is structured as follows: 162 * Section 2 describes concepts related to representation digests, 164 * Section 3 defines the Digest request and response header and 165 trailer field, 167 * Section 4 defines the Content-Digest request and response header 168 and trailer field, 170 * Section 5 defines the Want-Digest and Want-Content-Digest request 171 and response header and trailer field, 173 * Section 6 and Appendix D.1 describe algorithms and their relation 174 to Digest, 176 * Section 7 details computing representation digests, 178 * Appendix D.2 obsoletes Digest field parameters, and 180 * Appendix B and Appendix C provide examples of using Digest and 181 Want-Digest. 183 1.2. Concept Overview 185 This document defines the Digest request and response header and 186 trailer field; see Section 3. At a high level, the value contains a 187 checksum, computed over selected representation data (Section 3.2 of 188 [SEMANTICS]), that the recipient can use to validate integrity. 189 Basing Digest on the selected representation makes it straightforward 190 to apply it to use-cases where the transferred data requires some 191 sort of manipulation to be considered a representation or conveys a 192 partial representation of a resource, such as Range Requests (see 193 Section 14.2 of [SEMANTICS]). 195 To support use-cases where a simple checksum of the content bytes is 196 required, this document introduces the Content-Digest request and 197 response header and trailer field; see Section 4. 199 Digest and Content-Digest support algorithm agility. The Want-Digest 200 and Want-Content-Digest fields allows endpoints to express interest 201 in Digest and Content-Digest respectively, and preference of 202 algorithms in either. 204 Digest field calculations are tied to the Content-Encoding and 205 Content-Type header fields. Therefore, a given resource may have 206 multiple different checksum values when transferred with HTTP. To 207 allow both parties to exchange a simple checksum with no content 208 codings (see Section 8.4.1 of [SEMANTICS]), two more digest- 209 algorithms are added ("id-sha-256" and "id-sha-512"). 211 Digest fields do not provide integrity for HTTP messages or fields. 212 However, they can be combined with other mechanisms that protect 213 metadata, such as digital signatures, in order to protect the phases 214 of an HTTP exchange in whole or in part. 216 This specification does not define means for authentication, 217 authorization or privacy. 219 1.3. Replacing RFC 3230 221 Historically, the Content-MD5 header field provided an HTTP integrity 222 mechanism but HTTP/1.1 ([RFC7231], Appendix B) obsoleted it due to 223 inconsistent handling of partial responses. [RFC3230] defined the 224 concept of "instance" digests and a more flexible integrity scheme to 225 help address issues with Content-MD5. It first introduced the Digest 226 and Want-Digest fields. HTTP terminology has evolved since [RFC3230] 227 was published. The concept of "instance" has been superseded by 228 selected representation. 230 This document replaces [RFC3230]. The Digest and Want-Digest field 231 definitions are updated to align with the terms and notational 232 conventions in [SEMANTICS]. Changes are intended to be semantically 233 compatible with existing implementations but note that negotiation of 234 Content-MD5 is deprecated Appendix D.1 and has been replaced by 235 Content-Digest negotiation via Want-Content-Digest. Digest field 236 parameters are obsoleted Appendix D.2 and the algorithm table has 237 been updated to reflect the current state of the art. 239 1.4. Notational Conventions 241 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 242 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 243 "OPTIONAL" in this document are to be interpreted as described in 244 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 245 capitals, as shown here. 247 This document uses the Augmented BNF defined in [RFC5234] and updated 248 by [RFC7405] along with the "#rule" extension defined in 249 Section 5.6.1 of [SEMANTICS] and the "qvalue" rule defined in 250 Section 12.4.2 of [SEMANTICS]. 252 The definitions "representation", "selected representation", 253 "representation data", "representation metadata", and "content" in 254 this document are to be interpreted as described in [SEMANTICS]. 256 Algorithm names respect the casing used in their definition document 257 (e.g. SHA-1, CRC32c) whereas digest-algorithm tokens are quoted 258 (e.g. "sha", "crc32c"). 260 2. Representation Digest 262 The representation digest is an integrity mechanism for HTTP 263 resources which uses a checksum that is calculated independently of 264 the content (see Section 6.4 of [SEMANTICS]). It uses the 265 representation data (see Section 8.1 of [SEMANTICS]), that can be 266 fully or partially contained in the content, or not contained at all. 268 This takes into account the effect of the HTTP semantics on the 269 messages; for example, the content can be affected by Range Requests 270 or methods such as HEAD, while the way the content is transferred "on 271 the wire" is dependent on other transformations (e.g. transfer 272 codings for HTTP/1.1 - see Section 6.1 of [HTTP11]). To help 273 illustrate how such things affect Digest, several examples are 274 provided in Appendix A. 276 A representation digest consists of the value of a checksum computed 277 on the entire selected representation data (see Section 8.1 of 278 [SEMANTICS]) of a resource identified according to Section 6.4.2 of 279 [SEMANTICS] together with an indication of the algorithm used: 281 representation-data-digest = digest-algorithm "=" 282 284 When a message has no representation data it is still possible to 285 assert that no representation data was sent computing the 286 representation digest on an empty string (see Section 8.3). 288 The checksum is computed using one of the digest-algorithms listed in 289 the HTTP Digest Algorithm Values Registry (see Section 6) and then 290 encoded in the associated format. 292 3. The Digest Field 294 The Digest field contains a comma-separated list of one or more 295 representation digest values as defined in Section 2. It can be used 296 in both requests and responses. 298 Digest = 1#representation-data-digest 300 For example: 302 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 303 AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 305 A Digest field MAY contain multiple representation-data-digest 306 values. For example, a server may provide representation-data-digest 307 values using different algorithms, allowing it to support a 308 population of clients with different evolving capabilities; this is 309 particularly useful in support of transitioning away from weaker 310 algorithms should the need arise (see Section 8.6). 312 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 313 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 315 A recipient MAY ignore any or all of the representation-data-digests 316 in a Digest field. This allows the recipient to choose which digest- 317 algorithm(s) to use for validation instead of verifying every 318 received representation-data-digest. 320 A sender MAY send a representation-data-digest using a digest- 321 algorithm without knowing whether the recipient supports the digest- 322 algorithm, or even knowing that the recipient will ignore it. 324 Digest can be sent in a trailer section. In this case, Digest MAY be 325 merged into the header section; see Section 6.5.1 of [SEMANTICS]. 327 When an incremental digest-algorithm is used, the sender and the 328 receiver can dynamically compute the digest value while streaming the 329 content. 331 A non-comprehensive set of examples showing the impacts of 332 representation metadata, payload transformations and HTTP methods on 333 Digest is provided in Appendix B and Appendix C. 335 4. The Content-Digest Field 337 The Content-Digest field contains a comma-separated list of one or 338 more content digest values. A content digest value is computed by 339 applying a digest-algorithm to the actual message content (see 340 Section 6.4 of [SEMANTICS]). It can be used in both requests and 341 responses. 343 Content-Digest = 1#content-digest 344 content-digest = digest-algorithm "=" 345 347 For example: 349 Content-Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 350 AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 352 A Content-Digest field MAY contain multiple content-digest values, 353 similarly to Digest (see Section 3) 355 Content-Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 356 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 358 A recipient MAY ignore any or all of the content-digests in a 359 Content-Digest field. This allows the recipient to choose which 360 digest-algorithm(s) to use for validation instead of verifying every 361 received content-digest. 363 A sender MAY send a content-digest using a digest-algorithm without 364 knowing whether the recipient supports the digest-algorithm, or even 365 knowing that the recipient will ignore it. 367 Content-Digest can be sent in a trailer section. In this case, 368 Content-Digest MAY be merged into the header section; see 369 Section 6.5.1 of [SEMANTICS]. 371 When an incremental digest-algorithm is used, the sender and the 372 receiver can dynamically compute the digest value while streaming the 373 content. 375 5. Want-Digest and Want-Content-Digest Fields 377 Senders can indicate their integrity checksum preferences using the 378 Want-Digest or Want-Content-Digest fields. These can be used in both 379 requests and responses. 381 Want-Digest indicates the sender's desire to receive a representation 382 digest on messages associated with the request URI and representation 383 metadata, using the Digest field. 385 Want-Content-Digest indicates the sender's desire to receive a 386 content digest on messages associated with the request URI and 387 representation metadata, using the Content-Digest field. 389 Want-Digest = 1#want-digest-value 390 Want-Content-Digest = 1#want-digest-value 391 want-digest-value = digest-algorithm [ ";" "q" "=" qvalue] 393 qvalue indicates the sender's digest-algorithm preferences. 394 Section 12.4.2 of [SEMANTICS]) describes qvalue usage and semantics. 396 Senders can provide multiple digest-algorithm items with the same 397 qvalue. 399 Examples: 401 Want-Digest: sha-256 402 Want-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0 403 Want-Content-Digest: sha-256 404 Want-Content-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0 406 6. Digest Algorithm Values 408 Digest-algorithm values are used to indicate a specific digest 409 computation. 411 digest-algorithm = token 413 All digest-algorithm token values are case-insensitive but lower case 414 is preferred; digest-algorithm token values MUST be compared in a 415 case-insensitive fashion. 417 Every digest-algorithm defines its computation procedure and encoding 418 output. Unless specified otherwise, comparison of encoded output is 419 case-sensitive. 421 The "HTTP Digest Algorithm Values Registry", maintained by IANA at 422 https://www.iana.org/assignments/http-dig-alg/ 423 (https://www.iana.org/assignments/http-dig-alg/) registers digest- 424 algorithm values. Registrations MUST include the following fields: 426 * Digest algorithm: the token value. The registry can be used to 427 reserve token values 429 * Status: the status of the algorithm. Use "standard" for 430 standardized algorithms without known problems; "experimental" or 431 some other appropriate value 433 - e.g. according to the type and status of the primary document 434 in which the algorithm is defined; "deprecated" when the 435 algorithm is insecure or otherwise undesirable; "reserved" when 436 Digest algorithm references a reserved token value 438 * Description: the description of the digest-algorithm and its 439 encoding 441 * Reference: a set of pointers to the primary documents defining the 442 digest-algorithm 444 The associated encoding for new digest-algorithms MUST either be 445 represented as a quoted string or MUST NOT include ";" or "," in the 446 character sets used for the encoding. 448 Deprecated digest algorithms MUST NOT be used. 450 The registry is initialized with the tokens listed below. 452 sha-512 453 * Digest Algorithm: sha-512 455 * Description: The SHA-512 algorithm [RFC6234]. The output of 456 this algorithm is encoded using the base64 encoding [RFC4648]. 458 * Reference: [RFC6234], [RFC4648], this document. 460 * Status: standard 462 sha-256 463 * Digest Algorithm: sha-256 465 * Description: The SHA-256 algorithm [RFC6234]. The output of 466 this algorithm is encoded using the base64 encoding [RFC4648]. 468 * Reference: [RFC6234], [RFC4648], this document. 470 * Status: standard 472 md5 473 * Digest Algorithm: md5 474 * Description: The MD5 algorithm, as specified in [RFC1321]. The 475 output of this algorithm is encoded using the base64 encoding 476 [RFC4648]. This digest-algorithm is now vulnerable to 477 collision attacks. See [NO-MD5] and [CMU-836068]. 479 * Reference: [RFC1321], [RFC4648], this document. 481 * Status: deprecated 483 sha 484 * Digest Algorithm: sha 486 * Description: The SHA-1 algorithm [RFC3174]. The output of this 487 algorithm is encoded using the base64 encoding [RFC4648]. This 488 digest-algorithm is now vulnerable to collision attacks. See 489 [NO-SHA1] and [IACR-2020-014]. 491 * Reference: [RFC3174], [RFC6234], [RFC4648], this document. 493 * Status: deprecated 495 unixsum 496 * Digest Algorithm: unixsum 498 * Description: The algorithm computed by the UNIX "sum" command, 499 as defined by the Single UNIX Specification, Version 2 [UNIX]. 500 The output of this algorithm is an ASCII decimal-digit string 501 representing the 16-bit checksum, which is the first word of 502 the output of the UNIX "sum" command. 504 * Reference: [UNIX], this document. 506 * Status: deprecated 508 unixcksum 509 * Digest Algorithm: unixcksum 511 * Description: The algorithm computed by the UNIX "cksum" 512 command, as defined by the Single UNIX Specification, Version 2 513 [UNIX]. The output of this algorithm is an ASCII digit string 514 representing the 32-bit CRC, which is the first word of the 515 output of the UNIX "cksum" command. 517 * Reference: [UNIX], this document. 519 * Status: deprecated 521 adler32 522 * Digest Algorithm: adler32 524 * Description: The ADLER32 algorithm is a checksum specified in 525 [RFC1950] "ZLIB Compressed Data Format". The 32-bit output is 526 encoded in hexadecimal (using between 1 and 8 ASCII characters 527 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 528 adler32=03da0195 and adler32=3DA0195 are both valid checksums 529 for the 4-byte message "Wiki". This algorithm is obsoleted and 530 SHOULD NOT be used. 532 * Reference: [RFC1950], this document. 534 * Status: deprecated 536 crc32c 537 * Digest Algorithm: crc32c 539 * Description: The CRC32c algorithm is a 32-bit cyclic redundancy 540 check. It achieves a better hamming distance (for better 541 error-detection performance) than many other 32-bit CRC 542 functions. Other places it is used include iSCSI and SCTP. 543 The 32-bit output is encoded in hexadecimal (using between 1 544 and 8 ASCII characters from 0-9, A-F, and a-f; leading 0's are 545 allowed). For example, crc32c=0a72a4df and crc32c=A72A4DF are 546 both valid checksums for the 3-byte message "dog". 548 * Reference: [RFC4960] appendix B, this document. 550 * Status: deprecated. 552 To allow sender and recipient to provide a checksum which is 553 independent from Content-Encoding, the following additional digest- 554 algorithms are defined: 556 id-sha-512 557 * Description: The sha-512 digest of the representation data of 558 the resource when no content coding is applied 560 * Reference: [RFC6234], [RFC4648], this document. 562 * Status: standard 564 id-sha-256 565 * Description: The sha-256 digest of the representation data of 566 the resource when no content coding is applied 568 * Reference: [RFC6234], [RFC4648], this document. 570 * Status: standard 572 7. Using Digest in State-Changing Requests 574 When the representation enclosed in a state-changing request does not 575 describe the target resource, the representation digest MUST be 576 computed on the representation-data. This is the only possible 577 choice because representation digest requires complete representation 578 metadata (see Section 2). 580 In responses, 582 * if the representation describes the status of the request, Digest 583 MUST be computed on the enclosed representation (see Appendix B.8 584 ); 586 * if there is a referenced resource Digest MUST be computed on the 587 selected representation of the referenced resource even if that is 588 different from the target resource. That might or might not 589 result in computing Digest on the enclosed representation. 591 The latter case is done according to the HTTP semantics of the given 592 method, for example using the Content-Location header field (see 593 Section 8.7 of [SEMANTICS]). In contrast, the Location header field 594 does not affect Digest because it is not representation metadata. 596 For example, in PATCH requests, the representation digest will be 597 computed on the patch document because the representation metadata 598 refers to the patch document and not to the target resource (see 599 Section 2 of [PATCH]). In responses, instead, the representation 600 digest will be computed on the selected representation of the patched 601 resource. 603 7.1. Digest and Content-Location in Responses 605 When a state-changing method returns the Content-Location header 606 field, the enclosed representation refers to the resource identified 607 by its value and Digest is computed accordingly. An example is given 608 in Appendix B.7. 610 8. Security Considerations 612 8.1. Digest Does Not Protect the Full HTTP Message 614 This document specifies a data integrity mechanism that protects HTTP 615 representation data or content, but not HTTP header and trailer 616 fields, from certain kinds of accidental corruption. 618 Digest fields are not intended to be a general protection against 619 malicious tampering with HTTP messages. This can be achieved by 620 combining it with other approaches such as transport-layer security 621 or digital signatures. 623 8.2. Digest for End-to-End Integrity 625 Digest fields can help detect representation data or content 626 modification due to implementation errors, undesired "transforming 627 proxies" (see Section 7.7 of [SEMANTICS]) or other actions as the 628 data passes across multiple hops or system boundaries. Even a simple 629 mechanism for end-to-end representation data integrity is valuable 630 because user-agent can validate that resource retrieval succeeded 631 before handing off to a HTML parser, video player etc. for parsing. 633 Identity digest-algorithms (e.g. "id-sha-256" and "id-sha-512") are 634 particularly useful for end-to-end integrity because they allow 635 piecing together a resource from different sources with different 636 HTTP messaging characteristics. For example, different servers that 637 apply different content codings. 639 Note that using digest fields alone does not provide end-to-end 640 integrity of HTTP messages over multiple hops, since metadata could 641 be manipulated at any stage. Methods to protect metadata are 642 discussed in Section 8.3. 644 8.3. Usage in Signatures 646 Digital signatures are widely used together with checksums to provide 647 the certain identification of the origin of a message [NIST800-32]. 648 Such signatures can protect one or more HTTP fields and there are 649 additional considerations when Digest is included in this set. 651 Since digest fields are hashes of resource representations, they 652 explicitly depend on the representation metadata (e.g. the values of 653 Content-Type, Content-Encoding etc). A signature that protects 654 Digest but not other representation metadata can expose the 655 communication to tampering. For example, an actor could manipulate 656 the Content-Type field-value and cause a digest validation failure at 657 the recipient, preventing the application from accessing the 658 representation. Such an attack consumes the resources of both 659 endpoints. See also Section 7.1. 661 Digest fields SHOULD always be used over a connection that provides 662 integrity at the transport layer that protects HTTP fields. 664 A Digest field using NOT RECOMMENDED digest-algorithms SHOULD NOT be 665 used in signatures. 667 Using signatures to protect the checksum of an empty representation 668 allows receiving endpoints to detect if an eventual payload has been 669 stripped or added. 671 Any mangling of digest fields, including de-duplication of 672 representation-data-digest values or combining different field values 673 (see Section 5.2 of [SEMANTICS]) might affect signature validation. 675 8.4. Usage in Trailer Fields 677 Before sending digest fields in a trailer section, the sender should 678 consider that intermediaries are explicitly allowed to drop any 679 trailer (see Section 6.5.2 of [SEMANTICS]). 681 When digest fields are used in a trailer section, the field-values 682 are received after the content. Eager processing of content before 683 the trailer section prevents digest validation, possibly leading to 684 processing of invalid data. 686 Not every digest-algorithm is suitable for use in the trailer 687 section, some may require to pre-process the whole payload before 688 sending a message (e.g. see [I-D.thomson-http-mice]). 690 8.5. Usage with Encryption 692 Digest fields may expose details of encrypted payload when the 693 checksum is computed on the unencrypted data. For example, the use 694 of the "id-sha-256" digest-algorithm in conjunction with the 695 encrypted content-coding [RFC8188]. 697 The checksum of an encrypted payload can change between different 698 messages depending on the encryption algorithm used; in those cases 699 its value could not be used to provide a proof of integrity "at rest" 700 unless the whole (e.g. encoded) content is persisted. 702 8.6. Algorithm Agility 704 The security properties of digest-algorithms are not fixed. 705 Algorithm Agility (see [RFC7696]) is achieved by providing 706 implementations with flexibility choose digest-algorithms from the 707 IANA Digest Algorithm Values registry in Section 9.1. 709 To help endpoints distinguish weaker algorithms from stronger ones, 710 this document adds to the IANA Digest Algorithm Values registry a new 711 "Status" field containing the most recent appraisal of the digest- 712 algorithm. 714 An endpoint might have a preference for algorithms, such as 715 preferring "standard" algorithms over "deprecated" ones. Transition 716 from weak algorithms is supported by negotiation of digest-algorithm 717 using Want-Digest or Want-Content-Digest (see Section 5) or by 718 sending multiple representation-data-digest values from which the 719 receiver chooses. Endpoints are advised that sending multiple values 720 consumes resources, which may be wasted if the receiver ignores them 721 (see Section 3). 723 8.7. Duplicate digest-algorithm in field value 725 An endpoint might receive multiple representation-data-digest values 726 (see Section 3) that use the same digest-algorithm with different or 727 identical digest-values. For example: 729 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=, 730 sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= 732 A receiver is permitted to ignore any representation-data-digest 733 value, so validation of duplicates is left as an implementation 734 decision. Endpoints might select all, some, or none of the values 735 for checksum comparison and, based on the intersection of those 736 results, conditionally pass or fail digest validation. 738 8.8. Resource exhaustion 740 Digest fields validation consumes computational resources. In order 741 to avoid resource exhaustion, implementations can restrict validation 742 of the algorithm types, number of validations, or the size of 743 content. 745 9. IANA Considerations 747 9.1. Establish the HTTP Digest Algorithm Values Registry 749 This memo sets this specification to be the establishing document for 750 the HTTP Digest Algorithm Values (https://www.iana.org/assignments/ 751 http-dig-alg/) registry. 753 IANA is asked to update the "Reference" for this registry to refer 754 this document and to inizialize the registry with the tokens defined 755 in Section 6. 757 This registry uses the Specification Required policy (Section 4.6 of 758 [RFC8126]). 760 9.2. Obsolete "contentMD5" token in Digest Algorithm 762 This memo adds the "contentMD5" token in the HTTP Digest Algorithm 763 Values (https://www.iana.org/assignments/http-dig-alg/) registry: 765 * Digest Algorithm: contentMD5 767 * Description: Section 5 of [RFC3230] defined the "contentMD5" token 768 to be used only in Want-Digest. This token is obsoleted and MUST 769 NOT be used. 771 * Reference: Section 9.2 of this document, Section 5 of [RFC3230]. 773 * Status: obsoleted 775 9.3. Changes Compared to RFC3230 777 The contentMD5 digest-algorithm token defined in Section 5 of 778 [RFC3230] has been added to the HTTP Digest Algorithm Values Registry 779 with the "obsoleted" status. 781 All digest-algorithms defined in [RFC3230] are now "deprecated". 783 9.4. Changes Compared to RFC5843 785 The digest-algorithm tokens for "MD5", "SHA", "SHA-256", "SHA-512" 786 have been updated to lowercase. 788 The status of "MD5" and "SHA" has been updated to "deprecated", and 789 their description has been modified accordingly. 791 The "id-sha-256" and "id-sha-512" algorithms have been added to the 792 registry. 794 9.5. Want-Digest Field Registration 796 This section registers the Want-Digest field in the "Hypertext 797 Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. 799 Field name: Want-Digest 801 Status: permanent 803 Specification document(s): Section 5 of this document 805 9.6. Digest Field Registration 807 This section registers the Digest field in the "Hypertext Transfer 808 Protocol (HTTP) Field Name Registry" [SEMANTICS]. 810 Field name: Digest 812 Status: permanent 814 Specification document(s): Section 3 of this document 816 9.7. Want-Content-Digest Field Registration 818 This section registers the Want-Content-Digest field in the 819 "Hypertext Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. 821 Field name: Want-Content-Digest 823 Status: permanent 825 Specification document(s): Section 5 of this document 827 9.8. Content-Digest Field Registration 829 This section registers the Content-Digest field in the "Hypertext 830 Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. 832 Field name: Content-Digest 834 Status: permanent 836 Specification document(s): Section 4 of this document 838 10. References 840 10.1. Normative References 842 [CMU-836068] 843 Carnagie Mellon University, Software Engineering 844 Institute, "MD5 Vulnerable to collision attacks", 31 845 December 2008, . 847 [IACR-2020-014] 848 Leurent, G. and T. Peyrin, "SHA-1 is a Shambles", 5 849 January 2020, . 851 [NIST800-32] 852 National Institute of Standards and Technology, U.S. 853 Department of Commerce, "Introduction to Public Key 854 Technology and the Federal PKI Infrastructure", February 855 2001, . 858 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 859 DOI 10.17487/RFC1321, April 1992, 860 . 862 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 863 Specification version 3.3", RFC 1950, 864 DOI 10.17487/RFC1950, May 1996, 865 . 867 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 868 Requirement Levels", BCP 14, RFC 2119, 869 DOI 10.17487/RFC2119, March 1997, 870 . 872 [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 873 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, 874 . 876 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 877 RFC 3230, DOI 10.17487/RFC3230, January 2002, 878 . 880 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 881 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 882 . 884 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 885 RFC 4960, DOI 10.17487/RFC4960, September 2007, 886 . 888 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 889 Specifications: ABNF", STD 68, RFC 5234, 890 DOI 10.17487/RFC5234, January 2008, 891 . 893 [RFC5843] Bryan, A., "Additional Hash Algorithms for HTTP Instance 894 Digests", RFC 5843, DOI 10.17487/RFC5843, April 2010, 895 . 897 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 898 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 899 DOI 10.17487/RFC6234, May 2011, 900 . 902 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 903 RFC 7405, DOI 10.17487/RFC7405, December 2014, 904 . 906 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 907 Writing an IANA Considerations Section in RFCs", BCP 26, 908 RFC 8126, DOI 10.17487/RFC8126, June 2017, 909 . 911 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 912 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 913 May 2017, . 915 [SEMANTICS] 916 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 917 Semantics", Work in Progress, Internet-Draft, draft-ietf- 918 httpbis-semantics-19, 12 September 2021, 919 . 922 [UNIX] The Open Group, "The Single UNIX Specification, Version 2 923 - 6 Vol Set for UNIX 98", February 1997. 925 10.2. Informative References 927 [HTTP11] Fielding, R. T., Nottingham, M., and J. Reschke, 928 "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf- 929 httpbis-messaging-19, 12 September 2021, 930 . 933 [I-D.ietf-httpbis-header-structure] 934 Nottingham, M. and P. Kamp, "Structured Field Values for 935 HTTP", Work in Progress, Internet-Draft, draft-ietf- 936 httpbis-header-structure-19, 3 June 2020, 937 . 940 [I-D.thomson-http-mice] 941 Thomson, M. and J. Yasskin, "Merkle Integrity Content 942 Encoding", Work in Progress, Internet-Draft, draft- 943 thomson-http-mice-03, 13 August 2018, 944 . 947 [NO-MD5] Turner, S. and L. Chen, "Updated Security Considerations 948 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 949 RFC 6151, DOI 10.17487/RFC6151, March 2011, 950 . 952 [NO-SHA1] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security 953 Considerations for the SHA-0 and SHA-1 Message-Digest 954 Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011, 955 . 957 [PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 958 RFC 5789, DOI 10.17487/RFC5789, March 2010, 959 . 961 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 962 DOI 10.17487/RFC2818, May 2000, 963 . 965 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 966 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 967 DOI 10.17487/RFC7231, June 2014, 968 . 970 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 971 DOI 10.17487/RFC7396, October 2014, 972 . 974 [RFC7696] Housley, R., "Guidelines for Cryptographic Algorithm 975 Agility and Selecting Mandatory-to-Implement Algorithms", 976 BCP 201, RFC 7696, DOI 10.17487/RFC7696, November 2015, 977 . 979 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 980 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 981 . 983 [RFC8188] Thomson, M., "Encrypted Content-Encoding for HTTP", 984 RFC 8188, DOI 10.17487/RFC8188, June 2017, 985 . 987 Appendix A. Resource Representation and Representation-Data 989 The following examples show how representation metadata, payload 990 transformations and method impacts on the message and content. When 991 the content contains non-printable characters (e.g. when it is 992 compressed) it is shown as a Base64-encoded string. 994 PUT /entries/1234 HTTP/1.1 995 Host: foo.example 996 Content-Type: application/json 998 {"hello": "world"} 1000 Figure 1: Request containing a JSON object without any content coding 1002 PUT /entries/1234 HTTP/1.1 1003 Host: foo.example 1004 Content-Type: application/json 1005 Content-Encoding: gzip 1007 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 1009 Figure 2: Request containing a gzip-encoded JSON object 1011 Now the same content conveys a malformed JSON object, because the 1012 request does not indicate a content coding. 1014 PUT /entries/1234 HTTP/1.1 1015 Host: foo.example 1016 Content-Type: application/json 1018 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 1020 Figure 3: Request containing malformed JSON 1022 A Range-Request alters the content, conveying a partial 1023 representation. 1025 GET /entries/1234 HTTP/1.1 1026 Host: foo.example 1027 Range: bytes=1-7 1029 Figure 4: Request for partial content 1031 HTTP/1.1 206 Partial Content 1032 Content-Encoding: gzip 1033 Content-Type: application/json 1034 Content-Range: bytes 1-7/18 1036 iwgAla3RXA== 1038 Figure 5: Partial response from a gzip-encoded representation 1040 The method can also alter the content. For example, the response to 1041 a HEAD request does not carry content. 1043 HEAD /entries/1234 HTTP/1.1 1044 Host: foo.example 1045 Accept: application/json 1046 Accept-Encoding: gzip 1048 Figure 6: HEAD request 1050 HTTP/1.1 200 OK 1051 Content-Type: application/json 1052 Content-Encoding: gzip 1054 Figure 7: Response to HEAD request (empty content) 1056 Finally, the semantics of an HTTP response might decouple the 1057 effective request URI from the enclosed representation. In the 1058 example response below, the Content-Location header field indicates 1059 that the enclosed representation refers to the resource available at 1060 /authors/123, even though the request is directed to /authors/. 1062 POST /authors/ HTTP/1.1 1063 Host: foo.example 1064 Accept: application/json 1065 Content-Type: application/json 1067 {"author": "Camilleri"} 1069 Figure 8: POST request 1071 HTTP/1.1 201 Created 1072 Content-Type: application/json 1073 Content-Location: /authors/123 1074 Location: /authors/123 1076 {"id": "123", "author": "Camilleri"} 1078 Figure 9: Response with Content-Location header 1080 Appendix B. Examples of Unsolicited Digest 1082 The following examples demonstrate interactions where a server 1083 responds with a Digest or Content-Digest fields even though the 1084 client did not solicit one using Want-Digest or Want-Content-Digest. 1086 Some examples include JSON objects in the content. For presentation 1087 purposes, objects that fit completely within the line-length limits 1088 are presented on a single line using compact notation with no leading 1089 space. Objects that would exceed line-length limits are presented 1090 across multiple lines (one line per key-value pair) with 2 spaced of 1091 leading indentation. 1093 Checksum mechanisms defined in this document are media-type agnostic 1094 and do not provide canonicalization algorithms for specific formats. 1095 Examples are calculated inclusive of any space. While examples can 1096 include both fields, Digest and Content-Digest can be returned 1097 independently. 1099 B.1. Server Returns Full Representation Data 1101 In this example, the message content conveys complete representation 1102 data, so Digest and Content-Digest have the same value. 1104 GET /items/123 HTTP/1.1 1105 Host: foo.example 1107 Figure 10: GET request for an item 1109 HTTP/1.1 200 OK 1110 Content-Type: application/json 1111 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1112 Content-Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1114 {"hello": "world"} 1116 Figure 11: Response with Content-Digest 1118 B.2. Server Returns No Representation Data 1120 In this example, a HEAD request is used to retrieve the checksum of a 1121 resource. 1123 The response Digest field-value is calculated over the JSON object 1124 {"hello": "world"}, which is not shown because there is no payload 1125 data. Content-Digest is computed on empty content. 1127 HEAD /items/123 HTTP/1.1 1128 Host: foo.example 1130 Figure 12: HEAD request for an item 1132 HTTP/1.1 200 OK 1133 Content-Type: application/json 1134 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1135 Content-Digest: sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= 1137 Figure 13: Response with both Content-Digest and Digest; empty 1138 content 1140 B.3. Server Returns Partial Representation Data 1142 In this example, the client makes a range request and the server 1143 responds with partial content. The Digest field-value represents the 1144 entire JSON object {"hello": "world"}, while the Content-Digest 1145 field-value is computed on the message content "hello". 1147 GET /items/123 HTTP/1.1 1148 Host: foo.example 1149 Range: bytes=1-7 1151 Figure 14: Request for partial content 1153 HTTP/1.1 206 Partial Content 1154 Content-Type: application/json 1155 Content-Range: bytes 1-7/18 1156 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1157 Content-Digest: sha-256=Wqdirjg/u3J688ejbUlApbjECpiUUtIwT8lY/z81Tno= 1159 "hello" 1161 Figure 15: Partial response with both Content-Digest and Digest 1163 B.4. Client and Server Provide Full Representation Data 1165 The request contains a Digest field-value calculated on the enclosed 1166 representation. It also includes an Accept-Encoding: br header field 1167 that advertises the client supports Brotli encoding. 1169 The response includes a Content-Encoding: br that indicates the 1170 selected representation is Brotli-encoded. The Digest field-value is 1171 therefore different compared to the request. 1173 For presentation purposes, the response body is displayed as a 1174 Base64-encoded string because it contains non-printable characters. 1176 PUT /items/123 HTTP/1.1 1177 Host: foo.example 1178 Content-Type: application/json 1179 Accept-Encoding: br 1180 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1182 {"hello": "world"} 1184 Figure 16: PUT Request with Digest 1186 HTTP/1.1 200 OK 1187 Content-Type: application/json 1188 Content-Location: /items/123 1189 Content-Encoding: br 1190 Content-Length: 22 1191 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1193 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 1195 Figure 17: Response with Digest of encoded response 1197 B.5. Client Provides Full Representation Data, Server Provides No 1198 Representation Data 1200 The request Digest field-value is calculated on the enclosed payload. 1202 The response Digest field-value depends on the representation 1203 metadata header fields, including Content-Encoding: br even when the 1204 response does not contain content. 1206 PUT /items/123 HTTP/1.1 1207 Host: foo.example 1208 Content-Type: application/json 1209 Content-Length: 18 1210 Accept-Encoding: br 1211 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1213 {"hello": "world"} 1215 HTTP/1.1 204 No Content 1216 Content-Type: application/json 1217 Content-Encoding: br 1218 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1220 Figure 18: Empty response with Digest 1222 B.6. Client and Server Provide Full Representation Data, Client Uses 1223 id-sha-256. 1225 The response contains two digest values: 1227 * one with no content coding applied, which in this case 1228 accidentally matches the unencoded digest-value sent in the 1229 request; 1231 * one taking into account the Content-Encoding. 1233 As the response body contains non-printable characters, it is 1234 displayed as a base64-encoded string. 1236 PUT /items/123 HTTP/1.1 1237 Host: foo.example 1238 Content-Type: application/json 1239 Accept-Encoding: br 1240 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1242 {"hello": "world"} 1244 Figure 19: PUT Request with Digest 1246 HTTP/1.1 200 OK 1247 Content-Type: application/json 1248 Content-Encoding: br 1249 Content-Location: /items/123 1250 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 1251 id-sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1253 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 1255 Figure 20: Response with Digest of Encoded Content 1257 B.7. POST Response does not Reference the Request URI 1259 The request Digest field-value is computed on the enclosed 1260 representation (see Section 7). 1262 The representation enclosed in the response refers to the resource 1263 identified by Content-Location (see Section 6.4.2 of [SEMANTICS]). 1264 Digest is thus computed on the enclosed representation. 1266 POST /books HTTP/1.1 1267 Host: foo.example 1268 Content-Type: application/json 1269 Accept: application/json 1270 Accept-Encoding: identity 1271 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 1273 {"title": "New Title"} 1275 Figure 21: POST Request with Digest 1277 HTTP/1.1 201 Created 1278 Content-Type: application/json 1279 Content-Location: /books/123 1280 Location: /books/123 1281 Digest: id-sha-256=yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE= 1283 { 1284 "id": "123", 1285 "title": "New Title" 1286 } 1288 Figure 22: Response with Digest of Resource 1290 Note that a 204 No Content response without content but with the same 1291 Digest field-value would have been legitimate too. In that case, 1292 Content-Digest would have been computed on an empty content. 1294 B.8. POST Response Describes the Request Status 1296 The request Digest field-value is computed on the enclosed 1297 representation (see Section 7). 1299 The representation enclosed in the response describes the status of 1300 the request, so Digest is computed on that enclosed representation. 1302 Response Digest has no explicit relation with the resource referenced 1303 by Location. 1305 POST /books HTTP/1.1 1306 Host: foo.example 1307 Content-Type: application/json 1308 Accept: application/json 1309 Accept-Encoding: identity 1310 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 1312 {"title": "New Title"} 1313 Figure 23: POST Request with Digest 1315 HTTP/1.1 201 Created 1316 Content-Type: application/json 1317 Digest: id-sha-256=2LBp5RKZGpsSNf8BPXlXrX4Td4Tf5R5bZ9z7kdi5VvY= 1318 Location: /books/123 1320 { 1321 "status": "created", 1322 "id": "123", 1323 "ts": 1569327729, 1324 "instance": "/books/123" 1325 } 1327 Figure 24: Response with Digest of Representation 1329 B.9. Digest with PATCH 1331 This case is analogous to a POST request where the target resource 1332 reflects the effective request URI. 1334 The PATCH request uses the application/merge-patch+json media type 1335 defined in [RFC7396]. 1337 Digest is calculated on the enclosed payload, which corresponds to 1338 the patch document. 1340 The response Digest field-value is computed on the complete 1341 representation of the patched resource. 1343 PATCH /books/123 HTTP/1.1 1344 Host: foo.example 1345 Content-Type: application/merge-patch+json 1346 Accept: application/json 1347 Accept-Encoding: identity 1348 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 1350 {"title": "New Title"} 1352 Figure 25: PATCH Request with Digest 1354 HTTP/1.1 200 OK 1355 Content-Type: application/json 1356 Digest: id-sha-256=yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE= 1358 { 1359 "id": "123", 1360 "title": "New Title" 1361 } 1363 Figure 26: Response with Digest of Representation 1365 Note that a 204 No Content response without content but with the same 1366 Digest field-value would have been legitimate too. 1368 B.10. Error responses 1370 In error responses, the representation-data does not necessarily 1371 refer to the target resource. Instead, it refers to the 1372 representation of the error. 1374 In the following example, a client sends the same request from 1375 Figure 25 to patch the resource located at /books/123. However, the 1376 resource does not exist and the server generates a 404 response with 1377 a body that describes the error in accordance with [RFC7807]. 1379 The response Digest field-value is computed on this enclosed 1380 representation. 1382 HTTP/1.1 404 Not Found 1383 Content-Type: application/problem+json 1384 Digest: sha-256=KPqhVXAT25LLitV1w0O167unHmVQusu+fpxm65zAsvk= 1386 { 1387 "title": "Not Found", 1388 "detail": "Cannot PATCH a non-existent resource", 1389 "status": 404 1390 } 1392 Figure 27: Response with Digest of Error Representation 1394 B.11. Use with Trailer Fields and Transfer Coding 1396 An origin server sends Digest as trailer field, so it can calculate 1397 digest-value while streaming content and thus mitigate resource 1398 consumption. The Digest field-value is the same as in Appendix B.1 1399 because Digest is designed to be independent from the use of one or 1400 more transfer codings (see Section 2). 1402 GET /items/123 HTTP/1.1 1403 Host: foo.example 1405 Figure 28: GET Request 1407 HTTP/1.1 200 OK 1408 Content-Type: application/json 1409 Transfer-Encoding: chunked 1410 Trailer: Digest 1412 8\r\n 1413 {"hello"\r\n 1414 8 1415 : "world\r\n 1416 2\r\n 1417 "}\r\n 1418 0\r\n 1419 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1421 Figure 29: Chunked Response with Digest 1423 Appendix C. Examples of Want-Digest Solicited Digest 1425 The following examples demonstrate interactions where a client 1426 solicits a Digest using Want-Digest. The behavior of Content-Digest 1427 and Want-Content-Digest is identical. 1429 Some examples include JSON objects in the content. For presentation 1430 purposes, objects that fit completely within the line-length limits 1431 are presented on a single line using compact notation with no leading 1432 space. Objects that would exceed line-length limits are presented 1433 across multiple lines (one line per key-value pair) with 2 spaced of 1434 leading indentation. 1436 Checksum mechanisms described in this document are media-type 1437 agnostic and do not provide canonicalization algorithms for specific 1438 formats. Examples are calculated inclusive of any space. 1440 C.1. Server Selects Client's Least Preferred Algorithm 1442 The client requests a digest, preferring "sha". The server is free 1443 to reply with "sha-256" anyway. 1445 GET /items/123 HTTP/1.1 1446 Host: foo.example 1447 Want-Digest: sha-256;q=0.3, sha;q=1 1449 Figure 30: GET Request with Want-Digest 1451 HTTP/1.1 200 OK 1452 Content-Type: application/json 1453 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1455 {"hello": "world"} 1457 Figure 31: Response with Different Algorithm 1459 C.2. Server Selects Algorithm Unsupported by Client 1461 The client requests a "sha" digest only. The server is currently 1462 free to reply with a Digest containing an unsupported algorithm. 1464 GET /items/123 HTTP/1.1 1465 Host: foo.example 1466 Want-Digest: sha;q=1 1468 Figure 32: GET Request with Want-Digest 1470 HTTP/1.1 200 OK 1471 Content-Type: application/json 1472 Digest: id-sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 1473 +AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 1475 {"hello": "world"} 1477 Figure 33: Response with Unsupported Algorithm 1479 C.3. Server Does Not Support Client Algorithm and Returns an Error 1481 The client requests a "sha" Digest, the server advises "sha-256" and 1482 "sha-512". 1484 GET /items/123 HTTP/1.1 1485 Host: foo.example 1486 Want-Digest: sha;q=1 1488 Figure 34: GET Request with Want-Digest 1490 HTTP/1.1 400 Bad Request 1491 Want-Digest: sha-256, sha-512 1493 Figure 35: Response with Want-Digest 1495 Appendix D. Changes from RFC3230 1496 D.1. Deprecate Negotiation of Content-MD5 1498 This RFC deprecates the negotiation of Content-MD5 as it has been 1499 obsoleted by [RFC7231]. 1501 See Section 4 for a new checksum negotiation mechanism for HTTP 1502 message content. 1504 D.2. Obsolete Digest Field Parameters 1506 Sections 4.1.1 and 4.2 of [RFC3230] defined field parameters. This 1507 document obsoletes the usage of parameters with Digest because this 1508 feature has not been widely deployed and complicates field-value 1509 processing. 1511 [RFC3230] intended field parameters to provide a common way to attach 1512 additional information to a representation-data-digest. However, if 1513 parameters are used as an input to validate the checksum, an attacker 1514 could alter them to steer the validation behavior. 1516 A digest-algorithm can still be parameterized by defining its own way 1517 to encode parameters into the representation-data-digest, in such a 1518 way as to mitigate security risks related to its computation. 1520 Acknowledgements 1522 The vast majority of this document is inherited from [RFC3230], so 1523 thanks to J. Mogul and A. Van Hoff for their great work. The 1524 original idea of refreshing this document arose from an interesting 1525 discussion with M. Nottingham, J. Yasskin and M. Thomson when 1526 reviewing the MICE content coding. 1528 Thanks to Julian Reschke for his valuable contributions to this 1529 document, and to the following contributors that have helped improve 1530 this specification by reporting bugs, asking smart questions, 1531 drafting or reviewing text, and evaluating open issues: Mike Bishop, 1532 Brian Campbell, Matthew Kerwin, James Manger, Tommy Pauly, Sean 1533 Turner, and Erik Wilde. 1535 FAQ 1537 _RFC Editor: Please remove this section before publication._ 1539 1. Why remove all references to content-md5? 1541 Those were unnecessary to understanding and using this 1542 specification. 1544 2. Why remove references to instance manipulation? 1546 Those were unnecessary for correctly using and applying the 1547 specification. An example with Range Request is more than 1548 enough. This document uses the term "partial representation" 1549 which should group all those cases. 1551 3. How to use Digest with PATCH method? 1553 See Section 7. 1555 4. Why remove references to delta-encoding? 1557 Unnecessary for a correct implementation of this specification. 1558 The revised specification can be nicely adapted to "delta 1559 encoding", but all the references here to delta encoding don't 1560 add anything to this RFC. Another job would be to refresh delta 1561 encoding. 1563 5. Why remove references to Digest Authentication? 1565 This specification seems to me completely unrelated to Digest 1566 Authentication but for the word "Digest". 1568 6. What changes in Want-Digest? 1570 The contentMD5 token defined in Section 5 of [RFC3230] is 1571 deprecated by Appendix D.1. 1573 To clarify that Digest and Want-Digest can be used in both 1574 requests and responses - [RFC3230] carefully uses sender and 1575 receiver in their definition - we added examples on using Want- 1576 Digest in responses to advertise the supported digest-algorithms 1577 and the inability to accept requests with unsupported digest- 1578 algorithms. 1580 7. Does this specification change supported algorithms? 1582 Yes. This RFC updates [RFC5843] which is still delegated for all 1583 algorithms updates, and adds two more algorithms: "id-sha-256" 1584 and "id-sha-512" which allows to send a checksum of a resource 1585 representation with no content codings applied. To simplify a 1586 future transition to Structured Fields 1587 [I-D.ietf-httpbis-header-structure] we suggest to use lowercase 1588 for digest-algorithms. 1590 8. What about mid-stream trailer fields? 1591 While mid-stream trailer fields (https://github.com/httpwg/http- 1592 core/issues/313#issuecomment-584389706) are interesting, since 1593 this specification is a rewrite of [RFC3230] we do not think we 1594 should face that. As a first thought, nothing in this document 1595 precludes future work that would find a use for mid-stream 1596 trailers, for example an incremental digest-algorithm. A 1597 document defining such a digest-algorithm is best positioned to 1598 describe how it is used. 1600 Code Samples 1602 _RFC Editor: Please remove this section before publication._ 1604 How can I generate and validate the Digest values shown in the 1605 examples throughout this document? 1607 The following python3 code can be used to generate digests for JSON 1608 objects using SHA algorithms for a range of encodings. Note that 1609 these are formatted as base64. This function could be adapted to 1610 other algorithms and should take into account their specific 1611 formatting rules. 1613 import base64, json, hashlib, brotli, logging 1614 log = logging.getLogger() 1616 def encode_item(item, encoding=lambda x: x): 1617 indent = 2 if isinstance(item, dict) and len(item) > 1 else None 1618 json_bytes = json.dumps(item, indent=indent).encode() 1619 return encoding(json_bytes) 1621 def digest_bytes(bytes_, algorithm=hashlib.sha256): 1622 checksum_bytes = algorithm(bytes_).digest() 1623 log.warning("Log bytes: \n[%r]", bytes_) 1624 return base64.encodebytes(checksum_bytes).strip() 1626 def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): 1627 content_encoded = encode_item(item, encoding) 1628 return digest_bytes(content_encoded, algorithm) 1630 item = {"hello": "world"} 1632 print("Encoding | digest-algorithm | digest-value") 1633 print("Identity | sha256 |", digest(item)) 1634 # Encoding | digest-algorithm | digest-value 1635 # Identity | sha256 | X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1637 print("Encoding | digest-algorithm | digest-value") 1638 print("Brotli | sha256 |", digest(item, encoding=brotli.compress)) 1639 # Encoding | digest-algorithm | digest-value 1640 # Brotli | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1642 print("Encoding | digest-algorithm | digest-value") 1643 print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512)) 1644 # Encoding | digest-algorithm | digest-value 1645 # Identity | sha512 | b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm' 1646 # '+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==' 1648 Changes 1650 _RFC Editor: Please remove this section before publication._ 1652 Since draft-ietf-httpbis-digest-headers-05 1654 * Reboot digest-algorithm values registry #1567 1656 * Add Content-Digest #1542 1657 * Remove SRI section #1478 1659 Since draft-ietf-httpbis-digest-headers-04 1661 * Improve SRI section #1354 1663 * About duplicate digest-algorithms #1221 1665 * Improve security considerations #852 1667 * md5 and sha deprecation references #1392 1669 * Obsolete 3230 #1395 1671 * Editorial #1362 1673 Since draft-ietf-httpbis-digest-headers-03 1675 * Reference semantics-12 1677 * Detail encryption quirks 1679 * Details on Algorithm agility #1250 1681 * Obsolete parameters #850 1683 Since draft-ietf-httpbis-digest-headers-02 1685 * Deprecate SHA-1 #1154 1687 * Avoid id-* with encrypted content 1689 * Digest is independent from MESSAGING and HTTP/1.1 is not normative 1690 #1215 1692 * Identity is not a valid field value for content-encoding #1223 1694 * Mention trailers #1157 1696 * Reference httpbis-semantics #1156 1698 * Add contentMD5 as an obsoleted digest-algorithm #1249 1700 * Use lowercase digest-algorithms names in the doc and in the 1701 digest-algorithm IANA table. 1703 Since draft-ietf-httpbis-digest-headers-01 1704 * Digest of error responses is computed on the error representation- 1705 data #1004 1707 * Effect of HTTP semantics on payload and message body moved to 1708 appendix #1122 1710 * Editorial refactoring, moving headers sections up. #1109-#1112, 1711 #1116, #1117, #1122-#1124 1713 Since draft-ietf-httpbis-digest-headers-00 1715 * Align title with document name 1717 * Add id-sha-* algorithm examples #880 1719 * Reference [RFC6234] and [RFC3174] instead of FIPS-1 1721 * Deprecate MD5 1723 * Obsolete ADLER-32 but don't forbid it #828 1725 * Update CRC32C value in IANA table #828 1727 * Use when acting on resources (POST, PATCH) #853 1729 * Added Relationship with SRI, draft Use Cases #868, #971 1731 * Warn about the implications of Content-Location 1733 Authors' Addresses 1735 Roberto Polli 1736 Team Digitale, Italian Government 1737 Italy 1739 Email: robipolli@gmail.com 1741 Lucas Pardue 1742 Cloudflare 1744 Email: lucaspardue.24.7@gmail.com