idnits 2.17.1 draft-ietf-httpbis-digest-headers-09.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (25 May 2022) is 702 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 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 7807 (Obsoleted by RFC 9457) == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-message-signatures-09 Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 9 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: 26 November 2022 25 May 2022 8 Digest Fields 9 draft-ietf-httpbis-digest-headers-09 11 Abstract 13 This document defines HTTP fields that support integrity digests. 14 The Content-Digest field can be used for the integrity of HTTP 15 message content. The Repr-Digest field can be used for the integrity 16 of HTTP representations. Want-Content-Digest and Want-Repr-Digest 17 can be used to indicate a sender's interest and preferences for 18 receiving the respective Integrity fields. 20 This document obsoletes RFC 3230 and the Digest and Want-Digest HTTP 21 fields. 23 About This Document 25 This note is to be removed before publishing as an RFC. 27 Status information for this document may be found at 28 https://datatracker.ietf.org/doc/draft-ietf-httpbis-digest-headers/. 30 Discussion of this document takes place on the HTTP Working Group 31 mailing list (mailto:ietf-http-wg@w3.org), which is archived at 32 https://lists.w3.org/Archives/Public/ietf-http-wg/. Working Group 33 information can be found at https://httpwg.org/. 35 Source for this draft and an issue tracker can be found at 36 https://github.com/httpwg/http-extensions/labels/digest-headers. 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at https://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on 26 November 2022. 55 Copyright Notice 57 Copyright (c) 2022 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 62 license-info) in effect on the date of publication of this document. 63 Please review these documents carefully, as they describe your rights 64 and restrictions with respect to this document. Code Components 65 extracted from this document must include Revised BSD License text as 66 described in Section 4.e of the Trust Legal Provisions and are 67 provided without warranty as described in the Revised BSD License. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 72 1.1. Document Structure . . . . . . . . . . . . . . . . . . . 4 73 1.2. Concept Overview . . . . . . . . . . . . . . . . . . . . 4 74 1.3. Obsoleting RFC 3230 . . . . . . . . . . . . . . . . . . . 5 75 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 6 76 2. The Content-Digest Field . . . . . . . . . . . . . . . . . . 7 77 3. The Repr-Digest Field . . . . . . . . . . . . . . . . . . . . 8 78 3.1. Using Repr-Digest in State-Changing Requests . . . . . . 9 79 3.2. Repr-Digest and Content-Location in Responses . . . . . . 10 80 4. Integrity preference fields . . . . . . . . . . . . . . . . . 10 81 5. Hash Algorithms for HTTP Digest Fields Registry . . . . . . . 11 82 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 83 6.1. HTTP Messages Are Not Protected In Full . . . . . . . . . 13 84 6.2. End-to-End Integrity . . . . . . . . . . . . . . . . . . 13 85 6.3. Usage in Signatures . . . . . . . . . . . . . . . . . . . 13 86 6.4. Usage in Trailer Fields . . . . . . . . . . . . . . . . . 14 87 6.5. Usage with Encryption . . . . . . . . . . . . . . . . . . 14 88 6.6. Algorithm Agility . . . . . . . . . . . . . . . . . . . . 14 89 6.7. Resource exhaustion . . . . . . . . . . . . . . . . . . . 15 90 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 91 7.1. HTTP Field Name Registration . . . . . . . . . . . . . . 15 92 7.2. Establish the Hash Algorithms for HTTP Digest Fields 93 Registry . . . . . . . . . . . . . . . . . . . . . . . . 16 94 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 95 8.1. Normative References . . . . . . . . . . . . . . . . . . 16 96 8.2. Informative References . . . . . . . . . . . . . . . . . 18 97 Appendix A. Resource Representation and Representation Data . . 19 98 Appendix B. Examples of Unsolicited Digest . . . . . . . . . . . 21 99 B.1. Server Returns Full Representation Data . . . . . . . . . 22 100 B.2. Server Returns No Representation Data . . . . . . . . . . 22 101 B.3. Server Returns Partial Representation Data . . . . . . . 23 102 B.4. Client and Server Provide Full Representation Data . . . 24 103 B.5. Client Provides Full Representation Data, Server Provides 104 No Representation Data . . . . . . . . . . . . . . . . . 24 105 B.6. Client and Server Provide Full Representation Data . . . 25 106 B.7. POST Response does not Reference the Request URI . . . . 26 107 B.8. POST Response Describes the Request Status . . . . . . . 26 108 B.9. Digest with PATCH . . . . . . . . . . . . . . . . . . . . 27 109 B.10. Error responses . . . . . . . . . . . . . . . . . . . . . 28 110 B.11. Use with Trailer Fields and Transfer Coding . . . . . . . 29 111 Appendix C. Examples of Want-Repr-Digest Solicited Digest . . . 29 112 C.1. Server Selects Client's Least Preferred Algorithm . . . . 30 113 C.2. Server Selects Algorithm Unsupported by Client . . . . . 30 114 C.3. Server Does Not Support Client Algorithm and Returns an 115 Error . . . . . . . . . . . . . . . . . . . . . . . . . . 30 116 Appendix D. Migrating from RFC 3230 . . . . . . . . . . . . . . 31 117 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 32 118 Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . 32 119 Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 120 Since draft-ietf-httpbis-digest-headers-08 . . . . . . . . . . 33 121 Since draft-ietf-httpbis-digest-headers-07 . . . . . . . . . . 34 122 Since draft-ietf-httpbis-digest-headers-06 . . . . . . . . . . 34 123 Since draft-ietf-httpbis-digest-headers-05 . . . . . . . . . . 34 124 Since draft-ietf-httpbis-digest-headers-04 . . . . . . . . . . 34 125 Since draft-ietf-httpbis-digest-headers-03 . . . . . . . . . . 34 126 Since draft-ietf-httpbis-digest-headers-02 . . . . . . . . . . 35 127 Since draft-ietf-httpbis-digest-headers-01 . . . . . . . . . . 35 128 Since draft-ietf-httpbis-digest-headers-00 . . . . . . . . . . 35 129 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 131 1. Introduction 133 HTTP does not define the means to protect the data integrity of 134 content or representations. When HTTP messages are transferred 135 between endpoints, lower layer features or properties such as TCP 136 checksums or TLS records [RFC2818] can provide some integrity 137 protection. However, transport-oriented integrity provides a limited 138 utility because it is opaque to the application layer and only covers 139 the extent of a single connection. HTTP messages often travel over a 140 chain of separate connections, in between connections there is a 141 possibility for unintended or malicious data corruption. An HTTP 142 integrity mechanism can provide the means for endpoints, or 143 applications using HTTP, to detect data corruption and make a choice 144 about how to act on it. An example use case is to aid fault 145 detection and diagnosis across system boundaries. 147 This document defines two digest integrity mechanisms for HTTP. 148 First, content integrity, which acts on conveyed content (Section 6.4 149 of [SEMANTICS]). Second, representation data integrity, which acts 150 on representation data (Section 3.2 of [SEMANTICS]). This supports 151 advanced use cases such as validating the integrity of a resource 152 that was reconstructed from parts retrieved using multiple requests 153 or connections. 155 This document obsoletes RFC 3230 and therefore the Digest and Want- 156 Digest HTTP fields; see Section 1.3. 158 1.1. Document Structure 160 This document is structured as follows: 162 * Section 2 defines the Content-Digest request and response header 163 and trailer field, 165 * Section 3 defines the Repr-Digest request and response header and 166 trailer field, 168 * Section 4 defines the Want-Repr-Digest and Want-Content-Digest 169 request and response header and trailer field, 171 * Section 5 describes algorithms and their relation to the fields 172 defined in this document, 174 * Section 3.1 details computing representation digests, 176 * Appendix B and Appendix C provide examples of using Repr-Digest 177 and Want-Repr-Digest. 179 1.2. Concept Overview 181 The HTTP fields defined in this document can be used for HTTP 182 integrity. Senders choose a hashing algorithm and calculate a digest 183 from an input related to the HTTP message, the algorithm identifier 184 and digest are transmitted in an HTTP field. Receivers can validate 185 the digest for integrity purposes. Hashing algorithms are registered 186 in the "Hash Algorithms for HTTP Digest Fields" (see Section 5). 188 Selecting the data on which digests are calculated depends on the use 189 case of HTTP messages. This document provides different headers for 190 HTTP representation data and HTTP content. 192 There are use-cases where a simple digest of the HTTP content bytes 193 is required. The Content-Digest request and response header and 194 trailer field is defined to support digests of content (Section 3.2 195 of [SEMANTICS]); see Section 2. 197 For more advanced use-cases, the Repr-Digest request and response 198 header and trailer field (Section 3) is defined. It contains a 199 digest value computed by applying a hashing algorithm to selected 200 representation data (Section 3.2 of [SEMANTICS]). Basing Repr-Digest 201 on the selected representation makes it straightforward to apply it 202 to use-cases where the transferred data requires some sort of 203 manipulation to be considered a representation or conveys a partial 204 representation of a resource, such as Range Requests (see 205 Section 14.2 of [SEMANTICS]). 207 Content-Digest and Repr-Digest support hashing algorithm agility. 208 The Want-Content-Digest and Want-Repr-Digest fields allow endpoints 209 to express interest in Content-Digest and Repr-Digest respectively, 210 and preference of algorithms in either. 212 Content-Digest and Repr-Digest are collectively termed Integrity 213 fields. Want-Content-Digest and Want-Repr-Digest are collectively 214 termed Integrity preference fields. 216 Integrity fields are tied to the Content-Encoding and Content-Type 217 header fields. Therefore, a given resource may have multiple 218 different digest values when transferred with HTTP. 220 Integrity fields do not provide integrity for HTTP messages or 221 fields. However, they can be combined with other mechanisms that 222 protect metadata, such as digital signatures, in order to protect the 223 phases of an HTTP exchange in whole or in part. For example, HTTP 224 Message Signatures [SIGNATURES] could be used to sign Integrity 225 fields, thus providing coverage for HTTP content or representation 226 data. 228 This specification does not define means for authentication, 229 authorization or privacy. 231 1.3. Obsoleting RFC 3230 233 [RFC3230] defined the Digest and Want-Digest HTTP fields for HTTP 234 integrity. It also coined the term "instance" and "instance 235 manipulation" in order to explain concepts that are now more 236 universally defined, and implemented, as HTTP semantics such as 237 selected representation data (Section 3.2 of [SEMANTICS]). 239 Experience has shown that implementations of [RFC3230] have 240 interpreted the meaning of "instance" inconsistently, leading to 241 interoperability issues. The most common mistake being the 242 calculation of the digest using (what we now call) message content, 243 rather than using (what we now call) representation data as was 244 originally intended. Interestingly, time has also shown that a 245 digest of message content can be beneficial for some use cases. So 246 it is difficult to detect if non-conformance to [RFC3230] is 247 intentional or unintentional. 249 In order to address potential inconsistencies and ambiguity across 250 implementations of Digest and Want-Digest, this document obsoletes 251 [RFC3230]. The Integrity fields (Section 3 and Section 2) and 252 Integrity preference fields (Section 4) defined in this document are 253 better aligned with current HTTP semantics and have names that more 254 clearly articulate the intended usages. 256 1.4. Notational Conventions 258 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 259 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 260 "OPTIONAL" in this document are to be interpreted as described in 261 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 262 capitals, as shown here. 264 This document uses the Augmented BNF defined in [RFC5234] and updated 265 by [RFC7405]. 267 This document uses the following terminology from Section 3 of 268 [STRUCTURED-FIELDS] to specify syntax and parsing: Boolean, Byte 269 Sequence, Dictionary, Integer, and List. 271 The definitions "representation", "selected representation", 272 "representation data", "representation metadata", "user agent" and 273 "content" in this document are to be interpreted as described in 274 [SEMANTICS]. 276 Hashing algorithm names respect the casing used in their definition 277 document (e.g. SHA-1, CRC32c) whereas hashing algorithm keys are 278 quoted (e.g. "sha", "crc32c"). 280 The term "checksum" describes the output of the application of an 281 algorithm to a sequence of bytes, whereas "digest" is only used in 282 relation to the value contained in the fields. 284 Integrity fields: collective term for Content-Digest and Repr-Digest 285 Integrity preference fields: collective term for Want-Repr-Digest and 286 Want-Content-Digest 288 2. The Content-Digest Field 290 The Content-Digest HTTP field can be used in requests and responses 291 to communicate digests that are calculated using a hashing algorithm 292 applied to the actual message content (see Section 6.4 of 293 [SEMANTICS]). It is a Dictionary (see Section 3.2 of 294 [STRUCTURED-FIELDS]) where each: 296 * key conveys the hashing algorithm (see Section 5) used to compute 297 the digest; 299 * value is a Byte Sequence (Section 3.3.5 of [STRUCTURED-FIELDS]), 300 that contains the output of the digest calculation. 302 For example: 304 NOTE: '\' line wrapping per RFC 8792 306 Content-Digest: \ 307 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 308 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 310 The Dictionary type can be used, for example, to attach multiple 311 digests calculated using different hashing algorithms in order to 312 support a population of endpoints with different or evolving 313 capabilities. Such an approach could support transitions away from 314 weaker algorithms (see Section 6.6). 316 NOTE: '\' line wrapping per RFC 8792 318 Repr-Digest: \ 319 sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=:,\ 320 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 321 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 323 A recipient MAY ignore any or all digests. This allows the recipient 324 to choose which hashing algorithm(s) to use for validation instead of 325 verifying every digest. 327 A sender MAY send a digest without knowing whether the recipient 328 supports a given hashing algorithm, or even knowing that the 329 recipient will ignore it. 331 Content-Digest can be sent in a trailer section. In this case, 332 Content-Digest MAY be merged into the header section; see 333 Section 6.5.1 of [SEMANTICS]. 335 3. The Repr-Digest Field 337 The Repr-Digest HTTP field can be used in requests and responses to 338 communicate digests that are calculated using a hashing algorithm 339 applied to the entire selected representation data (see Section 8.1 340 of [SEMANTICS]). 342 Representations take into account the effect of the HTTP semantics on 343 messages. For example, the content can be affected by Range Requests 344 or methods such as HEAD, while the way the content is transferred "on 345 the wire" is dependent on other transformations (e.g. transfer 346 codings for HTTP/1.1 - see Section 6.1 of [HTTP11]). To help 347 illustrate HTTP representation concepts, several examples are 348 provided in Appendix A. 350 When a message has no representation data it is still possible to 351 assert that no representation data was sent by computing the digest 352 on an empty string (see Section 6.3). 354 Repr-Digest is a Dictionary (see Section 3.2 of [STRUCTURED-FIELDS]) 355 where each: 357 * key conveys the hashing algorithm (see Section 5) used to compute 358 the digest; 360 * value is a Byte Sequence that contains the output of the digest 361 calculation. 363 For example: 365 NOTE: '\' line wrapping per RFC 8792 367 Repr-Digest: \ 368 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 369 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 371 The Dictionary type can be used, for example, to attach multiple 372 digests calculated using different hashing algorithms in order to 373 support a population of endpoints with different or evolving 374 capabilities. Such an approach could support transitions away from 375 weaker algorithms (see Section 6.6). 377 NOTE: '\' line wrapping per RFC 8792 379 Repr-Digest: \ 380 sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=:,\ 381 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 382 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 384 A recipient MAY ignore any or all digests. This allows the recipient 385 to choose which hashing algorithm(s) to use for validation instead of 386 verifying every digest. 388 A sender MAY send a digest without knowing whether the recipient 389 supports a given hashing algorithm, or even knowing that the 390 recipient will ignore it. 392 Repr-Digest can be sent in a trailer section. In this case, Repr- 393 Digest MAY be merged into the header section; see Section 6.5.1 of 394 [SEMANTICS]. 396 3.1. Using Repr-Digest in State-Changing Requests 398 When the representation enclosed in a state-changing request does not 399 describe the target resource, the representation digest MUST be 400 computed on the representation data. This is the only possible 401 choice because representation digest requires complete representation 402 metadata (see Section 3). 404 In responses, 406 * if the representation describes the status of the request, Repr- 407 Digest MUST be computed on the enclosed representation (see 408 Appendix B.8 ); 410 * if there is a referenced resource Repr-Digest MUST be computed on 411 the selected representation of the referenced resource even if 412 that is different from the target resource. That might or might 413 not result in computing Repr-Digest on the enclosed 414 representation. 416 The latter case is done according to the HTTP semantics of the given 417 method, for example using the Content-Location header field (see 418 Section 8.7 of [SEMANTICS]). In contrast, the Location header field 419 does not affect Repr-Digest because it is not representation 420 metadata. 422 For example, in PATCH requests, the representation digest will be 423 computed on the patch document because the representation metadata 424 refers to the patch document and not to the target resource (see 425 Section 2 of [PATCH]). In responses, instead, the representation 426 digest will be computed on the selected representation of the patched 427 resource. 429 3.2. Repr-Digest and Content-Location in Responses 431 When a state-changing method returns the Content-Location header 432 field, the enclosed representation refers to the resource identified 433 by its value and Repr-Digest is computed accordingly. An example is 434 given in Appendix B.7. 436 4. Integrity preference fields 438 Senders can indicate their interest in Integrity fields and hashing 439 algorithm preferences using the Want-Content-Digest or Want-Repr- 440 Digest fields. These can be used in both requests and responses. 442 Want-Content-Digest indicates that the sender would like to receive a 443 content digest on messages associated with the request URI and 444 representation metadata, using the Content-Digest field. 446 Want-Repr-Digest indicates that the sender would like to receive a 447 representation digest on messages associated with the request URI and 448 representation metadata, using the Repr-Digest field. 450 If Want-Content-Digest or Want-Repr-Digest are used in a response, it 451 indicates that the server would like the client to provide the 452 respective Integrity field on future requests. 454 Want-Content-Digest and Want-Repr-Digest are of type Dictionary where 455 each: 457 * key conveys the hashing algorithm (see Section 5); 459 * value is an Integer (Section 3.3.1 of [STRUCTURED-FIELDS]) that 460 conveys an ascending, relative, weighted preference. It must be 461 in the range 0 to 10 inclusive. 1 is the least preferred, 10 is 462 the most preferred, and a value of 0 means "not acceptable". 464 Examples: 466 Want-Repr-Digest: sha-256=1 467 Want-Repr-Digest: sha-512=3, sha-256=10, unixsum=0 468 Want-Content-Digest: sha-256=1 469 Want-Content-Digest: sha-512=3, sha-256=10, unixsum=0 471 5. Hash Algorithms for HTTP Digest Fields Registry 473 The "Hash Algorithms for HTTP Digest Fields", maintained by IANA at 474 https://www.iana.org/assignments/http-dig-alg/ 475 (https://www.iana.org/assignments/http-dig-alg/), registers 476 algorithms for use with the Integrity and Integrity preference fields 477 defined in this document. 479 This registry uses the Specification Required policy (Section 4.6 of 480 [RFC8126]). 482 Registrations MUST include the following fields: 484 * Algorithm Key: the Structured Fields key value used in Content- 485 Digest, Repr-Digest, Want-Content-Digest, or Want-Repr-Digest 486 field Dictionary member keys 488 * Status: the status of the algorithm. Use "standard" for 489 standardized algorithms without known problems; "experimental" or 490 some other appropriate value 492 - e.g. according to the type and status of the primary document 493 in which the algorithm is defined; "insecure" when the 494 algorithm is insecure; "reserved" when the algorithm references 495 a reserved token value 497 * Description: a short description of the algorithm 499 * Reference(s): a set of pointers to the primary documents defining 500 the algorithm and key 502 Insecure hashing algorithms MAY be used to preserve integrity against 503 corruption, but MUST NOT be used in a potentially adversarial 504 setting; for example, when signing Integrity fields' values for 505 authenticity. 507 The entries in Table 1 are registered by this document. 509 +===========+==========+============================+==============+ 510 | Algorithm | Status | Description | Reference(s) | 511 | Key | | | | 512 +===========+==========+============================+==============+ 513 | sha-512 | standard | The SHA-512 algorithm. | [RFC6234], | 514 | | | | [RFC4648], | 515 | | | | this | 516 | | | | document. | 517 +-----------+----------+----------------------------+--------------+ 518 | sha-256 | standard | The SHA-256 algorithm. | [RFC6234], | 519 | | | | [RFC4648], | 520 | | | | this | 521 | | | | document. | 522 +-----------+----------+----------------------------+--------------+ 523 | md5 | insecure | The MD5 algorithm. It is | [RFC1321], | 524 | | | vulnerable to collision | [RFC4648], | 525 | | | attacks; see [NO-MD5] and | this | 526 | | | [CMU-836068] | document. | 527 +-----------+----------+----------------------------+--------------+ 528 | sha | insecure | The SHA-1 algorithm. It | [RFC3174], | 529 | | | is vulnerable to collision | [RFC4648], | 530 | | | attacks; see [NO-SHA] and | [RFC6234] | 531 | | | [IACR-2020-014] | this | 532 | | | | document. | 533 +-----------+----------+----------------------------+--------------+ 534 | unixsum | insecure | The algorithm used by the | [RFC4648], | 535 | | | UNIX "sum" command. | [RFC6234], | 536 | | | | [UNIX], this | 537 | | | | document. | 538 +-----------+----------+----------------------------+--------------+ 539 | unixcksum | insecure | The algorithm used by the | [RFC4648], | 540 | | | UNIX "cksum" command. | [RFC6234], | 541 | | | | [UNIX], this | 542 | | | | document. | 543 +-----------+----------+----------------------------+--------------+ 544 | adler | insecure | The ADLER32 algorithm. | [RFC1950], | 545 | | | | this | 546 | | | | document. | 547 +-----------+----------+----------------------------+--------------+ 548 | crc32c | insecure | The CRC32c algorithm. | [RFC4960] | 549 | | | | appendix B, | 550 | | | | this | 551 | | | | document. | 552 +-----------+----------+----------------------------+--------------+ 554 Table 1: Initial Hash Algorithms 556 6. Security Considerations 558 6.1. HTTP Messages Are Not Protected In Full 560 This document specifies a data integrity mechanism that protects HTTP 561 representation data or content, but not HTTP header and trailer 562 fields, from certain kinds of corruption. 564 Integrity fields are not intended to be a general protection against 565 malicious tampering with HTTP messages. This can be achieved by 566 combining it with other approaches such as transport-layer security 567 or digital signatures (for example, HTTP Message Signatures 568 [SIGNATURES]). 570 6.2. End-to-End Integrity 572 Integrity fields can help detect representation data or content 573 modification due to implementation errors, undesired "transforming 574 proxies" (see Section 7.7 of [SEMANTICS]) or other actions as the 575 data passes across multiple hops or system boundaries. Even a simple 576 mechanism for end-to-end representation data integrity is valuable 577 because a user agent can validate that resource retrieval succeeded 578 before handing off to a HTML parser, video player etc. for parsing. 580 Note that using these mechanisms alone does not provide end-to-end 581 integrity of HTTP messages over multiple hops, since metadata could 582 be manipulated at any stage. Methods to protect metadata are 583 discussed in Section 6.3. 585 6.3. Usage in Signatures 587 Digital signatures are widely used together with checksums to provide 588 the certain identification of the origin of a message [NIST800-32]. 589 Such signatures can protect one or more HTTP fields and there are 590 additional considerations when Integrity fields are included in this 591 set. 593 There are no restrictions placed on the type or format of digitial 594 signature that Integrity fields can be used with. One possible 595 approach is to combine them with HTTP Message Signatures 596 [SIGNATURES]. 598 Digests explicitly depend on the "representation metadata" (e.g. the 599 values of Content-Type, Content-Encoding etc). A signature that 600 protects Integrity fields but not other "representation metadata" can 601 expose the communication to tampering. For example, an actor could 602 manipulate the Content-Type field-value and cause a digest validation 603 failure at the recipient, preventing the application from accessing 604 the representation. Such an attack consumes the resources of both 605 endpoints. See also Section 3.2. 607 Signatures are likely to be deemed an adversarial setting when 608 applying Integrity fields; see Section 5. Using signatures to 609 protect the checksum of an empty representation allows receiving 610 endpoints to detect if an eventual payload has been stripped or 611 added. 613 Any mangling of Integrity fields, including digests' de-duplication 614 or combining different field values (see Section 5.2 of [SEMANTICS]) 615 might affect signature validation. 617 6.4. Usage in Trailer Fields 619 Before sending Integrity fields in a trailer section, the sender 620 should consider that intermediaries are explicitly allowed to drop 621 any trailer (see Section 6.5.2 of [SEMANTICS]). 623 When Integrity fields are used in a trailer section, the field-values 624 are received after the content. Eager processing of content before 625 the trailer section prevents digest validation, possibly leading to 626 processing of invalid data. 628 Not every hashing algorithm is suitable for use in the trailer 629 section, some may require to pre-process the whole payload before 630 sending a message (e.g. see [I-D.thomson-http-mice]). 632 6.5. Usage with Encryption 634 The checksum of an encrypted payload can change between different 635 messages depending on the encryption algorithm used; in those cases 636 its value could not be used to provide a proof of integrity "at rest" 637 unless the whole (e.g. encoded) content is persisted. 639 6.6. Algorithm Agility 641 The security properties of hashing algorithms are not fixed. 642 Algorithm Agility (see [RFC7696]) is achieved by providing 643 implementations with flexibility to choose hashing algorithms from 644 the IANA Hash Algorithms for HTTP Digest Fields registry; see 645 Section 7.2. 647 The "standard" algorithms listed in this document are suitable for 648 many purposes, including adversarial situations where hash functions 649 might need to provide resistance to collision, first-preimage and 650 second-preimage attacks. Algorithms listed as "insecure" either 651 provide none of these properties, or are known to be weak (see 652 [NO-MD5] and [NO-SHA]). 654 For adversarial situations, which of the "standard" algorithms are 655 acceptable will depend on the level of protection the circumstances 656 demand. As there is no negotiation, endpoints that depend on a 657 digest for security will be vulnerable to attacks on the weakest 658 algorithm they are willing to accept. 660 Transition from weak algorithms is supported by negotiation of 661 hashing algorithm using Want-Content-Digest or Want-Repr-Digest (see 662 Section 4) or by sending multiple digests from which the receiver 663 chooses. Endpoints are advised that sending multiple values consumes 664 resources, which may be wasted if the receiver ignores them (see 665 Section 3). 667 While algorithm agility allows the migration to stronger algorithms 668 it does not prevent the use of weaker algorithms. Integrity fields 669 do not provide any mitigiations for downgrade or substitution attacks 670 (see Section 1 of [RFC6211]) of the hashing algorithm. To protect 671 against such attacks, endpoints could restrict their set of supported 672 algorithms to stronger ones and protect the fields value by using TLS 673 and/or digital signatures. 675 6.7. Resource exhaustion 677 Integrity fields validation consumes computational resources. In 678 order to avoid resource exhaustion, implementations can restrict 679 validation of the algorithm types, number of validations, or the size 680 of content. 682 7. IANA Considerations 684 7.1. HTTP Field Name Registration 686 IANA is asked to update the "Hypertext Transfer Protocol (HTTP) Field 687 Name Registry" registry ([SEMANTICS]) according to the table below: 689 +=====================+===========+============================+ 690 | Field Name | Status | Reference | 691 +=====================+===========+============================+ 692 | Content-Digest | permanent | Section 2 of this document | 693 +---------------------+-----------+----------------------------+ 694 | Repr-Digest | permanent | Section 3 of this document | 695 +---------------------+-----------+----------------------------+ 696 | Want-Content-Digest | permanent | Section 4 of this document | 697 +---------------------+-----------+----------------------------+ 698 | Want-Repr-Digest | permanent | Section 4 of this document | 699 +---------------------+-----------+----------------------------+ 700 | Digest | obsoleted | [RFC3230], Section 1.3 of | 701 | | | this document | 702 +---------------------+-----------+----------------------------+ 703 | Want-Digest | obsoleted | [RFC3230], Section 1.3 of | 704 | | | this document | 705 +---------------------+-----------+----------------------------+ 707 Table 2 709 7.2. Establish the Hash Algorithms for HTTP Digest Fields Registry 711 This memo sets this specification to be the establishing document for 712 the Hash Algorithms for HTTP Digest Fields 713 (https://www.iana.org/assignments/http-structured-dig-alg/) registry 714 defined in Section 5. 716 IANA is asked to initialize the registry with the entries in Table 1. 718 8. References 720 8.1. Normative References 722 [CMU-836068] 723 Carnagie Mellon University, Software Engineering 724 Institute, "MD5 Vulnerable to collision attacks", 31 725 December 2008, . 727 [IACR-2020-014] 728 Leurent, G. and T. Peyrin, "SHA-1 is a Shambles", 5 729 January 2020, . 731 [NIST800-32] 732 National Institute of Standards and Technology, U.S. 733 Department of Commerce, "Introduction to Public Key 734 Technology and the Federal PKI Infrastructure", February 735 2001, . 738 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 739 DOI 10.17487/RFC1321, April 1992, 740 . 742 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 743 Specification version 3.3", RFC 1950, 744 DOI 10.17487/RFC1950, May 1996, 745 . 747 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 748 Requirement Levels", BCP 14, RFC 2119, 749 DOI 10.17487/RFC2119, March 1997, 750 . 752 [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 753 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, 754 . 756 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 757 RFC 3230, DOI 10.17487/RFC3230, January 2002, 758 . 760 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 761 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 762 . 764 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 765 RFC 4960, DOI 10.17487/RFC4960, September 2007, 766 . 768 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 769 Specifications: ABNF", STD 68, RFC 5234, 770 DOI 10.17487/RFC5234, January 2008, 771 . 773 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 774 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 775 DOI 10.17487/RFC6234, May 2011, 776 . 778 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 779 RFC 7405, DOI 10.17487/RFC7405, December 2014, 780 . 782 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 783 Writing an IANA Considerations Section in RFCs", BCP 26, 784 RFC 8126, DOI 10.17487/RFC8126, June 2017, 785 . 787 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 788 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 789 May 2017, . 791 [SEMANTICS] 792 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 793 Semantics", Work in Progress, Internet-Draft, draft-ietf- 794 httpbis-semantics-19, 12 September 2021, 795 . 798 [STRUCTURED-FIELDS] 799 Nottingham, M. and P-H. Kamp, "Structured Field Values for 800 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 801 . 803 [UNIX] The Open Group, "The Single UNIX Specification, Version 2 804 - 6 Vol Set for UNIX 98", February 1997. 806 8.2. Informative References 808 [HTTP11] Fielding, R. T., Nottingham, M., and J. Reschke, 809 "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf- 810 httpbis-messaging-19, 12 September 2021, 811 . 814 [I-D.thomson-http-mice] 815 Thomson, M. and J. Yasskin, "Merkle Integrity Content 816 Encoding", Work in Progress, Internet-Draft, draft- 817 thomson-http-mice-03, 13 August 2018, 818 . 821 [NO-MD5] Turner, S. and L. Chen, "Updated Security Considerations 822 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 823 RFC 6151, DOI 10.17487/RFC6151, March 2011, 824 . 826 [NO-SHA] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security 827 Considerations for the SHA-0 and SHA-1 Message-Digest 828 Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011, 829 . 831 [PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 832 RFC 5789, DOI 10.17487/RFC5789, March 2010, 833 . 835 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 836 DOI 10.17487/RFC2818, May 2000, 837 . 839 [RFC6211] Schaad, J., "Cryptographic Message Syntax (CMS) Algorithm 840 Identifier Protection Attribute", RFC 6211, 841 DOI 10.17487/RFC6211, April 2011, 842 . 844 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 845 DOI 10.17487/RFC7396, October 2014, 846 . 848 [RFC7696] Housley, R., "Guidelines for Cryptographic Algorithm 849 Agility and Selecting Mandatory-to-Implement Algorithms", 850 BCP 201, RFC 7696, DOI 10.17487/RFC7696, November 2015, 851 . 853 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 854 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 855 . 857 [SIGNATURES] 858 Backman, A., Richer, J., and M. Sporny, "HTTP Message 859 Signatures", Work in Progress, Internet-Draft, draft-ietf- 860 httpbis-message-signatures-09, 6 March 2022, 861 . 864 Appendix A. Resource Representation and Representation Data 866 The following examples show how representation metadata, payload 867 transformations and method impacts on the message and content. When 868 the content contains non-printable characters (e.g. when it is 869 compressed) it is shown as a Base64-encoded string. 871 PUT /entries/1234 HTTP/1.1 872 Host: foo.example 873 Content-Type: application/json 875 {"hello": "world"} 877 Figure 1: Request containing a JSON object without any content coding 878 PUT /entries/1234 HTTP/1.1 879 Host: foo.example 880 Content-Type: application/json 881 Content-Encoding: gzip 883 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 885 Figure 2: Request containing a gzip-encoded JSON object 887 Now the same content conveys a malformed JSON object, because the 888 request does not indicate a content coding. 890 PUT /entries/1234 HTTP/1.1 891 Host: foo.example 892 Content-Type: application/json 894 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 896 Figure 3: Request containing malformed JSON 898 A Range-Request alters the content, conveying a partial 899 representation. 901 GET /entries/1234 HTTP/1.1 902 Host: foo.example 903 Range: bytes=1-7 905 Figure 4: Request for partial content 907 HTTP/1.1 206 Partial Content 908 Content-Encoding: gzip 909 Content-Type: application/json 910 Content-Range: bytes 1-7/18 912 iwgAla3RXA== 914 Figure 5: Partial response from a gzip-encoded representation 916 The method can also alter the content. For example, the response to 917 a HEAD request does not carry content. 919 HEAD /entries/1234 HTTP/1.1 920 Host: foo.example 921 Accept: application/json 922 Accept-Encoding: gzip 924 Figure 6: HEAD request 926 HTTP/1.1 200 OK 927 Content-Type: application/json 928 Content-Encoding: gzip 930 Figure 7: Response to HEAD request (empty content) 932 Finally, the semantics of an HTTP response might decouple the 933 effective request URI from the enclosed representation. In the 934 example response below, the Content-Location header field indicates 935 that the enclosed representation refers to the resource available at 936 /authors/123, even though the request is directed to /authors/. 938 POST /authors/ HTTP/1.1 939 Host: foo.example 940 Accept: application/json 941 Content-Type: application/json 943 {"author": "Camilleri"} 945 Figure 8: POST request 947 HTTP/1.1 201 Created 948 Content-Type: application/json 949 Content-Location: /authors/123 950 Location: /authors/123 952 {"id": "123", "author": "Camilleri"} 954 Figure 9: Response with Content-Location header 956 Appendix B. Examples of Unsolicited Digest 958 The following examples demonstrate interactions where a server 959 responds with a Content-Digest or Repr-Digest fields even though the 960 client did not solicit one using Want-Content-Digest or Want-Repr- 961 Digest. 963 Some examples include JSON objects in the content. For presentation 964 purposes, objects that fit completely within the line-length limits 965 are presented on a single line using compact notation with no leading 966 space. Objects that would exceed line-length limits are presented 967 across multiple lines (one line per key-value pair) with 2 spaced of 968 leading indentation. 970 Checksum mechanisms defined in this document are media-type agnostic 971 and do not provide canonicalization algorithms for specific formats. 972 Examples are calculated inclusive of any space. While examples can 973 include both fields, Content-Digest and Repr-Digest can be returned 974 independently. 976 B.1. Server Returns Full Representation Data 978 In this example, the message content conveys complete representation 979 data. This means that in the response, Content-Digest and Repr- 980 Digest are both computed over the JSON object {"hello": "world"}, and 981 thus have the same value. 983 GET /items/123 HTTP/1.1 984 Host: foo.example 986 Figure 10: GET request for an item 988 NOTE: '\' line wrapping per RFC 8792 990 HTTP/1.1 200 OK 991 Content-Type: application/json 992 Content-Digest: \ 993 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 994 Repr-Digest: \ 995 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 997 {"hello": "world"} 999 Figure 11: Response with identical Repr-Digest and Content-Digest 1001 B.2. Server Returns No Representation Data 1003 In this example, a HEAD request is used to retrieve the checksum of a 1004 resource. 1006 The response Content-Digest field-value is computed on empty content. 1007 Repr-Digest is calculated over the JSON object {"hello": "world"}, 1008 which is not shown because there is no payload data. 1010 HEAD /items/123 HTTP/1.1 1011 Host: foo.example 1013 Figure 12: HEAD request for an item 1015 NOTE: '\' line wrapping per RFC 8792 1017 HTTP/1.1 200 OK 1018 Content-Type: application/json 1019 Content-Digest: \ 1020 sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=: 1021 Repr-Digest: \ 1022 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1024 Figure 13: Response with both Content-Digest and Digest; empty 1025 content 1027 B.3. Server Returns Partial Representation Data 1029 In this example, the client makes a range request and the server 1030 responds with partial content. 1032 GET /items/123 HTTP/1.1 1033 Host: foo.example 1034 Range: bytes=1-7 1036 Figure 14: Request for partial content 1038 NOTE: '\' line wrapping per RFC 8792 1040 HTTP/1.1 206 Partial Content 1041 Content-Type: application/json 1042 Content-Range: bytes 1-7/18 1043 Content-Digest: \ 1044 sha-256=:Wqdirjg/u3J688ejbUlApbjECpiUUtIwT8lY/z81Tno=: 1045 Repr-Digest: \ 1046 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1048 "hello" 1050 Figure 15: Partial response with both Content-Digest and Repr-Digest 1052 In the response message above, note that the Repr-Digest and Content- 1053 Digests are different. The Repr-Digest field-value is calculated 1054 across the entire JSON object {"hello": "world"}, and the field is 1056 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1058 However, since the message content is constrained to bytes 1-7, the 1059 Content-Digest field-value is calculated over the byte sequence 1060 "hello", thus resulting in 1061 NOTE: '\' line wrapping per RFC 8792 1063 Content-Digest: \ 1064 sha-256=:Wqdirjg/u3J688ejbUlApbjECpiUUtIwT8lY/z81Tno=: 1066 B.4. Client and Server Provide Full Representation Data 1068 The request contains a Repr-Digest field-value calculated on the 1069 enclosed representation. It also includes an Accept-Encoding: br 1070 header field that advertises the client supports Brotli encoding. 1072 The response includes a Content-Encoding: br that indicates the 1073 selected representation is Brotli-encoded. The Repr-Digest field- 1074 value is therefore different compared to the request. 1076 For presentation purposes, the response body is displayed as a 1077 Base64-encoded string because it contains non-printable characters. 1079 PUT /items/123 HTTP/1.1 1080 Host: foo.example 1081 Content-Type: application/json 1082 Accept-Encoding: br 1083 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1085 {"hello": "world"} 1087 Figure 16: PUT Request with Digest 1089 HTTP/1.1 200 OK 1090 Content-Type: application/json 1091 Content-Location: /items/123 1092 Content-Encoding: br 1093 Content-Length: 22 1094 Repr-Digest: sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=: 1096 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 1098 Figure 17: Response with Digest of encoded response 1100 B.5. Client Provides Full Representation Data, Server Provides No 1101 Representation Data 1103 The request Repr-Digest field-value is calculated on the enclosed 1104 payload. 1106 The response Repr-Digest field-value depends on the representation 1107 metadata header fields, including Content-Encoding: br even when the 1108 response does not contain content. 1110 PUT /items/123 HTTP/1.1 1111 Host: foo.example 1112 Content-Type: application/json 1113 Content-Length: 18 1114 Accept-Encoding: br 1115 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1117 {"hello": "world"} 1119 HTTP/1.1 204 No Content 1120 Content-Type: application/json 1121 Content-Encoding: br 1122 Repr-Digest: sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=: 1124 Figure 18: Empty response with Digest 1126 B.6. Client and Server Provide Full Representation Data 1128 The response contains two digest values using different algorithms. 1130 As the response body contains non-printable characters, it is 1131 displayed as a base64-encoded string. 1133 PUT /items/123 HTTP/1.1 1134 Host: foo.example 1135 Content-Type: application/json 1136 Accept-Encoding: br 1137 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1139 {"hello": "world"} 1141 Figure 19: PUT Request with Digest 1143 NOTE: '\' line wrapping per RFC 8792 1145 HTTP/1.1 200 OK 1146 Content-Type: application/json 1147 Content-Encoding: br 1148 Content-Location: /items/123 1149 Repr-Digest: \ 1150 sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=:,\ 1151 sha-512=:pxo7aYzcGI88pnDnoSmAnaOEVys0MABhgvHY9+VI+ElE60jBCwnMPyA/\ 1152 s3NF3ZO5oIWA7lf8ukk+5KJzm3p5og==: 1154 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 1156 Figure 20: Response with Digest of Encoded Content 1158 B.7. POST Response does not Reference the Request URI 1160 The request Repr-Digest field-value is computed on the enclosed 1161 representation (see Section 3.1). 1163 The representation enclosed in the response refers to the resource 1164 identified by Content-Location (see Section 6.4.2 of [SEMANTICS]). 1165 Repr-Digest is thus computed on the enclosed representation. 1167 POST /books HTTP/1.1 1168 Host: foo.example 1169 Content-Type: application/json 1170 Accept: application/json 1171 Accept-Encoding: identity 1172 Repr-Digest: sha-256=:bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=: 1174 {"title": "New Title"} 1176 Figure 21: POST Request with Digest 1178 HTTP/1.1 201 Created 1179 Content-Type: application/json 1180 Content-Location: /books/123 1181 Location: /books/123 1182 Repr-Digest: sha-256=:yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE=: 1184 { 1185 "id": "123", 1186 "title": "New Title" 1187 } 1189 Figure 22: Response with Digest of Resource 1191 Note that a 204 No Content response without content but with the same 1192 Repr-Digest field-value would have been legitimate too. In that 1193 case, Content-Digest would have been computed on an empty content. 1195 B.8. POST Response Describes the Request Status 1197 The request Repr-Digest field-value is computed on the enclosed 1198 representation (see Section 3.1). 1200 The representation enclosed in the response describes the status of 1201 the request, so Repr-Digest is computed on that enclosed 1202 representation. 1204 Response Repr-Digest has no explicit relation with the resource 1205 referenced by Location. 1207 POST /books HTTP/1.1 1208 Host: foo.example 1209 Content-Type: application/json 1210 Accept: application/json 1211 Accept-Encoding: identity 1212 Repr-Digest: sha-256=:bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=: 1214 {"title": "New Title"} 1216 Figure 23: POST Request with Digest 1218 HTTP/1.1 201 Created 1219 Content-Type: application/json 1220 Repr-Digest: sha-256=:2LBp5RKZGpsSNf8BPXlXrX4Td4Tf5R5bZ9z7kdi5VvY=: 1221 Location: /books/123 1223 { 1224 "status": "created", 1225 "id": "123", 1226 "ts": 1569327729, 1227 "instance": "/books/123" 1228 } 1230 Figure 24: Response with Digest of Representation 1232 B.9. Digest with PATCH 1234 This case is analogous to a POST request where the target resource 1235 reflects the effective request URI. 1237 The PATCH request uses the application/merge-patch+json media type 1238 defined in [RFC7396]. 1240 Repr-Digest is calculated on the enclosed payload, which corresponds 1241 to the patch document. 1243 The response Repr-Digest field-value is computed on the complete 1244 representation of the patched resource. 1246 PATCH /books/123 HTTP/1.1 1247 Host: foo.example 1248 Content-Type: application/merge-patch+json 1249 Accept: application/json 1250 Accept-Encoding: identity 1251 Repr-Digest: sha-256=:bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=: 1253 {"title": "New Title"} 1254 Figure 25: PATCH Request with Digest 1256 HTTP/1.1 200 OK 1257 Content-Type: application/json 1258 Repr-Digest: sha-256=:yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE=: 1260 { 1261 "id": "123", 1262 "title": "New Title" 1263 } 1265 Figure 26: Response with Digest of Representation 1267 Note that a 204 No Content response without content but with the same 1268 Repr-Digest field-value would have been legitimate too. 1270 B.10. Error responses 1272 In error responses, the representation data does not necessarily 1273 refer to the target resource. Instead, it refers to the 1274 representation of the error. 1276 In the following example, a client sends the same request from 1277 Figure 25 to patch the resource located at /books/123. However, the 1278 resource does not exist and the server generates a 404 response with 1279 a body that describes the error in accordance with [RFC7807]. 1281 The response Repr-Digest field-value is computed on this enclosed 1282 representation. 1284 HTTP/1.1 404 Not Found 1285 Content-Type: application/problem+json 1286 Repr-Digest: sha-256=:KPqhVXAT25LLitV1w0O167unHmVQusu+fpxm65zAsvk=: 1288 { 1289 "title": "Not Found", 1290 "detail": "Cannot PATCH a non-existent resource", 1291 "status": 404 1292 } 1294 Figure 27: Response with Digest of Error Representation 1296 B.11. Use with Trailer Fields and Transfer Coding 1298 An origin server sends Repr-Digest as trailer field, so it can 1299 calculate digest-value while streaming content and thus mitigate 1300 resource consumption. The Repr-Digest field-value is the same as in 1301 Appendix B.1 because Repr-Digest is designed to be independent from 1302 the use of one or more transfer codings (see Section 3). 1304 GET /items/123 HTTP/1.1 1305 Host: foo.example 1307 Figure 28: GET Request 1309 HTTP/1.1 200 OK 1310 Content-Type: application/json 1311 Transfer-Encoding: chunked 1312 Trailer: Digest 1314 8\r\n 1315 {"hello"\r\n 1316 8 1317 : "world\r\n 1318 2\r\n 1319 "}\r\n 1320 0\r\n 1321 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1323 Figure 29: Chunked Response with Digest 1325 Appendix C. Examples of Want-Repr-Digest Solicited Digest 1327 The following examples demonstrate interactions where a client 1328 solicits a Repr-Digest using Want-Repr-Digest. The behavior of 1329 Content-Digest and Want-Content-Digest is identical. 1331 Some examples include JSON objects in the content. For presentation 1332 purposes, objects that fit completely within the line-length limits 1333 are presented on a single line using compact notation with no leading 1334 space. Objects that would exceed line-length limits are presented 1335 across multiple lines (one line per key-value pair) with 2 spaced of 1336 leading indentation. 1338 Checksum mechanisms described in this document are media-type 1339 agnostic and do not provide canonicalization algorithms for specific 1340 formats. Examples are calculated inclusive of any space. 1342 C.1. Server Selects Client's Least Preferred Algorithm 1344 The client requests a digest, preferring "sha". The server is free 1345 to reply with "sha-256" anyway. 1347 GET /items/123 HTTP/1.1 1348 Host: foo.example 1349 Want-Repr-Digest: sha-256=3, sha=10 1351 Figure 30: GET Request with Want-Repr-Digest 1353 HTTP/1.1 200 OK 1354 Content-Type: application/json 1355 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1357 {"hello": "world"} 1359 Figure 31: Response with Different Algorithm 1361 C.2. Server Selects Algorithm Unsupported by Client 1363 The client requests a "sha" digest because that is the only algorithm 1364 it supports. The server is not obliged to produce a response 1365 containing a "sha" digest, it instead uses a different algorithm. 1367 GET /items/123 HTTP/1.1 1368 Host: foo.example 1369 Want-Repr-Digest: sha=10 1371 Figure 32: GET Request with Want-Repr-Digest 1373 NOTE: '\' line wrapping per RFC 8792 1375 HTTP/1.1 200 OK 1376 Content-Type: application/json 1377 Repr-Digest: \ 1378 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 1379 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 1381 {"hello": "world"} 1383 Figure 33: Response with Unsupported Algorithm 1385 C.3. Server Does Not Support Client Algorithm and Returns an Error 1387 Appendix C.2 is an example where a server ignores the client's 1388 preferred digest algorithm. Alternatively a server can also reject 1389 the request and return an error. 1391 In this example, the client requests a "sha" Repr-Digest, and the 1392 server returns an error with problem details [RFC7807] contained in 1393 the content. The problem details contain a list of the hashing 1394 algorithms that the server supports. This is purely an example, this 1395 specification does not define any format or requirements for such 1396 content. 1398 GET /items/123 HTTP/1.1 1399 Host: foo.example 1400 Want-Repr-Digest: sha=10 1402 Figure 34: GET Request with Want-Repr-Digest 1404 HTTP/1.1 400 Bad Request 1405 Content-Type: application/problem+json 1407 { 1408 "title": "Bad Request", 1409 "detail": "Supported hashing algorithms: sha-256, sha-512", 1410 "status": 400 1411 } 1413 Figure 35: Response advertising the supported algorithms 1415 Appendix D. Migrating from RFC 3230 1417 HTTP digests are computed by applying a hashing algorithm to input 1418 data. RFC 3230 defined the input data as an "instance", a term it 1419 also defined. The concept of instance has since been superseded by 1420 the HTTP semantic term "representation". It is understood that some 1421 implementations of RFC 3230 mistook "instance" to mean HTTP content. 1422 Using content for the Digest field is an error that leads to 1423 interoperability problems between peers that implement RFC 3230. 1425 For the uncertainty of doubt, RFC 3230 was only ever intended to use 1426 what HTTP now defines as selected representation data. The semantic 1427 concept of digest and representation are explained alongside the 1428 definition of Representation-Digest Section 3. 1430 While the syntax of Digest and Repr-Digest are different, the 1431 considerations and examples this document gives to Repr-Digest apply 1432 equally to Digest because they operate on the same input data. See 1433 Section 3.1, Section 6 and Section 6.3. 1435 RFC 3230 could never communicate the digest of HTTP message content 1436 in the Digest field; Content-Digest now provides that capability. 1438 Acknowledgements 1440 This document is based on ideas from [RFC3230], so thanks to J. 1441 Mogul and A. Van Hoff for their great work. The original idea of 1442 refreshing RFC3230 arose from an interesting discussion with M. 1443 Nottingham, J. Yasskin and M. Thomson when reviewing the MICE 1444 content coding. 1446 Thanks to Julian Reschke for his valuable contributions to this 1447 document, and to the following contributors that have helped improve 1448 this specification by reporting bugs, asking smart questions, 1449 drafting or reviewing text, and evaluating open issues: Mike Bishop, 1450 Brian Campbell, Matthew Kerwin, James Manger, Tommy Pauly, Sean 1451 Turner, Justin Richer, and Erik Wilde. 1453 Code Samples 1455 _RFC Editor: Please remove this section before publication._ 1457 How can I generate and validate the Repr-Digest values shown in the 1458 examples throughout this document? 1460 The following python3 code can be used to generate digests for JSON 1461 objects using SHA algorithms for a range of encodings. Note that 1462 these are formatted as base64. This function could be adapted to 1463 other algorithms and should take into account their specific 1464 formatting rules. 1466 import base64, json, hashlib, brotli, logging 1467 log = logging.getLogger() 1469 def encode_item(item, encoding=lambda x: x): 1470 indent = 2 if isinstance(item, dict) and len(item) > 1 else None 1471 json_bytes = json.dumps(item, indent=indent).encode() 1472 return encoding(json_bytes) 1474 def digest_bytes(bytes_, algorithm=hashlib.sha256): 1475 checksum_bytes = algorithm(bytes_).digest() 1476 log.warning("Log bytes: \n[%r]", bytes_) 1477 return base64.encodebytes(checksum_bytes).strip() 1479 def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): 1480 content_encoded = encode_item(item, encoding) 1481 return digest_bytes(content_encoded, algorithm) 1483 item = {"hello": "world"} 1485 print("Encoding | hashing algorithm | digest-value") 1486 print("Identity | sha256 |", digest(item)) 1487 # Encoding | hashing algorithm | digest-value 1488 # Identity | sha256 | X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1490 print("Encoding | hashing algorithm | digest-value") 1491 print("Brotli | sha256 |", digest(item, encoding=brotli.compress)) 1492 # Encoding | hashing algorithm | digest-value 1493 # Brotli | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1495 print("Encoding | hashing algorithm | digest-value") 1496 print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512)) 1497 print("Brotli | sha512 |", digest(item, algorithm=hashlib.sha512, 1498 encoding=brotli.compress)) 1499 # Encoding | hashing algorithm | digest-value 1500 # Identity | sha512 |b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm' 1501 # '+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==' 1502 # Brotli | sha512 | b'pxo7aYzcGI88pnDnoSmAnaOEVys0MABhgvHY9+VI+ElE6' 1503 # '0jBCwnMPyA/s3NF3ZO5oIWA7lf8ukk+5KJzm3p5og==' 1505 Changes 1507 _RFC Editor: Please remove this section before publication._ 1509 Since draft-ietf-httpbis-digest-headers-08 1511 * Add note about migrating from RFC 3230. #1968, #1971 1512 * Clarify what Want-* means in responses. #2097 1514 * Editorial changes to structure and to align to HTTP style guide. 1516 Since draft-ietf-httpbis-digest-headers-07 1518 * Introduced Repr-Digest and Want-Repr-Digest, and deprecated Digest 1519 and Want-Digest. Use of Structured Fields. #1993, #1919 1521 * IANA refactoring. #1983 1523 * No normative text in security considerations. #1972 1525 Since draft-ietf-httpbis-digest-headers-06 1527 * Remove id-sha-256 and id-sha-512 from the list of supported 1528 algorithms #855 1530 Since draft-ietf-httpbis-digest-headers-05 1532 * Reboot digest-algorithm values registry #1567 1534 * Add Content-Digest #1542 1536 * Remove SRI section #1478 1538 Since draft-ietf-httpbis-digest-headers-04 1540 * Improve SRI section #1354 1542 * About duplicate digest-algorithms #1221 1544 * Improve security considerations #852 1546 * md5 and sha deprecation references #1392 1548 * Obsolete 3230 #1395 1550 * Editorial #1362 1552 Since draft-ietf-httpbis-digest-headers-03 1554 * Reference semantics-12 1556 * Detail encryption quirks 1558 * Details on Algorithm agility #1250 1559 * Obsolete parameters #850 1561 Since draft-ietf-httpbis-digest-headers-02 1563 * Deprecate SHA-1 #1154 1565 * Avoid id-* with encrypted content 1567 * Digest is independent from MESSAGING and HTTP/1.1 is not normative 1568 #1215 1570 * Identity is not a valid field value for content-encoding #1223 1572 * Mention trailers #1157 1574 * Reference httpbis-semantics #1156 1576 * Add contentMD5 as an obsoleted digest-algorithm #1249 1578 * Use lowercase digest-algorithms names in the doc and in the 1579 digest-algorithm IANA table. 1581 Since draft-ietf-httpbis-digest-headers-01 1583 * Digest of error responses is computed on the error representation- 1584 data #1004 1586 * Effect of HTTP semantics on payload and message body moved to 1587 appendix #1122 1589 * Editorial refactoring, moving headers sections up. #1109-#1112, 1590 #1116, #1117, #1122-#1124 1592 Since draft-ietf-httpbis-digest-headers-00 1594 * Align title with document name 1596 * Add id-sha-* algorithm examples #880 1598 * Reference [RFC6234] and [RFC3174] instead of FIPS-1 1600 * Deprecate MD5 1602 * Obsolete ADLER-32 but don't forbid it #828 1604 * Update CRC32C value in IANA table #828 1606 * Use when acting on resources (POST, PATCH) #853 1607 * Added Relationship with SRI, draft Use Cases #868, #971 1609 * Warn about the implications of Content-Location 1611 Authors' Addresses 1613 Roberto Polli 1614 Team Digitale, Italian Government 1615 Italy 1616 Email: robipolli@gmail.com 1618 Lucas Pardue 1619 Cloudflare 1620 Email: lucaspardue.24.7@gmail.com