idnits 2.17.1 draft-ietf-httpbis-message-signatures-08.txt: -(3402): 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 are 2 instances of too long lines in the document, the longest one being 23 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 (28 January 2022) is 819 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: 1 August 2022 Bespoke Engineering 6 M. Sporny 7 Digital Bazaar 8 28 January 2022 10 HTTP Message Signatures 11 draft-ietf-httpbis-message-signatures-08 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 1 August 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 . . . . . . . . . . . . . . . . . . 6 77 1.4. Conventions and Terminology . . . . . . . . . . . . . . . 7 78 1.5. Application of HTTP Message Signatures . . . . . . . . . 9 79 2. HTTP Message Components . . . . . . . . . . . . . . . . . . . 10 80 2.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . . 11 81 2.1.1. Canonicalized Structured HTTP Fields . . . . . . . . 13 82 2.1.2. Dictionary Structured Field Members . . . . . . . . . 13 83 2.2. Derived Components . . . . . . . . . . . . . . . . . . . 14 84 2.2.1. Signature Parameters . . . . . . . . . . . . . . . . 16 85 2.2.2. Method . . . . . . . . . . . . . . . . . . . . . . . 17 86 2.2.3. Target URI . . . . . . . . . . . . . . . . . . . . . 18 87 2.2.4. Authority . . . . . . . . . . . . . . . . . . . . . . 18 88 2.2.5. Scheme . . . . . . . . . . . . . . . . . . . . . . . 19 89 2.2.6. Request Target . . . . . . . . . . . . . . . . . . . 19 90 2.2.7. Path . . . . . . . . . . . . . . . . . . . . . . . . 20 91 2.2.8. Query . . . . . . . . . . . . . . . . . . . . . . . . 21 92 2.2.9. Query Parameters . . . . . . . . . . . . . . . . . . 22 93 2.2.10. Status Code . . . . . . . . . . . . . . . . . . . . . 23 94 2.2.11. Request-Response Signature Binding . . . . . . . . . 23 95 2.3. Creating the Signature Input String . . . . . . . . . . . 26 96 3. HTTP Message Signatures . . . . . . . . . . . . . . . . . . . 28 97 3.1. Creating a Signature . . . . . . . . . . . . . . . . . . 29 98 3.2. Verifying a Signature . . . . . . . . . . . . . . . . . . 31 99 3.2.1. Enforcing Application Requirements . . . . . . . . . 33 100 3.3. Signature Algorithm Methods . . . . . . . . . . . . . . . 34 101 3.3.1. RSASSA-PSS using SHA-512 . . . . . . . . . . . . . . 35 102 3.3.2. RSASSA-PKCS1-v1_5 using SHA-256 . . . . . . . . . . . 35 103 3.3.3. HMAC using SHA-256 . . . . . . . . . . . . . . . . . 36 104 3.3.4. ECDSA using curve P-256 DSS and SHA-256 . . . . . . . 36 105 3.3.5. EdDSA using curve edwards25519 . . . . . . . . . . . 37 106 3.3.6. JSON Web Signature (JWS) algorithms . . . . . . . . . 38 107 4. Including a Message Signature in a Message . . . . . . . . . 38 108 4.1. The 'Signature-Input' HTTP Field . . . . . . . . . . . . 38 109 4.2. The 'Signature' HTTP Field . . . . . . . . . . . . . . . 39 110 4.3. Multiple Signatures . . . . . . . . . . . . . . . . . . . 40 111 5. Requesting Signatures . . . . . . . . . . . . . . . . . . . . 43 112 5.1. The Accept-Signature Field . . . . . . . . . . . . . . . 44 113 5.2. Processing an Accept-Signature . . . . . . . . . . . . . 45 114 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 115 6.1. HTTP Signature Algorithms Registry . . . . . . . . . . . 46 116 6.1.1. Registration Template . . . . . . . . . . . . . . . . 46 117 6.1.2. Initial Contents . . . . . . . . . . . . . . . . . . 47 118 6.2. HTTP Signature Metadata Parameters Registry . . . . . . . 47 119 6.2.1. Registration Template . . . . . . . . . . . . . . . . 47 120 6.2.2. Initial Contents . . . . . . . . . . . . . . . . . . 48 121 6.3. HTTP Signature Derived Component Identifiers Registry . . 49 122 6.3.1. Registration Template . . . . . . . . . . . . . . . . 49 123 6.3.2. Initial Contents . . . . . . . . . . . . . . . . . . 50 124 7. Security Considerations . . . . . . . . . . . . . . . . . . . 51 125 7.1. Signature Verification Skipping . . . . . . . . . . . . . 51 126 7.2. Use of TLS . . . . . . . . . . . . . . . . . . . . . . . 51 127 7.3. Signature Replay . . . . . . . . . . . . . . . . . . . . 52 128 7.4. Insufficient Coverage . . . . . . . . . . . . . . . . . . 52 129 7.5. Cryptography and Signature Collision . . . . . . . . . . 53 130 7.6. Key Theft . . . . . . . . . . . . . . . . . . . . . . . . 53 131 7.7. Modification of Required Message Parameters . . . . . . . 54 132 7.8. Mismatch of Signature Parameters from Message . . . . . . 54 133 7.9. Multiple Signature Confusion . . . . . . . . . . . . . . 54 134 7.10. Signature Labels . . . . . . . . . . . . . . . . . . . . 55 135 7.11. Symmetric Cryptography . . . . . . . . . . . . . . . . . 55 136 7.12. Canonicalization Attacks . . . . . . . . . . . . . . . . 56 137 7.13. Key Specification Mix-Up . . . . . . . . . . . . . . . . 56 138 7.14. HTTP Versions and Component Ambiguity . . . . . . . . . . 56 139 7.15. Key and Algorithm Specification Downgrades . . . . . . . 57 140 7.16. Parsing Structured Field Values . . . . . . . . . . . . . 57 141 7.17. Choosing Message Components . . . . . . . . . . . . . . . 58 142 7.18. Confusing HTTP Field Names for Derived Component 143 Identifiers . . . . . . . . . . . . . . . . . . . . . . 58 144 7.19. Non-deterministic Signature Primitives . . . . . . . . . 59 145 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 59 146 8.1. Identification through Keys . . . . . . . . . . . . . . . 59 147 8.2. Signatures do not provide confidentiality . . . . . . . . 59 148 8.3. Oracles . . . . . . . . . . . . . . . . . . . . . . . . . 60 149 8.4. Required Content . . . . . . . . . . . . . . . . . . . . 60 150 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 60 151 9.1. Normative References . . . . . . . . . . . . . . . . . . 60 152 9.2. Informative References . . . . . . . . . . . . . . . . . 62 153 Appendix A. Detecting HTTP Message Signatures . . . . . . . . . 63 154 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 63 155 B.1. Example Keys . . . . . . . . . . . . . . . . . . . . . . 63 156 B.1.1. Example Key RSA test . . . . . . . . . . . . . . . . 63 157 B.1.2. Example RSA PSS Key . . . . . . . . . . . . . . . . . 64 158 B.1.3. Example ECC P-256 Test Key . . . . . . . . . . . . . 65 159 B.1.4. Example Shared Secret . . . . . . . . . . . . . . . . 66 160 B.1.5. Example Ed25519 Test Key . . . . . . . . . . . . . . 66 161 B.2. Test Cases . . . . . . . . . . . . . . . . . . . . . . . 66 162 B.2.1. Minimal Signature Using rsa-pss-sha512 . . . . . . . 67 163 B.2.2. Selective Covered Components using rsa-pss-sha512 . . 68 164 B.2.3. Full Coverage using rsa-pss-sha512 . . . . . . . . . 69 165 B.2.4. Signing a Response using ecdsa-p256-sha256 . . . . . 70 166 B.2.5. Signing a Request using hmac-sha256 . . . . . . . . . 71 167 B.2.6. Signing a Request using ed25519 . . . . . . . . . . . 71 168 B.3. TLS-Terminating Proxies . . . . . . . . . . . . . . . . . 72 169 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 74 170 Document History . . . . . . . . . . . . . . . . . . . . . . . . 75 171 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78 173 1. Introduction 175 Message integrity and authenticity are important security properties 176 that are critical to the secure operation of many HTTP applications. 177 Application developers typically rely on the transport layer to 178 provide these properties, by operating their application over [TLS]. 179 However, TLS only guarantees these properties over a single TLS 180 connection, and the path between client and application may be 181 composed of multiple independent TLS connections (for example, if the 182 application is hosted behind a TLS-terminating gateway or if the 183 client is behind a TLS Inspection appliance). In such cases, TLS 184 cannot guarantee end-to-end message integrity or authenticity between 185 the client and application. Additionally, some operating 186 environments present obstacles that make it impractical to use TLS, 187 or to use features necessary to provide message authenticity. 188 Furthermore, some applications require the binding of an application- 189 level key to the HTTP message, separate from any TLS certificates in 190 use. Consequently, while TLS can meet message integrity and 191 authenticity needs for many HTTP-based applications, it is not a 192 universal solution. 194 This document defines a mechanism for providing end-to-end integrity 195 and authenticity for components of an HTTP message. The mechanism 196 allows applications to create digital signatures or message 197 authentication codes (MACs) over only the components of the message 198 that are meaningful and appropriate for the application. Strict 199 canonicalization rules ensure that the verifier can verify the 200 signature even if the message has been transformed in any of the many 201 ways permitted by HTTP. 203 The signing mechanism described in this document consists of three 204 parts: 206 * A common nomenclature and canonicalization rule set for the 207 different protocol elements and other components of HTTP messages, 208 used to create a signature input. 210 * Algorithms for generating and verifying signatures over HTTP 211 message components using this signature input through application 212 of cryptographic primitives. 214 * A mechanism for attaching a signature and related metadata to an 215 HTTP message, and for parsing attached signatures and metadata 216 from HTTP messages. 218 This document also provides a mechanism for a potential verifier to 219 signal to a potential signer that a signature is desired in one or 220 more subsequent messages. This optional negotiation mechanism can be 221 used along with opportunistic or application-driven message 222 signatures by either party. 224 1.1. Requirements Discussion 226 HTTP permits and sometimes requires intermediaries to transform 227 messages in a variety of ways. This may result in a recipient 228 receiving a message that is not bitwise equivalent to the message 229 that was originally sent. In such a case, the recipient will be 230 unable to verify a signature over the raw bytes of the sender's HTTP 231 message, as verifying digital signatures or MACs requires both signer 232 and verifier to have the exact same signature input. Since the exact 233 raw bytes of the message cannot be relied upon as a reliable source 234 of signature input, the signer and verifier must derive the signature 235 input from their respective versions of the message, via a mechanism 236 that is resilient to safe changes that do not alter the meaning of 237 the message. 239 For a variety of reasons, it is impractical to strictly define what 240 constitutes a safe change versus an unsafe one. Applications use 241 HTTP in a wide variety of ways, and may disagree on whether a 242 particular piece of information in a message (e.g., the body, or the 243 Date header field) is relevant. Thus a general purpose solution must 244 provide signers with some degree of control over which message 245 components are signed. 247 HTTP applications may be running in environments that do not provide 248 complete access to or control over HTTP messages (such as a web 249 browser's JavaScript environment), or may be using libraries that 250 abstract away the details of the protocol (such as the Java 251 HTTPClient library (https://openjdk.java.net/groups/net/httpclient/ 252 intro.html)). These applications need to be able to generate and 253 verify signatures despite incomplete knowledge of the HTTP message. 255 1.2. HTTP Message Transformations 257 As mentioned earlier, HTTP explicitly permits and in some cases 258 requires implementations to transform messages in a variety of ways. 259 Implementations are required to tolerate many of these 260 transformations. What follows is a non-normative and non-exhaustive 261 list of transformations that may occur under HTTP, provided as 262 context: 264 * Re-ordering of header fields with different header field names 265 (Section 3.2.2 of [MESSAGING]). 267 * Combination of header fields with the same field name 268 (Section 3.2.2 of [MESSAGING]). 270 * Removal of header fields listed in the Connection header field 271 (Section 6.1 of [MESSAGING]). 273 * Addition of header fields that indicate control options 274 (Section 6.1 of [MESSAGING]). 276 * Addition or removal of a transfer coding (Section 5.7.2 of 277 [MESSAGING]). 279 * Addition of header fields such as Via (Section 5.7.1 of 280 [MESSAGING]) and Forwarded (Section 4 of [RFC7239]). 282 1.3. Safe Transformations 284 Based on the definition of HTTP and the requirements described above, 285 we can identify certain types of transformations that should not 286 prevent signature verification, even when performed on message 287 components covered by the signature. The following list describes 288 those transformations: 290 * Combination of header fields with the same field name. 292 * Reordering of header fields with different names. 294 * Conversion between different versions of the HTTP protocol (e.g., 295 HTTP/1.x to HTTP/2, or vice-versa). 297 * Changes in casing (e.g., "Origin" to "origin") of any case- 298 insensitive components such as header field names, request URI 299 scheme, or host. 301 * Addition or removal of leading or trailing whitespace to a header 302 field value. 304 * Addition or removal of obs-folds. 306 * Changes to the request-target and Host header field that when 307 applied together do not result in a change to the message's 308 effective request URI, as defined in Section 5.5 of [MESSAGING]. 310 Additionally, all changes to components not covered by the signature 311 are considered safe. 313 1.4. Conventions and Terminology 315 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 316 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 317 "OPTIONAL" in this document are to be interpreted as described in 318 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 319 capitals, as shown here. 321 The terms "HTTP message", "HTTP request", "HTTP response", absolute- 322 form, absolute-path, "effective request URI", "gateway", "header 323 field", "intermediary", request-target, "sender", and "recipient" are 324 used as defined in [MESSAGING]. 326 The term "method" is to be interpreted as defined in Section 4 of 327 [SEMANTICS]. 329 For brevity, the term "signature" on its own is used in this document 330 to refer to both digital signatures (which use asymmetric 331 cryptography) and keyed MACs (which use symmetric cryptography). 332 Similarly, the verb "sign" refers to the generation of either a 333 digital signature or keyed MAC over a given input string. The 334 qualified term "digital signature" refers specifically to the output 335 of an asymmetric cryptographic signing operation. 337 In addition to those listed above, this document uses the following 338 terms: 340 HTTP Message Signature: 341 A digital signature or keyed MAC that covers one or more portions 342 of an HTTP message. Note that a given HTTP Message can contain 343 multiple HTTP Message Signatures. 345 Signer: 346 The entity that is generating or has generated an HTTP Message 347 Signature. Note that multiple entities can act as signers and 348 apply separate HTTP Message Signatures to a given HTTP Message. 350 Verifier: 351 An entity that is verifying or has verified an HTTP Message 352 Signature against an HTTP Message. Note that an HTTP Message 353 Signature may be verified multiple times, potentially by different 354 entities. 356 HTTP Message Component: 357 A portion of an HTTP message that is capable of being covered by 358 an HTTP Message Signature. 360 HTTP Message Component Identifier: 361 A value that uniquely identifies a specific HTTP Message Component 362 in respect to a particular HTTP Message Signature and the HTTP 363 Message it applies to. 365 HTTP Message Component Value: 366 The value associated with a given component identifier within the 367 context of a particular HTTP Message. Component values are 368 derived from the HTTP Message and are usually subject to a 369 canonicalization process. 371 Covered Components: 372 An ordered set of HTTP message component identifiers for fields 373 (Section 2.1) and derived components (Section 2.2) that indicates 374 the set of message components covered by the signature, never 375 including the @signature-params identifier itself. The order of 376 this set is preserved and communicated between the signer and 377 verifier to facilitate reconstruction of the signature input. 379 Signature Input: 380 The sequence of bytes processed by the cryptographic algorithm to 381 produce or verify the HTTP Message Signature. The signature input 382 is generated by the signer and verifier using the covered 383 components set and the HTTP Message. 385 HTTP Message Signature Algorithm: 386 A cryptographic algorithm that describes the signing and 387 verification process for the signature, defined in terms of the 388 HTTP_SIGN and HTTP_VERIFY primitives described in Section 3.3. 390 Key Material: 391 The key material required to create or verify the signature. The 392 key material is often identified with an explicit key identifier, 393 allowing the signer to indicate to the verifier which key was 394 used. 396 Creation Time: 397 A timestamp representing the point in time that the signature was 398 generated, as asserted by the signer. 400 Expiration Time: 401 A timestamp representing the point in time after which the 402 signature should no longer be accepted by the verifier, as 403 asserted by the signer. 405 The term "Unix time" is defined by [POSIX.1], Section 4.16 406 (http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ 407 V1_chap04.html#tag_04_16). 409 This document contains non-normative examples of partial and complete 410 HTTP messages. Some examples use a single trailing backslash '' to 411 indicate line wrapping for long values, as per [RFC8792]. The \ 412 character and leading spaces on wrapped lines are not part of the 413 value. 415 1.5. Application of HTTP Message Signatures 417 HTTP Message Signatures are designed to be a general-purpose security 418 mechanism applicable in a wide variety of circumstances and 419 applications. In order to properly and safely apply HTTP Message 420 Signatures, an application or profile of this specification MUST 421 specify all of the following items: 423 * The set of component identifiers (Section 2) that are expected and 424 required. For example, an authorization protocol could mandate 425 that the Authorization header be covered to protect the 426 authorization credentials and mandate the signature parameters 427 contain a created parameter, while an API expecting HTTP message 428 bodies could require the Digest header to be present and covered. 430 * A means of retrieving the key material used to verify the 431 signature. An application will usually use the keyid parameter of 432 the signature parameters (Section 2.2.1) and define rules for 433 resolving a key from there, though the appropriate key could be 434 known from other means. 436 * A means of determining the signature algorithm used to verify the 437 signature is appropriate for the key material. For example, the 438 process could use the alg parameter of the signature parameters 439 (Section 2.2.1) to state the algorithm explicitly, derive the 440 algorithm from the key material, or use some pre-configured 441 algorithm agreed upon by the signer and verifier. 443 * A means of determining that a given key and algorithm presented in 444 the request are appropriate for the request being made. For 445 example, a server expecting only ECDSA signatures should know to 446 reject any RSA signatures, or a server expecting asymmetric 447 cryptography should know to reject any symmetric cryptography. 449 An application using signatures also has to ensure that the verifier 450 will have access to all required information to re-create the 451 signature input string. For example, a server behind a reverse proxy 452 would need to know the original request URI to make use of 453 identifiers like @target-uri. Additionally, an application using 454 signatures in responses would need to ensure that clients receiving 455 signed responses have access to all the signed portions, including 456 any portions of the request that were signed by the server. 458 The details of this kind of profiling are the purview of the 459 application and outside the scope of this specification, however some 460 additional considerations are discussed in Section 7. 462 2. HTTP Message Components 464 In order to allow signers and verifiers to establish which components 465 are covered by a signature, this document defines component 466 identifiers for components covered by an HTTP Message Signature, a 467 set of rules for deriving and canonicalizing the values associated 468 with these component identifiers from the HTTP Message, and the means 469 for combining these canonicalized values into a signature input 470 string. The values for these items MUST be accessible to both the 471 signer and the verifier of the message, which means these are usually 472 derived from aspects of the HTTP message or signature itself. 474 Some HTTP message components can undergo transformations that change 475 the bitwise value without altering meaning of the component's value 476 (for example, the merging together of header fields with the same 477 name). Message component values must therefore be canonicalized 478 before it is signed, to ensure that a signature can be verified 479 despite such intermediary transformations. This document defines 480 rules for each component identifier that transform the identifier's 481 associated component value into such a canonical form. 483 Component identifiers are serialized using the production grammar 484 defined by [RFC8941], Section 4. The component identifier itself is 485 an sf-string value and MAY define parameters which are included using 486 the parameters rule. 488 component-identifier = sf-string parameters 490 Note that this means the serialization of the component identifier 491 itself is encased in double quotes, with parameters following as a 492 semicolon-separated list, such as "cache-control", "date", or 493 "@signature-params". 495 Component identifiers, including component identifiers with 496 parameters, MUST NOT be repeated within a single list of covered 497 components. Component identifiers with different parameter values 498 MAY be repeated within a single list of covered components. 500 The component value associated with a component identifier is defined 501 by the identifier itself. Component values MUST NOT contain newline 502 (\n) characters. 504 The following sections define component identifier types, their 505 parameters, their associated values, and the canonicalization rules 506 for their values. The method for combining component identifiers 507 into the signature input is defined in Section 2.3. 509 2.1. HTTP Fields 511 The component identifier for an HTTP field is the lowercased form of 512 its field name. While HTTP field names are case-insensitive, 513 implementations MUST use lowercased field names (e.g., content-type, 514 date, etag) when using them as component identifiers. 516 Unless overridden by additional parameters and rules, the HTTP field 517 value MUST be canonicalized as a single combined value as defined in 518 Section 5.2 of [SEMANTICS]. 520 If the combined value is not available for a given header, the 521 following algorithm will produce canonicalized results for an 522 implementation: 524 1. Create an ordered list of the field values of each instance of 525 the field in the message, in the order that they occur (or will 526 occur) in the message. 528 2. Strip leading and trailing whitespace from each item in the list. 529 Note that since HTTP field values are not allowed to contain 530 leading and trailing whitespace, this will be a no-op in a 531 compliant implementation. 533 3. Remove any obsolete line-folding within the line and replace it 534 with a single space (), as discussed in Section 5.2 of 535 [MESSAGING]. Note that this behavior is specific to [MESSAGING] 536 and does not apply to other versions of the HTTP specification. 538 4. Concatenate the list of values together with a single comma (,) 539 and a single space () between each item. 541 The resulting string is the canonicalized component value. 543 Following are non-normative examples of canonicalized values for 544 header fields, given the following example HTTP message fragment: 546 Host: www.example.com 547 Date: Tue, 20 Apr 2021 02:07:56 GMT 548 X-OWS-Header: Leading and trailing whitespace. 549 X-Obs-Fold-Header: Obsolete 550 line folding. 551 Cache-Control: max-age=60 552 Cache-Control: must-revalidate 553 Example-Dictionary: a=1, b=2;x=1;y=2, c=(a b c) 555 The following example shows canonicalized values for these example 556 header fields, presented using the signature input string format 557 discussed in Section 2.3: 559 "host": www.example.com 560 "date": Tue, 20 Apr 2021 02:07:56 GMT 561 "x-ows-header": Leading and trailing whitespace. 562 "x-obs-fold-header": Obsolete line folding. 563 "cache-control": max-age=60, must-revalidate 564 "Example-dictionary": a=1, b=2;x=1;y=2, c=(a b c) 566 Since empty HTTP header fields are allowed, they are also able to be 567 signed when present in a message. The canonicalized value is the 568 empty string. This means that the following empty header: 570 NOTE: '\' line wrapping per RFC 8792 572 X-Empty-Header: \ 574 Is serialized by the signature input generation algorithm 575 (Section 2.3) with an empty string value following the colon and 576 space added after the content identifier. 578 NOTE: '\' line wrapping per RFC 8792 580 "x-empty-header": \ 582 Note: these are shown here using the line wrapping algorithm in 583 [RFC8792] due to limitations in the document format that strips 584 trailing spaces from diagrams. 586 2.1.1. Canonicalized Structured HTTP Fields 588 If value of the the HTTP field in question is a structured field 589 ([RFC8941]), the component identifier MAY include the sf parameter to 590 indicate it is a known structured field. If this parameter is 591 included with a component identifier, the HTTP field value MUST be 592 serialized using the rules specified in Section 4 of [RFC8941] 593 applicable to the type of the HTTP field. Note that this process 594 will replace any optional internal whitespace with a single space 595 character, among other potential transformations of the value. 597 For example, the following dictionary field is a valid serialization: 599 Example-Dictionary: a=1, b=2;x=1;y=2, c=(a b c) 601 If included in the input string as-is, it would be: 603 "example-dictionary": a=1, b=2;x=1;y=2, c=(a b c) 605 However, if the sf parameter is added, the value is re-serialized as 606 follows: 608 "example-dictionary";sf: a=1, b=2;x=1;y=2, c=(a b c) 610 The resulting string is used as the component value in Section 2.1. 612 2.1.2. Dictionary Structured Field Members 614 An individual member in the value of a Dictionary Structured Field is 615 identified by using the parameter key to indicate the member key as 616 an sf-string value. 618 An individual member in the value of a Dictionary Structured Field is 619 canonicalized by applying the serialization algorithm described in 620 Section 4.1.2 of [RFC8941] on the member value and its parameters, 621 without the dictionary key. 623 Each parameterized key for a given field MUST NOT appear more than 624 once in the signature input. Parameterized keys MAY appear in any 625 order. 627 Following are non-normative examples of canonicalized values for 628 Dictionary Structured Field Members given the following example 629 header field, whose value is known to be a Dictionary: 631 Example-Dictionary: a=1, b=2;x=1;y=2, c=(a b c) 633 The following example shows canonicalized values for different 634 component identifiers of this field, presented using the signature 635 input string format discussed in Section 2.3: 637 "example-dictionary";key="a": 1 638 "example-dictionary";key="b": 2;x=1;y=2 639 "example-dictionary";key="c": (a b c) 641 Note that the value for key="c" has been re-serialized. 643 2.2. Derived Components 645 In addition to HTTP fields, there are a number of different 646 components that can be derived from the control data, processing 647 context, or other aspects of the HTTP message being signed. Such 648 derived components can be included in the signature input by defining 649 a component identifier and the derivation method for its component 650 value. 652 Derived component identifiers MUST start with the "at" @ character. 653 This differentiates derived component identifiers from HTTP field 654 names, which cannot contain the @ character as per Section 5.1 of 655 [SEMANTICS]. Processors of HTTP Message Signatures MUST treat 656 derived component identifiers separately from field names, as 657 discussed in Section 7.18. 659 This specification defines the following derived component 660 identifiers: 662 @signature-params The signature metadata parameters for this 663 signature. (Section 2.2.1) 665 @method The method used for a request. (Section 2.2.2) 666 @target-uri The full target URI for a request. (Section 2.2.3) 668 @authority The authority of the target URI for a request. 669 (Section 2.2.4) 671 @scheme The scheme of the target URI for a request. (Section 2.2.5) 673 @request-target The request target. (Section 2.2.6) 675 @path The absolute path portion of the target URI for a request. 676 (Section 2.2.7) 678 @query The query portion of the target URI for a request. 679 (Section 2.2.8) 681 @query-params The parsed query parameters of the target URI for a 682 request. (Section 2.2.9) 684 @status The status code for a response. (Section 2.2.10). 686 @request-response A signature from a request message that resulted 687 in this response message. (Section 2.2.11) 689 Additional derived component identifiers MAY be defined and 690 registered in the HTTP Signatures Derived Component Identifier 691 Registry. (Section 6.3) 693 Derived components can be applied in one or more of three targets: 695 request: Values derived from and results applied to an HTTP request 696 message as described in {{Section 3.4 of SEMANTICS. 698 response: Values derived from and results applied to an HTTP 699 response message as described in Section 3.4 of [SEMANTICS]. 701 related-response: Values derived from an HTTP request message and 702 results applied to the HTTP response message that is responding to 703 that specific request. 705 A component identifier definition MUST define all targets to which it 706 can be applied. 708 The component value MUST be derived from the HTTP message being 709 signed or the context in which the derivation occurs. The derived 710 component value MUST be of the following form: 712 derived-component-value = *VCHAR 714 2.2.1. Signature Parameters 716 HTTP Message Signatures have metadata properties that provide 717 information regarding the signature's generation and verification, 718 such as the set of covered components, a timestamp, identifiers for 719 verification key material, and other utilities. 721 The signature parameters component identifier is @signature-params. 722 This message component's value is REQUIRED as part of the signature 723 input string (Section 2.3) but the component identifier MUST NOT be 724 enumerated within the set of covered components itself. 726 The signature parameters component value is the serialization of the 727 signature parameters for this signature, including the covered 728 components set with all associated parameters. These parameters 729 include any of the following: 731 * created: Creation time as an sf-integer UNIX timestamp value. 732 Sub-second precision is not supported. Inclusion of this 733 parameter is RECOMMENDED. 735 * expires: Expiration time as an sf-integer UNIX timestamp value. 736 Sub-second precision is not supported. 738 * nonce: A random unique value generated for this signature as an 739 sf-string value. 741 * alg: The HTTP message signature algorithm from the HTTP Message 742 Signature Algorithm Registry, as an sf-string value. 744 * keyid: The identifier for the key material as an sf-string value. 746 Additional parameters can be defined in the HTTP Signature Parameters 747 Registry (Section 6.2.2). 749 The signature parameters component value is serialized as a 750 parameterized inner list using the rules in Section 4 of [RFC8941] as 751 follows: 753 1. Let the output be an empty string. 755 2. Determine an order for the component identifiers of the covered 756 components, not including the @signature-params component 757 identifier itself. Once this order is chosen, it cannot be 758 changed. This order MUST be the same order as used in creating 759 the signature input (Section 2.3). 761 3. Serialize the component identifiers of the covered components, 762 including all parameters, as an ordered inner-list according to 763 Section 4.1.1.1 of [RFC8941] and append this to the output. 765 4. Determine an order for any signature parameters. Once this order 766 is chosen, it cannot be changed. 768 5. Append the parameters to the inner-list in the chosen order 769 according to Section 4.1.1.2 of [RFC8941], skipping parameters 770 that are not available or not used for this message signature. 772 6. The output contains the signature parameters component value. 774 Note that the inner-list serialization is used for the covered 775 component value instead of the sf-list serialization in order to 776 facilitate this value's inclusion in message fields such as the 777 Signature-Input field's dictionary, as discussed in Section 4.1. 779 This example shows a canonicalized value for the parameters of a 780 given signature: 782 NOTE: '\' line wrapping per RFC 8792 784 ("@target-uri" "@authority" "date" "cache-control")\ 785 ;keyid="test-key-rsa-pss";alg="rsa-pss-sha512";\ 786 created=1618884475;expires=1618884775 788 Note that an HTTP message could contain multiple signatures 789 (Section 4.3), but only the signature parameters used for a single 790 signature are included in an entry. 792 2.2.2. Method 794 The @method component identifier refers to the HTTP method of a 795 request message. The component value of is canonicalized by taking 796 the value of the method as a string. Note that the method name is 797 case-sensitive as per [SEMANTICS], Section 9.1, and conventionally 798 standardized method names are uppercase US-ASCII. If used, the 799 @method component identifier MUST occur only once in the covered 800 components. 802 For example, the following request message: 804 POST /path?param=value HTTP/1.1 805 Host: www.example.com 807 Would result in the following @method value: 809 "@method": POST 811 If used in a related-response, the @method component identifier 812 refers to the associated component value of the request that 813 triggered the response message being signed. 815 2.2.3. Target URI 817 The @target-uri component identifier refers to the target URI of a 818 request message. The component value is the full absolute target URI 819 of the request, potentially assembled from all available parts 820 including the authority and request target as described in 821 [SEMANTICS], Section 7.1. If used, the @target-uri component 822 identifier MUST occur only once in the covered components. 824 For example, the following message sent over HTTPS: 826 POST /path?param=value HTTP/1.1 827 Host: www.example.com 829 Would result in the following @target-uri value: 831 "@target-uri": https://www.example.com/path?param=value 833 If used in a related-response, the @target-uri component identifier 834 refers to the associated component value of the request that 835 triggered the response message being signed. 837 2.2.4. Authority 839 The @authority component identifier refers to the authority component 840 of the target URI of the HTTP request message, as defined in 841 [SEMANTICS], Section 7.2. In HTTP 1.1, this is usually conveyed 842 using the Host header, while in HTTP 2 and HTTP 3 it is conveyed 843 using the :authority pseudo-header. The value is the fully-qualified 844 authority component of the request, comprised of the host and, 845 optionally, port of the request target, as a string. The component 846 value MUST be normalized according to the rules in [SEMANTICS], 847 Section 4.2.3. Namely, the host name is normalized to lowercase and 848 the default port is omitted. If used, the @authority component 849 identifier MUST occur only once in the covered components. 851 For example, the following request message: 853 POST /path?param=value HTTP/1.1 854 Host: www.example.com 856 Would result in the following @authority component value: 858 "@authority": www.example.com 860 If used in a related-response, the @authority component identifier 861 refers to the associated component value of the request that 862 triggered the response message being signed. 864 2.2.5. Scheme 866 The @scheme component identifier refers to the scheme of the target 867 URL of the HTTP request message. The component value is the scheme 868 as a string as defined in [SEMANTICS], Section 4.2. While the scheme 869 itself is case-insensitive, it MUST be normalized to lowercase for 870 inclusion in the signature input string. If used, the @scheme 871 component identifier MUST occur only once in the covered components. 873 For example, the following request message requested over plain HTTP: 875 POST /path?param=value HTTP/1.1 876 Host: www.example.com 878 Would result in the following @scheme value: 880 "@scheme": http 882 If used in a related-response, the @scheme component identifier 883 refers to the associated component value of the request that 884 triggered the response message being signed. 886 2.2.6. Request Target 888 The @request-target component identifier refers to the full request 889 target of the HTTP request message, as defined in [SEMANTICS], 890 Section 7.1. The component value of the request target can take 891 different forms, depending on the type of request, as described 892 below. If used, the @request-target component identifier MUST occur 893 only once in the covered components. 895 For HTTP 1.1, the component value is equivalent to the request target 896 portion of the request line. However, this value is more difficult 897 to reliably construct in other versions of HTTP. Therefore, it is 898 NOT RECOMMENDED that this identifier be used when versions of HTTP 899 other than 1.1 might be in use. 901 The origin form value is combination of the absolute path and query 902 components of the request URL. For example, the following request 903 message: 905 POST /path?param=value HTTP/1.1 906 Host: www.example.com 908 Would result in the following @request-target component value: 910 "@request-target": /path?param=value 912 The following request to an HTTP proxy with the absolute-form value, 913 containing the fully qualified target URI: 915 GET https://www.example.com/path?param=value HTTP/1.1 917 Would result in the following @request-target component value: 919 "@request-target": https://www.example.com/path?param=value 921 The following CONNECT request with an authority-form value, 922 containing the host and port of the target: 924 CONNECT www.example.com:80 HTTP/1.1 925 Host: www.example.com 927 Would result in the following @request-target component value: 929 "@request-target": www.example.com:80 931 The following OPTIONS request message with the asterisk-form value, 932 containing a single asterisk * character: 934 OPTIONS * HTTP/1.1 935 Host: www.example.com 937 Would result in the following @request-target component value: 939 "@request-target": * 941 If used in a related-response, the @request-target component 942 identifier refers to the associated component value of the request 943 that triggered the response message being signed. 945 2.2.7. Path 947 The @path component identifier refers to the target path of the HTTP 948 request message. The component value is the absolute path of the 949 request target defined by [RFC3986], with no query component and no 950 trailing ? character. The value is normalized according to the rules 951 in [SEMANTICS], Section 4.2.3. Namely, an empty path string is 952 normalized as a single slash / character, and path components are 953 represented by their values after decoding any percent-encoded 954 octets. If used, the @path component identifier MUST occur only once 955 in the covered components. 957 For example, the following request message: 959 POST /path?param=value HTTP/1.1 960 Host: www.example.com 962 Would result in the following @path value: 964 "@path": /path 966 If used in a related-response, the @path identifier refers to the 967 associated component value of the request that triggered the response 968 message being signed. 970 2.2.8. Query 972 The @query component identifier refers to the query component of the 973 HTTP request message. The component value is the entire normalized 974 query string defined by [RFC3986], including the leading ? character. 975 The value is normalized according to the rules in [SEMANTICS], 976 Section 4.2.3. Namely, percent-encoded octets are decoded. If used, 977 the @query component identifier MUST occur only once in the covered 978 components. 980 For example, the following request message: 982 POST /path?param=value&foo=bar&baz=batman HTTP/1.1 983 Host: www.example.com 985 Would result in the following @query value: 987 "@query": ?param=value&foo=bar&baz=batman 989 The following request message: 991 POST /path?queryString HTTP/1.1 992 Host: www.example.com 994 Would result in the following @query value: 996 "@query": ?queryString 998 If used in a related-response, the @query component identifier refers 999 to the associated component value of the request that triggered the 1000 response message being signed. 1002 2.2.9. Query Parameters 1004 If a request target URI uses HTML form parameters in the query string 1005 as defined in HTMLURL, Section 5 [HTMLURL], the @query-params 1006 component identifier allows addressing of individual query 1007 parameters. The query parameters MUST be parsed according to 1008 HTMLURL, Section 5.1 [HTMLURL], resulting in a list of (nameString, 1009 valueString) tuples. The REQUIRED name parameter of each input 1010 identifier contains the nameString of a single query parameter as an 1011 sf-string value. Several different named query parameters MAY be 1012 included in the covered components. Single named parameters MAY 1013 occur in any order in the covered components. 1015 The component value of a single named parameter is the the 1016 valueString of the named query parameter defined by HTMLURL, 1017 Section 5.1 [HTMLURL], which is the value after percent-encoded 1018 octets are decoded. Note that this value does not include any 1019 leading ? characters, equals sign =, or separating & characters. 1020 Named query parameters with an empty valueString are included with an 1021 empty string as the component value. 1023 If a parameter name occurs multiple times in a request, all parameter 1024 values of that name MUST be included in separate signature input 1025 lines in the order in which the parameters occur in the target URI. 1027 For example for the following request: 1029 POST /path?param=value&foo=bar&baz=batman&qux= HTTP/1.1 1030 Host: www.example.com 1032 Indicating the baz, qux and param named query parameters in would 1033 result in the following @query-param value: 1035 "@query-params";name="baz": batman 1036 "@query-params";name="qux": 1037 "@query-params";name="param": value 1039 If used in a related-response, the @query-params component identifier 1040 refers to the associated component value of the request that 1041 triggered the response message being signed. 1043 2.2.10. Status Code 1045 The @status component identifier refers to the three-digit numeric 1046 HTTP status code of a response message as defined in [SEMANTICS], 1047 Section 15. The component value is the serialized three-digit 1048 integer of the HTTP response code, with no descriptive text. If 1049 used, the @status component identifier MUST occur only once in the 1050 covered components. 1052 For example, the following response message: 1054 HTTP/1.1 200 OK 1055 Date: Fri, 26 Mar 2010 00:05:00 GMT 1057 Would result in the following @status value: 1059 "@status": 200 1061 The @status component identifier MUST NOT be used in a request 1062 message. 1064 2.2.11. Request-Response Signature Binding 1066 When a signed request message results in a signed response message, 1067 the @request-response component identifier can be used to 1068 cryptographically link the request and the response to each other by 1069 including the identified request signature value in the response's 1070 signature input without copying the value of the request's signature 1071 to the response directly. This component identifier has a single 1072 REQUIRED parameter: 1074 key Identifies which signature from the response to sign. 1076 The component value is the sf-binary representation of the signature 1077 value of the referenced request identified by the key parameter. 1079 For example, when serving this signed request: 1081 NOTE: '\' line wrapping per RFC 8792 1083 POST /foo?param=Value&Pet=dog HTTP/1.1 1084 Host: example.com 1085 Date: Tue, 20 Apr 2021 02:07:55 GMT 1086 Content-Type: application/json 1087 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1088 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1089 Content-Length: 18 1090 Signature-Input: sig1=("@method" "@authority" "@path" \ 1091 "content-digest" "content-length" "content-type")\ 1092 ;created=1618884475;keyid="test-key-rsa-pss" 1093 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1094 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8Br\ 1095 c8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINTEzpx\ 1096 jqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr65+BXe\ 1097 TG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZElYyUKaAI\ 1098 jZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1100 {"hello": "world"} 1102 This would result in the following unsigned response message: 1104 HTTP/1.1 503 Service Unavailable 1105 Date: Tue, 20 Apr 2021 02:07:56 GMT 1106 Content-Type: application/json 1107 Content-Length: 62 1109 {"busy": true, "message": "Your call is very important to us"} 1111 To cryptographically link the response to the request, the server 1112 signs the response with its own key and includes the signature of 1113 sig1 from the request in the covered components of the response. The 1114 signature input string for this example is: 1116 NOTE: '\' line wrapping per RFC 8792 1118 "@status": 503 1119 "content-length": 62 1120 "content-type": application/json 1121 "@request-response";key="sig1": :LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJR\ 1122 GziCLuD8r5MW9S0RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVd\ 1123 wXyY/UkBIS1M8Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMT\ 1124 e0QE3IpWINTEzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuT\ 1125 Z9HdbD2Tr65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S\ 1126 1ag3LZElYyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1127 "@signature-params": ("@status" "content-length" "content-type" \ 1128 "@request-response";key="sig1");created=1618884479\ 1129 ;keyid="test-key-ecc-p256" 1131 The signed response message is: 1133 NOTE: '\' line wrapping per RFC 8792 1135 HTTP/1.1 503 Service Unavailable 1136 Date: Tue, 20 Apr 2021 02:07:56 GMT 1137 Content-Type: application/json 1138 Content-Length: 62 1139 Signature-Input: reqres=("@status" "content-length" "content-type" \ 1140 "@request-response";key="sig1");created=1618884479\ 1141 ;keyid="test-key-ecc-p256" 1142 Signature: reqres=:JqzXLIjNd6VWVg/M7enbjWkOgsPmIK9vcoFQEkLD0SXNbFjR\ 1143 6d+olsof1dv7xC7ygF1q0YKjVrbV2QlCpDxrHg==: 1145 {"busy": true, "message": "Your call is very important to us"} 1147 Since the request's signature value itself is not repeated in the 1148 response, the requester MUST keep the original signature value around 1149 long enough to validate the signature of the response that uses this 1150 component identifier. 1152 Note that the ECDSA algorithm in use here is non-deterministic, 1153 meaning a different signature value will be created every time the 1154 algorithm is run. The signature value provided here can be validated 1155 against the given keys, but newly-generated signature values are not 1156 expected to match the example. See Section 7.19. 1158 The @request-response component identifier MUST NOT be used in a 1159 request message. 1161 2.3. Creating the Signature Input String 1163 The signature input is a US-ASCII string containing the canonicalized 1164 HTTP message components covered by the signature. The input to the 1165 signature input creation algorithm is the list of covered component 1166 identifiers and their associated values, along with any additional 1167 signature parameters. The output is the signature input string, 1168 which has the following form: 1170 signature-input = *( signature-input-line LF ) signature-params-line 1171 signature-input-line = component-identifier ":" SP ( derived-component-value / field-value ) 1172 signature-params-line = DQUOTE "@signature-params" DQUOTE ":" SP inner-list 1174 To create the signature input string, the signer or verifier 1175 concatenates together entries for each identifier in the signature's 1176 covered components (including their parameters) using the following 1177 algorithm: 1179 1. Let the output be an empty string. 1181 2. For each message component item in the covered components set (in 1182 order): 1184 1. Append the component identifier for the covered component 1185 serialized according to the component-identifier rule. Note 1186 that this serialization places the component identifier in 1187 double quotes and appends any parameters outside of the 1188 quotes. 1190 2. Append a single colon : 1192 3. Append a single space " " 1194 4. Determine the component value for the component identifier. 1196 * If the component identifier starts with an "at" character 1197 (@), derive the component's value from the message 1198 according to the specific rules defined for the derived 1199 component identifier, as in Section 2.2. If the derived 1200 component identifier is unknown or the value cannot be 1201 derived, produce an error. 1203 * If the component identifier does not start with an "at" 1204 character (@), canonicalize the HTTP field value as 1205 described in Section 2.1. If the value cannot be 1206 calculated, produce an error. 1208 5. Append the covered component's canonicalized component value. 1210 6. Append a single newline \n 1212 3. Append the signature parameters component (Section 2.2.1) as 1213 follows: 1215 1. Append the component identifier for the signature parameters 1216 serialized according to the component-identifier rule, i.e. 1217 "@signature-params" 1219 2. Append a single colon : 1221 3. Append a single space " " 1223 4. Append the signature parameters' canonicalized component 1224 value as defined in Section 2.2.1 1226 4. Return the output string. 1228 If covered components reference a component identifier that cannot be 1229 resolved to a component value in the message, the implementation MUST 1230 produce an error and not create an input string. Such situations are 1231 included but not limited to: 1233 * The signer or verifier does not understand the derived component 1234 identifier. 1236 * The component identifier identifies a field that is not present in 1237 the message or whose value is malformed. 1239 * The component identifier indicates that a structured field 1240 serialization is used (via the sf parameter), but the field in 1241 question is known to not be a structured field or the type of 1242 structured field is not known to the implementation. 1244 * The component identifier is a dictionary member identifier that 1245 references a field that is not present in the message, is not a 1246 Dictionary Structured Field, or whose value is malformed. 1248 * The component identifier is a dictionary member identifier or a 1249 named query parameter identifier that references a member that is 1250 not present in the component value, or whose value is malformed. 1251 E.g., the identifier is "example-dictionary";key="c" and the value 1252 of the Example-Dictionary header field is a=1, b=2, which does not 1253 have the c value. 1255 In the following non-normative example, the HTTP message being signed 1256 is the following request: 1258 POST /foo?param=Value&Pet=dog HTTP/1.1 1259 Host: example.com 1260 Date: Tue, 20 Apr 2021 02:07:55 GMT 1261 Content-Type: application/json 1262 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1263 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1264 Content-Length: 18 1266 {"hello": "world"} 1268 The covered components consist of the @method, @path, and @authority 1269 derived component identifiers followed by the Content-Digest, 1270 Content-Length, and Content-Type HTTP header fields, in order. The 1271 signature parameters consist of a creation timestamp of 1618884473 1272 and a key identifier of test-key-rsa-pss. Note that no explicit alg 1273 parameter is given here since the verifier is assumed by the 1274 application to correctly use the RSA PSS algorithm based on the 1275 identified key. The signature input string for this message with 1276 these parameters is: 1278 NOTE: '\' line wrapping per RFC 8792 1280 "@method": POST 1281 "@authority": example.com 1282 "@path": /foo 1283 "content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\ 1284 +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1285 "content-length": 18 1286 "content-type": application/json 1287 "@signature-params": ("@method" "@authority" "@path" \ 1288 "content-digest" "content-length" "content-type")\ 1289 ;created=1618884473;keyid="test-key-rsa-pss" 1291 Figure 1: Non-normative example Signature Input 1293 Note that the example signature input here, or anywhere else within 1294 this specification, does not include the final newline that ends the 1295 example. 1297 3. HTTP Message Signatures 1299 An HTTP Message Signature is a signature over a string generated from 1300 a subset of the components of an HTTP message in addition to metadata 1301 about the signature itself. When successfully verified against an 1302 HTTP message, an HTTP Message Signature provides cryptographic proof 1303 that the message is semantically equivalent to the message for which 1304 the signature was generated, with respect to the subset of message 1305 components that was signed. 1307 3.1. Creating a Signature 1309 Creation of an HTTP message signature is a process that takes as its 1310 input the message and the requirements for the application. The 1311 output is a signature value and set of signature parameters that can 1312 be applied to the message. 1314 In order to create a signature, a signer MUST follow the following 1315 algorithm: 1317 1. The signer chooses an HTTP signature algorithm and key material 1318 for signing. The signer MUST choose key material that is 1319 appropriate for the signature's algorithm, and that conforms to 1320 any requirements defined by the algorithm, such as key size or 1321 format. The mechanism by which the signer chooses the algorithm 1322 and key material is out of scope for this document. 1324 2. The signer sets the signature's creation time to the current 1325 time. 1327 3. If applicable, the signer sets the signature's expiration time 1328 property to the time at which the signature is to expire. The 1329 expiration is a hint to the verifier, expressing the time at 1330 which the signer is no longer willing to vouch for the safety of 1331 the signature. 1333 4. The signer creates an ordered set of component identifiers 1334 representing the message components to be covered by the 1335 signature, and attaches signature metadata parameters to this 1336 set. The serialized value of this is later used as the value of 1337 the Signature-Input field as described in Section 4.1. 1339 * Once an order of covered components is chosen, the order MUST 1340 NOT change for the life of the signature. 1342 * Each covered component identifier MUST be either an HTTP field 1343 in the message Section 2.1 or a derived component identifier 1344 listed in Section 2.2 or its associated registry. 1346 * Signers of a request SHOULD include some or all of the message 1347 control data in the covered components, such as the @method, 1348 @authority, @target-uri, or some combination thereof. 1350 * Signers SHOULD include the created signature metadata 1351 parameter to indicate when the signature was created. 1353 * The @signature-params derived component identifier is not 1354 explicitly listed in the list of covered component 1355 identifiers, because it is required to always be present as 1356 the last line in the signature input. This ensures that a 1357 signature always covers its own metadata. 1359 * Further guidance on what to include in this set and in what 1360 order is out of scope for this document. 1362 5. The signer creates the signature input string based on these 1363 signature parameters. (Section 2.3) 1365 6. The signer uses the HTTP_SIGN function to sign the signature 1366 input with the chosen signing algorithm using the key material 1367 chosen by the signer. The HTTP_SIGN primitive and several 1368 concrete signing algorithms are defined in in Section 3.3. 1370 7. The byte array output of the signature function is the HTTP 1371 message signature output value to be included in the Signature 1372 field as defined in Section 4.2. 1374 For example, given the HTTP message and signature parameters in the 1375 example in Section 2.3, the example signature input string is signed 1376 with the test-key-rsa-pss key in Appendix B.1.2 and the RSA PSS 1377 algorithm described in Section 3.3.1, giving the following message 1378 signature output value, encoded in Base64: 1380 NOTE: '\' line wrapping per RFC 8792 1382 HIbjHC5rS0BYaa9v4QfD4193TORw7u9edguPh0AW3dMq9WImrlFrCGUDih47vAxi4L2\ 1383 YRZ3XMJc1uOKk/J0ZmZ+wcta4nKIgBkKq0rM9hs3CQyxXGxHLMCy8uqK488o+9jrptQ\ 1384 +xFPHK7a9sRL1IXNaagCNN3ZxJsYapFj+JXbmaI5rtAdSfSvzPuBCh+ARHBmWuNo1Uz\ 1385 VVdHXrl8ePL4cccqlazIJdC4QEjrF+Sn4IxBQzTZsL9y9TP5FsZYzHvDqbInkTNigBc\ 1386 E9cKOYNFCn4D/WM7F6TNuZO9EgtzepLWcjTymlHzK7aXq6Am6sfOrpIC49yXjj3ae6H\ 1387 RalVc/g== 1389 Figure 2: Non-normative example signature value 1391 Note that the RSA PSS algorithm in use here is non-deterministic, 1392 meaning a different signature value will be created every time the 1393 algorithm is run. The signature value provided here can be validated 1394 against the given keys, but newly-generated signature values are not 1395 expected to match the example. See Section 7.19. 1397 3.2. Verifying a Signature 1399 Verification of an HTTP message signature is a process that takes as 1400 its input the message (including Signature and Signature-Input 1401 fields) and the requirements for the application. The output of the 1402 verification is either a positive verification or an error. 1404 In order to verify a signature, a verifier MUST follow the following 1405 algorithm: 1407 1. Parse the Signature and Signature-Input fields as described in 1408 Section 4.1 and Section 4.2, and extract the signatures to be 1409 verified. 1411 1. If there is more than one signature value present, determine 1412 which signature should be processed for this message based on 1413 the policy and configuration of the verifier. If an 1414 applicable signature is not found, produce an error. 1416 2. If the chosen Signature value does not have a corresponding 1417 Signature-Input value, produce an error. 1419 2. Parse the values of the chosen Signature-Input field as a 1420 parameterized structured field inner list item (inner-list) to 1421 get the signature parameters for the signature to be verified. 1423 3. Parse the value of the corresponding Signature field to get the 1424 byte array value of the signature to be verified. 1426 4. Examine the signature parameters to confirm that the signature 1427 meets the requirements described in this document, as well as any 1428 additional requirements defined by the application such as which 1429 message components are required to be covered by the signature. 1430 (Section 3.2.1) 1432 5. Determine the verification key material for this signature. If 1433 the key material is known through external means such as static 1434 configuration or external protocol negotiation, the verifier will 1435 use that. If the key is identified in the signature parameters, 1436 the verifier will dereference this to appropriate key material to 1437 use with the signature. The verifier has to determine the 1438 trustworthiness of the key material for the context in which the 1439 signature is presented. If a key is identified that the verifier 1440 does not know, does not trust for this request, or does not match 1441 something preconfigured, the verification MUST fail. 1443 6. Determine the algorithm to apply for verification: 1445 1. If the algorithm is known through external means such as 1446 static configuration or external protocol negotiation, the 1447 verifier will use this algorithm. 1449 2. If the algorithm is explicitly stated in the signature 1450 parameters using a value from the HTTP Message Signatures 1451 registry, the verifier will use the referenced algorithm. 1453 3. If the algorithm can be determined from the keying material, 1454 such as through an algorithm field on the key value itself, 1455 the verifier will use this algorithm. 1457 4. If the algorithm is specified in more that one location, such 1458 as through static configuration and the algorithm signature 1459 parameter, or the algorithm signature parameter and from the 1460 key material itself, the resolved algorithms MUST be the 1461 same. If the algorithms are not the same, the verifier MUST 1462 vail the verification. 1464 7. Use the received HTTP message and the signature's metadata to 1465 recreate the signature input, using the process described in 1466 Section 2.3. The value of the @signature-params input is the 1467 value of the Signature-Input field for this signature serialized 1468 according to the rules described in Section 2.2.1, not including 1469 the signature's label from the Signature-Input field. 1471 8. If the key material is appropriate for the algorithm, apply the 1472 appropriate HTTP_VERIFY cryptographic verification algorithm to 1473 the signature, recalculated signature input, key material, 1474 signature value. The HTTP_VERIFY primitive and several concrete 1475 algorithms are defined in Section 3.3. 1477 9. The results of the verification algorithm function are the final 1478 results of the cryptographic verification function. 1480 If any of the above steps fail or produce an error, the signature 1481 validation fails. 1483 For example, verifying the signature with the key sig1 of the 1484 following message with the test-key-rsa-pss key in Appendix B.1.2 and 1485 the RSA PSS algorithm described in Section 3.3.1: 1487 NOTE: '\' line wrapping per RFC 8792 1489 POST /foo?param=Value&Pet=dog HTTP/1.1 1490 Host: example.com 1491 Date: Tue, 20 Apr 2021 02:07:55 GMT 1492 Content-Type: application/json 1493 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1494 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1495 Content-Length: 18 1496 Signature-Input: sig1=("@method" "@authority" "@path" \ 1497 "content-digest" "content-length" "content-type")\ 1498 ;created=1618884473;keyid="test-key-rsa-pss" 1499 Signature: sig1=:HIbjHC5rS0BYaa9v4QfD4193TORw7u9edguPh0AW3dMq9WImrl\ 1500 FrCGUDih47vAxi4L2YRZ3XMJc1uOKk/J0ZmZ+wcta4nKIgBkKq0rM9hs3CQyxXGxH\ 1501 LMCy8uqK488o+9jrptQ+xFPHK7a9sRL1IXNaagCNN3ZxJsYapFj+JXbmaI5rtAdSf\ 1502 SvzPuBCh+ARHBmWuNo1UzVVdHXrl8ePL4cccqlazIJdC4QEjrF+Sn4IxBQzTZsL9y\ 1503 9TP5FsZYzHvDqbInkTNigBcE9cKOYNFCn4D/WM7F6TNuZO9EgtzepLWcjTymlHzK7\ 1504 aXq6Am6sfOrpIC49yXjj3ae6HRalVc/g==: 1506 {"hello": "world"} 1508 With the additional requirements that at least the method, path, 1509 authority, and cache-control be signed, and that the signature 1510 creation timestamp is recent enough at the time of verification, the 1511 verification passes. 1513 3.2.1. Enforcing Application Requirements 1515 The verification requirements specified in this document are intended 1516 as a baseline set of restrictions that are generally applicable to 1517 all use cases. Applications using HTTP Message Signatures MAY impose 1518 requirements above and beyond those specified by this document, as 1519 appropriate for their use case. 1521 Some non-normative examples of additional requirements an application 1522 might define are: 1524 * Requiring a specific set of header fields to be signed (e.g., 1525 Authorization, Digest). 1527 * Enforcing a maximum signature age from the time of the created 1528 time stamp. 1530 * Rejection of signatures past the expiration time in the expires 1531 time stamp. Note that the expiration time is a hint from the 1532 signer and that a verifier can always reject a signature ahead of 1533 its expiration time. 1535 * Prohibition of certain signature metadata parameters, such as 1536 runtime algorithm signaling with the alg parameter when the 1537 algorithm is determined from the key information. 1539 * Ensuring successful dereferencing of the keyid parameter to valid 1540 and appropriate key material. 1542 * Prohibiting the use of certain algorithms, or mandating the use of 1543 a specific algorithm. 1545 * Requiring keys to be of a certain size (e.g., 2048 bits vs. 1024 1546 bits). 1548 * Enforcing uniqueness of a nonce value. 1550 Application-specific requirements are expected and encouraged. When 1551 an application defines additional requirements, it MUST enforce them 1552 during the signature verification process, and signature verification 1553 MUST fail if the signature does not conform to the application's 1554 requirements. 1556 Applications MUST enforce the requirements defined in this document. 1557 Regardless of use case, applications MUST NOT accept signatures that 1558 do not conform to these requirements. 1560 3.3. Signature Algorithm Methods 1562 HTTP Message signatures MAY use any cryptographic digital signature 1563 or MAC method that is appropriate for the key material, environment, 1564 and needs of the signer and verifier. 1566 Each signature algorithm method takes as its input the signature 1567 input string defined in Section 2.3 as a byte array (M), the signing 1568 key material (Ks), and outputs the signature output as a byte array 1569 (S): 1571 HTTP_SIGN (M, Ks) -> S 1573 Each verification algorithm method takes as its input the 1574 recalculated signature input string defined in Section 2.3 as a byte 1575 array (M), the verification key material (Kv), and the presented 1576 signature to be verified as a byte array (S) and outputs the 1577 verification result (V) as a boolean: 1579 HTTP_VERIFY (M, Kv, S) -> V 1580 This section contains several common algorithm methods. The method 1581 to use can be communicated through the algorithm signature parameter 1582 defined in Section 2.2.1, by reference to the key material, or 1583 through mutual agreement between the signer and verifier. 1585 3.3.1. RSASSA-PSS using SHA-512 1587 To sign using this algorithm, the signer applies the RSASSA-PSS-SIGN 1588 (K, M) function [RFC8017] with the signer's private signing key (K) 1589 and the signature input string (M) (Section 2.3). The mask 1590 generation function is MGF1 as specified in [RFC8017] with a hash 1591 function of SHA-512 [RFC6234]. The salt length (sLen) is 64 bytes. 1592 The hash function (Hash) SHA-512 [RFC6234] is applied to the 1593 signature input string to create the digest content to which the 1594 digital signature is applied. The resulting signed content byte 1595 array (S) is the HTTP message signature output used in Section 3.1. 1597 To verify using this algorithm, the verifier applies the RSASSA-PSS- 1598 VERIFY ((n, e), M, S) function [RFC8017] using the public key portion 1599 of the verification key material ((n, e)) and the signature input 1600 string (M) re-created as described in Section 3.2. The mask 1601 generation function is MGF1 as specified in [RFC8017] with a hash 1602 function of SHA-512 [RFC6234]. The salt length (sLen) is 64 bytes. 1603 The hash function (Hash) SHA-512 [RFC6234] is applied to the 1604 signature input string to create the digest content to which the 1605 verification function is applied. The verifier extracts the HTTP 1606 message signature to be verified (S) as described in Section 3.2. 1607 The results of the verification function indicate if the signature 1608 presented is valid. 1610 Note that the output of RSA PSS algorithms are non-deterministic, and 1611 therefore it is not correct to re-calculate a new signature on the 1612 signature input and compare the results to an existing signature. 1613 Instead, the verification algorithm defined here needs to be used. 1614 See Section 7.19. 1616 Use of this algorithm can be indicated at runtime using the rsa-pss- 1617 sha512 value for the alg signature parameter. 1619 3.3.2. RSASSA-PKCS1-v1_5 using SHA-256 1621 To sign using this algorithm, the signer applies the RSASSA- 1622 PKCS1-V1_5-SIGN (K, M) function [RFC8017] with the signer's private 1623 signing key (K) and the signature input string (M) (Section 2.3). 1624 The hash SHA-256 [RFC6234] is applied to the signature input string 1625 to create the digest content to which the digital signature is 1626 applied. The resulting signed content byte array (S) is the HTTP 1627 message signature output used in Section 3.1. 1629 To verify using this algorithm, the verifier applies the RSASSA- 1630 PKCS1-V1_5-VERIFY ((n, e), M, S) function [RFC8017] using the public 1631 key portion of the verification key material ((n, e)) and the 1632 signature input string (M) re-created as described in Section 3.2. 1633 The hash function SHA-256 [RFC6234] is applied to the signature input 1634 string to create the digest content to which the verification 1635 function is applied. The verifier extracts the HTTP message 1636 signature to be verified (S) as described in Section 3.2. The 1637 results of the verification function are compared to the http message 1638 signature to determine if the signature presented is valid. 1640 Use of this algorithm can be indicated at runtime using the rsa- 1641 v1_5-sha256 value for the alg signature parameter. 1643 3.3.3. HMAC using SHA-256 1645 To sign and verify using this algorithm, the signer applies the HMAC 1646 function [RFC2104] with the shared signing key (K) and the signature 1647 input string (text) (Section 2.3). The hash function SHA-256 1648 [RFC6234] is applied to the signature input string to create the 1649 digest content to which the HMAC is applied, giving the signature 1650 result. 1652 For signing, the resulting value is the HTTP message signature output 1653 used in Section 3.1. 1655 For verification, the verifier extracts the HTTP message signature to 1656 be verified (S) as described in Section 3.2. The output of the HMAC 1657 function is compared to the value of the HTTP message signature, and 1658 the results of the comparison determine the validity of the signature 1659 presented. 1661 Use of this algorithm can be indicated at runtime using the hmac- 1662 sha256 value for the alg signature parameter. 1664 3.3.4. ECDSA using curve P-256 DSS and SHA-256 1666 To sign using this algorithm, the signer applies the ECDSA algorithm 1667 [FIPS186-4] using curve P-256 with the signer's private signing key 1668 and the signature input string (Section 2.3). The hash SHA-256 1669 [RFC6234] is applied to the signature input string to create the 1670 digest content to which the digital signature is applied, (M). The 1671 signature algorithm returns two integer values, r and s. These are 1672 both encoded in big-endian unsigned integers, zero-padded to 1673 32-octets each. These encoded values are concatenated into a single 1674 64-octet array consisting of the encoded value of r followed by the 1675 encoded value of s. The resulting concatenation of (r, s) is byte 1676 array of the HTTP message signature output used in Section 3.1. 1678 To verify using this algorithm, the verifier applies the ECDSA 1679 algorithm [FIPS186-4] using the public key portion of the 1680 verification key material and the signature input string re-created 1681 as described in Section 3.2. The hash function SHA-256 [RFC6234] is 1682 applied to the signature input string to create the digest content to 1683 which the signature verification function is applied, (M). The 1684 verifier extracts the HTTP message signature to be verified (S) as 1685 described in Section 3.2. This value is a 64-octet array consisting 1686 of the encoded values of r and s concatenated in order. These are 1687 both encoded in big-endian unsigned integers, zero-padded to 1688 32-octets each. The resulting signature value (r, s) is used as 1689 input to the signature verification function. The results of the 1690 verification function indicate if the signature presented is valid. 1692 Note that the output of ECDSA algorithms are non-deterministic, and 1693 therefore it is not correct to re-calculate a new signature on the 1694 signature input and compare the results to an existing signature. 1695 Instead, the verification algorithm defined here needs to be used. 1696 See Section 7.19. 1698 Use of this algorithm can be indicated at runtime using the ecdsa- 1699 p256-sha256 value for the alg signature parameter. 1701 3.3.5. EdDSA using curve edwards25519 1703 To sign using this algorithm, the signer applies the Ed25519 1704 algorithm Section 5.1.6 of [RFC8032] with the signer's private 1705 signing key and the signature input string (Section 2.3). The 1706 signature input string is taken as the input message (M) with no pre- 1707 hash function. The signature is a 64-octet concatenation of R and S 1708 as specified in Section 5.1.6 of [RFC8032], and this is taken as a 1709 byte array for the HTTP message signature output used in Section 3.1. 1711 To verify using this algorithm, the signer applies the Ed25519 1712 algorithm Section 5.1.7 of [RFC8032] using the public key portion of 1713 the verification key material (A) and the signature input string re- 1714 created as described in Section 3.2. The signature input string is 1715 taken as the input message (M) with no pre-hash function. The 1716 signature to be verified is processed as the 64-octet concatenation 1717 of R and S as specified in Section 5.1.7 of [RFC8032]. The results 1718 of the verification function indicate if the signature presented is 1719 valid. 1721 Use of this algorithm can be indicated at runtime using the ed25519 1722 value for the alg signature parameter. 1724 3.3.6. JSON Web Signature (JWS) algorithms 1726 If the signing algorithm is a JOSE signing algorithm from the JSON 1727 Web Signature and Encryption Algorithms Registry established by 1728 [RFC7518], the JWS algorithm definition determines the signature and 1729 hashing algorithms to apply for both signing and verification. 1731 For both signing and verification, the HTTP messages signature input 1732 string (Section 2.3) is used as the entire "JWS Signing Input". The 1733 JOSE Header defined in [RFC7517] is not used, and the signature input 1734 string is not first encoded in Base64 before applying the algorithm. 1735 The output of the JWS signature is taken as a byte array prior to the 1736 Base64url encoding used in JOSE. 1738 The JWS algorithm MUST NOT be none and MUST NOT be any algorithm with 1739 a JOSE Implementation Requirement of Prohibited. 1741 There is no use of the explicit alg signature parameter when using 1742 JOSE signing algorithms, as they can be signaled using JSON Web Keys 1743 or other mechanisms. 1745 4. Including a Message Signature in a Message 1747 Message signatures can be included within an HTTP message via the 1748 Signature-Input and Signature HTTP fields, both defined within this 1749 specification. When attached to a message, an HTTP message signature 1750 is identified by a label. This label MUST be unique within a given 1751 HTTP message and MUST be used in both the Signature-Input and 1752 Signature. The label is chosen by the signer, except where a 1753 specific label is dictated by protocol negotiations. 1755 An HTTP message signature MUST use both fields containing the same 1756 labels: the Signature HTTP field contains the signature value, while 1757 the Signature-Input HTTP field identifies the covered components and 1758 parameters that describe how the signature was generated. Each field 1759 contains labeled values and MAY contain multiple labeled values, 1760 where the labels determine the correlation between the Signature and 1761 Signature-Input fields. 1763 4.1. The 'Signature-Input' HTTP Field 1765 The Signature-Input HTTP field is a Dictionary Structured Field 1766 [RFC8941] containing the metadata for one or more message signatures 1767 generated from components within the HTTP message. Each member 1768 describes a single message signature. The member's name is an 1769 identifier that uniquely identifies the message signature within the 1770 context of the HTTP message. The member's value is the serialization 1771 of the covered components including all signature metadata 1772 parameters, using the serialization process defined in Section 2.2.1. 1774 NOTE: '\' line wrapping per RFC 8792 1776 Signature-Input: sig1=("@method" "@target-uri" "host" "date" \ 1777 "cache-control");created=1618884475\ 1778 ;keyid="test-key-rsa-pss" 1780 To facilitate signature validation, the Signature-Input field value 1781 MUST contain the same serialized value used in generating the 1782 signature input string's @signature-params value. 1784 The signer MAY include the Signature-Input field as a trailer to 1785 facilitate signing a message after its content has been processed by 1786 the signer. However, since intermediaries are allowed to drop 1787 trailers as per [SEMANTICS], it is RECOMMENDED that the Signature- 1788 Input HTTP field be included only as a header to avoid signatures 1789 being inadvertently stripped from a message. 1791 Multiple Signature-Input fields MAY be included in a single HTTP 1792 message. The signature labels MUST be unique across all field 1793 values. 1795 4.2. The 'Signature' HTTP Field 1797 The Signature HTTP field is a Dictionary Structured field [RFC8941] 1798 containing one or more message signatures generated from components 1799 within the HTTP message. Each member's name is a signature 1800 identifier that is present as a member name in the Signature-Input 1801 Structured field within the HTTP message. Each member's value is a 1802 Byte Sequence containing the signature value for the message 1803 signature identified by the member name. Any member in the Signature 1804 HTTP field that does not have a corresponding member in the HTTP 1805 message's Signature-Input HTTP field MUST be ignored. 1807 NOTE: '\' line wrapping per RFC 8792 1809 Signature: sig1=:P0wLUszWQjoi54udOtydf9IWTfNhy+r53jGFj9XZuP4uKwxyJo\ 1810 1RSHi+oEF1FuX6O29d+lbxwwBao1BAgadijW+7O/PyezlTnqAOVPWx9GlyntiCiHz\ 1811 C87qmSQjvu1CFyFuWSjdGa3qLYYlNm7pVaJFalQiKWnUaqfT4LyttaXyoyZW84jS8\ 1812 gyarxAiWI97mPXU+OVM64+HVBHmnEsS+lTeIsEQo36T3NFf2CujWARPQg53r58Rmp\ 1813 Z+J9eKR2CD6IJQvacn5A4Ix5BUAVGqlyp8JYm+S/CWJi31PNUjRRCusCVRj05NrxA\ 1814 BNFv3r5S9IXf2fYJK+eyW4AiGVMvMcOg==: 1816 The signer MAY include the Signature field as a trailer to facilitate 1817 signing a message after its content has been processed by the signer. 1818 However, since intermediaries are allowed to drop trailers as per 1819 [SEMANTICS], it is RECOMMENDED that the Signature-Input HTTP field be 1820 included only as a header to avoid signatures being inadvertently 1821 stripped from a message. 1823 Multiple Signature fields MAY be included in a single HTTP message. 1824 The signature labels MUST be unique across all field values. 1826 4.3. Multiple Signatures 1828 Multiple distinct signatures MAY be included in a single message. 1829 Each distinct signature MUST have a unique label. Since Signature- 1830 Input and Signature are both defined as Dictionary Structured fields, 1831 they can be used to include multiple signatures within the same HTTP 1832 message by using distinct signature labels. These multiple 1833 signatures could be added all by the same signer or could come from 1834 several different signers. For example, a signer may include 1835 multiple signatures signing the same message components with 1836 different keys or algorithms to support verifiers with different 1837 capabilities, or a reverse proxy may include information about the 1838 client in fields when forwarding the request to a service host, 1839 including a signature over the client's original signature values. 1841 The following is a non-normative example starts with a signed request 1842 from the client. The proxy takes this request validates the client's 1843 signature. 1845 NOTE: '\' line wrapping per RFC 8792 1847 POST /foo?param=Value&Pet=dog HTTP/1.1 1848 Host: example.com 1849 Date: Tue, 20 Apr 2021 02:07:55 GMT 1850 Content-Type: application/json 1851 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1852 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1853 Content-Length: 18 1854 Signature-Input: sig1=("@method" "@authority" "@path" \ 1855 "content-digest" "content-length" "content-type")\ 1856 ;created=1618884475;keyid="test-key-rsa-pss" 1857 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1858 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8Br\ 1859 c8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINTEzpx\ 1860 jqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr65+BXe\ 1861 TG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZElYyUKaAI\ 1862 jZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1864 {"hello": "world"} 1866 The proxy then alters the message before forwarding it on to the 1867 origin server, changing the target host and adding the Forwarded 1868 header defined in [RFC7239]. 1870 NOTE: '\' line wrapping per RFC 8792 1872 POST /foo?param=Value&Pet=dog HTTP/1.1 1873 Host: origin.host.internal.example 1874 Date: Tue, 20 Apr 2021 02:07:56 GMT 1875 Content-Type: application/json 1876 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1877 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1878 Content-Length: 18 1879 Forwarded: for=192.0.2.123 1880 Signature-Input: sig1=("@method" "@authority" "@path" \ 1881 "content-digest" "content-length" "content-type")\ 1882 ;created=1618884475;keyid="test-key-rsa-pss" 1883 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1884 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8Br\ 1885 c8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINTEzpx\ 1886 jqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr65+BXe\ 1887 TG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZElYyUKaAI\ 1888 jZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1890 {"hello": "world"} 1891 The proxy includes the client's signature value under the label sig1, 1892 which the proxy signs in addition to the Forwarded header. Note that 1893 since the client's signature already covers the client's Signature- 1894 Input value for sig1, this value is transitively covered by the 1895 proxy's signature and need not be added explicitly. The proxy 1896 identifies its own key and algorithm and, in this example, includes 1897 an expiration for the signature to indicate to downstream systems 1898 that the proxy will not vouch for this signed message past this short 1899 time window. This results in a signature input string of: 1901 NOTE: '\' line wrapping per RFC 8792 1903 "signature";key="sig1": :LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8\ 1904 r5MW9S0RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkB\ 1905 IS1M8Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpW\ 1906 INTEzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2T\ 1907 r65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZEl\ 1908 YyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1909 "forwarded": for=192.0.2.123 1910 "@signature-params": ("signature";key="sig1" "forwarded")\ 1911 ;created=1618884480;expires=1618884540;keyid="test-key-rsa"\ 1912 ;alg="rsa-v1_5-sha256" 1914 And a signature output value of: 1916 NOTE: '\' line wrapping per RFC 8792 1918 G1WLTL4/9PGSKEQbSAMypZNk+I2dpLJ6qvl2JISahlP31OO/QEUd8/HdO2O7vYLi5k3\ 1919 JIiAK3UPK4U+kvJZyIUidsiXlzRI+Y2se3SGo0D8dLfhG95bKr6ukYXl60QHpsGRTfS\ 1920 iwdtvYKXGpKNrMlISJYd+oGrGRyI9gbCy0aFhc6I/okIMLeK4g9PgzpC3YTwhUQ98KI\ 1921 BNLWHgREfBgJxjPbxFlsgJ9ykPviLj8GKJ81HwsK3XM9P7WaS7fMGOt8h1kSqgkZQB9\ 1922 YqiIo+WhHvJa7iPy8QrYFKzx9BBEY6AwfStZAsXXz3LobZseyxsYcLJLs8rY0wVA9NP\ 1923 sxKrHGA== 1925 These values are added to the HTTP request message by the proxy. The 1926 original signature is included under the identifier sig1, and the 1927 reverse proxy's signature is included under the label proxy_sig. The 1928 proxy uses the key test-key-rsa to create its signature using the 1929 rsa-v1_5-sha256 signature algorithm, while the client's original 1930 signature was made using the key id of test-key-rsa-pss and an RSA 1931 PSS signature algorithm. 1933 NOTE: '\' line wrapping per RFC 8792 1935 POST /foo?param=Value&Pet=dog HTTP/1.1 1936 Host: origin.host.internal.example 1937 Date: Tue, 20 Apr 2021 02:07:56 GMT 1938 Content-Type: application/json 1939 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1940 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1941 Content-Length: 18 1942 Forwarded: for=192.0.2.123 1943 Signature-Input: sig1=("@method" "@authority" "@path" \ 1944 "content-digest" "content-length" "content-type")\ 1945 ;created=1618884475;keyid="test-key-rsa-pss", \ 1946 proxy_sig=("signature";key="sig1" "forwarded")\ 1947 ;created=1618884480;expires=1618884540;keyid="test-key-rsa"\ 1948 ;alg="rsa-v1_5-sha256" 1949 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1950 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8\ 1951 Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINT\ 1952 EzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr\ 1953 65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZE\ 1954 lYyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==:, \ 1955 proxy_sig=:G1WLTL4/9PGSKEQbSAMypZNk+I2dpLJ6qvl2JISahlP31OO/QEUd8/\ 1956 HdO2O7vYLi5k3JIiAK3UPK4U+kvJZyIUidsiXlzRI+Y2se3SGo0D8dLfhG95bKr\ 1957 6ukYXl60QHpsGRTfSiwdtvYKXGpKNrMlISJYd+oGrGRyI9gbCy0aFhc6I/okIML\ 1958 eK4g9PgzpC3YTwhUQ98KIBNLWHgREfBgJxjPbxFlsgJ9ykPviLj8GKJ81HwsK3X\ 1959 M9P7WaS7fMGOt8h1kSqgkZQB9YqiIo+WhHvJa7iPy8QrYFKzx9BBEY6AwfStZAs\ 1960 XXz3LobZseyxsYcLJLs8rY0wVA9NPsxKrHGA==: 1962 {"hello": "world"} 1964 The proxy's signature and the client's original signature can be 1965 verified independently for the same message, based on the needs of 1966 the application. Since the proxy's signature covers the client 1967 signature, the backend service fronted by the proxy can trust that 1968 the proxy has validated the incoming signature. 1970 5. Requesting Signatures 1972 While a signer is free to attach a signature to a request or response 1973 without prompting, it is often desirable for a potential verifier to 1974 signal that it expects a signature from a potential signer using the 1975 Accept-Signature field. 1977 The message to which the requested signature is applied is known as 1978 the "target message". When the Accept-Signature field is sent in an 1979 HTTP Request message, the field indicates that the client desires the 1980 server to sign the response using the identified parameters and the 1981 target message is the response to this request. All responses from 1982 resources that support such signature negotiation SHOULD either be 1983 uncacheable or contain a Vary header field that lists Accept- 1984 Signature, in order to prevent a cache from returning a response with 1985 a signature intended for a different request. 1987 When the Accept-Signature field is used in an HTTP Response message, 1988 the field indicates that the server desires the client to sign its 1989 next request to the server with the identified parameters, and the 1990 target message is the client's next request. The client can choose 1991 to also continue signing future requests to the same server in the 1992 same way. 1994 The target message of an Accept-Signature field MUST include all 1995 labeled signatures indicated in the Accept-Header signature, each 1996 covering the same identified components of the Accept-Signature 1997 field. 1999 The sender of an Accept-Signature field MUST include identifiers that 2000 are appropriate for the type of the target message. For example, if 2001 the target message is a response, the identifiers can not include the 2002 @status identifier. 2004 5.1. The Accept-Signature Field 2006 The Accept-Signature HTTP header field is a Dictionary Structured 2007 field [RFC8941] containing the metadata for one or more requested 2008 message signatures to be generated from message components of the 2009 target HTTP message. Each member describes a single message 2010 signature. The member's name is an identifier that uniquely 2011 identifies the requested message signature within the context of the 2012 target HTTP message. The member's value is the serialization of the 2013 desired covered components of the target message, including any 2014 allowed signature metadata parameters, using the serialization 2015 process defined in Section 2.2.1. 2017 NOTE: '\' line wrapping per RFC 8792 2019 Accept-Signature: sig1=("@method" "@target-uri" "host" "date" \ 2020 "cache-control")\ 2021 ;keyid="test-key-rsa-pss" 2023 The requested signature MAY include parameters, such as a desired 2024 algorithm or key identifier. These parameters MUST NOT include 2025 parameters that the signer is expected to generate, including the 2026 created and nonce parameters. 2028 5.2. Processing an Accept-Signature 2030 The receiver of an Accept-Signature field fulfills that header as 2031 follows: 2033 1. Parse the field value as a Dictionary 2035 2. For each member of the dictionary: 2037 1. The name of the member is the label of the output signature 2038 as specified in Section 4.1 2040 2. Parse the value of the member to obtain the set of covered 2041 component identifiers 2043 3. Process the requested parameters, such as the signing 2044 algorithm and key material. If any requested parameters 2045 cannot be fulfilled, or if the requested parameters conflict 2046 with those deemed appropriate to the target message, the 2047 process fails and returns an error. 2049 4. Select any additional parameters necessary for completing the 2050 signature 2052 5. Create the Signature-Input and Signature header values and 2053 associate them with the label 2055 3. Optionally create any additional Signature-Input and Signature 2056 values, with unique labels not found in the Accept-Signature 2057 field 2059 4. Combine all labeled Signature-Input and Signature values and 2060 attach both headers to the target message 2062 Note that by this process, a signature applied to a target message 2063 MUST have the same label, MUST have the same set of covered 2064 component, and MAY have additional parameters. Also note that the 2065 target message MAY include additional signatures not specified by the 2066 Accept-Signature field. 2068 6. IANA Considerations 2070 IANA is requested to create three registries and to populate those 2071 registries with initial values as described in this section. 2073 6.1. HTTP Signature Algorithms Registry 2075 This document defines HTTP Signature Algorithms, for which IANA is 2076 asked to create and maintain a new registry titled "HTTP Signature 2077 Algorithms". Initial values for this registry are given in 2078 Section 6.1.2. Future assignments and modifications to existing 2079 assignment are to be made through the Expert Review registration 2080 policy [RFC8126] and shall follow the template presented in 2081 Section 6.1.1. 2083 Algorithms referenced by algorithm identifiers have to be fully 2084 defined with all parameters fixed. Algorithm identifiers in this 2085 registry are to be interpreted as whole string values and not as a 2086 combination of parts. That is to say, it is expected that 2087 implementors understand rsa-pss-sha512 as referring to one specific 2088 algorithm with its hash, mask, and salt values set as defined here. 2089 Implementors do not parse out the rsa, pss, and sha512 portions of 2090 the identifier to determine parameters of the signing algorithm from 2091 the string. 2093 Algorithms added to this registry MUST NOT be aliases for other 2094 entries in the registry. 2096 6.1.1. Registration Template 2098 Algorithm Name: 2099 An identifier for the HTTP Signature Algorithm. The name MUST be 2100 an ASCII string consisting only of lower-case characters ("a" - 2101 "z"), digits ("0" - "9"), and hyphens ("-"), and SHOULD NOT exceed 2102 20 characters in length. The identifier MUST be unique within the 2103 context of the registry. 2105 Status: 2106 A brief text description of the status of the algorithm. The 2107 description MUST begin with one of "Active" or "Deprecated", and 2108 MAY provide further context or explanation as to the reason for 2109 the status. 2111 Description: 2112 A brief description of the algorithm used to sign the signature 2113 input string. 2115 Specification document(s): 2116 Reference to the document(s) that specify the token endpoint 2117 authorization method, preferably including a URI that can be used 2118 to retrieve a copy of the document(s). An indication of the 2119 relevant sections may also be included but is not required. 2121 6.1.2. Initial Contents 2123 +===================+========+===================+===============+ 2124 | Algorithm Name | Status | Description | Specification | 2125 | | | | document(s) | 2126 +===================+========+===================+===============+ 2127 | rsa-pss-sha512 | Active | RSASSA-PSS using | [[This | 2128 | | | SHA-512 | document]], | 2129 | | | | Section 3.3.1 | 2130 +-------------------+--------+-------------------+---------------+ 2131 | rsa-v1_5-sha256 | Active | RSASSA-PKCS1-v1_5 | [[This | 2132 | | | using SHA-256 | document]], | 2133 | | | | Section 3.3.2 | 2134 +-------------------+--------+-------------------+---------------+ 2135 | hmac-sha256 | Active | HMAC using | [[This | 2136 | | | SHA-256 | document]], | 2137 | | | | Section 3.3.3 | 2138 +-------------------+--------+-------------------+---------------+ 2139 | ecdsa-p256-sha256 | Active | ECDSA using curve | [[This | 2140 | | | P-256 DSS and | document]], | 2141 | | | SHA-256 | Section 3.3.4 | 2142 +-------------------+--------+-------------------+---------------+ 2143 | ed25519 | Active | Edwards Curve DSA | [[This | 2144 | | | using curve | document]], | 2145 | | | edwards25519 | Section 3.3.5 | 2146 +-------------------+--------+-------------------+---------------+ 2148 Table 1 2150 6.2. HTTP Signature Metadata Parameters Registry 2152 This document defines the signature parameters structure, the values 2153 of which may have parameters containing metadata about a message 2154 signature. IANA is asked to create and maintain a new registry 2155 titled "HTTP Signature Metadata Parameters" to record and maintain 2156 the set of parameters defined for use with member values in the 2157 signature parameters structure. Initial values for this registry are 2158 given in Section 6.2.2. Future assignments and modifications to 2159 existing assignments are to be made through the Expert Review 2160 registration policy [RFC8126] and shall follow the template presented 2161 in Section 6.2.1. 2163 6.2.1. Registration Template 2165 Name: 2167 An identifier for the HTTP signature metadata parameter. The name 2168 MUST be an ASCII string consisting only of lower-case characters 2169 ("a" - "z"), digits ("0" - "9"), and hyphens ("-"), and SHOULD NOT 2170 exceed 20 characters in length. The identifier MUST be unique 2171 within the context of the registry. 2173 Description: 2174 A brief description of the metadata parameter and what it 2175 represents. 2177 Specification document(s): 2178 Reference to the document(s) that specify the token endpoint 2179 authorization method, preferably including a URI that can be used 2180 to retrieve a copy of the document(s). An indication of the 2181 relevant sections may also be included but is not required. 2183 6.2.2. Initial Contents 2185 The table below contains the initial contents of the HTTP Signature 2186 Metadata Parameters Registry. Each row in the table represents a 2187 distinct entry in the registry. 2189 +=========+===============================+==================+ 2190 | Name | Description | Specification | 2191 | | | document(s) | 2192 +=========+===============================+==================+ 2193 | alg | Explicitly declared signature | Section 2.2.1 of | 2194 | | algorithm | this document | 2195 +---------+-------------------------------+------------------+ 2196 | created | Timestamp of signature | Section 2.2.1 of | 2197 | | creation | this document | 2198 +---------+-------------------------------+------------------+ 2199 | expires | Timestamp of proposed | Section 2.2.1 of | 2200 | | signature expiration | this document | 2201 +---------+-------------------------------+------------------+ 2202 | keyid | Key identifier for the | Section 2.2.1 of | 2203 | | signing and verification keys | this document | 2204 | | used to create this signature | | 2205 +---------+-------------------------------+------------------+ 2206 | nonce | A single-use nonce value | Section 2.2.1 of | 2207 | | | this document | 2208 +---------+-------------------------------+------------------+ 2210 Table 2: Initial contents of the HTTP Signature Metadata 2211 Parameters Registry. 2213 6.3. HTTP Signature Derived Component Identifiers Registry 2215 This document defines a method for canonicalizing HTTP message 2216 components, including components that can be derived from the context 2217 of the HTTP message outside of the HTTP fields. These components are 2218 identified by a unique string, known as the component identifier. 2219 Component identifiers for derived components always start with the 2220 "@" (at) symbol to distinguish them from HTTP header fields. IANA is 2221 asked to create and maintain a new registry typed "HTTP Signature 2222 Derived Component Identifiers" to record and maintain the set of non- 2223 field component identifiers and the methods to produce their 2224 associated component values. Initial values for this registry are 2225 given in Section 6.3.2. Future assignments and modifications to 2226 existing assignments are to be made through the Expert Review 2227 registration policy [RFC8126] and shall follow the template presented 2228 in Section 6.3.1. 2230 6.3.1. Registration Template 2232 Identifier: 2233 An identifier for the HTTP derived component identifier. The name 2234 MUST begin with the "@" character followed by an ASCII string 2235 consisting only of lower-case characters ("a" - "z"), digits ("0" 2236 - "9"), and hyphens ("-"), and SHOULD NOT exceed 20 characters in 2237 length. The identifier MUST be unique within the context of the 2238 registry. 2240 Status: 2241 A brief text description of the status of the algorithm. The 2242 description MUST begin with one of "Active" or "Deprecated", and 2243 MAY provide further context or explanation as to the reason for 2244 the status. 2246 Target: 2247 The valid message targets for the derived parameter. MUST be one 2248 of the values "Request", "Request, Response", "Request, Related- 2249 Response", or "Related-Response". The semantics of these are 2250 defined in Section 2.2. 2252 Specification document(s): 2253 Reference to the document(s) that specify the token endpoint 2254 authorization method, preferably including a URI that can be used 2255 to retrieve a copy of the document(s). An indication of the 2256 relevant sections may also be included but is not required. 2258 6.3.2. Initial Contents 2260 The table below contains the initial contents of the HTTP Signature 2261 Derived Component Identifiers Registry. 2263 +===================+========+==================+==================+ 2264 | Identifier | Status | Target | Specification | 2265 | | | | document(s) | 2266 +===================+========+==================+==================+ 2267 | @signature-params | Active | Request, | Section 2.2.1 of | 2268 | | | Response | this document | 2269 +-------------------+--------+------------------+------------------+ 2270 | @method | Active | Request, | Section 2.2.2 of | 2271 | | | Related-Response | this document | 2272 +-------------------+--------+------------------+------------------+ 2273 | @authority | Active | Request, | Section 2.2.4 of | 2274 | | | Related-Response | this document | 2275 +-------------------+--------+------------------+------------------+ 2276 | @scheme | Active | Request, | Section 2.2.5 of | 2277 | | | Related-Response | this document | 2278 +-------------------+--------+------------------+------------------+ 2279 | @target-uri | Active | Request, | Section 2.2.3 of | 2280 | | | Related-Response | this document | 2281 +-------------------+--------+------------------+------------------+ 2282 | @request-target | Active | Request, | Section 2.2.6 of | 2283 | | | Related-Response | this document | 2284 +-------------------+--------+------------------+------------------+ 2285 | @path | Active | Request, | Section 2.2.7 of | 2286 | | | Related-Response | this document | 2287 +-------------------+--------+------------------+------------------+ 2288 | @query | Active | Request, | Section 2.2.8 of | 2289 | | | Related-Response | this document | 2290 +-------------------+--------+------------------+------------------+ 2291 | @query-params | Active | Request, | Section 2.2.9 of | 2292 | | | Related-Response | this document | 2293 +-------------------+--------+------------------+------------------+ 2294 | @status | Active | Response | Section 2.2.10 | 2295 | | | | of this document | 2296 +-------------------+--------+------------------+------------------+ 2297 | @request-response | Active | Related-Response | Section 2.2.11 | 2298 | | | | of this document | 2299 +-------------------+--------+------------------+------------------+ 2301 Table 3: Initial contents of the HTTP Signature Derived 2302 Component Identifiers Registry. 2304 7. Security Considerations 2306 In order for an HTTP message to be considered covered by a signature, 2307 all of the following conditions have to be true: 2309 * a signature is expected or allowed on the message by the verifier 2311 * the signature exists on the message 2313 * the signature is verified against the identified key material and 2314 algorithm 2316 * the key material and algorithm are appropriate for the context of 2317 the message 2319 * the signature is within expected time boundaries 2321 * the signature covers the expected content, including any critical 2322 components 2324 7.1. Signature Verification Skipping 2326 HTTP Message Signatures only provide security if the signature is 2327 verified by the verifier. Since the message to which the signature 2328 is attached remains a valid HTTP message without the signature 2329 fields, it is possible for a verifier to ignore the output of the 2330 verification function and still process the message. Common reasons 2331 for this could be relaxed requirements in a development environment 2332 or a temporary suspension of enforcing verification during debugging 2333 an overall system. Such temporary suspensions are difficult to 2334 detect under positive-example testing since a good signature will 2335 always trigger a valid response whether or not it has been checked. 2337 To detect this, verifiers should be tested using both valid and 2338 invalid signatures, ensuring that the invalid signature fails as 2339 expected. 2341 7.2. Use of TLS 2343 The use of HTTP Message Signatures does not negate the need for TLS 2344 or its equivalent to protect information in transit. Message 2345 signatures provide message integrity over the covered message 2346 components but do not provide any confidentiality for the 2347 communication between parties. 2349 TLS provides such confidentiality between the TLS endpoints. As part 2350 of this, TLS also protects the signature data itself from being 2351 captured by an attacker, which is an important step in preventing 2352 signature replay (Section 7.3). 2354 When TLS is used, it needs to be deployed according to the 2355 recommendations in [BCP195]. 2357 7.3. Signature Replay 2359 Since HTTP Message Signatures allows sub-portions of the HTTP message 2360 to be signed, it is possible for two different HTTP messages to 2361 validate against the same signature. The most extreme form of this 2362 would be a signature over no message components. If such a signature 2363 were intercepted, it could be replayed at will by an attacker, 2364 attached to any HTTP message. Even with sufficient component 2365 coverage, a given signature could be applied to two similar HTTP 2366 messages, allowing a message to be replayed by an attacker with the 2367 signature intact. 2369 To counteract these kinds of attacks, it's first important for the 2370 signer to cover sufficient portions of the message to differentiate 2371 it from other messages. In addition, the signature can use the nonce 2372 signature parameter to provide a per-message unique value to allow 2373 the verifier to detect replay of the signature itself if a nonce 2374 value is repeated. Furthermore, the signer can provide a timestamp 2375 for when the signature was created and a time at which the signer 2376 considers the signature to be invalid, limiting the utility of a 2377 captured signature value. 2379 If a verifier wants to trigger a new signature from a signer, it can 2380 send the Accept-Signature header field with a new nonce parameter. 2381 An attacker that is simply replaying a signature would not be able to 2382 generate a new signature with the chosen nonce value. 2384 7.4. Insufficient Coverage 2386 Any portions of the message not covered by the signature are 2387 susceptible to modification by an attacker without affecting the 2388 signature. An attacker can take advantage of this by introducing a 2389 header field or other message component that will change the 2390 processing of the message but will not be covered by the signature. 2391 Such an altered message would still pass signature verification, but 2392 when the verifier processes the message as a whole, the unsigned 2393 content injected by the attacker would subvert the trust conveyed by 2394 the valid signature and change the outcome of processing the message. 2396 To combat this, an application of this specification should require 2397 as much of the message as possible to be signed, within the limits of 2398 the application and deployment. The verifier should only trust 2399 message components that have been signed. Verifiers could also strip 2400 out any sensitive unsigned portions of the message before processing 2401 of the message continues. 2403 7.5. Cryptography and Signature Collision 2405 The HTTP Message Signatures specification does not define any of its 2406 own cryptographic primitives, and instead relies on other 2407 specifications to define such elements. If the signature algorithm 2408 or key used to process the signature input string is vulnerable to 2409 any attacks, the resulting signature will also be susceptible to 2410 these same attacks. 2412 A common attack against signature systems is to force a signature 2413 collision, where the same signature value successfully verifies 2414 against multiple different inputs. Since this specification relies 2415 on reconstruction of the input string based on an HTTP message, and 2416 the list of components signed is fixed in the signature, it is 2417 difficult but not impossible for an attacker to effect such a 2418 collision. An attacker would need to manipulate the HTTP message and 2419 its covered message components in order to make the collision 2420 effective. 2422 To counter this, only vetted keys and signature algorithms should be 2423 used to sign HTTP messages. The HTTP Message Signatures Algorithm 2424 Registry is one source of potential trusted algorithms. 2426 While it is possible for an attacker to substitute the signature 2427 parameters value or the signature value separately, the signature 2428 input generation algorithm (Section 2.3) always covers the signature 2429 parameters as the final value in the input string using a 2430 deterministic serialization method. This step strongly binds the 2431 signature input with the signature value in a way that makes it much 2432 more difficult for an attacker to perform a partial substitution on 2433 the signature inputs. 2435 7.6. Key Theft 2437 A foundational assumption of signature-based cryptographic systems is 2438 that the signing key is not compromised by an attacker. If the keys 2439 used to sign the message are exfiltrated or stolen, the attacker will 2440 be able to generate their own signatures using those keys. As a 2441 consequence, signers have to protect any signing key material from 2442 exfiltration, capture, and use by an attacker. 2444 To combat this, signers can rotate keys over time to limit the amount 2445 of time stolen keys are useful. Signers can also use key escrow and 2446 storage systems to limit the attack surface against keys. 2447 Furthermore, the use of asymmetric signing algorithms exposes key 2448 material less than the use of symmetric signing algorithms 2449 (Section 7.11). 2451 7.7. Modification of Required Message Parameters 2453 An attacker could effectively deny a service by modifying an 2454 otherwise benign signature parameter or signed message component. 2455 While rejecting a modified message is the desired behavior, 2456 consistently failing signatures could lead to the verifier turning 2457 off signature checking in order to make systems work again (see 2458 Section 7.1). 2460 If such failures are common within an application, the signer and 2461 verifier should compare their generated signature input strings with 2462 each other to determine which part of the message is being modified. 2463 However, the signer and verifier should not remove the requirement to 2464 sign the modified component when it is suspected an attacker is 2465 modifying the component. 2467 7.8. Mismatch of Signature Parameters from Message 2469 The verifier needs to make sure that the signed message components 2470 match those in the message itself. This specification encourages 2471 this by requiring the verifier to derive these values from the 2472 message, but lazy cacheing or conveyance of the signature input 2473 string to a processing system could lead to downstream verifiers 2474 accepting a message that does not match the presented signature. 2476 7.9. Multiple Signature Confusion 2478 Since multiple signatures can be applied to one message 2479 (Section 4.3), it is possible for an attacker to attach their own 2480 signature to a captured message without modifying existing 2481 signatures. This new signature could be completely valid based on 2482 the attacker's key, or it could be an invalid signature for any 2483 number of reasons. Each of these situations need to be accounted 2484 for. 2486 A verifier processing a set of valid signatures needs to account for 2487 all of the signers, identified by the signing keys. Only signatures 2488 from expected signers should be accepted, regardless of the 2489 cryptographic validity of the signature itself. 2491 A verifier processing a set of signatures on a message also needs to 2492 determine what to do when one or more of the signatures are not 2493 valid. If a message is accepted when at least one signature is 2494 valid, then a verifier could drop all invalid signatures from the 2495 request before processing the message further. Alternatively, if the 2496 verifier rejects a message for a single invalid signature, an 2497 attacker could use this to deny service to otherwise valid messages 2498 by injecting invalid signatures alongside the valid ones. 2500 7.10. Signature Labels 2502 HTTP Message Signature values are identified in the Signature and 2503 Signature-Input field values by unique labels. These labels are 2504 chosen only when attaching the signature values to the message and 2505 are not accounted for in the signing process. An intermediary adding 2506 its own signature is allowed to re-label an existing signature when 2507 processing the message. 2509 Therefore, applications should not rely on specific labels being 2510 present, and applications should not put semantic meaning on the 2511 labels themselves. Instead, additional signature parmeters can be 2512 used to convey whatever additional meaning is required to be attached 2513 to and covered by the signature. 2515 7.11. Symmetric Cryptography 2517 The HTTP Message Signatures specification allows for both asymmetric 2518 and symmetric cryptography to be applied to HTTP messages. By its 2519 nature, symmetric cryptographic methods require the same key material 2520 to be known by both the signer and verifier. This effectively means 2521 that a verifier is capable of generating a valid signature, since 2522 they have access to the same key material. An attacker that is able 2523 to compromise a verifier would be able to then impersonate a signer. 2525 Where possible, asymmetric methods or secure key agreement mechanisms 2526 should be used in order to avoid this type of attack. When symmetric 2527 methods are used, distribution of the key material needs to be 2528 protected by the overall system. One technique for this is the use 2529 of separate cryptographic modules that separate the verification 2530 process (and therefore the key material) from other code, minimizing 2531 the vulnerable attack surface. Another technique is the use of key 2532 derivation functions that allow the signer and verifier to agree on 2533 unique keys for each message without having to share the key values 2534 directly. 2536 Additionally, if symmetric algorithms are allowed within a system, 2537 special care must be taken to avoid key downgrade attacks 2538 (Section 7.15). 2540 7.12. Canonicalization Attacks 2542 Any ambiguity in the generation of the signature input string could 2543 provide an attacker with leverage to substitute or break a signature 2544 on a message. Some message component values, particularly HTTP field 2545 values, are potentially susceptible to broken implementations that 2546 could lead to unexpected and insecure behavior. Naive 2547 implementations of this specification might implement HTTP field 2548 processing by taking the single value of a field and using it as the 2549 direct component value without processing it appropriately. 2551 For example, if the handling of obs-fold field values does not remove 2552 the internal line folding and whitespace, additional newlines could 2553 be introduced into the signature input string by the signer, 2554 providing a potential place for an attacker to mount a signature 2555 collision (Section 7.5) attack. Alternatively, if header fields that 2556 appear multiple times are not joined into a single string value, as 2557 is required by this specification, similar attacks can be mounted as 2558 a signed component value would show up in the input string more than 2559 once and could be substituted or otherwise attacked in this way. 2561 To counter this, the entire field processing algorithm needs to be 2562 implemented by all implementations of signers and verifiers. 2564 7.13. Key Specification Mix-Up 2566 The existence of a valid signature on an HTTP message is not 2567 sufficient to prove that the message has been signed by the 2568 appropriate party. It is up to the verifier to ensure that a given 2569 key and algorithm are appropriate for the message in question. If 2570 the verifier does not perform such a step, an attacker could 2571 substitute their own signature using their own key on a message and 2572 force a verifier to accept and process it. To combat this, the 2573 verifier needs to ensure that not only does the signature validate 2574 for a message, but that the key and algorithm used are appropriate. 2576 7.14. HTTP Versions and Component Ambiguity 2578 Some message components are expressed in different ways across HTTP 2579 versions. For example, the authority of the request target is sent 2580 using the Host header field in HTTP 1.1 but with the :authority 2581 pseudo-header in HTTP 2. If a signer sends an HTTP 1.1 message and 2582 signs the Host field, but the message is translated to HTTP 2 before 2583 it reaches the verifier, the signature will not validate as the Host 2584 header field could be dropped. 2586 It is for this reason that HTTP Message Signatures defines a set of 2587 derived components that define a single way to get value in question, 2588 such as the @authority derived component identifier (Section 2.2.4) 2589 in lieu of the Host header field. Applications should therefore 2590 prefer derived component identifiers for such options where possible. 2592 7.15. Key and Algorithm Specification Downgrades 2594 Applications of this specification need to protect against key 2595 specification downgrade attacks. For example, the same RSA key can 2596 be used for both RSA-PSS and RSA v1.5 signatures. If an application 2597 expects a key to only be used with RSA-PSS, it needs to reject 2598 signatures for that key using the weaker RSA 1.5 specification. 2600 Another example of a downgrade attack occurs when an asymmetric 2601 algorithm is expected, such as RSA-PSS, but an attacker substitutes a 2602 signature using symmetric algorithm, such as HMAC. A naive verifier 2603 implementation could use the value of the public RSA key as the input 2604 to the HMAC verification function. Since the public key is known to 2605 the attacker, this would allow the attacker to create a valid HMAC 2606 signature against this known key. To prevent this, the verifier 2607 needs to ensure that both the key material and the algorithm are 2608 appropriate for the usage in question. Additionally, while this 2609 specification does allow runtime specification of the algorithm using 2610 the alg signature parameter, applications are encouraged to use other 2611 mechanisms such as static configuration or higher protocol-level 2612 algorithm specification instead. 2614 7.16. Parsing Structured Field Values 2616 Several parts of this specification rely on the parsing of structured 2617 field values [RFC8941]. In particular, normalization of HTTP 2618 structured field values (Section 2.1.1), referencing members of a 2619 dictionary structured field (Section 2.1.2), and processing the 2620 @signature-input value when verifying a signature (Section 3.2). 2621 While structured field values are designed to be relatively simple to 2622 parse, a naive or broken implementation of such a parser could lead 2623 to subtle attack surfaces being exposed in the implementation. 2625 For example, if a buggy parser of the @signature-input value does not 2626 enforce proper closing of quotes around string values within the list 2627 of component identifiers, an attacker could take advantage of this 2628 and inject additional content into the signature input string through 2629 manipulating the Signature-Input field value on a message. 2631 To counteract this, implementations should use fully compliant and 2632 trusted parsers for all structured field processing, both on the 2633 signer and verifier side. 2635 7.17. Choosing Message Components 2637 Applications of HTTP Message Signatures need to decide which message 2638 components will be covered by the signature. Depending on the 2639 application, some components could be expected to be changed by 2640 intermediaries prior to the signature's verification. If these 2641 components are covered, such changes would, by design, break the 2642 signature. 2644 However, the HTTP Message Signature standard allows for flexibility 2645 in determining which components are signed precisely so that a given 2646 application can choose the appropriate portions of the message that 2647 need to be signed, avoiding problematic components. For example, a 2648 web application framework that relies on rewriting query parameters 2649 might avoid use of the @query content identifier in favor of sub- 2650 indexing the query value using @query-params content identifier 2651 instead. 2653 Some components are expected to be changed by intermediaries and 2654 ought not to be signed under most circumstance. The Via and 2655 Forwarded header fields, for example, are expected to be manipulated 2656 by proxies and other middle-boxes, including replacing or entirely 2657 dropping existing values. These fields should not be covered by the 2658 signature except in very limited and tightly-coupled scenarios. 2660 Additional considerations for choosing signature aspects are 2661 discussed in Section 1.5. 2663 7.18. Confusing HTTP Field Names for Derived Component Identifiers 2665 The definition of HTTP field names does not allow for the use of the 2666 @ character anywhere in the name. As such, since all derived 2667 component identifiers start with the @ character, these namespaces 2668 should be completely separate. However, some HTTP implementations 2669 are not sufficiently strict about the characters accepted in HTTP 2670 headers. In such implementations, a sender (or attacker) could 2671 inject a header field starting with an @ character and have it passed 2672 through to the application code. These invalid header fields could 2673 be used to override a portion of the derived message content and 2674 substitute an arbitrary value, providing a potential place for an 2675 attacker to mount a signature collision (Section 7.5) attack. 2677 To combat this, when selecting values for a message component, if the 2678 component identifier starts with the @ character, it needs to be 2679 processed as a derived component and never taken as a fields. Only 2680 if the component identifier does not start with the @ character can 2681 it be taken from the fields of the message. The algorithm discussed 2682 in Section 2.3 provides a safe order of operations. 2684 7.19. Non-deterministic Signature Primitives 2686 Some cryptographic primitives such as RSA PSS and ECDSA have non- 2687 deterministic outputs, which include some amount of entropy within 2688 the algorithm. For such algorithms, multiple signatures generated in 2689 succession will not match. A lazy implementation of a verifier could 2690 ignore this distinction and simply check for the same value being 2691 created by re-signing the signature input. Such an implementation 2692 would work for deterministic algorithms such as HMAC and EdDSA but 2693 fail to verify valid signatures made using non-deterministic 2694 algorithms. It is therefore important that a verifier always use the 2695 correctly-defined verification function for the algorithm in question 2696 and not do a simple comparison. 2698 8. Privacy Considerations 2700 8.1. Identification through Keys 2702 If a signer uses the same key with multiple verifiers, or uses the 2703 same key over time with a single verifier, the ongoing use of that 2704 key can be used to track the signer throughout the set of verifiers 2705 that messages are sent to. Since cryptographic keys are meant to be 2706 functionally unique, the use of the same key over time is a strong 2707 indicator that it is the same party signing multiple messages. 2709 In many applications, this is a desirable trait, and it allows HTTP 2710 Message Signatures to be used as part of authenticating the signer to 2711 the verifier. However, unintentional tracking that a signer might 2712 not be aware of. To counter this kind of tracking, a signer can use 2713 a different key for each verifier that it is in communication with. 2714 Sometimes, a signer could also rotate their key when sending messages 2715 to a given verifier. These approaches do not negate the need for 2716 other anti-tracking techniques to be applied as necessary. 2718 8.2. Signatures do not provide confidentiality 2720 HTTP Message Signatures do not provide confidentiality of any of the 2721 information protected by the signature. The content of the HTTP 2722 message, including the value of all fields and the value of the 2723 signature itself, is presented in plaintext to any party with access 2724 to the message. 2726 To provide confidentiality at the transport level, TLS or its 2727 equivalent can be used as discussed in Section 7.2. 2729 8.3. Oracles 2731 It is important to balance the need for providing useful feedback to 2732 developers on error conditions without providing additional 2733 information to an attacker. For example, a naive but helpful server 2734 implementation might try to indicate the required key identifier 2735 needed for requesting a resource. If someone knows who controls that 2736 key, a correlation can be made between the resource's existence and 2737 the party identified by the key. Access to such information could be 2738 used by an attacker as a means to target the legitimate owner of the 2739 resource for further attacks. 2741 8.4. Required Content 2743 A core design tenet of this specification is that all message 2744 components covered by the signature need to be available to the 2745 verifier in order to recreate the signature input string and verify 2746 the signature. As a consequence, if an application of this 2747 specification requires that a particular field be signed, the 2748 verifier will need access to the value of that field. 2750 For example, in some complex systems with intermediary processors 2751 this could cause the surprising behavior of an intermediary not being 2752 able to remove privacy-sensitive information from a message before 2753 forwarding it on for processing, for fear of breaking the signature. 2754 A possible mitigation for this specific situation would be for the 2755 intermediary to verify the signature itself, then modifying the 2756 message to remove the privacy-sensitive information. The 2757 intermediary can add its own signature at this point to signal to the 2758 next destination that the incoming signature was validated, as is 2759 shown in the example in Section 4.3. 2761 9. References 2763 9.1. Normative References 2765 [FIPS186-4] 2766 "Digital Signature Standard (DSS)", 2013, 2767 . 2770 [HTMLURL] "URL (Living Standard)", 2021, 2771 . 2773 [MESSAGING] 2774 Fielding, R. T., Nottingham, M., and J. Reschke, 2775 "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf- 2776 httpbis-messaging-19, 12 September 2021, 2777 . 2780 [POSIX.1] "The Open Group Base Specifications Issue 7, 2018 2781 edition", 2018, 2782 . 2784 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2785 Hashing for Message Authentication", RFC 2104, 2786 DOI 10.17487/RFC2104, February 1997, 2787 . 2789 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2790 Requirement Levels", BCP 14, RFC 2119, 2791 DOI 10.17487/RFC2119, March 1997, 2792 . 2794 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2795 Resource Identifier (URI): Generic Syntax", STD 66, 2796 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2797 . 2799 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 2800 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 2801 DOI 10.17487/RFC6234, May 2011, 2802 . 2804 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 2805 DOI 10.17487/RFC7517, May 2015, 2806 . 2808 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 2809 DOI 10.17487/RFC7518, May 2015, 2810 . 2812 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 2813 "PKCS #1: RSA Cryptography Specifications Version 2.2", 2814 RFC 8017, DOI 10.17487/RFC8017, November 2016, 2815 . 2817 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 2818 Signature Algorithm (EdDSA)", RFC 8032, 2819 DOI 10.17487/RFC8032, January 2017, 2820 . 2822 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2823 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2824 May 2017, . 2826 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 2827 "Handling Long Lines in Content of Internet-Drafts and 2828 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 2829 . 2831 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 2832 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 2833 . 2835 [SEMANTICS] 2836 Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 2837 Semantics", Work in Progress, Internet-Draft, draft-ietf- 2838 httpbis-semantics-19, 12 September 2021, 2839 . 2842 9.2. Informative References 2844 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 2845 "Recommendations for Secure Use of Transport Layer 2846 Security (TLS) and Datagram Transport Layer Security 2847 (DTLS)", BCP 195, RFC 7525, May 2015. 2849 Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS 2850 1.1", BCP 195, RFC 8996, March 2021. 2852 2854 [I-D.ietf-httpbis-client-cert-field] 2855 Campbell, B. and M. Bishop, "Client-Cert HTTP Header 2856 Field", Work in Progress, Internet-Draft, draft-ietf- 2857 httpbis-client-cert-field-01, 25 January 2022, 2858 . 2861 [RFC7239] Petersson, A. and M. Nilsson, "Forwarded HTTP Extension", 2862 RFC 7239, DOI 10.17487/RFC7239, June 2014, 2863 . 2865 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 2866 Writing an IANA Considerations Section in RFCs", BCP 26, 2867 RFC 8126, DOI 10.17487/RFC8126, June 2017, 2868 . 2870 [TLS] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2871 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2872 . 2874 Appendix A. Detecting HTTP Message Signatures 2876 There have been many attempts to create signed HTTP messages in the 2877 past, including other non-standardized definitions of the Signature 2878 field, which is used within this specification. It is recommended 2879 that developers wishing to support both this specification and other 2880 historical drafts do so carefully and deliberately, as 2881 incompatibilities between this specification and various versions of 2882 other drafts could lead to unexpected problems. 2884 It is recommended that implementers first detect and validate the 2885 Signature-Input field defined in this specification to detect that 2886 this standard is in use and not an alternative. If the Signature- 2887 Input field is present, all Signature fields can be parsed and 2888 interpreted in the context of this draft. 2890 Appendix B. Examples 2892 B.1. Example Keys 2894 This section provides cryptographic keys that are referenced in 2895 example signatures throughout this document. These keys MUST NOT be 2896 used for any purpose other than testing. 2898 The key identifiers for each key are used throughout the examples in 2899 this specification. It is assumed for these examples that the signer 2900 and verifier can unambiguously dereference all key identifiers used 2901 here, and that the keys and algorithms used are appropriate for the 2902 context in which the signature is presented. 2904 B.1.1. Example Key RSA test 2906 The following key is a 2048-bit RSA public and private key pair, 2907 referred to in this document as test-key-rsa: 2909 -----BEGIN RSA PUBLIC KEY----- 2910 MIIBCgKCAQEAhAKYdtoeoy8zcAcR874L8cnZxKzAGwd7v36APp7Pv6Q2jdsPBRrw 2911 WEBnez6d0UDKDwGbc6nxfEXAy5mbhgajzrw3MOEt8uA5txSKobBpKDeBLOsdJKFq 2912 MGmXCQvEG7YemcxDTRPxAleIAgYYRjTSd/QBwVW9OwNFhekro3RtlinV0a75jfZg 2913 kne/YiktSvLG34lw2zqXBDTC5NHROUqGTlML4PlNZS5Ri2U4aCNx2rUPRcKIlE0P 2914 uKxI4T+HIaFpv8+rdV6eUgOrB2xeI1dSFFn/nnv5OoZJEIB+VmuKn3DCUcCZSFlQ 2915 PSXSfBDiUGhwOw76WuSSsf1D4b/vLoJ10wIDAQAB 2916 -----END RSA PUBLIC KEY----- 2918 -----BEGIN RSA PRIVATE KEY----- 2919 MIIEqAIBAAKCAQEAhAKYdtoeoy8zcAcR874L8cnZxKzAGwd7v36APp7Pv6Q2jdsP 2920 BRrwWEBnez6d0UDKDwGbc6nxfEXAy5mbhgajzrw3MOEt8uA5txSKobBpKDeBLOsd 2921 JKFqMGmXCQvEG7YemcxDTRPxAleIAgYYRjTSd/QBwVW9OwNFhekro3RtlinV0a75 2922 jfZgkne/YiktSvLG34lw2zqXBDTC5NHROUqGTlML4PlNZS5Ri2U4aCNx2rUPRcKI 2923 lE0PuKxI4T+HIaFpv8+rdV6eUgOrB2xeI1dSFFn/nnv5OoZJEIB+VmuKn3DCUcCZ 2924 SFlQPSXSfBDiUGhwOw76WuSSsf1D4b/vLoJ10wIDAQABAoIBAG/JZuSWdoVHbi56 2925 vjgCgkjg3lkO1KrO3nrdm6nrgA9P9qaPjxuKoWaKO1cBQlE1pSWp/cKncYgD5WxE 2926 CpAnRUXG2pG4zdkzCYzAh1i+c34L6oZoHsirK6oNcEnHveydfzJL5934egm6p8DW 2927 +m1RQ70yUt4uRc0YSor+q1LGJvGQHReF0WmJBZHrhz5e63Pq7lE0gIwuBqL8SMaA 2928 yRXtK+JGxZpImTq+NHvEWWCu09SCq0r838ceQI55SvzmTkwqtC+8AT2zFviMZkKR 2929 Qo6SPsrqItxZWRty2izawTF0Bf5S2VAx7O+6t3wBsQ1sLptoSgX3QblELY5asI0J 2930 YFz7LJECgYkAsqeUJmqXE3LP8tYoIjMIAKiTm9o6psPlc8CrLI9CH0UbuaA2JCOM 2931 cCNq8SyYbTqgnWlB9ZfcAm/cFpA8tYci9m5vYK8HNxQr+8FS3Qo8N9RJ8d0U5Csw 2932 DzMYfRghAfUGwmlWj5hp1pQzAuhwbOXFtxKHVsMPhz1IBtF9Y8jvgqgYHLbmyiu1 2933 mwJ5AL0pYF0G7x81prlARURwHo0Yf52kEw1dxpx+JXER7hQRWQki5/NsUEtv+8RT 2934 qn2m6qte5DXLyn83b1qRscSdnCCwKtKWUug5q2ZbwVOCJCtmRwmnP131lWRYfj67 2935 B/xJ1ZA6X3GEf4sNReNAtaucPEelgR2nsN0gKQKBiGoqHWbK1qYvBxX2X3kbPDkv 2936 9C+celgZd2PW7aGYLCHq7nPbmfDV0yHcWjOhXZ8jRMjmANVR/eLQ2EfsRLdW69bn 2937 f3ZD7JS1fwGnO3exGmHO3HZG+6AvberKYVYNHahNFEw5TsAcQWDLRpkGybBcxqZo 2938 81YCqlqidwfeO5YtlO7etx1xLyqa2NsCeG9A86UjG+aeNnXEIDk1PDK+EuiThIUa 2939 /2IxKzJKWl1BKr2d4xAfR0ZnEYuRrbeDQYgTImOlfW6/GuYIxKYgEKCFHFqJATAG 2940 IxHrq1PDOiSwXd2GmVVYyEmhZnbcp8CxaEMQoevxAta0ssMK3w6UsDtvUvYvF22m 2941 qQKBiD5GwESzsFPy3Ga0MvZpn3D6EJQLgsnrtUPZx+z2Ep2x0xc5orneB5fGyF1P 2942 WtP+fG5Q6Dpdz3LRfm+KwBCWFKQjg7uTxcjerhBWEYPmEMKYwTJF5PBG9/ddvHLQ 2943 EQeNC8fHGg4UXU8mhHnSBt3EA10qQJfRDs15M38eG2cYwB1PZpDHScDnDA0= 2944 -----END RSA PRIVATE KEY----- 2946 B.1.2. Example RSA PSS Key 2948 The following key is a 2048-bit RSA public and private key pair, 2949 referred to in this document as test-key-rsa-pss: 2951 -----BEGIN PUBLIC KEY----- 2952 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr4tmm3r20Wd/PbqvP1s2 2953 +QEtvpuRaV8Yq40gjUR8y2Rjxa6dpG2GXHbPfvMs8ct+Lh1GH45x28Rw3Ry53mm+ 2954 oAXjyQ86OnDkZ5N8lYbggD4O3w6M6pAvLkhk95AndTrifbIFPNU8PPMO7OyrFAHq 2955 gDsznjPFmTOtCEcN2Z1FpWgchwuYLPL+Wokqltd11nqqzi+bJ9cvSKADYdUAAN5W 2956 Utzdpiy6LbTgSxP7ociU4Tn0g5I6aDZJ7A8Lzo0KSyZYoA485mqcO0GVAdVw9lq4 2957 aOT9v6d+nb4bnNkQVklLQ3fVAvJm+xdDOp9LCNCN48V2pnDOkFV6+U9nV5oyc6XI 2958 2wIDAQAB 2959 -----END PUBLIC KEY----- 2961 -----BEGIN PRIVATE KEY----- 2962 MIIEvgIBADALBgkqhkiG9w0BAQoEggSqMIIEpgIBAAKCAQEAr4tmm3r20Wd/Pbqv 2963 P1s2+QEtvpuRaV8Yq40gjUR8y2Rjxa6dpG2GXHbPfvMs8ct+Lh1GH45x28Rw3Ry5 2964 3mm+oAXjyQ86OnDkZ5N8lYbggD4O3w6M6pAvLkhk95AndTrifbIFPNU8PPMO7Oyr 2965 FAHqgDsznjPFmTOtCEcN2Z1FpWgchwuYLPL+Wokqltd11nqqzi+bJ9cvSKADYdUA 2966 AN5WUtzdpiy6LbTgSxP7ociU4Tn0g5I6aDZJ7A8Lzo0KSyZYoA485mqcO0GVAdVw 2967 9lq4aOT9v6d+nb4bnNkQVklLQ3fVAvJm+xdDOp9LCNCN48V2pnDOkFV6+U9nV5oy 2968 c6XI2wIDAQABAoIBAQCUB8ip+kJiiZVKF8AqfB/aUP0jTAqOQewK1kKJ/iQCXBCq 2969 pbo360gvdt05H5VZ/RDVkEgO2k73VSsbulqezKs8RFs2tEmU+JgTI9MeQJPWcP6X 2970 aKy6LIYs0E2cWgp8GADgoBs8llBq0UhX0KffglIeek3n7Z6Gt4YFge2TAcW2WbN4 2971 XfK7lupFyo6HHyWRiYHMMARQXLJeOSdTn5aMBP0PO4bQyk5ORxTUSeOciPJUFktQ 2972 HkvGbym7KryEfwH8Tks0L7WhzyP60PL3xS9FNOJi9m+zztwYIXGDQuKM2GDsITeD 2973 2mI2oHoPMyAD0wdI7BwSVW18p1h+jgfc4dlexKYRAoGBAOVfuiEiOchGghV5vn5N 2974 RDNscAFnpHj1QgMr6/UG05RTgmcLfVsI1I4bSkbrIuVKviGGf7atlkROALOG/xRx 2975 DLadgBEeNyHL5lz6ihQaFJLVQ0u3U4SB67J0YtVO3R6lXcIjBDHuY8SjYJ7Ci6Z6 2976 vuDcoaEujnlrtUhaMxvSfcUJAoGBAMPsCHXte1uWNAqYad2WdLjPDlKtQJK1diCm 2977 rqmB2g8QE99hDOHItjDBEdpyFBKOIP+NpVtM2KLhRajjcL9Ph8jrID6XUqikQuVi 2978 4J9FV2m42jXMuioTT13idAILanYg8D3idvy/3isDVkON0X3UAVKrgMEne0hJpkPL 2979 FYqgetvDAoGBAKLQ6JZMbSe0pPIJkSamQhsehgL5Rs51iX4m1z7+sYFAJfhvN3Q/ 2980 OGIHDRp6HjMUcxHpHw7U+S1TETxePwKLnLKj6hw8jnX2/nZRgWHzgVcY+sPsReRx 2981 NJVf+Cfh6yOtznfX00p+JWOXdSY8glSSHJwRAMog+hFGW1AYdt7w80XBAoGBAImR 2982 NUugqapgaEA8TrFxkJmngXYaAqpA0iYRA7kv3S4QavPBUGtFJHBNULzitydkNtVZ 2983 3w6hgce0h9YThTo/nKc+OZDZbgfN9s7cQ75x0PQCAO4fx2P91Q+mDzDUVTeG30mE 2984 t2m3S0dGe47JiJxifV9P3wNBNrZGSIF3mrORBVNDAoGBAI0QKn2Iv7Sgo4T/XjND 2985 dl2kZTXqGAk8dOhpUiw/HdM3OGWbhHj2NdCzBliOmPyQtAr770GITWvbAI+IRYyF 2986 S7Fnk6ZVVVHsxjtaHy1uJGFlaZzKR4AGNaUTOJMs6NadzCmGPAxNQQOCqoUjn4XR 2987 rOjr9w349JooGXhOxbu8nOxX 2988 -----END PRIVATE KEY----- 2990 B.1.3. Example ECC P-256 Test Key 2992 The following key is an elliptical curve key over the curve P-256, 2993 referred to in this document as test-key-ecc-p256. 2995 -----BEGIN EC PRIVATE KEY----- 2996 MHcCAQEEIFKbhfNZfpDsW43+0+JjUr9K+bTeuxopu653+hBaXGA7oAoGCCqGSM49 2997 AwEHoUQDQgAEqIVYZVLCrPZHGHjP17CTW0/+D9Lfw0EkjqF7xB4FivAxzic30tMM 2998 4GF+hR6Dxh71Z50VGGdldkkDXZCnTNnoXQ== 2999 -----END EC PRIVATE KEY----- 3001 -----BEGIN PUBLIC KEY----- 3002 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqIVYZVLCrPZHGHjP17CTW0/+D9Lf 3003 w0EkjqF7xB4FivAxzic30tMM4GF+hR6Dxh71Z50VGGdldkkDXZCnTNnoXQ== 3004 -----END PUBLIC KEY----- 3006 B.1.4. Example Shared Secret 3008 The following shared secret is 64 randomly-generated bytes encoded in 3009 Base64, referred to in this document as test-shared-secret. 3011 NOTE: '\' line wrapping per RFC 8792 3013 uzvJfB4u3N0Jy4T7NZ75MDVcr8zSTInedJtkgcu46YW4XByzNJjxBdtjUkdJPBt\ 3014 bmHhIDi6pcl8jsasjlTMtDQ== 3016 B.1.5. Example Ed25519 Test Key 3018 The following key is an elliptical curve key over the Edwards curve 3019 ed25519, referred to in this document as test-key-edd25519. 3021 -----BEGIN PRIVATE KEY----- 3022 MC4CAQAwBQYDK2VwBCIEIJ+DYvh6SEqVTm50DFtMDoQikTmiCqirVv9mWG9qfSnF 3023 -----END PRIVATE KEY----- 3025 -----BEGIN PUBLIC KEY----- 3026 MCowBQYDK2VwAyEAJrQLj5P/89iXES9+vFgrIy29clF9CC/oPPsw3c5D0bs= 3027 -----END PUBLIC KEY----- 3029 B.2. Test Cases 3031 This section provides non-normative examples that may be used as test 3032 cases to validate implementation correctness. These examples are 3033 based on the following HTTP messages: 3035 For requests, this test-request message is used: 3037 POST /foo?param=Value&Pet=dog HTTP/1.1 3038 Host: example.com 3039 Date: Tue, 20 Apr 2021 02:07:55 GMT 3040 Content-Type: application/json 3041 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 3042 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 3043 Content-Length: 18 3045 {"hello": "world"} 3047 For responses, this test-response message is used: 3049 HTTP/1.1 200 OK 3050 Date: Tue, 20 Apr 2021 02:07:56 GMT 3051 Content-Type: application/json 3052 Content-Digest: sha-512=:JlEy2bfUz7WrWIjc1qV6KVLpdr/7L5/L4h7Sxvh6sN\ 3053 HpDQWDCL+GauFQWcZBvVDhiyOnAQsxzZFYwi0wDH+1pw==: 3054 Content-Length: 23 3056 {"message": "good dog"} 3058 B.2.1. Minimal Signature Using rsa-pss-sha512 3060 This example presents a minimal signature using the rsa-pss-sha512 3061 algorithm over test-request, covering none of the components of the 3062 HTTP message, but providing a timestamped signature proof of 3063 possession of the key with a signer-provided nonce. 3065 The corresponding signature input is: 3067 NOTE: '\' line wrapping per RFC 8792 3069 "@signature-params": ();created=1618884473;keyid="test-key-rsa-pss"\ 3070 ;nonce="b3k2pp5k7z-50gnwp.yemd" 3072 This results in the following Signature-Input and Signature headers 3073 being added to the message under the signature label sig-b21: 3075 NOTE: '\' line wrapping per RFC 8792 3077 Signature-Input: sig-b21=();created=1618884473\ 3078 ;keyid="test-key-rsa-pss";nonce="b3k2pp5k7z-50gnwp.yemd" 3079 Signature: sig-b21=:d2pmTvmbncD3xQm8E9ZV2828BjQWGgiwAaw5bAkgibUopem\ 3080 LJcWDy/lkbbHAve4cRAtx31Iq786U7it++wgGxbtRxf8Udx7zFZsckzXaJMkA7ChG\ 3081 52eSkFxykJeNqsrWH5S+oxNFlD4dzVuwe8DhTSja8xxbR/Z2cOGdCbzR72rgFWhzx\ 3082 2VjBqJzsPLMIQKhO4DGezXehhWwE56YCE+O6c0mKZsfxVrogUvA4HELjVKWmAvtl6\ 3083 UnCh8jYzuVG5WSb/QEVPnP5TmcAnLH1g+s++v6d4s8m0gCw1fV5/SITLq9mhho8K3\ 3084 +7EPYTU8IU1bLhdxO5Nyt8C8ssinQ98Xw9Q==: 3086 Note that since the covered components list is empty, this signature 3087 could be applied by an attacker to an unrelated HTTP message. In 3088 this example, the nonce parameter is included to prevent the same 3089 signature from being replayed more than once, but if an attacker 3090 intercepts the signature and prevents its delivery to the verifier, 3091 the attacker could apply this signature to another message. 3092 Therefore, use of an empty covered components set is discouraged. 3093 See Section 7.4 for more discussion. 3095 Note that the RSA PSS algorithm in use here is non-deterministic, 3096 meaning a different signature value will be created every time the 3097 algorithm is run. The signature value provided here can be validated 3098 against the given keys, but newly-generated signature values are not 3099 expected to match the example. See Section 7.19. 3101 B.2.2. Selective Covered Components using rsa-pss-sha512 3103 This example covers additional components in test-request using the 3104 rsa-pss-sha512 algorithm. 3106 The corresponding signature input is: 3108 NOTE: '\' line wrapping per RFC 8792 3110 "@authority": example.com 3111 "content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\ 3112 +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 3113 "@signature-params": ("@authority" "content-digest")\ 3114 ;created=1618884473;keyid="test-key-rsa-pss" 3116 This results in the following Signature-Input and Signature headers 3117 being added to the message under the label sig-b22: 3119 NOTE: '\' line wrapping per RFC 8792 3121 Signature-Input: sig-b22=("@authority" "content-digest")\ 3122 ;created=1618884473;keyid="test-key-rsa-pss" 3123 Signature: sig-b22=:Fee1uy9YGZq5UUwwYU6vz4dZNvfw3GYrFl1L6YlVIyUMuWs\ 3124 wWDNSvql4dVtSeidYjYZUm7SBCENIb5KYy2ByoC3bI+7gydd2i4OAT5lyDtmeapnA\ 3125 a8uP/b9xUpg+VSPElbBs6JWBIQsd+nMdHDe+ls/IwVMwXktC37SqsnbNyhNp6kcvc\ 3126 WpevjzFcD2VqdZleUz4jN7P+W5A3wHiMGfIjIWn36KXNB+RKyrlGnIS8yaBBrom5r\ 3127 cZWLrLbtg6VlrH1+/07RV+kgTh/l10h8qgpl9zQHu7mWbDKTq0tJ8K4ywcPoC4s2I\ 3128 4rU88jzDKDGdTTQFZoTVZxZmuTM1FvHfzIw==: 3130 Note that the RSA PSS algorithm in use here is non-deterministic, 3131 meaning a different signature value will be created every time the 3132 algorithm is run. The signature value provided here can be validated 3133 against the given keys, but newly-generated signature values are not 3134 expected to match the example. See Section 7.19. 3136 B.2.3. Full Coverage using rsa-pss-sha512 3138 This example covers all applicable in test-request (including the 3139 content type and length) plus many derived components, again using 3140 the rsa-pss-sha512 algorithm. Note that the Host header field is not 3141 covered because the @authority derived component is included instead. 3143 The corresponding signature input is: 3145 NOTE: '\' line wrapping per RFC 8792 3147 "date": Tue, 20 Apr 2021 02:07:55 GMT 3148 "@method": POST 3149 "@path": /foo 3150 "@query": param=Value&Pet=dog 3151 "@authority": example.com 3152 "content-type": application/json 3153 "content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\ 3154 +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 3155 "content-length": 18 3156 "@signature-params": ("date" "@method" "@path" "@query" \ 3157 "@authority" "content-type" "content-digest" "content-length")\ 3158 ;created=1618884473;keyid="test-key-rsa-pss" 3160 This results in the following Signature-Input and Signature headers 3161 being added to the message under the label sig-b23: 3163 NOTE: '\' line wrapping per RFC 8792 3165 Signature-Input: sig-b23=("date" "@method" "@path" "@query" \ 3166 "@authority" "content-type" "content-digest" "content-length")\ 3167 ;created=1618884473;keyid="test-key-rsa-pss" 3168 Signature: sig-b23=:f9nOGJSjCdQ/t+/Mp7gpAHU7Kn1LpnWJE6W2081yRFITJob\ 3169 BDODwQNxnjiIdAGstfGKuM2vlc5SyN16//K5dBLGoiaboMco4J6R0zS+8oXqD7o6K\ 3170 RpIZR/qMrFc5Bu6f6UxuoWZPfCxhs3vxL/60JbF8dcdul1b77mWyC07ZjZ9VkelBy\ 3171 eF5+zN7v6Al/vnBzMS3H1NLz9dI2sw5Vb7kxQQ6CvEI9v3R30aFgWz4rCuyT0Kt3y\ 3172 tQvTHOBsadF66eDe641Sd6O/DgbdFibsE/+ToYopL9NlAuva42NlcFemrozvOKvGI\ 3173 PXdAPqmng/bePoSR6DIaFbWp5aDlNSbWlcA==: 3175 Note in this example that the value of the Date header and the value 3176 of the created signature parameter need not be the same. This is due 3177 to the fact that the Date header is added when creating the HTTP 3178 Message and the created parameter is populated when creating the 3179 signature over that message, and these two times could vary. If the 3180 Date header is covered by the signature, it is up to the verifier to 3181 determine whether its value has to match that of the created 3182 parameter or not. 3184 Note that the RSA PSS algorithm in use here is non-deterministic, 3185 meaning a different signature value will be created every time the 3186 algorithm is run. The signature value provided here can be validated 3187 against the given keys, but newly-generated signature values are not 3188 expected to match the example. See Section 7.19. 3190 B.2.4. Signing a Response using ecdsa-p256-sha256 3192 This example covers portions of the test-response response message 3193 using the ecdsa-p256-sha256 algorithm and the key test-key-ecc-p256. 3195 The corresponding signature input is: 3197 NOTE: '\' line wrapping per RFC 8792 3199 "@status": 200 3200 "content-type": application/json 3201 "content-digest": sha-512=:JlEy2bfUz7WrWIjc1qV6KVLpdr/7L5/L4h7Sxvh6\ 3202 sNHpDQWDCL+GauFQWcZBvVDhiyOnAQsxzZFYwi0wDH+1pw==: 3203 "content-length": 23 3204 "@signature-params": ("@status" "content-type" "content-digest" \ 3205 "content-length");created=1618884473;keyid="test-key-ecc-p256" 3207 This results in the following Signature-Input and Signature headers 3208 being added to the message under the label sig-b24: 3210 NOTE: '\' line wrapping per RFC 8792 3212 Signature-Input: sig-b24=("@status" "content-type" \ 3213 "content-digest" "content-length");created=1618884473\ 3214 ;keyid="test-key-ecc-p256" 3215 Signature: sig-b24=:0Ry6HsvzS5VmA6HlfBYS/fYYeNs7fYuA7s0tAdxfUlPGv0C\ 3216 SVuwrrzBOjcCFHTxVRJ01wjvSzM2BetJauj8dsw==: 3218 Note that the ECDSA algorithm in use here is non-deterministic, 3219 meaning a different signature value will be created every time the 3220 algorithm is run. The signature value provided here can be validated 3221 against the given keys, but newly-generated signature values are not 3222 expected to match the example. See Section 7.19. 3224 B.2.5. Signing a Request using hmac-sha256 3226 This example covers portions of the test-request using the hmac- 3227 sha256 algorithm and the secret test-shared-secret. 3229 The corresponding signature input is: 3231 NOTE: '\' line wrapping per RFC 8792 3233 "date": Tue, 20 Apr 2021 02:07:55 GMT 3234 "@authority": example.com 3235 "content-type": application/json 3236 "@signature-params": ("date" "@authority" "content-type")\ 3237 ;created=1618884473;keyid="test-shared-secret" 3239 This results in the following Signature-Input and Signature headers 3240 being added to the message under the label sig-b25: 3242 NOTE: '\' line wrapping per RFC 8792 3244 Signature-Input: sig-b25=("date" "@authority" "content-type")\ 3245 ;created=1618884473;keyid="test-shared-secret" 3246 Signature: sig-b25=:pxcQw6G3AjtMBQjwo8XzkZf/bws5LelbaMk5rGIGtE8=: 3248 Before using symmetric signatures in practice, see the discussion of 3249 the security tradeoffs in Section 7.11. 3251 B.2.6. Signing a Request using ed25519 3253 This example covers portions of the test-request using the ed25519 3254 algorithm and the key test-key-ed25519. 3256 The corresponding signature input is: 3258 NOTE: '\' line wrapping per RFC 8792 3260 "date": Tue, 20 Apr 2021 02:07:55 GMT 3261 "@method": POST 3262 "@path": /foo 3263 "@authority": example.com 3264 "content-type": application/json 3265 "content-length": 18 3266 "@signature-params": ("date" "@method" "@path" "@authority" \ 3267 "content-type" "content-length");created=1618884473\ 3268 ;keyid="test-key-ed25519" 3270 This results in the following Signature-Input and Signature headers 3271 being added to the message under the label sig-b26: 3273 NOTE: '\' line wrapping per RFC 8792 3275 Signature-Input: sig-b26=("date" "@method" "@path" "@authority" \ 3276 "content-type" "content-length");created=1618884473\ 3277 ;keyid="test-key-ed25519" 3278 Signature: sig-b26=:wqcAqbmYJ2ji2glfAMaRy4gruYYnx2nEFN2HN6jrnDnQCK1\ 3279 u02Gb04v9EDgwUPiu4A0w6vuQv5lIp5WPpBKRCw==: 3281 B.3. TLS-Terminating Proxies 3283 In this example, there is a TLS-terminating reverse proxy sitting in 3284 front of the resource. The client does not sign the request but 3285 instead uses mutual TLS to make its call. The terminating proxy 3286 validates the TLS stream and injects a Client-Cert header according 3287 to [I-D.ietf-httpbis-client-cert-field], and then applies a signature 3288 to this field. By signing this header field, a reverse proxy can not 3289 only attest to its own validation of the initial request's TLS 3290 parameters but also authenticate itself to the backend system 3291 independently of the client's actions. 3293 The client makes the following request to the TLS terminating proxy 3294 using mutual TLS: 3296 POST /foo?Param=value&pet=Dog HTTP/1.1 3297 Host: example.com 3298 Date: Tue, 20 Apr 2021 02:07:55 GMT 3299 Content-Type: application/json 3300 Content-Length: 18 3302 {"hello": "world"} 3304 The proxy processes the TLS connection and extracts the client's TLS 3305 certificate to a Client-Cert header field and passes it along to the 3306 internal service hosted at service.internal.example. This results in 3307 the following unsigned request: 3309 NOTE: '\' line wrapping per RFC 8792 3311 POST /foo?param=Value&Pet=dog HTTP/1.1 3312 Host: service.internal.example 3313 Date: Tue, 20 Apr 2021 02:07:55 GMT 3314 Content-Type: application/json 3315 Content-Length: 18 3316 Client-Cert: :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQKD\ 3317 BJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBDQT\ 3318 AeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDMFk\ 3319 wEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXmck\ 3320 C8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQYDV\ 3321 R0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8BAf\ 3322 8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQGV\ 3323 4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0Q6\ 3324 bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: 3326 {"hello": "world"} 3328 Without a signature, the internal service would need to trust that 3329 the incoming connection has the right information. By signing the 3330 Client-Cert header and other portions of the internal request, the 3331 internal service can be assured that the correct party, the trusted 3332 proxy, has processed the request and presented it to the correct 3333 service. The proxy's signature input consists of the following: 3335 NOTE: '\' line wrapping per RFC 8792 3337 "@path": /foo 3338 "@query": param=Value&Pet=dog 3339 "@method": POST 3340 "@authority": service.internal.example 3341 "client-cert": :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQ\ 3342 KDBJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBD\ 3343 QTAeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDM\ 3344 FkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXm\ 3345 ckC8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQY\ 3346 DVR0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8B\ 3347 Af8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQ\ 3348 GV4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0\ 3349 Q6bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: 3350 "@signature-params": ("@path" "@query" "@method" "@authority" \ 3351 "client-cert");created=1618884473;keyid="test-key-ecc-p256" 3353 This results in the following signature: 3355 NOTE: '\' line wrapping per RFC 8792 3357 aLFj9LxKArG+6IY9mfdR3e6K1zfoDJKw71fAkWROXZh34FIiWKAgshFIfBjmiU2X01u\ 3358 6YbDkRgzwyg5L9tky0w== 3360 Which results in the following signed request sent from the proxy to 3361 the internal service with the proxy's signature under the label ttrp: 3363 NOTE: '\' line wrapping per RFC 8792 3365 POST /foo?param=Value&Pet=dog HTTP/1.1 3366 Host: service.internal.example 3367 Date: Tue, 20 Apr 2021 02:07:55 GMT 3368 Content-Type: application/json 3369 Content-Length: 18 3370 Client-Cert: :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQKD\ 3371 BJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBDQT\ 3372 AeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDMFk\ 3373 wEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXmck\ 3374 C8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQYDV\ 3375 R0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8BAf\ 3376 8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQGV\ 3377 4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0Q6\ 3378 bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: 3379 Signature-Input: ttrp=("@path" "@query" "@method" "@authority" \ 3380 "client-cert");created=1618884473;keyid="test-key-ecc-p256" 3381 Signature: ttrp=:aLFj9LxKArG+6IY9mfdR3e6K1zfoDJKw71fAkWROXZh34FIiWK\ 3382 AgshFIfBjmiU2X01u6YbDkRgzwyg5L9tky0w==: 3384 {"hello": "world"} 3386 The internal service can validate the proxy's signature and therefore 3387 be able to trust that the client's certificate has been appropriately 3388 processed. 3390 Acknowledgements 3392 This specification was initially based on the draft-cavage-http- 3393 signatures internet draft. The editors would like to thank the 3394 authors of that draft, Mark Cavage and Manu Sporny, for their work on 3395 that draft and their continuing contributions. The specification 3396 also includes contributions from the draft-oauth-signed-http-request 3397 internet draft and other similar efforts. 3399 The editors would also like to thank the following individuals for 3400 feedback, insight, and implementation of this draft and its 3401 predecessors (in alphabetical order): Mark Adamcin, Mark Allen, Paul 3402 Annesley, Karl Böhlmark, Stéphane Bortzmeyer, Sarven Capadisli, Liam 3403 Dennehy, Stephen Farrell, Phillip Hallam-Baker, Eric Holmes, Andrey 3404 Kislyuk, Adam Knight, Dave Lehn, Dave Longley, Ilari Liusvaara, James 3405 H. Manger, Kathleen Moriarty, Mark Nottingham, Yoav Nir, Adrian 3406 Palmer, Lucas Pardue, Roberto Polli, Julian Reschke, Michael 3407 Richardson, Wojciech Rygielski, Adam Scarr, Cory J. Slep, Dirk 3408 Stein, Henry Story, Lukasz Szewc, Chris Webber, and Jeffrey Yasskin. 3410 Document History 3412 _RFC EDITOR: please remove this section before publication_ 3414 * draft-ietf-httpbis-message-signatures 3416 - -08 3418 o Editorial fixes. 3420 o Changed "specialty component" to "derived component". 3422 o Expanded signature input generation and ABNF rules. 3424 o Added Ed25519 algorithm. 3426 o Clarified encoding of ECDSA signature. 3428 o Clarified use of non-deterministic algorithms. 3430 - -07 3432 o Added security and privacy considerations. 3434 o Added pointers to algorithm values from definition sections. 3436 o Expanded IANA registry sections. 3438 o Clarified that the signing and verification algorithms take 3439 application requirements as inputs. 3441 o Defined "signature targets" of request, response, and 3442 related-response for specialty components. 3444 - -06 3446 o Updated language for message components, including 3447 identifiers and values. 3449 o Clarified that Signature-Input and Signature are fields 3450 which can be used as headers or trailers. 3452 o Add "Accept-Signature" field and semantics for signature 3453 negotiation. 3455 o Define new specialty content identifiers, re-defined 3456 request-target identifier. 3458 o Added request-response binding. 3460 - -05 3462 o Remove list prefixes. 3464 o Clarify signature algorithm parameters. 3466 o Update and fix examples. 3468 o Add examples for ECC and HMAC. 3470 - -04 3472 o Moved signature component definitions up to intro. 3474 o Created formal function definitions for algorithms to 3475 fulfill. 3477 o Updated all examples. 3479 o Added nonce parameter field. 3481 - -03 3483 o Clarified signing and verification processes. 3485 o Updated algorithm and key selection method. 3487 o Clearly defined core algorithm set. 3489 o Defined JOSE signature mapping process. 3491 o Removed legacy signature methods. 3493 o Define signature parameters separately from "signature" 3494 object model. 3496 o Define serialization values for signature-input header based 3497 on signature input. 3499 - -02 3500 o Removed editorial comments on document sources. 3502 o Removed in-document issues list in favor of tracked issues. 3504 o Replaced unstructured Signature header with Signature-Input 3505 and Signature Dictionary Structured Header Fields. 3507 o Defined content identifiers for individual Dictionary 3508 members, e.g., "x-dictionary-field";key=member-name. 3510 o Defined content identifiers for first N members of a List, 3511 e.g., "x-list-field":prefix=4. 3513 o Fixed up examples. 3515 o Updated introduction now that it's adopted. 3517 o Defined specialty content identifiers and a means to extend 3518 them. 3520 o Required signature parameters to be included in signature. 3522 o Added guidance on backwards compatibility, detection, and 3523 use of signature methods. 3525 - -01 3527 o Strengthened requirement for content identifiers for header 3528 fields to be lower-case (changed from SHOULD to MUST). 3530 o Added real example values for Creation Time and Expiration 3531 Time. 3533 o Minor editorial corrections and readability improvements. 3535 - -00 3537 o Initialized from draft-richanna-http-message-signatures-00, 3538 following adoption by the working group. 3540 * draft-richanna-http-message-signatures 3542 - -00 3544 o Converted to xml2rfc v3 and reformatted to comply with RFC 3545 style guides. 3547 o Removed Signature auth-scheme definition and related 3548 content. 3550 o Removed conflicting normative requirements for use of 3551 algorithm parameter. Now MUST NOT be relied upon. 3553 o Removed Extensions appendix. 3555 o Rewrote abstract and introduction to explain context and 3556 need, and challenges inherent in signing HTTP messages. 3558 o Rewrote and heavily expanded algorithm definition, retaining 3559 normative requirements. 3561 o Added definitions for key terms, referenced RFC 7230 for 3562 HTTP terms. 3564 o Added examples for canonicalization and signature generation 3565 steps. 3567 o Rewrote Signature header definition, retaining normative 3568 requirements. 3570 o Added default values for algorithm and expires parameters. 3572 o Rewrote HTTP Signature Algorithms registry definition. 3573 Added change control policy and registry template. Removed 3574 suggested URI. 3576 o Added IANA HTTP Signature Parameter registry. 3578 o Added additional normative and informative references. 3580 o Added Topics for Working Group Discussion section, to be 3581 removed prior to publication as an RFC. 3583 Authors' Addresses 3585 Annabelle Backman (editor) 3586 Amazon 3587 P.O. Box 81226 3588 Seattle, WA 98108-1226 3589 United States of America 3591 Email: richanna@amazon.com 3592 URI: https://www.amazon.com/ 3593 Justin Richer 3594 Bespoke Engineering 3596 Email: ietf@justin.richer.org 3597 URI: https://bspk.io/ 3599 Manu Sporny 3600 Digital Bazaar 3601 203 Roanoke Street W. 3602 Blacksburg, VA 24060 3603 United States of America 3605 Email: msporny@digitalbazaar.com 3606 URI: https://manu.sporny.org/