idnits 2.17.1 draft-cavage-http-signatures-12.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 seems to lack a Security Considerations section. ** The abstract seems to contain references ([2], [3], [4], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 199: '... REQUIRED. The `keyId` field is an ...' RFC 2119 keyword, line 203: '... Implementations MUST be able to disco...' RFC 2119 keyword, line 210: '... REQUIRED. The `signature` paramete...' RFC 2119 keyword, line 220: '... RECOMMENDED. The `algorithm` param...' RFC 2119 keyword, line 223: '... and MUST NOT be marked "deprecated"...' (29 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 20, 2019) is 1649 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) -- Looks like a reference, but probably isn't: '1' on line 688 -- Looks like a reference, but probably isn't: '2' on line 690 -- Looks like a reference, but probably isn't: '3' on line 692 -- Looks like a reference, but probably isn't: '4' on line 694 -- Looks like a reference, but probably isn't: '5' on line 696 -- Looks like a reference, but probably isn't: '6' on line 698 -- Looks like a reference, but probably isn't: '7' on line 700 -- Looks like a reference, but probably isn't: '8' on line 702 -- Looks like a reference, but probably isn't: '9' on line 704 -- Looks like a reference, but probably isn't: '10' on line 706 -- Looks like a reference, but probably isn't: '11' on line 708 -- Looks like a reference, but probably isn't: '12' on line 710 -- Looks like a reference, but probably isn't: '13' on line 712 -- Looks like a reference, but probably isn't: '14' on line 714 -- Looks like a reference, but probably isn't: '15' on line 716 -- Looks like a reference, but probably isn't: '16' on line 746 -- Looks like a reference, but probably isn't: '17' on line 752 -- Looks like a reference, but probably isn't: '18' on line 754 -- Looks like a reference, but probably isn't: '19' on line 764 -- Looks like a reference, but probably isn't: '20' on line 904 -- Looks like a reference, but probably isn't: '21' on line 915 -- Looks like a reference, but probably isn't: '22' on line 928 -- Looks like a reference, but probably isn't: '23' on line 940 -- Looks like a reference, but probably isn't: '24' on line 950 -- Looks like a reference, but probably isn't: '25' on line 960 -- Looks like a reference, but probably isn't: '26' on line 970 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Obsolete informational reference (is this intentional?): RFC 3230 (Obsoleted by RFC 9530) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 30 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Cavage 3 Internet-Draft Oracle 4 Intended status: Standards Track M. Sporny 5 Expires: April 22, 2020 Digital Bazaar 6 October 20, 2019 8 Signing HTTP Messages 9 draft-cavage-http-signatures-12 11 Abstract 13 When communicating over the Internet using the HTTP protocol, it can 14 be desirable for a server or client to authenticate the sender of a 15 particular message. It can also be desirable to ensure that the 16 message was not tampered with during transit. This document 17 describes a way for servers and clients to simultaneously add 18 authentication and message integrity to HTTP messages by using a 19 digital signature. 21 Feedback 23 This specification is a joint work product of the W3C Digital 24 Verification Community Group [1] and the W3C Credentials Community 25 Group [2]. Feedback related to this specification should logged in 26 the issue tracker [3] or be sent to public-credentials@w3.org [4]. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on April 22, 2020. 45 Copyright Notice 47 Copyright (c) 2019 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Using Signatures in HTTP Requests . . . . . . . . . . . . 4 61 1.2. Using Signatures in HTTP Responses . . . . . . . . . . . 4 62 2. The Components of a Signature . . . . . . . . . . . . . . . . 4 63 2.1. Signature Parameters . . . . . . . . . . . . . . . . . . 5 64 2.1.1. keyId . . . . . . . . . . . . . . . . . . . . . . . . 5 65 2.1.2. signature . . . . . . . . . . . . . . . . . . . . . . 5 66 2.1.3. algorithm . . . . . . . . . . . . . . . . . . . . . . 5 67 2.1.4. created . . . . . . . . . . . . . . . . . . . . . . . 6 68 2.1.5. expires . . . . . . . . . . . . . . . . . . . . . . . 6 69 2.1.6. headers . . . . . . . . . . . . . . . . . . . . . . . 6 70 2.2. Ambiguous Parameters . . . . . . . . . . . . . . . . . . 6 71 2.3. Signature String Construction . . . . . . . . . . . . . . 7 72 2.4. Creating a Signature . . . . . . . . . . . . . . . . . . 9 73 2.5. Verifying a Signature . . . . . . . . . . . . . . . . . . 9 74 3. The 'Signature' HTTP Authentication Scheme . . . . . . . . . 10 75 3.1. Authorization Header . . . . . . . . . . . . . . . . . . 10 76 3.1.1. Initiating Signature Authorization . . . . . . . . . 11 77 3.1.2. RSA Example . . . . . . . . . . . . . . . . . . . . . 11 78 3.1.3. HMAC Example . . . . . . . . . . . . . . . . . . . . 12 79 4. The 'Signature' HTTP Header . . . . . . . . . . . . . . . . . 12 80 4.1. Signature Header . . . . . . . . . . . . . . . . . . . . 12 81 4.1.1. RSA Example . . . . . . . . . . . . . . . . . . . . . 13 82 4.1.2. HMAC Example . . . . . . . . . . . . . . . . . . . . 14 83 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 84 5.1. Normative References . . . . . . . . . . . . . . . . . . 14 85 5.2. Informative References . . . . . . . . . . . . . . . . . 14 86 5.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 15 87 Appendix A. Security Considerations . . . . . . . . . . . . . . 16 88 Appendix B. Extensions . . . . . . . . . . . . . . . . . . . . . 16 89 Appendix C. Test Values . . . . . . . . . . . . . . . . . . . . 17 90 C.1. Default Test . . . . . . . . . . . . . . . . . . . . . . 18 91 C.2. Basic Test . . . . . . . . . . . . . . . . . . . . . . . 18 92 C.3. All Headers Test . . . . . . . . . . . . . . . . . . . . 19 94 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 19 95 Appendix E. IANA Considerations . . . . . . . . . . . . . . . . 20 96 E.1. Signature Authentication Scheme . . . . . . . . . . . . . 20 97 E.2. HTTP Signatures Algorithms Registry . . . . . . . . . . . 20 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 100 1. Introduction 102 This protocol extension is intended to provide a simple and standard 103 way for clients to sign HTTP messages. 105 HTTP Authentication [RFC2617] defines Basic and Digest authentication 106 mechanisms, TLS 1.2 [RFC5246] defines cryptographically strong 107 transport layer security, and OAuth 2.0 [RFC6749] provides a fully- 108 specified alternative for authorization of web service requests. 109 Each of these approaches are employed on the Internet today with 110 varying degrees of protection. However, none of these schemes are 111 designed to cryptographically sign the HTTP messages themselves, 112 which is required in order to ensure end-to-end message integrity. 113 An added benefit of signing the HTTP message for the purposes of end- 114 to-end message integrity is that the client can be authenticated 115 using the same mechanism without the need for multiple round-trips. 117 Several web service providers have invented their own schemes for 118 signing HTTP messages, but to date, none have been standardized. 119 While there are no techniques in this proposal that are novel beyond 120 the previous art, it is useful to standardize a simple and 121 cryptographically strong mechanism for digitally signing HTTP 122 messages. 124 This specification presents two mechanisms with distinct purposes: 126 1. The "Signature" scheme which is intended primarily to allow a 127 sender to assert the contents of the message sent are correct and 128 have not been altered during transmission or storage in a way 129 that alters the meaning expressed in the original message as 130 signed. Any party reading the message (the verifier) may 131 independently confirm the validity of the message signature. 132 This scheme is agnostic to the client/server direction and can be 133 used to verify the contents of either HTTP requests, HTTP 134 reponses, or both. 136 2. The "Authorization" scheme which is intended primarily to allow a 137 sender to request access to a resource or resources by proving 138 that they control a secret key. This specification allows for 139 this both with a shared secret (using HMAC) or with public/ 140 private keys. The "Authorization" scheme is typically used in 141 authentication processes and not directly for message signing. 143 As a consequence `Authorization` header is normally generated 144 (and the message signed) by the HTTP client and the message 145 verified by the HTTP server. 147 1.1. Using Signatures in HTTP Requests 149 It is common practice to protect sensitive website and API 150 functionality via authentication mechanisms. Often, the entity 151 accessing these APIs is a piece of automated software outside of an 152 interactive human session. While there are mechanisms like OAuth and 153 API secrets that are used to grant API access, each have their 154 weaknesses such as unnecessary complexity for particular use cases or 155 the use of shared secrets which may not be acceptable to an 156 implementer. Shared secrets also prohibit any possibility for non- 157 repudiation, while secure transports such as TLS do not provide for 158 this at all. 160 Digital signatures are widely used to provide authentication and 161 integrity assurances without the need for shared secrets. They also 162 do not require a round-trip in order to authenticate the client, and 163 allow the integrity of a message to be verified independently of the 164 transport (e.g. TLS). A server need only have an understanding of 165 the key (e.g. through a mapping between the key being used to sign 166 the content and the authorized entity) to verify that a message was 167 signed by that entity. 169 When optionally combined with asymmetric keys associated with an 170 identity, this specification can also enable authentication of a 171 client and server with or without prior knowledge of each other. 173 1.2. Using Signatures in HTTP Responses 175 HTTP messages are routinely altered as they traverse the 176 infrastructure of the Internet, for mostly benign reasons. Gateways 177 and proxies add, remove and alter headers for operational reasons, so 178 a sender cannot rely on the recipient receiving exactly the message 179 transmitted. By allowing a sender to sign specified headers, and 180 recipient or intermediate system can confirm that the original intent 181 of the sender is preserved, and including a Digest header can also 182 verify the message body is not modified. This allows any recipient 183 to easily confirm both the sender's identity, and any incidental or 184 malicious changes that alter the content or meaning of the message. 186 2. The Components of a Signature 188 There are a number of components in a signature that are common 189 between the 'Signature' HTTP Authentication Scheme and the 190 'Signature' HTTP Header. This section details the components of the 191 digital signature paremeters common to both schemes. 193 2.1. Signature Parameters 195 The following section details the Signature Parameters. 197 2.1.1. keyId 199 REQUIRED. The `keyId` field is an opaque string that the server can 200 use to look up the component they need to validate the signature. It 201 could be an SSH key fingerprint, a URL to machine-readable key data, 202 an LDAP DN, etc. Management of keys and assignment of `keyId` is out 203 of scope for this document. Implementations MUST be able to discover 204 metadata about the key from the `keyId` such that they can determine 205 the type of digital signature algorithm to employ when creating or 206 verifying signatures. 208 2.1.2. signature 210 REQUIRED. The `signature` parameter is a base 64 encoded digital 211 signature, as described in RFC 4648 [RFC4648], Section 4 [5]. The 212 client uses the `algorithm` and `headers` Signature Parameters to 213 form a canonicalized `signing string`. This `signing string` is then 214 signed using the key associated with the `keyId` according to its 215 digital signature algorithm. The `signature` parameter is then set 216 to the base 64 encoding of the signature. 218 2.1.3. algorithm 220 RECOMMENDED. The `algorithm` parameter is used to specify the 221 signature string construction mechanism. Valid values for this 222 parameter can be found in the HTTP Signatures Algorithms Registry [6] 223 and MUST NOT be marked "deprecated". Implementers SHOULD derive the 224 digital signature algorithm used by an implementation from the key 225 metadata identified by the `keyId` rather than from this field. If 226 `algorithm` is provided and differs from the key metadata identified 227 by the `keyId`, for example `rsa-sha256` but an EdDSA key is 228 identified via `keyId`, then an implementation MUST produce an error. 229 Implementers should note that previous versions of the `algorithm` 230 parameter did not use the key information to derive the digital 231 signature type and thus could be utilized by attackers to expose 232 security vulnerabilities. 234 2.1.4. created 236 RECOMMENDED. The `created` field expresses when the signature was 237 created. The value MUST be a Unix timestamp integer value. A 238 signature with a `created` timestamp value that is in the future MUST 239 NOT be processed. Using a Unix timestamp simplifies processing and 240 avoids timezone management required by specifications such as 241 RFC3339. Subsecond precision is not supported. This value is useful 242 when clients are not capable of controlling the `Date` HTTP Header 243 such as when operating in certain web browser environments. 245 2.1.5. expires 247 OPTIONAL. The `expires` field expresses when the signature ceases to 248 be valid. The value MUST be a Unix timestamp integer value. A 249 signature with an `expires` timestamp value that is in the past MUST 250 NOT be processed. Using a Unix timestamp simplifies processing and 251 avoid timezone management existing in RFC3339. Subsecod precision is 252 allowed using decimal notation. 254 2.1.6. headers 256 OPTIONAL. The `headers` parameter is used to specify the list of 257 HTTP headers included when generating the signature for the message. 258 If specified, it SHOULD be a lowercased, quoted list of HTTP header 259 fields, separated by a single space character. If not specified, 260 implementations MUST operate as if the field were specified with a 261 single value, `(created)`, in the list of HTTP headers. Note: 263 1. The list order is important, and MUST be specified in the order 264 the HTTP header field-value pairs are concatenated together 265 during Signature String Construction (Section 2.3) used during 266 signing and verifying. 268 2. A zero-length `headers` parameter value MUST NOT be used, since 269 it results in a signature of an empty string. 271 2.2. Ambiguous Parameters 273 If any of the parameters listed above are erroneously duplicated in 274 the associated header field, then the the signature MUST NOT be 275 processed. Any parameter that is not recognized as a parameter, or 276 is not well-formed, MUST be ignored. 278 2.3. Signature String Construction 280 A signed HTTP message needs to be tolerant of some trivial 281 alterations during transmission as it goes through gateways, proxies, 282 and other entities. These changes are often of little consequence 283 and very benign, but also often not visible to or detectable by 284 either the sender or the recipient. Simply signing the entire 285 message that was transmitted by the sender is therefore not feasible: 286 Even very minor changes would result in a signature which cannot be 287 verified. 289 This specification allows the sender to select which headers are 290 meaningful by including their names in the `headers` Signature 291 Parameter. The headers appearing in this parameter are then used to 292 construct the intermediate Signature String, which is the data that 293 is actually signed. 295 In order to generate the string that is signed with a key, the client 296 MUST use the values of each HTTP header field in the `headers` 297 Signature Parameter, in the order they appear in the `headers` 298 Signature Parameter. It is out of scope for this document to dictate 299 what header fields an application will want to enforce, but 300 implementers SHOULD at minimum include the `(request-target)` and 301 `(created)` header fields if `algorithm` does not start with `rsa`, 302 `hmac`, or `ecdsa`. Otherwise, `(request-target)` and `date` SHOULD 303 be included in the signature. 305 To include the HTTP request target in the signature calculation, use 306 the special `(request-target)` header field name. To include the 307 signature creation time, use the special `(created)` header field 308 name. To include the signature expiration time, use the special 309 `(expires)` header field name. 311 1. If the header field name is `(request-target)` then generate the 312 header field value by concatenating the lowercased :method, an 313 ASCII space, and the :path pseudo-headers (as specified in 314 HTTP/2, Section 8.1.2.3 [7]). Note: For the avoidance of doubt, 315 lowercasing only applies to the :method pseudo-header and not to 316 the :path pseudo-header. 318 2. If the header field name is `(created)` and the `algorithm` 319 parameter starts with `rsa`, `hmac`, or `ecdsa` an implementation 320 MUST produce an error. If the `created` Signature Parameter is 321 not specified, or is not an integer, an implementation MUST 322 produce an error. Otherwise, the header field value is the 323 integer expressed by the `created` signature parameter. 325 3. If the header field name is `(expires)` and the `algorithm` 326 parameter starts with `rsa`, `hmac`, or `ecdsa` an implementation 327 MUST produce an error. If the `expires` Signature Parameter is 328 not specified, or is not an integer, an implementation MUST 329 produce an error. Otherwise, the header field value is the 330 integer expressed by the `created` signature parameter. 332 4. Create the header field string by concatenating the lowercased 333 header field name followed with an ASCII colon `:`, an ASCII 334 space ` `, and the header field value. Leading and trailing 335 optional whitespace (OWS) in the header field value MUST be 336 omitted (as specified in RFC7230 [RFC7230], Section 3.2.4 [8]). 338 1. If there are multiple instances of the same header field, all 339 header field values associated with the header field MUST be 340 concatenated, separated by a ASCII comma and an ASCII space 341 `, `, and used in the order in which they will appear in the 342 transmitted HTTP message. 344 2. If the header value (after removing leading and trailing 345 whitespace) is a zero-length string, the signature string 346 line correlating with that header will simply be the 347 (lowercased) header name, an ASCII colon `:`, and an ASCII 348 space ` `. 350 3. Any other modification to the header field value MUST NOT be 351 made. 353 4. If a header specified in the headers parameter is malformed 354 or cannot be matched with a provided header in the message, 355 the implementation MUST produce an error. 357 5. If value is not the last value then append an ASCII newline `\n`. 359 To illustrate the rules specified above, assume a `headers` parameter 360 list with the value of `(request-target) (created) host date cache- 361 control x-emptyheader x-example` with the following HTTP request 362 headers: 364 GET /foo HTTP/1.1 365 Host: example.org 366 Date: Tue, 07 Jun 2014 20:51:35 GMT 367 X-Example: Example header 368 with some whitespace. 369 X-EmptyHeader: 370 Cache-Control: max-age=60 371 Cache-Control: must-revalidate 372 For the HTTP request headers above, the corresponding signature 373 string is: 375 (request-target): get /foo 376 (created): 1402170695 377 host: example.org 378 date: Tue, 07 Jun 2014 20:51:35 GMT 379 cache-control: max-age=60, must-revalidate 380 x-emptyheader: 381 x-example: Example header with some whitespace. 383 2.4. Creating a Signature 385 In order to create a signature, a client MUST: 387 1. Use the `headers` and `algorithm` values as well as the contents 388 of the HTTP message, to create the signature string. 390 2. Use the key associated with `keyId` to generate a digital 391 signature on the signature string. 393 3. The `signature` is then generated by base 64 encoding the output 394 of the digital signature algorithm. 396 For example, assume that the `algorithm` value is "hs2019" and the 397 `keyId` refers to an EdDSA public key. This would signal to the 398 application that the signature string construction mechanism is the 399 one defined in Section 2.3: Signature String Construction [9], the 400 signature string hashing function is SHA-512, and the signing 401 algorithm is Ed25519 as defined in RFC 8032 [RFC8032], Section 5.1: 402 Ed25519ph, Ed25519ctx, and Ed25519. The result of the signature 403 creation algorithm should result in a binary string, which is then 404 base 64 encoded and placed into the `signature` value. 406 2.5. Verifying a Signature 408 In order to verify a signature, a server MUST: 410 1. Use the received HTTP message, the `headers` value, and the 411 Signature String Construction (Section 2.3) algorithm to recreate 412 the signature. 414 2. The `algorithm`, `keyId`, and base 64 decoded `signature` listed 415 in the Signature Parameters are then used to verify the 416 authenticity of the digital signature. Note: The application 417 verifying the signature MUST derive the digital signature 418 algorithm from the metadata associated with the `keyId` and MUST 419 NOT use the value of `algorithm` from the signed message. 421 If a header specified in the `headers` value of the Signature 422 Parameters (or the default item `(created)` where the `headers` value 423 is not supplied) is absent from the message, the implementation MUST 424 produce an error. 426 For example, assume that the `algorithm` value was "hs2019" and and 427 the `keyId` refers to an EdDSA public key. This would signal to the 428 application that the signature string construction mechanism is the 429 one defined in Section 2.3: Signature String Construction [10], the 430 signature string hashing function is SHA-512, and the signing 431 algorithm is Ed25519 as defined in RFC 8032 [RFC8032], Section 5.1: 432 Ed25519ph, Ed25519ctx, and Ed25519. The result of the signature 433 verification algorithm should result in a successful verification 434 unless the headers protected by the signature were tampered with in 435 transit. 437 3. The 'Signature' HTTP Authentication Scheme 439 The "Signature" authentication scheme is based on the model that the 440 client must authenticate itself with a digital signature produced by 441 either a private asymmetric key (e.g., RSA) or a shared symmetric key 442 (e.g., HMAC). 444 The scheme is parameterized enough such that it is not bound to any 445 particular key type or signing algorithm. 447 3.1. Authorization Header 449 The client is expected to send an Authorization header (as defined in 450 RFC 7235 [RFC7235], Section 4.1 [11]) where the "auth-scheme" is 451 "Signature" and the "auth-param" parameters meet the requirements 452 listed in Section 2: The Components of a Signature. 454 The rest of this section uses the following HTTP request as an 455 example. 457 POST /foo HTTP/1.1 458 Host: example.org 459 Date: Tue, 07 Jun 2014 20:51:35 GMT 460 Content-Type: application/json 461 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 462 Content-Length: 18 464 {"hello": "world"} 466 Note that the use of the `Digest` header field is per RFC 3230 467 [RFC3230], Section 4.3.2 [12] and is included merely as a 468 demonstration of how an implementer could include information about 469 the body of the message in the signature. The following sections 470 also assume that the "rsa-key-1" keyId asserted by the client is an 471 identifier meaningful to the server. 473 3.1.1. Initiating Signature Authorization 475 A server may notify a client when a resource is protected by 476 requiring a signature. To initiate this process, the server will 477 request that the client authenticate itself via a 401 response [13] 478 code. The server may optionally specify which HTTP headers it 479 expects to be signed by specifying the `headers` parameter in the 480 WWW-Authenticate header. For example: 482 HTTP/1.1 401 Unauthorized 483 Date: Thu, 08 Jun 2014 18:32:30 GMT 484 Content-Length: 1234 485 Content-Type: text/html 486 WWW-Authenticate: Signature 487 realm="Example",headers="(request-target) (created)" 489 ... 491 3.1.2. RSA Example 493 The authorization header and signature would be generated as: 495 Authorization: Signature keyId="rsa-key-1",algorithm="hs2019", 496 headers="(request-target) (created) host digest content-length", 497 signature="Base64(RSA-SHA512(signing string))" 499 The client would compose the signing string as: 501 (request-target): post /foo\n 502 (created): 1402174295 503 host: example.org\n 504 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 505 content-length: 18 507 Note that the '\n' symbols above are included to demonstrate where 508 the new line character should be inserted. There is no new line on 509 the final line of the signing string. Each HTTP header above is 510 displayed on a new line to provide better readability of the example. 512 For an RSA-based signature, the authorization header and signature 513 would then be generated as: 515 Authorization: Signature keyId="rsa-key-1",algorithm="hs2019", 516 headers="(request-target) (created) host digest content-length", 517 signature="Base64(RSA-SHA512(signing string))" 519 3.1.3. HMAC Example 521 For an HMAC-based signature without a list of headers specified, the 522 authorization header and signature would be generated as: 524 Authorization: Signature keyId="hmac-key-1",algorithm="hs2019", 525 headers="(request-target) (created) host digest content-length", 526 signature="Base64(HMAC-SHA512(signing string))" 528 The only difference between the RSA Example and the HMAC Example is 529 the digital signature algorithm that is used. The client would 530 compose the signing string in the same way as the RSA Example above: 532 (request-target): post /foo\n 533 (created): 1402174295 534 host: example.org\n 535 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 536 content-length: 18 538 4. The 'Signature' HTTP Header 540 The "Signature" HTTP Header provides a mechanism to link the headers 541 of a message (client request or server response) to a digital 542 signature. By including the "Digest" header with a properly 543 formatted digest, the message body can also be linked to the 544 signature. The signature is generated and verified either using a 545 shared secret (e.g. HMAC) or public/private keys (e.g. RSA, EC). 546 This allows the receiver and/or any intermediate system to 547 immediately or later verify the integrity of the message. When the 548 signature is generated with a private key it can also provide a 549 measure of non-repudiation, though a full implementation of a non- 550 repudiatable statement is beyond the scope of this specification and 551 highly dependent on implementation. 553 The "Signature" scheme can also be used for authentication similar to 554 the purpose of the 'Signature' HTTP Authentication Scheme 555 (Section 3). The scheme is parameterized enough such that it is not 556 bound to any particular key type or signing algorithm. 558 4.1. Signature Header 560 The sender is expected to transmit a header (as defined in RFC 7230 561 [RFC7230], Section 3.2 [14]) where the "field-name" is "Signature", 562 and the "field-value" contains one or more "auth-param"s (as defined 563 in RFC 7235 [RFC7235], Section 4.1 [15]) where the "auth-param" 564 parameters meet the requirements listed in Section 2: The Components 565 of a Signature. 567 The rest of this section uses the following HTTP request as an 568 example. 570 POST /foo HTTP/1.1 571 Host: example.org 572 Date: Tue, 07 Jun 2014 20:51:35 GMT 573 Content-Type: application/json 574 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 575 Content-Length: 18 577 {"hello": "world"} 579 The following sections assume that the "rsa-key-1" keyId provided by 580 the signer is an identifier meaningful to the server. 582 4.1.1. RSA Example 584 The signature header and signature would be generated as: 586 Signature: keyId="rsa-key-1",algorithm="hs2019", 587 created=1402170695, expires=1402170995, 588 headers="(request-target) (created) (expires) 589 host date digest content-length", 590 signature="Base64(RSA-SHA256(signing string))" 592 The client would compose the signing string as: 594 (request-target): post /foo\n 595 (created): 1402170695 596 (expires): 1402170995 597 host: example.org\n 598 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 599 content-length: 18 601 Note that the '\n' symbols above are included to demonstrate where 602 the new line character should be inserted. There is no new line on 603 the final line of the signing string. Each HTTP header above is 604 displayed on a new line to provide better readability of the example. 606 For an RSA-based signature, the authorization header and signature 607 would then be generated as: 609 Signature: keyId="rsa-key-1",algorithm="hs2019",created=1402170695, 610 headers="(request-target) (created) host digest content-length", 611 signature="Base64(RSA-SHA512(signing string))" 613 4.1.2. HMAC Example 615 For an HMAC-based signature without a list of headers specified, the 616 authorization header and signature would be generated as: 618 Signature: keyId="hmac-key-1",algorithm="hs2019",created=1402170695, 619 headers="(request-target) (created) host digest content-length", 620 signature="Base64(HMAC-SHA512(signing string))" 622 The only difference between the RSA Example and the HMAC Example is 623 the signature algorithm that is used. The client would compose the 624 signing string in the same way as the RSA Example above: 626 (request-target): post /foo\n 627 (created): 1402170695 628 host: example.org\n 629 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 630 content-length: 18 632 5. References 634 5.1. Normative References 636 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 637 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 638 . 640 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 641 Protocol (HTTP/1.1): Message Syntax and Routing", 642 RFC 7230, DOI 10.17487/RFC7230, June 2014, 643 . 645 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 646 Protocol (HTTP/1.1): Authentication", RFC 7235, 647 DOI 10.17487/RFC7235, June 2014, 648 . 650 5.2. Informative References 652 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 653 Leach, P., Luotonen, A., and L. Stewart, "HTTP 654 Authentication: Basic and Digest Access Authentication", 655 RFC 2617, DOI 10.17487/RFC2617, June 1999, 656 . 658 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 659 RFC 3230, DOI 10.17487/RFC3230, January 2002, 660 . 662 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 663 (TLS) Protocol Version 1.2", RFC 5246, 664 DOI 10.17487/RFC5246, August 2008, 665 . 667 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 668 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 669 DOI 10.17487/RFC6234, May 2011, 670 . 672 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 673 RFC 6749, DOI 10.17487/RFC6749, October 2012, 674 . 676 [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, 677 "PKCS #1: RSA Cryptography Specifications Version 2.2", 678 RFC 8017, DOI 10.17487/RFC8017, November 2016, 679 . 681 [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital 682 Signature Algorithm (EdDSA)", RFC 8032, 683 DOI 10.17487/RFC8032, January 2017, 684 . 686 5.3. URIs 688 [1] https://w3c-dvcg.github.io/ 690 [2] https://w3c-ccg.github.io/ 692 [3] https://github.com/w3c-dvcg/http-signatures/issues 694 [4] mailto:public-credentials@w3.org 696 [5] https://tools.ietf.org/html/rfc4648#section-4 698 [6] #hsa-registry 700 [7] https://tools.ietf.org/html/rfc7540#section-8.1.2.3 702 [8] https://tools.ietf.org/html/rfc7230#section-3.2.4 704 [9] #canonicalization 706 [10] #canonicalization 708 [11] https://tools.ietf.org/html/rfc7235#section-2.1 710 [12] https://tools.ietf.org/html/rfc3230#section-4.3.2 712 [13] https://tools.ietf.org/html/rfc7235#section-3.1 714 [14] https://tools.ietf.org/html/rfc7230#section-3.2 716 [15] https://tools.ietf.org/html/rfc7235#section-4.1 718 [16] https://web-payments.org/specs/source/http-signatures-audit/ 720 [17] https://web-payments.org/specs/source/http-signature-nonces/ 722 [18] https://web-payments.org/specs/source/http-signature-trailers/ 724 [19] https://www.iana.org/assignments/http-auth-scheme-signature 726 [20] https://www.iana.org/assignments/http-authschemes 728 [21] https://www.iana.org/assignments/shm-algorithms 730 [22] #canonicalization 732 [23] #canonicalization 734 [24] #canonicalization 736 [25] #canonicalization 738 [26] #canonicalization 740 Appendix A. Security Considerations 742 There are a number of security considerations to take into account 743 when implementing or utilizing this specification. A thorough 744 security analysis of this protocol, including its strengths and 745 weaknesses, can be found in Security Considerations for HTTP 746 Signatures [16]. 748 Appendix B. Extensions 750 This specification was designed to be simple, modular, and 751 extensible. There are a number of other specifications that build on 752 this one. For example, the HTTP Signature Nonces [17] specification 753 details how to use HTTP Signatures over a non-secured channel like 754 HTTP and the HTTP Signature Trailers [18] specification explains how 755 to apply HTTP Signatures to streaming content. Developers that 756 desire more functionality than this specification provides are urged 757 to ensure that an extension specification doesn't already exist 758 before implementing a proprietary extension. 760 If extensions to this specification are made by adding new Signature 761 Parameters, those extension parameters MUST be registered in the 762 Signature Authentication Scheme Registry. The registry will be 763 created and maintained at (the suggested URI) 764 https://www.iana.org/assignments/http-auth-scheme-signature [19]. An 765 example entry in this registry is included below: 767 Signature Parameter: nonce 768 Reference to specification: [HTTP_AUTH_SIGNATURE_NONCE], Section XYZ. 769 Notes (optional): The HTTP Signature Nonces specification details 770 how to use HTTP Signatures over a unsecured channel like HTTP. 772 Appendix C. Test Values 774 WARNING: THESE TEST VECTORS ARE OLD AND POSSIBLY WRONG. THE NEXT 775 VERSION OF THIS SPECIFICATION WILL CONTAIN THE PROPER TEST VECTORS. 777 The following test data uses the following RSA 2048-bit keys, which 778 we will refer to as `keyId=Test` in the following samples: 780 -----BEGIN PUBLIC KEY----- 781 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3 782 6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6 783 Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw 784 oYi+1hqp1fIekaxsyQIDAQAB 785 -----END PUBLIC KEY----- 787 -----BEGIN RSA PRIVATE KEY----- 788 MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF 789 NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F 790 UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB 791 AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA 792 QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK 793 kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg 794 f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u 795 412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc 796 mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7 797 kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA 798 gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW 799 G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI 800 7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA== 801 -----END RSA PRIVATE KEY----- 802 All examples use this request: 804 POST /foo?param=value&pet=dog HTTP/1.1 805 Host: example.com 806 Date: Sun, 05 Jan 2014 21:31:40 GMT 807 Content-Type: application/json 808 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 809 Content-Length: 18 811 {"hello": "world"} 813 C.1. Default Test 815 If a list of headers is not included, the date is the only header 816 that is signed by default for rsa-sha256. The string to sign would 817 be: 819 date: Sun, 05 Jan 2014 21:31:40 GMT 821 The Authorization header would be: 823 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 824 signature="SjWJWbWN7i0wzBvtPl8rbASWz5xQW6mcJmn+ibttBqtifLN7Sazz 825 6m79cNfwwb8DMJ5cou1s7uEGKKCs+FLEEaDV5lp7q25WqS+lavg7T8hc0GppauB 826 6hbgEKTwblDHYGEtbGmtdHgVCk9SuS13F0hZ8FD0k/5OxEPXe5WozsbM=" 828 The Signature header would be: 830 Signature: keyId="Test",algorithm="rsa-sha256", 831 signature="SjWJWbWN7i0wzBvtPl8rbASWz5xQW6mcJmn+ibttBqtifLN7Sazz 832 6m79cNfwwb8DMJ5cou1s7uEGKKCs+FLEEaDV5lp7q25WqS+lavg7T8hc0GppauB 833 6hbgEKTwblDHYGEtbGmtdHgVCk9SuS13F0hZ8FD0k/5OxEPXe5WozsbM=" 835 C.2. Basic Test 837 The minimum recommended data to sign is the (request-target), host, 838 and date. In this case, the string to sign would be: 840 (request-target): post /foo?param=value&pet=dog 841 host: example.com 842 date: Sun, 05 Jan 2014 21:31:40 GMT 844 The Authorization header would be: 846 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 847 headers="(request-target) host date", 848 signature="qdx+H7PHHDZgy4y/Ahn9Tny9V3GP6YgBPyUXMmoxWtLbHpUnXS 849 2mg2+SbrQDMCJypxBLSPQR2aAjn7ndmw2iicw3HMbe8VfEdKFYRqzic+efkb3 850 nndiv/x1xSHDJWeSWkx3ButlYSuBskLu6kd9Fswtemr3lgdDEmn04swr2Os0=" 852 C.3. All Headers Test 854 A strong signature including all of the headers and a digest of the 855 body of the HTTP request would result in the following signing 856 string: 858 (request-target): post /foo?param=value&pet=dog 859 host: example.com 860 date: Sun, 05 Jan 2014 21:31:40 GMT 861 content-type: application/json 862 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 863 content-length: 18 865 The Authorization header would be: 867 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 868 created=1402170695, expires=1402170699, 869 headers="(request-target) (created) (expires) 870 host date content-type digest content-length", 871 signature="vSdrb+dS3EceC9bcwHSo4MlyKS59iFIrhgYkz8+oVLEEzmYZZvRs 872 8rgOp+63LEM3v+MFHB32NfpB2bEKBIvB1q52LaEUHFv120V01IL+TAD48XaERZF 873 ukWgHoBTLMhYS2Gb51gWxpeIq8knRmPnYePbF5MOkR0Zkly4zKH7s1dE=" 875 The Signature header would be: 877 Signature: keyId="Test",algorithm="rsa-sha256", 878 created=1402170695, expires=1402170699, 879 headers="(request-target) (created) (expires) 880 host date content-type digest content-length", 881 signature="vSdrb+dS3EceC9bcwHSo4MlyKS59iFIrhgYkz8+oVLEEzmYZZvRs 882 8rgOp+63LEM3v+MFHB32NfpB2bEKBIvB1q52LaEUHFv120V01IL+TAD48XaERZF 883 ukWgHoBTLMhYS2Gb51gWxpeIq8knRmPnYePbF5MOkR0Zkly4zKH7s1dE=" 885 Appendix D. Acknowledgements 887 The editor would like to thank the following individuals for feedback 888 on and implementations of the specification (in alphabetical order): 889 Mark Adamcin, Mark Allen, Paul Annesley, Karl Boehlmark, Stephane 890 Bortzmeyer, Sarven Capadisli, Liam Dennehy, ductm54, Stephen Farrell, 891 Phillip Hallam-Baker, Eric Holmes, Andrey Kislyuk, Adam Knight, Dave 892 Lehn, Dave Longley, James H. Manger, Ilari Liusvaara, Mark 893 Nottingham, Yoav Nir, Adrian Palmer, Lucas Pardue, Roberto Polli, 894 Julian Reschke, Michael Richardson, Wojciech Rygielski, Adam Scarr, 895 Cory J. Slep, Dirk Stein, Henry Story, Lukasz Szewc, Chris Webber, 896 and Jeffrey Yasskin 898 Appendix E. IANA Considerations 900 E.1. Signature Authentication Scheme 902 The following entry should be added to the Authentication Scheme 903 Registry located at https://www.iana.org/assignments/http-authschemes 904 [20] 906 Authentication Scheme Name: Signature 907 Reference: [RFC_THIS_DOCUMENT], Section 2. 908 Notes (optional): The Signature scheme is designed for clients to 909 authenticate themselves with a server. 911 E.2. HTTP Signatures Algorithms Registry 913 The following initial entries should be added to the Canonicalization 914 Algorithms Registry to be created and maintained at (the suggested 915 URI) https://www.iana.org/assignments/shm-algorithms [21]: 917 Editor's note: The references in this section are problematic as many 918 of the specifications that they refer to are too implementation 919 specific, rather than just pointing to the proper signature and 920 hashing specifications. A better approach might be just specifying 921 the signature and hashing function specifications, leaving 922 implementers to connect the dots (which are not that hard to 923 connect). 925 Algorithm Name: hs2019 926 Status: active 927 Canonicalization Algorithm: [RFC_THIS_DOCUMENT], Section 2.3: 928 Signature String Construction [22] 929 Hash Algorithm: RFC 6234 [RFC6234], SHA-512 (SHA-2 with 512-bits of 930 digest output) 931 Digital Signature Algorithm: Derived from metadata associated with 932 `keyId`. Recommend support for RFC 8017 [RFC8017], Section 8.1: 933 RSASSA-PSS, RFC 6234 [RFC6234], Section 7.1: SHA-Based HMACs, ANSI 934 X9.62-2005 ECDSA, P-256, and RFC 8032 [RFC8032], Section 5.1: 935 Ed25519ph, Ed25519ctx, and Ed25519. 937 Algorithm Name: rsa-sha1 938 Status: deprecated, SHA-1 not secure. 939 Canonicalization Algorithm: [RFC_THIS_DOCUMENT], Section 2.3: 940 Signature String Construction [23] 941 Hash Algorithm: RFC 6234 [RFC6234], SHA-1 (SHA-1 with 160-bits of 942 digest output) 943 Digital Signature Algorithm: RFC 8017 [RFC8017], Section 8.2: RSASSA- 944 PKCS1-v1_5 946 Algorithm Name: rsa-sha256 947 Status: deprecated, specifying signature algorithm enables attack 948 vector. 949 Canonicalization Algorithm: [RFC_THIS_DOCUMENT], Section 2.3: 950 Signature String Construction [24] 951 Hash Algorithm: RFC 6234 [RFC6234], SHA-256 (SHA-2 with 256-bits of 952 digest output) 953 Digital Signature Algorithm: RFC 8017 [RFC8017], Section 8.2: RSASSA- 954 PKCS1-v1_5 956 Algorithm Name: hmac-sha256 957 Status: deprecated, specifying signature algorithm enables attack 958 vector. 959 Canonicalization Algorithm: [RFC_THIS_DOCUMENT], Section 2.3: 960 Signature String Construction [25] 961 Hash Algorithm: RFC 6234 [RFC6234], SHA-256 (SHA-2 with 256-bits of 962 digest output) 963 Message Authentication Code Algorithm: RFC 6234 [RFC6234], 964 Section 7.1: SHA-Based HMACs 966 Algorithm Name: ecdsa-sha256 967 Status: deprecated, specifying signature algorithm enables attack 968 vector. 969 Canonicalization Algorithm: [RFC_THIS_DOCUMENT], Section 2.3: 970 Signature String Construction [26] 971 Hash Algorithm: RFC 6234 [RFC6234], SHA-256 (SHA-2 with 256-bits of 972 digest output) 973 Digital Signature Algorithm: ANSI X9.62-2005 ECDSA, P-256 975 Authors' Addresses 977 Mark Cavage 978 Oracle 979 500 Oracle Parkway 980 Redwood Shores, CA 94065 981 US 983 Phone: +1 415 400 0626 984 Email: mcavage@gmail.com 985 URI: https://www.oracle.com/ 986 Manu Sporny 987 Digital Bazaar 988 203 Roanoke Street W. 989 Blacksburg, VA 24060 990 US 992 Phone: +1 540 961 4469 993 Email: msporny@digitalbazaar.com 994 URI: https://manu.sporny.org/