idnits 2.17.1 draft-ietf-httpbis-message-signatures-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (8 June 2021) is 1053 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' ** Obsolete normative reference: RFC 7540 (ref. 'HTTP2') (Obsoleted by RFC 9113) ** Obsolete normative reference: RFC 7230 (ref. 'MESSAGING') (Obsoleted by RFC 9110, RFC 9112) ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Downref: Normative reference to an Informational RFC: RFC 8792 ** Obsolete normative reference: RFC 7231 (ref. 'SEMANTICS') (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 3 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: 10 December 2021 Bespoke Engineering 6 M. Sporny 7 Digital Bazaar 8 8 June 2021 10 Signing HTTP Messages 11 draft-ietf-httpbis-message-signatures-05 13 Abstract 15 This document describes a mechanism for creating, encoding, and 16 verifying digital signatures or message authentication codes over 17 content within 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. 22 Note to Readers 24 _RFC EDITOR: please remove this section before publication_ 26 Discussion of this draft takes place on the HTTP working group 27 mailing list (ietf-http-wg@w3.org), which is archived at 28 https://lists.w3.org/Archives/Public/ietf-http-wg/ 29 (https://lists.w3.org/Archives/Public/ietf-http-wg/). 31 Working Group information can be found at https://httpwg.org/ 32 (https://httpwg.org/); source code and issues list for this draft can 33 be found at https://github.com/httpwg/http-extensions/labels/ 34 signatures (https://github.com/httpwg/http-extensions/labels/ 35 signatures). 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at https://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on 10 December 2021. 54 Copyright Notice 56 Copyright (c) 2021 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 61 license-info) in effect on the date of publication of this document. 62 Please review these documents carefully, as they describe your rights 63 and restrictions with respect to this document. Code Components 64 extracted from this document must include Simplified BSD License text 65 as described in Section 4.e of the Trust Legal Provisions and are 66 provided without warranty as described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 71 1.1. Requirements Discussion . . . . . . . . . . . . . . . . . 4 72 1.2. HTTP Message Transformations . . . . . . . . . . . . . . 5 73 1.3. Safe Transformations . . . . . . . . . . . . . . . . . . 5 74 1.4. Conventions and Terminology . . . . . . . . . . . . . . . 6 75 1.5. Application of HTTP Message Signatures . . . . . . . . . 8 76 2. HTTP Message Signature Covered Content . . . . . . . . . . . 8 77 2.1. HTTP Headers . . . . . . . . . . . . . . . . . . . . . . 9 78 2.1.1. Canonicalized Structured HTTP Headers . . . . . . . . 10 79 2.1.2. Canonicalization Examples . . . . . . . . . . . . . . 10 80 2.2. Dictionary Structured Field Members . . . . . . . . . . . 11 81 2.2.1. Canonicalization Examples . . . . . . . . . . . . . . 11 82 2.3. Specialty Content Fields . . . . . . . . . . . . . . . . 11 83 2.3.1. Request Target . . . . . . . . . . . . . . . . . . . 12 84 2.3.2. Signature Parameters . . . . . . . . . . . . . . . . 13 85 2.4. Creating the Signature Input String . . . . . . . . . . . 14 86 3. HTTP Message Signatures . . . . . . . . . . . . . . . . . . . 16 87 3.1. Creating a Signature . . . . . . . . . . . . . . . . . . 17 88 3.2. Verifying a Signature . . . . . . . . . . . . . . . . . . 18 89 3.2.1. Enforcing Application Requirements . . . . . . . . . 20 90 3.3. Signature Algorithm Methods . . . . . . . . . . . . . . . 21 91 3.3.1. RSASSA-PSS using SHA-512 . . . . . . . . . . . . . . 21 92 3.3.2. RSASSA-PKCS1-v1_5 using SHA-256 . . . . . . . . . . . 22 93 3.3.3. HMAC using SHA-256 . . . . . . . . . . . . . . . . . 22 94 3.3.4. ECDSA using curve P-256 DSS and SHA-256 . . . . . . . 23 95 3.3.5. JSON Web Signature (JWS) algorithms . . . . . . . . . 23 96 4. Including a Message Signature in a Message . . . . . . . . . 23 97 4.1. The 'Signature-Input' HTTP Header . . . . . . . . . . . . 24 98 4.2. The 'Signature' HTTP Header . . . . . . . . . . . . . . . 24 99 4.3. Multiple Signatures . . . . . . . . . . . . . . . . . . . 25 100 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 101 5.1. HTTP Signature Algorithms Registry . . . . . . . . . . . 26 102 5.1.1. Registration Template . . . . . . . . . . . . . . . . 26 103 5.1.2. Initial Contents . . . . . . . . . . . . . . . . . . 27 104 5.2. HTTP Signature Metadata Parameters Registry . . . . . . . 28 105 5.2.1. Registration Template . . . . . . . . . . . . . . . . 28 106 5.2.2. Initial Contents . . . . . . . . . . . . . . . . . . 29 107 5.3. HTTP Signature Specialty Content Identifiers Registry . . 29 108 5.3.1. Registration Template . . . . . . . . . . . . . . . . 29 109 5.3.2. Initial Contents . . . . . . . . . . . . . . . . . . 29 110 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 111 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 112 7.1. Normative References . . . . . . . . . . . . . . . . . . 30 113 7.2. Informative References . . . . . . . . . . . . . . . . . 31 114 Appendix A. Detecting HTTP Message Signatures . . . . . . . . . 32 115 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 32 116 B.1. Example Keys . . . . . . . . . . . . . . . . . . . . . . 32 117 B.1.1. Example Key RSA test . . . . . . . . . . . . . . . . 33 118 B.1.2. Example RSA PSS Key . . . . . . . . . . . . . . . . . 33 119 B.1.3. Example ECC P-256 Test Key . . . . . . . . . . . . . 34 120 B.1.4. Example Shared Secret . . . . . . . . . . . . . . . . 35 121 B.2. Test Cases . . . . . . . . . . . . . . . . . . . . . . . 35 122 B.2.1. Minimal Signature Header using rsa-pss-sha512 . . . . 36 123 B.2.2. Header Coverage using rsa-pss-sha512 . . . . . . . . 36 124 B.2.3. Full Coverage using rsa-pss-sha512 . . . . . . . . . 37 125 B.2.4. Signing a Response using ecdsa-p256-sha256 . . . . . 37 126 B.2.5. Signing a Request using hmac-sha256 . . . . . . . . . 38 127 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 38 128 Document History . . . . . . . . . . . . . . . . . . . . . . . . 39 129 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 131 1. Introduction 133 Message integrity and authenticity are important security properties 134 that are critical to the secure operation of many HTTP applications. 135 Application developers typically rely on the transport layer to 136 provide these properties, by operating their application over [TLS]. 137 However, TLS only guarantees these properties over a single TLS 138 connection, and the path between client and application may be 139 composed of multiple independent TLS connections (for example, if the 140 application is hosted behind a TLS-terminating gateway or if the 141 client is behind a TLS Inspection appliance). In such cases, TLS 142 cannot guarantee end-to-end message integrity or authenticity between 143 the client and application. Additionally, some operating 144 environments present obstacles that make it impractical to use TLS, 145 or to use features necessary to provide message authenticity. 146 Furthermore, some applications require the binding of an application- 147 level key to the HTTP message, separate from any TLS certificates in 148 use. Consequently, while TLS can meet message integrity and 149 authenticity needs for many HTTP-based applications, it is not a 150 universal solution. 152 This document defines a mechanism for providing end-to-end integrity 153 and authenticity for content within an HTTP message. The mechanism 154 allows applications to create digital signatures or message 155 authentication codes (MACs) over only that content within the message 156 that is meaningful and appropriate for the application. Strict 157 canonicalization rules ensure that the verifier can verify the 158 signature even if the message has been transformed in any of the many 159 ways permitted by HTTP. 161 The mechanism described in this document consists of three parts: 163 * A common nomenclature and canonicalization rule set for the 164 different protocol elements and other content within HTTP 165 messages. 167 * Algorithms for generating and verifying signatures over HTTP 168 message content using this nomenclature and rule set. 170 * A mechanism for attaching a signature and related metadata to an 171 HTTP message. 173 1.1. Requirements Discussion 175 HTTP permits and sometimes requires intermediaries to transform 176 messages in a variety of ways. This may result in a recipient 177 receiving a message that is not bitwise equivalent to the message 178 that was originally sent. In such a case, the recipient will be 179 unable to verify a signature over the raw bytes of the sender's HTTP 180 message, as verifying digital signatures or MACs requires both signer 181 and verifier to have the exact same signed content. Since the raw 182 bytes of the message cannot be relied upon as signed content, the 183 signer and verifier must derive the signed content from their 184 respective versions of the message, via a mechanism that is resilient 185 to safe changes that do not alter the meaning of the message. 187 For a variety of reasons, it is impractical to strictly define what 188 constitutes a safe change versus an unsafe one. Applications use 189 HTTP in a wide variety of ways, and may disagree on whether a 190 particular piece of information in a message (e.g., the body, or the 191 "Date" header field) is relevant. Thus a general purpose solution 192 must provide signers with some degree of control over which message 193 content is signed. 195 HTTP applications may be running in environments that do not provide 196 complete access to or control over HTTP messages (such as a web 197 browser's JavaScript environment), or may be using libraries that 198 abstract away the details of the protocol (such as the Java 199 HTTPClient library (https://openjdk.java.net/groups/net/httpclient/ 200 intro.html)). These applications need to be able to generate and 201 verify signatures despite incomplete knowledge of the HTTP message. 203 1.2. HTTP Message Transformations 205 As mentioned earlier, HTTP explicitly permits and in some cases 206 requires implementations to transform messages in a variety of ways. 207 Implementations are required to tolerate many of these 208 transformations. What follows is a non-normative and non-exhaustive 209 list of transformations that may occur under HTTP, provided as 210 context: 212 * Re-ordering of header fields with different header field names 213 ([MESSAGING], Section 3.2.2). 215 * Combination of header fields with the same field name 216 ([MESSAGING], Section 3.2.2). 218 * Removal of header fields listed in the "Connection" header field 219 ([MESSAGING], Section 6.1). 221 * Addition of header fields that indicate control options 222 ([MESSAGING], Section 6.1). 224 * Addition or removal of a transfer coding ([MESSAGING], 225 Section 5.7.2). 227 * Addition of header fields such as "Via" ([MESSAGING], 228 Section 5.7.1) and "Forwarded" ([RFC7239], Section 4). 230 1.3. Safe Transformations 232 Based on the definition of HTTP and the requirements described above, 233 we can identify certain types of transformations that should not 234 prevent signature verification, even when performed on content 235 covered by the signature. The following list describes those 236 transformations: 238 * Combination of header fields with the same field name. 240 * Reordering of header fields with different names. 242 * Conversion between different versions of the HTTP protocol (e.g., 243 HTTP/1.x to HTTP/2, or vice-versa). 245 * Changes in casing (e.g., "Origin" to "origin") of any case- 246 insensitive content such as header field names, request URI 247 scheme, or host. 249 * Addition or removal of leading or trailing whitespace to a header 250 field value. 252 * Addition or removal of "obs-folds". 254 * Changes to the "request-target" and "Host" header field that when 255 applied together do not result in a change to the message's 256 effective request URI, as defined in Section 5.5 of [MESSAGING]. 258 Additionally, all changes to content not covered by the signature are 259 considered safe. 261 1.4. Conventions and Terminology 263 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 264 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 265 "OPTIONAL" in this document are to be interpreted as described in 266 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 267 capitals, as shown here. 269 The terms "HTTP message", "HTTP request", "HTTP response", "absolute- 270 form", "absolute-path", "effective request URI", "gateway", "header 271 field", "intermediary", "request-target", "sender", and "recipient" 272 are used as defined in [MESSAGING]. 274 The term "method" is to be interpreted as defined in Section 4 of 275 [SEMANTICS]. 277 For brevity, the term "signature" on its own is used in this document 278 to refer to both digital signatures and keyed MACs. Similarly, the 279 verb "sign" refers to the generation of either a digital signature or 280 keyed MAC over a given input string. The qualified term "digital 281 signature" refers specifically to the output of an asymmetric 282 cryptographic signing operation. 284 In addition to those listed above, this document uses the following 285 terms: 287 Signer: 289 The entity that is generating or has generated an HTTP Message 290 Signature. 292 Verifier: 293 An entity that is verifying or has verified an HTTP Message 294 Signature against an HTTP Message. Note that an HTTP Message 295 Signature may be verified multiple times, potentially by different 296 entities. 298 Covered Content: 299 An ordered list of content identifiers for headers (Section 2.1) 300 and specialty content (Section 2.3) that indicates the metadata 301 and message content that is covered by the signature, not 302 including the "@signature-params" specialty field itself. 304 HTTP Signature Algorithm: 305 A cryptographic algorithm that describes the signing and 306 verification process for the signature. When expressed 307 explicitly, the value maps to a string defined in the HTTP 308 Signature Algorithms Registry defined in this document. 310 Key Material: 311 The key material required to create or verify the signature. The 312 key material is often identified with an explicit key identifier, 313 allowing the signer to indicate to the verifier which key was 314 used. 316 Creation Time: 317 A timestamp representing the point in time that the signature was 318 generated, as asserted by the signer. 320 Expiration Time: 321 A timestamp representing the point in time at which the signature 322 expires, as asserted by the signer. A signature's expiration time 323 could be undefined, indicating that the signature does not expire 324 from the perspective of the signer. 326 The term "Unix time" is defined by [POSIX.1], Section 4.16 327 (http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ 328 V1_chap04.html#tag_04_16). 330 This document contains non-normative examples of partial and complete 331 HTTP messages. Some examples use a single trailing backslash '' to 332 indicate line wrapping for long values, as per [RFC8792]. The "\" 333 character and leading spaces on wrapped lines are not part of the 334 value. 336 1.5. Application of HTTP Message Signatures 338 HTTP Message Signatures are designed to be a general-purpose security 339 mechanism applicable in a wide variety of circumstances and 340 applications. In order to properly and safely apply HTTP Message 341 Signatures, an application or profile of this specification MUST 342 specify all of the following items: 344 * The set of content identifiers (Section 2) that are expected and 345 required. For example, an authorization protocol could mandate 346 that the "Authorization" header be covered to protect the 347 authorization credentials and mandate the signature parameters 348 contain a "created" parameter, while an API expecting HTTP message 349 bodies could require the "Digest" header to be present and 350 covered. 352 * A means of retrieving the key material used to verify the 353 signature. An application will usually use the "keyid" parameter 354 of the signature parameters (Section 2.3.2) and define rules for 355 resolving a key from there, though the appropriate key could be 356 known from other means. 358 * A means of determining the signature algorithm used to verify the 359 signature content is appropriate for the key material. For 360 example, the process could use the "alg" parameter of the 361 signature parameters (Section 2.3.2) to state the algorithm 362 explicitly, derive the algorithm from the key material, or use 363 some pre-configured algorithm agreed upon by the signer and 364 verifier. 366 * A means of determining that a given key and algorithm presented in 367 the request are appropriate for the request being made. For 368 example, a server expecting only ECDSA signatures should know to 369 reject any RSA signatures, or a server expecting asymmetric 370 cryptography should know to reject any symmetric cryptography. 372 The details of this kind of profiling are the purview of the 373 application and outside the scope of this specification. 375 2. HTTP Message Signature Covered Content 377 In order to allow signers and verifiers to establish which content is 378 covered by a signature, this document defines content identifiers for 379 data items covered by an HTTP Message Signature as well as the means 380 for combining these canonicalized values into a signature input 381 string. 383 Some content within HTTP messages can undergo transformations that 384 change the bitwise value without altering meaning of the content (for 385 example, the merging together of header fields with the same name). 386 Message content must therefore be canonicalized before it is signed, 387 to ensure that a signature can be verified despite such intermediary 388 transformations. This document defines rules for each content 389 identifier that transform the identifier's associated content into 390 such a canonical form. 392 Content identifiers are defined using production grammar defined by 393 RFC8941, Section 4 [RFC8941]. The content identifier is an "sf- 394 string" value. The content identifier type MAY define parameters 395 which are included using the "parameters" rule. 397 content-identifier = sf-string parameters 399 Note that this means the value of the identifier itself is encased in 400 double quotes, with parameters following as a semicolon-separated 401 list, such as ""cache-control"", ""date"", or ""@signature-params"". 403 The following sections define content identifier types, their 404 parameters, their associated content, and their canonicalization 405 rules. The method for combining content identifiers into the 406 signature input string is defined in Section 2.4. 408 2.1. HTTP Headers 410 The content identifier for an HTTP header is the lowercased form of 411 its header field name. While HTTP header field names are case- 412 insensitive, implementations MUST use lowercased field names (e.g., 413 "content-type", "date", "etag") when using them as content 414 identifiers. 416 Unless overridden by additional parameters and rules, the HTTP header 417 field value MUST be canonicalized with the following steps: 419 1. Create an ordered list of the field values of each instance of 420 the header field in the message, in the order that they occur (or 421 will occur) in the message. 423 2. Strip leading and trailing whitespace from each item in the list. 425 3. Concatenate the list items together, with a comma "," and space " 426 " between each item. 428 The resulting string is the canonicalized value. 430 2.1.1. Canonicalized Structured HTTP Headers 432 If value of the the HTTP header in question is a structured field 433 ([RFC8941]), the content identifier MAY include the "sf" parameter. 434 If this parameter is included, the HTTP header value MUST be 435 canonicalized using the rules specified in Section 4 of RFC8941 436 [RFC8941]. Note that this process will replace any optional 437 whitespace with a single space. 439 The resulting string is used as the field value input in Section 2.1. 441 2.1.2. Canonicalization Examples 443 This section contains non-normative examples of canonicalized values 444 for header fields, given the following example HTTP message: 446 Server: www.example.com 447 Date: Tue, 07 Jun 2014 20:51:35 GMT 448 X-OWS-Header: Leading and trailing whitespace. 449 X-Obs-Fold-Header: Obsolete 450 line folding. 451 X-Empty-Header: 452 Cache-Control: max-age=60 453 Cache-Control: must-revalidate 455 The following table shows example canonicalized values for header 456 fields, given that message: 458 +=====================+==================================+ 459 | Header Field | Canonicalized Value | 460 +=====================+==================================+ 461 | "cache-control" | max-age=60, must-revalidate | 462 +---------------------+----------------------------------+ 463 | "date" | Tue, 07 Jun 2014 20:51:35 GMT | 464 +---------------------+----------------------------------+ 465 | "server" | www.example.com | 466 +---------------------+----------------------------------+ 467 | "x-empty-header" | | 468 +---------------------+----------------------------------+ 469 | "x-obs-fold-header" | Obsolete line folding. | 470 +---------------------+----------------------------------+ 471 | "x-ows-header" | Leading and trailing whitespace. | 472 +---------------------+----------------------------------+ 474 Table 1: Non-normative examples of header field 475 canonicalization. 477 2.2. Dictionary Structured Field Members 479 An individual member in the value of a Dictionary Structured Field is 480 identified by using the parameter "key" on the content identifier for 481 the header. The value of this parameter is a the key being 482 identified, without any parameters present on that key in the 483 original dictionary. 485 An individual member in the value of a Dictionary Structured Field is 486 canonicalized by applying the serialization algorithm described in 487 Section 4.1.2 of RFC8941 [RFC8941] on a Dictionary containing only 488 that member. 490 2.2.1. Canonicalization Examples 492 This section contains non-normative examples of canonicalized values 493 for Dictionary Structured Field Members given the following example 494 header field, whose value is assumed to be a Dictionary: 496 X-Dictionary: a=1, b=2;x=1;y=2, c=(a b c) 498 The following table shows example canonicalized values for different 499 content identifiers, given that field: 501 +======================+=====================+ 502 | Content Identifier | Canonicalized Value | 503 +======================+=====================+ 504 | "x-dictionary";key=a | 1 | 505 +----------------------+---------------------+ 506 | "x-dictionary";key=b | 2;x=1;y=2 | 507 +----------------------+---------------------+ 508 | "x-dictionary";key=c | (a, b, c) | 509 +----------------------+---------------------+ 511 Table 2: Non-normative examples of 512 Dictionary member canonicalization. 514 2.3. Specialty Content Fields 516 Content not found in an HTTP header can be included in the signature 517 base string by defining a content identifier and the canonicalization 518 method for its content. 520 To differentiate specialty content identifiers from HTTP headers, 521 specialty content identifiers MUST start with the "at" "@" character. 522 This specification defines the following specialty content 523 identifiers: 525 @request-target The target request endpoint. (Section 2.3.1) 527 @signature-params The signature metadata parameters for this 528 signature. (Section 2.3.2) 530 Additional specialty content identifiers MAY be defined and 531 registered in the HTTP Signatures Specialty Content Identifier 532 Registry. (Section 5.3) 534 2.3.1. Request Target 536 The request target endpoint, consisting of the request method and the 537 path and query of the effective request URI, is identified by the 538 "@request-target" identifier. 540 Its value is canonicalized as follows: 542 1. Take the lowercased HTTP method of the message. 544 2. Append a space " ". 546 3. Append the path and query of the request target of the message, 547 formatted according to the rules defined for the :path pseudo- 548 header in [HTTP2], Section 8.1.2.3. The resulting string is the 549 canonicalized value. 551 2.3.1.1. Canonicalization Examples 553 The following table contains non-normative example HTTP messages and 554 their canonicalized "@request-target" values. 556 +=========================+=================+ 557 |HTTP Message | @request-target | 558 +=========================+=================+ 559 | POST /?param=value HTTP/1.1| post | 560 | Host: www.example.com | /?param=value | 561 +-------------------------+-----------------+ 562 | POST /a/b HTTP/1.1 | post /a/b | 563 | Host: www.example.com | | 564 +-------------------------+-----------------+ 565 | GET http://www.example.com/a/ HTTP/1.1| get /a/ | 566 +-------------------------+-----------------+ 567 | GET http://www.example.com HTTP/1.1| get / | 568 +-------------------------+-----------------+ 569 | CONNECT server.example.com:80 HTTP/1.1| connect / | 570 | Host: server.example.com| | 571 +-------------------------+-----------------+ 572 | OPTIONS * HTTP/1.1 | options * | 573 | Host: server.example.com| | 574 +-------------------------+-----------------+ 576 Table 3: Non-normative examples of "@request-target" 577 canonicalization. 579 2.3.2. Signature Parameters 581 HTTP Message Signatures have metadata properties that provide 582 information regarding the signature's generation and/or verification. 584 The signature parameters specialty content is identified by the 585 "@signature-params" identifier. 587 Its canonicalized value is the serialization of the signature 588 parameters for this signature, including the covered content list 589 with all associated parameters. 591 * "alg": The HTTP message signature algorithm from the HTTP Message 592 Signature Algorithm Registry, as an "sf-string" value. 594 * "keyid": The identifier for the key material as an "sf-string" 595 value. 597 * "created": Creation time as an "sf-integer" UNIX timestamp value. 598 Sub-second precision is not supported. 600 * "expires": Expiration time as an "sf-integer" UNIX timestamp 601 value. Sub-second precision is not supported. 603 * "nonce": A random unique value generated for this signature. 605 Additional parameters can be defined in the HTTP Signature Parameters 606 Registry (Section 5.2.2). 608 The signature parameters are serialized using the rules in Section 4 609 of RFC8941 [RFC8941] as follows: 611 1. Let the output be an empty string. 613 2. Determine an order for the content identifiers of the covered 614 content. Once this order is chosen, it cannot be changed. 616 3. Serialize the content identifiers of the covered content, 617 including all parameters, as an ordered "inner-list" according to 618 Section 4.1.1.1 of RFC8941 [RFC8941] and append this to the 619 output. 621 4. Determine an order for any signature parameters. Once this order 622 is chosen, it cannot be changed. 624 5. Append the parameters to the "inner-list" in the chosen order 625 according to Section 4.1.1.2 of RFC8941 [RFC8941], skipping 626 parameters that are not available or not used for this signature. 628 6. The output contains the signature parameters value. 630 Note that the "inner-list" serialization is used for the covered 631 content value instead of the "sf-list" serialization in order to 632 facilitate this value's additional inclusion in the "Signature-Input" 633 header's dictionary, as discussed in Section 4.1. 635 This example shows a canonicalized value for the parameters of a 636 given signature: 638 ("@request-target" "host" "date" "cache-control" "x-empty-header" \ 639 "x-example");keyid="test-key-rsa-pss";alg="rsa-pss-sha512";\ 640 created=1618884475;expires=1618884775 642 Note that an HTTP message could contain multiple signatures, but only 643 the signature parameters used for the current signature are included 644 in this field. 646 2.4. Creating the Signature Input String 648 The signature input is a US-ASCII string containing the content that 649 is covered by the signature. To create the signature input string, 650 the signer or verifier concatenates together entries for each 651 identifier in the signature's covered content and parameters using 652 the following algorithm: 654 1. Let the output be an empty string. 656 2. For each covered content item in the covered content list (in 657 order): 659 1. Append the identifier for the covered content serialized 660 according to the "content-identifier" rule. 662 2. Append a single colon "":"" 664 3. Append a single space "" "" 666 4. Append the covered content's canonicalized value, as defined 667 by the covered content type. (Section 2.1 and Section 2.3) 669 5. Append a single newline ""\\n"" 671 3. Append the signature parameters (Section 2.3.2) as follows: 673 1. Append the identifier for the signature parameters serialized 674 according to the "content-identifier" rule, ""@signature- 675 params"" 677 2. Append a single colon "":"" 679 3. Append a single space "" "" 681 4. Append the signature parameters' canonicalized value as 682 defined in Section 2.3.2 684 4. Return the output string. 686 If covered content references an identifier that cannot be resolved 687 to a value in the message, the implementation MUST produce an error. 688 Such situations are included but not limited to: 690 * The signer or verifier does not understand the content identifier. 692 * The identifier identifies a header field that is not present in 693 the message or whose value is malformed. 695 * The identifier is a Dictionary member identifier that references a 696 header field that is not present in the message, is not a 697 Dictionary Structured Field, or whose value is malformed. 699 * The identifier is a Dictionary member identifier that references a 700 member that is not present in the header field value, or whose 701 value is malformed. E.g., the identifier is 702 ""x-dictionary";key="c"" and the value of the "x-dictionary" 703 header field is "a=1, b=2" 705 In the following non-normative example, the HTTP message being signed 706 is the following request: 708 GET /foo HTTP/1.1 709 Host: example.org 710 Date: Tue, 20 Apr 2021 02:07:55 GMT 711 X-Example: Example header 712 with some whitespace. 713 X-Empty-Header: 714 Cache-Control: max-age=60 715 Cache-Control: must-revalidate 717 The covered content consists of the "@request-target" specialty 718 content followed by the "Host", "Date", "Cache-Control", "X-Empty- 719 Header", "X-Example" HTTP headers, in order. The signature creation 720 timestamp is "1618884475" and the key identifier is "test-key-rsa- 721 pss". The signature input string for this message with these 722 parameters is: 724 "@request-target": get /foo 725 "host": example.org 726 "date": Tue, 20 Apr 2021 02:07:55 GMT 727 "cache-control": max-age=60, must-revalidate 728 "x-empty-header": 729 "x-example": Example header with some whitespace. 730 "@signature-params": ("@request-target" "host" "date" "cache-control" \ 731 "x-empty-header" "x-example");created=1618884475;\ 732 keyid="test-key-rsa-pss" 734 Figure 1: Non-normative example Signature Input 736 3. HTTP Message Signatures 738 An HTTP Message Signature is a signature over a string generated from 739 a subset of the content in an HTTP message and metadata about the 740 signature itself. When successfully verified against an HTTP 741 message, it provides cryptographic proof that with respect to the 742 subset of content that was signed, the message is semantically 743 equivalent to the message for which the signature was generated. 745 3.1. Creating a Signature 747 In order to create a signature, a signer MUST follow the following 748 algorithm: 750 1. The signer chooses an HTTP signature algorithm and key material 751 for signing. The signer MUST choose key material that is 752 appropriate for the signature's algorithm, and that conforms to 753 any requirements defined by the algorithm, such as key size or 754 format. The mechanism by which the signer chooses the algorithm 755 and key material is out of scope for this document. 757 2. The signer sets the signature's creation time to the current 758 time. 760 3. If applicable, the signer sets the signature's expiration time 761 property to the time at which the signature is to expire. 763 4. The signer creates an ordered list of content identifiers 764 representing the message content and signature metadata to be 765 covered by the signature, and assigns this list as the 766 signature's Covered Content. 768 * Once an order of covered content is chosen, the order MUST NOT 769 change for the life of the signature. 771 * Each covered content identifier MUST either reference an HTTP 772 header in the request message Section 2.1 or reference a 773 specialty content field listed in Section 2.3 or its 774 associated registry. 776 * Signers SHOULD include "@request-target" in the covered 777 content list. 779 * Signers SHOULD include a date stamp in some form, such as 780 using the "date" header. Alternatively, the "created" 781 signature metadata parameter can fulfil this role. 783 * Further guidance on what to include in this list and in what 784 order is out of scope for this document. However, note that 785 the list order is significant and once established for a given 786 signature it MUST be preserved for that signature. 788 * Note that the "@signature-params" specialty identifier is not 789 explicitly listed in the list of covered content identifiers, 790 because it is required to always be present as the last line 791 in the signature input. This ensures that a signature always 792 covers its own metadata. 794 5. The signer creates the signature input string. (Section 2.4) 796 6. The signer signs the signature input with the chosen signing 797 algorithm using the key material chosen by the signer. Several 798 signing algorithms are defined in in Section 3.3. 800 7. The byte array output of the signature function is the HTTP 801 message signature output value to be included in the "Signature" 802 header as defined in Section 4.2. 804 For example, given the HTTP message and signature parameters in the 805 example in Section 2.4, the example signature input string when 806 signed with the "test-key-rsa-pss" key in Appendix B.1.2 gives the 807 following message signature output value, encoded in Base64: 809 lPxkxqDEPhgrx1yPaKLO7eJ+oPjSwsQ5NjWNRfYP7Jw0FwnK1k8/GH7g5s2q0VTTKVm\ 810 xyfpUDp/HsDphh5Z7Fa/lvtujHyFe/0EP9z7bnVb7YBZrxV52LGvP8p4APhOYuG4yaH\ 811 z478GsJav9BQYK0B2IOHdLFJe8qwWPJs07J47gPewpNwCt0To/zZ2KPpylGX5UHVgJP\ 812 Uom64KjX43u2OwIvSoPEYk4nuBvLR9yxYAHURaTfLoEDUCtY1FsU1hOfG3jAlcT6ill\ 813 fnyS72PEdSSzw1KsxroMj9IYpFhva77YxmJRk4pCIW0F0Kj0ukl7J4y2aZJHMCYI3g8\ 814 yfqh/wQ== 816 Figure 2: Non-normative example signature value 818 3.2. Verifying a Signature 820 A verifier processes a signature and its associated signature input 821 parameters in concert with each other. 823 In order to verify a signature, a verifier MUST follow the following 824 algorithm: 826 1. Parse the "Signature" and "Signature-Input" headers and extract 827 the signatures to be verified. 829 1. If there is more than one signature value present, determine 830 which signature should be processed for this request. If an 831 appropriate signature is not found, produce an error. 833 2. If the chosen "Signature" value does not have a corresponding 834 "Signature-Input" value, produce an error. 836 2. Parse the values of the chosen "Signature-Input" header field to 837 get the parameters for the signature to be verified. 839 3. Parse the value of the corresponding "Signature" header field to 840 get the byte array value of the signature to be verified. 842 4. Examine the signature parameters to confirm that the signature 843 meets the requirements described in this document, as well as any 844 additional requirements defined by the application such as which 845 contents are required to be covered by the signature. 846 (Section 3.2.1) 848 5. Determine the verification key material for this signature. If 849 the key material is known through external means such as static 850 configuration or external protocol negotiation, the verifier will 851 use that. If the key is identified in the signature parameters, 852 the verifier will dereference this to appropriate key material to 853 use with the signature. The verifier has to determine the 854 trustworthiness of the key material for the context in which the 855 signature is presented. If a key is identified that the verifier 856 does not know, does not trust for this request, or does not match 857 something preconfigured, the verification MUST fail. 859 6. Determine the algorithm to apply for verification: 861 1. If the algorithm is known through external means such as 862 static configuration or external protocol negotiation, the 863 verifier will use this algorithm. 865 2. If the algorithm is explicitly stated in the signature 866 parameters using a value from the HTTP Message Signatures 867 registry, the verifier will use the referenced algorithm. 869 3. If the algorithm can be determined from the keying material, 870 such as through an algorithm field on the key value itself, 871 the verifier will use this algorithm. 873 4. If the algorithm is specified in more that one location, such 874 as through static configuration and the algorithm signature 875 parameter, or the algorithm signature parameter and from the 876 key material itself, the resolved algorithms MUST be the 877 same. If the algorithms are not the same, the verifier MUST 878 vail the verification. 880 7. Use the received HTTP message and the signature's metadata to 881 recreate the signature input, using the process described in 882 Section 2.4. The value of the "@signature-params" input is the 883 value of the SignatureInput header field for this signature 884 serialized according to the rules described in Section 2.3.2, not 885 including the signature's label from the "Signature-Input" 886 header. 888 8. If the key material is appropriate for the algorithm, apply the 889 verification algorithm to the signature, recalculated signature 890 input, signature parameters, key material, and algorithm. 891 Several algorithms are defined in Section 3.3. 893 9. The results of the verification algorithm function are the final 894 results of the signature verification. 896 If any of the above steps fail, the signature validation fails. 898 3.2.1. Enforcing Application Requirements 900 The verification requirements specified in this document are intended 901 as a baseline set of restrictions that are generally applicable to 902 all use cases. Applications using HTTP Message Signatures MAY impose 903 requirements above and beyond those specified by this document, as 904 appropriate for their use case. 906 Some non-normative examples of additional requirements an application 907 might define are: 909 * Requiring a specific set of header fields to be signed (e.g., 910 Authorization, Digest). 912 * Enforcing a maximum signature age. 914 * Prohibiting the use of certain algorithms, or mandating the use of 915 an algorithm. 917 * Requiring keys to be of a certain size (e.g., 2048 bits vs. 1024 918 bits). 920 * Enforcing uniqueness of a nonce value. 922 Application-specific requirements are expected and encouraged. When 923 an application defines additional requirements, it MUST enforce them 924 during the signature verification process, and signature verification 925 MUST fail if the signature does not conform to the application's 926 requirements. 928 Applications MUST enforce the requirements defined in this document. 929 Regardless of use case, applications MUST NOT accept signatures that 930 do not conform to these requirements. 932 3.3. Signature Algorithm Methods 934 HTTP Message signatures MAY use any cryptographic digital signature 935 or MAC method that is appropriate for the key material, environment, 936 and needs of the signer and verifier. All signatures are generated 937 from and verified against the byte values of the signature input 938 string defined in Section 2.4. 940 Each signature algorithm method takes as its input the signature 941 input string as a set of byte values ("I"), the signing key material 942 ("Ks"), and outputs the signed content as a set of byte values ("S"): 944 HTTP_SIGN (I, Ks) -> S 946 Each verification algorithm method takes as its input the 947 recalculated signature input string as a set of byte values ("I"), 948 the verification key material ("Kv"), and the presented signature to 949 be verified as a set of byte values ("S") and outputs the 950 verification result ("V") as a boolean: 952 HTTP_VERIFY (I, Kv, S) -> V 954 This section contains several common algorithm methods. The method 955 to use can be communicated through the algorithm signature parameter 956 defined in Section 2.3.2, by reference to the key material, or 957 through mutual agreement between the signer and verifier. 959 3.3.1. RSASSA-PSS using SHA-512 961 To sign using this algorithm, the signer applies the "RSASSA-PSS-SIGN 962 (K, M)" function [RFC8017] with the signer's private signing key 963 ("K") and the signature input string ("M") (Section 2.4). The mask 964 generation function is "MGF1" as specified in [RFC8017] with a hash 965 function of SHA-512 [RFC6234]. The salt length ("sLen") is 64 bytes. 966 The hash function ("Hash") SHA-512 [RFC6234] is applied to the 967 signature input string to create the digest content to which the 968 digital signature is applied. The resulting signed content byte 969 array ("S") is the HTTP message signature output used in Section 3.1. 971 To verify using this algorithm, the verifier applies the "RSASSA-PSS- 972 VERIFY ((n, e), M, S)" function [RFC8017] using the public key 973 portion of the verification key material ("(n, e)") and the signature 974 input string ("M") re-created as described in Section 3.2. The mask 975 generation function is "MGF1" as specified in [RFC8017] with a hash 976 function of SHA-512 [RFC6234]. The salt length ("sLen") is 64 bytes. 977 The hash function ("Hash") SHA-512 [RFC6234] is applied to the 978 signature input string to create the digest content to which the 979 verification function is applied. The verifier extracts the HTTP 980 message signature to be verified ("S") as described in Section 3.2. 981 The results of the verification function are compared to the http 982 message signature to determine if the signature presented is valid. 984 3.3.2. RSASSA-PKCS1-v1_5 using SHA-256 986 To sign using this algorithm, the signer applies the "RSASSA- 987 PKCS1-V1_5-SIGN (K, M)" function [RFC8017] with the signer's private 988 signing key ("K") and the signature input string ("M") (Section 2.4). 989 The hash SHA-256 [RFC6234] is applied to the signature input string 990 to create the digest content to which the digital signature is 991 applied. The resulting signed content byte array ("S") is the HTTP 992 message signature output used in Section 3.1. 994 To verify using this algorithm, the verifier applies the "RSASSA- 995 PKCS1-V1_5-VERIFY ((n, e), M, S)" function [RFC8017] using the public 996 key portion of the verification key material ("(n, e)") and the 997 signature input string ("M") re-created as described in Section 3.2. 998 The hash function SHA-256 [RFC6234] is applied to the signature input 999 string to create the digest content to which the verification 1000 function is applied. The verifier extracts the HTTP message 1001 signature to be verified ("S") as described in Section 3.2. The 1002 results of the verification function are compared to the http message 1003 signature to determine if the signature presented is valid. 1005 3.3.3. HMAC using SHA-256 1007 To sign and verify using this algorithm, the signer applies the 1008 "HMAC" function [RFC2104] with the shared signing key ("K") and the 1009 signature input string ("text") (Section 2.4). The hash function 1010 SHA-256 [RFC6234] is applied to the signature input string to create 1011 the digest content to which the HMAC is applied, giving the signature 1012 result. 1014 For signing, the resulting value is the HTTP message signature output 1015 used in Section 3.1. 1017 For verification, the verifier extracts the HTTP message signature to 1018 be verified ("S") as described in Section 3.2. The output of the 1019 HMAC function is compared to the value of the HTTP message signature, 1020 and the results of the comparison determine the validity of the 1021 signature presented. 1023 3.3.4. ECDSA using curve P-256 DSS and SHA-256 1025 To sign using this algorithm, the signer applies the "ECDSA" 1026 algorithm [FIPS186-4] using curve P-256 with the signer's private 1027 signing key and the signature input string (Section 2.4). The hash 1028 SHA-256 [RFC6234] is applied to the signature input string to create 1029 the digest content to which the digital signature is applied. The 1030 resulting signed content byte array is the HTTP message signature 1031 output used in Section 3.1. 1033 To verify using this algorithm, the verifier applies the "ECDSA" 1034 algorithm [FIPS186-4] using the public key portion of the 1035 verification key material and the signature input string re-created 1036 as described in Section 3.2. The hash function SHA-256 [RFC6234] is 1037 applied to the signature input string to create the digest content to 1038 which the verification function is applied. The verifier extracts 1039 the HTTP message signature to be verified ("S") as described in 1040 Section 3.2. The results of the verification function are compared 1041 to the http message signature to determine if the signature presented 1042 is valid. 1044 3.3.5. JSON Web Signature (JWS) algorithms 1046 If the signing algorithm is a JOSE signing algorithm from the JSON 1047 Web Signature and Encryption Algorithms Registry established by 1048 [RFC7518], the JWS algorithm definition determines the signature and 1049 hashing algorithms to apply for both signing and verification. There 1050 is no use of the explicit "alg" signature parameter when using JOSE 1051 signing algorithms. 1053 For both signing and verification, the HTTP messages signature input 1054 string (Section 2.4) is used as the entire "JWS Signing Input". The 1055 JOSE Header defined in [RFC7517] is not used, and the signature input 1056 string is not first encoded in Base64 before applying the algorithm. 1057 The output of the JWS signature is taken as a byte array prior to the 1058 Base64url encoding used in JOSE. 1060 The JWS algorithm MUST NOT be "none" and MUST NOT be any algorithm 1061 with a JOSE Implementation Requirement of "Prohibited". 1063 4. Including a Message Signature in a Message 1065 Message signatures can be included within an HTTP message via the 1066 "Signature-Input" and "Signature" HTTP header fields, both defined 1067 within this specification. 1069 An HTTP message signature MUST use both headers: the "Signature" HTTP 1070 header field contains the signature value, while the "Signature- 1071 Input" HTTP header field identifies the covered content and 1072 parameters that describe how the signature was generated. Each 1073 header MAY contain multiple labeled values, where the labels 1074 determine the correlation between the "Signature" and "Signature- 1075 Input" fields. 1077 4.1. The 'Signature-Input' HTTP Header 1079 The "Signature-Input" HTTP header field is a Dictionary Structured 1080 Header [RFC8941] containing the metadata for one or more message 1081 signatures generated from content within the HTTP message. Each 1082 member describes a single message signature. The member's name is an 1083 identifier that uniquely identifies the message signature within the 1084 context of the HTTP message. The member's value is the serialization 1085 of the covered content including all signature metadata parameters, 1086 using the serialization process defined in Section 2.3.2. 1088 Signature-Input: sig1=("@request-target" "host" "date" \ 1089 "cache-control" "x-empty-header" "x-example");created=1618884475\ 1090 ;keyid="test-key-rsa-pss" 1092 To facilitate signature validation, the "Signature-Input" header 1093 value MUST contain the same serialized value used in generating the 1094 signature input string's "@signature-params" value. 1096 4.2. The 'Signature' HTTP Header 1098 The "Signature" HTTP header field is a Dictionary Structured Header 1099 [RFC8941] containing one or more message signatures generated from 1100 content within the HTTP message. Each member's name is a signature 1101 identifier that is present as a member name in the "Signature-Input" 1102 Structured Header within the HTTP message. Each member's value is a 1103 Byte Sequence containing the signature value for the message 1104 signature identified by the member name. Any member in the 1105 "Signature" HTTP header field that does not have a corresponding 1106 member in the HTTP message's "Signature-Input" HTTP header field MUST 1107 be ignored. 1109 Signature: sig1=:lPxkxqDEPhgrx1yPaKLO7eJ+oPjSwsQ5NjWNRfYP7Jw0FwnK1k\ 1110 8/GH7g5s2q0VTTKVmxyfpUDp/HsDphh5Z7Fa/lvtujHyFe/0EP9z7bnVb7YBZrxV5\ 1111 2LGvP8p4APhOYuG4yaHz478GsJav9BQYK0B2IOHdLFJe8qwWPJs07J47gPewpNwCt\ 1112 0To/zZ2KPpylGX5UHVgJPUom64KjX43u2OwIvSoPEYk4nuBvLR9yxYAHURaTfLoED\ 1113 UCtY1FsU1hOfG3jAlcT6illfnyS72PEdSSzw1KsxroMj9IYpFhva77YxmJRk4pCIW\ 1114 0F0Kj0ukl7J4y2aZJHMCYI3g8yfqh/wQ==: 1116 4.3. Multiple Signatures 1118 Since "Signature-Input" and "Signature" are both defined as 1119 Dictionary Structured Headers, they can be used to include multiple 1120 signatures within the same HTTP message. For example, a signer may 1121 include multiple signatures signing the same content with different 1122 keys or algorithms to support verifiers with different capabilities, 1123 or a reverse proxy may include information about the client in header 1124 fields when forwarding the request to a service host, including a 1125 signature over those fields and the client's original signature. 1127 The following is a non-normative example of header fields a reverse 1128 proxy sets in addition to the examples in the previous sections. The 1129 original signature is included under the identifier "sig1", and the 1130 reverse proxy's signature is included under "proxy_sig". The proxy 1131 uses the key "rsa-test-key" to create its signature using the "rsa- 1132 v1_5-sha256" signature value. This results in a signature input 1133 string of: 1135 "signature";key="sig1": \ 1136 :lPxkxqDEPhgrx1yPaKLO7eJ+oPjSwsQ5NjWNRfYP7Jw0FwnK1k8/GH7g5s2q0VTT\ 1137 KVmxyfpUDp/HsDphh5Z7Fa/lvtujHyFe/0EP9z7bnVb7YBZrxV52LGvP8p4APhOYu\ 1138 G4yaHz478GsJav9BQYK0B2IOHdLFJe8qwWPJs07J47gPewpNwCt0To/zZ2KPpylGX\ 1139 5UHVgJPUom64KjX43u2OwIvSoPEYk4nuBvLR9yxYAHURaTfLoEDUCtY1FsU1hOfG3\ 1140 jAlcT6illfnyS72PEdSSzw1KsxroMj9IYpFhva77YxmJRk4pCIW0F0Kj0ukl7J4y2\ 1141 aZJHMCYI3g8yfqh/wQ==: 1142 "x-forwarded-for": 192.0.2.123 1143 "@signature-params": ("signature";key="sig1" "x-forwarded-for")\ 1144 ;created=1618884480;keyid="test-key-rsa";alg="rsa-v1_5-sha256" 1146 And a signature output value of: 1148 XD1O/vEh772WVpY7jYvReXop2+b7xTIIPKH8/OCYzPn78Wd9jodCwAJPF5TYCn9L6n6\ 1149 8j4EjGsqFOMkVLVdSQEZqMLjEbvMEdIe8m1a0CLd5kydeaAwoHoglqod6ijkwhhEtxt\ 1150 aD8tDZmihQw2mZEH8u4aMSnRntqy7ExCNld0JLharsHV0iCbRO9jIP+d2ApD7gB+eZp\ 1151 n3pIvvVJZlxTwPkahFpxKlQtNMPaSqa1lvejURx+ST8CEuz4sS+G/oLJiX3MZenuUoO\ 1152 R8HeOHDnjN/VLzrEN4x44iF7WIL+iY2PtK87LUWRAsJAX9GqHL/upsGh1nxIdoVaoLV\ 1153 V5w+fRw== 1155 These values are added to the HTTP request message by the proxy. The 1156 different signature values are wrapped onto separate lines to 1157 increase human-readability of the result. 1159 X-Forwarded-For: 192.0.2.123 1160 Signature-Input: sig1=("@request-target" "host" "date" \ 1161 "cache-control" "x-empty-header" "x-example")\ 1162 ;created=1618884475;keyid="test-key-rsa-pss", \ 1163 proxy_sig=("signature";key="sig1" "x-forwarded-for")\ 1164 ;created=1618884480;keyid="test-key-rsa";alg="rsa-v1_5-sha256" 1165 Signature: sig1=:lPxkxqDEPhgrx1yPaKLO7eJ+oPjSwsQ5NjWNRfYP7Jw0FwnK1k\ 1166 8/GH7g5s2q0VTTKVmxyfpUDp/HsDphh5Z7Fa/lvtujHyFe/0EP9z7bnVb7YBZrx\ 1167 V52LGvP8p4APhOYuG4yaHz478GsJav9BQYK0B2IOHdLFJe8qwWPJs07J47gPewp\ 1168 NwCt0To/zZ2KPpylGX5UHVgJPUom64KjX43u2OwIvSoPEYk4nuBvLR9yxYAHURa\ 1169 TfLoEDUCtY1FsU1hOfG3jAlcT6illfnyS72PEdSSzw1KsxroMj9IYpFhva77Yxm\ 1170 JRk4pCIW0F0Kj0ukl7J4y2aZJHMCYI3g8yfqh/wQ==:, \ 1171 proxy_sig=:XD1O/vEh772WVpY7jYvReXop2+b7xTIIPKH8/OCYzPn78Wd9jodCwA\ 1172 JPF5TYCn9L6n68j4EjGsqFOMkVLVdSQEZqMLjEbvMEdIe8m1a0CLd5kydeaAwoH\ 1173 oglqod6ijkwhhEtxtaD8tDZmihQw2mZEH8u4aMSnRntqy7ExCNld0JLharsHV0i\ 1174 CbRO9jIP+d2ApD7gB+eZpn3pIvvVJZlxTwPkahFpxKlQtNMPaSqa1lvejURx+ST\ 1175 8CEuz4sS+G/oLJiX3MZenuUoOR8HeOHDnjN/VLzrEN4x44iF7WIL+iY2PtK87LU\ 1176 WRAsJAX9GqHL/upsGh1nxIdoVaoLVV5w+fRw==: 1178 The proxy's signature and the client's original signature can be 1179 verified independently for the same message, depending on the needs 1180 of the application. 1182 5. IANA Considerations 1184 5.1. HTTP Signature Algorithms Registry 1186 This document defines HTTP Signature Algorithms, for which IANA is 1187 asked to create and maintain a new registry titled "HTTP Signature 1188 Algorithms". Initial values for this registry are given in 1189 Section 5.1.2. Future assignments and modifications to existing 1190 assignment are to be made through the Expert Review registration 1191 policy [RFC8126] and shall follow the template presented in 1192 Section 5.1.1. 1194 Algorithms referenced by algorithm identifiers have to be fully 1195 defined with all parameters fixed. Algorithm identifiers in this 1196 registry are to be interpreted as whole string values and not as a 1197 combination of parts. That is to say, it is expected that 1198 implementors understand "rsa-pss-sha512" as referring to one specific 1199 algorithm with its hash, mask, and salt values set as defined here. 1200 Implementors do not parse out the "rsa", "pss", and "sha512" portions 1201 of the identifier to determine parameters of the signing algorithm 1202 from the string. 1204 5.1.1. Registration Template 1206 Algorithm Name: 1208 An identifier for the HTTP Signature Algorithm. The name MUST be 1209 an ASCII string consisting only of lower-case characters (""a"" - 1210 ""z""), digits (""0"" - ""9""), and hyphens (""-""), and SHOULD 1211 NOT exceed 20 characters in length. The identifier MUST be unique 1212 within the context of the registry. 1214 Status: 1215 A brief text description of the status of the algorithm. The 1216 description MUST begin with one of "Active" or "Deprecated", and 1217 MAY provide further context or explanation as to the reason for 1218 the status. 1220 Description: 1221 A brief description of the algorithm used to sign the signature 1222 input string. 1224 Specification document(s): 1225 Reference to the document(s) that specify the token endpoint 1226 authorization method, preferably including a URI that can be used 1227 to retrieve a copy of the document(s). An indication of the 1228 relevant sections may also be included but is not required. 1230 5.1.2. Initial Contents 1232 5.1.2.1. rsa-pss-sha512 1234 Algorithm Name: 1235 "rsa-pss-sha512" 1237 Status: 1238 Active 1240 Definition: 1241 RSASSA-PSS using SHA-256 1243 Specification document(s): 1244 [[This document]], Section 3.3.1 1246 5.1.2.2. rsa-v1_5-sha256 1248 Algorithm Name: 1249 "rsa-v1_5-sha256" 1251 Status: 1252 Active 1254 Description: 1255 RSASSA-PKCS1-v1_5 using SHA-256 1257 Specification document(s): 1258 [[This document]], Section 3.3.2 1260 5.1.2.3. hmac-sha256 1262 Algorithm Name: 1263 "hmac-sha256" 1265 Status: 1266 Active 1268 Description: 1269 HMAC using SHA-256 1271 Specification document(s): 1272 [[This document]], Section 3.3.3 1274 5.1.2.4. ecdsa-p256-sha256 1276 Algorithm Name: 1277 "ecdsa-p256-sha256" 1279 Status: 1280 Active 1282 Description: 1283 ECDSA using curve P-256 DSS and SHA-256 1285 Specification document(s): 1286 [[This document]], Section 3.3.4 1288 5.2. HTTP Signature Metadata Parameters Registry 1290 This document defines the "Signature-Input" Structured Header, whose 1291 member values may have parameters containing metadata about a message 1292 signature. IANA is asked to create and maintain a new registry 1293 titled "HTTP Signature Metadata Parameters" to record and maintain 1294 the set of parameters defined for use with member values in the 1295 "Signature-Input" Structured Header. Initial values for this 1296 registry are given in Section 5.2.2. Future assignments and 1297 modifications to existing assignments are to be made through the 1298 Expert Review registration policy [RFC8126] and shall follow the 1299 template presented in Section 5.2.1. 1301 5.2.1. Registration Template 1302 5.2.2. Initial Contents 1304 The table below contains the initial contents of the HTTP Signature 1305 Metadata Parameters Registry. Each row in the table represents a 1306 distinct entry in the registry. 1308 +=========+========+================================+ 1309 | Name | Status | Reference(s) | 1310 +=========+========+================================+ 1311 | alg | Active | Section 2.3.2 of this document | 1312 +---------+--------+--------------------------------+ 1313 | created | Active | Section 2.3.2 of this document | 1314 +---------+--------+--------------------------------+ 1315 | expires | Active | Section 2.3.2 of this document | 1316 +---------+--------+--------------------------------+ 1317 | keyid | Active | Section 2.3.2 of this document | 1318 +---------+--------+--------------------------------+ 1319 | nonce | Active | Section 2.3.2 of this document | 1320 +---------+--------+--------------------------------+ 1322 Table 4: Initial contents of the HTTP Signature 1323 Metadata Parameters Registry. 1325 5.3. HTTP Signature Specialty Content Identifiers Registry 1327 This document defines a method for canonicalizing HTTP message 1328 content, including content that can be generated from the context of 1329 the HTTP message outside of the HTTP headers. This content is 1330 identified by a unique key. IANA is asked to create and maintain a 1331 new registry typed "HTTP Signature Specialty Content Identifiers" to 1332 record and maintain the set of non-header content identifiers and 1333 their canonicalization method. Initial values for this registry are 1334 given in Section 5.3.2. Future assignments and modifications to 1335 existing assignments are to be made through the Expert Review 1336 registration policy [RFC8126] and shall follow the template presented 1337 in Section 5.3.1. 1339 5.3.1. Registration Template 1341 5.3.2. Initial Contents 1343 The table below contains the initial contents of the HTTP Signature 1344 Specialty Content Identifiers Registry. 1346 +===================+========+================================+ 1347 | Name | Status | Reference(s) | 1348 +===================+========+================================+ 1349 | @request-target | Active | Section 2.3.1 of this document | 1350 +-------------------+--------+--------------------------------+ 1351 | @signature-params | Active | Section 2.3.2 of this document | 1352 +-------------------+--------+--------------------------------+ 1354 Table 5: Initial contents of the HTTP Signature Specialty 1355 Content Identifiers Registry. 1357 6. Security Considerations 1359 (( TODO: need to dive deeper on this section; not sure how much of 1360 what's referenced below is actually applicable, or if it covers 1361 everything we need to worry about. )) 1363 (( TODO: Should provide some recommendations on how to determine what 1364 content needs to be signed for a given use case. )) 1366 There are a number of security considerations to take into account 1367 when implementing or utilizing this specification. A thorough 1368 security analysis of this protocol, including its strengths and 1369 weaknesses, can be found in [WP-HTTP-Sig-Audit]. 1371 7. References 1373 7.1. Normative References 1375 [FIPS186-4] 1376 "Digital Signature Standard (DSS)", 2013, 1377 . 1380 [HTTP2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1381 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1382 DOI 10.17487/RFC7540, May 2015, 1383 . 1385 [MESSAGING] 1386 Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1387 Protocol (HTTP/1.1): Message Syntax and Routing", 1388 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1389 . 1391 [POSIX.1] "The Open Group Base Specifications Issue 7, 2018 1392 edition", 2018, 1393 . 1395 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1396 Hashing for Message Authentication", RFC 2104, 1397 DOI 10.17487/RFC2104, February 1997, 1398 . 1400 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1401 Requirement Levels", BCP 14, RFC 2119, 1402 DOI 10.17487/RFC2119, March 1997, 1403 . 1405 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1406 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1407 May 2017, . 1409 [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 1410 "Handling Long Lines in Content of Internet-Drafts and 1411 RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, 1412 . 1414 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 1415 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 1416 . 1418 [SEMANTICS] 1419 Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1420 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1421 DOI 10.17487/RFC7231, June 2014, 1422 . 1424 7.2. Informative References 1426 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 1427 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 1428 DOI 10.17487/RFC6234, May 2011, 1429 . 1431 [RFC7239] Petersson, A. and M. Nilsson, "Forwarded HTTP Extension", 1432 RFC 7239, DOI 10.17487/RFC7239, June 2014, 1433 . 1435 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, 1436 DOI 10.17487/RFC7517, May 2015, 1437 . 1439 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 1440 DOI 10.17487/RFC7518, May 2015, 1441 . 1443 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 1444 "PKCS #1: RSA Cryptography Specifications Version 2.2", 1445 RFC 8017, DOI 10.17487/RFC8017, November 2016, 1446 . 1448 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 1449 Writing an IANA Considerations Section in RFCs", BCP 26, 1450 RFC 8126, DOI 10.17487/RFC8126, June 2017, 1451 . 1453 [TLS] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1454 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1455 . 1457 [WP-HTTP-Sig-Audit] 1458 "Security Considerations for HTTP Signatures", 2013, 1459 . 1462 Appendix A. Detecting HTTP Message Signatures 1464 There have been many attempts to create signed HTTP messages in the 1465 past, including other non-standard definitions of the "Signature" 1466 header used within this specification. It is recommended that 1467 developers wishing to support both this specification and other 1468 historical drafts do so carefully and deliberately, as 1469 incompatibilities between this specification and various versions of 1470 other drafts could lead to unexpected problems. 1472 It is recommended that implementers first detect and validate the 1473 "Signature-Input" header defined in this specification to detect that 1474 this standard is in use and not an alternative. If the "Signature- 1475 Input" header is present, all "Signature" headers can be parsed and 1476 interpreted in the context of this draft. 1478 Appendix B. Examples 1480 B.1. Example Keys 1482 This section provides cryptographic keys that are referenced in 1483 example signatures throughout this document. These keys MUST NOT be 1484 used for any purpose other than testing. 1486 The key identifiers for each key are used throughout the examples in 1487 this specification. It is assumed for these examples that the signer 1488 and verifier can unambiguously dereference all key identifiers used 1489 here, and that the keys and algorithms used are appropriate for the 1490 context in which the signature is presented. 1492 B.1.1. Example Key RSA test 1494 The following key is a 2048-bit RSA public and private key pair, 1495 referred to in this document as "test-key-rsa": 1497 -----BEGIN RSA PUBLIC KEY----- 1498 MIIBCgKCAQEAhAKYdtoeoy8zcAcR874L8cnZxKzAGwd7v36APp7Pv6Q2jdsPBRrw 1499 WEBnez6d0UDKDwGbc6nxfEXAy5mbhgajzrw3MOEt8uA5txSKobBpKDeBLOsdJKFq 1500 MGmXCQvEG7YemcxDTRPxAleIAgYYRjTSd/QBwVW9OwNFhekro3RtlinV0a75jfZg 1501 kne/YiktSvLG34lw2zqXBDTC5NHROUqGTlML4PlNZS5Ri2U4aCNx2rUPRcKIlE0P 1502 uKxI4T+HIaFpv8+rdV6eUgOrB2xeI1dSFFn/nnv5OoZJEIB+VmuKn3DCUcCZSFlQ 1503 PSXSfBDiUGhwOw76WuSSsf1D4b/vLoJ10wIDAQAB 1504 -----END RSA PUBLIC KEY----- 1506 -----BEGIN RSA PRIVATE KEY----- 1507 MIIEqAIBAAKCAQEAhAKYdtoeoy8zcAcR874L8cnZxKzAGwd7v36APp7Pv6Q2jdsP 1508 BRrwWEBnez6d0UDKDwGbc6nxfEXAy5mbhgajzrw3MOEt8uA5txSKobBpKDeBLOsd 1509 JKFqMGmXCQvEG7YemcxDTRPxAleIAgYYRjTSd/QBwVW9OwNFhekro3RtlinV0a75 1510 jfZgkne/YiktSvLG34lw2zqXBDTC5NHROUqGTlML4PlNZS5Ri2U4aCNx2rUPRcKI 1511 lE0PuKxI4T+HIaFpv8+rdV6eUgOrB2xeI1dSFFn/nnv5OoZJEIB+VmuKn3DCUcCZ 1512 SFlQPSXSfBDiUGhwOw76WuSSsf1D4b/vLoJ10wIDAQABAoIBAG/JZuSWdoVHbi56 1513 vjgCgkjg3lkO1KrO3nrdm6nrgA9P9qaPjxuKoWaKO1cBQlE1pSWp/cKncYgD5WxE 1514 CpAnRUXG2pG4zdkzCYzAh1i+c34L6oZoHsirK6oNcEnHveydfzJL5934egm6p8DW 1515 +m1RQ70yUt4uRc0YSor+q1LGJvGQHReF0WmJBZHrhz5e63Pq7lE0gIwuBqL8SMaA 1516 yRXtK+JGxZpImTq+NHvEWWCu09SCq0r838ceQI55SvzmTkwqtC+8AT2zFviMZkKR 1517 Qo6SPsrqItxZWRty2izawTF0Bf5S2VAx7O+6t3wBsQ1sLptoSgX3QblELY5asI0J 1518 YFz7LJECgYkAsqeUJmqXE3LP8tYoIjMIAKiTm9o6psPlc8CrLI9CH0UbuaA2JCOM 1519 cCNq8SyYbTqgnWlB9ZfcAm/cFpA8tYci9m5vYK8HNxQr+8FS3Qo8N9RJ8d0U5Csw 1520 DzMYfRghAfUGwmlWj5hp1pQzAuhwbOXFtxKHVsMPhz1IBtF9Y8jvgqgYHLbmyiu1 1521 mwJ5AL0pYF0G7x81prlARURwHo0Yf52kEw1dxpx+JXER7hQRWQki5/NsUEtv+8RT 1522 qn2m6qte5DXLyn83b1qRscSdnCCwKtKWUug5q2ZbwVOCJCtmRwmnP131lWRYfj67 1523 B/xJ1ZA6X3GEf4sNReNAtaucPEelgR2nsN0gKQKBiGoqHWbK1qYvBxX2X3kbPDkv 1524 9C+celgZd2PW7aGYLCHq7nPbmfDV0yHcWjOhXZ8jRMjmANVR/eLQ2EfsRLdW69bn 1525 f3ZD7JS1fwGnO3exGmHO3HZG+6AvberKYVYNHahNFEw5TsAcQWDLRpkGybBcxqZo 1526 81YCqlqidwfeO5YtlO7etx1xLyqa2NsCeG9A86UjG+aeNnXEIDk1PDK+EuiThIUa 1527 /2IxKzJKWl1BKr2d4xAfR0ZnEYuRrbeDQYgTImOlfW6/GuYIxKYgEKCFHFqJATAG 1528 IxHrq1PDOiSwXd2GmVVYyEmhZnbcp8CxaEMQoevxAta0ssMK3w6UsDtvUvYvF22m 1529 qQKBiD5GwESzsFPy3Ga0MvZpn3D6EJQLgsnrtUPZx+z2Ep2x0xc5orneB5fGyF1P 1530 WtP+fG5Q6Dpdz3LRfm+KwBCWFKQjg7uTxcjerhBWEYPmEMKYwTJF5PBG9/ddvHLQ 1531 EQeNC8fHGg4UXU8mhHnSBt3EA10qQJfRDs15M38eG2cYwB1PZpDHScDnDA0= 1532 -----END RSA PRIVATE KEY----- 1534 B.1.2. Example RSA PSS Key 1536 The following key is a 2048-bit RSA public and private key pair, 1537 referred to in this document as "test-key-rsa-pss": 1539 -----BEGIN PUBLIC KEY----- 1540 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr4tmm3r20Wd/PbqvP1s2 1541 +QEtvpuRaV8Yq40gjUR8y2Rjxa6dpG2GXHbPfvMs8ct+Lh1GH45x28Rw3Ry53mm+ 1542 oAXjyQ86OnDkZ5N8lYbggD4O3w6M6pAvLkhk95AndTrifbIFPNU8PPMO7OyrFAHq 1543 gDsznjPFmTOtCEcN2Z1FpWgchwuYLPL+Wokqltd11nqqzi+bJ9cvSKADYdUAAN5W 1544 Utzdpiy6LbTgSxP7ociU4Tn0g5I6aDZJ7A8Lzo0KSyZYoA485mqcO0GVAdVw9lq4 1545 aOT9v6d+nb4bnNkQVklLQ3fVAvJm+xdDOp9LCNCN48V2pnDOkFV6+U9nV5oyc6XI 1546 2wIDAQAB 1547 -----END PUBLIC KEY----- 1549 -----BEGIN PRIVATE KEY----- 1550 MIIEvgIBADALBgkqhkiG9w0BAQoEggSqMIIEpgIBAAKCAQEAr4tmm3r20Wd/Pbqv 1551 P1s2+QEtvpuRaV8Yq40gjUR8y2Rjxa6dpG2GXHbPfvMs8ct+Lh1GH45x28Rw3Ry5 1552 3mm+oAXjyQ86OnDkZ5N8lYbggD4O3w6M6pAvLkhk95AndTrifbIFPNU8PPMO7Oyr 1553 FAHqgDsznjPFmTOtCEcN2Z1FpWgchwuYLPL+Wokqltd11nqqzi+bJ9cvSKADYdUA 1554 AN5WUtzdpiy6LbTgSxP7ociU4Tn0g5I6aDZJ7A8Lzo0KSyZYoA485mqcO0GVAdVw 1555 9lq4aOT9v6d+nb4bnNkQVklLQ3fVAvJm+xdDOp9LCNCN48V2pnDOkFV6+U9nV5oy 1556 c6XI2wIDAQABAoIBAQCUB8ip+kJiiZVKF8AqfB/aUP0jTAqOQewK1kKJ/iQCXBCq 1557 pbo360gvdt05H5VZ/RDVkEgO2k73VSsbulqezKs8RFs2tEmU+JgTI9MeQJPWcP6X 1558 aKy6LIYs0E2cWgp8GADgoBs8llBq0UhX0KffglIeek3n7Z6Gt4YFge2TAcW2WbN4 1559 XfK7lupFyo6HHyWRiYHMMARQXLJeOSdTn5aMBP0PO4bQyk5ORxTUSeOciPJUFktQ 1560 HkvGbym7KryEfwH8Tks0L7WhzyP60PL3xS9FNOJi9m+zztwYIXGDQuKM2GDsITeD 1561 2mI2oHoPMyAD0wdI7BwSVW18p1h+jgfc4dlexKYRAoGBAOVfuiEiOchGghV5vn5N 1562 RDNscAFnpHj1QgMr6/UG05RTgmcLfVsI1I4bSkbrIuVKviGGf7atlkROALOG/xRx 1563 DLadgBEeNyHL5lz6ihQaFJLVQ0u3U4SB67J0YtVO3R6lXcIjBDHuY8SjYJ7Ci6Z6 1564 vuDcoaEujnlrtUhaMxvSfcUJAoGBAMPsCHXte1uWNAqYad2WdLjPDlKtQJK1diCm 1565 rqmB2g8QE99hDOHItjDBEdpyFBKOIP+NpVtM2KLhRajjcL9Ph8jrID6XUqikQuVi 1566 4J9FV2m42jXMuioTT13idAILanYg8D3idvy/3isDVkON0X3UAVKrgMEne0hJpkPL 1567 FYqgetvDAoGBAKLQ6JZMbSe0pPIJkSamQhsehgL5Rs51iX4m1z7+sYFAJfhvN3Q/ 1568 OGIHDRp6HjMUcxHpHw7U+S1TETxePwKLnLKj6hw8jnX2/nZRgWHzgVcY+sPsReRx 1569 NJVf+Cfh6yOtznfX00p+JWOXdSY8glSSHJwRAMog+hFGW1AYdt7w80XBAoGBAImR 1570 NUugqapgaEA8TrFxkJmngXYaAqpA0iYRA7kv3S4QavPBUGtFJHBNULzitydkNtVZ 1571 3w6hgce0h9YThTo/nKc+OZDZbgfN9s7cQ75x0PQCAO4fx2P91Q+mDzDUVTeG30mE 1572 t2m3S0dGe47JiJxifV9P3wNBNrZGSIF3mrORBVNDAoGBAI0QKn2Iv7Sgo4T/XjND 1573 dl2kZTXqGAk8dOhpUiw/HdM3OGWbhHj2NdCzBliOmPyQtAr770GITWvbAI+IRYyF 1574 S7Fnk6ZVVVHsxjtaHy1uJGFlaZzKR4AGNaUTOJMs6NadzCmGPAxNQQOCqoUjn4XR 1575 rOjr9w349JooGXhOxbu8nOxX 1576 -----END PRIVATE KEY----- 1578 B.1.3. Example ECC P-256 Test Key 1580 The following key is an elliptical curve key over the curve P-256, 1581 referred to in this document as "test-key-ecc-p256". 1583 -----BEGIN EC PRIVATE KEY----- 1584 MHcCAQEEIFKbhfNZfpDsW43+0+JjUr9K+bTeuxopu653+hBaXGA7oAoGCCqGSM49 1585 AwEHoUQDQgAEqIVYZVLCrPZHGHjP17CTW0/+D9Lfw0EkjqF7xB4FivAxzic30tMM 1586 4GF+hR6Dxh71Z50VGGdldkkDXZCnTNnoXQ== 1587 -----END EC PRIVATE KEY----- 1589 -----BEGIN PUBLIC KEY----- 1590 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqIVYZVLCrPZHGHjP17CTW0/+D9Lf 1591 w0EkjqF7xB4FivAxzic30tMM4GF+hR6Dxh71Z50VGGdldkkDXZCnTNnoXQ== 1592 -----END PUBLIC KEY----- 1594 B.1.4. Example Shared Secret 1596 The following shared secret is 64 randomly-generated bytes encoded in 1597 Base64, referred to in this document as "test-shared-secret". 1599 uzvJfB4u3N0Jy4T7NZ75MDVcr8zSTInedJtkgcu46YW4XByzNJjxBdtjUkdJPBt\ 1600 bmHhIDi6pcl8jsasjlTMtDQ== 1602 B.2. Test Cases 1604 This section provides non-normative examples that may be used as test 1605 cases to validate implementation correctness. These examples are 1606 based on the following HTTP messages: 1608 For requests, this "test-request" message is used: 1610 POST /foo?param=value&pet=dog HTTP/1.1 1611 Host: example.com 1612 Date: Tue, 20 Apr 2021 02:07:55 GMT 1613 Content-Type: application/json 1614 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1615 Content-Length: 18 1617 {"hello": "world"} 1619 For responses, this "test-response" message is used: 1621 HTTP/1.1 200 OK 1622 Date: Tue, 20 Apr 2021 02:07:56 GMT 1623 Content-Type: application/json 1624 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1625 Content-Length: 18 1627 {"hello": "world"} 1629 B.2.1. Minimal Signature Header using rsa-pss-sha512 1631 This example presents a minimal "Signature-Input" and "Signature" 1632 header for a signature using the "rsa-pss-sha512" algorithm over 1633 "test-request", covering none of the content of the HTTP message 1634 request but providing a timestamped signature proof of possession of 1635 the key. 1637 The corresponding signature input is: 1639 "@signature-params": ();created=1618884475\ 1640 ;keyid="test-key-rsa-pss";alg="rsa-pss-sha512" 1642 This results in the following "Signature-Input" and "Signature" 1643 headers being added to the message: 1645 Signature-Input: sig1=();created=1618884475\ 1646 ;keyid="test-key-rsa-pss";alg="rsa-pss-sha512" 1647 Signature: sig1=:VrfdC2KEFFLoGMYTbQz4PSlKat4hAxcr5XkVN7Mm/7OQQJG+uX\ 1648 gOez7kA6n/yTCaR1VL+FmJd2IVFCsUfcc/jO9siZK3siadoK1Dfgp2ieh9eO781ty\ 1649 SS70OwvAkdORuQLWDnaDMRDlQhg5sNP6JaQghFLqD4qgFrM9HMPxLrznhAQugJ0Fd\ 1650 RZLtSpnjECW6qsu2PVRoCYfnwe4gu8TfqH5GDx2SkpCF9BQ8CijuIWlOg7QP73tKt\ 1651 QNp65u14Si9VEVXHWGiLw4blyPLzWz/fqJbdLaq94Ep60Nq8WjYEAInYH6KyV7EAD\ 1652 60LXdspwF50R3dkWXJP/x+gkAHSMsxbg==: 1654 B.2.2. Header Coverage using rsa-pss-sha512 1656 This example covers all the specified headers in "test-request" 1657 except for the body digest header using the "rsa-pss-sha512" 1658 algorithm. 1660 The corresponding signature input is: 1662 "host": example.com 1663 "date": Tue, 20 Apr 2021 02:07:55 GMT 1664 "content-type": application/json 1665 "@signature-params": ("host" "date" "content-type")\ 1666 ;created=1618884475;keyid="test-key-rsa-pss" 1668 This results in the following "Signature-Input" and "Signature" 1669 headers being added to the message: 1671 Signature-Input: sig1=("host" "date" "content-type")\ 1672 ;created=1618884475;keyid="test-key-rsa-pss" 1673 Signature: sig1=:Zu48JBrHlXN+hVj3T5fPQUjMNEEhABM5vNmiWuUUl7BWNid5Rz\ 1674 OH1tEjVi+jObYkYT8p09lZ2hrNuU3xm+JUBT8WNIlopJtt0EzxFnjGlHvkhu3KbJf\ 1675 xNlvCJVlOEdR4AivDLMeK/ZgASpZ7py1UNHJqRyGCYkYpeedinXUertL/ySNp+VbK\ 1676 2O/qCoui2jFgff2kXQd6rjL1Up83Fpr+/KoZ6HQkv3qwBdMBDyHQykfZHhLn4AO1I\ 1677 G+vKhOLJQDfaLsJ/fYfzsgc1s46j3GpPPD/W2nEEtdhNwu7oXq81qVRsENChIu1XI\ 1678 FKR9q7WpyHDKEWTtaNZDS8TFvIQRU22w==: 1680 B.2.3. Full Coverage using rsa-pss-sha512 1682 This example covers all headers in "test-request" plus the request 1683 target and message body digest using the "rsa-pss-sha512" algorithm. 1685 The corresponding signature input is: 1687 "@request-target": post /foo?param=value&pet=dog 1688 "host": example.com 1689 "date": Tue, 20 Apr 2021 02:07:55 GMT 1690 "content-type": application/json 1691 "digest": SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1692 "content-length": 18 1693 "@signature-params": ("@request-target" "host" "date" \ 1694 "content-type" "digest" "content-length");created=1618884475\ 1695 ;keyid="test-key-rsa-pss" 1697 This results in the following "Signature-Input" and "Signature" 1698 headers being added to the message: 1700 Signature-Input: sig1=("@request-target" "host" "date" \ 1701 "content-type" "digest" "content-length");created=1618884475\ 1702 ;keyid="test-key-rsa-pss" 1703 Signature: \ 1704 sig1=:iD5NhkJoGSuuTpWMzS0BI47DfbWwsGmHHLTwOxT0n+0cQFSC+1c26B7IOfI\ 1705 RTYofqD0sfYYrnSwCvWJfA1zthAEv9J1CxS/CZXe7CQvFpuKuFJxMpkAzVYdE/TA6\ 1706 fELxNZy9RJEWZUPBU4+aJ26d8PC0XhPObXe6JkP6/C7XvG2QinsDde7rduMdhFN/H\ 1707 j2MuX1Ipzvv4EgbHJdKwmWRNamfmKJZC4U5Tn0F58lzGF+WIpU73V67/6aSGvJGM5\ 1708 7U9bRHrBB7ExuQhOX2J2dvJMYkE33pEJA70XBUp9ZvciTI+vjIUgUQ2oRww3huWML\ 1709 mMMqEc95CliwIoL5aBdCnlQ==: 1711 B.2.4. Signing a Response using ecdsa-p256-sha256 1713 This example covers portions of the "test-response" response message 1714 using the "ecdsa-p256-sha256" algorithm and the key "test-key-ecc- 1715 p256". 1717 The corresponding signature input is: 1719 "date": Tue, 20 Apr 2021 02:07:56 GMT 1720 "content-type": application/json 1721 "digest": SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 1722 "content-length": 18 1723 "@signature-params": ("date" "content-type" "digest" \ 1724 "content-length");created=1618884475;keyid="test-key-ecc-p256" 1726 This results in the following "Signature-Input" and "Signature" 1727 headers being added to the message: 1729 Signature-Input: sig1=("date" "content-type" "digest" \ 1730 "content-length");created=1618884475;keyid="test-key-ecc-p256" 1731 Signature: \ 1732 sig1=:3zmRDW6r50/RETqqhtx/N5sdd5eTh8xmHdsrYRK9wK4rCNEwLjCOBlcQxTL\ 1733 2oJTCWGRkuqE2r9KyqZFY9jd+NQ==: 1735 B.2.5. Signing a Request using hmac-sha256 1737 This example covers portions of the "test-request" using the "hmac- 1738 sha256" algorithm and the secret "test-shared-secret". 1740 The corresponding signature input is: 1742 "host": example.com 1743 "date": Tue, 20 Apr 2021 02:07:55 GMT 1744 "content-type": application/json 1745 "@signature-params": ("host" "date" "content-type")\ 1746 ;created=1618884475;keyid="test-shared-secret" 1748 This results in the following "Signature-Input" and "Signature" 1749 headers being added to the message: 1751 Signature-Input: sig1=("host" "date" "content-type")\ 1752 ;created=1618884475;keyid="test-shared-secret" 1753 Signature: sig1=:x54VEvVOb0TMw8fUbsWdUHqqqOre+K7sB/LqHQvnfaQ=: 1755 Acknowledgements 1757 This specification was initially based on the draft-cavage-http- 1758 signatures internet draft. The editors would like to thank the 1759 authors of that draft, Mark Cavage and Manu Sporny, for their work on 1760 that draft and their continuing contributions. 1762 The editors would also like to thank the following individuals for 1763 feedback, insight, and implementation of this draft and its 1764 predecessors (in alphabetical order): Mark Adamcin, Mark Allen, Paul 1765 Annesley, Karl Boehlmark, Stephane Bortzmeyer, Sarven Capadisli, Liam 1766 Dennehy, ductm54, Stephen Farrell, Phillip Hallam-Baker, Eric Holmes, 1767 Andrey Kislyuk, Adam Knight, Dave Lehn, Dave Longley, Ilari 1768 Liusvaara, James H. Manger, Kathleen Moriarty, Mark Nottingham, Yoav 1769 Nir, Adrian Palmer, Lucas Pardue, Roberto Polli, Julian Reschke, 1770 Michael Richardson, Wojciech Rygielski, Adam Scarr, Cory J. Slep, 1771 Dirk Stein, Henry Story, Lukasz Szewc, Chris Webber, and Jeffrey 1772 Yasskin. 1774 Document History 1776 _RFC EDITOR: please remove this section before publication_ 1778 * draft-ietf-httpbis-message-signatures 1780 - -05 1782 o Remove list prefixes. 1784 o Clarify signature algorithm parameters. 1786 o Update and fix examples. 1788 o Add examples for ECC and HMAC. 1790 - -04 1792 o Moved signature component definitions up to intro. 1794 o Created formal function definitions for algorithms to 1795 fulfill. 1797 o Updated all examples. 1799 o Added nonce parameter field. 1801 - -03 1803 o Clarified signing and verification processes. 1805 o Updated algorithm and key selection method. 1807 o Clearly defined core algorithm set. 1809 o Defined JOSE signature mapping process. 1811 o Removed legacy signature methods. 1813 o Define signature parameters separately from "signature" 1814 object model. 1816 o Define serialization values for signature-input header based 1817 on signature input. 1819 - -02 1821 o Removed editorial comments on document sources. 1823 o Removed in-document issues list in favor of tracked issues. 1825 o Replaced unstructured "Signature" header with "Signature- 1826 Input" and "Signature" Dictionary Structured Header Fields. 1828 o Defined content identifiers for individual Dictionary 1829 members, e.g., ""x-dictionary-field";key=member-name". 1831 o Defined content identifiers for first N members of a List, 1832 e.g., ""x-list-field":prefix=4". 1834 o Fixed up examples. 1836 o Updated introduction now that it's adopted. 1838 o Defined specialty content identifiers and a means to extend 1839 them. 1841 o Required signature parameters to be included in signature. 1843 o Added guidance on backwards compatibility, detection, and 1844 use of signature methods. 1846 - -01 1848 o Strengthened requirement for content identifiers for header 1849 fields to be lower-case (changed from SHOULD to MUST). 1851 o Added real example values for Creation Time and Expiration 1852 Time. 1854 o Minor editorial corrections and readability improvements. 1856 - -00 1858 o Initialized from draft-richanna-http-message-signatures-00, 1859 following adoption by the working group. 1861 * draft-richanna-http-message-signatures 1863 - -00 1864 o Converted to xml2rfc v3 and reformatted to comply with RFC 1865 style guides. 1867 o Removed Signature auth-scheme definition and related 1868 content. 1870 o Removed conflicting normative requirements for use of 1871 algorithm parameter. Now MUST NOT be relied upon. 1873 o Removed Extensions appendix. 1875 o Rewrote abstract and introduction to explain context and 1876 need, and challenges inherent in signing HTTP messages. 1878 o Rewrote and heavily expanded algorithm definition, retaining 1879 normative requirements. 1881 o Added definitions for key terms, referenced RFC 7230 for 1882 HTTP terms. 1884 o Added examples for canonicalization and signature generation 1885 steps. 1887 o Rewrote Signature header definition, retaining normative 1888 requirements. 1890 o Added default values for algorithm and expires parameters. 1892 o Rewrote HTTP Signature Algorithms registry definition. 1893 Added change control policy and registry template. Removed 1894 suggested URI. 1896 o Added IANA HTTP Signature Parameter registry. 1898 o Added additional normative and informative references. 1900 o Added Topics for Working Group Discussion section, to be 1901 removed prior to publication as an RFC. 1903 Authors' Addresses 1905 Annabelle Backman (editor) 1906 Amazon 1907 P.O. Box 81226 1908 Seattle, WA 98108-1226 1909 United States of America 1911 Email: richanna@amazon.com 1912 URI: https://www.amazon.com/ 1914 Justin Richer 1915 Bespoke Engineering 1917 Email: ietf@justin.richer.org 1918 URI: https://bspk.io/ 1920 Manu Sporny 1921 Digital Bazaar 1922 203 Roanoke Street W. 1923 Blacksburg, VA 24060 1924 United States of America 1926 Email: msporny@digitalbazaar.com 1927 URI: https://manu.sporny.org/