idnits 2.17.1 draft-ietf-httpbis-message-signatures-10.txt: -(3737): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 6 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (26 May 2022) is 702 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. 'HTTP' -- Possible downref: Normative reference to a draft: ref. 'HTTP1' ** 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 -- 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-02 == Outdated reference: A later version (-13) exists of draft-ietf-httpbis-digest-headers-09 Summary: 6 errors (**), 0 flaws (~~), 4 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: 27 November 2022 Bespoke Engineering 6 M. Sporny 7 Digital Bazaar 8 26 May 2022 10 HTTP Message Signatures 11 draft-ietf-httpbis-message-signatures-10 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 27 November 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. Conventions and Terminology . . . . . . . . . . . . . . . 7 77 1.4. Application of HTTP Message Signatures . . . . . . . . . 10 78 2. HTTP Message Components . . . . . . . . . . . . . . . . . . . 11 79 2.1. HTTP Fields . . . . . . . . . . . . . . . . . . . . . . . 12 80 2.1.1. Canonicalized Structured HTTP Fields . . . . . . . . 14 81 2.1.2. Dictionary Structured Field Members . . . . . . . . . 14 82 2.2. Derived Components . . . . . . . . . . . . . . . . . . . 15 83 2.2.1. Signature Parameters . . . . . . . . . . . . . . . . 17 84 2.2.2. Method . . . . . . . . . . . . . . . . . . . . . . . 18 85 2.2.3. Target URI . . . . . . . . . . . . . . . . . . . . . 19 86 2.2.4. Authority . . . . . . . . . . . . . . . . . . . . . . 19 87 2.2.5. Scheme . . . . . . . . . . . . . . . . . . . . . . . 20 88 2.2.6. Request Target . . . . . . . . . . . . . . . . . . . 20 89 2.2.7. Path . . . . . . . . . . . . . . . . . . . . . . . . 22 90 2.2.8. Query . . . . . . . . . . . . . . . . . . . . . . . . 22 91 2.2.9. Query Parameters . . . . . . . . . . . . . . . . . . 23 92 2.2.10. Status Code . . . . . . . . . . . . . . . . . . . . . 25 93 2.3. Request-Response Signature Binding . . . . . . . . . . . 25 94 2.4. Creating the Signature Base . . . . . . . . . . . . . . . 28 95 3. HTTP Message Signatures . . . . . . . . . . . . . . . . . . . 30 96 3.1. Creating a Signature . . . . . . . . . . . . . . . . . . 31 97 3.2. Verifying a Signature . . . . . . . . . . . . . . . . . . 33 98 3.2.1. Enforcing Application Requirements . . . . . . . . . 35 99 3.3. Signature Algorithm Methods . . . . . . . . . . . . . . . 36 100 3.3.1. RSASSA-PSS using SHA-512 . . . . . . . . . . . . . . 37 101 3.3.2. RSASSA-PKCS1-v1_5 using SHA-256 . . . . . . . . . . . 37 102 3.3.3. HMAC using SHA-256 . . . . . . . . . . . . . . . . . 38 103 3.3.4. ECDSA using curve P-256 DSS and SHA-256 . . . . . . . 38 104 3.3.5. EdDSA using curve edwards25519 . . . . . . . . . . . 39 105 3.3.6. JSON Web Signature (JWS) algorithms . . . . . . . . . 40 106 4. Including a Message Signature in a Message . . . . . . . . . 40 107 4.1. The Signature-Input HTTP Field . . . . . . . . . . . . . 41 108 4.2. The Signature HTTP Field . . . . . . . . . . . . . . . . 41 109 4.3. Multiple Signatures . . . . . . . . . . . . . . . . . . . 42 110 5. Requesting Signatures . . . . . . . . . . . . . . . . . . . . 45 111 5.1. The Accept-Signature Field . . . . . . . . . . . . . . . 46 112 5.2. Processing an Accept-Signature . . . . . . . . . . . . . 47 113 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 114 6.1. HTTP Signature Algorithms Registry . . . . . . . . . . . 48 115 6.1.1. Registration Template . . . . . . . . . . . . . . . . 48 116 6.1.2. Initial Contents . . . . . . . . . . . . . . . . . . 49 117 6.2. HTTP Signature Metadata Parameters Registry . . . . . . . 49 118 6.2.1. Registration Template . . . . . . . . . . . . . . . . 49 119 6.2.2. Initial Contents . . . . . . . . . . . . . . . . . . 50 120 6.3. HTTP Signature Derived Component Names Registry . . . . . 50 121 6.3.1. Registration Template . . . . . . . . . . . . . . . . 51 122 6.3.2. Initial Contents . . . . . . . . . . . . . . . . . . 51 123 6.4. HTTP Signature Component Parameters Registry . . . . . . 53 124 6.4.1. Registration Template . . . . . . . . . . . . . . . . 53 125 6.4.2. Initial Contents . . . . . . . . . . . . . . . . . . 53 126 7. Security Considerations . . . . . . . . . . . . . . . . . . . 54 127 7.1. Signature Verification Skipping . . . . . . . . . . . . . 55 128 7.2. Use of TLS . . . . . . . . . . . . . . . . . . . . . . . 55 129 7.3. Signature Replay . . . . . . . . . . . . . . . . . . . . 55 130 7.4. Insufficient Coverage . . . . . . . . . . . . . . . . . . 56 131 7.5. Cryptography and Signature Collision . . . . . . . . . . 56 132 7.6. Key Theft . . . . . . . . . . . . . . . . . . . . . . . . 57 133 7.7. Modification of Required Message Parameters . . . . . . . 57 134 7.8. Mismatch of Signature Parameters from Message . . . . . . 58 135 7.9. Multiple Signature Confusion . . . . . . . . . . . . . . 58 136 7.10. Signature Labels . . . . . . . . . . . . . . . . . . . . 58 137 7.11. Symmetric Cryptography . . . . . . . . . . . . . . . . . 59 138 7.12. Canonicalization Attacks . . . . . . . . . . . . . . . . 59 139 7.13. Key Specification Mix-Up . . . . . . . . . . . . . . . . 60 140 7.14. HTTP Versions and Component Ambiguity . . . . . . . . . . 60 141 7.15. Key and Algorithm Specification Downgrades . . . . . . . 60 142 7.16. Parsing Structured Field Values . . . . . . . . . . . . . 61 143 7.17. Choosing Message Components . . . . . . . . . . . . . . . 61 144 7.18. Confusing HTTP Field Names for Derived Component Names . 62 145 7.19. Non-deterministic Signature Primitives . . . . . . . . . 62 146 7.20. Choosing Signature Parameters and Derived Components over 147 HTTP Fields . . . . . . . . . . . . . . . . . . . . . . 63 148 7.21. Semantically Equivalent Field Values . . . . . . . . . . 63 149 7.22. Message Content . . . . . . . . . . . . . . . . . . . . . 64 150 8. Privacy Considerations . . . . . . . . . . . . . . . . . . . 65 151 8.1. Identification through Keys . . . . . . . . . . . . . . . 65 152 8.2. Signatures do not provide confidentiality . . . . . . . . 65 153 8.3. Oracles . . . . . . . . . . . . . . . . . . . . . . . . . 66 154 8.4. Required Content . . . . . . . . . . . . . . . . . . . . 66 155 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 156 9.1. Normative References . . . . . . . . . . . . . . . . . . 66 157 9.2. Informative References . . . . . . . . . . . . . . . . . 68 158 Appendix A. Detecting HTTP Message Signatures . . . . . . . . . 69 159 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 69 160 B.1. Example Keys . . . . . . . . . . . . . . . . . . . . . . 69 161 B.1.1. Example Key RSA test . . . . . . . . . . . . . . . . 70 162 B.1.2. Example RSA PSS Key . . . . . . . . . . . . . . . . . 71 163 B.1.3. Example ECC P-256 Test Key . . . . . . . . . . . . . 72 164 B.1.4. Example Ed25519 Test Key . . . . . . . . . . . . . . 73 165 B.1.5. Example Shared Secret . . . . . . . . . . . . . . . . 73 166 B.2. Test Cases . . . . . . . . . . . . . . . . . . . . . . . 73 167 B.2.1. Minimal Signature Using rsa-pss-sha512 . . . . . . . 74 168 B.2.2. Selective Covered Components using rsa-pss-sha512 . . 75 169 B.2.3. Full Coverage using rsa-pss-sha512 . . . . . . . . . 76 170 B.2.4. Signing a Response using ecdsa-p256-sha256 . . . . . 77 171 B.2.5. Signing a Request using hmac-sha256 . . . . . . . . . 78 172 B.2.6. Signing a Request using ed25519 . . . . . . . . . . . 78 173 B.3. TLS-Terminating Proxies . . . . . . . . . . . . . . . . . 79 174 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 81 175 Document History . . . . . . . . . . . . . . . . . . . . . . . . 82 176 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 86 178 1. Introduction 180 Message integrity and authenticity are important security properties 181 that are critical to the secure operation of many HTTP applications. 182 Application developers typically rely on the transport layer to 183 provide these properties, by operating their application over [TLS]. 184 However, TLS only guarantees these properties over a single TLS 185 connection, and the path between client and application may be 186 composed of multiple independent TLS connections (for example, if the 187 application is hosted behind a TLS-terminating gateway or if the 188 client is behind a TLS Inspection appliance). In such cases, TLS 189 cannot guarantee end-to-end message integrity or authenticity between 190 the client and application. Additionally, some operating 191 environments present obstacles that make it impractical to use TLS, 192 or to use features necessary to provide message authenticity. 193 Furthermore, some applications require the binding of an application- 194 level key to the HTTP message, separate from any TLS certificates in 195 use. Consequently, while TLS can meet message integrity and 196 authenticity needs for many HTTP-based applications, it is not a 197 universal solution. 199 This document defines a mechanism for providing end-to-end integrity 200 and authenticity for components of an HTTP message. The mechanism 201 allows applications to create digital signatures or message 202 authentication codes (MACs) over only the components of the message 203 that are meaningful and appropriate for the application. Strict 204 canonicalization rules ensure that the verifier can verify the 205 signature even if the message has been transformed in any of the many 206 ways permitted by HTTP. 208 The signing mechanism described in this document consists of three 209 parts: 211 * A common nomenclature and canonicalization rule set for the 212 different protocol elements and other components of HTTP messages, 213 used to create the signature base. 215 * Algorithms for generating and verifying signatures over HTTP 216 message components using this signature base through application 217 of cryptographic primitives. 219 * A mechanism for attaching a signature and related metadata to an 220 HTTP message, and for parsing attached signatures and metadata 221 from HTTP messages. To facilitate this, this document defines the 222 "Signature-Input" and "Signature" fields. 224 This document also provides a mechanism for a potential verifier to 225 signal to a potential signer that a signature is desired in one or 226 more subsequent messages. This optional negotiation mechanism can be 227 used along with opportunistic or application-driven message 228 signatures by either party. To facilitate this, this document 229 defines the "Accept-Signature" field. 231 1.1. Requirements Discussion 233 HTTP permits and sometimes requires intermediaries to transform 234 messages in a variety of ways. This may result in a recipient 235 receiving a message that is not bitwise equivalent to the message 236 that was originally sent. In such a case, the recipient will be 237 unable to verify a signature over the raw bytes of the sender's HTTP 238 message, as verifying digital signatures or MACs requires both signer 239 and verifier to have the exact same signature base. Since the exact 240 raw bytes of the message cannot be relied upon as a reliable source 241 for a signature base, the signer and verifier must independently 242 create the signature base from their respective versions of the 243 message, via a mechanism that is resilient to safe changes that do 244 not alter the meaning of the message. 246 For a variety of reasons, it is impractical to strictly define what 247 constitutes a safe change versus an unsafe one. Applications use 248 HTTP in a wide variety of ways, and may disagree on whether a 249 particular piece of information in a message (e.g., the message 250 content, the method, or the Date header field) is relevant. Thus a 251 general purpose solution must provide signers with some degree of 252 control over which message components are signed. 254 HTTP applications may be running in environments that do not provide 255 complete access to or control over HTTP messages (such as a web 256 browser's JavaScript environment), or may be using libraries that 257 abstract away the details of the protocol (such as the Java 258 HTTPClient library (https://openjdk.java.net/groups/net/httpclient/ 259 intro.html)). These applications need to be able to generate and 260 verify signatures despite incomplete knowledge of the HTTP message. 262 1.2. HTTP Message Transformations 264 As mentioned earlier, HTTP explicitly permits and in some cases 265 requires implementations to transform messages in a variety of ways. 266 Implementations are required to tolerate many of these 267 transformations. What follows is a non-normative and non-exhaustive 268 list of transformations that may occur under HTTP, provided as 269 context: 271 * Re-ordering of header fields with different header field names 272 (Section 3.2.2 of [HTTP1]). 274 * Combination of header fields with the same field name 275 (Section 3.2.2 of [HTTP1]). 277 * Removal of header fields listed in the Connection header field 278 (Section 6.1 of [HTTP1]). 280 * Addition of header fields that indicate control options 281 (Section 6.1 of [HTTP1]). 283 * Addition or removal of a transfer coding (Section 5.7.2 of 284 [HTTP1]). 286 * Addition of header fields such as Via (Section 5.7.1 of [HTTP1]) 287 and Forwarded (Section 4 of [RFC7239]). 289 Based on the definition of HTTP and the requirements described above, 290 we can identify certain types of transformations that should not 291 prevent signature verification, even when performed on message 292 components covered by the signature. The following list describes 293 those transformations: 295 * Combination of header fields with the same field name. 297 * Reordering of header fields with different names. 299 * Conversion between different versions of the HTTP protocol (e.g., 300 HTTP/1.x to HTTP/2, or vice-versa). 302 * Changes in casing (e.g., "Origin" to "origin") of any case- 303 insensitive components such as header field names, request URI 304 scheme, or host. 306 * Addition or removal of leading or trailing whitespace to a header 307 field value. 309 * Addition or removal of obs-folds. 311 * Changes to the request-target and Host header field that when 312 applied together do not result in a change to the message's 313 effective request URI, as defined in Section 5.5 of [HTTP1]. 315 Additionally, all changes to components not covered by the signature 316 are considered safe. 318 1.3. Conventions and Terminology 320 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 321 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 322 "OPTIONAL" in this document are to be interpreted as described in 323 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 324 capitals, as shown here. 326 The terms "HTTP message", "HTTP request", "HTTP response", absolute- 327 form, absolute-path, "effective request URI", "gateway", "header 328 field", "intermediary", request-target, "sender", and "recipient" are 329 used as defined in [HTTP1]. 331 The term "method" is to be interpreted as defined in Section 4 of 332 [HTTP]. 334 For brevity, the term "signature" on its own is used in this document 335 to refer to both digital signatures (which use asymmetric 336 cryptography) and keyed MACs (which use symmetric cryptography). 338 Similarly, the verb "sign" refers to the generation of either a 339 digital signature or keyed MAC over a given input string. The 340 qualified term "digital signature" refers specifically to the output 341 of an asymmetric cryptographic signing operation. 343 In addition to those listed above, this document uses the following 344 terms: 346 HTTP Message Signature: 347 A digital signature or keyed MAC that covers one or more portions 348 of an HTTP message. Note that a given HTTP Message can contain 349 multiple HTTP Message Signatures. 351 Signer: 352 The entity that is generating or has generated an HTTP Message 353 Signature. Note that multiple entities can act as signers and 354 apply separate HTTP Message Signatures to a given HTTP Message. 356 Verifier: 357 An entity that is verifying or has verified an HTTP Message 358 Signature against an HTTP Message. Note that an HTTP Message 359 Signature may be verified multiple times, potentially by different 360 entities. 362 HTTP Message Component: 363 A portion of an HTTP message that is capable of being covered by 364 an HTTP Message Signature. 366 HTTP Message Component Name: 367 A name that identifies an HTTP Message Component. 369 HTTP Message Component Identifier: 370 The combination of an HTTP Message Component Name and any 371 parameters that uniquely identifies a specific HTTP Message 372 Component in respect to a particular HTTP Message Signature and 373 the HTTP Message it applies to. 375 HTTP Message Component Value: 376 The value associated with a given component identifier within the 377 context of a particular HTTP Message. Component values are 378 derived from the HTTP Message and are usually subject to a 379 canonicalization process. 381 Covered Components: 383 An ordered set of HTTP message component identifiers for fields 384 (Section 2.1) and derived components (Section 2.2) that indicates 385 the set of message components covered by the signature, never 386 including the @signature-params identifier itself. The order of 387 this set is preserved and communicated between the signer and 388 verifier to facilitate reconstruction of the signature base. 390 Signature Base: 391 The sequence of bytes processed by the cryptographic algorithm to 392 produce or verify the HTTP Message Signature. The signature base 393 is generated by the signer and verifier using the covered 394 components set and the HTTP Message. 396 HTTP Message Signature Algorithm: 397 A cryptographic algorithm that describes the signing and 398 verification process for the signature, defined in terms of the 399 HTTP_SIGN and HTTP_VERIFY primitives described in Section 3.3. 401 Key Material: 402 The key material required to create or verify the signature. The 403 key material is often identified with an explicit key identifier, 404 allowing the signer to indicate to the verifier which key was 405 used. 407 Creation Time: 408 A timestamp representing the point in time that the signature was 409 generated, as asserted by the signer. 411 Expiration Time: 412 A timestamp representing the point in time after which the 413 signature should no longer be accepted by the verifier, as 414 asserted by the signer. 416 The term "Unix time" is defined by [POSIX.1], Section 4.16 417 (http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ 418 V1_chap04.html#tag_04_16). 420 This document contains non-normative examples of partial and complete 421 HTTP messages. Some examples use a single trailing backslash '' to 422 indicate line wrapping for long values, as per [RFC8792]. The \ 423 character and leading spaces on wrapped lines are not part of the 424 value. 426 This document uses the following terminology from Section 3 of 427 [STRUCTURED-FIELDS] to specify syntax and parsing: List, Inner List, 428 Dictionary, String, Integer, Byte Sequence, and Boolean. This 429 document uses the following ABNF rules from [STRUCTURED-FIELDS] where 430 applicable: sf-string, key, parameters. 432 1.4. Application of HTTP Message Signatures 434 HTTP Message Signatures are designed to be a general-purpose security 435 mechanism applicable in a wide variety of circumstances and 436 applications. In order to properly and safely apply HTTP Message 437 Signatures, an application or profile of this specification MUST 438 specify all of the following items: 440 * The set of component identifiers (Section 2) that are expected and 441 required. For example, an authorization protocol could mandate 442 that the Authorization field be covered to protect the 443 authorization credentials and mandate the signature parameters 444 contain a created parameter, while an API expecting semantically 445 relevant HTTP message content could require the Content-Digest 446 header to be present and covered. 448 * A means of retrieving the key material used to verify the 449 signature. An application will usually use the keyid parameter of 450 the signature parameters (Section 2.2.1) and define rules for 451 resolving a key from there, though the appropriate key could be 452 known from other means. 454 * A means of determining the signature algorithm used to verify the 455 signature is appropriate for the key material. For example, the 456 process could use the alg parameter of the signature parameters 457 (Section 2.2.1) to state the algorithm explicitly, derive the 458 algorithm from the key material, or use some pre-configured 459 algorithm agreed upon by the signer and verifier. 461 * A means of determining that a given key and algorithm presented in 462 the request are appropriate for the request being made. For 463 example, a server expecting only ECDSA signatures should know to 464 reject any RSA signatures, or a server expecting asymmetric 465 cryptography should know to reject any symmetric cryptography. 467 An application using signatures also has to ensure that the verifier 468 will have access to all required information to re-create the 469 signature base. For example, a server behind a reverse proxy would 470 need to know the original request URI to make use of identifiers like 471 @target-uri. Additionally, an application using signatures in 472 responses would need to ensure that clients receiving signed 473 responses have access to all the signed portions, including any 474 portions of the request that were signed by the server. 476 The details of this kind of profiling are the purview of the 477 application and outside the scope of this specification, however some 478 additional considerations are discussed in Section 7. 480 2. HTTP Message Components 482 In order to allow signers and verifiers to establish which components 483 are covered by a signature, this document defines component 484 identifiers for components covered by an HTTP Message Signature, a 485 set of rules for deriving and canonicalizing the values associated 486 with these component identifiers from the HTTP Message, and the means 487 for combining these canonicalized values into a signature base. The 488 values for these items MUST be accessible to both the signer and the 489 verifier of the message, which means these are usually derived from 490 aspects of the HTTP message or signature itself. 492 Some HTTP message components can undergo transformations that change 493 the bitwise value without altering meaning of the component's value 494 (for example, the merging together of header fields with the same 495 name). Message component values must therefore be canonicalized 496 before it is signed, to ensure that a signature can be verified 497 despite such intermediary transformations. This document defines 498 rules for each component identifier that transform the identifier's 499 associated component value into such a canonical form. 501 Component identifiers are serialized using the production grammar 502 defined by [STRUCTURED-FIELDS], Section 4. The component identifier 503 has a component name, which is a String value serialized using the 504 sf-string ABNF rule. The component identifier MAY also include 505 defined parameters which are serialized using the parameters rule. 507 component-identifier = component-name parameters 508 component-name = sf-string 510 Note that this means the serialization of the component name itself 511 is encased in double quotes, with parameters following as a 512 semicolon-separated list, such as "cache-control", "date", or 513 "@signature-params", and "example-dictionary";key="foo". 515 One component identifier is distinct from another if either the 516 component name or its parameters differ. Within a single list of 517 covered components, each component identifier MUST be distinct from 518 every other component identifier. Multiple component identifiers 519 having the same component name MAY be included if they have 520 parameters that make them distinct. 522 The component value associated with a component identifier is defined 523 by the identifier itself. Component values MUST NOT contain newline 524 (\n) characters. 526 The following sections define component identifier types, their 527 parameters, their associated values, and the canonicalization rules 528 for their values. The method for combining component identifiers 529 into the signature base is defined in Section 2.4. 531 2.1. HTTP Fields 533 The component name for an HTTP field is the lowercased form of its 534 field name. While HTTP field names are case-insensitive, 535 implementations MUST use lowercased field names (e.g., content-type, 536 date, etag) when using them as component names. 538 Unless overridden by additional parameters and rules, the HTTP field 539 value MUST be canonicalized as a single combined value as defined in 540 Section 5.2 of [HTTP]. 542 If the combined value is not available for a given header, the 543 following algorithm will produce canonicalized results for an 544 implementation: 546 1. Create an ordered list of the field values of each instance of 547 the field in the message, in the order that they occur (or will 548 occur) in the message. 550 2. Strip leading and trailing whitespace from each item in the list. 551 Note that since HTTP field values are not allowed to contain 552 leading and trailing whitespace, this will be a no-op in a 553 compliant implementation. 555 3. Remove any obsolete line-folding within the line and replace it 556 with a single space (" "), as discussed in Section 5.2 of 557 [HTTP1]. Note that this behavior is specific to [HTTP1] and does 558 not apply to other versions of the HTTP specification. 560 4. Concatenate the list of values together with a single comma (",") 561 and a single space (" ") between each item. 563 The resulting string is the canonicalized component value. 565 Note that some HTTP fields have values with multiple valid 566 serializations that have equivalent semantics. Applications signing 567 and processing such fields MUST consider how to handle the values of 568 such fields to ensure that the signer and verifier can derive the 569 same value, as discussed in Section 7.21. 571 Following are non-normative examples of canonicalized values for 572 header fields, given the following example HTTP message fragment: 574 Host: www.example.com 575 Date: Tue, 20 Apr 2021 02:07:56 GMT 576 X-OWS-Header: Leading and trailing whitespace. 577 X-Obs-Fold-Header: Obsolete 578 line folding. 579 Cache-Control: max-age=60 580 Cache-Control: must-revalidate 581 Example-Dict: a=1, b=2;x=1;y=2, c=(a b c) 583 The following example shows canonicalized values for these example 584 header fields, presented using the signature base format discussed in 585 Section 2.4: 587 "host": www.example.com 588 "date": Tue, 20 Apr 2021 02:07:56 GMT 589 "x-ows-header": Leading and trailing whitespace. 590 "x-obs-fold-header": Obsolete line folding. 591 "cache-control": max-age=60, must-revalidate 592 "example-dict": a=1, b=2;x=1;y=2, c=(a b c) 594 Since empty HTTP header fields are allowed, they are also able to be 595 signed when present in a message. The canonicalized value is the 596 empty string. This means that the following empty header: 598 NOTE: '\' line wrapping per RFC 8792 600 X-Empty-Header: \ 602 Is serialized by the signature base generation algorithm 603 (Section 2.4) with an empty string value following the colon and 604 space added after the content identifier. 606 NOTE: '\' line wrapping per RFC 8792 608 "x-empty-header": \ 610 Note: these are shown here using the line wrapping algorithm in 611 [RFC8792] due to limitations in the document format that strips 612 trailing spaces from diagrams. 614 Any HTTP field component identifiers MAY have the following 615 parameters in specific circumstances. 617 sf A boolean flag indicating that the field value is to be 618 canonicalized using strict encoding of the structured field value. 619 Section 2.1.1 621 key A string parameter used to select a single member value from a 622 dictionary structured field. Section 2.1.2 624 2.1.1. Canonicalized Structured HTTP Fields 626 If the value of the the HTTP field in question is a structured field 627 ([STRUCTURED-FIELDS]), the component identifier MAY include the sf 628 parameter to indicate it is a known structured field. If this 629 parameter is included with a component identifier, the HTTP field 630 value MUST be serialized using the rules specified in Section 4 of 631 [STRUCTURED-FIELDS] applicable to the type of the HTTP field. Note 632 that this process will replace any optional internal whitespace with 633 a single space character, among other potential transformations of 634 the value. 636 For example, the following dictionary field is a valid serialization: 638 Example-Dict: a=1, b=2;x=1;y=2, c=(a b c) 640 If included in the input string as-is, it would be: 642 "example-dict": a=1, b=2;x=1;y=2, c=(a b c) 644 However, if the sf parameter is added, the value is re-serialized as 645 follows: 647 "example-dict";sf: a=1, b=2;x=1;y=2, c=(a b c) 649 The resulting string is used as the component value in Section 2.1. 651 2.1.2. Dictionary Structured Field Members 653 If a given field is known by the application to be a Dictionary 654 structured field, an individual member in the value of that 655 Dictionary is identified by using the parameter key and the 656 Dictionary member key as a String value. 658 An individual member value of a Dictionary Structured Field is 659 canonicalized by applying the serialization algorithm described in 660 Section 4.1.2 of [STRUCTURED-FIELDS] on the member_value and its 661 parameters, without the dictionary key. Specifically, the value is 662 serialized as an Item or Inner List (the two possible values of a 663 Dictionary member). 665 Each parameterized key for a given field MUST NOT appear more than 666 once in the signature base. Parameterized keys MAY appear in any 667 order in the signature base, regardless of the order they occur in 668 the source Dictionary. 670 If a Dictionary key is named as a covered component but it does not 671 occur in the Dictionary, this MUST cause an error in the signature 672 base generation. 674 Following are non-normative examples of canonicalized values for 675 Dictionary structured field members given the following example 676 header field, whose value is known by the application to be a 677 Dictionary: 679 Example-Dict: a=1, b=2;x=1;y=2, c=(a b c), d 681 The following example shows canonicalized values for different 682 component identifiers of this field, presented using the signature 683 base format discussed in Section 2.4: 685 "example-dict";key="a": 1 686 "example-dict";key="d": ?1 687 "example-dict";key="b": 2;x=1;y=2 688 "example-dict";key="c": (a b c) 690 Note that the value for key="c" has been re-serialized according to 691 the strict member_value algorithm. 693 2.2. Derived Components 695 In addition to HTTP fields, there are a number of different 696 components that can be derived from the control data, processing 697 context, or other aspects of the HTTP message being signed. Such 698 derived components can be included in the signature base by defining 699 a component name, possible parameters, and the derivation method for 700 its component value. 702 Derived component names MUST start with the "at" @ character. This 703 differentiates derived component names from HTTP field names, which 704 cannot contain the @ character as per Section 5.1 of [HTTP]. 705 Processors of HTTP Message Signatures MUST treat derived component 706 names separately from field names, as discussed in Section 7.18. 708 This specification defines the following derived components: 710 @signature-params The signature metadata parameters for this 711 signature. (Section 2.2.1) 713 @method The method used for a request. (Section 2.2.2) 715 @target-uri The full target URI for a request. (Section 2.2.3) 717 @authority The authority of the target URI for a request. 719 (Section 2.2.4) 721 @scheme The scheme of the target URI for a request. (Section 2.2.5) 723 @request-target The request target. (Section 2.2.6) 725 @path The absolute path portion of the target URI for a request. 726 (Section 2.2.7) 728 @query The query portion of the target URI for a request. 729 (Section 2.2.8) 731 @query-param A parsed query parameter of the target URI for a 732 request. (Section 2.2.9) 734 @status The status code for a response. (Section 2.2.10). 736 Additional derived component names MAY be defined and registered in 737 the HTTP Signatures Derived Component Name Registry. (Section 6.3) 739 Derived component values are taken from the context of the target 740 message for the signature. This context includes information about 741 the message itself, such as its control data, as well as any 742 additional state and context held by the signer. In particular, when 743 signing a response, the signer can include any derived components 744 from the originating request by using the request-response signature 745 binding parameter (Section 2.3). 747 request: Values derived from and results applied to an HTTP request 748 message as described in Section 3.4 of [HTTP]. 750 response: Values derived from and results applied to an HTTP 751 response message as described in Section 3.4 of [HTTP]. 753 A derived component definition MUST define all targets to which it 754 can be applied. 756 The component value MUST be derived from the HTTP message being 757 signed or the context in which the derivation occurs. The derived 758 component value MUST be of the following form: 760 derived-component-value = *VCHAR 762 2.2.1. Signature Parameters 764 HTTP Message Signatures have metadata properties that provide 765 information regarding the signature's generation and verification, 766 such as the set of covered components, a timestamp, identifiers for 767 verification key material, and other utilities. 769 The signature parameters component name is @signature-params. This 770 message component's value is REQUIRED as part of the signature base 771 (Section 2.4) but the component identifier MUST NOT be enumerated 772 within the set of covered components itself. 774 The signature parameters component value is the serialization of the 775 signature parameters for this signature, including the covered 776 components set with all associated parameters. These parameters 777 include any of the following: 779 * created: Creation time as an Integer UNIX timestamp value. Sub- 780 second precision is not supported. Inclusion of this parameter is 781 RECOMMENDED. 783 * expires: Expiration time as an Integer UNIX timestamp value. Sub- 784 second precision is not supported. 786 * nonce: A random unique value generated for this signature as a 787 String value. 789 * alg: The HTTP message signature algorithm from the HTTP Message 790 Signature Algorithm Registry, as a String value. 792 * keyid: The identifier for the key material as a String value. 794 Additional parameters can be defined in the HTTP Signature Parameters 795 Registry (Section 6.2.2). 797 The signature parameters component value is serialized as a 798 parameterized inner list using the rules in Section 4 of 799 [STRUCTURED-FIELDS] as follows: 801 1. Let the output be an empty string. 803 2. Determine an order for the component identifiers of the covered 804 components, not including the @signature-params component 805 identifier itself. Once this order is chosen, it cannot be 806 changed. This order MUST be the same order as used in creating 807 the signature base (Section 2.4). 809 3. Serialize the component identifiers of the covered components, 810 including all parameters, as an ordered inner-list according to 811 Section 4.1.1.1 of [STRUCTURED-FIELDS] and append this to the 812 output. 814 4. Determine an order for any signature parameters. Once this order 815 is chosen, it cannot be changed. 817 5. Append the parameters to the inner-list in the chosen order 818 according to Section 4.1.1.2 of [STRUCTURED-FIELDS], skipping 819 parameters that are not available or not used for this message 820 signature. 822 6. The output contains the signature parameters component value. 824 Note that the Inner List serialization from Section 4.1.1.1 of 825 [STRUCTURED-FIELDS] is used for the covered component value instead 826 of the List serialization from Section 4.1.1 of [STRUCTURED-FIELDS] 827 in order to facilitate parallelism with this value's inclusion in the 828 Signature-Input field, as discussed in Section 4.1. 830 This example shows a canonicalized value for the parameters of a 831 given signature: 833 NOTE: '\' line wrapping per RFC 8792 835 ("@target-uri" "@authority" "date" "cache-control")\ 836 ;keyid="test-key-rsa-pss";alg="rsa-pss-sha512";\ 837 created=1618884475;expires=1618884775 839 Note that an HTTP message could contain multiple signatures 840 (Section 4.3), but only the signature parameters used for a single 841 signature are included in an entry. 843 2.2.2. Method 845 The @method derived component refers to the HTTP method of a request 846 message. The component value is canonicalized by taking the value of 847 the method as a string. Note that the method name is case-sensitive 848 as per [HTTP], Section 9.1, and conventionally standardized method 849 names are uppercase US-ASCII. If used, the @method component 850 identifier MUST occur only once in the covered components. 852 For example, the following request message: 854 POST /path?param=value HTTP/1.1 855 Host: www.example.com 856 Would result in the following @method component value: 858 POST 860 And the following signature base line: 862 "@method": POST 864 2.2.3. Target URI 866 The @target-uri derived component refers to the target URI of a 867 request message. The component value is the full absolute target URI 868 of the request, potentially assembled from all available parts 869 including the authority and request target as described in [HTTP], 870 Section 7.1. If used, the @target-uri component identifier MUST 871 occur only once in the covered components. 873 For example, the following message sent over HTTPS: 875 POST /path?param=value HTTP/1.1 876 Host: www.example.com 878 Would result in the following @target-uri component value: 880 https://www.example.com/path?param=value 882 And the following signature base line: 884 "@target-uri": https://www.example.com/path?param=value 886 2.2.4. Authority 888 The @authority derived component refers to the authority component of 889 the target URI of the HTTP request message, as defined in [HTTP], 890 Section 7.2. In HTTP 1.1, this is usually conveyed using the Host 891 header, while in HTTP 2 and HTTP 3 it is conveyed using the 892 :authority pseudo-header. The value is the fully-qualified authority 893 component of the request, comprised of the host and, optionally, port 894 of the request target, as a string. The component value MUST be 895 normalized according to the rules in [HTTP], Section 4.2.3. Namely, 896 the host name is normalized to lowercase and the default port is 897 omitted. If used, the @authority component identifier MUST occur 898 only once in the covered components. 900 For example, the following request message: 902 POST /path?param=value HTTP/1.1 903 Host: www.example.com 904 Would result in the following @authority component value: 906 www.example.com 908 And the following signature base line: 910 "@authority": www.example.com 912 The @authority derived component SHOULD be used instead of signing 913 the Host header directly, see Section 7.20. 915 2.2.5. Scheme 917 The @scheme derived component refers to the scheme of the target URL 918 of the HTTP request message. The component value is the scheme as a 919 string as defined in [HTTP], Section 4.2. While the scheme itself is 920 case-insensitive, it MUST be normalized to lowercase for inclusion in 921 the signature base. If used, the @scheme component identifier MUST 922 occur only once in the covered components. 924 For example, the following request message requested over plain HTTP: 926 POST /path?param=value HTTP/1.1 927 Host: www.example.com 929 Would result in the following @scheme component value: 931 http 933 And the following signature base line: 935 "@scheme": http 937 2.2.6. Request Target 939 The @request-target derived component refers to the full request 940 target of the HTTP request message, as defined in [HTTP], 941 Section 7.1. The component value of the request target can take 942 different forms, depending on the type of request, as described 943 below. If used, the @request-target component identifier MUST occur 944 only once in the covered components. 946 For HTTP 1.1, the component value is equivalent to the request target 947 portion of the request line. However, this value is more difficult 948 to reliably construct in other versions of HTTP. Therefore, it is 949 NOT RECOMMENDED that this component be used when versions of HTTP 950 other than 1.1 might be in use. 952 The origin form value is combination of the absolute path and query 953 components of the request URL. For example, the following request 954 message: 956 POST /path?param=value HTTP/1.1 957 Host: www.example.com 959 Would result in the following @request-target component value: 961 /path?param=value 963 And the following signature base line: 965 "@request-target": /path?param=value 967 The following request to an HTTP proxy with the absolute-form value, 968 containing the fully qualified target URI: 970 GET https://www.example.com/path?param=value HTTP/1.1 972 Would result in the following @request-target component value: 974 https://www.example.com/path?param=value 976 And the following signature base line: 978 "@request-target": https://www.example.com/path?param=value 980 The following CONNECT request with an authority-form value, 981 containing the host and port of the target: 983 CONNECT www.example.com:80 HTTP/1.1 984 Host: www.example.com 986 Would result in the following @request-target component value: 988 www.example.com:80 990 And the following signature base line: 992 "@request-target": www.example.com:80 994 The following OPTIONS request message with the asterisk-form value, 995 containing a single asterisk * character: 997 OPTIONS * HTTP/1.1 998 Host: www.example.com 999 Would result in the following @request-target component value: 1001 * 1003 And the following signature base line: 1005 "@request-target": * 1007 2.2.7. Path 1009 The @path derived component refers to the target path of the HTTP 1010 request message. The component value is the absolute path of the 1011 request target defined by [RFC3986], with no query component and no 1012 trailing ? character. The value is normalized according to the rules 1013 in [HTTP], Section 4.2.3. Namely, an empty path string is normalized 1014 as a single slash / character, and path components are represented by 1015 their values after decoding any percent-encoded octets. If used, the 1016 @path component identifier MUST occur only once in the covered 1017 components. 1019 For example, the following request message: 1021 POST /path?param=value HTTP/1.1 1022 Host: www.example.com 1024 Would result in the following @path component value: 1026 /path 1028 And the following signature base line: 1030 "@path": /path 1032 2.2.8. Query 1034 The @query derived component refers to the query component of the 1035 HTTP request message. The component value is the entire normalized 1036 query string defined by [RFC3986], including the leading ? character. 1037 The value is normalized according to the rules in [HTTP], 1038 Section 4.2.3. Namely, percent-encoded octets are decoded. If used, 1039 the @query component identifier MUST occur only once in the covered 1040 components. 1042 For example, the following request message: 1044 POST /path?param=value&foo=bar&baz=batman HTTP/1.1 1045 Host: www.example.com 1046 Would result in the following @query component value: 1048 ?param=value&foo=bar&baz=batman 1050 And the following signature base line: 1052 "@query": ?param=value&foo=bar&baz=batman 1054 The following request message: 1056 POST /path?queryString HTTP/1.1 1057 Host: www.example.com 1059 Would result in the following @query component value: 1061 ?queryString 1063 And the following signature base line: 1065 "@query": ?queryString 1067 If the query string is absent from the request message, the value is 1068 the leading ? character alone: 1070 ? 1072 Resulting in the following signature base line: 1074 "@query": ? 1076 2.2.9. Query Parameters 1078 If a request target URI uses HTML form parameters in the query string 1079 as defined in HTMLURL, Section 5 [HTMLURL], the @query-param derived 1080 component allows addressing of individual query parameters. The 1081 query parameters MUST be parsed according to HTMLURL, Section 5.1 1082 [HTMLURL], resulting in a list of (nameString, valueString) tuples. 1083 The REQUIRED name parameter of each component identifier contains the 1084 nameString of a single query parameter as a String value. Several 1085 different named query parameters MAY be included in the covered 1086 components. Single named parameters MAY occur in any order in the 1087 covered components. 1089 The component value of a single named parameter is the the 1090 valueString of the named query parameter defined by HTMLURL, 1091 Section 5.1 [HTMLURL], which is the value after percent-encoded 1092 octets are decoded. Note that this value does not include any 1093 leading ? characters, equals sign =, or separating & characters. 1094 Named query parameters with an empty valueString are included with an 1095 empty string as the component value. 1097 If a query parameter is named as a covered component but it does not 1098 occur in the query parameters, this MUST cause an error in the 1099 signature base generation. 1101 For example for the following request: 1103 POST /path?param=value&foo=bar&baz=batman&qux= HTTP/1.1 1104 Host: www.example.com 1106 Indicating the baz, qux and param named query parameters in would 1107 result in the following @query-param component values: 1109 _baz:_ batman 1111 _qux:_ an empty string 1113 _param:_ value 1115 And the following signature base lines: 1117 NOTE: '\' line wrapping per RFC 8792 1119 "@query-param";name="baz": batman 1120 "@query-param";name="qux": \ 1122 "@query-param";name="param": value 1124 If a parameter name occurs multiple times in a request, all parameter 1125 values of that name MUST be included in separate signature base lines 1126 in the order in which the parameters occur in the target URI. Note 1127 that in some implementations, the order of parsed query parameters is 1128 not stable, and this situation could lead to unexpected results. If 1129 multiple parameters are common within an application, it is 1130 RECOMMENDED to sign the entire query string using the @query 1131 component identifier defined in Section 2.2.8. 1133 2.2.10. Status Code 1135 The @status derived component refers to the three-digit numeric HTTP 1136 status code of a response message as defined in [HTTP], Section 15. 1137 The component value is the serialized three-digit integer of the HTTP 1138 status code, with no descriptive text. If used, the @status 1139 component identifier MUST occur only once in the covered components. 1141 For example, the following response message: 1143 HTTP/1.1 200 OK 1144 Date: Fri, 26 Mar 2010 00:05:00 GMT 1146 Would result in the following @status component value: 1148 200 1150 And the following signature base line: 1152 "@status": 200 1154 The @status component identifier MUST NOT be used in a request 1155 message. 1157 2.3. Request-Response Signature Binding 1159 When a request message results in a signed response message, the 1160 signer can include portions of the request message in the signature 1161 base by adding the req parameter to the component identifier. 1163 req Indicates that the component value is derived from the request 1164 that triggered this response message and not from the response 1165 message directly. 1167 This parameter can be applied to both HTTP fields and derived 1168 components with the same semantics. The component value for a 1169 message component using this parameter is calculated in the same 1170 manner as it is normally, but data is pulled from the request 1171 message. 1173 Note that the same component name MAY be included with and without 1174 the req parameter in a single signature base, indicating the same 1175 named component from both the request and response message. 1177 The req parameter MAY be combined with other parameters as 1178 appropriate for the component identifier, such as the key parameter 1179 for a dictionary field. 1181 For example, when serving a response for this signed request: 1183 NOTE: '\' line wrapping per RFC 8792 1185 POST /foo?param=Value&Pet=dog HTTP/1.1 1186 Host: example.com 1187 Date: Tue, 20 Apr 2021 02:07:55 GMT 1188 Content-Type: application/json 1189 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1190 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1191 Content-Length: 18 1192 Signature-Input: sig1=("@method" "@authority" "@path" \ 1193 "content-digest" "content-length" "content-type")\ 1194 ;created=1618884475;keyid="test-key-rsa-pss" 1195 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1196 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8Br\ 1197 c8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINTEzpx\ 1198 jqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr65+BXe\ 1199 TG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZElYyUKaAI\ 1200 jZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1202 {"hello": "world"} 1204 This would result in the following unsigned response message: 1206 HTTP/1.1 503 Service Unavailable 1207 Date: Tue, 20 Apr 2021 02:07:56 GMT 1208 Content-Type: application/json 1209 Content-Length: 62 1211 {"busy": true, "message": "Your call is very important to us"} 1213 To cryptographically link the response to the request, the server 1214 signs the response with its own key and includes the signature of 1215 sig1 from the request in the covered components of the response. The 1216 signature base for this example is: 1218 NOTE: '\' line wrapping per RFC 8792 1220 "@status": 503 1221 "content-length": 62 1222 "content-type": application/json 1223 "signature";req;key="sig1": :LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziC\ 1224 LuD8r5MW9S0RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY\ 1225 /UkBIS1M8Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE\ 1226 3IpWINTEzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9Hd\ 1227 bD2Tr65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3\ 1228 LZElYyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1229 "@signature-params": ("@status" "content-length" "content-type" \ 1230 "signature";req;key="sig1");created=1618884479\ 1231 ;keyid="test-key-ecc-p256" 1233 The signed response message is: 1235 NOTE: '\' line wrapping per RFC 8792 1237 HTTP/1.1 503 Service Unavailable 1238 Date: Tue, 20 Apr 2021 02:07:56 GMT 1239 Content-Type: application/json 1240 Content-Length: 62 1241 Signature-Input: reqres=("@status" "content-length" "content-type" \ 1242 "signature";req;key="sig1");created=1618884479\ 1243 ;keyid="test-key-ecc-p256" 1244 Signature: reqres=:vR1E+sDgh0J3dZyVdPc7mK0ZbEMW3N47eDpFjXLE9g95Gx1K\ 1245 QLpdOmDQfedgdLzaFCqfD0WPn9e9/jubyUuZRw==: 1247 {"busy": true, "message": "Your call is very important to us"} 1249 Since the request's signature value itself is not repeated in the 1250 response, the requester MUST keep the original signature value around 1251 long enough to validate the signature of the response that uses this 1252 component identifier. 1254 Note that the ECDSA algorithm in use here is non-deterministic, 1255 meaning a different signature value will be created every time the 1256 algorithm is run. The signature value provided here can be validated 1257 against the given keys, but newly-generated signature values are not 1258 expected to match the example. See Section 7.19. 1260 The req parameter MUST NOT be used with a request message. 1262 2.4. Creating the Signature Base 1264 The signature base is a US-ASCII string containing the canonicalized 1265 HTTP message components covered by the signature. The input to the 1266 signature base creation algorithm is the list of covered component 1267 identifiers and their associated values, along with any additional 1268 signature parameters. The output is the ordered set of bytes that 1269 form the signature base, which conforms to the following ABNF: 1271 signature-base = *( signature-base-line LF ) signature-params-line 1272 signature-base-line = component-identifier ":" SP 1273 ( derived-component-value / field-value ) 1274 signature-params-line = DQUOTE "@signature-params" DQUOTE ":" SP inner-list 1276 To create the signature base, the signer or verifier concatenates 1277 together entries for each identifier in the signature's covered 1278 components (including their parameters) using the following 1279 algorithm: 1281 1. Let the output be an empty string. 1283 2. For each message component item in the covered components set (in 1284 order): 1286 1. Append the component identifier for the covered component 1287 serialized according to the component-identifier rule. Note 1288 that this serialization places the component name in double 1289 quotes and appends any parameters outside of the quotes. 1291 2. Append a single colon : 1293 3. Append a single space " " 1295 4. Determine the component value for the component identifier. 1297 * If the component name starts with an "at" character (@), 1298 derive the component's value from the message according to 1299 the specific rules defined for the derived component, as 1300 in Section 2.2. If the derived component name is unknown 1301 or the value cannot be derived, produce an error. 1303 * If the component name does not start with an "at" 1304 character (@), canonicalize the HTTP field value as 1305 described in Section 2.1. If the value cannot be 1306 calculated, produce an error. 1308 5. Append the covered component's canonicalized component value. 1310 6. Append a single newline \n 1312 3. Append the signature parameters component (Section 2.2.1) as 1313 follows: 1315 1. Append the component identifier for the signature parameters 1316 serialized according to the component-identifier rule, i.e. 1317 "@signature-params" 1319 2. Append a single colon : 1321 3. Append a single space " " 1323 4. Append the signature parameters' canonicalized component 1324 value as defined in Section 2.2.1 1326 4. Return the output string. 1328 If covered components reference a component identifier that cannot be 1329 resolved to a component value in the message, the implementation MUST 1330 produce an error and not create an input string. Such situations are 1331 included but not limited to: 1333 * The signer or verifier does not understand the derived component 1334 name. 1336 * The component name identifies a field that is not present in the 1337 message or whose value is malformed. 1339 * The component identifier indicates that a structured field 1340 serialization is used (via the sf parameter), but the field in 1341 question is known to not be a structured field or the type of 1342 structured field is not known to the implementation. 1344 * The component identifier is a dictionary member identifier that 1345 references a field that is not present in the message, is not a 1346 Dictionary Structured Field, or whose value is malformed. 1348 * The component identifier is a dictionary member identifier or a 1349 named query parameter identifier that references a member that is 1350 not present in the component value, or whose value is malformed. 1351 E.g., the identifier is "example-dict";key="c" and the value of 1352 the Example-Dict header field is a=1, b=2, which does not have the 1353 c value. 1355 In the following non-normative example, the HTTP message being signed 1356 is the following request: 1358 NOTE: '\' line wrapping per RFC 8792 1360 POST /foo?param=Value&Pet=dog HTTP/1.1 1361 Host: example.com 1362 Date: Tue, 20 Apr 2021 02:07:55 GMT 1363 Content-Type: application/json 1364 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1365 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1366 Content-Length: 18 1368 {"hello": "world"} 1370 The covered components consist of the @method, @authority, and @path 1371 derived components followed by the Content-Digest, Content-Length, 1372 and Content-Type HTTP header fields, in order. The signature 1373 parameters consist of a creation timestamp of 1618884473 and a key 1374 identifier of test-key-rsa-pss. Note that no explicit alg parameter 1375 is given here since the verifier is assumed by the application to 1376 correctly use the RSA PSS algorithm based on the identified key. The 1377 signature base for this message with these parameters is: 1379 NOTE: '\' line wrapping per RFC 8792 1381 "@method": POST 1382 "@authority": example.com 1383 "@path": /foo 1384 "content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\ 1385 +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1386 "content-length": 18 1387 "content-type": application/json 1388 "@signature-params": ("@method" "@authority" "@path" \ 1389 "content-digest" "content-length" "content-type")\ 1390 ;created=1618884473;keyid="test-key-rsa-pss" 1392 Figure 1: Non-normative example Signature Base 1394 Note that the example signature base here, or anywhere else within 1395 this specification, does not include the final newline that ends the 1396 displayed example. 1398 3. HTTP Message Signatures 1400 An HTTP Message Signature is a signature over a string generated from 1401 a subset of the components of an HTTP message in addition to metadata 1402 about the signature itself. When successfully verified against an 1403 HTTP message, an HTTP Message Signature provides cryptographic proof 1404 that the message is semantically equivalent to the message for which 1405 the signature was generated, with respect to the subset of message 1406 components that was signed. 1408 3.1. Creating a Signature 1410 Creation of an HTTP message signature is a process that takes as its 1411 input the message and the requirements for the application. The 1412 output is a signature value and set of signature parameters that can 1413 be applied to the message. 1415 In order to create a signature, a signer MUST follow the following 1416 algorithm: 1418 1. The signer chooses an HTTP signature algorithm and key material 1419 for signing. The signer MUST choose key material that is 1420 appropriate for the signature's algorithm, and that conforms to 1421 any requirements defined by the algorithm, such as key size or 1422 format. The mechanism by which the signer chooses the algorithm 1423 and key material is out of scope for this document. 1425 2. The signer sets the signature's creation time to the current 1426 time. 1428 3. If applicable, the signer sets the signature's expiration time 1429 property to the time at which the signature is to expire. The 1430 expiration is a hint to the verifier, expressing the time at 1431 which the signer is no longer willing to vouch for the safety of 1432 the signature. 1434 4. The signer creates an ordered set of component identifiers 1435 representing the message components to be covered by the 1436 signature, and attaches signature metadata parameters to this 1437 set. The serialized value of this is later used as the value of 1438 the Signature-Input field as described in Section 4.1. 1440 * Once an order of covered components is chosen, the order MUST 1441 NOT change for the life of the signature. 1443 * Each covered component identifier MUST be either an HTTP field 1444 in the message Section 2.1 or a derived component listed in 1445 Section 2.2 or its associated registry. 1447 * Signers of a request SHOULD include some or all of the message 1448 control data in the covered components, such as the @method, 1449 @authority, @target-uri, or some combination thereof. 1451 * Signers SHOULD include the created signature metadata 1452 parameter to indicate when the signature was created. 1454 * The @signature-params derived component identifier is not 1455 explicitly listed in the list of covered component 1456 identifiers, because it is required to always be present as 1457 the last line in the signature base. This ensures that a 1458 signature always covers its own metadata. 1460 * Further guidance on what to include in this set and in what 1461 order is out of scope for this document. 1463 5. The signer creates the signature base using these parameters and 1464 the signature base creation algorithm. (Section 2.4) 1466 6. The signer uses the HTTP_SIGN primitive function to sign the 1467 signature base with the chosen signing algorithm using the key 1468 material chosen by the signer. The HTTP_SIGN primitive and 1469 several concrete applications of signing algorithms are defined 1470 in in Section 3.3. 1472 7. The byte array output of the signature function is the HTTP 1473 message signature output value to be included in the Signature 1474 field as defined in Section 4.2. 1476 For example, given the HTTP message and signature parameters in the 1477 example in Section 2.4, the example signature base is signed with the 1478 test-key-rsa-pss key in Appendix B.1.2 and the RSA PSS algorithm 1479 described in Section 3.3.1, giving the following message signature 1480 output value, encoded in Base64: 1482 NOTE: '\' line wrapping per RFC 8792 1484 HIbjHC5rS0BYaa9v4QfD4193TORw7u9edguPh0AW3dMq9WImrlFrCGUDih47vAxi4L2\ 1485 YRZ3XMJc1uOKk/J0ZmZ+wcta4nKIgBkKq0rM9hs3CQyxXGxHLMCy8uqK488o+9jrptQ\ 1486 +xFPHK7a9sRL1IXNaagCNN3ZxJsYapFj+JXbmaI5rtAdSfSvzPuBCh+ARHBmWuNo1Uz\ 1487 VVdHXrl8ePL4cccqlazIJdC4QEjrF+Sn4IxBQzTZsL9y9TP5FsZYzHvDqbInkTNigBc\ 1488 E9cKOYNFCn4D/WM7F6TNuZO9EgtzepLWcjTymlHzK7aXq6Am6sfOrpIC49yXjj3ae6H\ 1489 RalVc/g== 1491 Figure 2: Non-normative example signature value 1493 Note that the RSA PSS algorithm in use here is non-deterministic, 1494 meaning a different signature value will be created every time the 1495 algorithm is run. The signature value provided here can be validated 1496 against the given keys, but newly-generated signature values are not 1497 expected to match the example. See Section 7.19. 1499 3.2. Verifying a Signature 1501 Verification of an HTTP message signature is a process that takes as 1502 its input the message (including Signature and Signature-Input 1503 fields) and the requirements for the application. The output of the 1504 verification is either a positive verification or an error. 1506 In order to verify a signature, a verifier MUST follow the following 1507 algorithm: 1509 1. Parse the Signature and Signature-Input fields as described in 1510 Section 4.1 and Section 4.2, and extract the signatures to be 1511 verified. 1513 1. If there is more than one signature value present, determine 1514 which signature should be processed for this message based on 1515 the policy and configuration of the verifier. If an 1516 applicable signature is not found, produce an error. 1518 2. If the chosen Signature value does not have a corresponding 1519 Signature-Input value, produce an error. 1521 2. Parse the values of the chosen Signature-Input field as a 1522 parameterized Inner List to get the ordered list of covered 1523 components and the signature parameters for the signature to be 1524 verified. 1526 3. Parse the value of the corresponding Signature field to get the 1527 byte array value of the signature to be verified. 1529 4. Examine the signature parameters to confirm that the signature 1530 meets the requirements described in this document, as well as any 1531 additional requirements defined by the application such as which 1532 message components are required to be covered by the signature. 1533 (Section 3.2.1) 1535 5. Determine the verification key material for this signature. If 1536 the key material is known through external means such as static 1537 configuration or external protocol negotiation, the verifier will 1538 use that. If the key is identified in the signature parameters, 1539 the verifier will dereference this to appropriate key material to 1540 use with the signature. The verifier has to determine the 1541 trustworthiness of the key material for the context in which the 1542 signature is presented. If a key is identified that the verifier 1543 does not know, does not trust for this request, or does not match 1544 something preconfigured, the verification MUST fail. 1546 6. Determine the algorithm to apply for verification: 1548 1. If the algorithm is known through external means such as 1549 static configuration or external protocol negotiation, the 1550 verifier will use this algorithm. 1552 2. If the algorithm is explicitly stated in the signature 1553 parameters using a value from the HTTP Message Signatures 1554 registry, the verifier will use the referenced algorithm. 1556 3. If the algorithm can be determined from the keying material, 1557 such as through an algorithm field on the key value itself, 1558 the verifier will use this algorithm. 1560 4. If the algorithm is specified in more than one location, such 1561 as through static configuration and the algorithm signature 1562 parameter, or the algorithm signature parameter and from the 1563 key material itself, the resolved algorithms MUST be the 1564 same. If the algorithms are not the same, the verifier MUST 1565 fail the verification. 1567 7. Use the received HTTP message and the signature's metadata to 1568 recreate the signature base, using the algorithm defined in 1569 Section 2.4. The value of the @signature-params input is the 1570 value of the Signature-Input field for this signature serialized 1571 according to the rules described in Section 2.2.1, not including 1572 the signature's label from the Signature-Input field. 1574 8. If the key material is appropriate for the algorithm, apply the 1575 appropriate HTTP_VERIFY cryptographic verification algorithm to 1576 the signature, recalculated signature base, key material, 1577 signature value. The HTTP_VERIFY primitive and several concrete 1578 algorithms are defined in Section 3.3. 1580 9. The results of the verification algorithm function are the final 1581 results of the cryptographic verification function. 1583 If any of the above steps fail or produce an error, the signature 1584 validation fails. 1586 For example, verifying the signature with the key sig1 of the 1587 following message with the test-key-rsa-pss key in Appendix B.1.2 and 1588 the RSA PSS algorithm described in Section 3.3.1: 1590 NOTE: '\' line wrapping per RFC 8792 1592 POST /foo?param=Value&Pet=dog HTTP/1.1 1593 Host: example.com 1594 Date: Tue, 20 Apr 2021 02:07:55 GMT 1595 Content-Type: application/json 1596 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1597 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1598 Content-Length: 18 1599 Signature-Input: sig1=("@method" "@authority" "@path" \ 1600 "content-digest" "content-length" "content-type")\ 1601 ;created=1618884473;keyid="test-key-rsa-pss" 1602 Signature: sig1=:HIbjHC5rS0BYaa9v4QfD4193TORw7u9edguPh0AW3dMq9WImrl\ 1603 FrCGUDih47vAxi4L2YRZ3XMJc1uOKk/J0ZmZ+wcta4nKIgBkKq0rM9hs3CQyxXGxH\ 1604 LMCy8uqK488o+9jrptQ+xFPHK7a9sRL1IXNaagCNN3ZxJsYapFj+JXbmaI5rtAdSf\ 1605 SvzPuBCh+ARHBmWuNo1UzVVdHXrl8ePL4cccqlazIJdC4QEjrF+Sn4IxBQzTZsL9y\ 1606 9TP5FsZYzHvDqbInkTNigBcE9cKOYNFCn4D/WM7F6TNuZO9EgtzepLWcjTymlHzK7\ 1607 aXq6Am6sfOrpIC49yXjj3ae6HRalVc/g==: 1609 {"hello": "world"} 1611 With the additional requirements that at least the method, authority, 1612 path, content-digest, content-length, and content-type be signed, and 1613 that the signature creation timestamp is recent enough at the time of 1614 verification, the verification passes. 1616 3.2.1. Enforcing Application Requirements 1618 The verification requirements specified in this document are intended 1619 as a baseline set of restrictions that are generally applicable to 1620 all use cases. Applications using HTTP Message Signatures MAY impose 1621 requirements above and beyond those specified by this document, as 1622 appropriate for their use case. 1624 Some non-normative examples of additional requirements an application 1625 might define are: 1627 * Requiring a specific set of header fields to be signed (e.g., 1628 Authorization, Digest). 1630 * Enforcing a maximum signature age from the time of the created 1631 time stamp. 1633 * Rejection of signatures past the expiration time in the expires 1634 time stamp. Note that the expiration time is a hint from the 1635 signer and that a verifier can always reject a signature ahead of 1636 its expiration time. 1638 * Prohibition of certain signature metadata parameters, such as 1639 runtime algorithm signaling with the alg parameter when the 1640 algorithm is determined from the key information. 1642 * Ensuring successful dereferencing of the keyid parameter to valid 1643 and appropriate key material. 1645 * Prohibiting the use of certain algorithms, or mandating the use of 1646 a specific algorithm. 1648 * Requiring keys to be of a certain size (e.g., 2048 bits vs. 1024 1649 bits). 1651 * Enforcing uniqueness of a nonce value. 1653 Application-specific requirements are expected and encouraged. When 1654 an application defines additional requirements, it MUST enforce them 1655 during the signature verification process, and signature verification 1656 MUST fail if the signature does not conform to the application's 1657 requirements. 1659 Applications MUST enforce the requirements defined in this document. 1660 Regardless of use case, applications MUST NOT accept signatures that 1661 do not conform to these requirements. 1663 3.3. Signature Algorithm Methods 1665 HTTP Message signatures MAY use any cryptographic digital signature 1666 or MAC method that is appropriate for the key material, environment, 1667 and needs of the signer and verifier. 1669 Each signature algorithm method takes as its input the signature base 1670 defined in Section 2.4 as a byte array (M), the signing key material 1671 (Ks), and outputs the signature output as a byte array (S): 1673 HTTP_SIGN (M, Ks) -> S 1675 Each verification algorithm method takes as its input the 1676 recalculated signature base defined in Section 2.4 as a byte array 1677 (M), the verification key material (Kv), and the presented signature 1678 to be verified as a byte array (S) and outputs the verification 1679 result (V) as a boolean: 1681 HTTP_VERIFY (M, Kv, S) -> V 1682 This section contains several common algorithm methods. The method 1683 to use can be communicated through the explicit algorithm signature 1684 parameter alg defined in Section 2.2.1, by reference to the key 1685 material, or through mutual agreement between the signer and 1686 verifier. 1688 3.3.1. RSASSA-PSS using SHA-512 1690 To sign using this algorithm, the signer applies the RSASSA-PSS-SIGN 1691 (K, M) function [RFC8017] with the signer's private signing key (K) 1692 and the signature base (M) (Section 2.4). The mask generation 1693 function is MGF1 as specified in [RFC8017] with a hash function of 1694 SHA-512 [RFC6234]. The salt length (sLen) is 64 bytes. The hash 1695 function (Hash) SHA-512 [RFC6234] is applied to the signature base to 1696 create the digest content to which the digital signature is applied. 1697 The resulting signed content byte array (S) is the HTTP message 1698 signature output used in Section 3.1. 1700 To verify using this algorithm, the verifier applies the RSASSA-PSS- 1701 VERIFY ((n, e), M, S) function [RFC8017] using the public key portion 1702 of the verification key material ((n, e)) and the signature base (M) 1703 re-created as described in Section 3.2. The mask generation function 1704 is MGF1 as specified in [RFC8017] with a hash function of SHA-512 1705 [RFC6234]. The salt length (sLen) is 64 bytes. The hash function 1706 (Hash) SHA-512 [RFC6234] is applied to the signature base to create 1707 the digest content to which the verification function is applied. 1708 The verifier extracts the HTTP message signature to be verified (S) 1709 as described in Section 3.2. The results of the verification 1710 function indicate if the signature presented is valid. 1712 Note that the output of RSA PSS algorithms are non-deterministic, and 1713 therefore it is not correct to re-calculate a new signature on the 1714 signature base and compare the results to an existing signature. 1715 Instead, the verification algorithm defined here needs to be used. 1716 See Section 7.19. 1718 Use of this algorithm can be indicated at runtime using the rsa-pss- 1719 sha512 value for the alg signature parameter. 1721 3.3.2. RSASSA-PKCS1-v1_5 using SHA-256 1723 To sign using this algorithm, the signer applies the RSASSA- 1724 PKCS1-V1_5-SIGN (K, M) function [RFC8017] with the signer's private 1725 signing key (K) and the signature base (M) (Section 2.4). The hash 1726 SHA-256 [RFC6234] is applied to the signature base to create the 1727 digest content to which the digital signature is applied. The 1728 resulting signed content byte array (S) is the HTTP message signature 1729 output used in Section 3.1. 1731 To verify using this algorithm, the verifier applies the RSASSA- 1732 PKCS1-V1_5-VERIFY ((n, e), M, S) function [RFC8017] using the public 1733 key portion of the verification key material ((n, e)) and the 1734 signature base (M) re-created as described in Section 3.2. The hash 1735 function SHA-256 [RFC6234] is applied to the signature base to create 1736 the digest content to which the verification function is applied. 1737 The verifier extracts the HTTP message signature to be verified (S) 1738 as described in Section 3.2. The results of the verification 1739 function are compared to the http message signature to determine if 1740 the signature presented is valid. 1742 Use of this algorithm can be indicated at runtime using the rsa- 1743 v1_5-sha256 value for the alg signature parameter. 1745 3.3.3. HMAC using SHA-256 1747 To sign and verify using this algorithm, the signer applies the HMAC 1748 function [RFC2104] with the shared signing key (K) and the signature 1749 base (text) (Section 2.4). The hash function SHA-256 [RFC6234] is 1750 applied to the signature base to create the digest content to which 1751 the HMAC is applied, giving the signature result. 1753 For signing, the resulting value is the HTTP message signature output 1754 used in Section 3.1. 1756 For verification, the verifier extracts the HTTP message signature to 1757 be verified (S) as described in Section 3.2. The output of the HMAC 1758 function is compared to the value of the HTTP message signature, and 1759 the results of the comparison determine the validity of the signature 1760 presented. 1762 Use of this algorithm can be indicated at runtime using the hmac- 1763 sha256 value for the alg signature parameter. 1765 3.3.4. ECDSA using curve P-256 DSS and SHA-256 1767 To sign using this algorithm, the signer applies the ECDSA algorithm 1768 [FIPS186-4] using curve P-256 with the signer's private signing key 1769 and the signature base (Section 2.4). The hash SHA-256 [RFC6234] is 1770 applied to the signature base to create the digest content to which 1771 the digital signature is applied, (M). The signature algorithm 1772 returns two integer values, r and s. These are both encoded in big- 1773 endian unsigned integers, zero-padded to 32-octets each. These 1774 encoded values are concatenated into a single 64-octet array 1775 consisting of the encoded value of r followed by the encoded value of 1776 s. The resulting concatenation of (r, s) is byte array of the HTTP 1777 message signature output used in Section 3.1. 1779 To verify using this algorithm, the verifier applies the ECDSA 1780 algorithm [FIPS186-4] using the public key portion of the 1781 verification key material and the signature base re-created as 1782 described in Section 3.2. The hash function SHA-256 [RFC6234] is 1783 applied to the signature base to create the digest content to which 1784 the signature verification function is applied, (M). The verifier 1785 extracts the HTTP message signature to be verified (S) as described 1786 in Section 3.2. This value is a 64-octet array consisting of the 1787 encoded values of r and s concatenated in order. These are both 1788 encoded in big-endian unsigned integers, zero-padded to 32-octets 1789 each. The resulting signature value (r, s) is used as input to the 1790 signature verification function. The results of the verification 1791 function indicate if the signature presented is valid. 1793 Note that the output of ECDSA algorithms are non-deterministic, and 1794 therefore it is not correct to re-calculate a new signature on the 1795 signature base and compare the results to an existing signature. 1796 Instead, the verification algorithm defined here needs to be used. 1797 See Section 7.19. 1799 Use of this algorithm can be indicated at runtime using the ecdsa- 1800 p256-sha256 value for the alg signature parameter. 1802 3.3.5. EdDSA using curve edwards25519 1804 To sign using this algorithm, the signer applies the Ed25519 1805 algorithm Section 5.1.6 of [RFC8032] with the signer's private 1806 signing key and the signature base (Section 2.4). The signature base 1807 is taken as the input message (M) with no pre-hash function. The 1808 signature is a 64-octet concatenation of R and S as specified in 1809 Section 5.1.6 of [RFC8032], and this is taken as a byte array for the 1810 HTTP message signature output used in Section 3.1. 1812 To verify using this algorithm, the signer applies the Ed25519 1813 algorithm Section 5.1.7 of [RFC8032] using the public key portion of 1814 the verification key material (A) and the signature base re-created 1815 as described in Section 3.2. The signature base is taken as the 1816 input message (M) with no pre-hash function. The signature to be 1817 verified is processed as the 64-octet concatenation of R and S as 1818 specified in Section 5.1.7 of [RFC8032]. The results of the 1819 verification function indicate if the signature presented is valid. 1821 Use of this algorithm can be indicated at runtime using the ed25519 1822 value for the alg signature parameter. 1824 3.3.6. JSON Web Signature (JWS) algorithms 1826 If the signing algorithm is a JOSE signing algorithm from the JSON 1827 Web Signature and Encryption Algorithms Registry established by 1828 [RFC7518], the JWS algorithm definition determines the signature and 1829 hashing algorithms to apply for both signing and verification. 1831 For both signing and verification, the HTTP messages signature base 1832 (Section 2.4) is used as the entire "JWS Signing Input". The JOSE 1833 Header defined in [RFC7517] is not used, and the signature base is 1834 not first encoded in Base64 before applying the algorithm. The 1835 output of the JWS signature is taken as a byte array prior to the 1836 Base64url encoding used in JOSE. 1838 The JWS algorithm MUST NOT be none and MUST NOT be any algorithm with 1839 a JOSE Implementation Requirement of Prohibited. 1841 JWA algorithm values from the JSON Web Signature and Encryption 1842 Algorithms Registry are not included as signature parameters. In 1843 fact, the explicit alg signature parameter is not used at all when 1844 using JOSE signing algorithms, as the JWS algorithm can be signaled 1845 using JSON Web Keys or other mechanisms common to JOSE 1846 implementations. 1848 4. Including a Message Signature in a Message 1850 Message signatures can be included within an HTTP message via the 1851 Signature-Input and Signature fields, both defined within this 1852 specification. When attached to a message, an HTTP message signature 1853 is identified by a label. This label MUST be unique within a given 1854 HTTP message and MUST be used in both the Signature-Input and 1855 Signature fields. The label is chosen by the signer, except where a 1856 specific label is dictated by protocol negotiations such as described 1857 in Section 5 1859 An HTTP message signature MUST use both fields and each field MUST 1860 contain the same labels. The Signature-Input and Signature 1861 Dictionaries are parallel data structures of each other, and the 1862 presence of any key in one field but not in the other is an error. 1863 The Signature-Input field identifies the covered components and 1864 parameters that describe how the signature was generated, while the 1865 Signature field contains the signature value. Each field MAY contain 1866 multiple labeled values. 1868 4.1. The Signature-Input HTTP Field 1870 The Signature-Input field is a Dictionary structured field defined in 1871 Section 3.2 of [STRUCTURED-FIELDS] containing the metadata for one or 1872 more message signatures generated from components within the HTTP 1873 message. Each member describes a single message signature. The 1874 member's key is an identifier that uniquely identifies the message 1875 signature within the context of the HTTP message. The member's value 1876 is the serialization of the covered components including all 1877 signature metadata parameters, using the Inner List serialization 1878 process defined in Section 2.2.1. 1880 NOTE: '\' line wrapping per RFC 8792 1882 Signature-Input: sig1=("@method" "@target-uri" "@authority" \ 1883 "content-digest" "cache-control");\ 1884 created=1618884475;keyid="test-key-rsa-pss" 1886 To facilitate signature validation, the Signature-Input field value 1887 MUST contain the same serialized value used in generating the 1888 signature base's @signature-params value. Note that in a structured 1889 field value, parameter order has to be preserved. 1891 The signer MAY include the Signature-Input field as a trailer to 1892 facilitate signing a message after its content has been processed by 1893 the signer. However, since intermediaries are allowed to drop 1894 trailers as per [HTTP], it is RECOMMENDED that the Signature-Input 1895 field be included only as a header to avoid signatures being 1896 inadvertently stripped from a message. 1898 Multiple Signature-Input fields MAY be included in a single HTTP 1899 message. The signature labels MUST be unique across all field 1900 values. 1902 4.2. The Signature HTTP Field 1904 The Signature field is a Dictionary structured field defined in 1905 Section 3.2 of [STRUCTURED-FIELDS] containing one or more message 1906 signatures generated from components and context of the HTTP message. 1907 The member's key is an identifier that uniquely identifies the 1908 message signature within the context of the HTTP message. The 1909 member's value is a Byte Sequence containing the signature value for 1910 the message signature identified by the member name. 1912 NOTE: '\' line wrapping per RFC 8792 1914 Signature: sig1=:P0wLUszWQjoi54udOtydf9IWTfNhy+r53jGFj9XZuP4uKwxyJo\ 1915 1RSHi+oEF1FuX6O29d+lbxwwBao1BAgadijW+7O/PyezlTnqAOVPWx9GlyntiCiHz\ 1916 C87qmSQjvu1CFyFuWSjdGa3qLYYlNm7pVaJFalQiKWnUaqfT4LyttaXyoyZW84jS8\ 1917 gyarxAiWI97mPXU+OVM64+HVBHmnEsS+lTeIsEQo36T3NFf2CujWARPQg53r58Rmp\ 1918 Z+J9eKR2CD6IJQvacn5A4Ix5BUAVGqlyp8JYm+S/CWJi31PNUjRRCusCVRj05NrxA\ 1919 BNFv3r5S9IXf2fYJK+eyW4AiGVMvMcOg==: 1921 The signer MAY include the Signature field as a trailer to facilitate 1922 signing a message after its content has been processed by the signer. 1923 However, since intermediaries are allowed to drop trailers as per 1924 [HTTP], it is RECOMMENDED that the Signature field be included only 1925 as a header to avoid signatures being inadvertently stripped from a 1926 message. 1928 Multiple Signature fields MAY be included in a single HTTP message. 1929 The signature labels MUST be unique across all field values. 1931 4.3. Multiple Signatures 1933 Multiple distinct signatures MAY be included in a single message. 1934 Each distinct signature MUST have a unique label. These multiple 1935 signatures could be added all by the same signer or could come from 1936 several different signers. For example, a signer may include 1937 multiple signatures signing the same message components with 1938 different keys or algorithms to support verifiers with different 1939 capabilities, or a reverse proxy may include information about the 1940 client in fields when forwarding the request to a service host, 1941 including a signature over the client's original signature values. 1943 The following non-normative example starts with a signed request from 1944 the client. The proxy takes this request validates the client's 1945 signature. 1947 NOTE: '\' line wrapping per RFC 8792 1949 POST /foo?param=Value&Pet=dog HTTP/1.1 1950 Host: example.com 1951 Date: Tue, 20 Apr 2021 02:07:55 GMT 1952 Content-Type: application/json 1953 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1954 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1955 Content-Length: 18 1956 Signature-Input: sig1=("@method" "@authority" "@path" \ 1957 "content-digest" "content-length" "content-type")\ 1958 ;created=1618884475;keyid="test-key-rsa-pss" 1959 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1960 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8Br\ 1961 c8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINTEzpx\ 1962 jqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr65+BXe\ 1963 TG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZElYyUKaAI\ 1964 jZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1966 {"hello": "world"} 1968 The proxy then alters the message before forwarding it on to the 1969 origin server, changing the target host and adding the Forwarded 1970 header field defined in [RFC7239]. 1972 NOTE: '\' line wrapping per RFC 8792 1974 POST /foo?param=Value&Pet=dog HTTP/1.1 1975 Host: origin.host.internal.example 1976 Date: Tue, 20 Apr 2021 02:07:56 GMT 1977 Content-Type: application/json 1978 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 1979 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 1980 Content-Length: 18 1981 Forwarded: for=192.0.2.123 1982 Signature-Input: sig1=("@method" "@authority" "@path" \ 1983 "content-digest" "content-length" "content-type")\ 1984 ;created=1618884475;keyid="test-key-rsa-pss" 1985 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 1986 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8Br\ 1987 c8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINTEzpx\ 1988 jqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr65+BXe\ 1989 TG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZElYyUKaAI\ 1990 jZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 1992 {"hello": "world"} 1993 The proxy includes the client's signature value under the label sig1, 1994 which the proxy signs in addition to the Forwarded field. Note that 1995 since the client's signature already covers the client's Signature- 1996 Input value for sig1, this value is transitively covered by the 1997 proxy's signature and need not be added explicitly. The proxy 1998 identifies its own key and algorithm and, in this example, includes 1999 an expiration for the signature to indicate to downstream systems 2000 that the proxy will not vouch for this signed message past this short 2001 time window. This results in a signature base of: 2003 NOTE: '\' line wrapping per RFC 8792 2005 "signature";key="sig1": :LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8\ 2006 r5MW9S0RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkB\ 2007 IS1M8Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpW\ 2008 INTEzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2T\ 2009 r65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZEl\ 2010 YyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==: 2011 "forwarded": for=192.0.2.123 2012 "@signature-params": ("signature";key="sig1" "forwarded")\ 2013 ;created=1618884480;expires=1618884540;keyid="test-key-rsa"\ 2014 ;alg="rsa-v1_5-sha256" 2016 And a signature output value of: 2018 NOTE: '\' line wrapping per RFC 8792 2020 G1WLTL4/9PGSKEQbSAMypZNk+I2dpLJ6qvl2JISahlP31OO/QEUd8/HdO2O7vYLi5k3\ 2021 JIiAK3UPK4U+kvJZyIUidsiXlzRI+Y2se3SGo0D8dLfhG95bKr6ukYXl60QHpsGRTfS\ 2022 iwdtvYKXGpKNrMlISJYd+oGrGRyI9gbCy0aFhc6I/okIMLeK4g9PgzpC3YTwhUQ98KI\ 2023 BNLWHgREfBgJxjPbxFlsgJ9ykPviLj8GKJ81HwsK3XM9P7WaS7fMGOt8h1kSqgkZQB9\ 2024 YqiIo+WhHvJa7iPy8QrYFKzx9BBEY6AwfStZAsXXz3LobZseyxsYcLJLs8rY0wVA9NP\ 2025 sxKrHGA== 2027 These values are added to the HTTP request message by the proxy. The 2028 original signature is included under the identifier sig1, and the 2029 reverse proxy's signature is included under the label proxy_sig. The 2030 proxy uses the key test-key-rsa to create its signature using the 2031 rsa-v1_5-sha256 signature algorithm, while the client's original 2032 signature was made using the key id of test-key-rsa-pss and an RSA 2033 PSS signature algorithm. 2035 NOTE: '\' line wrapping per RFC 8792 2037 POST /foo?param=Value&Pet=dog HTTP/1.1 2038 Host: origin.host.internal.example 2039 Date: Tue, 20 Apr 2021 02:07:56 GMT 2040 Content-Type: application/json 2041 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 2042 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 2043 Content-Length: 18 2044 Forwarded: for=192.0.2.123 2045 Signature-Input: sig1=("@method" "@authority" "@path" \ 2046 "content-digest" "content-length" "content-type")\ 2047 ;created=1618884475;keyid="test-key-rsa-pss", \ 2048 proxy_sig=("signature";key="sig1" "forwarded")\ 2049 ;created=1618884480;expires=1618884540;keyid="test-key-rsa"\ 2050 ;alg="rsa-v1_5-sha256" 2051 Signature: sig1=:LAH8BjcfcOcLojiuOBFWn0P5keD3xAOuJRGziCLuD8r5MW9S0\ 2052 RoXXLzLSRfGY/3SF8kVIkHjE13SEFdTo4Af/fJ/Pu9wheqoLVdwXyY/UkBIS1M8\ 2053 Brc8IODsn5DFIrG0IrburbLi0uCc+E2ZIIb6HbUJ+o+jP58JelMTe0QE3IpWINT\ 2054 EzpxjqDf5/Df+InHCAkQCTuKsamjWXUpyOT1Wkxi7YPVNOjW4MfNuTZ9HdbD2Tr\ 2055 65+BXeTG9ZS/9SWuXAc+BZ8WyPz0QRz//ec3uWXd7bYYODSjRAxHqX+S1ag3LZE\ 2056 lYyUKaAIjZ8MGOt4gXEwCSLDv/zqxZeWLj/PDkn6w==:, \ 2057 proxy_sig=:G1WLTL4/9PGSKEQbSAMypZNk+I2dpLJ6qvl2JISahlP31OO/QEUd8/\ 2058 HdO2O7vYLi5k3JIiAK3UPK4U+kvJZyIUidsiXlzRI+Y2se3SGo0D8dLfhG95bKr\ 2059 6ukYXl60QHpsGRTfSiwdtvYKXGpKNrMlISJYd+oGrGRyI9gbCy0aFhc6I/okIML\ 2060 eK4g9PgzpC3YTwhUQ98KIBNLWHgREfBgJxjPbxFlsgJ9ykPviLj8GKJ81HwsK3X\ 2061 M9P7WaS7fMGOt8h1kSqgkZQB9YqiIo+WhHvJa7iPy8QrYFKzx9BBEY6AwfStZAs\ 2062 XXz3LobZseyxsYcLJLs8rY0wVA9NPsxKrHGA==: 2064 {"hello": "world"} 2066 The proxy's signature and the client's original signature can be 2067 verified independently for the same message, based on the needs of 2068 the application. Since the proxy's signature covers the client 2069 signature, the backend service fronted by the proxy can trust that 2070 the proxy has validated the incoming signature. 2072 5. Requesting Signatures 2074 While a signer is free to attach a signature to a request or response 2075 without prompting, it is often desirable for a potential verifier to 2076 signal that it expects a signature from a potential signer using the 2077 Accept-Signature field. 2079 The message to which the requested signature is applied is known as 2080 the "target message". When the Accept-Signature field is sent in an 2081 HTTP request message, the field indicates that the client desires the 2082 server to sign the response using the identified parameters, and the 2083 target message is the response to this request. All responses from 2084 resources that support such signature negotiation SHOULD either be 2085 uncacheable or contain a Vary header field that lists Accept- 2086 Signature, in order to prevent a cache from returning a response with 2087 a signature intended for a different request. 2089 When the Accept-Signature field is used in an HTTP response message, 2090 the field indicates that the server desires the client to sign its 2091 next request to the server with the identified parameters, and the 2092 target message is the client's next request. The client can choose 2093 to also continue signing future requests to the same server in the 2094 same way. 2096 The target message of an Accept-Signature field MUST include all 2097 labeled signatures indicated in the Accept-Header signature, each 2098 covering the same identified components of the Accept-Signature 2099 field. 2101 The sender of an Accept-Signature field MUST include identifiers that 2102 are appropriate for the type of the target message. For example, if 2103 the target message is a request, the component identifiers can not 2104 include the @status component identifier. 2106 5.1. The Accept-Signature Field 2108 The Accept-Signature field is a Dictionary structured field defined 2109 in Section 3.2 of [STRUCTURED-FIELDS] containing the metadata for one 2110 or more requested message signatures to be generated from message 2111 components of the target HTTP message. Each member describes a 2112 single message signature. The member's name is an identifier that 2113 uniquely identifies the requested message signature within the 2114 context of the target HTTP message. The member's value is the 2115 serialization of the desired covered components of the target 2116 message, including any allowed signature metadata parameters, using 2117 the serialization process defined in Section 2.2.1. 2119 NOTE: '\' line wrapping per RFC 8792 2121 Accept-Signature: sig1=("@method" "@target-uri" "@authority" \ 2122 "content-digest" "cache-control");\ 2123 keyid="test-key-rsa-pss" 2125 The requested signature MAY include parameters, such as a desired 2126 algorithm or key identifier. These parameters MUST NOT include 2127 parameters that the signer is expected to generate, including the 2128 created and nonce parameters. 2130 5.2. Processing an Accept-Signature 2132 The receiver of an Accept-Signature field fulfills that header as 2133 follows: 2135 1. Parse the field value as a Dictionary 2137 2. For each member of the dictionary: 2139 1. The name of the member is the label of the output signature 2140 as specified in Section 4.1 2142 2. Parse the value of the member to obtain the set of covered 2143 component identifiers 2145 3. Process the requested parameters, such as the signing 2146 algorithm and key material. If any requested parameters 2147 cannot be fulfilled, or if the requested parameters conflict 2148 with those deemed appropriate to the target message, the 2149 process fails and returns an error. 2151 4. Select any additional parameters necessary for completing the 2152 signature 2154 5. Create the Signature-Input and Signature header values and 2155 associate them with the label 2157 3. Optionally create any additional Signature-Input and Signature 2158 values, with unique labels not found in the Accept-Signature 2159 field 2161 4. Combine all labeled Signature-Input and Signature values and 2162 attach both fields to the target message 2164 Note that by this process, a signature applied to a target message 2165 MUST have the same label, MUST have the same set of covered 2166 component, and MAY have additional parameters. Also note that the 2167 target message MAY include additional signatures not specified by the 2168 Accept-Signature field. 2170 6. IANA Considerations 2172 IANA is requested to create three registries and to populate those 2173 registries with initial values as described in this section. 2175 6.1. HTTP Signature Algorithms Registry 2177 This document defines HTTP Signature Algorithms, for which IANA is 2178 asked to create and maintain a new registry titled "HTTP Signature 2179 Algorithms". Initial values for this registry are given in 2180 Section 6.1.2. Future assignments and modifications to existing 2181 assignment are to be made through the Expert Review registration 2182 policy [RFC8126] and shall follow the template presented in 2183 Section 6.1.1. 2185 Algorithms referenced by algorithm identifiers have to be fully 2186 defined with all parameters fixed. Algorithm identifiers in this 2187 registry are to be interpreted as whole string values and not as a 2188 combination of parts. That is to say, it is expected that 2189 implementors understand rsa-pss-sha512 as referring to one specific 2190 algorithm with its hash, mask, and salt values set as defined here. 2191 Implementors do not parse out the rsa, pss, and sha512 portions of 2192 the identifier to determine parameters of the signing algorithm from 2193 the string. 2195 Algorithms added to this registry MUST NOT be aliases for other 2196 entries in the registry. 2198 6.1.1. Registration Template 2200 Algorithm Name: 2201 An identifier for the HTTP Signature Algorithm. The name MUST be 2202 an ASCII string consisting only of lower-case characters ("a" - 2203 "z"), digits ("0" - "9"), and hyphens ("-"), and SHOULD NOT exceed 2204 20 characters in length. The identifier MUST be unique within the 2205 context of the registry. 2207 Description: 2208 A brief description of the algorithm used to sign the signature 2209 base. 2211 Status: 2212 A brief text description of the status of the algorithm. The 2213 description MUST begin with one of "Active" or "Deprecated", and 2214 MAY provide further context or explanation as to the reason for 2215 the status. 2217 Specification document(s): 2218 Reference to the document(s) that specify the algorithm, 2219 preferably including a URI that can be used to retrieve a copy of 2220 the document(s). An indication of the relevant sections may also 2221 be included but is not required. 2223 6.1.2. Initial Contents 2225 +===================+===================+========+===============+ 2226 | Algorithm Name | Description | Status | Specification | 2227 | | | | document(s) | 2228 +===================+===================+========+===============+ 2229 | rsa-pss-sha512 | RSASSA-PSS using | Active | Section 3.3.1 | 2230 | | SHA-512 | | of RFC nnnn | 2231 +-------------------+-------------------+--------+---------------+ 2232 | rsa-v1_5-sha256 | RSASSA-PKCS1-v1_5 | Active | Section 3.3.2 | 2233 | | using SHA-256 | | of RFC nnnn | 2234 +-------------------+-------------------+--------+---------------+ 2235 | hmac-sha256 | HMAC using | Active | Section 3.3.3 | 2236 | | SHA-256 | | of RFC nnnn | 2237 +-------------------+-------------------+--------+---------------+ 2238 | ecdsa-p256-sha256 | ECDSA using curve | Active | Section 3.3.4 | 2239 | | P-256 DSS and | | of RFC nnnn | 2240 | | SHA-256 | | | 2241 +-------------------+-------------------+--------+---------------+ 2242 | ed25519 | Edwards Curve DSA | Active | Section 3.3.5 | 2243 | | using curve | | of RFC nnnn | 2244 | | edwards25519 | | | 2245 +-------------------+-------------------+--------+---------------+ 2247 Table 1: Initial contents of the HTTP Signature Algorithms 2248 Registry. 2250 6.2. HTTP Signature Metadata Parameters Registry 2252 This document defines the signature parameters structure, the values 2253 of which may have parameters containing metadata about a message 2254 signature. IANA is asked to create and maintain a new registry 2255 titled "HTTP Signature Metadata Parameters" to record and maintain 2256 the set of parameters defined for use with member values in the 2257 signature parameters structure. Initial values for this registry are 2258 given in Section 6.2.2. Future assignments and modifications to 2259 existing assignments are to be made through the Expert Review 2260 registration policy [RFC8126] and shall follow the template presented 2261 in Section 6.2.1. 2263 6.2.1. Registration Template 2265 Name: 2266 An identifier for the HTTP signature metadata parameter. The name 2267 MUST be an ASCII string consisting only of lower-case characters 2268 ("a" - "z"), digits ("0" - "9"), and hyphens ("-"), and SHOULD NOT 2269 exceed 20 characters in length. The identifier MUST be unique 2270 within the context of the registry. 2272 Description: 2273 A brief description of the metadata parameter and what it 2274 represents. 2276 Specification document(s): 2277 Reference to the document(s) that specify the parameter, 2278 preferably including a URI that can be used to retrieve a copy of 2279 the document(s). An indication of the relevant sections may also 2280 be included but is not required. 2282 6.2.2. Initial Contents 2284 The table below contains the initial contents of the HTTP Signature 2285 Metadata Parameters Registry. Each row in the table represents a 2286 distinct entry in the registry. 2288 +=========+===============================+===============+ 2289 | Name | Description | Specification | 2290 | | | document(s) | 2291 +=========+===============================+===============+ 2292 | alg | Explicitly declared signature | Section 2.2.1 | 2293 | | algorithm | of RFC nnnn | 2294 +---------+-------------------------------+---------------+ 2295 | created | Timestamp of signature | Section 2.2.1 | 2296 | | creation | of RFC nnnn | 2297 +---------+-------------------------------+---------------+ 2298 | expires | Timestamp of proposed | Section 2.2.1 | 2299 | | signature expiration | of RFC nnnn | 2300 +---------+-------------------------------+---------------+ 2301 | keyid | Key identifier for the | Section 2.2.1 | 2302 | | signing and verification keys | of RFC nnnn | 2303 | | used to create this signature | | 2304 +---------+-------------------------------+---------------+ 2305 | nonce | A single-use nonce value | Section 2.2.1 | 2306 | | | of RFC nnnn | 2307 +---------+-------------------------------+---------------+ 2309 Table 2: Initial contents of the HTTP Signature 2310 Metadata Parameters Registry. 2312 6.3. HTTP Signature Derived Component Names Registry 2314 This document defines a method for canonicalizing HTTP message 2315 components, including components that can be derived from the context 2316 of the HTTP message outside of the HTTP fields. These derived 2317 components are identified by a unique string, known as the component 2318 name. Component names for derived components always start with the 2319 "@" (at) symbol to distinguish them from HTTP header fields. IANA is 2320 asked to create and maintain a new registry typed "HTTP Signature 2321 Derived Component Names" to record and maintain the set of non-field 2322 component names and the methods to produce their associated component 2323 values. Initial values for this registry are given in Section 6.3.2. 2324 Future assignments and modifications to existing assignments are to 2325 be made through the Expert Review registration policy [RFC8126] and 2326 shall follow the template presented in Section 6.3.1. 2328 6.3.1. Registration Template 2330 Name: 2331 A name for the HTTP derived component. The name MUST begin with 2332 the "@" character followed by an ASCII string consisting only of 2333 lower-case characters ("a" - "z"), digits ("0" - "9"), and hyphens 2334 ("-"), and SHOULD NOT exceed 20 characters in length. The name 2335 MUST be unique within the context of the registry. 2337 Description: 2338 A description of the derived component. 2340 Status: 2341 A brief text description of the status of the algorithm. The 2342 description MUST begin with one of "Active" or "Deprecated", and 2343 MAY provide further context or explanation as to the reason for 2344 the status. 2346 Target: 2347 The valid message targets for the derived parameter. MUST be one 2348 of the values "Request", "Response", or "Request, Response". The 2349 semantics of these are defined in Section 2.2. 2351 Specification document(s): 2352 Reference to the document(s) that specify the derived component, 2353 preferably including a URI that can be used to retrieve a copy of 2354 the document(s). An indication of the relevant sections may also 2355 be included but is not required. 2357 6.3.2. Initial Contents 2359 The table below contains the initial contents of the HTTP Signature 2360 Derived Component Names Registry. 2362 +===========+============+=========+========+===============+=======+ 2363 |Name |Description |Status |Target |Specification | | 2364 | | | | |document(s) | | 2365 +===========+============+=========+========+===============+=======+ 2366 |@signature-|Signature |Active |Request,|Section 2.2.1 | | 2367 |params |parameters, | |Response|of RFC nnnn | | 2368 | |including | | | | | 2369 | |covered | | | | | 2370 | |content list| | | | | 2371 +-----------+------------+---------+--------+---------------+-------+ 2372 |@method |The HTTP |Active |Request |Section 2.2.2 | | 2373 | |request | | |of RFC nnnn | | 2374 | |method | | | | | 2375 +-----------+------------+---------+--------+---------------+-------+ 2376 |@authority |The HTTP |Active |Request |Section 2.2.4 | | 2377 | |authority, | | |of RFC nnnn | | 2378 | |or target | | | | | 2379 | |host | | | | | 2380 +-----------+------------+---------+--------+---------------+-------+ 2381 |@scheme |The URI |Active |Request |Section 2.2.5 | | 2382 | |scheme of | | |of RFC nnnn | | 2383 | |the request | | | | | 2384 | |URI | | | | | 2385 +-----------+------------+---------+--------+---------------+-------+ 2386 |@target-uri|The full |Active |Request |Section 2.2.3 | | 2387 | |target URI | | |of RFC nnnn | | 2388 | |of the | | | | | 2389 | |request | | | | | 2390 +-----------+------------+---------+--------+---------------+-------+ 2391 |@request- |The request |Active |Request |Section 2.2.6 | | 2392 |target |target of | | |of RFC nnnn | | 2393 | |the request | | | | | 2394 +-----------+------------+---------+--------+---------------+-------+ 2395 |@path |The full |Active |Request |Section 2.2.7 | | 2396 | |path of the | | |of RFC nnnn | | 2397 | |request URI | | | | | 2398 +-----------+------------+---------+--------+---------------+-------+ 2399 |@query |The full |Active |Request |Section 2.2.8 | | 2400 | |query of the| | |of RFC nnnn | | 2401 | |request URI | | | | | 2402 +-----------+------------+---------+--------+---------------+-------+ 2403 |@query- | |A single |Active |Request |Section| 2404 |param | |named | | |2.2.9 | 2405 | | |query | | |of RFC | 2406 | | |parameter| | |nnnn | 2407 +-----------+------------+---------+--------+---------------+-------+ 2408 |@status |The status |Active |Response|Section 2.2.10 | | 2409 | |code of the | | |of RFC nnnn | | 2410 | |response | | | | | 2411 +-----------+------------+---------+--------+---------------+-------+ 2413 Table 3: Initial contents of the HTTP Signature Derived Component 2414 Names Registry. 2416 6.4. HTTP Signature Component Parameters Registry 2418 This document defines several kinds of component identifiers, some of 2419 which can be parameterized in specific circumstances to provide 2420 unique modified behavior. IANA is asked to create and maintain a new 2421 registry typed "HTTP Signature Component Parameters" to record and 2422 maintain the set of parameters names, the component identifiers they 2423 are associated with, and the modifications these parameters make to 2424 the component value. Initial values for this registry are given in 2425 Section 6.4.2. Future assignments and modifications to existing 2426 assignments are to be made through the Expert Review registration 2427 policy [RFC8126] and shall follow the template presented in 2428 Section 6.4.1. 2430 6.4.1. Registration Template 2432 Name: 2433 A name for the parameter. The name MUST be an ASCII string that 2434 conforms to the key ABNF rule defined in [STRUCTURED-FIELDS] and 2435 SHOULD NOT exceed 20 characters in length. The name MUST be 2436 unique within the context of the registry. 2438 Description: 2439 A description of the parameter's function. 2441 Status: 2442 A brief text description of the status of the parameter. The 2443 description MUST begin with one of "Active" or "Deprecated", and 2444 MAY provide further context or explanation as to the reason for 2445 the status. 2447 Target: 2448 The applicable component identifiers for the parmeter. Can be a 2449 combination of one or more derived component identifiers as 2450 described in Section 2.2, one or more specific HTTP field names, 2451 the special value "Field Value" meaning all HTTP fields, or a 2452 separate human-readable description of the target. 2454 Specification document(s): 2455 Reference to the document(s) that specify the derived component, 2456 preferably including a URI that can be used to retrieve a copy of 2457 the document(s). An indication of the relevant sections may also 2458 be included but is not required. 2460 6.4.2. Initial Contents 2462 The table below contains the initial contents of the HTTP Signature 2463 Derived Component Names Registry. 2465 +======+===============+========+=================+===============+ 2466 | Name | Description | Status | Target | Specification | 2467 | | | | | document(s) | 2468 +======+===============+========+=================+===============+ 2469 | key | Dictionary | Active | Section 2.1.2 | | 2470 | | structured | | of RFC nnnn | | 2471 | | fields | | | | 2472 +------+---------------+--------+-----------------+---------------+ 2473 | name | Named query | Active | @query-param | Section 2.2.9 | 2474 | | parameters | | | of RFC nnnn | 2475 +------+---------------+--------+-----------------+---------------+ 2476 | sf | Strict | Active | Structured | Section 2.1.1 | 2477 | | structured | | fields | of RFC nnnn | 2478 | | field | | | | 2479 | | serialization | | | | 2480 +------+---------------+--------+-----------------+---------------+ 2481 | req | Related | Active | Derived content | Section 2.2.5 | 2482 | | request | | identifiers | of RFC nnnn | 2483 | | indicator | | with a target | | 2484 | | | | of Request or | | 2485 | | | | any field | | 2486 +------+---------------+--------+-----------------+---------------+ 2488 Table 4: Initial contents of the HTTP Signature Component 2489 Parameters Registry. 2491 7. Security Considerations 2493 In order for an HTTP message to be considered covered by a signature, 2494 all of the following conditions have to be true: 2496 * a signature is expected or allowed on the message by the verifier 2498 * the signature exists on the message 2500 * the signature is verified against the identified key material and 2501 algorithm 2503 * the key material and algorithm are appropriate for the context of 2504 the message 2506 * the signature is within expected time boundaries 2508 * the signature covers the expected content, including any critical 2509 components 2511 7.1. Signature Verification Skipping 2513 HTTP Message Signatures only provide security if the signature is 2514 verified by the verifier. Since the message to which the signature 2515 is attached remains a valid HTTP message without the signature 2516 fields, it is possible for a verifier to ignore the output of the 2517 verification function and still process the message. Common reasons 2518 for this could be relaxed requirements in a development environment 2519 or a temporary suspension of enforcing verification during debugging 2520 an overall system. Such temporary suspensions are difficult to 2521 detect under positive-example testing since a good signature will 2522 always trigger a valid response whether or not it has been checked. 2524 To detect this, verifiers should be tested using both valid and 2525 invalid signatures, ensuring that the invalid signature fails as 2526 expected. 2528 7.2. Use of TLS 2530 The use of HTTP Message Signatures does not negate the need for TLS 2531 or its equivalent to protect information in transit. Message 2532 signatures provide message integrity over the covered message 2533 components but do not provide any confidentiality for the 2534 communication between parties. 2536 TLS provides such confidentiality between the TLS endpoints. As part 2537 of this, TLS also protects the signature data itself from being 2538 captured by an attacker, which is an important step in preventing 2539 signature replay (Section 7.3). 2541 When TLS is used, it needs to be deployed according to the 2542 recommendations in [BCP195]. 2544 7.3. Signature Replay 2546 Since HTTP Message Signatures allows sub-portions of the HTTP message 2547 to be signed, it is possible for two different HTTP messages to 2548 validate against the same signature. The most extreme form of this 2549 would be a signature over no message components. If such a signature 2550 were intercepted, it could be replayed at will by an attacker, 2551 attached to any HTTP message. Even with sufficient component 2552 coverage, a given signature could be applied to two similar HTTP 2553 messages, allowing a message to be replayed by an attacker with the 2554 signature intact. 2556 To counteract these kinds of attacks, it's first important for the 2557 signer to cover sufficient portions of the message to differentiate 2558 it from other messages. In addition, the signature can use the nonce 2559 signature parameter to provide a per-message unique value to allow 2560 the verifier to detect replay of the signature itself if a nonce 2561 value is repeated. Furthermore, the signer can provide a timestamp 2562 for when the signature was created and a time at which the signer 2563 considers the signature to be invalid, limiting the utility of a 2564 captured signature value. 2566 If a verifier wants to trigger a new signature from a signer, it can 2567 send the Accept-Signature header field with a new nonce parameter. 2568 An attacker that is simply replaying a signature would not be able to 2569 generate a new signature with the chosen nonce value. 2571 7.4. Insufficient Coverage 2573 Any portions of the message not covered by the signature are 2574 susceptible to modification by an attacker without affecting the 2575 signature. An attacker can take advantage of this by introducing a 2576 header field or other message component that will change the 2577 processing of the message but will not be covered by the signature. 2578 Such an altered message would still pass signature verification, but 2579 when the verifier processes the message as a whole, the unsigned 2580 content injected by the attacker would subvert the trust conveyed by 2581 the valid signature and change the outcome of processing the message. 2583 To combat this, an application of this specification should require 2584 as much of the message as possible to be signed, within the limits of 2585 the application and deployment. The verifier should only trust 2586 message components that have been signed. Verifiers could also strip 2587 out any sensitive unsigned portions of the message before processing 2588 of the message continues. 2590 7.5. Cryptography and Signature Collision 2592 The HTTP Message Signatures specification does not define any of its 2593 own cryptographic primitives, and instead relies on other 2594 specifications to define such elements. If the signature algorithm 2595 or key used to process the signature base is vulnerable to any 2596 attacks, the resulting signature will also be susceptible to these 2597 same attacks. 2599 A common attack against signature systems is to force a signature 2600 collision, where the same signature value successfully verifies 2601 against multiple different inputs. Since this specification relies 2602 on reconstruction of the input string based on an HTTP message, and 2603 the list of components signed is fixed in the signature, it is 2604 difficult but not impossible for an attacker to effect such a 2605 collision. An attacker would need to manipulate the HTTP message and 2606 its covered message components in order to make the collision 2607 effective. 2609 To counter this, only vetted keys and signature algorithms should be 2610 used to sign HTTP messages. The HTTP Message Signatures Algorithm 2611 Registry is one source of potential trusted algorithms. 2613 While it is possible for an attacker to substitute the signature 2614 parameters value or the signature value separately, the signature 2615 base generation algorithm (Section 2.4) always covers the signature 2616 parameters as the final value in the input string using a 2617 deterministic serialization method. This step strongly binds the 2618 signature base with the signature value in a way that makes it much 2619 more difficult for an attacker to perform a partial substitution on 2620 the signature bases. 2622 7.6. Key Theft 2624 A foundational assumption of signature-based cryptographic systems is 2625 that the signing key is not compromised by an attacker. If the keys 2626 used to sign the message are exfiltrated or stolen, the attacker will 2627 be able to generate their own signatures using those keys. As a 2628 consequence, signers have to protect any signing key material from 2629 exfiltration, capture, and use by an attacker. 2631 To combat this, signers can rotate keys over time to limit the amount 2632 of time stolen keys are useful. Signers can also use key escrow and 2633 storage systems to limit the attack surface against keys. 2634 Furthermore, the use of asymmetric signing algorithms exposes key 2635 material less than the use of symmetric signing algorithms 2636 (Section 7.11). 2638 7.7. Modification of Required Message Parameters 2640 An attacker could effectively deny a service by modifying an 2641 otherwise benign signature parameter or signed message component. 2642 While rejecting a modified message is the desired behavior, 2643 consistently failing signatures could lead to the verifier turning 2644 off signature checking in order to make systems work again (see 2645 Section 7.1). 2647 If such failures are common within an application, the signer and 2648 verifier should compare their generated signature bases with each 2649 other to determine which part of the message is being modified. 2650 However, the signer and verifier should not remove the requirement to 2651 sign the modified component when it is suspected an attacker is 2652 modifying the component. 2654 7.8. Mismatch of Signature Parameters from Message 2656 The verifier needs to make sure that the signed message components 2657 match those in the message itself. This specification encourages 2658 this by requiring the verifier to derive these values from the 2659 message, but lazy cacheing or conveyance of the signature base to a 2660 processing system could lead to downstream verifiers accepting a 2661 message that does not match the presented signature. 2663 7.9. Multiple Signature Confusion 2665 Since multiple signatures can be applied to one message 2666 (Section 4.3), it is possible for an attacker to attach their own 2667 signature to a captured message without modifying existing 2668 signatures. This new signature could be completely valid based on 2669 the attacker's key, or it could be an invalid signature for any 2670 number of reasons. Each of these situations need to be accounted 2671 for. 2673 A verifier processing a set of valid signatures needs to account for 2674 all of the signers, identified by the signing keys. Only signatures 2675 from expected signers should be accepted, regardless of the 2676 cryptographic validity of the signature itself. 2678 A verifier processing a set of signatures on a message also needs to 2679 determine what to do when one or more of the signatures are not 2680 valid. If a message is accepted when at least one signature is 2681 valid, then a verifier could drop all invalid signatures from the 2682 request before processing the message further. Alternatively, if the 2683 verifier rejects a message for a single invalid signature, an 2684 attacker could use this to deny service to otherwise valid messages 2685 by injecting invalid signatures alongside the valid ones. 2687 7.10. Signature Labels 2689 HTTP Message Signature values are identified in the Signature and 2690 Signature-Input field values by unique labels. These labels are 2691 chosen only when attaching the signature values to the message and 2692 are not accounted for in the signing process. An intermediary adding 2693 its own signature is allowed to re-label an existing signature when 2694 processing the message. 2696 Therefore, applications should not rely on specific labels being 2697 present, and applications should not put semantic meaning on the 2698 labels themselves. Instead, additional signature parmeters can be 2699 used to convey whatever additional meaning is required to be attached 2700 to and covered by the signature. 2702 7.11. Symmetric Cryptography 2704 The HTTP Message Signatures specification allows for both asymmetric 2705 and symmetric cryptography to be applied to HTTP messages. By its 2706 nature, symmetric cryptographic methods require the same key material 2707 to be known by both the signer and verifier. This effectively means 2708 that a verifier is capable of generating a valid signature, since 2709 they have access to the same key material. An attacker that is able 2710 to compromise a verifier would be able to then impersonate a signer. 2712 Where possible, asymmetric methods or secure key agreement mechanisms 2713 should be used in order to avoid this type of attack. When symmetric 2714 methods are used, distribution of the key material needs to be 2715 protected by the overall system. One technique for this is the use 2716 of separate cryptographic modules that separate the verification 2717 process (and therefore the key material) from other code, minimizing 2718 the vulnerable attack surface. Another technique is the use of key 2719 derivation functions that allow the signer and verifier to agree on 2720 unique keys for each message without having to share the key values 2721 directly. 2723 Additionally, if symmetric algorithms are allowed within a system, 2724 special care must be taken to avoid key downgrade attacks 2725 (Section 7.15). 2727 7.12. Canonicalization Attacks 2729 Any ambiguity in the generation of the signature base could provide 2730 an attacker with leverage to substitute or break a signature on a 2731 message. Some message component values, particularly HTTP field 2732 values, are potentially susceptible to broken implementations that 2733 could lead to unexpected and insecure behavior. Naive 2734 implementations of this specification might implement HTTP field 2735 processing by taking the single value of a field and using it as the 2736 direct component value without processing it appropriately. 2738 For example, if the handling of obs-fold field values does not remove 2739 the internal line folding and whitespace, additional newlines could 2740 be introduced into the signature base by the signer, providing a 2741 potential place for an attacker to mount a signature collision 2742 (Section 7.5) attack. Alternatively, if header fields that appear 2743 multiple times are not joined into a single string value, as is 2744 required by this specification, similar attacks can be mounted as a 2745 signed component value would show up in the input string more than 2746 once and could be substituted or otherwise attacked in this way. 2748 To counter this, the entire field processing algorithm needs to be 2749 implemented by all implementations of signers and verifiers. 2751 7.13. Key Specification Mix-Up 2753 The existence of a valid signature on an HTTP message is not 2754 sufficient to prove that the message has been signed by the 2755 appropriate party. It is up to the verifier to ensure that a given 2756 key and algorithm are appropriate for the message in question. If 2757 the verifier does not perform such a step, an attacker could 2758 substitute their own signature using their own key on a message and 2759 force a verifier to accept and process it. To combat this, the 2760 verifier needs to ensure that not only does the signature validate 2761 for a message, but that the key and algorithm used are appropriate. 2763 7.14. HTTP Versions and Component Ambiguity 2765 Some message components are expressed in different ways across HTTP 2766 versions. For example, the authority of the request target is sent 2767 using the Host header field in HTTP 1.1 but with the :authority 2768 pseudo-header in HTTP 2. If a signer sends an HTTP 1.1 message and 2769 signs the Host field, but the message is translated to HTTP 2 before 2770 it reaches the verifier, the signature will not validate as the Host 2771 header field could be dropped. 2773 It is for this reason that HTTP Message Signatures defines a set of 2774 derived components that define a single way to get value in question, 2775 such as the @authority derived component (Section 2.2.4) in lieu of 2776 the Host header field. Applications should therefore prefer derived 2777 components for such options where possible. 2779 7.15. Key and Algorithm Specification Downgrades 2781 Applications of this specification need to protect against key 2782 specification downgrade attacks. For example, the same RSA key can 2783 be used for both RSA-PSS and RSA v1.5 signatures. If an application 2784 expects a key to only be used with RSA-PSS, it needs to reject 2785 signatures for that key using the weaker RSA 1.5 specification. 2787 Another example of a downgrade attack occurs when an asymmetric 2788 algorithm is expected, such as RSA-PSS, but an attacker substitutes a 2789 signature using symmetric algorithm, such as HMAC. A naive verifier 2790 implementation could use the value of the public RSA key as the input 2791 to the HMAC verification function. Since the public key is known to 2792 the attacker, this would allow the attacker to create a valid HMAC 2793 signature against this known key. To prevent this, the verifier 2794 needs to ensure that both the key material and the algorithm are 2795 appropriate for the usage in question. Additionally, while this 2796 specification does allow runtime specification of the algorithm using 2797 the alg signature parameter, applications are encouraged to use other 2798 mechanisms such as static configuration or higher protocol-level 2799 algorithm specification instead. 2801 7.16. Parsing Structured Field Values 2803 Several parts of this specification rely on the parsing of structured 2804 field values [STRUCTURED-FIELDS]. In particular, normalization of 2805 HTTP structured field values (Section 2.1.1), referencing members of 2806 a dictionary structured field (Section 2.1.2), and processing the 2807 @signature-input value when verifying a signature (Section 3.2). 2808 While structured field values are designed to be relatively simple to 2809 parse, a naive or broken implementation of such a parser could lead 2810 to subtle attack surfaces being exposed in the implementation. 2812 For example, if a buggy parser of the @signature-input value does not 2813 enforce proper closing of quotes around string values within the list 2814 of component identifiers, an attacker could take advantage of this 2815 and inject additional content into the signature base through 2816 manipulating the Signature-Input field value on a message. 2818 To counteract this, implementations should use fully compliant and 2819 trusted parsers for all structured field processing, both on the 2820 signer and verifier side. 2822 7.17. Choosing Message Components 2824 Applications of HTTP Message Signatures need to decide which message 2825 components will be covered by the signature. Depending on the 2826 application, some components could be expected to be changed by 2827 intermediaries prior to the signature's verification. If these 2828 components are covered, such changes would, by design, break the 2829 signature. 2831 However, the HTTP Message Signature standard allows for flexibility 2832 in determining which components are signed precisely so that a given 2833 application can choose the appropriate portions of the message that 2834 need to be signed, avoiding problematic components. For example, a 2835 web application framework that relies on rewriting query parameters 2836 might avoid use of the @query derived component in favor of sub- 2837 indexing the query value using @query-param derived components 2838 instead. 2840 Some components are expected to be changed by intermediaries and 2841 ought not to be signed under most circumstance. The Via and 2842 Forwarded header fields, for example, are expected to be manipulated 2843 by proxies and other middle-boxes, including replacing or entirely 2844 dropping existing values. These fields should not be covered by the 2845 signature except in very limited and tightly-coupled scenarios. 2847 Additional considerations for choosing signature aspects are 2848 discussed in Section 1.4. 2850 7.18. Confusing HTTP Field Names for Derived Component Names 2852 The definition of HTTP field names does not allow for the use of the 2853 @ character anywhere in the name. As such, since all derived 2854 component names start with the @ character, these namespaces should 2855 be completely separate. However, some HTTP implementations are not 2856 sufficiently strict about the characters accepted in HTTP headers. 2857 In such implementations, a sender (or attacker) could inject a header 2858 field starting with an @ character and have it passed through to the 2859 application code. These invalid header fields could be used to 2860 override a portion of the derived message content and substitute an 2861 arbitrary value, providing a potential place for an attacker to mount 2862 a signature collision (Section 7.5) attack. 2864 To combat this, when selecting values for a message component, if the 2865 component name starts with the @ character, it needs to be processed 2866 as a derived component and never taken as a fields. Only if the 2867 component name does not start with the @ character can it be taken 2868 from the fields of the message. The algorithm discussed in 2869 Section 2.4 provides a safe order of operations. 2871 7.19. Non-deterministic Signature Primitives 2873 Some cryptographic primitives such as RSA PSS and ECDSA have non- 2874 deterministic outputs, which include some amount of entropy within 2875 the algorithm. For such algorithms, multiple signatures generated in 2876 succession will not match. A lazy implementation of a verifier could 2877 ignore this distinction and simply check for the same value being 2878 created by re-signing the signature base. Such an implementation 2879 would work for deterministic algorithms such as HMAC and EdDSA but 2880 fail to verify valid signatures made using non-deterministic 2881 algorithms. It is therefore important that a verifier always use the 2882 correctly-defined verification function for the algorithm in question 2883 and not do a simple comparison. 2885 7.20. Choosing Signature Parameters and Derived Components over HTTP 2886 Fields 2888 Some HTTP fields have values and interpretations that are similar to 2889 HTTP signature parameters or derived components. In most cases, it 2890 is more desirable to sign the non-field alternative. In particular, 2891 the following fields should usually not be included in the signature 2892 unless the application specifically requires it: 2894 "date" The "date" field value represents the timestamp of the HTTP 2895 message. However, the creation time of the signature itself is 2896 encoded in the created signature parameter. These two values can 2897 be different, depending on how the signature and the HTTP message 2898 are created and serialized. Applications processing signatures 2899 for valid time windows should use the created signature parameter 2900 for such calculations. An application could also put limits on 2901 how much skew there is between the "date" field and the created 2902 signature parameter, in order to limit the application of a 2903 generated signature to different HTTP messages. See also 2904 Section 7.3 and Section 7.4. 2906 "host" The "host" header field is specific to HTTP 1.1, and its 2907 functionality is subsumed by the "@authority" derived component, 2908 defined in Section 2.2.4. In order to preserve the value across 2909 different HTTP versions, applications should always use the 2910 "@authority" derived component. 2912 7.21. Semantically Equivalent Field Values 2914 The signature base generation algorithm (Section 2.4) uses the value 2915 of an HTTP field as its component value. In the common case, this 2916 amounts to taking the actual bytes of the field value as the 2917 component value for both the signer and verifier. However, some 2918 field values allow for transformation of the values in semantically 2919 equivalent ways that alter the bytes used in the value itself. For 2920 example, a field definition can declare some or all of its value to 2921 be case-insensitive, or to have special handling of internal 2922 whitespace characters. Other fields have expected transformations 2923 from intermediaries, such as the removal of comments in the Via 2924 header field. In such cases, a verifier could be tripped up by using 2925 the equivalent transformed field value, which would differ from the 2926 byte value used by the signer. The verifier would have have a 2927 difficult time finding this class of errors since the value of the 2928 field is still acceptable for the application, but the actual bytes 2929 required by the signature base would not match. 2931 When processing such fields, the signer and verifier have to agree 2932 how to handle such transformations, if at all. One option is to not 2933 sign problematic fields, but care must be taken to ensure that there 2934 is still sufficient signature coverage (Section 7.4) for the 2935 application. Another option is to define an application-specific 2936 canonicalization value for the field before it is added to the HTTP 2937 message, such as to always remove internal comments before signing, 2938 or to always transform values to lowercase. Since these 2939 transformations are applied prior to the field being used as input to 2940 the signature base generation algorithm, the signature base will 2941 still simply contain the byte value of the field as it appears within 2942 the message. If the transformations were to be applied after the 2943 value is extracted from the message but before it is added to the 2944 signature base, different attack surfaces such as value substitution 2945 attacks could be launched against the application. All application- 2946 specific additional rules are outside the scope of this 2947 specification, and by their very nature these transformations would 2948 harm interoperability of the implementation outside of this specific 2949 application. It is recommended that applications avoid the use of 2950 such additional rules wherever possible. 2952 7.22. Message Content 2954 On its own, this specification does not provide coverage for the 2955 content of an HTTP message under the signature, either in request or 2956 response. However, [DIGEST] defines a set of fields that allow a 2957 cryptographic digest of the content to be represented in a field. 2958 Once this field is created, it can be included just like any other 2959 field as defined in Section 2.1. 2961 For example, in the following response message: 2963 HTTP/1.1 200 OK 2964 Content-Type: application/json 2966 {"hello": "world"} 2968 The digest of the content can be added to the Content-Digest field as 2969 follows: 2971 NOTE: '\' line wrapping per RFC 8792 2973 HTTP/1.1 200 OK 2974 Content-Type: application/json 2975 Content-Digest: \ 2976 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 2978 {"hello": "world"} 2979 This field can be included in a signature base just like any other 2980 field along with the basic signature parameters: 2982 "@status": 200 2983 "content-digest": \ 2984 sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=: 2985 "@signature-input": ("@status" "content-digest") 2987 From here, the signing process proceeds as usual. 2989 Upon verification, it is important that the verifier validate not 2990 only the signature but also the value of the Content-Digest field 2991 itself against the actual received content. Unless the verifier 2992 performs this step, it would be possible for an attacker to 2993 substitute the message content but leave the Content-Digest field 2994 value untouched. Since only the field value is covered by the 2995 signature directly, checking only the signature is not sufficient 2996 protection against such a substitution attack. 2998 8. Privacy Considerations 3000 8.1. Identification through Keys 3002 If a signer uses the same key with multiple verifiers, or uses the 3003 same key over time with a single verifier, the ongoing use of that 3004 key can be used to track the signer throughout the set of verifiers 3005 that messages are sent to. Since cryptographic keys are meant to be 3006 functionally unique, the use of the same key over time is a strong 3007 indicator that it is the same party signing multiple messages. 3009 In many applications, this is a desirable trait, and it allows HTTP 3010 Message Signatures to be used as part of authenticating the signer to 3011 the verifier. However, it could be unintentional tracking that a 3012 signer might not be aware of. To counter this kind of tracking, a 3013 signer can use a different key for each verifier that it is in 3014 communication with. Sometimes, a signer could also rotate their key 3015 when sending messages to a given verifier. These approaches do not 3016 negate the need for other anti-tracking techniques to be applied as 3017 necessary. 3019 8.2. Signatures do not provide confidentiality 3021 HTTP Message Signatures do not provide confidentiality of any of the 3022 information protected by the signature. The content of the HTTP 3023 message, including the value of all fields and the value of the 3024 signature itself, is presented in plaintext to any party with access 3025 to the message. 3027 To provide confidentiality at the transport level, TLS or its 3028 equivalent can be used as discussed in Section 7.2. 3030 8.3. Oracles 3032 It is important to balance the need for providing useful feedback to 3033 developers on error conditions without providing additional 3034 information to an attacker. For example, a naive but helpful server 3035 implementation might try to indicate the required key identifier 3036 needed for requesting a resource. If someone knows who controls that 3037 key, a correlation can be made between the resource's existence and 3038 the party identified by the key. Access to such information could be 3039 used by an attacker as a means to target the legitimate owner of the 3040 resource for further attacks. 3042 8.4. Required Content 3044 A core design tenet of this specification is that all message 3045 components covered by the signature need to be available to the 3046 verifier in order to recreate the signature base and verify the 3047 signature. As a consequence, if an application of this specification 3048 requires that a particular field be signed, the verifier will need 3049 access to the value of that field. 3051 For example, in some complex systems with intermediary processors 3052 this could cause the surprising behavior of an intermediary not being 3053 able to remove privacy-sensitive information from a message before 3054 forwarding it on for processing, for fear of breaking the signature. 3055 A possible mitigation for this specific situation would be for the 3056 intermediary to verify the signature itself, then modifying the 3057 message to remove the privacy-sensitive information. The 3058 intermediary can add its own signature at this point to signal to the 3059 next destination that the incoming signature was validated, as is 3060 shown in the example in Section 4.3. 3062 9. References 3064 9.1. Normative References 3066 [FIPS186-4] 3067 "Digital Signature Standard (DSS)", 2013, 3068 . 3071 [HTMLURL] "URL (Living Standard)", 2021, 3072 . 3074 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 3075 Semantics", Work in Progress, Internet-Draft, draft-ietf- 3076 httpbis-semantics-19, 12 September 2021, 3077 . 3080 [HTTP1] Fielding, R. T., Nottingham, M., and J. Reschke, 3081 "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf- 3082 httpbis-messaging-19, 12 September 2021, 3083 . 3086 [POSIX.1] "The Open Group Base Specifications Issue 7, 2018 3087 edition", 2018, 3088 . 3090 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 3091 Hashing for Message Authentication", RFC 2104, 3092 DOI 10.17487/RFC2104, February 1997, 3093 . 3095 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3096 Requirement Levels", BCP 14, RFC 2119, 3097 DOI 10.17487/RFC2119, March 1997, 3098 . 3100 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3101 Resource Identifier (URI): Generic Syntax", STD 66, 3102 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3103 . 3105 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 3106 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 3107 DOI 10.17487/RFC6234, May 2011, 3108 . 3110 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 3111 DOI 10.17487/RFC7517, May 2015, 3112 . 3114 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 3115 DOI 10.17487/RFC7518, May 2015, 3116 . 3118 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 3119 "PKCS #1: RSA Cryptography Specifications Version 2.2", 3120 RFC 8017, DOI 10.17487/RFC8017, November 2016, 3121 . 3123 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 3124 Signature Algorithm (EdDSA)", RFC 8032, 3125 DOI 10.17487/RFC8032, January 2017, 3126 . 3128 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3129 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3130 May 2017, . 3132 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 3133 "Handling Long Lines in Content of Internet-Drafts and 3134 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 3135 . 3137 [STRUCTURED-FIELDS] 3138 Nottingham, M. and P-H. Kamp, "Structured Field Values for 3139 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 3140 . 3142 9.2. Informative References 3144 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 3145 "Recommendations for Secure Use of Transport Layer 3146 Security (TLS) and Datagram Transport Layer Security 3147 (DTLS)", BCP 195, RFC 7525, May 2015. 3149 Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS 3150 1.1", BCP 195, RFC 8996, March 2021. 3152 3154 [CLIENT-CERT] 3155 Campbell, B. and M. Bishop, "Client-Cert HTTP Header 3156 Field", Work in Progress, Internet-Draft, draft-ietf- 3157 httpbis-client-cert-field-02, 25 May 2022, 3158 . 3161 [DIGEST] Polli, R. and L. Pardue, "Digest Fields", Work in 3162 Progress, Internet-Draft, draft-ietf-httpbis-digest- 3163 headers-09, 25 May 2022, 3164 . 3167 [RFC7239] Petersson, A. and M. Nilsson, "Forwarded HTTP Extension", 3168 RFC 7239, DOI 10.17487/RFC7239, June 2014, 3169 . 3171 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3172 Writing an IANA Considerations Section in RFCs", BCP 26, 3173 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3174 . 3176 [TLS] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3177 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3178 . 3180 Appendix A. Detecting HTTP Message Signatures 3182 There have been many attempts to create signed HTTP messages in the 3183 past, including other non-standardized definitions of the Signature 3184 field, which is used within this specification. It is recommended 3185 that developers wishing to support both this specification and other 3186 historical drafts do so carefully and deliberately, as 3187 incompatibilities between this specification and various versions of 3188 other drafts could lead to unexpected problems. 3190 It is recommended that implementers first detect and validate the 3191 Signature-Input field defined in this specification to detect that 3192 this standard is in use and not an alternative. If the Signature- 3193 Input field is present, all Signature fields can be parsed and 3194 interpreted in the context of this draft. 3196 Appendix B. Examples 3198 The following non-normative examples are provided as a means of 3199 testing implementations of HTTP Message Signatures. The signed 3200 messages given can be used to create the signature base with the 3201 stated parameters, creating signatures using the stated algorithms 3202 and keys. 3204 The private keys given can be used to generate signatures, though 3205 since several of the demonstrated algorithms are nondeterministic, 3206 the results of a signature are expected to be different from the 3207 exact bytes of the examples. The public keys given can be used to 3208 validate all signed examples. 3210 B.1. Example Keys 3212 This section provides cryptographic keys that are referenced in 3213 example signatures throughout this document. These keys MUST NOT be 3214 used for any purpose other than testing. 3216 The key identifiers for each key are used throughout the examples in 3217 this specification. It is assumed for these examples that the signer 3218 and verifier can unambiguously dereference all key identifiers used 3219 here, and that the keys and algorithms used are appropriate for the 3220 context in which the signature is presented. 3222 The components for each private key in PEM format can be displayed by 3223 executing the following OpenSSL command: 3225 openssl pkey -text 3227 This command was tested with all the example keys on OpenSSL version 3228 1.1.1m. Note that some systems cannot produce or use these keys 3229 directly, and may require additional processing. 3231 B.1.1. Example Key RSA test 3233 The following key is a 2048-bit RSA public and private key pair, 3234 referred to in this document as test-key-rsa. This key is encoded in 3235 PEM Format, with no encryption. 3237 -----BEGIN RSA PUBLIC KEY----- 3238 MIIBCgKCAQEAhAKYdtoeoy8zcAcR874L8cnZxKzAGwd7v36APp7Pv6Q2jdsPBRrw 3239 WEBnez6d0UDKDwGbc6nxfEXAy5mbhgajzrw3MOEt8uA5txSKobBpKDeBLOsdJKFq 3240 MGmXCQvEG7YemcxDTRPxAleIAgYYRjTSd/QBwVW9OwNFhekro3RtlinV0a75jfZg 3241 kne/YiktSvLG34lw2zqXBDTC5NHROUqGTlML4PlNZS5Ri2U4aCNx2rUPRcKIlE0P 3242 uKxI4T+HIaFpv8+rdV6eUgOrB2xeI1dSFFn/nnv5OoZJEIB+VmuKn3DCUcCZSFlQ 3243 PSXSfBDiUGhwOw76WuSSsf1D4b/vLoJ10wIDAQAB 3244 -----END RSA PUBLIC KEY----- 3246 -----BEGIN RSA PRIVATE KEY----- 3247 MIIEqAIBAAKCAQEAhAKYdtoeoy8zcAcR874L8cnZxKzAGwd7v36APp7Pv6Q2jdsP 3248 BRrwWEBnez6d0UDKDwGbc6nxfEXAy5mbhgajzrw3MOEt8uA5txSKobBpKDeBLOsd 3249 JKFqMGmXCQvEG7YemcxDTRPxAleIAgYYRjTSd/QBwVW9OwNFhekro3RtlinV0a75 3250 jfZgkne/YiktSvLG34lw2zqXBDTC5NHROUqGTlML4PlNZS5Ri2U4aCNx2rUPRcKI 3251 lE0PuKxI4T+HIaFpv8+rdV6eUgOrB2xeI1dSFFn/nnv5OoZJEIB+VmuKn3DCUcCZ 3252 SFlQPSXSfBDiUGhwOw76WuSSsf1D4b/vLoJ10wIDAQABAoIBAG/JZuSWdoVHbi56 3253 vjgCgkjg3lkO1KrO3nrdm6nrgA9P9qaPjxuKoWaKO1cBQlE1pSWp/cKncYgD5WxE 3254 CpAnRUXG2pG4zdkzCYzAh1i+c34L6oZoHsirK6oNcEnHveydfzJL5934egm6p8DW 3255 +m1RQ70yUt4uRc0YSor+q1LGJvGQHReF0WmJBZHrhz5e63Pq7lE0gIwuBqL8SMaA 3256 yRXtK+JGxZpImTq+NHvEWWCu09SCq0r838ceQI55SvzmTkwqtC+8AT2zFviMZkKR 3257 Qo6SPsrqItxZWRty2izawTF0Bf5S2VAx7O+6t3wBsQ1sLptoSgX3QblELY5asI0J 3258 YFz7LJECgYkAsqeUJmqXE3LP8tYoIjMIAKiTm9o6psPlc8CrLI9CH0UbuaA2JCOM 3259 cCNq8SyYbTqgnWlB9ZfcAm/cFpA8tYci9m5vYK8HNxQr+8FS3Qo8N9RJ8d0U5Csw 3260 DzMYfRghAfUGwmlWj5hp1pQzAuhwbOXFtxKHVsMPhz1IBtF9Y8jvgqgYHLbmyiu1 3261 mwJ5AL0pYF0G7x81prlARURwHo0Yf52kEw1dxpx+JXER7hQRWQki5/NsUEtv+8RT 3262 qn2m6qte5DXLyn83b1qRscSdnCCwKtKWUug5q2ZbwVOCJCtmRwmnP131lWRYfj67 3263 B/xJ1ZA6X3GEf4sNReNAtaucPEelgR2nsN0gKQKBiGoqHWbK1qYvBxX2X3kbPDkv 3264 9C+celgZd2PW7aGYLCHq7nPbmfDV0yHcWjOhXZ8jRMjmANVR/eLQ2EfsRLdW69bn 3265 f3ZD7JS1fwGnO3exGmHO3HZG+6AvberKYVYNHahNFEw5TsAcQWDLRpkGybBcxqZo 3266 81YCqlqidwfeO5YtlO7etx1xLyqa2NsCeG9A86UjG+aeNnXEIDk1PDK+EuiThIUa 3267 /2IxKzJKWl1BKr2d4xAfR0ZnEYuRrbeDQYgTImOlfW6/GuYIxKYgEKCFHFqJATAG 3268 IxHrq1PDOiSwXd2GmVVYyEmhZnbcp8CxaEMQoevxAta0ssMK3w6UsDtvUvYvF22m 3269 qQKBiD5GwESzsFPy3Ga0MvZpn3D6EJQLgsnrtUPZx+z2Ep2x0xc5orneB5fGyF1P 3270 WtP+fG5Q6Dpdz3LRfm+KwBCWFKQjg7uTxcjerhBWEYPmEMKYwTJF5PBG9/ddvHLQ 3271 EQeNC8fHGg4UXU8mhHnSBt3EA10qQJfRDs15M38eG2cYwB1PZpDHScDnDA0= 3272 -----END RSA PRIVATE KEY----- 3274 B.1.2. Example RSA PSS Key 3276 The following key is a 2048-bit RSA public and private key pair, 3277 referred to in this document as test-key-rsa-pss. This key is PCKS#8 3278 encoded in PEM format, with no encryption. 3280 -----BEGIN PUBLIC KEY----- 3281 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr4tmm3r20Wd/PbqvP1s2 3282 +QEtvpuRaV8Yq40gjUR8y2Rjxa6dpG2GXHbPfvMs8ct+Lh1GH45x28Rw3Ry53mm+ 3283 oAXjyQ86OnDkZ5N8lYbggD4O3w6M6pAvLkhk95AndTrifbIFPNU8PPMO7OyrFAHq 3284 gDsznjPFmTOtCEcN2Z1FpWgchwuYLPL+Wokqltd11nqqzi+bJ9cvSKADYdUAAN5W 3285 Utzdpiy6LbTgSxP7ociU4Tn0g5I6aDZJ7A8Lzo0KSyZYoA485mqcO0GVAdVw9lq4 3286 aOT9v6d+nb4bnNkQVklLQ3fVAvJm+xdDOp9LCNCN48V2pnDOkFV6+U9nV5oyc6XI 3287 2wIDAQAB 3288 -----END PUBLIC KEY----- 3290 -----BEGIN PRIVATE KEY----- 3291 MIIEvgIBADALBgkqhkiG9w0BAQoEggSqMIIEpgIBAAKCAQEAr4tmm3r20Wd/Pbqv 3292 P1s2+QEtvpuRaV8Yq40gjUR8y2Rjxa6dpG2GXHbPfvMs8ct+Lh1GH45x28Rw3Ry5 3293 3mm+oAXjyQ86OnDkZ5N8lYbggD4O3w6M6pAvLkhk95AndTrifbIFPNU8PPMO7Oyr 3294 FAHqgDsznjPFmTOtCEcN2Z1FpWgchwuYLPL+Wokqltd11nqqzi+bJ9cvSKADYdUA 3295 AN5WUtzdpiy6LbTgSxP7ociU4Tn0g5I6aDZJ7A8Lzo0KSyZYoA485mqcO0GVAdVw 3296 9lq4aOT9v6d+nb4bnNkQVklLQ3fVAvJm+xdDOp9LCNCN48V2pnDOkFV6+U9nV5oy 3297 c6XI2wIDAQABAoIBAQCUB8ip+kJiiZVKF8AqfB/aUP0jTAqOQewK1kKJ/iQCXBCq 3298 pbo360gvdt05H5VZ/RDVkEgO2k73VSsbulqezKs8RFs2tEmU+JgTI9MeQJPWcP6X 3299 aKy6LIYs0E2cWgp8GADgoBs8llBq0UhX0KffglIeek3n7Z6Gt4YFge2TAcW2WbN4 3300 XfK7lupFyo6HHyWRiYHMMARQXLJeOSdTn5aMBP0PO4bQyk5ORxTUSeOciPJUFktQ 3301 HkvGbym7KryEfwH8Tks0L7WhzyP60PL3xS9FNOJi9m+zztwYIXGDQuKM2GDsITeD 3302 2mI2oHoPMyAD0wdI7BwSVW18p1h+jgfc4dlexKYRAoGBAOVfuiEiOchGghV5vn5N 3303 RDNscAFnpHj1QgMr6/UG05RTgmcLfVsI1I4bSkbrIuVKviGGf7atlkROALOG/xRx 3304 DLadgBEeNyHL5lz6ihQaFJLVQ0u3U4SB67J0YtVO3R6lXcIjBDHuY8SjYJ7Ci6Z6 3305 vuDcoaEujnlrtUhaMxvSfcUJAoGBAMPsCHXte1uWNAqYad2WdLjPDlKtQJK1diCm 3306 rqmB2g8QE99hDOHItjDBEdpyFBKOIP+NpVtM2KLhRajjcL9Ph8jrID6XUqikQuVi 3307 4J9FV2m42jXMuioTT13idAILanYg8D3idvy/3isDVkON0X3UAVKrgMEne0hJpkPL 3308 FYqgetvDAoGBAKLQ6JZMbSe0pPIJkSamQhsehgL5Rs51iX4m1z7+sYFAJfhvN3Q/ 3309 OGIHDRp6HjMUcxHpHw7U+S1TETxePwKLnLKj6hw8jnX2/nZRgWHzgVcY+sPsReRx 3310 NJVf+Cfh6yOtznfX00p+JWOXdSY8glSSHJwRAMog+hFGW1AYdt7w80XBAoGBAImR 3311 NUugqapgaEA8TrFxkJmngXYaAqpA0iYRA7kv3S4QavPBUGtFJHBNULzitydkNtVZ 3312 3w6hgce0h9YThTo/nKc+OZDZbgfN9s7cQ75x0PQCAO4fx2P91Q+mDzDUVTeG30mE 3313 t2m3S0dGe47JiJxifV9P3wNBNrZGSIF3mrORBVNDAoGBAI0QKn2Iv7Sgo4T/XjND 3314 dl2kZTXqGAk8dOhpUiw/HdM3OGWbhHj2NdCzBliOmPyQtAr770GITWvbAI+IRYyF 3315 S7Fnk6ZVVVHsxjtaHy1uJGFlaZzKR4AGNaUTOJMs6NadzCmGPAxNQQOCqoUjn4XR 3316 rOjr9w349JooGXhOxbu8nOxX 3317 -----END PRIVATE KEY----- 3319 B.1.3. Example ECC P-256 Test Key 3321 The following key is a public and private elliptical curve key pair 3322 over the curve P-256, referred to in this document as `test-key-ecc- 3323 p256. This key is encoded in PEM format, with no encryption. 3325 -----BEGIN PUBLIC KEY----- 3326 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqIVYZVLCrPZHGHjP17CTW0/+D9Lf 3327 w0EkjqF7xB4FivAxzic30tMM4GF+hR6Dxh71Z50VGGdldkkDXZCnTNnoXQ== 3328 -----END PUBLIC KEY----- 3330 -----BEGIN EC PRIVATE KEY----- 3331 MHcCAQEEIFKbhfNZfpDsW43+0+JjUr9K+bTeuxopu653+hBaXGA7oAoGCCqGSM49 3332 AwEHoUQDQgAEqIVYZVLCrPZHGHjP17CTW0/+D9Lfw0EkjqF7xB4FivAxzic30tMM 3333 4GF+hR6Dxh71Z50VGGdldkkDXZCnTNnoXQ== 3334 -----END EC PRIVATE KEY----- 3336 B.1.4. Example Ed25519 Test Key 3338 The following key is an elliptical curve key over the Edwards curve 3339 ed25519, referred to in this document as test-key-ed25519. This key 3340 is PCKS#8 encoded in PEM format, with no encryption. 3342 -----BEGIN PUBLIC KEY----- 3343 MCowBQYDK2VwAyEAJrQLj5P/89iXES9+vFgrIy29clF9CC/oPPsw3c5D0bs= 3344 -----END PUBLIC KEY----- 3346 -----BEGIN PRIVATE KEY----- 3347 MC4CAQAwBQYDK2VwBCIEIJ+DYvh6SEqVTm50DFtMDoQikTmiCqirVv9mWG9qfSnF 3348 -----END PRIVATE KEY----- 3350 B.1.5. Example Shared Secret 3352 The following shared secret is 64 randomly-generated bytes encoded in 3353 Base64, referred to in this document as test-shared-secret. 3355 NOTE: '\' line wrapping per RFC 8792 3357 uzvJfB4u3N0Jy4T7NZ75MDVcr8zSTInedJtkgcu46YW4XByzNJjxBdtjUkdJPBt\ 3358 bmHhIDi6pcl8jsasjlTMtDQ== 3360 B.2. Test Cases 3362 This section provides non-normative examples that may be used as test 3363 cases to validate implementation correctness. These examples are 3364 based on the following HTTP messages: 3366 For requests, this test-request message is used: 3368 NOTE: '\' line wrapping per RFC 8792 3370 POST /foo?param=Value&Pet=dog HTTP/1.1 3371 Host: example.com 3372 Date: Tue, 20 Apr 2021 02:07:55 GMT 3373 Content-Type: application/json 3374 Content-Digest: sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+T\ 3375 aPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 3376 Content-Length: 18 3378 {"hello": "world"} 3380 For responses, this test-response message is used: 3382 NOTE: '\' line wrapping per RFC 8792 3384 HTTP/1.1 200 OK 3385 Date: Tue, 20 Apr 2021 02:07:56 GMT 3386 Content-Type: application/json 3387 Content-Digest: sha-512=:JlEy2bfUz7WrWIjc1qV6KVLpdr/7L5/L4h7Sxvh6sN\ 3388 HpDQWDCL+GauFQWcZBvVDhiyOnAQsxzZFYwi0wDH+1pw==: 3389 Content-Length: 23 3391 {"message": "good dog"} 3393 B.2.1. Minimal Signature Using rsa-pss-sha512 3395 This example presents a minimal signature using the rsa-pss-sha512 3396 algorithm over test-request, covering none of the components of the 3397 HTTP message, but providing a timestamped signature proof of 3398 possession of the key with a signer-provided nonce. 3400 The corresponding signature base is: 3402 NOTE: '\' line wrapping per RFC 8792 3404 "@signature-params": ();created=1618884473;keyid="test-key-rsa-pss"\ 3405 ;nonce="b3k2pp5k7z-50gnwp.yemd" 3407 This results in the following Signature-Input and Signature headers 3408 being added to the message under the signature label sig-b21: 3410 NOTE: '\' line wrapping per RFC 8792 3412 Signature-Input: sig-b21=();created=1618884473\ 3413 ;keyid="test-key-rsa-pss";nonce="b3k2pp5k7z-50gnwp.yemd" 3414 Signature: sig-b21=:d2pmTvmbncD3xQm8E9ZV2828BjQWGgiwAaw5bAkgibUopem\ 3415 LJcWDy/lkbbHAve4cRAtx31Iq786U7it++wgGxbtRxf8Udx7zFZsckzXaJMkA7ChG\ 3416 52eSkFxykJeNqsrWH5S+oxNFlD4dzVuwe8DhTSja8xxbR/Z2cOGdCbzR72rgFWhzx\ 3417 2VjBqJzsPLMIQKhO4DGezXehhWwE56YCE+O6c0mKZsfxVrogUvA4HELjVKWmAvtl6\ 3418 UnCh8jYzuVG5WSb/QEVPnP5TmcAnLH1g+s++v6d4s8m0gCw1fV5/SITLq9mhho8K3\ 3419 +7EPYTU8IU1bLhdxO5Nyt8C8ssinQ98Xw9Q==: 3421 Note that since the covered components list is empty, this signature 3422 could be applied by an attacker to an unrelated HTTP message. In 3423 this example, the nonce parameter is included to prevent the same 3424 signature from being replayed more than once, but if an attacker 3425 intercepts the signature and prevents its delivery to the verifier, 3426 the attacker could apply this signature to another message. 3427 Therefore, use of an empty covered components set is discouraged. 3428 See Section 7.4 for more discussion. 3430 Note that the RSA PSS algorithm in use here is non-deterministic, 3431 meaning a different signature value will be created every time the 3432 algorithm is run. The signature value provided here can be validated 3433 against the given keys, but newly-generated signature values are not 3434 expected to match the example. See Section 7.19. 3436 B.2.2. Selective Covered Components using rsa-pss-sha512 3438 This example covers additional components in test-request using the 3439 rsa-pss-sha512 algorithm. 3441 The corresponding signature base is: 3443 NOTE: '\' line wrapping per RFC 8792 3445 "@authority": example.com 3446 "content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\ 3447 +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 3448 "@signature-params": ("@authority" "content-digest")\ 3449 ;created=1618884473;keyid="test-key-rsa-pss" 3451 This results in the following Signature-Input and Signature headers 3452 being added to the message under the label sig-b22: 3454 NOTE: '\' line wrapping per RFC 8792 3456 Signature-Input: sig-b22=("@authority" "content-digest")\ 3457 ;created=1618884473;keyid="test-key-rsa-pss" 3458 Signature: sig-b22=:Fee1uy9YGZq5UUwwYU6vz4dZNvfw3GYrFl1L6YlVIyUMuWs\ 3459 wWDNSvql4dVtSeidYjYZUm7SBCENIb5KYy2ByoC3bI+7gydd2i4OAT5lyDtmeapnA\ 3460 a8uP/b9xUpg+VSPElbBs6JWBIQsd+nMdHDe+ls/IwVMwXktC37SqsnbNyhNp6kcvc\ 3461 WpevjzFcD2VqdZleUz4jN7P+W5A3wHiMGfIjIWn36KXNB+RKyrlGnIS8yaBBrom5r\ 3462 cZWLrLbtg6VlrH1+/07RV+kgTh/l10h8qgpl9zQHu7mWbDKTq0tJ8K4ywcPoC4s2I\ 3463 4rU88jzDKDGdTTQFZoTVZxZmuTM1FvHfzIw==: 3465 Note that the RSA PSS algorithm in use here is non-deterministic, 3466 meaning a different signature value will be created every time the 3467 algorithm is run. The signature value provided here can be validated 3468 against the given keys, but newly-generated signature values are not 3469 expected to match the example. See Section 7.19. 3471 B.2.3. Full Coverage using rsa-pss-sha512 3473 This example covers all applicable message components in test-request 3474 (including the content type and length) plus many derived components, 3475 again using the rsa-pss-sha512 algorithm. Note that the Host header 3476 field is not covered because the @authority derived component is 3477 included instead. 3479 The corresponding signature base is: 3481 NOTE: '\' line wrapping per RFC 8792 3483 "date": Tue, 20 Apr 2021 02:07:55 GMT 3484 "@method": POST 3485 "@path": /foo 3486 "@query": ?param=Value&Pet=dog 3487 "@authority": example.com 3488 "content-type": application/json 3489 "content-digest": sha-512=:WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX\ 3490 +TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==: 3491 "content-length": 18 3492 "@signature-params": ("date" "@method" "@path" "@query" \ 3493 "@authority" "content-type" "content-digest" "content-length")\ 3494 ;created=1618884473;keyid="test-key-rsa-pss" 3496 This results in the following Signature-Input and Signature headers 3497 being added to the message under the label sig-b23: 3499 NOTE: '\' line wrapping per RFC 8792 3501 Signature-Input: sig-b23=("date" "@method" "@path" "@query" \ 3502 "@authority" "content-type" "content-digest" "content-length")\ 3503 ;created=1618884473;keyid="test-key-rsa-pss" 3504 Signature: sig-b23=:bbN8oArOxYoyylQQUU6QYwrTuaxLwjAC9fbY2F6SVWvh0yB\ 3505 iMIRGOnMYwZ/5MR6fb0Kh1rIRASVxFkeGt683+qRpRRU5p2voTp768ZrCUb38K0fU\ 3506 xN0O0iC59DzYx8DFll5GmydPxSmme9v6ULbMFkl+V5B1TP/yPViV7KsLNmvKiLJH1\ 3507 pFkh/aYA2HXXZzNBXmIkoQoLd7YfW91kE9o/CCoC1xMy7JA1ipwvKvfrs65ldmlu9\ 3508 bpG6A9BmzhuzF8Eim5f8ui9eH8LZH896+QIF61ka39VBrohr9iyMUJpvRX2Zbhl5Z\ 3509 JzSRxpJyoEZAFL2FUo5fTIztsDZKEgM4cUA==: 3511 Note in this example that the value of the Date header and the value 3512 of the created signature parameter need not be the same. This is due 3513 to the fact that the Date header is added when creating the HTTP 3514 Message and the created parameter is populated when creating the 3515 signature over that message, and these two times could vary. If the 3516 Date header is covered by the signature, it is up to the verifier to 3517 determine whether its value has to match that of the created 3518 parameter or not. See Section 7.20 for more discussion. 3520 Note that the RSA PSS algorithm in use here is non-deterministic, 3521 meaning a different signature value will be created every time the 3522 algorithm is run. The signature value provided here can be validated 3523 against the given keys, but newly-generated signature values are not 3524 expected to match the example. See Section 7.19. 3526 B.2.4. Signing a Response using ecdsa-p256-sha256 3528 This example covers portions of the test-response response message 3529 using the ecdsa-p256-sha256 algorithm and the key test-key-ecc-p256. 3531 The corresponding signature base is: 3533 NOTE: '\' line wrapping per RFC 8792 3535 "@status": 200 3536 "content-type": application/json 3537 "content-digest": sha-512=:mEWXIS7MaLRuGgxOBdODa3xqM1XdEvxoYhvlCFJ4\ 3538 1QJgJc4GTsPp29l5oGX69wWdXymyU0rjJuahq4l5aGgfLQ==: 3539 "content-length": 23 3540 "@signature-params": ("@status" "content-type" "content-digest" \ 3541 "content-length");created=1618884473;keyid="test-key-ecc-p256" 3543 This results in the following Signature-Input and Signature headers 3544 being added to the message under the label sig-b24: 3546 NOTE: '\' line wrapping per RFC 8792 3548 Signature-Input: sig-b24=("@status" "content-type" \ 3549 "content-digest" "content-length");created=1618884473\ 3550 ;keyid="test-key-ecc-p256" 3551 Signature: sig-b24=:wNmSUAhwb5LxtOtOpNa6W5xj067m5hFrj0XQ4fvpaCLx0NK\ 3552 ocgPquLgyahnzDnDAUy5eCdlYUEkLIj+32oiasw==: 3554 Note that the ECDSA algorithm in use here is non-deterministic, 3555 meaning a different signature value will be created every time the 3556 algorithm is run. The signature value provided here can be validated 3557 against the given keys, but newly-generated signature values are not 3558 expected to match the example. See Section 7.19. 3560 B.2.5. Signing a Request using hmac-sha256 3562 This example covers portions of the test-request using the hmac- 3563 sha256 algorithm and the secret test-shared-secret. 3565 The corresponding signature base is: 3567 NOTE: '\' line wrapping per RFC 8792 3569 "date": Tue, 20 Apr 2021 02:07:55 GMT 3570 "@authority": example.com 3571 "content-type": application/json 3572 "@signature-params": ("date" "@authority" "content-type")\ 3573 ;created=1618884473;keyid="test-shared-secret" 3575 This results in the following Signature-Input and Signature headers 3576 being added to the message under the label sig-b25: 3578 NOTE: '\' line wrapping per RFC 8792 3580 Signature-Input: sig-b25=("date" "@authority" "content-type")\ 3581 ;created=1618884473;keyid="test-shared-secret" 3582 Signature: sig-b25=:pxcQw6G3AjtMBQjwo8XzkZf/bws5LelbaMk5rGIGtE8=: 3584 Before using symmetric signatures in practice, see the discussion of 3585 the security tradeoffs in Section 7.11. 3587 B.2.6. Signing a Request using ed25519 3589 This example covers portions of the test-request using the ed25519 3590 algorithm and the key test-key-ed25519. 3592 The corresponding signature base is: 3594 NOTE: '\' line wrapping per RFC 8792 3596 "date": Tue, 20 Apr 2021 02:07:55 GMT 3597 "@method": POST 3598 "@path": /foo 3599 "@authority": example.com 3600 "content-type": application/json 3601 "content-length": 18 3602 "@signature-params": ("date" "@method" "@path" "@authority" \ 3603 "content-type" "content-length");created=1618884473\ 3604 ;keyid="test-key-ed25519" 3606 This results in the following Signature-Input and Signature headers 3607 being added to the message under the label sig-b26: 3609 NOTE: '\' line wrapping per RFC 8792 3611 Signature-Input: sig-b26=("date" "@method" "@path" "@authority" \ 3612 "content-type" "content-length");created=1618884473\ 3613 ;keyid="test-key-ed25519" 3614 Signature: sig-b26=:wqcAqbmYJ2ji2glfAMaRy4gruYYnx2nEFN2HN6jrnDnQCK1\ 3615 u02Gb04v9EDgwUPiu4A0w6vuQv5lIp5WPpBKRCw==: 3617 B.3. TLS-Terminating Proxies 3619 In this example, there is a TLS-terminating reverse proxy sitting in 3620 front of the resource. The client does not sign the request but 3621 instead uses mutual TLS to make its call. The terminating proxy 3622 validates the TLS stream and injects a Client-Cert header according 3623 to [CLIENT-CERT], and then applies a signature to this field. By 3624 signing this header field, a reverse proxy can not only attest to its 3625 own validation of the initial request's TLS parameters but also 3626 authenticate itself to the backend system independently of the 3627 client's actions. 3629 The client makes the following request to the TLS terminating proxy 3630 using mutual TLS: 3632 POST /foo?param=Value&Pet=dog HTTP/1.1 3633 Host: example.com 3634 Date: Tue, 20 Apr 2021 02:07:55 GMT 3635 Content-Type: application/json 3636 Content-Length: 18 3638 {"hello": "world"} 3639 The proxy processes the TLS connection and extracts the client's TLS 3640 certificate to a Client-Cert header field and passes it along to the 3641 internal service hosted at service.internal.example. This results in 3642 the following unsigned request: 3644 NOTE: '\' line wrapping per RFC 8792 3646 POST /foo?param=Value&Pet=dog HTTP/1.1 3647 Host: service.internal.example 3648 Date: Tue, 20 Apr 2021 02:07:55 GMT 3649 Content-Type: application/json 3650 Content-Length: 18 3651 Client-Cert: :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQKD\ 3652 BJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBDQT\ 3653 AeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDMFk\ 3654 wEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXmck\ 3655 C8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQYDV\ 3656 R0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8BAf\ 3657 8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQGV\ 3658 4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0Q6\ 3659 bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: 3661 {"hello": "world"} 3663 Without a signature, the internal service would need to trust that 3664 the incoming connection has the right information. By signing the 3665 Client-Cert header and other portions of the internal request, the 3666 internal service can be assured that the correct party, the trusted 3667 proxy, has processed the request and presented it to the correct 3668 service. The proxy's signature base consists of the following: 3670 NOTE: '\' line wrapping per RFC 8792 3672 "@path": /foo 3673 "@query": ?param=Value&Pet=dog 3674 "@method": POST 3675 "@authority": service.internal.example 3676 "client-cert": :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQ\ 3677 KDBJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBD\ 3678 QTAeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDM\ 3679 FkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXm\ 3680 ckC8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQY\ 3681 DVR0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8B\ 3682 Af8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQ\ 3683 GV4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0\ 3684 Q6bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: 3685 "@signature-params": ("@path" "@query" "@method" "@authority" \ 3686 "client-cert");created=1618884473;keyid="test-key-ecc-p256" 3688 This results in the following signature: 3690 NOTE: '\' line wrapping per RFC 8792 3692 xVMHVpawaAC/0SbHrKRs9i8I3eOs5RtTMGCWXm/9nvZzoHsIg6Mce9315T6xoklyy0y\ 3693 zhD9ah4JHRwMLOgmizw== 3695 Which results in the following signed request sent from the proxy to 3696 the internal service with the proxy's signature under the label ttrp: 3698 NOTE: '\' line wrapping per RFC 8792 3700 POST /foo?param=Value&Pet=dog HTTP/1.1 3701 Host: service.internal.example 3702 Date: Tue, 20 Apr 2021 02:07:55 GMT 3703 Content-Type: application/json 3704 Content-Length: 18 3705 Client-Cert: :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQKD\ 3706 BJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBDQT\ 3707 AeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDMFk\ 3708 wEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXmck\ 3709 C8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQYDV\ 3710 R0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8BAf\ 3711 8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQGV\ 3712 4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0Q6\ 3713 bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: 3714 Signature-Input: ttrp=("@path" "@query" "@method" "@authority" \ 3715 "client-cert");created=1618884473;keyid="test-key-ecc-p256" 3716 Signature: ttrp=:xVMHVpawaAC/0SbHrKRs9i8I3eOs5RtTMGCWXm/9nvZzoHsIg6\ 3717 Mce9315T6xoklyy0yzhD9ah4JHRwMLOgmizw==: 3719 {"hello": "world"} 3721 The internal service can validate the proxy's signature and therefore 3722 be able to trust that the client's certificate has been appropriately 3723 processed. 3725 Acknowledgements 3727 This specification was initially based on the draft-cavage-http- 3728 signatures internet draft. The editors would like to thank the 3729 authors of that draft, Mark Cavage and Manu Sporny, for their work on 3730 that draft and their continuing contributions. The specification 3731 also includes contributions from the draft-oauth-signed-http-request 3732 internet draft and other similar efforts. 3734 The editors would also like to thank the following individuals for 3735 feedback, insight, and implementation of this draft and its 3736 predecessors (in alphabetical order): Mark Adamcin, Mark Allen, Paul 3737 Annesley, Karl Böhlmark, Stéphane Bortzmeyer, Sarven Capadisli, Liam 3738 Dennehy, Stephen Farrell, Phillip Hallam-Baker, Tyler Ham, Eric 3739 Holmes, Andrey Kislyuk, Adam Knight, Dave Lehn, Dave Longley, Ilari 3740 Liusvaara, James H. Manger, Kathleen Moriarty, Mark Nottingham, Yoav 3741 Nir, Adrian Palmer, Lucas Pardue, Roberto Polli, Julian Reschke, 3742 Michael Richardson, Wojciech Rygielski, Rich Salz, Adam Scarr, Cory 3743 J. Slep, Dirk Stein, Henry Story, Lukasz Szewc, Chris Webber, and 3744 Jeffrey Yasskin. 3746 Document History 3748 _RFC EDITOR: please remove this section before publication_ 3750 * draft-ietf-httpbis-message-signatures 3752 - -10 3754 o Removed "related response" and "@request-response" in favor 3755 of generic "req" parameter. 3757 o Editorial fixes to comply with HTTP extension style 3758 guidelines. 3760 o Add security consideration on message content. 3762 - -09 3764 o Explained key formats better. 3766 o Removed "host" and "date" from most examples. 3768 o Fixed query component generation. 3770 o Renamed "signature input" and "signature input string" to 3771 "signature base". 3773 o Added consideration for semantically equivalent field 3774 values. 3776 - -08 3778 o Editorial fixes. 3780 o Changed "specialty component" to "derived component". 3782 o Expanded signature input generation and ABNF rules. 3784 o Added Ed25519 algorithm. 3786 o Clarified encoding of ECDSA signature. 3788 o Clarified use of non-deterministic algorithms. 3790 - -07 3792 o Added security and privacy considerations. 3794 o Added pointers to algorithm values from definition sections. 3796 o Expanded IANA registry sections. 3798 o Clarified that the signing and verification algorithms take 3799 application requirements as inputs. 3801 o Defined "signature targets" of request, response, and 3802 related-response for specialty components. 3804 - -06 3806 o Updated language for message components, including 3807 identifiers and values. 3809 o Clarified that Signature-Input and Signature are fields 3810 which can be used as headers or trailers. 3812 o Add "Accept-Signature" field and semantics for signature 3813 negotiation. 3815 o Define new specialty content identifiers, re-defined 3816 request-target identifier. 3818 o Added request-response binding. 3820 - -05 3822 o Remove list prefixes. 3824 o Clarify signature algorithm parameters. 3826 o Update and fix examples. 3828 o Add examples for ECC and HMAC. 3830 - -04 3832 o Moved signature component definitions up to intro. 3834 o Created formal function definitions for algorithms to 3835 fulfill. 3837 o Updated all examples. 3839 o Added nonce parameter field. 3841 - -03 3843 o Clarified signing and verification processes. 3845 o Updated algorithm and key selection method. 3847 o Clearly defined core algorithm set. 3849 o Defined JOSE signature mapping process. 3851 o Removed legacy signature methods. 3853 o Define signature parameters separately from "signature" 3854 object model. 3856 o Define serialization values for signature-input header based 3857 on signature input. 3859 - -02 3861 o Removed editorial comments on document sources. 3863 o Removed in-document issues list in favor of tracked issues. 3865 o Replaced unstructured Signature header with Signature-Input 3866 and Signature Dictionary Structured Header Fields. 3868 o Defined content identifiers for individual Dictionary 3869 members, e.g., "x-dictionary-field";key=member-name. 3871 o Defined content identifiers for first N members of a List, 3872 e.g., "x-list-field":prefix=4. 3874 o Fixed up examples. 3876 o Updated introduction now that it's adopted. 3878 o Defined specialty content identifiers and a means to extend 3879 them. 3881 o Required signature parameters to be included in signature. 3883 o Added guidance on backwards compatibility, detection, and 3884 use of signature methods. 3886 - -01 3888 o Strengthened requirement for content identifiers for header 3889 fields to be lower-case (changed from SHOULD to MUST). 3891 o Added real example values for Creation Time and Expiration 3892 Time. 3894 o Minor editorial corrections and readability improvements. 3896 - -00 3898 o Initialized from draft-richanna-http-message-signatures-00, 3899 following adoption by the working group. 3901 * draft-richanna-http-message-signatures 3903 - -00 3905 o Converted to xml2rfc v3 and reformatted to comply with RFC 3906 style guides. 3908 o Removed Signature auth-scheme definition and related 3909 content. 3911 o Removed conflicting normative requirements for use of 3912 algorithm parameter. Now MUST NOT be relied upon. 3914 o Removed Extensions appendix. 3916 o Rewrote abstract and introduction to explain context and 3917 need, and challenges inherent in signing HTTP messages. 3919 o Rewrote and heavily expanded algorithm definition, retaining 3920 normative requirements. 3922 o Added definitions for key terms, referenced RFC 7230 for 3923 HTTP terms. 3925 o Added examples for canonicalization and signature generation 3926 steps. 3928 o Rewrote Signature header definition, retaining normative 3929 requirements. 3931 o Added default values for algorithm and expires parameters. 3933 o Rewrote HTTP Signature Algorithms registry definition. 3934 Added change control policy and registry template. Removed 3935 suggested URI. 3937 o Added IANA HTTP Signature Parameter registry. 3939 o Added additional normative and informative references. 3941 o Added Topics for Working Group Discussion section, to be 3942 removed prior to publication as an RFC. 3944 Authors' Addresses 3946 Annabelle Backman (editor) 3947 Amazon 3948 P.O. Box 81226 3949 Seattle, WA 98108-1226 3950 United States of America 3951 Email: richanna@amazon.com 3952 URI: https://www.amazon.com/ 3954 Justin Richer 3955 Bespoke Engineering 3956 Email: ietf@justin.richer.org 3957 URI: https://bspk.io/ 3959 Manu Sporny 3960 Digital Bazaar 3961 203 Roanoke Street W. 3962 Blacksburg, VA 24060 3963 United States of America 3964 Email: msporny@digitalbazaar.com 3965 URI: https://manu.sporny.org/