idnits 2.17.1 draft-ietf-httpbis-digest-headers-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (19 June 2022) is 676 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) ** Downref: Normative reference to an Informational RFC: RFC 1321 ** Downref: Normative reference to an Informational RFC: RFC 1950 ** Downref: Normative reference to an Informational RFC: RFC 3174 ** Downref: Normative reference to an Informational RFC: RFC 6234 -- Obsolete informational reference (is this intentional?): RFC 3230 (Obsoleted by RFC 9530) -- 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-10 Summary: 4 errors (**), 0 flaws (~~), 3 warnings (==), 4 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: 21 December 2022 19 June 2022 8 Digest Fields 9 draft-ietf-httpbis-digest-headers-10 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 21 December 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 . . . . . . . . . . . . . . . . . 17 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 . . . 23 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 . . . . 25 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 . . . . . . . 28 111 Appendix C. Examples of Want-Repr-Digest Solicited Digest . . . 29 112 C.1. Server Selects Client's Least Preferred Algorithm . . . . 29 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 . . . . . . . . . . . . . . . . . . . . . . . . 31 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 [TLS] can provide some integrity protection. 137 However, transport-oriented integrity provides a limited utility 138 because it is opaque to the application layer and only covers the 139 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 [HTTP]). Second, representation data integrity, which acts on 150 representation data (Section 3.2 of [HTTP]). This supports advanced 151 use cases such as validating the integrity of a resource that was 152 reconstructed from parts retrieved using multiple requests or 153 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 [HTTP]); 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 [HTTP]). Basing Repr-Digest on 201 the selected representation makes it straightforward to apply it to 202 use-cases where the message content requires some sort of 203 manipulation to be considered as representation of the resource or 204 content conveys a partial representation of a resource, such as Range 205 Requests (see Section 14.2 of [HTTP]). 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 to express algorithm preferences 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 [HTTP]). 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 [HTTP]. 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 [HTTP]). 293 It is a Dictionary (see Section 3.2 of [STRUCTURED-FIELDS]) where 294 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 [HTTP]. 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 [HTTP]). 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 [HTTP/1.1]). 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 [HTTP]. 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 [HTTP]). In contrast, the Location header field does 419 not affect Repr-Digest because it is not representation metadata. 421 For example, in PATCH requests, the representation digest will be 422 computed on the patch document because the representation metadata 423 refers to the patch document and not to the target resource (see 424 Section 2 of [PATCH]). In responses, instead, the representation 425 digest will be computed on the selected representation of the patched 426 resource. 428 3.2. Repr-Digest and Content-Location in Responses 430 When a state-changing method returns the Content-Location header 431 field, the enclosed representation refers to the resource identified 432 by its value and Repr-Digest is computed accordingly. An example is 433 given in Appendix B.7. 435 4. Integrity preference fields 437 Senders can indicate their interest in Integrity fields and hashing 438 algorithm preferences using the Want-Content-Digest or Want-Repr- 439 Digest fields. These can be used in both requests and responses. 441 Want-Content-Digest indicates that the sender would like to receive a 442 content digest on messages associated with the request URI and 443 representation metadata, using the Content-Digest field. 445 Want-Repr-Digest indicates that the sender would like to receive a 446 representation digest on messages associated with the request URI and 447 representation metadata, using the Repr-Digest field. 449 If Want-Content-Digest or Want-Repr-Digest are used in a response, it 450 indicates that the server would like the client to provide the 451 respective Integrity field on future requests. 453 Want-Content-Digest and Want-Repr-Digest are of type Dictionary where 454 each: 456 * key conveys the hashing algorithm (see Section 5); 458 * value is an Integer (Section 3.3.1 of [STRUCTURED-FIELDS]) that 459 conveys an ascending, relative, weighted preference. It must be 460 in the range 0 to 10 inclusive. 1 is the least preferred, 10 is 461 the most preferred, and a value of 0 means "not acceptable". 463 Examples: 465 Want-Repr-Digest: sha-256=1 466 Want-Repr-Digest: sha-512=3, sha-256=10, unixsum=0 467 Want-Content-Digest: sha-256=1 468 Want-Content-Digest: sha-512=3, sha-256=10, unixsum=0 470 5. Hash Algorithms for HTTP Digest Fields Registry 472 The "Hash Algorithms for HTTP Digest Fields", maintained by IANA at 473 https://www.iana.org/assignments/http-dig-alg/ 474 (https://www.iana.org/assignments/http-dig-alg/), registers 475 algorithms for use with the Integrity and Integrity preference fields 476 defined in this document. 478 This registry uses the Specification Required policy (Section 4.6 of 479 [RFC8126]). 481 Registrations MUST include the following fields: 483 * Algorithm Key: the Structured Fields key value used in Content- 484 Digest, Repr-Digest, Want-Content-Digest, or Want-Repr-Digest 485 field Dictionary member keys 487 * Status: the status of the algorithm. Use "standard" for 488 standardized algorithms without known problems; "experimental" or 489 some other appropriate value 491 - e.g. according to the type and status of the primary document 492 in which the algorithm is defined; "insecure" when the 493 algorithm is insecure; "reserved" when the algorithm references 494 a reserved token value 496 * Description: a short description of the algorithm 498 * Reference(s): a set of pointers to the primary documents defining 499 the algorithm and key 501 Insecure hashing algorithms MAY be used to preserve integrity against 502 corruption, but MUST NOT be used in a potentially adversarial 503 setting; for example, when signing Integrity fields' values for 504 authenticity. 506 The entries in Table 1 are registered by this document. 508 +===========+==========+============================+==============+ 509 | Algorithm | Status | Description | Reference(s) | 510 | Key | | | | 511 +===========+==========+============================+==============+ 512 | sha-512 | standard | The SHA-512 algorithm. | [RFC6234], | 513 | | | | [RFC4648], | 514 | | | | this | 515 | | | | document. | 516 +-----------+----------+----------------------------+--------------+ 517 | sha-256 | standard | The SHA-256 algorithm. | [RFC6234], | 518 | | | | [RFC4648], | 519 | | | | this | 520 | | | | document. | 521 +-----------+----------+----------------------------+--------------+ 522 | md5 | insecure | The MD5 algorithm. It is | [RFC1321], | 523 | | | vulnerable to collision | [RFC4648], | 524 | | | attacks; see [NO-MD5] and | this | 525 | | | [CMU-836068] | document. | 526 +-----------+----------+----------------------------+--------------+ 527 | sha | insecure | The SHA-1 algorithm. It | [RFC3174], | 528 | | | is vulnerable to collision | [RFC4648], | 529 | | | attacks; see [NO-SHA] and | [RFC6234] | 530 | | | [IACR-2020-014] | this | 531 | | | | document. | 532 +-----------+----------+----------------------------+--------------+ 533 | unixsum | insecure | The algorithm used by the | [RFC4648], | 534 | | | UNIX "sum" command. | [RFC6234], | 535 | | | | [UNIX], this | 536 | | | | document. | 537 +-----------+----------+----------------------------+--------------+ 538 | unixcksum | insecure | The algorithm used by the | [RFC4648], | 539 | | | UNIX "cksum" command. | [RFC6234], | 540 | | | | [UNIX], this | 541 | | | | document. | 542 +-----------+----------+----------------------------+--------------+ 543 | adler | insecure | The ADLER32 algorithm. | [RFC1950], | 544 | | | | this | 545 | | | | document. | 546 +-----------+----------+----------------------------+--------------+ 547 | crc32c | insecure | The CRC32c algorithm. | [RFC9260] | 548 | | | | appendix B, | 549 | | | | this | 550 | | | | document. | 551 +-----------+----------+----------------------------+--------------+ 553 Table 1: Initial Hash Algorithms 555 6. Security Considerations 557 6.1. HTTP Messages Are Not Protected In Full 559 This document specifies a data integrity mechanism that protects HTTP 560 representation data or content, but not HTTP header and trailer 561 fields, from certain kinds of corruption. 563 Integrity fields are not intended to be a general protection against 564 malicious tampering with HTTP messages. This can be achieved by 565 combining it with other approaches such as transport-layer security 566 or digital signatures (for example, HTTP Message Signatures 567 [SIGNATURES]). 569 6.2. End-to-End Integrity 571 Integrity fields can help detect representation data or content 572 modification due to implementation errors, undesired "transforming 573 proxies" (see Section 7.7 of [HTTP]) or other actions as the data 574 passes across multiple hops or system boundaries. Even a simple 575 mechanism for end-to-end representation data integrity is valuable 576 because a user agent can validate that resource retrieval succeeded 577 before handing off to a HTML parser, video player etc. for parsing. 579 Note that using these mechanisms alone does not provide end-to-end 580 integrity of HTTP messages over multiple hops, since metadata could 581 be manipulated at any stage. Methods to protect metadata are 582 discussed in Section 6.3. 584 6.3. Usage in Signatures 586 Digital signatures are widely used together with checksums to provide 587 the certain identification of the origin of a message [NIST800-32]. 588 Such signatures can protect one or more HTTP fields and there are 589 additional considerations when Integrity fields are included in this 590 set. 592 There are no restrictions placed on the type or format of digitial 593 signature that Integrity fields can be used with. One possible 594 approach is to combine them with HTTP Message Signatures 595 [SIGNATURES]. 597 Digests explicitly depend on the "representation metadata" (e.g. the 598 values of Content-Type, Content-Encoding etc). A signature that 599 protects Integrity fields but not other "representation metadata" can 600 expose the communication to tampering. For example, an actor could 601 manipulate the Content-Type field-value and cause a digest validation 602 failure at the recipient, preventing the application from accessing 603 the representation. Such an attack consumes the resources of both 604 endpoints. See also Section 3.2. 606 Signatures are likely to be deemed an adversarial setting when 607 applying Integrity fields; see Section 5. Using signatures to 608 protect the checksum of an empty representation allows receiving 609 endpoints to detect if an eventual payload has been stripped or 610 added. 612 Any mangling of Integrity fields, including digests' de-duplication 613 or combining different field values (see Section 5.2 of [HTTP]) might 614 affect signature validation. 616 6.4. Usage in Trailer Fields 618 Before sending Integrity fields in a trailer section, the sender 619 should consider that intermediaries are explicitly allowed to drop 620 any trailer (see Section 6.5.2 of [HTTP]). 622 When Integrity fields are used in a trailer section, the field-values 623 are received after the content. Eager processing of content before 624 the trailer section prevents digest validation, possibly leading to 625 processing of invalid data. 627 Not every hashing algorithm is suitable for use in the trailer 628 section, some may require to pre-process the whole payload before 629 sending a message (e.g. see [I-D.thomson-http-mice]). 631 6.5. Usage with Encryption 633 The checksum of an encrypted payload can change between different 634 messages depending on the encryption algorithm used; in those cases 635 its value could not be used to provide a proof of integrity "at rest" 636 unless the whole (e.g. encoded) content is persisted. 638 6.6. Algorithm Agility 640 The security properties of hashing algorithms are not fixed. 641 Algorithm Agility (see [RFC7696]) is achieved by providing 642 implementations with flexibility to choose hashing algorithms from 643 the IANA Hash Algorithms for HTTP Digest Fields registry; see 644 Section 7.2. 646 The "standard" algorithms listed in this document are suitable for 647 many purposes, including adversarial situations where hash functions 648 might need to provide resistance to collision, first-preimage and 649 second-preimage attacks. Algorithms listed as "insecure" either 650 provide none of these properties, or are known to be weak (see 651 [NO-MD5] and [NO-SHA]). 653 For adversarial situations, which of the "standard" algorithms are 654 acceptable will depend on the level of protection the circumstances 655 demand. As there is no negotiation, endpoints that depend on a 656 digest for security will be vulnerable to attacks on the weakest 657 algorithm they are willing to accept. 659 Transition from weak algorithms is supported by negotiation of 660 hashing algorithm using Want-Content-Digest or Want-Repr-Digest (see 661 Section 4) or by sending multiple digests from which the receiver 662 chooses. Endpoints are advised that sending multiple values consumes 663 resources, which may be wasted if the receiver ignores them (see 664 Section 3). 666 While algorithm agility allows the migration to stronger algorithms 667 it does not prevent the use of weaker algorithms. Integrity fields 668 do not provide any mitigiations for downgrade or substitution attacks 669 (see Section 1 of [RFC6211]) of the hashing algorithm. To protect 670 against such attacks, endpoints could restrict their set of supported 671 algorithms to stronger ones and protect the fields value by using TLS 672 and/or digital signatures. 674 6.7. Resource exhaustion 676 Integrity fields validation consumes computational resources. In 677 order to avoid resource exhaustion, implementations can restrict 678 validation of the algorithm types, number of validations, or the size 679 of content. 681 7. IANA Considerations 683 7.1. HTTP Field Name Registration 685 IANA is asked to update the "Hypertext Transfer Protocol (HTTP) Field 686 Name Registry" registry ([HTTP]) according to the table below: 688 +=====================+===========+============================+ 689 | Field Name | Status | Reference | 690 +=====================+===========+============================+ 691 | Content-Digest | permanent | Section 2 of this document | 692 +---------------------+-----------+----------------------------+ 693 | Repr-Digest | permanent | Section 3 of this document | 694 +---------------------+-----------+----------------------------+ 695 | Want-Content-Digest | permanent | Section 4 of this document | 696 +---------------------+-----------+----------------------------+ 697 | Want-Repr-Digest | permanent | Section 4 of this document | 698 +---------------------+-----------+----------------------------+ 699 | Digest | obsoleted | [RFC3230], Section 1.3 of | 700 | | | this document | 701 +---------------------+-----------+----------------------------+ 702 | Want-Digest | obsoleted | [RFC3230], Section 1.3 of | 703 | | | this document | 704 +---------------------+-----------+----------------------------+ 706 Table 2 708 7.2. Establish the Hash Algorithms for HTTP Digest Fields Registry 710 This memo sets this specification to be the establishing document for 711 the Hash Algorithms for HTTP Digest Fields 712 (https://www.iana.org/assignments/http-structured-dig-alg/) registry 713 defined in Section 5. 715 IANA is asked to initialize the registry with the entries in Table 1. 717 8. References 719 8.1. Normative References 721 [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 722 Ed., "HTTP Semantics", STD 97, RFC 9110, 723 DOI 10.17487/RFC9110, June 2022, 724 . 726 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 727 DOI 10.17487/RFC1321, April 1992, 728 . 730 [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format 731 Specification version 3.3", RFC 1950, 732 DOI 10.17487/RFC1950, May 1996, 733 . 735 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 736 Requirement Levels", BCP 14, RFC 2119, 737 DOI 10.17487/RFC2119, March 1997, 738 . 740 [RFC3174] Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 741 (SHA1)", RFC 3174, DOI 10.17487/RFC3174, September 2001, 742 . 744 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 745 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 746 . 748 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 749 Specifications: ABNF", STD 68, RFC 5234, 750 DOI 10.17487/RFC5234, January 2008, 751 . 753 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 754 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 755 DOI 10.17487/RFC6234, May 2011, 756 . 758 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 759 RFC 7405, DOI 10.17487/RFC7405, December 2014, 760 . 762 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 763 Writing an IANA Considerations Section in RFCs", BCP 26, 764 RFC 8126, DOI 10.17487/RFC8126, June 2017, 765 . 767 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 768 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 769 May 2017, . 771 [STRUCTURED-FIELDS] 772 Nottingham, M. and P-H. Kamp, "Structured Field Values for 773 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 774 . 776 8.2. Informative References 778 [CMU-836068] 779 Carnegie Mellon University, Software Engineering 780 Institute, "MD5 Vulnerable to collision attacks", 31 781 December 2008, . 783 [HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 784 Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, 785 June 2022, . 787 [I-D.thomson-http-mice] 788 Thomson, M. and J. Yasskin, "Merkle Integrity Content 789 Encoding", Work in Progress, Internet-Draft, draft- 790 thomson-http-mice-03, 13 August 2018, 791 . 794 [IACR-2020-014] 795 Leurent, G. and T. Peyrin, "SHA-1 is a Shambles", 5 796 January 2020, . 798 [NIST800-32] 799 National Institute of Standards and Technology, U.S. 800 Department of Commerce, "Introduction to Public Key 801 Technology and the Federal PKI Infrastructure", February 802 2001, . 805 [NO-MD5] Turner, S. and L. Chen, "Updated Security Considerations 806 for the MD5 Message-Digest and the HMAC-MD5 Algorithms", 807 RFC 6151, DOI 10.17487/RFC6151, March 2011, 808 . 810 [NO-SHA] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security 811 Considerations for the SHA-0 and SHA-1 Message-Digest 812 Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011, 813 . 815 [PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 816 RFC 5789, DOI 10.17487/RFC5789, March 2010, 817 . 819 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 820 RFC 3230, DOI 10.17487/RFC3230, January 2002, 821 . 823 [RFC6211] Schaad, J., "Cryptographic Message Syntax (CMS) Algorithm 824 Identifier Protection Attribute", RFC 6211, 825 DOI 10.17487/RFC6211, April 2011, 826 . 828 [RFC7396] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7396, 829 DOI 10.17487/RFC7396, October 2014, 830 . 832 [RFC7696] Housley, R., "Guidelines for Cryptographic Algorithm 833 Agility and Selecting Mandatory-to-Implement Algorithms", 834 BCP 201, RFC 7696, DOI 10.17487/RFC7696, November 2015, 835 . 837 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 838 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 839 . 841 [RFC9260] Stewart, R., Tüxen, M., and K. Nielsen, "Stream Control 842 Transmission Protocol", RFC 9260, DOI 10.17487/RFC9260, 843 June 2022, . 845 [SIGNATURES] 846 Backman, A., Richer, J., and M. Sporny, "HTTP Message 847 Signatures", Work in Progress, Internet-Draft, draft-ietf- 848 httpbis-message-signatures-10, 26 May 2022, 849 . 852 [TLS] Rescorla, E., "The Transport Layer Security (TLS) Protocol 853 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 854 . 856 [UNIX] The Open Group, "The Single UNIX Specification, Version 2 857 - 6 Vol Set for UNIX 98", February 1997. 859 Appendix A. Resource Representation and Representation Data 861 The following examples show how representation metadata, payload 862 transformations and method impacts on the message and content. When 863 the content contains non-printable characters (e.g. when it is 864 compressed) it is shown as a Base64-encoded string. 866 PUT /entries/1234 HTTP/1.1 867 Host: foo.example 868 Content-Type: application/json 870 {"hello": "world"} 872 Figure 1: Request containing a JSON object without any content coding 874 PUT /entries/1234 HTTP/1.1 875 Host: foo.example 876 Content-Type: application/json 877 Content-Encoding: gzip 879 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 880 Figure 2: Request containing a gzip-encoded JSON object 882 Now the same content conveys a malformed JSON object, because the 883 request does not indicate a content coding. 885 PUT /entries/1234 HTTP/1.1 886 Host: foo.example 887 Content-Type: application/json 889 H4sIAItWyFwC/6tWSlSyUlAypANQqgUAREcqfG0AAAA= 891 Figure 3: Request containing malformed JSON 893 A Range-Request alters the content, conveying a partial 894 representation. 896 GET /entries/1234 HTTP/1.1 897 Host: foo.example 898 Range: bytes=1-7 900 Figure 4: Request for partial content 902 HTTP/1.1 206 Partial Content 903 Content-Encoding: gzip 904 Content-Type: application/json 905 Content-Range: bytes 1-7/18 907 iwgAla3RXA== 909 Figure 5: Partial response from a gzip-encoded representation 911 The method can also alter the content. For example, the response to 912 a HEAD request does not carry content. 914 HEAD /entries/1234 HTTP/1.1 915 Host: foo.example 916 Accept: application/json 917 Accept-Encoding: gzip 919 Figure 6: HEAD request 921 HTTP/1.1 200 OK 922 Content-Type: application/json 923 Content-Encoding: gzip 925 Figure 7: Response to HEAD request (empty content) 927 Finally, the semantics of an HTTP response might decouple the 928 effective request URI from the enclosed representation. In the 929 example response below, the Content-Location header field indicates 930 that the enclosed representation refers to the resource available at 931 /authors/123, even though the request is directed to /authors/. 933 POST /authors/ HTTP/1.1 934 Host: foo.example 935 Accept: application/json 936 Content-Type: application/json 938 {"author": "Camilleri"} 940 Figure 8: POST request 942 HTTP/1.1 201 Created 943 Content-Type: application/json 944 Content-Location: /authors/123 945 Location: /authors/123 947 {"id": "123", "author": "Camilleri"} 949 Figure 9: Response with Content-Location header 951 Appendix B. Examples of Unsolicited Digest 953 The following examples demonstrate interactions where a server 954 responds with a Content-Digest or Repr-Digest fields even though the 955 client did not solicit one using Want-Content-Digest or Want-Repr- 956 Digest. 958 Some examples include JSON objects in the content. For presentation 959 purposes, objects that fit completely within the line-length limits 960 are presented on a single line using compact notation with no leading 961 space. Objects that would exceed line-length limits are presented 962 across multiple lines (one line per key-value pair) with 2 spaced of 963 leading indentation. 965 Checksum mechanisms defined in this document are media-type agnostic 966 and do not provide canonicalization algorithms for specific formats. 967 Examples are calculated inclusive of any space. While examples can 968 include both fields, Content-Digest and Repr-Digest can be returned 969 independently. 971 B.1. Server Returns Full Representation Data 973 In this example, the message content conveys complete representation 974 data. This means that in the response, Content-Digest and Repr- 975 Digest are both computed over the JSON object {"hello": "world"}, and 976 thus have the same value. 978 GET /items/123 HTTP/1.1 979 Host: foo.example 981 Figure 10: GET request for an item 983 NOTE: '\' line wrapping per RFC 8792 985 HTTP/1.1 200 OK 986 Content-Type: application/json 987 Content-Digest: \ 988 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 989 Repr-Digest: \ 990 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 992 {"hello": "world"} 994 Figure 11: Response with identical Repr-Digest and Content-Digest 996 B.2. Server Returns No Representation Data 998 In this example, a HEAD request is used to retrieve the checksum of a 999 resource. 1001 The response Content-Digest field-value is computed on empty content. 1002 Repr-Digest is calculated over the JSON object {"hello": "world"}, 1003 which is not shown because there is no payload data. 1005 HEAD /items/123 HTTP/1.1 1006 Host: foo.example 1008 Figure 12: HEAD request for an item 1010 NOTE: '\' line wrapping per RFC 8792 1012 HTTP/1.1 200 OK 1013 Content-Type: application/json 1014 Content-Digest: \ 1015 sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=: 1016 Repr-Digest: \ 1017 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1019 Figure 13: Response with both Content-Digest and Digest; empty 1020 content 1022 B.3. Server Returns Partial Representation Data 1024 In this example, the client makes a range request and the server 1025 responds with partial content. 1027 GET /items/123 HTTP/1.1 1028 Host: foo.example 1029 Range: bytes=1-7 1031 Figure 14: Request for partial content 1033 NOTE: '\' line wrapping per RFC 8792 1035 HTTP/1.1 206 Partial Content 1036 Content-Type: application/json 1037 Content-Range: bytes 1-7/18 1038 Content-Digest: \ 1039 sha-256=:Wqdirjg/u3J688ejbUlApbjECpiUUtIwT8lY/z81Tno=: 1040 Repr-Digest: \ 1041 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1043 "hello" 1045 Figure 15: Partial response with both Content-Digest and Repr-Digest 1047 In the response message above, note that the Repr-Digest and Content- 1048 Digests are different. The Repr-Digest field-value is calculated 1049 across the entire JSON object {"hello": "world"}, and the field is 1051 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1053 However, since the message content is constrained to bytes 1-7, the 1054 Content-Digest field-value is calculated over the byte sequence 1055 "hello", thus resulting in 1057 NOTE: '\' line wrapping per RFC 8792 1059 Content-Digest: \ 1060 sha-256=:Wqdirjg/u3J688ejbUlApbjECpiUUtIwT8lY/z81Tno=: 1062 B.4. Client and Server Provide Full Representation Data 1064 The request contains a Repr-Digest field-value calculated on the 1065 enclosed representation. It also includes an Accept-Encoding: br 1066 header field that advertises the client supports Brotli encoding. 1068 The response includes a Content-Encoding: br that indicates the 1069 selected representation is Brotli-encoded. The Repr-Digest field- 1070 value is therefore different compared to the request. 1072 For presentation purposes, the response body is displayed as a 1073 Base64-encoded string because it contains non-printable characters. 1075 PUT /items/123 HTTP/1.1 1076 Host: foo.example 1077 Content-Type: application/json 1078 Accept-Encoding: br 1079 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1081 {"hello": "world"} 1083 Figure 16: PUT Request with Digest 1085 HTTP/1.1 200 OK 1086 Content-Type: application/json 1087 Content-Location: /items/123 1088 Content-Encoding: br 1089 Content-Length: 22 1090 Repr-Digest: sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=: 1092 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 1094 Figure 17: Response with Digest of encoded response 1096 B.5. Client Provides Full Representation Data, Server Provides No 1097 Representation Data 1099 The request Repr-Digest field-value is calculated on the enclosed 1100 payload. 1102 The response Repr-Digest field-value depends on the representation 1103 metadata header fields, including Content-Encoding: br even when the 1104 response does not contain content. 1106 PUT /items/123 HTTP/1.1 1107 Host: foo.example 1108 Content-Type: application/json 1109 Content-Length: 18 1110 Accept-Encoding: br 1111 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1113 {"hello": "world"} 1114 HTTP/1.1 204 No Content 1115 Content-Type: application/json 1116 Content-Encoding: br 1117 Repr-Digest: sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=: 1119 Figure 18: Empty response with Digest 1121 B.6. Client and Server Provide Full Representation Data 1123 The response contains two digest values using different algorithms. 1125 As the response body contains non-printable characters, it is 1126 displayed as a base64-encoded string. 1128 PUT /items/123 HTTP/1.1 1129 Host: foo.example 1130 Content-Type: application/json 1131 Accept-Encoding: br 1132 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1134 {"hello": "world"} 1136 Figure 19: PUT Request with Digest 1138 NOTE: '\' line wrapping per RFC 8792 1140 HTTP/1.1 200 OK 1141 Content-Type: application/json 1142 Content-Encoding: br 1143 Content-Location: /items/123 1144 Repr-Digest: \ 1145 sha-256=:4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo=:,\ 1146 sha-512=:pxo7aYzcGI88pnDnoSmAnaOEVys0MABhgvHY9+VI+ElE60jBCwnMPyA/\ 1147 s3NF3ZO5oIWA7lf8ukk+5KJzm3p5og==: 1149 iwiAeyJoZWxsbyI6ICJ3b3JsZCJ9Aw== 1151 Figure 20: Response with Digest of Encoded Content 1153 B.7. POST Response does not Reference the Request URI 1155 The request Repr-Digest field-value is computed on the enclosed 1156 representation (see Section 3.1). 1158 The representation enclosed in the response refers to the resource 1159 identified by Content-Location (see Section 6.4.2 of [HTTP]). Repr- 1160 Digest is thus computed on the enclosed representation. 1162 POST /books HTTP/1.1 1163 Host: foo.example 1164 Content-Type: application/json 1165 Accept: application/json 1166 Accept-Encoding: identity 1167 Repr-Digest: sha-256=:bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=: 1169 {"title": "New Title"} 1171 Figure 21: POST Request with Digest 1173 HTTP/1.1 201 Created 1174 Content-Type: application/json 1175 Content-Location: /books/123 1176 Location: /books/123 1177 Repr-Digest: sha-256=:yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE=: 1179 { 1180 "id": "123", 1181 "title": "New Title" 1182 } 1184 Figure 22: Response with Digest of Resource 1186 Note that a 204 No Content response without content but with the same 1187 Repr-Digest field-value would have been legitimate too. In that 1188 case, Content-Digest would have been computed on an empty content. 1190 B.8. POST Response Describes the Request Status 1192 The request Repr-Digest field-value is computed on the enclosed 1193 representation (see Section 3.1). 1195 The representation enclosed in the response describes the status of 1196 the request, so Repr-Digest is computed on that enclosed 1197 representation. 1199 Response Repr-Digest has no explicit relation with the resource 1200 referenced by Location. 1202 POST /books HTTP/1.1 1203 Host: foo.example 1204 Content-Type: application/json 1205 Accept: application/json 1206 Accept-Encoding: identity 1207 Repr-Digest: sha-256=:bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=: 1209 {"title": "New Title"} 1210 Figure 23: POST Request with Digest 1212 HTTP/1.1 201 Created 1213 Content-Type: application/json 1214 Repr-Digest: sha-256=:2LBp5RKZGpsSNf8BPXlXrX4Td4Tf5R5bZ9z7kdi5VvY=: 1215 Location: /books/123 1217 { 1218 "status": "created", 1219 "id": "123", 1220 "ts": 1569327729, 1221 "instance": "/books/123" 1222 } 1224 Figure 24: Response with Digest of Representation 1226 B.9. Digest with PATCH 1228 This case is analogous to a POST request where the target resource 1229 reflects the effective request URI. 1231 The PATCH request uses the application/merge-patch+json media type 1232 defined in [RFC7396]. 1234 Repr-Digest is calculated on the enclosed payload, which corresponds 1235 to the patch document. 1237 The response Repr-Digest field-value is computed on the complete 1238 representation of the patched resource. 1240 PATCH /books/123 HTTP/1.1 1241 Host: foo.example 1242 Content-Type: application/merge-patch+json 1243 Accept: application/json 1244 Accept-Encoding: identity 1245 Repr-Digest: sha-256=:bWopGGNiZtbVgHsG+I4knzfEJpmmmQHf7RHDXA3o1hQ=: 1247 {"title": "New Title"} 1249 Figure 25: PATCH Request with Digest 1251 HTTP/1.1 200 OK 1252 Content-Type: application/json 1253 Repr-Digest: sha-256=:yxOAqEeoj+reqygSIsLpT0LhumrNkIds5uLKtmdLyYE=: 1255 { 1256 "id": "123", 1257 "title": "New Title" 1258 } 1260 Figure 26: Response with Digest of Representation 1262 Note that a 204 No Content response without content but with the same 1263 Repr-Digest field-value would have been legitimate too. 1265 B.10. Error responses 1267 In error responses, the representation data does not necessarily 1268 refer to the target resource. Instead, it refers to the 1269 representation of the error. 1271 In the following example, a client sends the same request from 1272 Figure 25 to patch the resource located at /books/123. However, the 1273 resource does not exist and the server generates a 404 response with 1274 a body that describes the error in accordance with [RFC7807]. 1276 The response Repr-Digest field-value is computed on this enclosed 1277 representation. 1279 HTTP/1.1 404 Not Found 1280 Content-Type: application/problem+json 1281 Repr-Digest: sha-256=:KPqhVXAT25LLitV1w0O167unHmVQusu+fpxm65zAsvk=: 1283 { 1284 "title": "Not Found", 1285 "detail": "Cannot PATCH a non-existent resource", 1286 "status": 404 1287 } 1289 Figure 27: Response with Digest of Error Representation 1291 B.11. Use with Trailer Fields and Transfer Coding 1293 An origin server sends Repr-Digest as trailer field, so it can 1294 calculate digest-value while streaming content and thus mitigate 1295 resource consumption. The Repr-Digest field-value is the same as in 1296 Appendix B.1 because Repr-Digest is designed to be independent from 1297 the use of one or more transfer codings (see Section 3). 1299 GET /items/123 HTTP/1.1 1300 Host: foo.example 1302 Figure 28: GET Request 1304 HTTP/1.1 200 OK 1305 Content-Type: application/json 1306 Transfer-Encoding: chunked 1307 Trailer: Digest 1309 8\r\n 1310 {"hello"\r\n 1311 8 1312 : "world\r\n 1313 2\r\n 1314 "}\r\n 1315 0\r\n 1316 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1318 Figure 29: Chunked Response with Digest 1320 Appendix C. Examples of Want-Repr-Digest Solicited Digest 1322 The following examples demonstrate interactions where a client 1323 solicits a Repr-Digest using Want-Repr-Digest. The behavior of 1324 Content-Digest and Want-Content-Digest is identical. 1326 Some examples include JSON objects in the content. For presentation 1327 purposes, objects that fit completely within the line-length limits 1328 are presented on a single line using compact notation with no leading 1329 space. Objects that would exceed line-length limits are presented 1330 across multiple lines (one line per key-value pair) with 2 spaced of 1331 leading indentation. 1333 Checksum mechanisms described in this document are media-type 1334 agnostic and do not provide canonicalization algorithms for specific 1335 formats. Examples are calculated inclusive of any space. 1337 C.1. Server Selects Client's Least Preferred Algorithm 1339 The client requests a digest, preferring "sha". The server is free 1340 to reply with "sha-256" anyway. 1342 GET /items/123 HTTP/1.1 1343 Host: foo.example 1344 Want-Repr-Digest: sha-256=3, sha=10 1346 Figure 30: GET Request with Want-Repr-Digest 1348 HTTP/1.1 200 OK 1349 Content-Type: application/json 1350 Repr-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 1352 {"hello": "world"} 1354 Figure 31: Response with Different Algorithm 1356 C.2. Server Selects Algorithm Unsupported by Client 1358 The client requests a "sha" digest because that is the only algorithm 1359 it supports. The server is not obliged to produce a response 1360 containing a "sha" digest, it instead uses a different algorithm. 1362 GET /items/123 HTTP/1.1 1363 Host: foo.example 1364 Want-Repr-Digest: sha=10 1366 Figure 32: GET Request with Want-Repr-Digest 1368 NOTE: '\' line wrapping per RFC 8792 1370 HTTP/1.1 200 OK 1371 Content-Type: application/json 1372 Repr-Digest: \ 1373 sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrI\ 1374 iYllu7BNNyealdVLvRwEmTHWXvJwew==: 1376 {"hello": "world"} 1378 Figure 33: Response with Unsupported Algorithm 1380 C.3. Server Does Not Support Client Algorithm and Returns an Error 1382 Appendix C.2 is an example where a server ignores the client's 1383 preferred digest algorithm. Alternatively a server can also reject 1384 the request and return an error. 1386 In this example, the client requests a "sha" Repr-Digest, and the 1387 server returns an error with problem details [RFC7807] contained in 1388 the content. The problem details contain a list of the hashing 1389 algorithms that the server supports. This is purely an example, this 1390 specification does not define any format or requirements for such 1391 content. 1393 GET /items/123 HTTP/1.1 1394 Host: foo.example 1395 Want-Repr-Digest: sha=10 1396 Figure 34: GET Request with Want-Repr-Digest 1398 HTTP/1.1 400 Bad Request 1399 Content-Type: application/problem+json 1401 { 1402 "title": "Bad Request", 1403 "detail": "Supported hashing algorithms: sha-256, sha-512", 1404 "status": 400 1405 } 1407 Figure 35: Response advertising the supported algorithms 1409 Appendix D. Migrating from RFC 3230 1411 HTTP digests are computed by applying a hashing algorithm to input 1412 data. RFC 3230 defined the input data as an "instance", a term it 1413 also defined. The concept of instance has since been superseded by 1414 the HTTP semantic term "representation". It is understood that some 1415 implementations of RFC 3230 mistook "instance" to mean HTTP content. 1416 Using content for the Digest field is an error that leads to 1417 interoperability problems between peers that implement RFC 3230. 1419 RFC 3230 was only ever intended to use what HTTP now defines as 1420 selected representation data. The semantic concept of digest and 1421 representation are explained alongside the definition of the 1422 Repr-Digest field (Section 3). 1424 While the syntax of Digest and Repr-Digest are different, the 1425 considerations and examples this document gives for Repr-Digest apply 1426 equally to Digest because they operate on the same input data; see 1427 Section 3.1, Section 6 and Section 6.3. 1429 RFC 3230 could never communicate the digest of HTTP message content 1430 in the Digest field; Content-Digest now provides that capability. 1432 Acknowledgements 1434 This document is based on ideas from [RFC3230], so thanks to Jeff 1435 Mogul and Arthur Van Hoff for their great work. The original idea of 1436 refreshing RFC3230 arose from an interesting discussion with Mark 1437 Nottingham, Jeffrey Yasskin and Martin Thomson when reviewing the 1438 MICE content coding. 1440 Thanks to Julian Reschke for his valuable contributions to this 1441 document, and to the following contributors that have helped improve 1442 this specification by reporting bugs, asking smart questions, 1443 drafting or reviewing text, and evaluating open issues: Mike Bishop, 1444 Brian Campbell, Matthew Kerwin, James Manger, Tommy Pauly, Sean 1445 Turner, Justin Richer, and Erik Wilde. 1447 Code Samples 1449 This section is to be removed before publishing as an RFC. 1451 How can I generate and validate the Repr-Digest values shown in the 1452 examples throughout this document? 1454 The following python3 code can be used to generate digests for JSON 1455 objects using SHA algorithms for a range of encodings. Note that 1456 these are formatted as base64. This function could be adapted to 1457 other algorithms and should take into account their specific 1458 formatting rules. 1460 import base64, json, hashlib, brotli, logging 1461 log = logging.getLogger() 1463 def encode_item(item, encoding=lambda x: x): 1464 indent = 2 if isinstance(item, dict) and len(item) > 1 else None 1465 json_bytes = json.dumps(item, indent=indent).encode() 1466 return encoding(json_bytes) 1468 def digest_bytes(bytes_, algorithm=hashlib.sha256): 1469 checksum_bytes = algorithm(bytes_).digest() 1470 log.warning("Log bytes: \n[%r]", bytes_) 1471 return base64.encodebytes(checksum_bytes).strip() 1473 def digest(item, encoding=lambda x: x, algorithm=hashlib.sha256): 1474 content_encoded = encode_item(item, encoding) 1475 return digest_bytes(content_encoded, algorithm) 1477 item = {"hello": "world"} 1479 print("Encoding | hashing algorithm | digest-value") 1480 print("Identity | sha256 |", digest(item)) 1481 # Encoding | hashing algorithm | digest-value 1482 # Identity | sha256 | X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1484 print("Encoding | hashing algorithm | digest-value") 1485 print("Brotli | sha256 |", digest(item, encoding=brotli.compress)) 1486 # Encoding | hashing algorithm | digest-value 1487 # Brotli | sha256 | 4REjxQ4yrqUVicfSKYNO/cF9zNj5ANbzgDZt3/h3Qxo= 1489 print("Encoding | hashing algorithm | digest-value") 1490 print("Identity | sha512 |", digest(item, algorithm=hashlib.sha512)) 1491 print("Brotli | sha512 |", digest(item, algorithm=hashlib.sha512, 1492 encoding=brotli.compress)) 1493 # Encoding | hashing algorithm | digest-value 1494 # Identity | sha512 |b'WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm' 1495 # '+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==' 1496 # Brotli | sha512 | b'pxo7aYzcGI88pnDnoSmAnaOEVys0MABhgvHY9+VI+ElE6' 1497 # '0jBCwnMPyA/s3NF3ZO5oIWA7lf8ukk+5KJzm3p5og==' 1499 Changes 1501 This section is to be removed before publishing as an RFC. 1503 Since draft-ietf-httpbis-digest-headers-08 1505 * Add note about migrating from RFC 3230. #1968, #1971 1506 * Clarify what Want-* means in responses. #2097 1508 * Editorial changes to structure and to align to HTTP style guide. 1510 Since draft-ietf-httpbis-digest-headers-07 1512 * Introduced Repr-Digest and Want-Repr-Digest, and deprecated Digest 1513 and Want-Digest. Use of Structured Fields. #1993, #1919 1515 * IANA refactoring. #1983 1517 * No normative text in security considerations. #1972 1519 Since draft-ietf-httpbis-digest-headers-06 1521 * Remove id-sha-256 and id-sha-512 from the list of supported 1522 algorithms #855 1524 Since draft-ietf-httpbis-digest-headers-05 1526 * Reboot digest-algorithm values registry #1567 1528 * Add Content-Digest #1542 1530 * Remove SRI section #1478 1532 Since draft-ietf-httpbis-digest-headers-04 1534 * Improve SRI section #1354 1536 * About duplicate digest-algorithms #1221 1538 * Improve security considerations #852 1540 * md5 and sha deprecation references #1392 1542 * Obsolete 3230 #1395 1544 * Editorial #1362 1546 Since draft-ietf-httpbis-digest-headers-03 1548 * Reference semantics-12 1550 * Detail encryption quirks 1552 * Details on Algorithm agility #1250 1553 * Obsolete parameters #850 1555 Since draft-ietf-httpbis-digest-headers-02 1557 * Deprecate SHA-1 #1154 1559 * Avoid id-* with encrypted content 1561 * Digest is independent from MESSAGING and HTTP/1.1 is not normative 1562 #1215 1564 * Identity is not a valid field value for content-encoding #1223 1566 * Mention trailers #1157 1568 * Reference httpbis-semantics #1156 1570 * Add contentMD5 as an obsoleted digest-algorithm #1249 1572 * Use lowercase digest-algorithms names in the doc and in the 1573 digest-algorithm IANA table. 1575 Since draft-ietf-httpbis-digest-headers-01 1577 * Digest of error responses is computed on the error representation- 1578 data #1004 1580 * Effect of HTTP semantics on payload and message body moved to 1581 appendix #1122 1583 * Editorial refactoring, moving headers sections up. #1109-#1112, 1584 #1116, #1117, #1122-#1124 1586 Since draft-ietf-httpbis-digest-headers-00 1588 * Align title with document name 1590 * Add id-sha-* algorithm examples #880 1592 * Reference [RFC6234] and [RFC3174] instead of FIPS-1 1594 * Deprecate MD5 1596 * Obsolete ADLER-32 but don't forbid it #828 1598 * Update CRC32C value in IANA table #828 1600 * Use when acting on resources (POST, PATCH) #853 1601 * Added Relationship with SRI, draft Use Cases #868, #971 1603 * Warn about the implications of Content-Location 1605 Authors' Addresses 1607 Roberto Polli 1608 Team Digitale, Italian Government 1609 Italy 1610 Email: robipolli@gmail.com 1612 Lucas Pardue 1613 Cloudflare 1614 Email: lucaspardue.24.7@gmail.com