idnits 2.17.1 draft-ietf-httpbis-digest-headers-07.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 is 1 instance of too long lines in the document, the longest one being 22 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 (16 November 2021) is 890 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 4960 (Obsoleted by RFC 9260) ** 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' -- 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 (~~), 1 warning (==), 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: 20 May 2022 16 November 2021 8 Digest Fields 9 draft-ietf-httpbis-digest-headers-07 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 20 May 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 . . . . . . . . . 9 76 6. Digest Algorithm Values . . . . . . . . . . . . . . . . . . . 9 77 7. Using Digest in State-Changing Requests . . . . . . . . . . . 12 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 . . . . . 16 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 . . . . . . . . . . . . . . . . 17 95 9.7. Want-Content-Digest Field Registration . . . . . . . . . 17 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 . . 21 102 Appendix B. Examples of Unsolicited Digest . . . . . . . . . . . 23 103 B.1. Server Returns Full Representation Data . . . . . . . . . 23 104 B.2. Server Returns No Representation Data . . . . . . . . . . 24 105 B.3. Server Returns Partial Representation Data . . . . . . . 24 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 . . . 26 110 B.7. POST Response does not Reference the Request URI . . . . 27 111 B.8. POST Response Describes the Request Status . . . . . . . 28 112 B.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . . 28 113 B.10. Error responses . . . . . . . . . . . . . . . . . . . . . 29 114 B.11. Use with Trailer Fields and Transfer Coding . . . . . . . 30 115 Appendix C. Examples of Want-Digest Solicited Digest . . . . . . 30 116 C.1. Server Selects Client's Least Preferred Algorithm . . . . 31 117 C.2. Server Selects Algorithm Unsupported by Client . . . . . 31 118 C.3. Server Does Not Support Client Algorithm and Returns an 119 Error . . . . . . . . . . . . . . . . . . . . . . . . . . 32 120 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 32 121 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 122 Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 34 123 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 124 Since draft-ietf-httpbis-digest-headers-06 . . . . . . . . . . 35 125 Since draft-ietf-httpbis-digest-headers-05 . . . . . . . . . . 36 126 Since draft-ietf-httpbis-digest-headers-04 . . . . . . . . . . 36 127 Since draft-ietf-httpbis-digest-headers-03 . . . . . . . . . . 36 128 Since draft-ietf-httpbis-digest-headers-02 . . . . . . . . . . 36 129 Since draft-ietf-httpbis-digest-headers-01 . . . . . . . . . . 37 130 Since draft-ietf-httpbis-digest-headers-00 . . . . . . . . . . 37 131 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 133 1. Introduction 135 HTTP does not define a means to protect the integrity of 136 representations. When HTTP messages are transferred between 137 endpoints, the protocol might choose to make use of features of the 138 lower layer in order to provide some integrity protection; for 139 instance, TCP checksums or TLS records [RFC2818]. 141 This document defines two digest integrity mechanisms for HTTP. 142 First, representation data integrity, which acts on representation 143 data (Section 3.2 of [SEMANTICS]). Second, content digest integrity, 144 which acts on conveyed content (Section 6.4 of [SEMANTICS]). Both 145 mechanisms operate independent of transport integrity, offering the 146 potential to detect programming errors and corruption of data in 147 flight or at rest. They can be used across multiple hops in order to 148 provide end-to-end integrity guarantees, which can aid fault 149 diagnosis when resources are transferred across hops and system 150 boundaries. Finally, they can be used to validate integrity when 151 reconstructing a resource fetched using different HTTP connections. 153 This document obsoletes [RFC3230]. 155 1.1. Document Structure 157 This document is structured as follows: 159 * Section 2 describes concepts related to representation digests, 161 * Section 3 defines the Digest request and response header and 162 trailer field, 164 * Section 4 defines the Content-Digest request and response header 165 and trailer field, 167 * Section 5 defines the Want-Digest and Want-Content-Digest request 168 and response header and trailer field, 170 * Section 6 describes algorithms and their relation to Digest, 172 * Section 7 details computing representation digests, 174 * Appendix B and Appendix C provide examples of using Digest and 175 Want-Digest. 177 1.2. Concept Overview 179 This document defines the Digest request and response header and 180 trailer field; see Section 3. At a high level, the value contains a 181 checksum, computed over selected representation data (Section 3.2 of 182 [SEMANTICS]), that the recipient can use to validate integrity. 183 Basing Digest on the selected representation makes it straightforward 184 to apply it to use-cases where the transferred data requires some 185 sort of manipulation to be considered a representation or conveys a 186 partial representation of a resource, such as Range Requests (see 187 Section 14.2 of [SEMANTICS]). 189 To support use-cases where a simple checksum of the content bytes is 190 required, this document introduces the Content-Digest request and 191 response header and trailer field; see Section 4. 193 Digest and Content-Digest support algorithm agility. The Want-Digest 194 and Want-Content-Digest fields allows endpoints to express interest 195 in Digest and Content-Digest respectively, and preference of 196 algorithms in either. 198 Digest field calculations are tied to the Content-Encoding and 199 Content-Type header fields. Therefore, a given resource may have 200 multiple different checksum values when transferred with HTTP. 202 Digest fields do not provide integrity for HTTP messages or fields. 203 However, they can be combined with other mechanisms that protect 204 metadata, such as digital signatures, in order to protect the phases 205 of an HTTP exchange in whole or in part. 207 This specification does not define means for authentication, 208 authorization or privacy. 210 1.3. Replacing RFC 3230 212 Historically, the Content-MD5 header field provided an HTTP integrity 213 mechanism but HTTP/1.1 ([RFC7231], Appendix B) obsoleted it due to 214 inconsistent handling of partial responses. [RFC3230] defined the 215 concept of "instance" digests and a more flexible integrity scheme to 216 help address issues with Content-MD5. It first introduced the Digest 217 and Want-Digest fields. HTTP terminology has evolved since [RFC3230] 218 was published. The concept of "instance" has been superseded by 219 selected representation. 221 This document replaces [RFC3230]. The changes described in the 222 following paragraphs are intended to be semantically compatible with 223 existing implementations where possible. 225 The Digest and Want-Digest field definitions are updated to align 226 with the terms and notational conventions in [SEMANTICS]. 228 Negotiation of Content-MD5 is deprecated and has been replaced by 229 Content-Digest negotiation via Want-Content-Digest. 231 Sections 4.1.1 and 4.2 of [RFC3230] defined field parameters. This 232 document obsoletes the usage of parameters with Digest because this 233 feature has not been widely deployed and complicates field-value 234 processing. [RFC3230] intended field parameters to provide a common 235 way to attach additional information to a representation-data-digest. 236 However, if parameters are used as an input to validate the checksum, 237 an attacker could alter them to steer the validation behavior. A 238 digest-algorithm can still be parameterized by defining its own way 239 to encode parameters into the representation-data-digest, in such a 240 way as to mitigate security risks related to its computation. 242 The algorithm table has been updated to reflect the current state of 243 the art, (see Section 6). 245 1.4. Notational Conventions 247 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 248 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 249 "OPTIONAL" in this document are to be interpreted as described in 250 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 251 capitals, as shown here. 253 This document uses the Augmented BNF defined in [RFC5234] and updated 254 by [RFC7405] along with the "#rule" extension defined in 255 Section 5.6.1 of [SEMANTICS] and the "qvalue" rule defined in 256 Section 12.4.2 of [SEMANTICS]. 258 The definitions "representation", "selected representation", 259 "representation data", "representation metadata", and "content" in 260 this document are to be interpreted as described in [SEMANTICS]. 262 Algorithm names respect the casing used in their definition document 263 (e.g. SHA-1, CRC32c) whereas digest-algorithm tokens are quoted 264 (e.g. "sha", "crc32c"). 266 2. Representation Digest 268 The representation digest is an integrity mechanism for HTTP 269 resources which uses a checksum that is calculated independently of 270 the content (see Section 6.4 of [SEMANTICS]). It uses the 271 representation data (see Section 8.1 of [SEMANTICS]), that can be 272 fully or partially contained in the content, or not contained at all. 274 This takes into account the effect of the HTTP semantics on the 275 messages; for example, the content can be affected by Range Requests 276 or methods such as HEAD, while the way the content is transferred "on 277 the wire" is dependent on other transformations (e.g. transfer 278 codings for HTTP/1.1 - see Section 6.1 of [HTTP11]). To help 279 illustrate how such things affect Digest, several examples are 280 provided in Appendix A. 282 A representation digest consists of the value of a checksum computed 283 on the entire selected representation data (see Section 8.1 of 284 [SEMANTICS]) of a resource identified according to Section 6.4.2 of 285 [SEMANTICS] together with an indication of the algorithm used: 287 representation-data-digest = digest-algorithm "=" 288 290 When a message has no representation data it is still possible to 291 assert that no representation data was sent computing the 292 representation digest on an empty string (see Section 8.3). 294 The checksum is computed using one of the digest-algorithms listed in 295 the HTTP Digest Algorithm Values Registry (see Section 6) and then 296 encoded in the associated format. 298 3. The Digest Field 300 The Digest field contains a comma-separated list of one or more 301 representation digest values as defined in Section 2. It can be used 302 in both requests and responses. 304 Digest = 1#representation-data-digest 306 For example: 308 Digest: sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 309 AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 311 A Digest field MAY contain multiple representation-data-digest 312 values. For example, a server may provide representation-data-digest 313 values using different algorithms, allowing it to support a 314 population of clients with different evolving capabilities; this is 315 particularly useful in support of transitioning away from weaker 316 algorithms should the need arise (see Section 8.6). 318 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 319 sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 320 AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 322 A recipient MAY ignore any or all of the representation-data-digests 323 in a Digest field. This allows the recipient to choose which digest- 324 algorithm(s) to use for validation instead of verifying every 325 received representation-data-digest. 327 A sender MAY send a representation-data-digest using a digest- 328 algorithm without knowing whether the recipient supports the digest- 329 algorithm, or even knowing that the recipient will ignore it. 331 Digest can be sent in a trailer section. In this case, Digest MAY be 332 merged into the header section; see Section 6.5.1 of [SEMANTICS]. 334 When an incremental digest-algorithm is used, the sender and the 335 receiver can dynamically compute the digest value while streaming the 336 content. 338 A non-comprehensive set of examples showing the impacts of 339 representation metadata, payload transformations and HTTP methods on 340 Digest is provided in Appendix B and Appendix C. 342 4. The Content-Digest Field 344 The Content-Digest field contains a comma-separated list of one or 345 more content digest values. A content digest value is computed by 346 applying a digest-algorithm to the actual message content (see 347 Section 6.4 of [SEMANTICS]). It can be used in both requests and 348 responses. 350 Content-Digest = 1#content-digest 351 content-digest = digest-algorithm "=" 352 354 For example: 356 Content-Digest: sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 357 AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 359 A Content-Digest field MAY contain multiple content-digest values, 360 similarly to Digest (see Section 3) 362 Content-Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 363 sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 364 AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 366 A recipient MAY ignore any or all of the content-digests in a 367 Content-Digest field. This allows the recipient to choose which 368 digest-algorithm(s) to use for validation instead of verifying every 369 received content-digest. 371 A sender MAY send a content-digest using a digest-algorithm without 372 knowing whether the recipient supports the digest-algorithm, or even 373 knowing that the recipient will ignore it. 375 Content-Digest can be sent in a trailer section. In this case, 376 Content-Digest MAY be merged into the header section; see 377 Section 6.5.1 of [SEMANTICS]. 379 When an incremental digest-algorithm is used, the sender and the 380 receiver can dynamically compute the digest value while streaming the 381 content. 383 5. Want-Digest and Want-Content-Digest Fields 385 Senders can indicate their integrity checksum preferences using the 386 Want-Digest or Want-Content-Digest fields. These can be used in both 387 requests and responses. 389 Want-Digest indicates the sender's desire to receive a representation 390 digest on messages associated with the request URI and representation 391 metadata, using the Digest field. 393 Want-Content-Digest indicates the sender's desire to receive a 394 content digest on messages associated with the request URI and 395 representation metadata, using the Content-Digest field. 397 Want-Digest = 1#want-digest-value 398 Want-Content-Digest = 1#want-digest-value 399 want-digest-value = digest-algorithm [ ";" "q" "=" qvalue] 401 qvalue indicates the sender's digest-algorithm preferences. 402 Section 12.4.2 of [SEMANTICS]) describes qvalue usage and semantics. 404 Senders can provide multiple digest-algorithm items with the same 405 qvalue. 407 Examples: 409 Want-Digest: sha-256 410 Want-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0 411 Want-Content-Digest: sha-256 412 Want-Content-Digest: sha-512;q=0.3, sha-256;q=1, unixsum;q=0 414 6. Digest Algorithm Values 416 Digest-algorithm values are used to indicate a specific digest 417 computation. 419 digest-algorithm = token 421 All digest-algorithm token values are case-insensitive but lower case 422 is preferred; digest-algorithm token values MUST be compared in a 423 case-insensitive fashion. 425 Every digest-algorithm defines its computation procedure and encoding 426 output. Unless specified otherwise, comparison of encoded output is 427 case-sensitive. 429 The "HTTP Digest Algorithm Values Registry", maintained by IANA at 430 https://www.iana.org/assignments/http-dig-alg/ 431 (https://www.iana.org/assignments/http-dig-alg/) registers digest- 432 algorithm values. Registrations MUST include the following fields: 434 * Digest algorithm: the token value. The registry can be used to 435 reserve token values 437 * Status: the status of the algorithm. Use "standard" for 438 standardized algorithms without known problems; "experimental" or 439 some other appropriate value 441 - e.g. according to the type and status of the primary document 442 in which the algorithm is defined; "insecure" when the 443 algorithm is insecure; "reserved" when Digest algorithm 444 references a reserved token value 446 * Description: the description of the digest-algorithm and its 447 encoding 449 * Reference: a set of pointers to the primary documents defining the 450 digest-algorithm 452 The associated encoding for new digest-algorithms MUST either be 453 represented as a quoted string or MUST NOT include ";" or "," in the 454 character sets used for the encoding. 456 Insecure digest algorithms MAY be used to preserve integrity against 457 accidental change, but MUST NOT be used in a potentially adversarial 458 setting; for example, when signing the digest of content for 459 authenticity. 461 The registry is initialized with the tokens listed below. 463 sha-512 464 * Digest Algorithm: sha-512 466 * Description: The SHA-512 algorithm [RFC6234]. The output of 467 this algorithm is encoded using the base64 encoding [RFC4648]. 469 * Reference: [RFC6234], [RFC4648], this document. 471 * Status: standard 473 sha-256 474 * Digest Algorithm: sha-256 475 * Description: The SHA-256 algorithm [RFC6234]. The output of 476 this algorithm is encoded using the base64 encoding [RFC4648]. 478 * Reference: [RFC6234], [RFC4648], this document. 480 * Status: standard 482 md5 483 * Digest Algorithm: md5 485 * Description: The MD5 algorithm, as specified in [RFC1321]. The 486 output of this algorithm is encoded using the base64 encoding 487 [RFC4648]. This digest-algorithm is now vulnerable to 488 collision attacks. See [NO-MD5] and [CMU-836068]. 490 * Reference: [RFC1321], [RFC4648], this document. 492 * Status: insecure 494 sha 495 * Digest Algorithm: sha 497 * Description: The SHA-1 algorithm [RFC3174]. The output of this 498 algorithm is encoded using the base64 encoding [RFC4648]. This 499 digest-algorithm is now vulnerable to collision attacks. See 500 [NO-SHA1] and [IACR-2020-014]. 502 * Reference: [RFC3174], [RFC6234], [RFC4648], this document. 504 * Status: insecure 506 unixsum 507 * Digest Algorithm: unixsum 509 * Description: The algorithm computed by the UNIX "sum" command, 510 as defined by the Single UNIX Specification, Version 2 [UNIX]. 511 The output of this algorithm is an ASCII decimal-digit string 512 representing the 16-bit checksum, which is the first word of 513 the output of the UNIX "sum" command. 515 * Reference: [UNIX], this document. 517 * Status: insecure 519 unixcksum 520 * Digest Algorithm: unixcksum 521 * Description: The algorithm computed by the UNIX "cksum" 522 command, as defined by the Single UNIX Specification, Version 2 523 [UNIX]. The output of this algorithm is an ASCII digit string 524 representing the 32-bit CRC, which is the first word of the 525 output of the UNIX "cksum" command. 527 * Reference: [UNIX], this document. 529 * Status: insecure 531 adler32 532 * Digest Algorithm: adler32 534 * Description: The ADLER32 algorithm is a checksum specified in 535 [RFC1950] "ZLIB Compressed Data Format". The 32-bit output is 536 encoded in hexadecimal (using between 1 and 8 ASCII characters 537 from 0-9, A-F, and a-f; leading 0's are allowed). For example, 538 adler32=03da0195 and adler32=3DA0195 are both valid checksums 539 for the 4-byte message "Wiki". This algorithm is obsoleted and 540 SHOULD NOT be used. 542 * Reference: [RFC1950], this document. 544 * Status: insecure 546 crc32c 547 * Digest Algorithm: crc32c 549 * Description: The CRC32c algorithm is a 32-bit cyclic redundancy 550 check. It achieves a better hamming distance (for better 551 error-detection performance) than many other 32-bit CRC 552 functions. Other places it is used include iSCSI and SCTP. 553 The 32-bit output is encoded in hexadecimal (using between 1 554 and 8 ASCII characters from 0-9, A-F, and a-f; leading 0's are 555 allowed). For example, crc32c=0a72a4df and crc32c=A72A4DF are 556 both valid checksums for the 3-byte message "dog". 558 * Reference: [RFC4960] appendix B, this document. 560 * Status: insecure 562 7. Using Digest in State-Changing Requests 564 When the representation enclosed in a state-changing request does not 565 describe the target resource, the representation digest MUST be 566 computed on the representation-data. This is the only possible 567 choice because representation digest requires complete representation 568 metadata (see Section 2). 570 In responses, 572 * if the representation describes the status of the request, Digest 573 MUST be computed on the enclosed representation (see Appendix B.8 574 ); 576 * if there is a referenced resource Digest MUST be computed on the 577 selected representation of the referenced resource even if that is 578 different from the target resource. That might or might not 579 result in computing Digest on the enclosed representation. 581 The latter case is done according to the HTTP semantics of the given 582 method, for example using the Content-Location header field (see 583 Section 8.7 of [SEMANTICS]). In contrast, the Location header field 584 does not affect Digest because it is not representation metadata. 586 For example, in PATCH requests, the representation digest will be 587 computed on the patch document because the representation metadata 588 refers to the patch document and not to the target resource (see 589 Section 2 of [PATCH]). In responses, instead, the representation 590 digest will be computed on the selected representation of the patched 591 resource. 593 7.1. Digest and Content-Location in Responses 595 When a state-changing method returns the Content-Location header 596 field, the enclosed representation refers to the resource identified 597 by its value and Digest is computed accordingly. An example is given 598 in Appendix B.7. 600 8. Security Considerations 602 8.1. Digest Does Not Protect the Full HTTP Message 604 This document specifies a data integrity mechanism that protects HTTP 605 representation data or content, but not HTTP header and trailer 606 fields, from certain kinds of accidental corruption. 608 Digest fields are not intended to be a general protection against 609 malicious tampering with HTTP messages. This can be achieved by 610 combining it with other approaches such as transport-layer security 611 or digital signatures. 613 8.2. Digest for End-to-End Integrity 615 Digest fields can help detect representation data or content 616 modification due to implementation errors, undesired "transforming 617 proxies" (see Section 7.7 of [SEMANTICS]) or other actions as the 618 data passes across multiple hops or system boundaries. Even a simple 619 mechanism for end-to-end representation data integrity is valuable 620 because user-agent can validate that resource retrieval succeeded 621 before handing off to a HTML parser, video player etc. for parsing. 623 Note that using digest fields alone does not provide end-to-end 624 integrity of HTTP messages over multiple hops, since metadata could 625 be manipulated at any stage. Methods to protect metadata are 626 discussed in Section 8.3. 628 8.3. Usage in Signatures 630 Digital signatures are widely used together with checksums to provide 631 the certain identification of the origin of a message [NIST800-32]. 632 Such signatures can protect one or more HTTP fields and there are 633 additional considerations when Digest is included in this set. 635 Since digest fields are hashes of resource representations, they 636 explicitly depend on the representation metadata (e.g. the values of 637 Content-Type, Content-Encoding etc). A signature that protects 638 Digest but not other representation metadata can expose the 639 communication to tampering. For example, an actor could manipulate 640 the Content-Type field-value and cause a digest validation failure at 641 the recipient, preventing the application from accessing the 642 representation. Such an attack consumes the resources of both 643 endpoints. See also Section 7.1. 645 Digest fields SHOULD always be used over a connection that provides 646 integrity at the transport layer that protects HTTP fields. 648 A Digest field using NOT RECOMMENDED digest-algorithms SHOULD NOT be 649 used in signatures. 651 Using signatures to protect the checksum of an empty representation 652 allows receiving endpoints to detect if an eventual payload has been 653 stripped or added. 655 Any mangling of digest fields, including de-duplication of 656 representation-data-digest values or combining different field values 657 (see Section 5.2 of [SEMANTICS]) might affect signature validation. 659 8.4. Usage in Trailer Fields 661 Before sending digest fields in a trailer section, the sender should 662 consider that intermediaries are explicitly allowed to drop any 663 trailer (see Section 6.5.2 of [SEMANTICS]). 665 When digest fields are used in a trailer section, the field-values 666 are received after the content. Eager processing of content before 667 the trailer section prevents digest validation, possibly leading to 668 processing of invalid data. 670 Not every digest-algorithm is suitable for use in the trailer 671 section, some may require to pre-process the whole payload before 672 sending a message (e.g. see [I-D.thomson-http-mice]). 674 8.5. Usage with Encryption 676 Digest fields may expose details of encrypted payload when the 677 checksum is computed on the unencrypted data. 679 The checksum of an encrypted payload can change between different 680 messages depending on the encryption algorithm used; in those cases 681 its value could not be used to provide a proof of integrity "at rest" 682 unless the whole (e.g. encoded) content is persisted. 684 8.6. Algorithm Agility 686 The security properties of digest-algorithms are not fixed. 687 Algorithm Agility (see [RFC7696]) is achieved by providing 688 implementations with flexibility choose digest-algorithms from the 689 IANA Digest Algorithm Values registry in Section 9.1. 691 To help endpoints distinguish weaker algorithms from stronger ones, 692 this document adds to the IANA Digest Algorithm Values registry a new 693 "Status" field containing the most recent appraisal of the digest- 694 algorithm. 696 An endpoint might have a preference for algorithms, such as 697 preferring "standard" algorithms over "insecure" ones. Transition 698 from weak algorithms is supported by negotiation of digest-algorithm 699 using Want-Digest or Want-Content-Digest (see Section 5) or by 700 sending multiple representation-data-digest values from which the 701 receiver chooses. Endpoints are advised that sending multiple values 702 consumes resources, which may be wasted if the receiver ignores them 703 (see Section 3). 705 8.7. Duplicate digest-algorithm in field value 707 An endpoint might receive multiple representation-data-digest values 708 (see Section 3) that use the same digest-algorithm with different or 709 identical digest-values. For example: 711 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=, 712 sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= 714 A receiver is permitted to ignore any representation-data-digest 715 value, so validation of duplicates is left as an implementation 716 decision. Endpoints might select all, some, or none of the values 717 for checksum comparison and, based on the intersection of those 718 results, conditionally pass or fail digest validation. 720 8.8. Resource exhaustion 722 Digest fields validation consumes computational resources. In order 723 to avoid resource exhaustion, implementations can restrict validation 724 of the algorithm types, number of validations, or the size of 725 content. 727 9. IANA Considerations 729 9.1. Establish the HTTP Digest Algorithm Values Registry 731 This memo sets this specification to be the establishing document for 732 the HTTP Digest Algorithm Values (https://www.iana.org/assignments/ 733 http-dig-alg/) registry. 735 IANA is asked to update the "Reference" for this registry to refer 736 this document and to inizialize the registry with the tokens defined 737 in Section 6. 739 This registry uses the Specification Required policy (Section 4.6 of 740 [RFC8126]). 742 9.2. Obsolete "contentMD5" token in Digest Algorithm 744 This memo adds the "contentMD5" token in the HTTP Digest Algorithm 745 Values (https://www.iana.org/assignments/http-dig-alg/) registry: 747 * Digest Algorithm: contentMD5 749 * Description: Section 5 of [RFC3230] defined the "contentMD5" token 750 to be used only in Want-Digest. This token is obsoleted and MUST 751 NOT be used. 753 * Reference: Section 9.2 of this document, Section 5 of [RFC3230]. 755 * Status: obsoleted 757 9.3. Changes Compared to RFC3230 759 The contentMD5 digest-algorithm token defined in Section 5 of 760 [RFC3230] has been added to the HTTP Digest Algorithm Values Registry 761 with the "obsoleted" status. 763 All digest-algorithms defined in [RFC3230] are now "insecure". 765 9.4. Changes Compared to RFC5843 767 The digest-algorithm tokens for "MD5", "SHA", "SHA-256", "SHA-512" 768 have been updated to lowercase. 770 The status of "MD5" and "SHA" has been updated to "insecure", and 771 their description has been modified accordingly. 773 9.5. Want-Digest Field Registration 775 This section registers the Want-Digest field in the "Hypertext 776 Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. 778 Field name: Want-Digest 780 Status: permanent 782 Specification document(s): Section 5 of this document 784 9.6. Digest Field Registration 786 This section registers the Digest field in the "Hypertext Transfer 787 Protocol (HTTP) Field Name Registry" [SEMANTICS]. 789 Field name: Digest 791 Status: permanent 793 Specification document(s): Section 3 of this document 795 9.7. Want-Content-Digest Field Registration 797 This section registers the Want-Content-Digest field in the 798 "Hypertext Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. 800 Field name: Want-Content-Digest 801 Status: permanent 803 Specification document(s): Section 5 of this document 805 9.8. Content-Digest Field Registration 807 This section registers the Content-Digest field in the "Hypertext 808 Transfer Protocol (HTTP) Field Name Registry" [SEMANTICS]. 810 Field name: Content-Digest 812 Status: permanent 814 Specification document(s): Section 4 of this document 816 10. References 818 10.1. Normative References 820 [CMU-836068] 821 Carnagie Mellon University, Software Engineering 822 Institute, "MD5 Vulnerable to collision attacks", 31 823 December 2008, . 825 [IACR-2020-014] 826 Leurent, G. and T. Peyrin, "SHA-1 is a Shambles", 5 827 January 2020, . 829 [NIST800-32] 830 National Institute of Standards and Technology, U.S. 831 Department of Commerce, "Introduction to Public Key 832 Technology and the Federal PKI Infrastructure", February 833 2001, . 836 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 837 DOI 10.17487/RFC1321, April 1992, 838 . 840 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 841 Specification version 3.3", RFC 1950, 842 DOI 10.17487/RFC1950, May 1996, 843 . 845 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 846 Requirement Levels", BCP 14, RFC 2119, 847 DOI 10.17487/RFC2119, March 1997, 848 . 850 [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 851 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, 852 . 854 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 855 RFC 3230, DOI 10.17487/RFC3230, January 2002, 856 . 858 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 859 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 860 . 862 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 863 RFC 4960, DOI 10.17487/RFC4960, September 2007, 864 . 866 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 867 Specifications: ABNF", STD 68, RFC 5234, 868 DOI 10.17487/RFC5234, January 2008, 869 . 871 [RFC5843] Bryan, A., "Additional Hash Algorithms for HTTP Instance 872 Digests", RFC 5843, DOI 10.17487/RFC5843, April 2010, 873 . 875 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 876 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 877 DOI 10.17487/RFC6234, May 2011, 878 . 880 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 881 RFC 7405, DOI 10.17487/RFC7405, December 2014, 882 . 884 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 885 Writing an IANA Considerations Section in RFCs", BCP 26, 886 RFC 8126, DOI 10.17487/RFC8126, June 2017, 887 . 889 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 890 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 891 May 2017, . 893 [SEMANTICS] 894 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 895 Semantics", Work in Progress, Internet-Draft, draft-ietf- 896 httpbis-semantics-19, 12 September 2021, 897 . 900 [UNIX] The Open Group, "The Single UNIX Specification, Version 2 901 - 6 Vol Set for UNIX 98", February 1997. 903 10.2. Informative References 905 [HTTP11] Fielding, R. T., Nottingham, M., and J. Reschke, 906 "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf- 907 httpbis-messaging-19, 12 September 2021, 908 . 911 [I-D.ietf-httpbis-header-structure] 912 Nottingham, M. and P. Kamp, "Structured Field Values for 913 HTTP", Work in Progress, Internet-Draft, draft-ietf- 914 httpbis-header-structure-19, 3 June 2020, 915 . 918 [I-D.thomson-http-mice] 919 Thomson, M. and J. Yasskin, "Merkle Integrity Content 920 Encoding", Work in Progress, Internet-Draft, draft- 921 thomson-http-mice-03, 13 August 2018, 922 . 925 [NO-MD5] Turner, S. and L. Chen, "Updated Security Considerations 926 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 927 RFC 6151, DOI 10.17487/RFC6151, March 2011, 928 . 930 [NO-SHA1] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security 931 Considerations for the SHA-0 and SHA-1 Message-Digest 932 Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011, 933 . 935 [PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 936 RFC 5789, DOI 10.17487/RFC5789, March 2010, 937 . 939 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 940 DOI 10.17487/RFC2818, May 2000, 941 . 943 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 944 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 945 DOI 10.17487/RFC7231, June 2014, 946 . 948 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 949 DOI 10.17487/RFC7396, October 2014, 950 . 952 [RFC7696] Housley, R., "Guidelines for Cryptographic Algorithm 953 Agility and Selecting Mandatory-to-Implement Algorithms", 954 BCP 201, RFC 7696, DOI 10.17487/RFC7696, November 2015, 955 . 957 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 958 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 959 . 961 Appendix A. Resource Representation and Representation-Data 963 The following examples show how representation metadata, payload 964 transformations and method impacts on the message and content. When 965 the content contains non-printable characters (e.g. when it is 966 compressed) it is shown as a Base64-encoded string. 968 PUT /entries/1234 HTTP/1.1 969 Host: foo.example 970 Content-Type: application/json 972 {"hello": "world"} 974 Figure 1: Request containing a JSON object without any content coding 976 PUT /entries/1234 HTTP/1.1 977 Host: foo.example 978 Content-Type: application/json 979 Content-Encoding: gzip 981 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 983 Figure 2: Request containing a gzip-encoded JSON object 985 Now the same content conveys a malformed JSON object, because the 986 request does not indicate a content coding. 988 PUT /entries/1234 HTTP/1.1 989 Host: foo.example 990 Content-Type: application/json 992 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 994 Figure 3: Request containing malformed JSON 996 A Range-Request alters the content, conveying a partial 997 representation. 999 GET /entries/1234 HTTP/1.1 1000 Host: foo.example 1001 Range: bytes=1-7 1003 Figure 4: Request for partial content 1005 HTTP/1.1 206 Partial Content 1006 Content-Encoding: gzip 1007 Content-Type: application/json 1008 Content-Range: bytes 1-7/18 1010 iwgAla3RXA== 1012 Figure 5: Partial response from a gzip-encoded representation 1014 The method can also alter the content. For example, the response to 1015 a HEAD request does not carry content. 1017 HEAD /entries/1234 HTTP/1.1 1018 Host: foo.example 1019 Accept: application/json 1020 Accept-Encoding: gzip 1022 Figure 6: HEAD request 1024 HTTP/1.1 200 OK 1025 Content-Type: application/json 1026 Content-Encoding: gzip 1028 Figure 7: Response to HEAD request (empty content) 1030 Finally, the semantics of an HTTP response might decouple the 1031 effective request URI from the enclosed representation. In the 1032 example response below, the Content-Location header field indicates 1033 that the enclosed representation refers to the resource available at 1034 /authors/123, even though the request is directed to /authors/. 1036 POST /authors/ HTTP/1.1 1037 Host: foo.example 1038 Accept: application/json 1039 Content-Type: application/json 1041 {"author": "Camilleri"} 1043 Figure 8: POST request 1045 HTTP/1.1 201 Created 1046 Content-Type: application/json 1047 Content-Location: /authors/123 1048 Location: /authors/123 1050 {"id": "123", "author": "Camilleri"} 1052 Figure 9: Response with Content-Location header 1054 Appendix B. Examples of Unsolicited Digest 1056 The following examples demonstrate interactions where a server 1057 responds with a Digest or Content-Digest fields even though the 1058 client did not solicit one using Want-Digest or Want-Content-Digest. 1060 Some examples include JSON objects in the content. For presentation 1061 purposes, objects that fit completely within the line-length limits 1062 are presented on a single line using compact notation with no leading 1063 space. Objects that would exceed line-length limits are presented 1064 across multiple lines (one line per key-value pair) with 2 spaced of 1065 leading indentation. 1067 Checksum mechanisms defined in this document are media-type agnostic 1068 and do not provide canonicalization algorithms for specific formats. 1069 Examples are calculated inclusive of any space. While examples can 1070 include both fields, Digest and Content-Digest can be returned 1071 independently. 1073 B.1. Server Returns Full Representation Data 1075 In this example, the message content conveys complete representation 1076 data, so Digest and Content-Digest have the same value. 1078 GET /items/123 HTTP/1.1 1079 Host: foo.example 1081 Figure 10: GET request for an item 1083 HTTP/1.1 200 OK 1084 Content-Type: application/json 1085 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1086 Content-Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1088 {"hello": "world"} 1090 Figure 11: Response with Content-Digest 1092 B.2. Server Returns No Representation Data 1094 In this example, a HEAD request is used to retrieve the checksum of a 1095 resource. 1097 The response Digest field-value is calculated over the JSON object 1098 {"hello": "world"}, which is not shown because there is no payload 1099 data. Content-Digest is computed on empty content. 1101 HEAD /items/123 HTTP/1.1 1102 Host: foo.example 1104 Figure 12: HEAD request for an item 1106 HTTP/1.1 200 OK 1107 Content-Type: application/json 1108 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1109 Content-Digest: sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= 1111 Figure 13: Response with both Content-Digest and Digest; empty 1112 content 1114 B.3. Server Returns Partial Representation Data 1116 In this example, the client makes a range request and the server 1117 responds with partial content. The Digest field-value represents the 1118 entire JSON object {"hello": "world"}, while the Content-Digest 1119 field-value is computed on the message content "hello". 1121 GET /items/123 HTTP/1.1 1122 Host: foo.example 1123 Range: bytes=1-7 1125 Figure 14: Request for partial content 1127 HTTP/1.1 206 Partial Content 1128 Content-Type: application/json 1129 Content-Range: bytes 1-7/18 1130 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1131 Content-Digest: sha-256=Wqdirjg/u3J688ejbUlApbjECpiUUtIwT8lY/z81Tno= 1133 "hello" 1135 Figure 15: Partial response with both Content-Digest and Digest 1137 B.4. Client and Server Provide Full Representation Data 1139 The request contains a Digest field-value calculated on the enclosed 1140 representation. It also includes an Accept-Encoding: br header field 1141 that advertises the client supports Brotli encoding. 1143 The response includes a Content-Encoding: br that indicates the 1144 selected representation is Brotli-encoded. The Digest field-value is 1145 therefore different compared to the request. 1147 For presentation purposes, the response body is displayed as a 1148 Base64-encoded string because it contains non-printable characters. 1150 PUT /items/123 HTTP/1.1 1151 Host: foo.example 1152 Content-Type: application/json 1153 Accept-Encoding: br 1154 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1156 {"hello": "world"} 1158 Figure 16: PUT Request with Digest 1160 HTTP/1.1 200 OK 1161 Content-Type: application/json 1162 Content-Location: /items/123 1163 Content-Encoding: br 1164 Content-Length: 22 1165 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1167 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 1169 Figure 17: Response with Digest of encoded response 1171 B.5. Client Provides Full Representation Data, Server Provides No 1172 Representation Data 1174 The request Digest field-value is calculated on the enclosed payload. 1176 The response Digest field-value depends on the representation 1177 metadata header fields, including Content-Encoding: br even when the 1178 response does not contain content. 1180 PUT /items/123 HTTP/1.1 1181 Host: foo.example 1182 Content-Type: application/json 1183 Content-Length: 18 1184 Accept-Encoding: br 1185 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1187 {"hello": "world"} 1189 HTTP/1.1 204 No Content 1190 Content-Type: application/json 1191 Content-Encoding: br 1192 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1194 Figure 18: Empty response with Digest 1196 B.6. Client and Server Provide Full Representation Data 1198 The response contains two digest values using different algorithms. 1200 As the response body contains non-printable characters, it is 1201 displayed as a base64-encoded string. 1203 PUT /items/123 HTTP/1.1 1204 Host: foo.example 1205 Content-Type: application/json 1206 Accept-Encoding: br 1207 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1209 {"hello": "world"} 1211 Figure 19: PUT Request with Digest 1213 HTTP/1.1 200 OK 1214 Content-Type: application/json 1215 Content-Encoding: br 1216 Content-Location: /items/123 1217 Digest: sha-256=4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=, 1218 sha-512=pxo7aYzcGI88pnDnoSmAnaOEVys0MABhgvHY9+VI+ElE6 1219 0jBCwnMPyA/s3NF3ZO5oIWA7lf8ukk+\n5KJzm3p5og== 1221 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 1223 Figure 20: Response with Digest of Encoded Content 1225 B.7. POST Response does not Reference the Request URI 1227 The request Digest field-value is computed on the enclosed 1228 representation (see Section 7). 1230 The representation enclosed in the response refers to the resource 1231 identified by Content-Location (see Section 6.4.2 of [SEMANTICS]). 1232 Digest is thus computed on the enclosed representation. 1234 POST /books HTTP/1.1 1235 Host: foo.example 1236 Content-Type: application/json 1237 Accept: application/json 1238 Accept-Encoding: identity 1239 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 1241 {"title": "New Title"} 1243 Figure 21: POST Request with Digest 1245 HTTP/1.1 201 Created 1246 Content-Type: application/json 1247 Content-Location: /books/123 1248 Location: /books/123 1249 Digest: sha-256=yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE= 1251 { 1252 "id": "123", 1253 "title": "New Title" 1254 } 1256 Figure 22: Response with Digest of Resource 1258 Note that a 204 No Content response without content but with the same 1259 Digest field-value would have been legitimate too. In that case, 1260 Content-Digest would have been computed on an empty content. 1262 B.8. POST Response Describes the Request Status 1264 The request Digest field-value is computed on the enclosed 1265 representation (see Section 7). 1267 The representation enclosed in the response describes the status of 1268 the request, so Digest is computed on that enclosed representation. 1270 Response Digest has no explicit relation with the resource referenced 1271 by Location. 1273 POST /books HTTP/1.1 1274 Host: foo.example 1275 Content-Type: application/json 1276 Accept: application/json 1277 Accept-Encoding: identity 1278 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 1280 {"title": "New Title"} 1282 Figure 23: POST Request with Digest 1284 HTTP/1.1 201 Created 1285 Content-Type: application/json 1286 Digest: sha-256=2LBp5RKZGpsSNf8BPXlXrX4Td4Tf5R5bZ9z7kdi5VvY= 1287 Location: /books/123 1289 { 1290 "status": "created", 1291 "id": "123", 1292 "ts": 1569327729, 1293 "instance": "/books/123" 1294 } 1296 Figure 24: Response with Digest of Representation 1298 B.9. Digest with PATCH 1300 This case is analogous to a POST request where the target resource 1301 reflects the effective request URI. 1303 The PATCH request uses the application/merge-patch+json media type 1304 defined in [RFC7396]. 1306 Digest is calculated on the enclosed payload, which corresponds to 1307 the patch document. 1309 The response Digest field-value is computed on the complete 1310 representation of the patched resource. 1312 PATCH /books/123 HTTP/1.1 1313 Host: foo.example 1314 Content-Type: application/merge-patch+json 1315 Accept: application/json 1316 Accept-Encoding: identity 1317 Digest: sha-256=bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ= 1319 {"title": "New Title"} 1321 Figure 25: PATCH Request with Digest 1323 HTTP/1.1 200 OK 1324 Content-Type: application/json 1325 Digest: sha-256=yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE= 1327 { 1328 "id": "123", 1329 "title": "New Title" 1330 } 1332 Figure 26: Response with Digest of Representation 1334 Note that a 204 No Content response without content but with the same 1335 Digest field-value would have been legitimate too. 1337 B.10. Error responses 1339 In error responses, the representation-data does not necessarily 1340 refer to the target resource. Instead, it refers to the 1341 representation of the error. 1343 In the following example, a client sends the same request from 1344 Figure 25 to patch the resource located at /books/123. However, the 1345 resource does not exist and the server generates a 404 response with 1346 a body that describes the error in accordance with [RFC7807]. 1348 The response Digest field-value is computed on this enclosed 1349 representation. 1351 HTTP/1.1 404 Not Found 1352 Content-Type: application/problem+json 1353 Digest: sha-256=KPqhVXAT25LLitV1w0O167unHmVQusu+fpxm65zAsvk= 1355 { 1356 "title": "Not Found", 1357 "detail": "Cannot PATCH a non-existent resource", 1358 "status": 404 1359 } 1361 Figure 27: Response with Digest of Error Representation 1363 B.11. Use with Trailer Fields and Transfer Coding 1365 An origin server sends Digest as trailer field, so it can calculate 1366 digest-value while streaming content and thus mitigate resource 1367 consumption. The Digest field-value is the same as in Appendix B.1 1368 because Digest is designed to be independent from the use of one or 1369 more transfer codings (see Section 2). 1371 GET /items/123 HTTP/1.1 1372 Host: foo.example 1374 Figure 28: GET Request 1376 HTTP/1.1 200 OK 1377 Content-Type: application/json 1378 Transfer-Encoding: chunked 1379 Trailer: Digest 1381 8\r\n 1382 {"hello"\r\n 1383 8 1384 : "world\r\n 1385 2\r\n 1386 "}\r\n 1387 0\r\n 1388 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1390 Figure 29: Chunked Response with Digest 1392 Appendix C. Examples of Want-Digest Solicited Digest 1394 The following examples demonstrate interactions where a client 1395 solicits a Digest using Want-Digest. The behavior of Content-Digest 1396 and Want-Content-Digest is identical. 1398 Some examples include JSON objects in the content. For presentation 1399 purposes, objects that fit completely within the line-length limits 1400 are presented on a single line using compact notation with no leading 1401 space. Objects that would exceed line-length limits are presented 1402 across multiple lines (one line per key-value pair) with 2 spaced of 1403 leading indentation. 1405 Checksum mechanisms described in this document are media-type 1406 agnostic and do not provide canonicalization algorithms for specific 1407 formats. Examples are calculated inclusive of any space. 1409 C.1. Server Selects Client's Least Preferred Algorithm 1411 The client requests a digest, preferring "sha". The server is free 1412 to reply with "sha-256" anyway. 1414 GET /items/123 HTTP/1.1 1415 Host: foo.example 1416 Want-Digest: sha-256;q=0.3, sha;q=1 1418 Figure 30: GET Request with Want-Digest 1420 HTTP/1.1 200 OK 1421 Content-Type: application/json 1422 Digest: sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1424 {"hello": "world"} 1426 Figure 31: Response with Different Algorithm 1428 C.2. Server Selects Algorithm Unsupported by Client 1430 The client requests a only "sha" digest because that is the only 1431 algorithm it supports. The server is not obliged to produce a 1432 response containing a "sha" digest, it instead uses a different 1433 algorithm. 1435 GET /items/123 HTTP/1.1 1436 Host: foo.example 1437 Want-Digest: sha;q=1 1439 Figure 32: GET Request with Want-Digest 1441 HTTP/1.1 200 OK 1442 Content-Type: application/json 1443 Digest: sha-512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm 1444 +AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew== 1446 {"hello": "world"} 1448 Figure 33: Response with Unsupported Algorithm 1450 C.3. Server Does Not Support Client Algorithm and Returns an Error 1452 Appendix C.2 is an example where a server ignores the client's 1453 preferred digest algorithm. Alternatively a server can also reject 1454 the request and return an error. 1456 In this example, the client requests a "sha" Digest, and the server 1457 returns an error with problem details [RFC7807] contained in the 1458 content. The problem details contain a list of the digest algorithms 1459 that the server supports. This is purely an example, this 1460 specification does not define any format or requirements for such 1461 content. 1463 GET /items/123 HTTP/1.1 1464 Host: foo.example 1465 Want-Digest: sha;q=1 1467 Figure 34: GET Request with Want-Digest 1469 HTTP/1.1 400 Bad Request 1470 Content-Type: application/problem+json 1472 { 1473 "title": "Bad Request", 1474 "detail": "Supported digest-algorithms: sha-256, sha-512", 1475 "status": 400 1476 } 1478 Figure 35: Response advertising the supported algorithms 1480 Acknowledgements 1482 The vast majority of this document is inherited from [RFC3230], so 1483 thanks to J. Mogul and A. Van Hoff for their great work. The 1484 original idea of refreshing this document arose from an interesting 1485 discussion with M. Nottingham, J. Yasskin and M. Thomson when 1486 reviewing the MICE content coding. 1488 Thanks to Julian Reschke for his valuable contributions to this 1489 document, and to the following contributors that have helped improve 1490 this specification by reporting bugs, asking smart questions, 1491 drafting or reviewing text, and evaluating open issues: Mike Bishop, 1492 Brian Campbell, Matthew Kerwin, James Manger, Tommy Pauly, Sean 1493 Turner, and Erik Wilde. 1495 FAQ 1497 _RFC Editor: Please remove this section before publication._ 1499 1. Why remove all references to content-md5? 1501 Those were unnecessary to understanding and using this 1502 specification. 1504 2. Why remove references to instance manipulation? 1506 Those were unnecessary for correctly using and applying the 1507 specification. An example with Range Request is more than 1508 enough. This document uses the term "partial representation" 1509 which should group all those cases. 1511 3. How to use Digest with PATCH method? 1513 See Section 7. 1515 4. Why remove references to delta-encoding? 1517 Unnecessary for a correct implementation of this specification. 1518 The revised specification can be nicely adapted to "delta 1519 encoding", but all the references here to delta encoding don't 1520 add anything to this RFC. Another job would be to refresh delta 1521 encoding. 1523 5. Why remove references to Digest Authentication? 1525 This specification seems to me completely unrelated to Digest 1526 Authentication but for the word "Digest". 1528 6. What changes in Want-Digest? 1530 The contentMD5 token defined in Section 5 of [RFC3230] is 1531 deprecated by this document. 1533 To clarify that Digest and Want-Digest can be used in both 1534 requests and responses - [RFC3230] carefully uses sender and 1535 receiver in their definition - we added examples on using Want- 1536 Digest in responses to advertise the supported digest-algorithms 1537 and the inability to accept requests with unsupported digest- 1538 algorithms. 1540 7. Does this specification change supported algorithms? 1542 Yes. This RFC updates [RFC5843] which is still delegated for all 1543 algorithms updates. To simplify a future transition to 1544 Structured Fields [I-D.ietf-httpbis-header-structure] we suggest 1545 to use lowercase for digest-algorithms. 1547 8. What about mid-stream trailer fields? 1549 While mid-stream trailer fields (https://github.com/httpwg/http- 1550 core/issues/313#issuecomment-584389706) are interesting, since 1551 this specification is a rewrite of [RFC3230] we do not think we 1552 should face that. As a first thought, nothing in this document 1553 precludes future work that would find a use for mid-stream 1554 trailers, for example an incremental digest-algorithm. A 1555 document defining such a digest-algorithm is best positioned to 1556 describe how it is used. 1558 Code Samples 1560 _RFC Editor: Please remove this section before publication._ 1562 How can I generate and validate the Digest values shown in the 1563 examples throughout this document? 1565 The following python3 code can be used to generate digests for JSON 1566 objects using SHA algorithms for a range of encodings. Note that 1567 these are formatted as base64. This function could be adapted to 1568 other algorithms and should take into account their specific 1569 formatting rules. 1571 import base64, json, hashlib, brotli, logging 1572 log = logging.getLogger() 1574 def encode_item(item, encoding=lambda x: x): 1575 indent = 2 if isinstance(item, dict) and len(item) > 1 else None 1576 json_bytes = json.dumps(item, indent=indent).encode() 1577 return encoding(json_bytes) 1579 def digest_bytes(bytes_, algorithm=hashlib.sha256): 1580 checksum_bytes = algorithm(bytes_).digest() 1581 log.warning("Log bytes: \n[%r]", bytes_) 1582 return base64.encodebytes(checksum_bytes).strip() 1584 def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): 1585 content_encoded = encode_item(item, encoding) 1586 return digest_bytes(content_encoded, algorithm) 1588 item = {"hello": "world"} 1590 print("Encoding | digest-algorithm | digest-value") 1591 print("Identity | sha256 |", digest(item)) 1592 # Encoding | digest-algorithm | digest-value 1593 # Identity | sha256 | X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1595 print("Encoding | digest-algorithm | digest-value") 1596 print("Brotli | sha256 |", digest(item, encoding=brotli.compress)) 1597 # Encoding | digest-algorithm | digest-value 1598 # Brotli | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1600 print("Encoding | digest-algorithm | digest-value") 1601 print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512)) 1602 print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512, encoding=brotli.compress)) 1603 # Encoding | digest-algorithm | digest-value 1604 # Identity | sha512 | b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm' 1605 # '+AbwAgBWnrIiYllu7BNNyealdVLvRwE\nmTHWXvJwew==' 1606 # Brotli | sha512 | b'pxo7aYzcGI88pnDnoSmAnaOEVys0MABhgvHY9+VI+ElE6' 1607 # '0jBCwnMPyA/s3NF3ZO5oIWA7lf8ukk+\n5KJzm3p5og==' 1609 Changes 1611 _RFC Editor: Please remove this section before publication._ 1613 Since draft-ietf-httpbis-digest-headers-06 1614 * Remove id-sha-256 and id-sha-512 from the list of supported 1615 algorithms #855 1617 Since draft-ietf-httpbis-digest-headers-05 1619 * Reboot digest-algorithm values registry #1567 1621 * Add Content-Digest #1542 1623 * Remove SRI section #1478 1625 Since draft-ietf-httpbis-digest-headers-04 1627 * Improve SRI section #1354 1629 * About duplicate digest-algorithms #1221 1631 * Improve security considerations #852 1633 * md5 and sha deprecation references #1392 1635 * Obsolete 3230 #1395 1637 * Editorial #1362 1639 Since draft-ietf-httpbis-digest-headers-03 1641 * Reference semantics-12 1643 * Detail encryption quirks 1645 * Details on Algorithm agility #1250 1647 * Obsolete parameters #850 1649 Since draft-ietf-httpbis-digest-headers-02 1651 * Deprecate SHA-1 #1154 1653 * Avoid id-* with encrypted content 1655 * Digest is independent from MESSAGING and HTTP/1.1 is not normative 1656 #1215 1658 * Identity is not a valid field value for content-encoding #1223 1660 * Mention trailers #1157 1661 * Reference httpbis-semantics #1156 1663 * Add contentMD5 as an obsoleted digest-algorithm #1249 1665 * Use lowercase digest-algorithms names in the doc and in the 1666 digest-algorithm IANA table. 1668 Since draft-ietf-httpbis-digest-headers-01 1670 * Digest of error responses is computed on the error representation- 1671 data #1004 1673 * Effect of HTTP semantics on payload and message body moved to 1674 appendix #1122 1676 * Editorial refactoring, moving headers sections up. #1109-#1112, 1677 #1116, #1117, #1122-#1124 1679 Since draft-ietf-httpbis-digest-headers-00 1681 * Align title with document name 1683 * Add id-sha-* algorithm examples #880 1685 * Reference [RFC6234] and [RFC3174] instead of FIPS-1 1687 * Deprecate MD5 1689 * Obsolete ADLER-32 but don't forbid it #828 1691 * Update CRC32C value in IANA table #828 1693 * Use when acting on resources (POST, PATCH) #853 1695 * Added Relationship with SRI, draft Use Cases #868, #971 1697 * Warn about the implications of Content-Location 1699 Authors' Addresses 1701 Roberto Polli 1702 Team Digitale, Italian Government 1703 Italy 1705 Email: robipolli@gmail.com 1706 Lucas Pardue 1707 Cloudflare 1709 Email: lucaspardue.24.7@gmail.com