idnits 2.17.1 draft-ietf-httpbis-message-signatures-09.txt: -(3536): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 6 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (6 March 2022) is 781 days in the past. Is this intentional? 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. 'FIPS186-4' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTMLURL' -- Possible downref: Normative reference to a draft: ref. 'MESSAGING' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Downref: Normative reference to an Informational RFC: RFC 6234 ** Downref: Normative reference to an Informational RFC: RFC 8017 ** Downref: Normative reference to an Informational RFC: RFC 8032 ** Downref: Normative reference to an Informational RFC: RFC 8792 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' -- Obsolete informational reference (is this intentional?): RFC 7525 (ref. 'BCP195') (Obsoleted by RFC 9325) == Outdated reference: A later version (-06) exists of draft-ietf-httpbis-client-cert-field-01 Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP A. Backman, Ed. 3 Internet-Draft Amazon 4 Intended status: Standards Track J. Richer 5 Expires: 7 September 2022 Bespoke Engineering 6 M. Sporny 7 Digital Bazaar 8 6 March 2022 10 HTTP Message Signatures 11 draft-ietf-httpbis-message-signatures-09 13 Abstract 15 This document describes a mechanism for creating, encoding, and 16 verifying digital signatures or message authentication codes over 17 components of an HTTP message. This mechanism supports use cases 18 where the full HTTP message may not be known to the signer, and where 19 the message may be transformed (e.g., by intermediaries) before 20 reaching the verifier. This document also describes a means for 21 requesting that a signature be applied to a subsequent HTTP message 22 in an ongoing HTTP exchange. 24 About This Document 26 This note is to be removed before publishing as an RFC. 28 Status information for this document may be found at 29 https://datatracker.ietf.org/doc/draft-ietf-httpbis-message- 30 signatures/. 32 Discussion of this document takes place on the HTTP Working Group 33 mailing list (mailto:ietf-http-wg@w3.org), which is archived at 34 https://lists.w3.org/Archives/Public/ietf-http-wg/. Working Group 35 information can be found at https://httpwg.org/. 37 Source for this draft and an issue tracker can be found at 38 https://github.com/httpwg/http-extensions/labels/signatures. 40 Status of This Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. 45 Internet-Drafts are working documents of the Internet Engineering 46 Task Force (IETF). Note that other groups may also distribute 47 working documents as Internet-Drafts. The list of current Internet- 48 Drafts is at https://datatracker.ietf.org/drafts/current/. 50 Internet-Drafts are draft documents valid for a maximum of six months 51 and may be updated, replaced, or obsoleted by other documents at any 52 time. It is inappropriate to use Internet-Drafts as reference 53 material or to cite them other than as "work in progress." 55 This Internet-Draft will expire on 7 September 2022. 57 Copyright Notice 59 Copyright (c) 2022 IETF Trust and the persons identified as the 60 document authors. All rights reserved. 62 This document is subject to BCP 78 and the IETF Trust's Legal 63 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 64 license-info) in effect on the date of publication of this document. 65 Please review these documents carefully, as they describe your rights 66 and restrictions with respect to this document. Code Components 67 extracted from this document must include Revised BSD License text as 68 described in Section 4.e of the Trust Legal Provisions and are 69 provided without warranty as described in the Revised BSD License. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 74 1.1. Requirements Discussion . . . . . . . . . . . . . . . . . 5 75 1.2. HTTP Message Transformations . . . . . . . . . . . . . . 6 76 1.3. Safe Transformations . . . . . . . . . . . . . . . . . . 7 77 1.4. Conventions and Terminology . . . . . . . . . . . . . . . 7 78 1.5. Application of HTTP Message Signatures . . . . . . . . . 10 79 2. HTTP Message Components . . . . . . . . . . . . . . . . . . . 11 80 2.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . . 12 81 2.1.1. Canonicalized Structured HTTP Fields . . . . . . . . 14 82 2.1.2. Dictionary Structured Field Members . . . . . . . . . 14 83 2.2. Derived Components . . . . . . . . . . . . . . . . . . . 15 84 2.2.1. Signature Parameters . . . . . . . . . . . . . . . . 16 85 2.2.2. Method . . . . . . . . . . . . . . . . . . . . . . . 18 86 2.2.3. Target URI . . . . . . . . . . . . . . . . . . . . . 19 87 2.2.4. Authority . . . . . . . . . . . . . . . . . . . . . . 19 88 2.2.5. Scheme . . . . . . . . . . . . . . . . . . . . . . . 20 89 2.2.6. Request Target . . . . . . . . . . . . . . . . . . . 20 90 2.2.7. Path . . . . . . . . . . . . . . . . . . . . . . . . 21 91 2.2.8. Query . . . . . . . . . . . . . . . . . . . . . . . . 22 92 2.2.9. Query Parameters . . . . . . . . . . . . . . . . . . 23 93 2.2.10. Status Code . . . . . . . . . . . . . . . . . . . . . 24 94 2.2.11. Request-Response Signature Binding . . . . . . . . . 24 95 2.3. Creating the Signature Base . . . . . . . . . . . . . . . 27 96 3. HTTP Message Signatures . . . . . . . . . . . . . . . . . . . 30 97 3.1. Creating a Signature . . . . . . . . . . . . . . . . . . 30 98 3.2. Verifying a Signature . . . . . . . . . . . . . . . . . . 32 99 3.2.1. Enforcing Application Requirements . . . . . . . . . 34 100 3.3. Signature Algorithm Methods . . . . . . . . . . . . . . . 35 101 3.3.1. RSASSA-PSS using SHA-512 . . . . . . . . . . . . . . 36 102 3.3.2. RSASSA-PKCS1-v1_5 using SHA-256 . . . . . . . . . . . 36 103 3.3.3. HMAC using SHA-256 . . . . . . . . . . . . . . . . . 37 104 3.3.4. ECDSA using curve P-256 DSS and SHA-256 . . . . . . . 37 105 3.3.5. EdDSA using curve edwards25519 . . . . . . . . . . . 38 106 3.3.6. JSON Web Signature (JWS) algorithms . . . . . . . . . 39 107 4. Including a Message Signature in a Message . . . . . . . . . 39 108 4.1. The 'Signature-Input' HTTP Field . . . . . . . . . . . . 40 109 4.2. The 'Signature' HTTP Field . . . . . . . . . . . . . . . 40 110 4.3. Multiple Signatures . . . . . . . . . . . . . . . . . . . 41 111 5. Requesting Signatures . . . . . . . . . . . . . . . . . . . . 44 112 5.1. The Accept-Signature Field . . . . . . . . . . . . . . . 45 113 5.2. Processing an Accept-Signature . . . . . . . . . . . . . 46 114 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 115 6.1. HTTP Signature Algorithms Registry . . . . . . . . . . . 47 116 6.1.1. Registration Template . . . . . . . . . . . . . . . . 47 117 6.1.2. Initial Contents . . . . . . . . . . . . . . . . . . 48 118 6.2. HTTP Signature Metadata Parameters Registry . . . . . . . 48 119 6.2.1. Registration Template . . . . . . . . . . . . . . . . 48 120 6.2.2. Initial Contents . . . . . . . . . . . . . . . . . . 49 121 6.3. HTTP Signature Derived Component Identifiers Registry . . 50 122 6.3.1. Registration Template . . . . . . . . . . . . . . . . 50 123 6.3.2. Initial Contents . . . . . . . . . . . . . . . . . . 51 124 7. Security Considerations . . . . . . . . . . . . . . . . . . . 52 125 7.1. Signature Verification Skipping . . . . . . . . . . . . . 52 126 7.2. Use of TLS . . . . . . . . . . . . . . . . . . . . . . . 52 127 7.3. Signature Replay . . . . . . . . . . . . . . . . . . . . 53 128 7.4. Insufficient Coverage . . . . . . . . . . . . . . . . . . 53 129 7.5. Cryptography and Signature Collision . . . . . . . . . . 54 130 7.6. Key Theft . . . . . . . . . . . . . . . . . . . . . . . . 54 131 7.7. Modification of Required Message Parameters . . . . . . . 55 132 7.8. Mismatch of Signature Parameters from Message . . . . . . 55 133 7.9. Multiple Signature Confusion . . . . . . . . . . . . . . 55 134 7.10. Signature Labels . . . . . . . . . . . . . . . . . . . . 56 135 7.11. Symmetric Cryptography . . . . . . . . . . . . . . . . . 56 136 7.12. Canonicalization Attacks . . . . . . . . . . . . . . . . 57 137 7.13. Key Specification Mix-Up . . . . . . . . . . . . . . . . 57 138 7.14. HTTP Versions and Component Ambiguity . . . . . . . . . . 57 139 7.15. Key and Algorithm Specification Downgrades . . . . . . . 58 140 7.16. Parsing Structured Field Values . . . . . . . . . . . . . 58 141 7.17. Choosing Message Components . . . . . . . . . . . . . . . 59 142 7.18. Confusing HTTP Field Names for Derived Component 143 Identifiers . . . . . . . . . . . . . . . . . . . . . . 59 144 7.19. Non-deterministic Signature Primitives . . . . . . . . . 60 145 7.20. Choosing Signature Parameters and Derived Components over 146 HTTP Fields . . . . . . . . . . . . . . . . . . . . . . 60 147 7.21. Semantically Equivalent Field Values . . . . . . . . . . 61 148 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 61 149 8.1. Identification through Keys . . . . . . . . . . . . . . . 62 150 8.2. Signatures do not provide confidentiality . . . . . . . . 62 151 8.3. Oracles . . . . . . . . . . . . . . . . . . . . . . . . . 62 152 8.4. Required Content . . . . . . . . . . . . . . . . . . . . 63 153 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 63 154 9.1. Normative References . . . . . . . . . . . . . . . . . . 63 155 9.2. Informative References . . . . . . . . . . . . . . . . . 65 156 Appendix A. Detecting HTTP Message Signatures . . . . . . . . . 65 157 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 66 158 B.1. Example Keys . . . . . . . . . . . . . . . . . . . . . . 66 159 B.1.1. Example Key RSA test . . . . . . . . . . . . . . . . 66 160 B.1.2. Example RSA PSS Key . . . . . . . . . . . . . . . . . 67 161 B.1.3. Example ECC P-256 Test Key . . . . . . . . . . . . . 68 162 B.1.4. Example Ed25519 Test Key . . . . . . . . . . . . . . 69 163 B.1.5. Example Shared Secret . . . . . . . . . . . . . . . . 69 164 B.2. Test Cases . . . . . . . . . . . . . . . . . . . . . . . 69 165 B.2.1. Minimal Signature Using rsa-pss-sha512 . . . . . . . 70 166 B.2.2. Selective Covered Components using rsa-pss-sha512 . . 71 167 B.2.3. Full Coverage using rsa-pss-sha512 . . . . . . . . . 72 168 B.2.4. Signing a Response using ecdsa-p256-sha256 . . . . . 73 169 B.2.5. Signing a Request using hmac-sha256 . . . . . . . . . 74 170 B.2.6. Signing a Request using ed25519 . . . . . . . . . . . 74 171 B.3. TLS-Terminating Proxies . . . . . . . . . . . . . . . . . 75 172 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 77 173 Document History . . . . . . . . . . . . . . . . . . . . . . . . 78 174 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82 176 1. Introduction 178 Message integrity and authenticity are important security properties 179 that are critical to the secure operation of many HTTP applications. 180 Application developers typically rely on the transport layer to 181 provide these properties, by operating their application over [TLS]. 182 However, TLS only guarantees these properties over a single TLS 183 connection, and the path between client and application may be 184 composed of multiple independent TLS connections (for example, if the 185 application is hosted behind a TLS-terminating gateway or if the 186 client is behind a TLS Inspection appliance). In such cases, TLS 187 cannot guarantee end-to-end message integrity or authenticity between 188 the client and application. Additionally, some operating 189 environments present obstacles that make it impractical to use TLS, 190 or to use features necessary to provide message authenticity. 191 Furthermore, some applications require the binding of an application- 192 level key to the HTTP message, separate from any TLS certificates in 193 use. Consequently, while TLS can meet message integrity and 194 authenticity needs for many HTTP-based applications, it is not a 195 universal solution. 197 This document defines a mechanism for providing end-to-end integrity 198 and authenticity for components of an HTTP message. The mechanism 199 allows applications to create digital signatures or message 200 authentication codes (MACs) over only the components of the message 201 that are meaningful and appropriate for the application. Strict 202 canonicalization rules ensure that the verifier can verify the 203 signature even if the message has been transformed in any of the many 204 ways permitted by HTTP. 206 The signing mechanism described in this document consists of three 207 parts: 209 * A common nomenclature and canonicalization rule set for the 210 different protocol elements and other components of HTTP messages, 211 used to create the signature base. 213 * Algorithms for generating and verifying signatures over HTTP 214 message components using this signature base through application 215 of cryptographic primitives. 217 * A mechanism for attaching a signature and related metadata to an 218 HTTP message, and for parsing attached signatures and metadata 219 from HTTP messages. 221 This document also provides a mechanism for a potential verifier to 222 signal to a potential signer that a signature is desired in one or 223 more subsequent messages. This optional negotiation mechanism can be 224 used along with opportunistic or application-driven message 225 signatures by either party. 227 1.1. Requirements Discussion 229 HTTP permits and sometimes requires intermediaries to transform 230 messages in a variety of ways. This may result in a recipient 231 receiving a message that is not bitwise equivalent to the message 232 that was originally sent. In such a case, the recipient will be 233 unable to verify a signature over the raw bytes of the sender's HTTP 234 message, as verifying digital signatures or MACs requires both signer 235 and verifier to have the exact same signature base. Since the exact 236 raw bytes of the message cannot be relied upon as a reliable source 237 for a signature base, the signer and verifier must independently 238 create the signature base from their respective versions of the 239 message, via a mechanism that is resilient to safe changes that do 240 not alter the meaning of the message. 242 For a variety of reasons, it is impractical to strictly define what 243 constitutes a safe change versus an unsafe one. Applications use 244 HTTP in a wide variety of ways, and may disagree on whether a 245 particular piece of information in a message (e.g., the body, or the 246 Date header field) is relevant. Thus a general purpose solution must 247 provide signers with some degree of control over which message 248 components are signed. 250 HTTP applications may be running in environments that do not provide 251 complete access to or control over HTTP messages (such as a web 252 browser's JavaScript environment), or may be using libraries that 253 abstract away the details of the protocol (such as the Java 254 HTTPClient library (https://openjdk.java.net/groups/net/httpclient/ 255 intro.html)). These applications need to be able to generate and 256 verify signatures despite incomplete knowledge of the HTTP message. 258 1.2. HTTP Message Transformations 260 As mentioned earlier, HTTP explicitly permits and in some cases 261 requires implementations to transform messages in a variety of ways. 262 Implementations are required to tolerate many of these 263 transformations. What follows is a non-normative and non-exhaustive 264 list of transformations that may occur under HTTP, provided as 265 context: 267 * Re-ordering of header fields with different header field names 268 (Section 3.2.2 of [MESSAGING]). 270 * Combination of header fields with the same field name 271 (Section 3.2.2 of [MESSAGING]). 273 * Removal of header fields listed in the Connection header field 274 (Section 6.1 of [MESSAGING]). 276 * Addition of header fields that indicate control options 277 (Section 6.1 of [MESSAGING]). 279 * Addition or removal of a transfer coding (Section 5.7.2 of 280 [MESSAGING]). 282 * Addition of header fields such as Via (Section 5.7.1 of 283 [MESSAGING]) and Forwarded (Section 4 of [RFC7239]). 285 1.3. Safe Transformations 287 Based on the definition of HTTP and the requirements described above, 288 we can identify certain types of transformations that should not 289 prevent signature verification, even when performed on message 290 components covered by the signature. The following list describes 291 those transformations: 293 * Combination of header fields with the same field name. 295 * Reordering of header fields with different names. 297 * Conversion between different versions of the HTTP protocol (e.g., 298 HTTP/1.x to HTTP/2, or vice-versa). 300 * Changes in casing (e.g., "Origin" to "origin") of any case- 301 insensitive components such as header field names, request URI 302 scheme, or host. 304 * Addition or removal of leading or trailing whitespace to a header 305 field value. 307 * Addition or removal of obs-folds. 309 * Changes to the request-target and Host header field that when 310 applied together do not result in a change to the message's 311 effective request URI, as defined in Section 5.5 of [MESSAGING]. 313 Additionally, all changes to components not covered by the signature 314 are considered safe. 316 1.4. Conventions and Terminology 318 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 319 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 320 "OPTIONAL" in this document are to be interpreted as described in 321 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 322 capitals, as shown here. 324 The terms "HTTP message", "HTTP request", "HTTP response", absolute- 325 form, absolute-path, "effective request URI", "gateway", "header 326 field", "intermediary", request-target, "sender", and "recipient" are 327 used as defined in [MESSAGING]. 329 The term "method" is to be interpreted as defined in Section 4 of 330 [SEMANTICS]. 332 For brevity, the term "signature" on its own is used in this document 333 to refer to both digital signatures (which use asymmetric 334 cryptography) and keyed MACs (which use symmetric cryptography). 335 Similarly, the verb "sign" refers to the generation of either a 336 digital signature or keyed MAC over a given input string. The 337 qualified term "digital signature" refers specifically to the output 338 of an asymmetric cryptographic signing operation. 340 In addition to those listed above, this document uses the following 341 terms: 343 HTTP Message Signature: 344 A digital signature or keyed MAC that covers one or more portions 345 of an HTTP message. Note that a given HTTP Message can contain 346 multiple HTTP Message Signatures. 348 Signer: 349 The entity that is generating or has generated an HTTP Message 350 Signature. Note that multiple entities can act as signers and 351 apply separate HTTP Message Signatures to a given HTTP Message. 353 Verifier: 354 An entity that is verifying or has verified an HTTP Message 355 Signature against an HTTP Message. Note that an HTTP Message 356 Signature may be verified multiple times, potentially by different 357 entities. 359 HTTP Message Component: 360 A portion of an HTTP message that is capable of being covered by 361 an HTTP Message Signature. 363 HTTP Message Component Identifier: 364 A value that uniquely identifies a specific HTTP Message Component 365 in respect to a particular HTTP Message Signature and the HTTP 366 Message it applies to. 368 HTTP Message Component Value: 369 The value associated with a given component identifier within the 370 context of a particular HTTP Message. Component values are 371 derived from the HTTP Message and are usually subject to a 372 canonicalization process. 374 Covered Components: 376 An ordered set of HTTP message component identifiers for fields 377 (Section 2.1) and derived components (Section 2.2) that indicates 378 the set of message components covered by the signature, never 379 including the @signature-params identifier itself. The order of 380 this set is preserved and communicated between the signer and 381 verifier to facilitate reconstruction of the signature base. 383 Signature Base: 384 The sequence of bytes processed by the cryptographic algorithm to 385 produce or verify the HTTP Message Signature. The signature base 386 is generated by the signer and verifier using the covered 387 components set and the HTTP Message. 389 HTTP Message Signature Algorithm: 390 A cryptographic algorithm that describes the signing and 391 verification process for the signature, defined in terms of the 392 HTTP_SIGN and HTTP_VERIFY primitives described in Section 3.3. 394 Key Material: 395 The key material required to create or verify the signature. The 396 key material is often identified with an explicit key identifier, 397 allowing the signer to indicate to the verifier which key was 398 used. 400 Creation Time: 401 A timestamp representing the point in time that the signature was 402 generated, as asserted by the signer. 404 Expiration Time: 405 A timestamp representing the point in time after which the 406 signature should no longer be accepted by the verifier, as 407 asserted by the signer. 409 The term "Unix time" is defined by [POSIX.1], Section 4.16 410 (http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ 411 V1_chap04.html#tag_04_16). 413 This document contains non-normative examples of partial and complete 414 HTTP messages. Some examples use a single trailing backslash '' to 415 indicate line wrapping for long values, as per [RFC8792]. The \ 416 character and leading spaces on wrapped lines are not part of the 417 value. 419 1.5. Application of HTTP Message Signatures 421 HTTP Message Signatures are designed to be a general-purpose security 422 mechanism applicable in a wide variety of circumstances and 423 applications. In order to properly and safely apply HTTP Message 424 Signatures, an application or profile of this specification MUST 425 specify all of the following items: 427 * The set of component identifiers (Section 2) that are expected and 428 required. For example, an authorization protocol could mandate 429 that the Authorization header be covered to protect the 430 authorization credentials and mandate the signature parameters 431 contain a created parameter, while an API expecting HTTP message 432 bodies could require the Digest header to be present and covered. 434 * A means of retrieving the key material used to verify the 435 signature. An application will usually use the keyid parameter of 436 the signature parameters (Section 2.2.1) and define rules for 437 resolving a key from there, though the appropriate key could be 438 known from other means. 440 * A means of determining the signature algorithm used to verify the 441 signature is appropriate for the key material. For example, the 442 process could use the alg parameter of the signature parameters 443 (Section 2.2.1) to state the algorithm explicitly, derive the 444 algorithm from the key material, or use some pre-configured 445 algorithm agreed upon by the signer and verifier. 447 * A means of determining that a given key and algorithm presented in 448 the request are appropriate for the request being made. For 449 example, a server expecting only ECDSA signatures should know to 450 reject any RSA signatures, or a server expecting asymmetric 451 cryptography should know to reject any symmetric cryptography. 453 An application using signatures also has to ensure that the verifier 454 will have access to all required information to re-create the 455 signature base. For example, a server behind a reverse proxy would 456 need to know the original request URI to make use of identifiers like 457 @target-uri. Additionally, an application using signatures in 458 responses would need to ensure that clients receiving signed 459 responses have access to all the signed portions, including any 460 portions of the request that were signed by the server. 462 The details of this kind of profiling are the purview of the 463 application and outside the scope of this specification, however some 464 additional considerations are discussed in Section 7. 466 2. HTTP Message Components 468 In order to allow signers and verifiers to establish which components 469 are covered by a signature, this document defines component 470 identifiers for components covered by an HTTP Message Signature, a 471 set of rules for deriving and canonicalizing the values associated 472 with these component identifiers from the HTTP Message, and the means 473 for combining these canonicalized values into a signature base. The 474 values for these items MUST be accessible to both the signer and the 475 verifier of the message, which means these are usually derived from 476 aspects of the HTTP message or signature itself. 478 Some HTTP message components can undergo transformations that change 479 the bitwise value without altering meaning of the component's value 480 (for example, the merging together of header fields with the same 481 name). Message component values must therefore be canonicalized 482 before it is signed, to ensure that a signature can be verified 483 despite such intermediary transformations. This document defines 484 rules for each component identifier that transform the identifier's 485 associated component value into such a canonical form. 487 Component identifiers are serialized using the production grammar 488 defined by [RFC8941], Section 4. The component identifier itself is 489 an sf-string value and MAY define parameters which are included using 490 the parameters rule. 492 component-identifier = sf-string parameters 494 Note that this means the serialization of the component identifier 495 itself is encased in double quotes, with parameters following as a 496 semicolon-separated list, such as "cache-control", "date", or 497 "@signature-params". 499 Component identifiers, including component identifiers with 500 parameters, MUST NOT be repeated within a single list of covered 501 components. Component identifiers with different parameter values 502 MAY be repeated within a single list of covered components. 504 The component value associated with a component identifier is defined 505 by the identifier itself. Component values MUST NOT contain newline 506 (\n) characters. 508 The following sections define component identifier types, their 509 parameters, their associated values, and the canonicalization rules 510 for their values. The method for combining component identifiers 511 into the signature base is defined in Section 2.3. 513 2.1. HTTP Fields 515 The component identifier for an HTTP field is the lowercased form of 516 its field name. While HTTP field names are case-insensitive, 517 implementations MUST use lowercased field names (e.g., content-type, 518 date, etag) when using them as component identifiers. 520 Unless overridden by additional parameters and rules, the HTTP field 521 value MUST be canonicalized as a single combined value as defined in 522 Section 5.2 of [SEMANTICS]. 524 If the combined value is not available for a given header, the 525 following algorithm will produce canonicalized results for an 526 implementation: 528 1. Create an ordered list of the field values of each instance of 529 the field in the message, in the order that they occur (or will 530 occur) in the message. 532 2. Strip leading and trailing whitespace from each item in the list. 533 Note that since HTTP field values are not allowed to contain 534 leading and trailing whitespace, this will be a no-op in a 535 compliant implementation. 537 3. Remove any obsolete line-folding within the line and replace it 538 with a single space (" "), as discussed in Section 5.2 of 539 [MESSAGING]. Note that this behavior is specific to [MESSAGING] 540 and does not apply to other versions of the HTTP specification. 542 4. Concatenate the list of values together with a single comma (",") 543 and a single space (" ") between each item. 545 The resulting string is the canonicalized component value. 547 Note that some HTTP fields have values with multiple valid 548 serializations that have equivalent semantics. Applications signing 549 and processing such fields MUST consider how to handle the values of 550 such fields to ensure that the signer and verifier can derive the 551 same value, as discussed in Section 7.21. 553 Following are non-normative examples of canonicalized values for 554 header fields, given the following example HTTP message fragment: 556 Host: www.example.com 557 Date: Tue, 20 Apr 2021 02:07:56 GMT 558 X-OWS-Header: Leading and trailing whitespace. 559 X-Obs-Fold-Header: Obsolete 560 line folding. 561 Cache-Control: max-age=60 562 Cache-Control: must-revalidate 563 Example-Dict: a=1, b=2;x=1;y=2, c=(a b c) 565 The following example shows canonicalized values for these example 566 header fields, presented using the signature base format discussed in 567 Section 2.3: 569 "host": www.example.com 570 "date": Tue, 20 Apr 2021 02:07:56 GMT 571 "x-ows-header": Leading and trailing whitespace. 572 "x-obs-fold-header": Obsolete line folding. 573 "cache-control": max-age=60, must-revalidate 574 "example-dict": a=1, b=2;x=1;y=2, c=(a b c) 576 Since empty HTTP header fields are allowed, they are also able to be 577 signed when present in a message. The canonicalized value is the 578 empty string. This means that the following empty header: 580 NOTE: '\' line wrapping per RFC 8792 582 X-Empty-Header: \ 584 Is serialized by the signature base generation algorithm 585 (Section 2.3) with an empty string value following the colon and 586 space added after the content identifier. 588 NOTE: '\' line wrapping per RFC 8792 590 "x-empty-header": \ 592 Note: these are shown here using the line wrapping algorithm in 593 [RFC8792] due to limitations in the document format that strips 594 trailing spaces from diagrams. 596 Any HTTP field component identifiers MAY have the following 597 parameters in specific circumstances. 599 sf A boolean flag indicating that the field value is to be 600 canonicalized using strict encoding of the structured field value. 601 Section 2.1.1 603 key A string parameter used to select a single member value from a 604 dictionary structured field. Section 2.1.2 606 2.1.1. Canonicalized Structured HTTP Fields 608 If value of the the HTTP field in question is a structured field 609 ([RFC8941]), the component identifier MAY include the sf parameter to 610 indicate it is a known structured field. If this parameter is 611 included with a component identifier, the HTTP field value MUST be 612 serialized using the rules specified in Section 4 of [RFC8941] 613 applicable to the type of the HTTP field. Note that this process 614 will replace any optional internal whitespace with a single space 615 character, among other potential transformations of the value. 617 For example, the following dictionary field is a valid serialization: 619 Example-Dict: a=1, b=2;x=1;y=2, c=(a b c) 621 If included in the input string as-is, it would be: 623 "example-dict": a=1, b=2;x=1;y=2, c=(a b c) 625 However, if the sf parameter is added, the value is re-serialized as 626 follows: 628 "example-dict";sf: a=1, b=2;x=1;y=2, c=(a b c) 630 The resulting string is used as the component value in Section 2.1. 632 2.1.2. Dictionary Structured Field Members 634 An individual member in the value of a Dictionary Structured Field is 635 identified by using the parameter key to indicate the member key as 636 an sf-string value. 638 An individual member in the value of a Dictionary Structured Field is 639 canonicalized by applying the serialization algorithm described in 640 Section 4.1.2 of [RFC8941] on the member value and its parameters, 641 without the dictionary key. 643 Each parameterized key for a given field MUST NOT appear more than 644 once in the signature base. Parameterized keys MAY appear in any 645 order. 647 If a dictionary key is named as a covered component but it does not 648 occur in the dictionary, this MUST cause an error in the signature 649 base generation. 651 Following are non-normative examples of canonicalized values for 652 Dictionary Structured Field Members given the following example 653 header field, whose value is known to be a Dictionary: 655 Example-Dict: a=1, b=2;x=1;y=2, c=(a b c) 657 The following example shows canonicalized values for different 658 component identifiers of this field, presented using the signature 659 base format discussed in Section 2.3: 661 "example-dict";key="a": 1 662 "example-dict";key="b": 2;x=1;y=2 663 "example-dict";key="c": (a b c) 665 Note that the value for key="c" has been re-serialized. 667 2.2. Derived Components 669 In addition to HTTP fields, there are a number of different 670 components that can be derived from the control data, processing 671 context, or other aspects of the HTTP message being signed. Such 672 derived components can be included in the signature base by defining 673 a component identifier and the derivation method for its component 674 value. 676 Derived component identifiers MUST start with the "at" @ character. 677 This differentiates derived component identifiers from HTTP field 678 names, which cannot contain the @ character as per Section 5.1 of 679 [SEMANTICS]. Processors of HTTP Message Signatures MUST treat 680 derived component identifiers separately from field names, as 681 discussed in Section 7.18. 683 This specification defines the following derived component 684 identifiers: 686 @signature-params The signature metadata parameters for this 687 signature. (Section 2.2.1) 689 @method The method used for a request. (Section 2.2.2) 691 @target-uri The full target URI for a request. (Section 2.2.3) 693 @authority The authority of the target URI for a request. 694 (Section 2.2.4) 696 @scheme The scheme of the target URI for a request. (Section 2.2.5) 698 @request-target The request target. (Section 2.2.6) 699 @path The absolute path portion of the target URI for a request. 700 (Section 2.2.7) 702 @query The query portion of the target URI for a request. 703 (Section 2.2.8) 705 @query-params The parsed query parameters of the target URI for a 706 request. (Section 2.2.9) 708 @status The status code for a response. (Section 2.2.10). 710 @request-response A signature from a request message that resulted 711 in this response message. (Section 2.2.11) 713 Additional derived component identifiers MAY be defined and 714 registered in the HTTP Signatures Derived Component Identifier 715 Registry. (Section 6.3) 717 Derived components can be applied in one or more of three targets: 719 request: Values derived from and results applied to an HTTP request 720 message as described in {{Section 3.4 of SEMANTICS. 722 response: Values derived from and results applied to an HTTP 723 response message as described in Section 3.4 of [SEMANTICS]. 725 related-response: Values derived from an HTTP request message and 726 results applied to the HTTP response message that is responding to 727 that specific request. 729 A component identifier definition MUST define all targets to which it 730 can be applied. 732 The component value MUST be derived from the HTTP message being 733 signed or the context in which the derivation occurs. The derived 734 component value MUST be of the following form: 736 derived-component-value = *VCHAR 738 2.2.1. Signature Parameters 740 HTTP Message Signatures have metadata properties that provide 741 information regarding the signature's generation and verification, 742 such as the set of covered components, a timestamp, identifiers for 743 verification key material, and other utilities. 745 The signature parameters component identifier is @signature-params. 746 This message component's value is REQUIRED as part of the signature 747 base (Section 2.3) but the component identifier MUST NOT be 748 enumerated within the set of covered components itself. 750 The signature parameters component value is the serialization of the 751 signature parameters for this signature, including the covered 752 components set with all associated parameters. These parameters 753 include any of the following: 755 * created: Creation time as an sf-integer UNIX timestamp value. 756 Sub-second precision is not supported. Inclusion of this 757 parameter is RECOMMENDED. 759 * expires: Expiration time as an sf-integer UNIX timestamp value. 760 Sub-second precision is not supported. 762 * nonce: A random unique value generated for this signature as an 763 sf-string value. 765 * alg: The HTTP message signature algorithm from the HTTP Message 766 Signature Algorithm Registry, as an sf-string value. 768 * keyid: The identifier for the key material as an sf-string value. 770 Additional parameters can be defined in the HTTP Signature Parameters 771 Registry (Section 6.2.2). 773 The signature parameters component value is serialized as a 774 parameterized inner list using the rules in Section 4 of [RFC8941] as 775 follows: 777 1. Let the output be an empty string. 779 2. Determine an order for the component identifiers of the covered 780 components, not including the @signature-params component 781 identifier itself. Once this order is chosen, it cannot be 782 changed. This order MUST be the same order as used in creating 783 the signature base (Section 2.3). 785 3. Serialize the component identifiers of the covered components, 786 including all parameters, as an ordered inner-list according to 787 Section 4.1.1.1 of [RFC8941] and append this to the output. 789 4. Determine an order for any signature parameters. Once this order 790 is chosen, it cannot be changed. 792 5. Append the parameters to the inner-list in the chosen order 793 according to Section 4.1.1.2 of [RFC8941], skipping parameters 794 that are not available or not used for this message signature. 796 6. The output contains the signature parameters component value. 798 Note that the inner-list serialization is used for the covered 799 component value instead of the sf-list serialization in order to 800 facilitate this value's inclusion in message fields such as the 801 Signature-Input field's dictionary, as discussed in Section 4.1. 803 This example shows a canonicalized value for the parameters of a 804 given signature: 806 NOTE: '\' line wrapping per RFC 8792 808 ("@target-uri" "@authority" "date" "cache-control")\ 809 ;keyid="test-key-rsa-pss";alg="rsa-pss-sha512";\ 810 created=1618884475;expires=1618884775 812 Note that an HTTP message could contain multiple signatures 813 (Section 4.3), but only the signature parameters used for a single 814 signature are included in an entry. 816 2.2.2. Method 818 The @method component identifier refers to the HTTP method of a 819 request message. The component value of is canonicalized by taking 820 the value of the method as a string. Note that the method name is 821 case-sensitive as per [SEMANTICS], Section 9.1, and conventionally 822 standardized method names are uppercase US-ASCII. If used, the 823 @method component identifier MUST occur only once in the covered 824 components. 826 For example, the following request message: 828 POST /path?param=value HTTP/1.1 829 Host: www.example.com 831 Would result in the following @method value: 833 "@method": POST 835 If used in a related-response, the @method component identifier 836 refers to the associated component value of the request that 837 triggered the response message being signed. 839 2.2.3. Target URI 841 The @target-uri component identifier refers to the target URI of a 842 request message. The component value is the full absolute target URI 843 of the request, potentially assembled from all available parts 844 including the authority and request target as described in 845 [SEMANTICS], Section 7.1. If used, the @target-uri component 846 identifier MUST occur only once in the covered components. 848 For example, the following message sent over HTTPS: 850 POST /path?param=value HTTP/1.1 851 Host: www.example.com 853 Would result in the following @target-uri value: 855 "@target-uri": https://www.example.com/path?param=value 857 If used in a related-response, the @target-uri component identifier 858 refers to the associated component value of the request that 859 triggered the response message being signed. 861 2.2.4. Authority 863 The @authority component identifier refers to the authority component 864 of the target URI of the HTTP request message, as defined in 865 [SEMANTICS], Section 7.2. In HTTP 1.1, this is usually conveyed 866 using the Host header, while in HTTP 2 and HTTP 3 it is conveyed 867 using the :authority pseudo-header. The value is the fully-qualified 868 authority component of the request, comprised of the host and, 869 optionally, port of the request target, as a string. The component 870 value MUST be normalized according to the rules in [SEMANTICS], 871 Section 4.2.3. Namely, the host name is normalized to lowercase and 872 the default port is omitted. If used, the @authority component 873 identifier MUST occur only once in the covered components. 875 For example, the following request message: 877 POST /path?param=value HTTP/1.1 878 Host: www.example.com 880 Would result in the following @authority component value: 882 "@authority": www.example.com 884 If used in a related-response, the @authority component identifier 885 refers to the associated component value of the request that 886 triggered the response message being signed. 888 The @authority derived component SHOULD be used instead signing the 889 Host header directly, see Section 7.20. 891 2.2.5. Scheme 893 The @scheme component identifier refers to the scheme of the target 894 URL of the HTTP request message. The component value is the scheme 895 as a string as defined in [SEMANTICS], Section 4.2. While the scheme 896 itself is case-insensitive, it MUST be normalized to lowercase for 897 inclusion in the signature base. If used, the @scheme component 898 identifier MUST occur only once in the covered components. 900 For example, the following request message requested over plain HTTP: 902 POST /path?param=value HTTP/1.1 903 Host: www.example.com 905 Would result in the following @scheme value: 907 "@scheme": http 909 If used in a related-response, the @scheme component identifier 910 refers to the associated component value of the request that 911 triggered the response message being signed. 913 2.2.6. Request Target 915 The @request-target component identifier refers to the full request 916 target of the HTTP request message, as defined in [SEMANTICS], 917 Section 7.1. The component value of the request target can take 918 different forms, depending on the type of request, as described 919 below. If used, the @request-target component identifier MUST occur 920 only once in the covered components. 922 For HTTP 1.1, the component value is equivalent to the request target 923 portion of the request line. However, this value is more difficult 924 to reliably construct in other versions of HTTP. Therefore, it is 925 NOT RECOMMENDED that this identifier be used when versions of HTTP 926 other than 1.1 might be in use. 928 The origin form value is combination of the absolute path and query 929 components of the request URL. For example, the following request 930 message: 932 POST /path?param=value HTTP/1.1 933 Host: www.example.com 935 Would result in the following @request-target component value: 937 "@request-target": /path?param=value 939 The following request to an HTTP proxy with the absolute-form value, 940 containing the fully qualified target URI: 942 GET https://www.example.com/path?param=value HTTP/1.1 944 Would result in the following @request-target component value: 946 "@request-target": https://www.example.com/path?param=value 948 The following CONNECT request with an authority-form value, 949 containing the host and port of the target: 951 CONNECT www.example.com:80 HTTP/1.1 952 Host: www.example.com 954 Would result in the following @request-target component value: 956 "@request-target": www.example.com:80 958 The following OPTIONS request message with the asterisk-form value, 959 containing a single asterisk * character: 961 OPTIONS * HTTP/1.1 962 Host: www.example.com 964 Would result in the following @request-target component value: 966 "@request-target": * 968 If used in a related-response, the @request-target component 969 identifier refers to the associated component value of the request 970 that triggered the response message being signed. 972 2.2.7. Path 974 The @path component identifier refers to the target path of the HTTP 975 request message. The component value is the absolute path of the 976 request target defined by [RFC3986], with no query component and no 977 trailing ? character. The value is normalized according to the rules 978 in [SEMANTICS], Section 4.2.3. Namely, an empty path string is 979 normalized as a single slash / character, and path components are 980 represented by their values after decoding any percent-encoded 981 octets. If used, the @path component identifier MUST occur only once 982 in the covered components. 984 For example, the following request message: 986 POST /path?param=value HTTP/1.1 987 Host: www.example.com 989 Would result in the following @path value: 991 "@path": /path 993 If used in a related-response, the @path identifier refers to the 994 associated component value of the request that triggered the response 995 message being signed. 997 2.2.8. Query 999 The @query component identifier refers to the query component of the 1000 HTTP request message. The component value is the entire normalized 1001 query string defined by [RFC3986], including the leading ? character. 1002 The value is normalized according to the rules in [SEMANTICS], 1003 Section 4.2.3. Namely, percent-encoded octets are decoded. If used, 1004 the @query component identifier MUST occur only once in the covered 1005 components. 1007 For example, the following request message: 1009 POST /path?param=value&foo=bar&baz=batman HTTP/1.1 1010 Host: www.example.com 1012 Would result in the following @query value: 1014 "@query": ?param=value&foo=bar&baz=batman 1016 The following request message: 1018 POST /path?queryString HTTP/1.1 1019 Host: www.example.com 1021 Would result in the following @query value: 1023 "@query": ?queryString 1025 If the query string is absent from the request message, the value is 1026 the leading ? character alone: 1028 "@query": ? 1030 If used in a related-response, the @query component identifier refers 1031 to the associated component value of the request that triggered the 1032 response message being signed. 1034 2.2.9. Query Parameters 1036 If a request target URI uses HTML form parameters in the query string 1037 as defined in HTMLURL, Section 5 [HTMLURL], the @query-params 1038 component identifier allows addressing of individual query 1039 parameters. The query parameters MUST be parsed according to 1040 HTMLURL, Section 5.1 [HTMLURL], resulting in a list of (nameString, 1041 valueString) tuples. The REQUIRED name parameter of each input 1042 identifier contains the nameString of a single query parameter as an 1043 sf-string value. Several different named query parameters MAY be 1044 included in the covered components. Single named parameters MAY 1045 occur in any order in the covered components. 1047 The component value of a single named parameter is the the 1048 valueString of the named query parameter defined by HTMLURL, 1049 Section 5.1 [HTMLURL], which is the value after percent-encoded 1050 octets are decoded. Note that this value does not include any 1051 leading ? characters, equals sign =, or separating & characters. 1052 Named query parameters with an empty valueString are included with an 1053 empty string as the component value. 1055 If a query parameter is named as a covered component but it does not 1056 occur in the query parameters, this MUST cause an error in the 1057 signature base generation. 1059 For example for the following request: 1061 POST /path?param=value&foo=bar&baz=batman&qux= HTTP/1.1 1062 Host: www.example.com 1064 Indicating the baz, qux and param named query parameters in would 1065 result in the following @query-param value: 1067 "@query-params";name="baz": batman 1068 "@query-params";name="qux": 1069 "@query-params";name="param": value 1071 If a parameter name occurs multiple times in a request, all parameter 1072 values of that name MUST be included in separate signature base lines 1073 in the order in which the parameters occur in the target URI. Note 1074 that in some implementations, the order of parsed query parameters is 1075 not stable, and this situation could lead to unexpected results. If 1076 multiple parameters are common within an application, it is 1077 RECOMMENDED to sign the entire query string using the @query 1078 component identifier defined in Section 2.2.8. 1080 If used in a related-response, the @query-params component identifier 1081 refers to the associated component value of the request that 1082 triggered the response message being signed. 1084 2.2.10. Status Code 1086 The @status component identifier refers to the three-digit numeric 1087 HTTP status code of a response message as defined in [SEMANTICS], 1088 Section 15. The component value is the serialized three-digit 1089 integer of the HTTP response code, with no descriptive text. If 1090 used, the @status component identifier MUST occur only once in the 1091 covered components. 1093 For example, the following response message: 1095 HTTP/1.1 200 OK 1096 Date: Fri, 26 Mar 2010 00:05:00 GMT 1098 Would result in the following @status value: 1100 "@status": 200 1102 The @status component identifier MUST NOT be used in a request 1103 message. 1105 2.2.11. Request-Response Signature Binding 1107 When a signed request message results in a signed response message, 1108 the @request-response component identifier can be used to 1109 cryptographically link the request and the response to each other by 1110 including the identified request signature value in the response's 1111 signature base without copying the value of the request's signature 1112 to the response directly. This component identifier has a single 1113 REQUIRED parameter: 1115 key Identifies which signature from the response to sign. 1117 The component value is the sf-binary representation of the signature 1118 value of the referenced request identified by the key parameter. 1120 For example, when serving this signed request: 1122 NOTE: '\' line wrapping per RFC 8792 1124 POST /foo?param=Value&Pet=dog HTTP/1.1 1125 Host: example.com 1126 Date: Tue, 20 Apr 2021 02:07:55 GMT 1127 Content-Type: application/json 1128 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1129 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1130 Content-Length: 18 1131 Signature-Input: sig1=("@method" "@authority" "@path" \ 1132 "content-digest" "content-length" "content-type")\ 1133 ;created=1618884475;keyid="test-key-rsa-pss" 1134 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1135 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8Br\ 1136 c8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINTEzpx\ 1137 jqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr65+BXe\ 1138 TG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZElYyUKaAI\ 1139 jZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1141 {"hello": "world"} 1143 This would result in the following unsigned response message: 1145 HTTP/1.1 503 Service Unavailable 1146 Date: Tue, 20 Apr 2021 02:07:56 GMT 1147 Content-Type: application/json 1148 Content-Length: 62 1150 {"busy": true, "message": "Your call is very important to us"} 1152 To cryptographically link the response to the request, the server 1153 signs the response with its own key and includes the signature of 1154 sig1 from the request in the covered components of the response. The 1155 signature base for this example is: 1157 NOTE: '\' line wrapping per RFC 8792 1159 "@status": 503 1160 "content-length": 62 1161 "content-type": application/json 1162 "@request-response";key="sig1": :LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJR\ 1163 GziCLuD8r5MW9S0RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVd\ 1164 wXyY/UkBIS1M8Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMT\ 1165 e0QE3IpWINTEzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuT\ 1166 Z9HdbD2Tr65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S\ 1167 1ag3LZElYyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1168 "@signature-params": ("@status" "content-length" "content-type" \ 1169 "@request-response";key="sig1");created=1618884479\ 1170 ;keyid="test-key-ecc-p256" 1172 The signed response message is: 1174 NOTE: '\' line wrapping per RFC 8792 1176 HTTP/1.1 503 Service Unavailable 1177 Date: Tue, 20 Apr 2021 02:07:56 GMT 1178 Content-Type: application/json 1179 Content-Length: 62 1180 Signature-Input: reqres=("@status" "content-length" "content-type" \ 1181 "@request-response";key="sig1");created=1618884479\ 1182 ;keyid="test-key-ecc-p256" 1183 Signature: reqres=:JqzXLIjNd6VWVg/M7enbjWkOgsPmIK9vcoFQEkLD0SXNbFjR\ 1184 6d+olsof1dv7xC7ygF1q0YKjVrbV2QlCpDxrHg==: 1186 {"busy": true, "message": "Your call is very important to us"} 1188 Since the request's signature value itself is not repeated in the 1189 response, the requester MUST keep the original signature value around 1190 long enough to validate the signature of the response that uses this 1191 component identifier. 1193 Note that the ECDSA algorithm in use here is non-deterministic, 1194 meaning a different signature value will be created every time the 1195 algorithm is run. The signature value provided here can be validated 1196 against the given keys, but newly-generated signature values are not 1197 expected to match the example. See Section 7.19. 1199 The @request-response component identifier MUST NOT be used in a 1200 request message. 1202 2.3. Creating the Signature Base 1204 The signature base is a US-ASCII string containing the canonicalized 1205 HTTP message components covered by the signature. The input to the 1206 signature base creation algorithm is the list of covered component 1207 identifiers and their associated values, along with any additional 1208 signature parameters. The output is the ordered set of bytes that 1209 form the signature base, which conforms to the following ABNF: 1211 signature-base = *( signature-base-line LF ) signature-params-line 1212 signature-base-line = component-identifier ":" SP 1213 ( derived-component-value / field-value ) 1214 signature-params-line = DQUOTE "@signature-params" DQUOTE ":" SP inner-list 1216 To create the signature base, the signer or verifier concatenates 1217 together entries for each identifier in the signature's covered 1218 components (including their parameters) using the following 1219 algorithm: 1221 1. Let the output be an empty string. 1223 2. For each message component item in the covered components set (in 1224 order): 1226 1. Append the component identifier for the covered component 1227 serialized according to the component-identifier rule. Note 1228 that this serialization places the component identifier in 1229 double quotes and appends any parameters outside of the 1230 quotes. 1232 2. Append a single colon : 1234 3. Append a single space " " 1236 4. Determine the component value for the component identifier. 1238 * If the component identifier starts with an "at" character 1239 (@), derive the component's value from the message 1240 according to the specific rules defined for the derived 1241 component identifier, as in Section 2.2. If the derived 1242 component identifier is unknown or the value cannot be 1243 derived, produce an error. 1245 * If the component identifier does not start with an "at" 1246 character (@), canonicalize the HTTP field value as 1247 described in Section 2.1. If the value cannot be 1248 calculated, produce an error. 1250 5. Append the covered component's canonicalized component value. 1252 6. Append a single newline \n 1254 3. Append the signature parameters component (Section 2.2.1) as 1255 follows: 1257 1. Append the component identifier for the signature parameters 1258 serialized according to the component-identifier rule, i.e. 1259 "@signature-params" 1261 2. Append a single colon : 1263 3. Append a single space " " 1265 4. Append the signature parameters' canonicalized component 1266 value as defined in Section 2.2.1 1268 4. Return the output string. 1270 If covered components reference a component identifier that cannot be 1271 resolved to a component value in the message, the implementation MUST 1272 produce an error and not create an input string. Such situations are 1273 included but not limited to: 1275 * The signer or verifier does not understand the derived component 1276 identifier. 1278 * The component identifier identifies a field that is not present in 1279 the message or whose value is malformed. 1281 * The component identifier indicates that a structured field 1282 serialization is used (via the sf parameter), but the field in 1283 question is known to not be a structured field or the type of 1284 structured field is not known to the implementation. 1286 * The component identifier is a dictionary member identifier that 1287 references a field that is not present in the message, is not a 1288 Dictionary Structured Field, or whose value is malformed. 1290 * The component identifier is a dictionary member identifier or a 1291 named query parameter identifier that references a member that is 1292 not present in the component value, or whose value is malformed. 1293 E.g., the identifier is "example-dict";key="c" and the value of 1294 the Example-Dict header field is a=1, b=2, which does not have the 1295 c value. 1297 In the following non-normative example, the HTTP message being signed 1298 is the following request: 1300 POST /foo?param=Value&Pet=dog HTTP/1.1 1301 Host: example.com 1302 Date: Tue, 20 Apr 2021 02:07:55 GMT 1303 Content-Type: application/json 1304 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1305 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1306 Content-Length: 18 1308 {"hello": "world"} 1310 The covered components consist of the @method, @path, and @authority 1311 derived component identifiers followed by the Content-Digest, 1312 Content-Length, and Content-Type HTTP header fields, in order. The 1313 signature parameters consist of a creation timestamp of 1618884473 1314 and a key identifier of test-key-rsa-pss. Note that no explicit alg 1315 parameter is given here since the verifier is assumed by the 1316 application to correctly use the RSA PSS algorithm based on the 1317 identified key. The signature base for this message with these 1318 parameters is: 1320 NOTE: '\' line wrapping per RFC 8792 1322 "@method": POST 1323 "@authority": example.com 1324 "@path": /foo 1325 "content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\ 1326 +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1327 "content-length": 18 1328 "content-type": application/json 1329 "@signature-params": ("@method" "@authority" "@path" \ 1330 "content-digest" "content-length" "content-type")\ 1331 ;created=1618884473;keyid="test-key-rsa-pss" 1333 Figure 1: Non-normative example Signature Base 1335 Note that the example signature base here, or anywhere else within 1336 this specification, does not include the final newline that ends the 1337 displayed example. 1339 3. HTTP Message Signatures 1341 An HTTP Message Signature is a signature over a string generated from 1342 a subset of the components of an HTTP message in addition to metadata 1343 about the signature itself. When successfully verified against an 1344 HTTP message, an HTTP Message Signature provides cryptographic proof 1345 that the message is semantically equivalent to the message for which 1346 the signature was generated, with respect to the subset of message 1347 components that was signed. 1349 3.1. Creating a Signature 1351 Creation of an HTTP message signature is a process that takes as its 1352 input the message and the requirements for the application. The 1353 output is a signature value and set of signature parameters that can 1354 be applied to the message. 1356 In order to create a signature, a signer MUST follow the following 1357 algorithm: 1359 1. The signer chooses an HTTP signature algorithm and key material 1360 for signing. The signer MUST choose key material that is 1361 appropriate for the signature's algorithm, and that conforms to 1362 any requirements defined by the algorithm, such as key size or 1363 format. The mechanism by which the signer chooses the algorithm 1364 and key material is out of scope for this document. 1366 2. The signer sets the signature's creation time to the current 1367 time. 1369 3. If applicable, the signer sets the signature's expiration time 1370 property to the time at which the signature is to expire. The 1371 expiration is a hint to the verifier, expressing the time at 1372 which the signer is no longer willing to vouch for the safety of 1373 the signature. 1375 4. The signer creates an ordered set of component identifiers 1376 representing the message components to be covered by the 1377 signature, and attaches signature metadata parameters to this 1378 set. The serialized value of this is later used as the value of 1379 the Signature-Input field as described in Section 4.1. 1381 * Once an order of covered components is chosen, the order MUST 1382 NOT change for the life of the signature. 1384 * Each covered component identifier MUST be either an HTTP field 1385 in the message Section 2.1 or a derived component identifier 1386 listed in Section 2.2 or its associated registry. 1388 * Signers of a request SHOULD include some or all of the message 1389 control data in the covered components, such as the @method, 1390 @authority, @target-uri, or some combination thereof. 1392 * Signers SHOULD include the created signature metadata 1393 parameter to indicate when the signature was created. 1395 * The @signature-params derived component identifier is not 1396 explicitly listed in the list of covered component 1397 identifiers, because it is required to always be present as 1398 the last line in the signature base. This ensures that a 1399 signature always covers its own metadata. 1401 * Further guidance on what to include in this set and in what 1402 order is out of scope for this document. 1404 5. The signer creates the signature base using these parameters and 1405 the signature base creation algorithm. (Section 2.3) 1407 6. The signer uses the HTTP_SIGN primitive function to sign the 1408 signature base with the chosen signing algorithm using the key 1409 material chosen by the signer. The HTTP_SIGN primitive and 1410 several concrete applications of signing algorithms are defined 1411 in in Section 3.3. 1413 7. The byte array output of the signature function is the HTTP 1414 message signature output value to be included in the Signature 1415 field as defined in Section 4.2. 1417 For example, given the HTTP message and signature parameters in the 1418 example in Section 2.3, the example signature base is signed with the 1419 test-key-rsa-pss key in Appendix B.1.2 and the RSA PSS algorithm 1420 described in Section 3.3.1, giving the following message signature 1421 output value, encoded in Base64: 1423 NOTE: '\' line wrapping per RFC 8792 1425 HIbjHC5rS0BYaa9v4QfD4193TORw7u9edguPh0AW3dMq9WImrlFrCGUDih47vAxi4L2\ 1426 YRZ3XMJc1uOKk/J0ZmZ+wcta4nKIgBkKq0rM9hs3CQyxXGxHLMCy8uqK488o+9jrptQ\ 1427 +xFPHK7a9sRL1IXNaagCNN3ZxJsYapFj+JXbmaI5rtAdSfSvzPuBCh+ARHBmWuNo1Uz\ 1428 VVdHXrl8ePL4cccqlazIJdC4QEjrF+Sn4IxBQzTZsL9y9TP5FsZYzHvDqbInkTNigBc\ 1429 E9cKOYNFCn4D/WM7F6TNuZO9EgtzepLWcjTymlHzK7aXq6Am6sfOrpIC49yXjj3ae6H\ 1430 RalVc/g== 1432 Figure 2: Non-normative example signature value 1434 Note that the RSA PSS algorithm in use here is non-deterministic, 1435 meaning a different signature value will be created every time the 1436 algorithm is run. The signature value provided here can be validated 1437 against the given keys, but newly-generated signature values are not 1438 expected to match the example. See Section 7.19. 1440 3.2. Verifying a Signature 1442 Verification of an HTTP message signature is a process that takes as 1443 its input the message (including Signature and Signature-Input 1444 fields) and the requirements for the application. The output of the 1445 verification is either a positive verification or an error. 1447 In order to verify a signature, a verifier MUST follow the following 1448 algorithm: 1450 1. Parse the Signature and Signature-Input fields as described in 1451 Section 4.1 and Section 4.2, and extract the signatures to be 1452 verified. 1454 1. If there is more than one signature value present, determine 1455 which signature should be processed for this message based on 1456 the policy and configuration of the verifier. If an 1457 applicable signature is not found, produce an error. 1459 2. If the chosen Signature value does not have a corresponding 1460 Signature-Input value, produce an error. 1462 2. Parse the values of the chosen Signature-Input field as a 1463 parameterized structured field inner list item (inner-list) to 1464 get the signature parameters for the signature to be verified. 1466 3. Parse the value of the corresponding Signature field to get the 1467 byte array value of the signature to be verified. 1469 4. Examine the signature parameters to confirm that the signature 1470 meets the requirements described in this document, as well as any 1471 additional requirements defined by the application such as which 1472 message components are required to be covered by the signature. 1473 (Section 3.2.1) 1475 5. Determine the verification key material for this signature. If 1476 the key material is known through external means such as static 1477 configuration or external protocol negotiation, the verifier will 1478 use that. If the key is identified in the signature parameters, 1479 the verifier will dereference this to appropriate key material to 1480 use with the signature. The verifier has to determine the 1481 trustworthiness of the key material for the context in which the 1482 signature is presented. If a key is identified that the verifier 1483 does not know, does not trust for this request, or does not match 1484 something preconfigured, the verification MUST fail. 1486 6. Determine the algorithm to apply for verification: 1488 1. If the algorithm is known through external means such as 1489 static configuration or external protocol negotiation, the 1490 verifier will use this algorithm. 1492 2. If the algorithm is explicitly stated in the signature 1493 parameters using a value from the HTTP Message Signatures 1494 registry, the verifier will use the referenced algorithm. 1496 3. If the algorithm can be determined from the keying material, 1497 such as through an algorithm field on the key value itself, 1498 the verifier will use this algorithm. 1500 4. If the algorithm is specified in more that one location, such 1501 as through static configuration and the algorithm signature 1502 parameter, or the algorithm signature parameter and from the 1503 key material itself, the resolved algorithms MUST be the 1504 same. If the algorithms are not the same, the verifier MUST 1505 vail the verification. 1507 7. Use the received HTTP message and the signature's metadata to 1508 recreate the signature base, using the algorithm defined in 1509 Section 2.3. The value of the @signature-params input is the 1510 value of the Signature-Input field for this signature serialized 1511 according to the rules described in Section 2.2.1, not including 1512 the signature's label from the Signature-Input field. 1514 8. If the key material is appropriate for the algorithm, apply the 1515 appropriate HTTP_VERIFY cryptographic verification algorithm to 1516 the signature, recalculated signature base, key material, 1517 signature value. The HTTP_VERIFY primitive and several concrete 1518 algorithms are defined in Section 3.3. 1520 9. The results of the verification algorithm function are the final 1521 results of the cryptographic verification function. 1523 If any of the above steps fail or produce an error, the signature 1524 validation fails. 1526 For example, verifying the signature with the key sig1 of the 1527 following message with the test-key-rsa-pss key in Appendix B.1.2 and 1528 the RSA PSS algorithm described in Section 3.3.1: 1530 NOTE: '\' line wrapping per RFC 8792 1532 POST /foo?param=Value&Pet=dog HTTP/1.1 1533 Host: example.com 1534 Date: Tue, 20 Apr 2021 02:07:55 GMT 1535 Content-Type: application/json 1536 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1537 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1538 Content-Length: 18 1539 Signature-Input: sig1=("@method" "@authority" "@path" \ 1540 "content-digest" "content-length" "content-type")\ 1541 ;created=1618884473;keyid="test-key-rsa-pss" 1542 Signature: sig1=:HIbjHC5rS0BYaa9v4QfD4193TORw7u9edguPh0AW3dMq9WImrl\ 1543 FrCGUDih47vAxi4L2YRZ3XMJc1uOKk/J0ZmZ+wcta4nKIgBkKq0rM9hs3CQyxXGxH\ 1544 LMCy8uqK488o+9jrptQ+xFPHK7a9sRL1IXNaagCNN3ZxJsYapFj+JXbmaI5rtAdSf\ 1545 SvzPuBCh+ARHBmWuNo1UzVVdHXrl8ePL4cccqlazIJdC4QEjrF+Sn4IxBQzTZsL9y\ 1546 9TP5FsZYzHvDqbInkTNigBcE9cKOYNFCn4D/WM7F6TNuZO9EgtzepLWcjTymlHzK7\ 1547 aXq6Am6sfOrpIC49yXjj3ae6HRalVc/g==: 1549 {"hello": "world"} 1551 With the additional requirements that at least the method, path, 1552 authority, and cache-control be signed, and that the signature 1553 creation timestamp is recent enough at the time of verification, the 1554 verification passes. 1556 3.2.1. Enforcing Application Requirements 1558 The verification requirements specified in this document are intended 1559 as a baseline set of restrictions that are generally applicable to 1560 all use cases. Applications using HTTP Message Signatures MAY impose 1561 requirements above and beyond those specified by this document, as 1562 appropriate for their use case. 1564 Some non-normative examples of additional requirements an application 1565 might define are: 1567 * Requiring a specific set of header fields to be signed (e.g., 1568 Authorization, Digest). 1570 * Enforcing a maximum signature age from the time of the created 1571 time stamp. 1573 * Rejection of signatures past the expiration time in the expires 1574 time stamp. Note that the expiration time is a hint from the 1575 signer and that a verifier can always reject a signature ahead of 1576 its expiration time. 1578 * Prohibition of certain signature metadata parameters, such as 1579 runtime algorithm signaling with the alg parameter when the 1580 algorithm is determined from the key information. 1582 * Ensuring successful dereferencing of the keyid parameter to valid 1583 and appropriate key material. 1585 * Prohibiting the use of certain algorithms, or mandating the use of 1586 a specific algorithm. 1588 * Requiring keys to be of a certain size (e.g., 2048 bits vs. 1024 1589 bits). 1591 * Enforcing uniqueness of a nonce value. 1593 Application-specific requirements are expected and encouraged. When 1594 an application defines additional requirements, it MUST enforce them 1595 during the signature verification process, and signature verification 1596 MUST fail if the signature does not conform to the application's 1597 requirements. 1599 Applications MUST enforce the requirements defined in this document. 1600 Regardless of use case, applications MUST NOT accept signatures that 1601 do not conform to these requirements. 1603 3.3. Signature Algorithm Methods 1605 HTTP Message signatures MAY use any cryptographic digital signature 1606 or MAC method that is appropriate for the key material, environment, 1607 and needs of the signer and verifier. 1609 Each signature algorithm method takes as its input the signature base 1610 defined in Section 2.3 as a byte array (M), the signing key material 1611 (Ks), and outputs the signature output as a byte array (S): 1613 HTTP_SIGN (M, Ks) -> S 1615 Each verification algorithm method takes as its input the 1616 recalculated signature base defined in Section 2.3 as a byte array 1617 (M), the verification key material (Kv), and the presented signature 1618 to be verified as a byte array (S) and outputs the verification 1619 result (V) as a boolean: 1621 HTTP_VERIFY (M, Kv, S) -> V 1622 This section contains several common algorithm methods. The method 1623 to use can be communicated through the explicit algorithm signature 1624 parameter alg defined in Section 2.2.1, by reference to the key 1625 material, or through mutual agreement between the signer and 1626 verifier. 1628 3.3.1. RSASSA-PSS using SHA-512 1630 To sign using this algorithm, the signer applies the RSASSA-PSS-SIGN 1631 (K, M) function [RFC8017] with the signer's private signing key (K) 1632 and the signature base (M) (Section 2.3). The mask generation 1633 function is MGF1 as specified in [RFC8017] with a hash function of 1634 SHA-512 [RFC6234]. The salt length (sLen) is 64 bytes. The hash 1635 function (Hash) SHA-512 [RFC6234] is applied to the signature base to 1636 create the digest content to which the digital signature is applied. 1637 The resulting signed content byte array (S) is the HTTP message 1638 signature output used in Section 3.1. 1640 To verify using this algorithm, the verifier applies the RSASSA-PSS- 1641 VERIFY ((n, e), M, S) function [RFC8017] using the public key portion 1642 of the verification key material ((n, e)) and the signature base (M) 1643 re-created as described in Section 3.2. The mask generation function 1644 is MGF1 as specified in [RFC8017] with a hash function of SHA-512 1645 [RFC6234]. The salt length (sLen) is 64 bytes. The hash function 1646 (Hash) SHA-512 [RFC6234] is applied to the signature base to create 1647 the digest content to which the verification function is applied. 1648 The verifier extracts the HTTP message signature to be verified (S) 1649 as described in Section 3.2. The results of the verification 1650 function indicate if the signature presented is valid. 1652 Note that the output of RSA PSS algorithms are non-deterministic, and 1653 therefore it is not correct to re-calculate a new signature on the 1654 signature base and compare the results to an existing signature. 1655 Instead, the verification algorithm defined here needs to be used. 1656 See Section 7.19. 1658 Use of this algorithm can be indicated at runtime using the rsa-pss- 1659 sha512 value for the alg signature parameter. 1661 3.3.2. RSASSA-PKCS1-v1_5 using SHA-256 1663 To sign using this algorithm, the signer applies the RSASSA- 1664 PKCS1-V1_5-SIGN (K, M) function [RFC8017] with the signer's private 1665 signing key (K) and the signature base (M) (Section 2.3). The hash 1666 SHA-256 [RFC6234] is applied to the signature base to create the 1667 digest content to which the digital signature is applied. The 1668 resulting signed content byte array (S) is the HTTP message signature 1669 output used in Section 3.1. 1671 To verify using this algorithm, the verifier applies the RSASSA- 1672 PKCS1-V1_5-VERIFY ((n, e), M, S) function [RFC8017] using the public 1673 key portion of the verification key material ((n, e)) and the 1674 signature base (M) re-created as described in Section 3.2. The hash 1675 function SHA-256 [RFC6234] is applied to the signature base to create 1676 the digest content to which the verification function is applied. 1677 The verifier extracts the HTTP message signature to be verified (S) 1678 as described in Section 3.2. The results of the verification 1679 function are compared to the http message signature to determine if 1680 the signature presented is valid. 1682 Use of this algorithm can be indicated at runtime using the rsa- 1683 v1_5-sha256 value for the alg signature parameter. 1685 3.3.3. HMAC using SHA-256 1687 To sign and verify using this algorithm, the signer applies the HMAC 1688 function [RFC2104] with the shared signing key (K) and the signature 1689 base (text) (Section 2.3). The hash function SHA-256 [RFC6234] is 1690 applied to the signature base to create the digest content to which 1691 the HMAC is applied, giving the signature result. 1693 For signing, the resulting value is the HTTP message signature output 1694 used in Section 3.1. 1696 For verification, the verifier extracts the HTTP message signature to 1697 be verified (S) as described in Section 3.2. The output of the HMAC 1698 function is compared to the value of the HTTP message signature, and 1699 the results of the comparison determine the validity of the signature 1700 presented. 1702 Use of this algorithm can be indicated at runtime using the hmac- 1703 sha256 value for the alg signature parameter. 1705 3.3.4. ECDSA using curve P-256 DSS and SHA-256 1707 To sign using this algorithm, the signer applies the ECDSA algorithm 1708 [FIPS186-4] using curve P-256 with the signer's private signing key 1709 and the signature base (Section 2.3). The hash SHA-256 [RFC6234] is 1710 applied to the signature base to create the digest content to which 1711 the digital signature is applied, (M). The signature algorithm 1712 returns two integer values, r and s. These are both encoded in big- 1713 endian unsigned integers, zero-padded to 32-octets each. These 1714 encoded values are concatenated into a single 64-octet array 1715 consisting of the encoded value of r followed by the encoded value of 1716 s. The resulting concatenation of (r, s) is byte array of the HTTP 1717 message signature output used in Section 3.1. 1719 To verify using this algorithm, the verifier applies the ECDSA 1720 algorithm [FIPS186-4] using the public key portion of the 1721 verification key material and the signature base re-created as 1722 described in Section 3.2. The hash function SHA-256 [RFC6234] is 1723 applied to the signature base to create the digest content to which 1724 the signature verification function is applied, (M). The verifier 1725 extracts the HTTP message signature to be verified (S) as described 1726 in Section 3.2. This value is a 64-octet array consisting of the 1727 encoded values of r and s concatenated in order. These are both 1728 encoded in big-endian unsigned integers, zero-padded to 32-octets 1729 each. The resulting signature value (r, s) is used as input to the 1730 signature verification function. The results of the verification 1731 function indicate if the signature presented is valid. 1733 Note that the output of ECDSA algorithms are non-deterministic, and 1734 therefore it is not correct to re-calculate a new signature on the 1735 signature base and compare the results to an existing signature. 1736 Instead, the verification algorithm defined here needs to be used. 1737 See Section 7.19. 1739 Use of this algorithm can be indicated at runtime using the ecdsa- 1740 p256-sha256 value for the alg signature parameter. 1742 3.3.5. EdDSA using curve edwards25519 1744 To sign using this algorithm, the signer applies the Ed25519 1745 algorithm Section 5.1.6 of [RFC8032] with the signer's private 1746 signing key and the signature base (Section 2.3). The signature base 1747 is taken as the input message (M) with no pre-hash function. The 1748 signature is a 64-octet concatenation of R and S as specified in 1749 Section 5.1.6 of [RFC8032], and this is taken as a byte array for the 1750 HTTP message signature output used in Section 3.1. 1752 To verify using this algorithm, the signer applies the Ed25519 1753 algorithm Section 5.1.7 of [RFC8032] using the public key portion of 1754 the verification key material (A) and the signature base re-created 1755 as described in Section 3.2. The signature base is taken as the 1756 input message (M) with no pre-hash function. The signature to be 1757 verified is processed as the 64-octet concatenation of R and S as 1758 specified in Section 5.1.7 of [RFC8032]. The results of the 1759 verification function indicate if the signature presented is valid. 1761 Use of this algorithm can be indicated at runtime using the ed25519 1762 value for the alg signature parameter. 1764 3.3.6. JSON Web Signature (JWS) algorithms 1766 If the signing algorithm is a JOSE signing algorithm from the JSON 1767 Web Signature and Encryption Algorithms Registry established by 1768 [RFC7518], the JWS algorithm definition determines the signature and 1769 hashing algorithms to apply for both signing and verification. 1771 For both signing and verification, the HTTP messages signature base 1772 (Section 2.3) is used as the entire "JWS Signing Input". The JOSE 1773 Header defined in [RFC7517] is not used, and the signature base is 1774 not first encoded in Base64 before applying the algorithm. The 1775 output of the JWS signature is taken as a byte array prior to the 1776 Base64url encoding used in JOSE. 1778 The JWS algorithm MUST NOT be none and MUST NOT be any algorithm with 1779 a JOSE Implementation Requirement of Prohibited. 1781 JWA algorithm values from the JSON Web Signature and Encryption 1782 Algorithms Registry are not included as signature parameters. In 1783 fact, the explicit alg signature parameter is not used at all when 1784 using JOSE signing algorithms, as the JWS algorithm can be signaled 1785 using JSON Web Keys or other mechanisms common to JOSE 1786 implementations. 1788 4. Including a Message Signature in a Message 1790 Message signatures can be included within an HTTP message via the 1791 Signature-Input and Signature HTTP fields, both defined within this 1792 specification. When attached to a message, an HTTP message signature 1793 is identified by a label. This label MUST be unique within a given 1794 HTTP message and MUST be used in both the Signature-Input and 1795 Signature. The label is chosen by the signer, except where a 1796 specific label is dictated by protocol negotiations. 1798 An HTTP message signature MUST use both fields containing the same 1799 labels: the Signature HTTP field contains the signature value, while 1800 the Signature-Input HTTP field identifies the covered components and 1801 parameters that describe how the signature was generated. Each field 1802 contains labeled values and MAY contain multiple labeled values, 1803 where the labels determine the correlation between the Signature and 1804 Signature-Input fields. 1806 4.1. The 'Signature-Input' HTTP Field 1808 The Signature-Input HTTP field is a Dictionary Structured Field 1809 [RFC8941] containing the metadata for one or more message signatures 1810 generated from components within the HTTP message. Each member 1811 describes a single message signature. The member's name is an 1812 identifier that uniquely identifies the message signature within the 1813 context of the HTTP message. The member's value is the serialization 1814 of the covered components including all signature metadata 1815 parameters, using the serialization process defined in Section 2.2.1. 1817 NOTE: '\' line wrapping per RFC 8792 1819 Signature-Input: sig1=("@method" "@target-uri" "@authority" \ 1820 "content-digest" "cache-control");\ 1821 created=1618884475;keyid="test-key-rsa-pss" 1823 To facilitate signature validation, the Signature-Input field value 1824 MUST contain the same serialized value used in generating the 1825 signature base's @signature-params value. 1827 The signer MAY include the Signature-Input field as a trailer to 1828 facilitate signing a message after its content has been processed by 1829 the signer. However, since intermediaries are allowed to drop 1830 trailers as per [SEMANTICS], it is RECOMMENDED that the Signature- 1831 Input HTTP field be included only as a header to avoid signatures 1832 being inadvertently stripped from a message. 1834 Multiple Signature-Input fields MAY be included in a single HTTP 1835 message. The signature labels MUST be unique across all field 1836 values. 1838 4.2. The 'Signature' HTTP Field 1840 The Signature HTTP field is a Dictionary Structured field [RFC8941] 1841 containing one or more message signatures generated from components 1842 within the HTTP message. Each member's name is a signature 1843 identifier that is present as a member name in the Signature-Input 1844 Structured field within the HTTP message. Each member's value is a 1845 Byte Sequence containing the signature value for the message 1846 signature identified by the member name. Any member in the Signature 1847 HTTP field that does not have a corresponding member in the HTTP 1848 message's Signature-Input HTTP field MUST be ignored. 1850 NOTE: '\' line wrapping per RFC 8792 1852 Signature: sig1=:P0wLUszWQjoi54udOtydf9IWTfNhy+r53jGFj9XZuP4uKwxyJo\ 1853 1RSHi+oEF1FuX6O29d+lbxwwBao1BAgadijW+7O/PyezlTnqAOVPWx9GlyntiCiHz\ 1854 C87qmSQjvu1CFyFuWSjdGa3qLYYlNm7pVaJFalQiKWnUaqfT4LyttaXyoyZW84jS8\ 1855 gyarxAiWI97mPXU+OVM64+HVBHmnEsS+lTeIsEQo36T3NFf2CujWARPQg53r58Rmp\ 1856 Z+J9eKR2CD6IJQvacn5A4Ix5BUAVGqlyp8JYm+S/CWJi31PNUjRRCusCVRj05NrxA\ 1857 BNFv3r5S9IXf2fYJK+eyW4AiGVMvMcOg==: 1859 The signer MAY include the Signature field as a trailer to facilitate 1860 signing a message after its content has been processed by the signer. 1861 However, since intermediaries are allowed to drop trailers as per 1862 [SEMANTICS], it is RECOMMENDED that the Signature-Input HTTP field be 1863 included only as a header to avoid signatures being inadvertently 1864 stripped from a message. 1866 Multiple Signature fields MAY be included in a single HTTP message. 1867 The signature labels MUST be unique across all field values. 1869 4.3. Multiple Signatures 1871 Multiple distinct signatures MAY be included in a single message. 1872 Each distinct signature MUST have a unique label. Since Signature- 1873 Input and Signature are both defined as Dictionary Structured fields, 1874 they can be used to include multiple signatures within the same HTTP 1875 message by using distinct signature labels. These multiple 1876 signatures could be added all by the same signer or could come from 1877 several different signers. For example, a signer may include 1878 multiple signatures signing the same message components with 1879 different keys or algorithms to support verifiers with different 1880 capabilities, or a reverse proxy may include information about the 1881 client in fields when forwarding the request to a service host, 1882 including a signature over the client's original signature values. 1884 The following is a non-normative example starts with a signed request 1885 from the client. The proxy takes this request validates the client's 1886 signature. 1888 NOTE: '\' line wrapping per RFC 8792 1890 POST /foo?param=Value&Pet=dog HTTP/1.1 1891 Host: example.com 1892 Date: Tue, 20 Apr 2021 02:07:55 GMT 1893 Content-Type: application/json 1894 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1895 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1896 Content-Length: 18 1897 Signature-Input: sig1=("@method" "@authority" "@path" \ 1898 "content-digest" "content-length" "content-type")\ 1899 ;created=1618884475;keyid="test-key-rsa-pss" 1900 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1901 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8Br\ 1902 c8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINTEzpx\ 1903 jqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr65+BXe\ 1904 TG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZElYyUKaAI\ 1905 jZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1907 {"hello": "world"} 1909 The proxy then alters the message before forwarding it on to the 1910 origin server, changing the target host and adding the Forwarded 1911 header defined in [RFC7239]. 1913 NOTE: '\' line wrapping per RFC 8792 1915 POST /foo?param=Value&Pet=dog HTTP/1.1 1916 Host: origin.host.internal.example 1917 Date: Tue, 20 Apr 2021 02:07:56 GMT 1918 Content-Type: application/json 1919 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1920 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1921 Content-Length: 18 1922 Forwarded: for=192.0.2.123 1923 Signature-Input: sig1=("@method" "@authority" "@path" \ 1924 "content-digest" "content-length" "content-type")\ 1925 ;created=1618884475;keyid="test-key-rsa-pss" 1926 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1927 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8Br\ 1928 c8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINTEzpx\ 1929 jqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr65+BXe\ 1930 TG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZElYyUKaAI\ 1931 jZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1933 {"hello": "world"} 1934 The proxy includes the client's signature value under the label sig1, 1935 which the proxy signs in addition to the Forwarded header. Note that 1936 since the client's signature already covers the client's Signature- 1937 Input value for sig1, this value is transitively covered by the 1938 proxy's signature and need not be added explicitly. The proxy 1939 identifies its own key and algorithm and, in this example, includes 1940 an expiration for the signature to indicate to downstream systems 1941 that the proxy will not vouch for this signed message past this short 1942 time window. This results in a signature base of: 1944 NOTE: '\' line wrapping per RFC 8792 1946 "signature";key="sig1": :LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8\ 1947 r5MW9S0RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkB\ 1948 IS1M8Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpW\ 1949 INTEzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2T\ 1950 r65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZEl\ 1951 YyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1952 "forwarded": for=192.0.2.123 1953 "@signature-params": ("signature";key="sig1" "forwarded")\ 1954 ;created=1618884480;expires=1618884540;keyid="test-key-rsa"\ 1955 ;alg="rsa-v1_5-sha256" 1957 And a signature output value of: 1959 NOTE: '\' line wrapping per RFC 8792 1961 G1WLTL4/9PGSKEQbSAMypZNk+I2dpLJ6qvl2JISahlP31OO/QEUd8/HdO2O7vYLi5k3\ 1962 JIiAK3UPK4U+kvJZyIUidsiXlzRI+Y2se3SGo0D8dLfhG95bKr6ukYXl60QHpsGRTfS\ 1963 iwdtvYKXGpKNrMlISJYd+oGrGRyI9gbCy0aFhc6I/okIMLeK4g9PgzpC3YTwhUQ98KI\ 1964 BNLWHgREfBgJxjPbxFlsgJ9ykPviLj8GKJ81HwsK3XM9P7WaS7fMGOt8h1kSqgkZQB9\ 1965 YqiIo+WhHvJa7iPy8QrYFKzx9BBEY6AwfStZAsXXz3LobZseyxsYcLJLs8rY0wVA9NP\ 1966 sxKrHGA== 1968 These values are added to the HTTP request message by the proxy. The 1969 original signature is included under the identifier sig1, and the 1970 reverse proxy's signature is included under the label proxy_sig. The 1971 proxy uses the key test-key-rsa to create its signature using the 1972 rsa-v1_5-sha256 signature algorithm, while the client's original 1973 signature was made using the key id of test-key-rsa-pss and an RSA 1974 PSS signature algorithm. 1976 NOTE: '\' line wrapping per RFC 8792 1978 POST /foo?param=Value&Pet=dog HTTP/1.1 1979 Host: origin.host.internal.example 1980 Date: Tue, 20 Apr 2021 02:07:56 GMT 1981 Content-Type: application/json 1982 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1983 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1984 Content-Length: 18 1985 Forwarded: for=192.0.2.123 1986 Signature-Input: sig1=("@method" "@authority" "@path" \ 1987 "content-digest" "content-length" "content-type")\ 1988 ;created=1618884475;keyid="test-key-rsa-pss", \ 1989 proxy_sig=("signature";key="sig1" "forwarded")\ 1990 ;created=1618884480;expires=1618884540;keyid="test-key-rsa"\ 1991 ;alg="rsa-v1_5-sha256" 1992 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1993 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8\ 1994 Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINT\ 1995 EzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr\ 1996 65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZE\ 1997 lYyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==:, \ 1998 proxy_sig=:G1WLTL4/9PGSKEQbSAMypZNk+I2dpLJ6qvl2JISahlP31OO/QEUd8/\ 1999 HdO2O7vYLi5k3JIiAK3UPK4U+kvJZyIUidsiXlzRI+Y2se3SGo0D8dLfhG95bKr\ 2000 6ukYXl60QHpsGRTfSiwdtvYKXGpKNrMlISJYd+oGrGRyI9gbCy0aFhc6I/okIML\ 2001 eK4g9PgzpC3YTwhUQ98KIBNLWHgREfBgJxjPbxFlsgJ9ykPviLj8GKJ81HwsK3X\ 2002 M9P7WaS7fMGOt8h1kSqgkZQB9YqiIo+WhHvJa7iPy8QrYFKzx9BBEY6AwfStZAs\ 2003 XXz3LobZseyxsYcLJLs8rY0wVA9NPsxKrHGA==: 2005 {"hello": "world"} 2007 The proxy's signature and the client's original signature can be 2008 verified independently for the same message, based on the needs of 2009 the application. Since the proxy's signature covers the client 2010 signature, the backend service fronted by the proxy can trust that 2011 the proxy has validated the incoming signature. 2013 5. Requesting Signatures 2015 While a signer is free to attach a signature to a request or response 2016 without prompting, it is often desirable for a potential verifier to 2017 signal that it expects a signature from a potential signer using the 2018 Accept-Signature field. 2020 The message to which the requested signature is applied is known as 2021 the "target message". When the Accept-Signature field is sent in an 2022 HTTP Request message, the field indicates that the client desires the 2023 server to sign the response using the identified parameters and the 2024 target message is the response to this request. All responses from 2025 resources that support such signature negotiation SHOULD either be 2026 uncacheable or contain a Vary header field that lists Accept- 2027 Signature, in order to prevent a cache from returning a response with 2028 a signature intended for a different request. 2030 When the Accept-Signature field is used in an HTTP Response message, 2031 the field indicates that the server desires the client to sign its 2032 next request to the server with the identified parameters, and the 2033 target message is the client's next request. The client can choose 2034 to also continue signing future requests to the same server in the 2035 same way. 2037 The target message of an Accept-Signature field MUST include all 2038 labeled signatures indicated in the Accept-Header signature, each 2039 covering the same identified components of the Accept-Signature 2040 field. 2042 The sender of an Accept-Signature field MUST include identifiers that 2043 are appropriate for the type of the target message. For example, if 2044 the target message is a response, the identifiers can not include the 2045 @status identifier. 2047 5.1. The Accept-Signature Field 2049 The Accept-Signature HTTP header field is a Dictionary Structured 2050 field [RFC8941] containing the metadata for one or more requested 2051 message signatures to be generated from message components of the 2052 target HTTP message. Each member describes a single message 2053 signature. The member's name is an identifier that uniquely 2054 identifies the requested message signature within the context of the 2055 target HTTP message. The member's value is the serialization of the 2056 desired covered components of the target message, including any 2057 allowed signature metadata parameters, using the serialization 2058 process defined in Section 2.2.1. 2060 NOTE: '\' line wrapping per RFC 8792 2062 Accept-Signature: sig1=("@method" "@target-uri" "@authority" \ 2063 "content-digest" "cache-control");\ 2064 created=1618884475;keyid="test-key-rsa-pss" 2066 The requested signature MAY include parameters, such as a desired 2067 algorithm or key identifier. These parameters MUST NOT include 2068 parameters that the signer is expected to generate, including the 2069 created and nonce parameters. 2071 5.2. Processing an Accept-Signature 2073 The receiver of an Accept-Signature field fulfills that header as 2074 follows: 2076 1. Parse the field value as a Dictionary 2078 2. For each member of the dictionary: 2080 1. The name of the member is the label of the output signature 2081 as specified in Section 4.1 2083 2. Parse the value of the member to obtain the set of covered 2084 component identifiers 2086 3. Process the requested parameters, such as the signing 2087 algorithm and key material. If any requested parameters 2088 cannot be fulfilled, or if the requested parameters conflict 2089 with those deemed appropriate to the target message, the 2090 process fails and returns an error. 2092 4. Select any additional parameters necessary for completing the 2093 signature 2095 5. Create the Signature-Input and Signature header values and 2096 associate them with the label 2098 3. Optionally create any additional Signature-Input and Signature 2099 values, with unique labels not found in the Accept-Signature 2100 field 2102 4. Combine all labeled Signature-Input and Signature values and 2103 attach both headers to the target message 2105 Note that by this process, a signature applied to a target message 2106 MUST have the same label, MUST have the same set of covered 2107 component, and MAY have additional parameters. Also note that the 2108 target message MAY include additional signatures not specified by the 2109 Accept-Signature field. 2111 6. IANA Considerations 2113 IANA is requested to create three registries and to populate those 2114 registries with initial values as described in this section. 2116 6.1. HTTP Signature Algorithms Registry 2118 This document defines HTTP Signature Algorithms, for which IANA is 2119 asked to create and maintain a new registry titled "HTTP Signature 2120 Algorithms". Initial values for this registry are given in 2121 Section 6.1.2. Future assignments and modifications to existing 2122 assignment are to be made through the Expert Review registration 2123 policy [RFC8126] and shall follow the template presented in 2124 Section 6.1.1. 2126 Algorithms referenced by algorithm identifiers have to be fully 2127 defined with all parameters fixed. Algorithm identifiers in this 2128 registry are to be interpreted as whole string values and not as a 2129 combination of parts. That is to say, it is expected that 2130 implementors understand rsa-pss-sha512 as referring to one specific 2131 algorithm with its hash, mask, and salt values set as defined here. 2132 Implementors do not parse out the rsa, pss, and sha512 portions of 2133 the identifier to determine parameters of the signing algorithm from 2134 the string. 2136 Algorithms added to this registry MUST NOT be aliases for other 2137 entries in the registry. 2139 6.1.1. Registration Template 2141 Algorithm Name: 2142 An identifier for the HTTP Signature Algorithm. The name MUST be 2143 an ASCII string consisting only of lower-case characters ("a" - 2144 "z"), digits ("0" - "9"), and hyphens ("-"), and SHOULD NOT exceed 2145 20 characters in length. The identifier MUST be unique within the 2146 context of the registry. 2148 Status: 2149 A brief text description of the status of the algorithm. The 2150 description MUST begin with one of "Active" or "Deprecated", and 2151 MAY provide further context or explanation as to the reason for 2152 the status. 2154 Description: 2155 A brief description of the algorithm used to sign the signature 2156 base. 2158 Specification document(s): 2159 Reference to the document(s) that specify the token endpoint 2160 authorization method, preferably including a URI that can be used 2161 to retrieve a copy of the document(s). An indication of the 2162 relevant sections may also be included but is not required. 2164 6.1.2. Initial Contents 2166 +===================+========+===================+===============+ 2167 | Algorithm Name | Status | Description | Specification | 2168 | | | | document(s) | 2169 +===================+========+===================+===============+ 2170 | rsa-pss-sha512 | Active | RSASSA-PSS using | [[This | 2171 | | | SHA-512 | document]], | 2172 | | | | Section 3.3.1 | 2173 +-------------------+--------+-------------------+---------------+ 2174 | rsa-v1_5-sha256 | Active | RSASSA-PKCS1-v1_5 | [[This | 2175 | | | using SHA-256 | document]], | 2176 | | | | Section 3.3.2 | 2177 +-------------------+--------+-------------------+---------------+ 2178 | hmac-sha256 | Active | HMAC using | [[This | 2179 | | | SHA-256 | document]], | 2180 | | | | Section 3.3.3 | 2181 +-------------------+--------+-------------------+---------------+ 2182 | ecdsa-p256-sha256 | Active | ECDSA using curve | [[This | 2183 | | | P-256 DSS and | document]], | 2184 | | | SHA-256 | Section 3.3.4 | 2185 +-------------------+--------+-------------------+---------------+ 2186 | ed25519 | Active | Edwards Curve DSA | [[This | 2187 | | | using curve | document]], | 2188 | | | edwards25519 | Section 3.3.5 | 2189 +-------------------+--------+-------------------+---------------+ 2191 Table 1 2193 6.2. HTTP Signature Metadata Parameters Registry 2195 This document defines the signature parameters structure, the values 2196 of which may have parameters containing metadata about a message 2197 signature. IANA is asked to create and maintain a new registry 2198 titled "HTTP Signature Metadata Parameters" to record and maintain 2199 the set of parameters defined for use with member values in the 2200 signature parameters structure. Initial values for this registry are 2201 given in Section 6.2.2. Future assignments and modifications to 2202 existing assignments are to be made through the Expert Review 2203 registration policy [RFC8126] and shall follow the template presented 2204 in Section 6.2.1. 2206 6.2.1. Registration Template 2208 Name: 2210 An identifier for the HTTP signature metadata parameter. The name 2211 MUST be an ASCII string consisting only of lower-case characters 2212 ("a" - "z"), digits ("0" - "9"), and hyphens ("-"), and SHOULD NOT 2213 exceed 20 characters in length. The identifier MUST be unique 2214 within the context of the registry. 2216 Description: 2217 A brief description of the metadata parameter and what it 2218 represents. 2220 Specification document(s): 2221 Reference to the document(s) that specify the token endpoint 2222 authorization method, preferably including a URI that can be used 2223 to retrieve a copy of the document(s). An indication of the 2224 relevant sections may also be included but is not required. 2226 6.2.2. Initial Contents 2228 The table below contains the initial contents of the HTTP Signature 2229 Metadata Parameters Registry. Each row in the table represents a 2230 distinct entry in the registry. 2232 +=========+===============================+==================+ 2233 | Name | Description | Specification | 2234 | | | document(s) | 2235 +=========+===============================+==================+ 2236 | alg | Explicitly declared signature | Section 2.2.1 of | 2237 | | algorithm | this document | 2238 +---------+-------------------------------+------------------+ 2239 | created | Timestamp of signature | Section 2.2.1 of | 2240 | | creation | this document | 2241 +---------+-------------------------------+------------------+ 2242 | expires | Timestamp of proposed | Section 2.2.1 of | 2243 | | signature expiration | this document | 2244 +---------+-------------------------------+------------------+ 2245 | keyid | Key identifier for the | Section 2.2.1 of | 2246 | | signing and verification keys | this document | 2247 | | used to create this signature | | 2248 +---------+-------------------------------+------------------+ 2249 | nonce | A single-use nonce value | Section 2.2.1 of | 2250 | | | this document | 2251 +---------+-------------------------------+------------------+ 2253 Table 2: Initial contents of the HTTP Signature Metadata 2254 Parameters Registry. 2256 6.3. HTTP Signature Derived Component Identifiers Registry 2258 This document defines a method for canonicalizing HTTP message 2259 components, including components that can be derived from the context 2260 of the HTTP message outside of the HTTP fields. These components are 2261 identified by a unique string, known as the component identifier. 2262 Component identifiers for derived components always start with the 2263 "@" (at) symbol to distinguish them from HTTP header fields. IANA is 2264 asked to create and maintain a new registry typed "HTTP Signature 2265 Derived Component Identifiers" to record and maintain the set of non- 2266 field component identifiers and the methods to produce their 2267 associated component values. Initial values for this registry are 2268 given in Section 6.3.2. Future assignments and modifications to 2269 existing assignments are to be made through the Expert Review 2270 registration policy [RFC8126] and shall follow the template presented 2271 in Section 6.3.1. 2273 6.3.1. Registration Template 2275 Identifier: 2276 An identifier for the HTTP derived component identifier. The name 2277 MUST begin with the "@" character followed by an ASCII string 2278 consisting only of lower-case characters ("a" - "z"), digits ("0" 2279 - "9"), and hyphens ("-"), and SHOULD NOT exceed 20 characters in 2280 length. The identifier MUST be unique within the context of the 2281 registry. 2283 Status: 2284 A brief text description of the status of the algorithm. The 2285 description MUST begin with one of "Active" or "Deprecated", and 2286 MAY provide further context or explanation as to the reason for 2287 the status. 2289 Target: 2290 The valid message targets for the derived parameter. MUST be one 2291 of the values "Request", "Request, Response", "Request, Related- 2292 Response", or "Related-Response". The semantics of these are 2293 defined in Section 2.2. 2295 Specification document(s): 2296 Reference to the document(s) that specify the token endpoint 2297 authorization method, preferably including a URI that can be used 2298 to retrieve a copy of the document(s). An indication of the 2299 relevant sections may also be included but is not required. 2301 6.3.2. Initial Contents 2303 The table below contains the initial contents of the HTTP Signature 2304 Derived Component Identifiers Registry. 2306 +===================+========+==================+==================+ 2307 | Identifier | Status | Target | Specification | 2308 | | | | document(s) | 2309 +===================+========+==================+==================+ 2310 | @signature-params | Active | Request, | Section 2.2.1 of | 2311 | | | Response | this document | 2312 +-------------------+--------+------------------+------------------+ 2313 | @method | Active | Request, | Section 2.2.2 of | 2314 | | | Related-Response | this document | 2315 +-------------------+--------+------------------+------------------+ 2316 | @authority | Active | Request, | Section 2.2.4 of | 2317 | | | Related-Response | this document | 2318 +-------------------+--------+------------------+------------------+ 2319 | @scheme | Active | Request, | Section 2.2.5 of | 2320 | | | Related-Response | this document | 2321 +-------------------+--------+------------------+------------------+ 2322 | @target-uri | Active | Request, | Section 2.2.3 of | 2323 | | | Related-Response | this document | 2324 +-------------------+--------+------------------+------------------+ 2325 | @request-target | Active | Request, | Section 2.2.6 of | 2326 | | | Related-Response | this document | 2327 +-------------------+--------+------------------+------------------+ 2328 | @path | Active | Request, | Section 2.2.7 of | 2329 | | | Related-Response | this document | 2330 +-------------------+--------+------------------+------------------+ 2331 | @query | Active | Request, | Section 2.2.8 of | 2332 | | | Related-Response | this document | 2333 +-------------------+--------+------------------+------------------+ 2334 | @query-params | Active | Request, | Section 2.2.9 of | 2335 | | | Related-Response | this document | 2336 +-------------------+--------+------------------+------------------+ 2337 | @status | Active | Response | Section 2.2.10 | 2338 | | | | of this document | 2339 +-------------------+--------+------------------+------------------+ 2340 | @request-response | Active | Related-Response | Section 2.2.11 | 2341 | | | | of this document | 2342 +-------------------+--------+------------------+------------------+ 2344 Table 3: Initial contents of the HTTP Signature Derived 2345 Component Identifiers Registry. 2347 7. Security Considerations 2349 In order for an HTTP message to be considered covered by a signature, 2350 all of the following conditions have to be true: 2352 * a signature is expected or allowed on the message by the verifier 2354 * the signature exists on the message 2356 * the signature is verified against the identified key material and 2357 algorithm 2359 * the key material and algorithm are appropriate for the context of 2360 the message 2362 * the signature is within expected time boundaries 2364 * the signature covers the expected content, including any critical 2365 components 2367 7.1. Signature Verification Skipping 2369 HTTP Message Signatures only provide security if the signature is 2370 verified by the verifier. Since the message to which the signature 2371 is attached remains a valid HTTP message without the signature 2372 fields, it is possible for a verifier to ignore the output of the 2373 verification function and still process the message. Common reasons 2374 for this could be relaxed requirements in a development environment 2375 or a temporary suspension of enforcing verification during debugging 2376 an overall system. Such temporary suspensions are difficult to 2377 detect under positive-example testing since a good signature will 2378 always trigger a valid response whether or not it has been checked. 2380 To detect this, verifiers should be tested using both valid and 2381 invalid signatures, ensuring that the invalid signature fails as 2382 expected. 2384 7.2. Use of TLS 2386 The use of HTTP Message Signatures does not negate the need for TLS 2387 or its equivalent to protect information in transit. Message 2388 signatures provide message integrity over the covered message 2389 components but do not provide any confidentiality for the 2390 communication between parties. 2392 TLS provides such confidentiality between the TLS endpoints. As part 2393 of this, TLS also protects the signature data itself from being 2394 captured by an attacker, which is an important step in preventing 2395 signature replay (Section 7.3). 2397 When TLS is used, it needs to be deployed according to the 2398 recommendations in [BCP195]. 2400 7.3. Signature Replay 2402 Since HTTP Message Signatures allows sub-portions of the HTTP message 2403 to be signed, it is possible for two different HTTP messages to 2404 validate against the same signature. The most extreme form of this 2405 would be a signature over no message components. If such a signature 2406 were intercepted, it could be replayed at will by an attacker, 2407 attached to any HTTP message. Even with sufficient component 2408 coverage, a given signature could be applied to two similar HTTP 2409 messages, allowing a message to be replayed by an attacker with the 2410 signature intact. 2412 To counteract these kinds of attacks, it's first important for the 2413 signer to cover sufficient portions of the message to differentiate 2414 it from other messages. In addition, the signature can use the nonce 2415 signature parameter to provide a per-message unique value to allow 2416 the verifier to detect replay of the signature itself if a nonce 2417 value is repeated. Furthermore, the signer can provide a timestamp 2418 for when the signature was created and a time at which the signer 2419 considers the signature to be invalid, limiting the utility of a 2420 captured signature value. 2422 If a verifier wants to trigger a new signature from a signer, it can 2423 send the Accept-Signature header field with a new nonce parameter. 2424 An attacker that is simply replaying a signature would not be able to 2425 generate a new signature with the chosen nonce value. 2427 7.4. Insufficient Coverage 2429 Any portions of the message not covered by the signature are 2430 susceptible to modification by an attacker without affecting the 2431 signature. An attacker can take advantage of this by introducing a 2432 header field or other message component that will change the 2433 processing of the message but will not be covered by the signature. 2434 Such an altered message would still pass signature verification, but 2435 when the verifier processes the message as a whole, the unsigned 2436 content injected by the attacker would subvert the trust conveyed by 2437 the valid signature and change the outcome of processing the message. 2439 To combat this, an application of this specification should require 2440 as much of the message as possible to be signed, within the limits of 2441 the application and deployment. The verifier should only trust 2442 message components that have been signed. Verifiers could also strip 2443 out any sensitive unsigned portions of the message before processing 2444 of the message continues. 2446 7.5. Cryptography and Signature Collision 2448 The HTTP Message Signatures specification does not define any of its 2449 own cryptographic primitives, and instead relies on other 2450 specifications to define such elements. If the signature algorithm 2451 or key used to process the signature base is vulnerable to any 2452 attacks, the resulting signature will also be susceptible to these 2453 same attacks. 2455 A common attack against signature systems is to force a signature 2456 collision, where the same signature value successfully verifies 2457 against multiple different inputs. Since this specification relies 2458 on reconstruction of the input string based on an HTTP message, and 2459 the list of components signed is fixed in the signature, it is 2460 difficult but not impossible for an attacker to effect such a 2461 collision. An attacker would need to manipulate the HTTP message and 2462 its covered message components in order to make the collision 2463 effective. 2465 To counter this, only vetted keys and signature algorithms should be 2466 used to sign HTTP messages. The HTTP Message Signatures Algorithm 2467 Registry is one source of potential trusted algorithms. 2469 While it is possible for an attacker to substitute the signature 2470 parameters value or the signature value separately, the signature 2471 base generation algorithm (Section 2.3) always covers the signature 2472 parameters as the final value in the input string using a 2473 deterministic serialization method. This step strongly binds the 2474 signature base with the signature value in a way that makes it much 2475 more difficult for an attacker to perform a partial substitution on 2476 the signature bases. 2478 7.6. Key Theft 2480 A foundational assumption of signature-based cryptographic systems is 2481 that the signing key is not compromised by an attacker. If the keys 2482 used to sign the message are exfiltrated or stolen, the attacker will 2483 be able to generate their own signatures using those keys. As a 2484 consequence, signers have to protect any signing key material from 2485 exfiltration, capture, and use by an attacker. 2487 To combat this, signers can rotate keys over time to limit the amount 2488 of time stolen keys are useful. Signers can also use key escrow and 2489 storage systems to limit the attack surface against keys. 2490 Furthermore, the use of asymmetric signing algorithms exposes key 2491 material less than the use of symmetric signing algorithms 2492 (Section 7.11). 2494 7.7. Modification of Required Message Parameters 2496 An attacker could effectively deny a service by modifying an 2497 otherwise benign signature parameter or signed message component. 2498 While rejecting a modified message is the desired behavior, 2499 consistently failing signatures could lead to the verifier turning 2500 off signature checking in order to make systems work again (see 2501 Section 7.1). 2503 If such failures are common within an application, the signer and 2504 verifier should compare their generated signature bases with each 2505 other to determine which part of the message is being modified. 2506 However, the signer and verifier should not remove the requirement to 2507 sign the modified component when it is suspected an attacker is 2508 modifying the component. 2510 7.8. Mismatch of Signature Parameters from Message 2512 The verifier needs to make sure that the signed message components 2513 match those in the message itself. This specification encourages 2514 this by requiring the verifier to derive these values from the 2515 message, but lazy cacheing or conveyance of the signature base to a 2516 processing system could lead to downstream verifiers accepting a 2517 message that does not match the presented signature. 2519 7.9. Multiple Signature Confusion 2521 Since multiple signatures can be applied to one message 2522 (Section 4.3), it is possible for an attacker to attach their own 2523 signature to a captured message without modifying existing 2524 signatures. This new signature could be completely valid based on 2525 the attacker's key, or it could be an invalid signature for any 2526 number of reasons. Each of these situations need to be accounted 2527 for. 2529 A verifier processing a set of valid signatures needs to account for 2530 all of the signers, identified by the signing keys. Only signatures 2531 from expected signers should be accepted, regardless of the 2532 cryptographic validity of the signature itself. 2534 A verifier processing a set of signatures on a message also needs to 2535 determine what to do when one or more of the signatures are not 2536 valid. If a message is accepted when at least one signature is 2537 valid, then a verifier could drop all invalid signatures from the 2538 request before processing the message further. Alternatively, if the 2539 verifier rejects a message for a single invalid signature, an 2540 attacker could use this to deny service to otherwise valid messages 2541 by injecting invalid signatures alongside the valid ones. 2543 7.10. Signature Labels 2545 HTTP Message Signature values are identified in the Signature and 2546 Signature-Input field values by unique labels. These labels are 2547 chosen only when attaching the signature values to the message and 2548 are not accounted for in the signing process. An intermediary adding 2549 its own signature is allowed to re-label an existing signature when 2550 processing the message. 2552 Therefore, applications should not rely on specific labels being 2553 present, and applications should not put semantic meaning on the 2554 labels themselves. Instead, additional signature parmeters can be 2555 used to convey whatever additional meaning is required to be attached 2556 to and covered by the signature. 2558 7.11. Symmetric Cryptography 2560 The HTTP Message Signatures specification allows for both asymmetric 2561 and symmetric cryptography to be applied to HTTP messages. By its 2562 nature, symmetric cryptographic methods require the same key material 2563 to be known by both the signer and verifier. This effectively means 2564 that a verifier is capable of generating a valid signature, since 2565 they have access to the same key material. An attacker that is able 2566 to compromise a verifier would be able to then impersonate a signer. 2568 Where possible, asymmetric methods or secure key agreement mechanisms 2569 should be used in order to avoid this type of attack. When symmetric 2570 methods are used, distribution of the key material needs to be 2571 protected by the overall system. One technique for this is the use 2572 of separate cryptographic modules that separate the verification 2573 process (and therefore the key material) from other code, minimizing 2574 the vulnerable attack surface. Another technique is the use of key 2575 derivation functions that allow the signer and verifier to agree on 2576 unique keys for each message without having to share the key values 2577 directly. 2579 Additionally, if symmetric algorithms are allowed within a system, 2580 special care must be taken to avoid key downgrade attacks 2581 (Section 7.15). 2583 7.12. Canonicalization Attacks 2585 Any ambiguity in the generation of the signature base could provide 2586 an attacker with leverage to substitute or break a signature on a 2587 message. Some message component values, particularly HTTP field 2588 values, are potentially susceptible to broken implementations that 2589 could lead to unexpected and insecure behavior. Naive 2590 implementations of this specification might implement HTTP field 2591 processing by taking the single value of a field and using it as the 2592 direct component value without processing it appropriately. 2594 For example, if the handling of obs-fold field values does not remove 2595 the internal line folding and whitespace, additional newlines could 2596 be introduced into the signature base by the signer, providing a 2597 potential place for an attacker to mount a signature collision 2598 (Section 7.5) attack. Alternatively, if header fields that appear 2599 multiple times are not joined into a single string value, as is 2600 required by this specification, similar attacks can be mounted as a 2601 signed component value would show up in the input string more than 2602 once and could be substituted or otherwise attacked in this way. 2604 To counter this, the entire field processing algorithm needs to be 2605 implemented by all implementations of signers and verifiers. 2607 7.13. Key Specification Mix-Up 2609 The existence of a valid signature on an HTTP message is not 2610 sufficient to prove that the message has been signed by the 2611 appropriate party. It is up to the verifier to ensure that a given 2612 key and algorithm are appropriate for the message in question. If 2613 the verifier does not perform such a step, an attacker could 2614 substitute their own signature using their own key on a message and 2615 force a verifier to accept and process it. To combat this, the 2616 verifier needs to ensure that not only does the signature validate 2617 for a message, but that the key and algorithm used are appropriate. 2619 7.14. HTTP Versions and Component Ambiguity 2621 Some message components are expressed in different ways across HTTP 2622 versions. For example, the authority of the request target is sent 2623 using the Host header field in HTTP 1.1 but with the :authority 2624 pseudo-header in HTTP 2. If a signer sends an HTTP 1.1 message and 2625 signs the Host field, but the message is translated to HTTP 2 before 2626 it reaches the verifier, the signature will not validate as the Host 2627 header field could be dropped. 2629 It is for this reason that HTTP Message Signatures defines a set of 2630 derived components that define a single way to get value in question, 2631 such as the @authority derived component identifier (Section 2.2.4) 2632 in lieu of the Host header field. Applications should therefore 2633 prefer derived component identifiers for such options where possible. 2635 7.15. Key and Algorithm Specification Downgrades 2637 Applications of this specification need to protect against key 2638 specification downgrade attacks. For example, the same RSA key can 2639 be used for both RSA-PSS and RSA v1.5 signatures. If an application 2640 expects a key to only be used with RSA-PSS, it needs to reject 2641 signatures for that key using the weaker RSA 1.5 specification. 2643 Another example of a downgrade attack occurs when an asymmetric 2644 algorithm is expected, such as RSA-PSS, but an attacker substitutes a 2645 signature using symmetric algorithm, such as HMAC. A naive verifier 2646 implementation could use the value of the public RSA key as the input 2647 to the HMAC verification function. Since the public key is known to 2648 the attacker, this would allow the attacker to create a valid HMAC 2649 signature against this known key. To prevent this, the verifier 2650 needs to ensure that both the key material and the algorithm are 2651 appropriate for the usage in question. Additionally, while this 2652 specification does allow runtime specification of the algorithm using 2653 the alg signature parameter, applications are encouraged to use other 2654 mechanisms such as static configuration or higher protocol-level 2655 algorithm specification instead. 2657 7.16. Parsing Structured Field Values 2659 Several parts of this specification rely on the parsing of structured 2660 field values [RFC8941]. In particular, normalization of HTTP 2661 structured field values (Section 2.1.1), referencing members of a 2662 dictionary structured field (Section 2.1.2), and processing the 2663 @signature-input value when verifying a signature (Section 3.2). 2664 While structured field values are designed to be relatively simple to 2665 parse, a naive or broken implementation of such a parser could lead 2666 to subtle attack surfaces being exposed in the implementation. 2668 For example, if a buggy parser of the @signature-input value does not 2669 enforce proper closing of quotes around string values within the list 2670 of component identifiers, an attacker could take advantage of this 2671 and inject additional content into the signature base through 2672 manipulating the Signature-Input field value on a message. 2674 To counteract this, implementations should use fully compliant and 2675 trusted parsers for all structured field processing, both on the 2676 signer and verifier side. 2678 7.17. Choosing Message Components 2680 Applications of HTTP Message Signatures need to decide which message 2681 components will be covered by the signature. Depending on the 2682 application, some components could be expected to be changed by 2683 intermediaries prior to the signature's verification. If these 2684 components are covered, such changes would, by design, break the 2685 signature. 2687 However, the HTTP Message Signature standard allows for flexibility 2688 in determining which components are signed precisely so that a given 2689 application can choose the appropriate portions of the message that 2690 need to be signed, avoiding problematic components. For example, a 2691 web application framework that relies on rewriting query parameters 2692 might avoid use of the @query content identifier in favor of sub- 2693 indexing the query value using @query-params content identifier 2694 instead. 2696 Some components are expected to be changed by intermediaries and 2697 ought not to be signed under most circumstance. The Via and 2698 Forwarded header fields, for example, are expected to be manipulated 2699 by proxies and other middle-boxes, including replacing or entirely 2700 dropping existing values. These fields should not be covered by the 2701 signature except in very limited and tightly-coupled scenarios. 2703 Additional considerations for choosing signature aspects are 2704 discussed in Section 1.5. 2706 7.18. Confusing HTTP Field Names for Derived Component Identifiers 2708 The definition of HTTP field names does not allow for the use of the 2709 @ character anywhere in the name. As such, since all derived 2710 component identifiers start with the @ character, these namespaces 2711 should be completely separate. However, some HTTP implementations 2712 are not sufficiently strict about the characters accepted in HTTP 2713 headers. In such implementations, a sender (or attacker) could 2714 inject a header field starting with an @ character and have it passed 2715 through to the application code. These invalid header fields could 2716 be used to override a portion of the derived message content and 2717 substitute an arbitrary value, providing a potential place for an 2718 attacker to mount a signature collision (Section 7.5) attack. 2720 To combat this, when selecting values for a message component, if the 2721 component identifier starts with the @ character, it needs to be 2722 processed as a derived component and never taken as a fields. Only 2723 if the component identifier does not start with the @ character can 2724 it be taken from the fields of the message. The algorithm discussed 2725 in Section 2.3 provides a safe order of operations. 2727 7.19. Non-deterministic Signature Primitives 2729 Some cryptographic primitives such as RSA PSS and ECDSA have non- 2730 deterministic outputs, which include some amount of entropy within 2731 the algorithm. For such algorithms, multiple signatures generated in 2732 succession will not match. A lazy implementation of a verifier could 2733 ignore this distinction and simply check for the same value being 2734 created by re-signing the signature base. Such an implementation 2735 would work for deterministic algorithms such as HMAC and EdDSA but 2736 fail to verify valid signatures made using non-deterministic 2737 algorithms. It is therefore important that a verifier always use the 2738 correctly-defined verification function for the algorithm in question 2739 and not do a simple comparison. 2741 7.20. Choosing Signature Parameters and Derived Components over HTTP 2742 Fields 2744 Some HTTP fields have values and interpretations that are similar to 2745 HTTP signature parameters or derived components. In most cases, it 2746 is more desirable to sign the non-field alternative. In particular, 2747 the following fields should usually not be included in the signature 2748 unless the application specifically requires it: 2750 "date" The "date" field value represents the timestamp of the HTTP 2751 message. However, the creation time of the signature itself is 2752 encoded in the created signature parameter. These two values can 2753 be different, depending on how the signature and the HTTP message 2754 are created and serialized. Applications processing signatures 2755 for valid time windows should use the created signature parameter 2756 for such calculations. An application could also put limits on 2757 how much skew there is between the "date" field and the created 2758 signature parameter, in order to limit the application of a 2759 generated signature to different HTTP messages. See also 2760 Section 7.3 and Section 7.4. 2762 "host" The "host" header field is specific to HTTP 1.1, and its 2763 functionality is subsumed by the "@authority" derived component, 2764 defined in Section 2.2.4. In order to preserve the value across 2765 different HTTP versions, applications should always use the 2766 "@authority" derived component. 2768 7.21. Semantically Equivalent Field Values 2770 The signature base generation algorithm (Section 2.3) uses the value 2771 of an HTTP field as its component value. In the common case, this 2772 amounts to taking the actual bytes of the field value as the 2773 component value for both the signer and verifier. However, some 2774 field values allow for transformation of the values in semantically 2775 equivalent ways that alter the bytes used in the value itself. For 2776 example, a field definition can declare some or all of its value to 2777 be case-insensitive, or to have special handling of internal 2778 whitespace characters. Other fields have expected transformations 2779 from intermediaries, such as the removal of comments in the Via 2780 header field. In such cases, a verifier could be tripped up by using 2781 the equivalent transformed field value, which would differ from the 2782 byte value used by the signer. The verifier would have have a 2783 difficult time finding this class of errors since the value of the 2784 field is still acceptable for the application, but the actual bytes 2785 required by the signature base would not match. 2787 When processing such fields, the signer and verifier have to agree 2788 how to handle such transformations, if at all. One option is to not 2789 sign problematic fields, but care must be taken to ensure that there 2790 is still sufficient signature coverage (Section 7.4) for the 2791 application. Another option is to define an application-specific 2792 canonicalization value for the field before it is added to the HTTP 2793 message, such as to always remove internal comments before signing, 2794 or to always transform values to lowercase. Since these 2795 transformations are applied prior to the field being used as input to 2796 the signature base generation algorithm, the signature base will 2797 still simply contain the byte value of the field as it appears within 2798 the message. If the transformations were to be applied after the 2799 value is extracted from the message but before it is added to the 2800 signature base, different attack surfaces such as value substitution 2801 attacks could be launched against the application. All application- 2802 specific additional rules are outside the scope of this 2803 specification, and by their very nature these transformations would 2804 harm interoperability of the implementation outside of this specific 2805 application. It is recommended that applications avoid the use of 2806 such additional rules wherever possible. 2808 8. Privacy Considerations 2809 8.1. Identification through Keys 2811 If a signer uses the same key with multiple verifiers, or uses the 2812 same key over time with a single verifier, the ongoing use of that 2813 key can be used to track the signer throughout the set of verifiers 2814 that messages are sent to. Since cryptographic keys are meant to be 2815 functionally unique, the use of the same key over time is a strong 2816 indicator that it is the same party signing multiple messages. 2818 In many applications, this is a desirable trait, and it allows HTTP 2819 Message Signatures to be used as part of authenticating the signer to 2820 the verifier. However, unintentional tracking that a signer might 2821 not be aware of. To counter this kind of tracking, a signer can use 2822 a different key for each verifier that it is in communication with. 2823 Sometimes, a signer could also rotate their key when sending messages 2824 to a given verifier. These approaches do not negate the need for 2825 other anti-tracking techniques to be applied as necessary. 2827 8.2. Signatures do not provide confidentiality 2829 HTTP Message Signatures do not provide confidentiality of any of the 2830 information protected by the signature. The content of the HTTP 2831 message, including the value of all fields and the value of the 2832 signature itself, is presented in plaintext to any party with access 2833 to the message. 2835 To provide confidentiality at the transport level, TLS or its 2836 equivalent can be used as discussed in Section 7.2. 2838 8.3. Oracles 2840 It is important to balance the need for providing useful feedback to 2841 developers on error conditions without providing additional 2842 information to an attacker. For example, a naive but helpful server 2843 implementation might try to indicate the required key identifier 2844 needed for requesting a resource. If someone knows who controls that 2845 key, a correlation can be made between the resource's existence and 2846 the party identified by the key. Access to such information could be 2847 used by an attacker as a means to target the legitimate owner of the 2848 resource for further attacks. 2850 8.4. Required Content 2852 A core design tenet of this specification is that all message 2853 components covered by the signature need to be available to the 2854 verifier in order to recreate the signature base and verify the 2855 signature. As a consequence, if an application of this specification 2856 requires that a particular field be signed, the verifier will need 2857 access to the value of that field. 2859 For example, in some complex systems with intermediary processors 2860 this could cause the surprising behavior of an intermediary not being 2861 able to remove privacy-sensitive information from a message before 2862 forwarding it on for processing, for fear of breaking the signature. 2863 A possible mitigation for this specific situation would be for the 2864 intermediary to verify the signature itself, then modifying the 2865 message to remove the privacy-sensitive information. The 2866 intermediary can add its own signature at this point to signal to the 2867 next destination that the incoming signature was validated, as is 2868 shown in the example in Section 4.3. 2870 9. References 2872 9.1. Normative References 2874 [FIPS186-4] 2875 "Digital Signature Standard (DSS)", 2013, 2876 . 2879 [HTMLURL] "URL (Living Standard)", 2021, 2880 . 2882 [MESSAGING] 2883 Fielding, R. T., Nottingham, M., and J. Reschke, 2884 "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf- 2885 httpbis-messaging-19, 12 September 2021, 2886 . 2889 [POSIX.1] "The Open Group Base Specifications Issue 7, 2018 2890 edition", 2018, 2891 . 2893 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2894 Hashing for Message Authentication", RFC 2104, 2895 DOI 10.17487/RFC2104, February 1997, 2896 . 2898 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2899 Requirement Levels", BCP 14, RFC 2119, 2900 DOI 10.17487/RFC2119, March 1997, 2901 . 2903 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2904 Resource Identifier (URI): Generic Syntax", STD 66, 2905 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2906 . 2908 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 2909 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 2910 DOI 10.17487/RFC6234, May 2011, 2911 . 2913 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 2914 DOI 10.17487/RFC7517, May 2015, 2915 . 2917 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 2918 DOI 10.17487/RFC7518, May 2015, 2919 . 2921 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 2922 "PKCS #1: RSA Cryptography Specifications Version 2.2", 2923 RFC 8017, DOI 10.17487/RFC8017, November 2016, 2924 . 2926 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 2927 Signature Algorithm (EdDSA)", RFC 8032, 2928 DOI 10.17487/RFC8032, January 2017, 2929 . 2931 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2932 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2933 May 2017, . 2935 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 2936 "Handling Long Lines in Content of Internet-Drafts and 2937 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 2938 . 2940 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 2941 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 2942 . 2944 [SEMANTICS] 2945 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 2946 Semantics", Work in Progress, Internet-Draft, draft-ietf- 2947 httpbis-semantics-19, 12 September 2021, 2948 . 2951 9.2. Informative References 2953 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 2954 "Recommendations for Secure Use of Transport Layer 2955 Security (TLS) and Datagram Transport Layer Security 2956 (DTLS)", BCP 195, RFC 7525, May 2015. 2958 Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS 2959 1.1", BCP 195, RFC 8996, March 2021. 2961 2963 [I-D.ietf-httpbis-client-cert-field] 2964 Campbell, B. and M. Bishop, "Client-Cert HTTP Header 2965 Field", Work in Progress, Internet-Draft, draft-ietf- 2966 httpbis-client-cert-field-01, 25 January 2022, 2967 . 2970 [RFC7239] Petersson, A. and M. Nilsson, "Forwarded HTTP Extension", 2971 RFC 7239, DOI 10.17487/RFC7239, June 2014, 2972 . 2974 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2975 Writing an IANA Considerations Section in RFCs", BCP 26, 2976 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2977 . 2979 [TLS] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2980 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2981 . 2983 Appendix A. Detecting HTTP Message Signatures 2985 There have been many attempts to create signed HTTP messages in the 2986 past, including other non-standardized definitions of the Signature 2987 field, which is used within this specification. It is recommended 2988 that developers wishing to support both this specification and other 2989 historical drafts do so carefully and deliberately, as 2990 incompatibilities between this specification and various versions of 2991 other drafts could lead to unexpected problems. 2993 It is recommended that implementers first detect and validate the 2994 Signature-Input field defined in this specification to detect that 2995 this standard is in use and not an alternative. If the Signature- 2996 Input field is present, all Signature fields can be parsed and 2997 interpreted in the context of this draft. 2999 Appendix B. Examples 3001 The following non-normative examples are provided as a means of 3002 testing implementations of HTTP Message Signatures. The signed 3003 messages given can be used to create the signature base with the 3004 stated parameters, creating signatures using the stated algorithms 3005 and keys. 3007 The private keys given can be used to generate signatures, though 3008 since several of the demonstrated algorithms are nondeterministic, 3009 the results of a signature are expected to be different from the 3010 exact bytes of the examples. The public keys given can be used to 3011 validate all signed examples. 3013 B.1. Example Keys 3015 This section provides cryptographic keys that are referenced in 3016 example signatures throughout this document. These keys MUST NOT be 3017 used for any purpose other than testing. 3019 The key identifiers for each key are used throughout the examples in 3020 this specification. It is assumed for these examples that the signer 3021 and verifier can unambiguously dereference all key identifiers used 3022 here, and that the keys and algorithms used are appropriate for the 3023 context in which the signature is presented. 3025 The components for each private key in PEM format can be displayed by 3026 executing the following OpenSSL command: 3028 openssl pkey -text 3030 This command was tested with all the example keys on OpenSSL version 3031 1.1.1m. Note that some systems cannot produce or use these keys 3032 directly, and may require additional processing. 3034 B.1.1. Example Key RSA test 3036 The following key is a 2048-bit RSA public and private key pair, 3037 referred to in this document as test-key-rsa. This key is encoded in 3038 PEM Format, with no encryption. 3040 -----BEGIN RSA PUBLIC KEY----- 3041 MIIBCgKCAQEAhAKYdtoeoy8zcAcR874L8cnZxKzAGwd7v36APp7Pv6Q2jdsPBRrw 3042 WEBnez6d0UDKDwGbc6nxfEXAy5mbhgajzrw3MOEt8uA5txSKobBpKDeBLOsdJKFq 3043 MGmXCQvEG7YemcxDTRPxAleIAgYYRjTSd/QBwVW9OwNFhekro3RtlinV0a75jfZg 3044 kne/YiktSvLG34lw2zqXBDTC5NHROUqGTlML4PlNZS5Ri2U4aCNx2rUPRcKIlE0P 3045 uKxI4T+HIaFpv8+rdV6eUgOrB2xeI1dSFFn/nnv5OoZJEIB+VmuKn3DCUcCZSFlQ 3046 PSXSfBDiUGhwOw76WuSSsf1D4b/vLoJ10wIDAQAB 3047 -----END RSA PUBLIC KEY----- 3049 -----BEGIN RSA PRIVATE KEY----- 3050 MIIEqAIBAAKCAQEAhAKYdtoeoy8zcAcR874L8cnZxKzAGwd7v36APp7Pv6Q2jdsP 3051 BRrwWEBnez6d0UDKDwGbc6nxfEXAy5mbhgajzrw3MOEt8uA5txSKobBpKDeBLOsd 3052 JKFqMGmXCQvEG7YemcxDTRPxAleIAgYYRjTSd/QBwVW9OwNFhekro3RtlinV0a75 3053 jfZgkne/YiktSvLG34lw2zqXBDTC5NHROUqGTlML4PlNZS5Ri2U4aCNx2rUPRcKI 3054 lE0PuKxI4T+HIaFpv8+rdV6eUgOrB2xeI1dSFFn/nnv5OoZJEIB+VmuKn3DCUcCZ 3055 SFlQPSXSfBDiUGhwOw76WuSSsf1D4b/vLoJ10wIDAQABAoIBAG/JZuSWdoVHbi56 3056 vjgCgkjg3lkO1KrO3nrdm6nrgA9P9qaPjxuKoWaKO1cBQlE1pSWp/cKncYgD5WxE 3057 CpAnRUXG2pG4zdkzCYzAh1i+c34L6oZoHsirK6oNcEnHveydfzJL5934egm6p8DW 3058 +m1RQ70yUt4uRc0YSor+q1LGJvGQHReF0WmJBZHrhz5e63Pq7lE0gIwuBqL8SMaA 3059 yRXtK+JGxZpImTq+NHvEWWCu09SCq0r838ceQI55SvzmTkwqtC+8AT2zFviMZkKR 3060 Qo6SPsrqItxZWRty2izawTF0Bf5S2VAx7O+6t3wBsQ1sLptoSgX3QblELY5asI0J 3061 YFz7LJECgYkAsqeUJmqXE3LP8tYoIjMIAKiTm9o6psPlc8CrLI9CH0UbuaA2JCOM 3062 cCNq8SyYbTqgnWlB9ZfcAm/cFpA8tYci9m5vYK8HNxQr+8FS3Qo8N9RJ8d0U5Csw 3063 DzMYfRghAfUGwmlWj5hp1pQzAuhwbOXFtxKHVsMPhz1IBtF9Y8jvgqgYHLbmyiu1 3064 mwJ5AL0pYF0G7x81prlARURwHo0Yf52kEw1dxpx+JXER7hQRWQki5/NsUEtv+8RT 3065 qn2m6qte5DXLyn83b1qRscSdnCCwKtKWUug5q2ZbwVOCJCtmRwmnP131lWRYfj67 3066 B/xJ1ZA6X3GEf4sNReNAtaucPEelgR2nsN0gKQKBiGoqHWbK1qYvBxX2X3kbPDkv 3067 9C+celgZd2PW7aGYLCHq7nPbmfDV0yHcWjOhXZ8jRMjmANVR/eLQ2EfsRLdW69bn 3068 f3ZD7JS1fwGnO3exGmHO3HZG+6AvberKYVYNHahNFEw5TsAcQWDLRpkGybBcxqZo 3069 81YCqlqidwfeO5YtlO7etx1xLyqa2NsCeG9A86UjG+aeNnXEIDk1PDK+EuiThIUa 3070 /2IxKzJKWl1BKr2d4xAfR0ZnEYuRrbeDQYgTImOlfW6/GuYIxKYgEKCFHFqJATAG 3071 IxHrq1PDOiSwXd2GmVVYyEmhZnbcp8CxaEMQoevxAta0ssMK3w6UsDtvUvYvF22m 3072 qQKBiD5GwESzsFPy3Ga0MvZpn3D6EJQLgsnrtUPZx+z2Ep2x0xc5orneB5fGyF1P 3073 WtP+fG5Q6Dpdz3LRfm+KwBCWFKQjg7uTxcjerhBWEYPmEMKYwTJF5PBG9/ddvHLQ 3074 EQeNC8fHGg4UXU8mhHnSBt3EA10qQJfRDs15M38eG2cYwB1PZpDHScDnDA0= 3075 -----END RSA PRIVATE KEY----- 3077 B.1.2. Example RSA PSS Key 3079 The following key is a 2048-bit RSA public and private key pair, 3080 referred to in this document as test-key-rsa-pss. This key is PCKS#8 3081 encoded in PEM format, with no encryption. 3083 -----BEGIN PUBLIC KEY----- 3084 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr4tmm3r20Wd/PbqvP1s2 3085 +QEtvpuRaV8Yq40gjUR8y2Rjxa6dpG2GXHbPfvMs8ct+Lh1GH45x28Rw3Ry53mm+ 3086 oAXjyQ86OnDkZ5N8lYbggD4O3w6M6pAvLkhk95AndTrifbIFPNU8PPMO7OyrFAHq 3087 gDsznjPFmTOtCEcN2Z1FpWgchwuYLPL+Wokqltd11nqqzi+bJ9cvSKADYdUAAN5W 3088 Utzdpiy6LbTgSxP7ociU4Tn0g5I6aDZJ7A8Lzo0KSyZYoA485mqcO0GVAdVw9lq4 3089 aOT9v6d+nb4bnNkQVklLQ3fVAvJm+xdDOp9LCNCN48V2pnDOkFV6+U9nV5oyc6XI 3090 2wIDAQAB 3091 -----END PUBLIC KEY----- 3093 -----BEGIN PRIVATE KEY----- 3094 MIIEvgIBADALBgkqhkiG9w0BAQoEggSqMIIEpgIBAAKCAQEAr4tmm3r20Wd/Pbqv 3095 P1s2+QEtvpuRaV8Yq40gjUR8y2Rjxa6dpG2GXHbPfvMs8ct+Lh1GH45x28Rw3Ry5 3096 3mm+oAXjyQ86OnDkZ5N8lYbggD4O3w6M6pAvLkhk95AndTrifbIFPNU8PPMO7Oyr 3097 FAHqgDsznjPFmTOtCEcN2Z1FpWgchwuYLPL+Wokqltd11nqqzi+bJ9cvSKADYdUA 3098 AN5WUtzdpiy6LbTgSxP7ociU4Tn0g5I6aDZJ7A8Lzo0KSyZYoA485mqcO0GVAdVw 3099 9lq4aOT9v6d+nb4bnNkQVklLQ3fVAvJm+xdDOp9LCNCN48V2pnDOkFV6+U9nV5oy 3100 c6XI2wIDAQABAoIBAQCUB8ip+kJiiZVKF8AqfB/aUP0jTAqOQewK1kKJ/iQCXBCq 3101 pbo360gvdt05H5VZ/RDVkEgO2k73VSsbulqezKs8RFs2tEmU+JgTI9MeQJPWcP6X 3102 aKy6LIYs0E2cWgp8GADgoBs8llBq0UhX0KffglIeek3n7Z6Gt4YFge2TAcW2WbN4 3103 XfK7lupFyo6HHyWRiYHMMARQXLJeOSdTn5aMBP0PO4bQyk5ORxTUSeOciPJUFktQ 3104 HkvGbym7KryEfwH8Tks0L7WhzyP60PL3xS9FNOJi9m+zztwYIXGDQuKM2GDsITeD 3105 2mI2oHoPMyAD0wdI7BwSVW18p1h+jgfc4dlexKYRAoGBAOVfuiEiOchGghV5vn5N 3106 RDNscAFnpHj1QgMr6/UG05RTgmcLfVsI1I4bSkbrIuVKviGGf7atlkROALOG/xRx 3107 DLadgBEeNyHL5lz6ihQaFJLVQ0u3U4SB67J0YtVO3R6lXcIjBDHuY8SjYJ7Ci6Z6 3108 vuDcoaEujnlrtUhaMxvSfcUJAoGBAMPsCHXte1uWNAqYad2WdLjPDlKtQJK1diCm 3109 rqmB2g8QE99hDOHItjDBEdpyFBKOIP+NpVtM2KLhRajjcL9Ph8jrID6XUqikQuVi 3110 4J9FV2m42jXMuioTT13idAILanYg8D3idvy/3isDVkON0X3UAVKrgMEne0hJpkPL 3111 FYqgetvDAoGBAKLQ6JZMbSe0pPIJkSamQhsehgL5Rs51iX4m1z7+sYFAJfhvN3Q/ 3112 OGIHDRp6HjMUcxHpHw7U+S1TETxePwKLnLKj6hw8jnX2/nZRgWHzgVcY+sPsReRx 3113 NJVf+Cfh6yOtznfX00p+JWOXdSY8glSSHJwRAMog+hFGW1AYdt7w80XBAoGBAImR 3114 NUugqapgaEA8TrFxkJmngXYaAqpA0iYRA7kv3S4QavPBUGtFJHBNULzitydkNtVZ 3115 3w6hgce0h9YThTo/nKc+OZDZbgfN9s7cQ75x0PQCAO4fx2P91Q+mDzDUVTeG30mE 3116 t2m3S0dGe47JiJxifV9P3wNBNrZGSIF3mrORBVNDAoGBAI0QKn2Iv7Sgo4T/XjND 3117 dl2kZTXqGAk8dOhpUiw/HdM3OGWbhHj2NdCzBliOmPyQtAr770GITWvbAI+IRYyF 3118 S7Fnk6ZVVVHsxjtaHy1uJGFlaZzKR4AGNaUTOJMs6NadzCmGPAxNQQOCqoUjn4XR 3119 rOjr9w349JooGXhOxbu8nOxX 3120 -----END PRIVATE KEY----- 3122 B.1.3. Example ECC P-256 Test Key 3124 The following key is a public and private elliptical curve key pair 3125 over the curve P-256, referred to in this document as `test-key-ecc- 3126 p256. This key is encoded in PEM format, with no encryption. 3128 -----BEGIN PUBLIC KEY----- 3129 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqIVYZVLCrPZHGHjP17CTW0/+D9Lf 3130 w0EkjqF7xB4FivAxzic30tMM4GF+hR6Dxh71Z50VGGdldkkDXZCnTNnoXQ== 3131 -----END PUBLIC KEY----- 3133 -----BEGIN EC PRIVATE KEY----- 3134 MHcCAQEEIFKbhfNZfpDsW43+0+JjUr9K+bTeuxopu653+hBaXGA7oAoGCCqGSM49 3135 AwEHoUQDQgAEqIVYZVLCrPZHGHjP17CTW0/+D9Lfw0EkjqF7xB4FivAxzic30tMM 3136 4GF+hR6Dxh71Z50VGGdldkkDXZCnTNnoXQ== 3137 -----END EC PRIVATE KEY----- 3139 B.1.4. Example Ed25519 Test Key 3141 The following key is an elliptical curve key over the Edwards curve 3142 ed25519, referred to in this document as test-key-ed25519. This key 3143 is PCKS#8 encoded in PEM format, with no encryption. 3145 -----BEGIN PUBLIC KEY----- 3146 MCowBQYDK2VwAyEAJrQLj5P/89iXES9+vFgrIy29clF9CC/oPPsw3c5D0bs= 3147 -----END PUBLIC KEY----- 3149 -----BEGIN PRIVATE KEY----- 3150 MC4CAQAwBQYDK2VwBCIEIJ+DYvh6SEqVTm50DFtMDoQikTmiCqirVv9mWG9qfSnF 3151 -----END PRIVATE KEY----- 3153 B.1.5. Example Shared Secret 3155 The following shared secret is 64 randomly-generated bytes encoded in 3156 Base64, referred to in this document as test-shared-secret. 3158 NOTE: '\' line wrapping per RFC 8792 3160 uzvJfB4u3N0Jy4T7NZ75MDVcr8zSTInedJtkgcu46YW4XByzNJjxBdtjUkdJPBt\ 3161 bmHhIDi6pcl8jsasjlTMtDQ== 3163 B.2. Test Cases 3165 This section provides non-normative examples that may be used as test 3166 cases to validate implementation correctness. These examples are 3167 based on the following HTTP messages: 3169 For requests, this test-request message is used: 3171 POST /foo?param=Value&Pet=dog HTTP/1.1 3172 Host: example.com 3173 Date: Tue, 20 Apr 2021 02:07:55 GMT 3174 Content-Type: application/json 3175 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 3176 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 3177 Content-Length: 18 3179 {"hello": "world"} 3181 For responses, this test-response message is used: 3183 HTTP/1.1 200 OK 3184 Date: Tue, 20 Apr 2021 02:07:56 GMT 3185 Content-Type: application/json 3186 Content-Digest: sha-512=:JlEy2bfUz7WrWIjc1qV6KVLpdr/7L5/L4h7Sxvh6sN\ 3187 HpDQWDCL+GauFQWcZBvVDhiyOnAQsxzZFYwi0wDH+1pw==: 3188 Content-Length: 23 3190 {"message": "good dog"} 3192 B.2.1. Minimal Signature Using rsa-pss-sha512 3194 This example presents a minimal signature using the rsa-pss-sha512 3195 algorithm over test-request, covering none of the components of the 3196 HTTP message, but providing a timestamped signature proof of 3197 possession of the key with a signer-provided nonce. 3199 The corresponding signature base is: 3201 NOTE: '\' line wrapping per RFC 8792 3203 "@signature-params": ();created=1618884473;keyid="test-key-rsa-pss"\ 3204 ;nonce="b3k2pp5k7z-50gnwp.yemd" 3206 This results in the following Signature-Input and Signature headers 3207 being added to the message under the signature label sig-b21: 3209 NOTE: '\' line wrapping per RFC 8792 3211 Signature-Input: sig-b21=();created=1618884473\ 3212 ;keyid="test-key-rsa-pss";nonce="b3k2pp5k7z-50gnwp.yemd" 3213 Signature: sig-b21=:d2pmTvmbncD3xQm8E9ZV2828BjQWGgiwAaw5bAkgibUopem\ 3214 LJcWDy/lkbbHAve4cRAtx31Iq786U7it++wgGxbtRxf8Udx7zFZsckzXaJMkA7ChG\ 3215 52eSkFxykJeNqsrWH5S+oxNFlD4dzVuwe8DhTSja8xxbR/Z2cOGdCbzR72rgFWhzx\ 3216 2VjBqJzsPLMIQKhO4DGezXehhWwE56YCE+O6c0mKZsfxVrogUvA4HELjVKWmAvtl6\ 3217 UnCh8jYzuVG5WSb/QEVPnP5TmcAnLH1g+s++v6d4s8m0gCw1fV5/SITLq9mhho8K3\ 3218 +7EPYTU8IU1bLhdxO5Nyt8C8ssinQ98Xw9Q==: 3220 Note that since the covered components list is empty, this signature 3221 could be applied by an attacker to an unrelated HTTP message. In 3222 this example, the nonce parameter is included to prevent the same 3223 signature from being replayed more than once, but if an attacker 3224 intercepts the signature and prevents its delivery to the verifier, 3225 the attacker could apply this signature to another message. 3226 Therefore, use of an empty covered components set is discouraged. 3227 See Section 7.4 for more discussion. 3229 Note that the RSA PSS algorithm in use here is non-deterministic, 3230 meaning a different signature value will be created every time the 3231 algorithm is run. The signature value provided here can be validated 3232 against the given keys, but newly-generated signature values are not 3233 expected to match the example. See Section 7.19. 3235 B.2.2. Selective Covered Components using rsa-pss-sha512 3237 This example covers additional components in test-request using the 3238 rsa-pss-sha512 algorithm. 3240 The corresponding signature base is: 3242 NOTE: '\' line wrapping per RFC 8792 3244 "@authority": example.com 3245 "content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\ 3246 +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 3247 "@signature-params": ("@authority" "content-digest")\ 3248 ;created=1618884473;keyid="test-key-rsa-pss" 3250 This results in the following Signature-Input and Signature headers 3251 being added to the message under the label sig-b22: 3253 NOTE: '\' line wrapping per RFC 8792 3255 Signature-Input: sig-b22=("@authority" "content-digest")\ 3256 ;created=1618884473;keyid="test-key-rsa-pss" 3257 Signature: sig-b22=:Fee1uy9YGZq5UUwwYU6vz4dZNvfw3GYrFl1L6YlVIyUMuWs\ 3258 wWDNSvql4dVtSeidYjYZUm7SBCENIb5KYy2ByoC3bI+7gydd2i4OAT5lyDtmeapnA\ 3259 a8uP/b9xUpg+VSPElbBs6JWBIQsd+nMdHDe+ls/IwVMwXktC37SqsnbNyhNp6kcvc\ 3260 WpevjzFcD2VqdZleUz4jN7P+W5A3wHiMGfIjIWn36KXNB+RKyrlGnIS8yaBBrom5r\ 3261 cZWLrLbtg6VlrH1+/07RV+kgTh/l10h8qgpl9zQHu7mWbDKTq0tJ8K4ywcPoC4s2I\ 3262 4rU88jzDKDGdTTQFZoTVZxZmuTM1FvHfzIw==: 3264 Note that the RSA PSS algorithm in use here is non-deterministic, 3265 meaning a different signature value will be created every time the 3266 algorithm is run. The signature value provided here can be validated 3267 against the given keys, but newly-generated signature values are not 3268 expected to match the example. See Section 7.19. 3270 B.2.3. Full Coverage using rsa-pss-sha512 3272 This example covers all applicable in test-request (including the 3273 content type and length) plus many derived components, again using 3274 the rsa-pss-sha512 algorithm. Note that the Host header field is not 3275 covered because the @authority derived component is included instead. 3277 The corresponding signature base is: 3279 NOTE: '\' line wrapping per RFC 8792 3281 "date": Tue, 20 Apr 2021 02:07:55 GMT 3282 "@method": POST 3283 "@path": /foo 3284 "@query": ?param=Value&Pet=dog 3285 "@authority": example.com 3286 "content-type": application/json 3287 "content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\ 3288 +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 3289 "content-length": 18 3290 "@signature-params": ("date" "@method" "@path" "@query" \ 3291 "@authority" "content-type" "content-digest" "content-length")\ 3292 ;created=1618884473;keyid="test-key-rsa-pss" 3294 This results in the following Signature-Input and Signature headers 3295 being added to the message under the label sig-b23: 3297 NOTE: '\' line wrapping per RFC 8792 3299 Signature-Input: sig-b23=("date" "@method" "@path" "@query" \ 3300 "@authority" "content-type" "content-digest" "content-length")\ 3301 ;created=1618884473;keyid="test-key-rsa-pss" 3302 Signature: sig-b23=:bbN8oArOxYoyylQQUU6QYwrTuaxLwjAC9fbY2F6SVWvh0yB\ 3303 iMIRGOnMYwZ/5MR6fb0Kh1rIRASVxFkeGt683+qRpRRU5p2voTp768ZrCUb38K0fU\ 3304 xN0O0iC59DzYx8DFll5GmydPxSmme9v6ULbMFkl+V5B1TP/yPViV7KsLNmvKiLJH1\ 3305 pFkh/aYA2HXXZzNBXmIkoQoLd7YfW91kE9o/CCoC1xMy7JA1ipwvKvfrs65ldmlu9\ 3306 bpG6A9BmzhuzF8Eim5f8ui9eH8LZH896+QIF61ka39VBrohr9iyMUJpvRX2Zbhl5Z\ 3307 JzSRxpJyoEZAFL2FUo5fTIztsDZKEgM4cUA==: 3309 Note in this example that the value of the Date header and the value 3310 of the created signature parameter need not be the same. This is due 3311 to the fact that the Date header is added when creating the HTTP 3312 Message and the created parameter is populated when creating the 3313 signature over that message, and these two times could vary. If the 3314 Date header is covered by the signature, it is up to the verifier to 3315 determine whether its value has to match that of the created 3316 parameter or not. See Section 7.20 for more discussion. 3318 Note that the RSA PSS algorithm in use here is non-deterministic, 3319 meaning a different signature value will be created every time the 3320 algorithm is run. The signature value provided here can be validated 3321 against the given keys, but newly-generated signature values are not 3322 expected to match the example. See Section 7.19. 3324 B.2.4. Signing a Response using ecdsa-p256-sha256 3326 This example covers portions of the test-response response message 3327 using the ecdsa-p256-sha256 algorithm and the key test-key-ecc-p256. 3329 The corresponding signature base is: 3331 NOTE: '\' line wrapping per RFC 8792 3333 "@status": 200 3334 "content-type": application/json 3335 "content-digest": sha-512=:JlEy2bfUz7WrWIjc1qV6KVLpdr/7L5/L4h7Sxvh6\ 3336 sNHpDQWDCL+GauFQWcZBvVDhiyOnAQsxzZFYwi0wDH+1pw==: 3337 "content-length": 23 3338 "@signature-params": ("@status" "content-type" "content-digest" \ 3339 "content-length");created=1618884473;keyid="test-key-ecc-p256" 3341 This results in the following Signature-Input and Signature headers 3342 being added to the message under the label sig-b24: 3344 NOTE: '\' line wrapping per RFC 8792 3346 Signature-Input: sig-b24=("@status" "content-type" \ 3347 "content-digest" "content-length");created=1618884473\ 3348 ;keyid="test-key-ecc-p256" 3349 Signature: sig-b24=:0Ry6HsvzS5VmA6HlfBYS/fYYeNs7fYuA7s0tAdxfUlPGv0C\ 3350 SVuwrrzBOjcCFHTxVRJ01wjvSzM2BetJauj8dsw==: 3352 Note that the ECDSA algorithm in use here is non-deterministic, 3353 meaning a different signature value will be created every time the 3354 algorithm is run. The signature value provided here can be validated 3355 against the given keys, but newly-generated signature values are not 3356 expected to match the example. See Section 7.19. 3358 B.2.5. Signing a Request using hmac-sha256 3360 This example covers portions of the test-request using the hmac- 3361 sha256 algorithm and the secret test-shared-secret. 3363 The corresponding signature base is: 3365 NOTE: '\' line wrapping per RFC 8792 3367 "date": Tue, 20 Apr 2021 02:07:55 GMT 3368 "@authority": example.com 3369 "content-type": application/json 3370 "@signature-params": ("date" "@authority" "content-type")\ 3371 ;created=1618884473;keyid="test-shared-secret" 3373 This results in the following Signature-Input and Signature headers 3374 being added to the message under the label sig-b25: 3376 NOTE: '\' line wrapping per RFC 8792 3378 Signature-Input: sig-b25=("date" "@authority" "content-type")\ 3379 ;created=1618884473;keyid="test-shared-secret" 3380 Signature: sig-b25=:pxcQw6G3AjtMBQjwo8XzkZf/bws5LelbaMk5rGIGtE8=: 3382 Before using symmetric signatures in practice, see the discussion of 3383 the security tradeoffs in Section 7.11. 3385 B.2.6. Signing a Request using ed25519 3387 This example covers portions of the test-request using the ed25519 3388 algorithm and the key test-key-ed25519. 3390 The corresponding signature base is: 3392 NOTE: '\' line wrapping per RFC 8792 3394 "date": Tue, 20 Apr 2021 02:07:55 GMT 3395 "@method": POST 3396 "@path": /foo 3397 "@authority": example.com 3398 "content-type": application/json 3399 "content-length": 18 3400 "@signature-params": ("date" "@method" "@path" "@authority" \ 3401 "content-type" "content-length");created=1618884473\ 3402 ;keyid="test-key-ed25519" 3404 This results in the following Signature-Input and Signature headers 3405 being added to the message under the label sig-b26: 3407 NOTE: '\' line wrapping per RFC 8792 3409 Signature-Input: sig-b26=("date" "@method" "@path" "@authority" \ 3410 "content-type" "content-length");created=1618884473\ 3411 ;keyid="test-key-ed25519" 3412 Signature: sig-b26=:wqcAqbmYJ2ji2glfAMaRy4gruYYnx2nEFN2HN6jrnDnQCK1\ 3413 u02Gb04v9EDgwUPiu4A0w6vuQv5lIp5WPpBKRCw==: 3415 B.3. TLS-Terminating Proxies 3417 In this example, there is a TLS-terminating reverse proxy sitting in 3418 front of the resource. The client does not sign the request but 3419 instead uses mutual TLS to make its call. The terminating proxy 3420 validates the TLS stream and injects a Client-Cert header according 3421 to [I-D.ietf-httpbis-client-cert-field], and then applies a signature 3422 to this field. By signing this header field, a reverse proxy can not 3423 only attest to its own validation of the initial request's TLS 3424 parameters but also authenticate itself to the backend system 3425 independently of the client's actions. 3427 The client makes the following request to the TLS terminating proxy 3428 using mutual TLS: 3430 POST /foo?param=Value&Pet=dog HTTP/1.1 3431 Host: example.com 3432 Date: Tue, 20 Apr 2021 02:07:55 GMT 3433 Content-Type: application/json 3434 Content-Length: 18 3436 {"hello": "world"} 3438 The proxy processes the TLS connection and extracts the client's TLS 3439 certificate to a Client-Cert header field and passes it along to the 3440 internal service hosted at service.internal.example. This results in 3441 the following unsigned request: 3443 NOTE: '\' line wrapping per RFC 8792 3445 POST /foo?param=Value&Pet=dog HTTP/1.1 3446 Host: service.internal.example 3447 Date: Tue, 20 Apr 2021 02:07:55 GMT 3448 Content-Type: application/json 3449 Content-Length: 18 3450 Client-Cert: :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQKD\ 3451 BJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBDQT\ 3452 AeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDMFk\ 3453 wEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXmck\ 3454 C8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQYDV\ 3455 R0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8BAf\ 3456 8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQGV\ 3457 4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0Q6\ 3458 bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: 3460 {"hello": "world"} 3462 Without a signature, the internal service would need to trust that 3463 the incoming connection has the right information. By signing the 3464 Client-Cert header and other portions of the internal request, the 3465 internal service can be assured that the correct party, the trusted 3466 proxy, has processed the request and presented it to the correct 3467 service. The proxy's signature base consists of the following: 3469 NOTE: '\' line wrapping per RFC 8792 3471 "@path": /foo 3472 "@query": ?param=Value&Pet=dog 3473 "@method": POST 3474 "@authority": service.internal.example 3475 "client-cert": :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQ\ 3476 KDBJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBD\ 3477 QTAeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDM\ 3478 FkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXm\ 3479 ckC8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQY\ 3480 DVR0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8B\ 3481 Af8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQ\ 3482 GV4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0\ 3483 Q6bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: 3484 "@signature-params": ("@path" "@query" "@method" "@authority" \ 3485 "client-cert");created=1618884473;keyid="test-key-ecc-p256" 3487 This results in the following signature: 3489 NOTE: '\' line wrapping per RFC 8792 3491 xVMHVpawaAC/0SbHrKRs9i8I3eOs5RtTMGCWXm/9nvZzoHsIg6Mce9315T6xoklyy0y\ 3492 zhD9ah4JHRwMLOgmizw== 3494 Which results in the following signed request sent from the proxy to 3495 the internal service with the proxy's signature under the label ttrp: 3497 NOTE: '\' line wrapping per RFC 8792 3499 POST /foo?param=Value&Pet=dog HTTP/1.1 3500 Host: service.internal.example 3501 Date: Tue, 20 Apr 2021 02:07:55 GMT 3502 Content-Type: application/json 3503 Content-Length: 18 3504 Client-Cert: :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQKD\ 3505 BJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBDQT\ 3506 AeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDMFk\ 3507 wEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXmck\ 3508 C8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQYDV\ 3509 R0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8BAf\ 3510 8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQGV\ 3511 4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0Q6\ 3512 bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: 3513 Signature-Input: ttrp=("@path" "@query" "@method" "@authority" \ 3514 "client-cert");created=1618884473;keyid="test-key-ecc-p256" 3515 Signature: ttrp=:xVMHVpawaAC/0SbHrKRs9i8I3eOs5RtTMGCWXm/9nvZzoHsIg6\ 3516 Mce9315T6xoklyy0yzhD9ah4JHRwMLOgmizw==: 3518 {"hello": "world"} 3520 The internal service can validate the proxy's signature and therefore 3521 be able to trust that the client's certificate has been appropriately 3522 processed. 3524 Acknowledgements 3526 This specification was initially based on the draft-cavage-http- 3527 signatures internet draft. The editors would like to thank the 3528 authors of that draft, Mark Cavage and Manu Sporny, for their work on 3529 that draft and their continuing contributions. The specification 3530 also includes contributions from the draft-oauth-signed-http-request 3531 internet draft and other similar efforts. 3533 The editors would also like to thank the following individuals for 3534 feedback, insight, and implementation of this draft and its 3535 predecessors (in alphabetical order): Mark Adamcin, Mark Allen, Paul 3536 Annesley, Karl Böhlmark, Stéphane Bortzmeyer, Sarven Capadisli, Liam 3537 Dennehy, Stephen Farrell, Phillip Hallam-Baker, Eric Holmes, Andrey 3538 Kislyuk, Adam Knight, Dave Lehn, Dave Longley, Ilari Liusvaara, James 3539 H. Manger, Kathleen Moriarty, Mark Nottingham, Yoav Nir, Adrian 3540 Palmer, Lucas Pardue, Roberto Polli, Julian Reschke, Michael 3541 Richardson, Wojciech Rygielski, Rich Salz, Adam Scarr, Cory J. Slep, 3542 Dirk Stein, Henry Story, Lukasz Szewc, Chris Webber, and Jeffrey 3543 Yasskin. 3545 Document History 3547 _RFC EDITOR: please remove this section before publication_ 3549 * draft-ietf-httpbis-message-signatures 3551 - -09 3553 o Explained key formats better. 3555 o Removed "host" and "date" from most examples. 3557 o Fixed query component generation. 3559 o Renamed "signature input" and "signature input string" to 3560 "signature base". 3562 o Added consideration for semantically equivalent field 3563 values. 3565 - -08 3567 o Editorial fixes. 3569 o Changed "specialty component" to "derived component". 3571 o Expanded signature input generation and ABNF rules. 3573 o Added Ed25519 algorithm. 3575 o Clarified encoding of ECDSA signature. 3577 o Clarified use of non-deterministic algorithms. 3579 - -07 3581 o Added security and privacy considerations. 3583 o Added pointers to algorithm values from definition sections. 3585 o Expanded IANA registry sections. 3587 o Clarified that the signing and verification algorithms take 3588 application requirements as inputs. 3590 o Defined "signature targets" of request, response, and 3591 related-response for specialty components. 3593 - -06 3595 o Updated language for message components, including 3596 identifiers and values. 3598 o Clarified that Signature-Input and Signature are fields 3599 which can be used as headers or trailers. 3601 o Add "Accept-Signature" field and semantics for signature 3602 negotiation. 3604 o Define new specialty content identifiers, re-defined 3605 request-target identifier. 3607 o Added request-response binding. 3609 - -05 3611 o Remove list prefixes. 3613 o Clarify signature algorithm parameters. 3615 o Update and fix examples. 3617 o Add examples for ECC and HMAC. 3619 - -04 3621 o Moved signature component definitions up to intro. 3623 o Created formal function definitions for algorithms to 3624 fulfill. 3626 o Updated all examples. 3628 o Added nonce parameter field. 3630 - -03 3632 o Clarified signing and verification processes. 3634 o Updated algorithm and key selection method. 3636 o Clearly defined core algorithm set. 3638 o Defined JOSE signature mapping process. 3640 o Removed legacy signature methods. 3642 o Define signature parameters separately from "signature" 3643 object model. 3645 o Define serialization values for signature-input header based 3646 on signature input. 3648 - -02 3650 o Removed editorial comments on document sources. 3652 o Removed in-document issues list in favor of tracked issues. 3654 o Replaced unstructured Signature header with Signature-Input 3655 and Signature Dictionary Structured Header Fields. 3657 o Defined content identifiers for individual Dictionary 3658 members, e.g., "x-dictionary-field";key=member-name. 3660 o Defined content identifiers for first N members of a List, 3661 e.g., "x-list-field":prefix=4. 3663 o Fixed up examples. 3665 o Updated introduction now that it's adopted. 3667 o Defined specialty content identifiers and a means to extend 3668 them. 3670 o Required signature parameters to be included in signature. 3672 o Added guidance on backwards compatibility, detection, and 3673 use of signature methods. 3675 - -01 3677 o Strengthened requirement for content identifiers for header 3678 fields to be lower-case (changed from SHOULD to MUST). 3680 o Added real example values for Creation Time and Expiration 3681 Time. 3683 o Minor editorial corrections and readability improvements. 3685 - -00 3687 o Initialized from draft-richanna-http-message-signatures-00, 3688 following adoption by the working group. 3690 * draft-richanna-http-message-signatures 3692 - -00 3694 o Converted to xml2rfc v3 and reformatted to comply with RFC 3695 style guides. 3697 o Removed Signature auth-scheme definition and related 3698 content. 3700 o Removed conflicting normative requirements for use of 3701 algorithm parameter. Now MUST NOT be relied upon. 3703 o Removed Extensions appendix. 3705 o Rewrote abstract and introduction to explain context and 3706 need, and challenges inherent in signing HTTP messages. 3708 o Rewrote and heavily expanded algorithm definition, retaining 3709 normative requirements. 3711 o Added definitions for key terms, referenced RFC 7230 for 3712 HTTP terms. 3714 o Added examples for canonicalization and signature generation 3715 steps. 3717 o Rewrote Signature header definition, retaining normative 3718 requirements. 3720 o Added default values for algorithm and expires parameters. 3722 o Rewrote HTTP Signature Algorithms registry definition. 3723 Added change control policy and registry template. Removed 3724 suggested URI. 3726 o Added IANA HTTP Signature Parameter registry. 3728 o Added additional normative and informative references. 3730 o Added Topics for Working Group Discussion section, to be 3731 removed prior to publication as an RFC. 3733 Authors' Addresses 3735 Annabelle Backman (editor) 3736 Amazon 3737 P.O. Box 81226 3738 Seattle, WA 98108-1226 3739 United States of America 3740 Email: richanna@amazon.com 3741 URI: https://www.amazon.com/ 3743 Justin Richer 3744 Bespoke Engineering 3745 Email: ietf@justin.richer.org 3746 URI: https://bspk.io/ 3748 Manu Sporny 3749 Digital Bazaar 3750 203 Roanoke Street W. 3751 Blacksburg, VA 24060 3752 United States of America 3753 Email: msporny@digitalbazaar.com 3754 URI: https://manu.sporny.org/