idnits 2.17.1 draft-cavage-http-signatures-09.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. ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. ** The abstract seems to contain references ([2], [3], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (November 15, 2017) is 2352 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 548 -- Looks like a reference, but probably isn't: '2' on line 550 -- Looks like a reference, but probably isn't: '3' on line 552 -- Looks like a reference, but probably isn't: '4' on line 554 -- Looks like a reference, but probably isn't: '5' on line 556 -- Looks like a reference, but probably isn't: '6' on line 558 -- Looks like a reference, but probably isn't: '7' on line 560 -- Looks like a reference, but probably isn't: '8' on line 562 -- Looks like a reference, but probably isn't: '9' on line 564 -- Looks like a reference, but probably isn't: '10' on line 566 -- Looks like a reference, but probably isn't: '11' on line 569 -- Looks like a reference, but probably isn't: '12' on line 571 -- Looks like a reference, but probably isn't: '13' on line 573 -- Looks like a reference, but probably isn't: '14' on line 593 -- Looks like a reference, but probably isn't: '15' on line 599 -- Looks like a reference, but probably isn't: '16' on line 601 -- Looks like a reference, but probably isn't: '17' on line 611 -- Looks like a reference, but probably isn't: '18' on line 739 -- Looks like a reference, but probably isn't: '19' on line 751 == Unused Reference: 'RFC2119' is defined on line 496, but no explicit reference was found in the text == Outdated reference: A later version (-40) exists of draft-ietf-jose-json-web-algorithms-20 ** 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 3447 (Obsoleted by RFC 8017) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 24 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: May 19, 2018 Digital Bazaar 6 November 15, 2017 8 Signing HTTP Messages 9 draft-cavage-http-signatures-09 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 be sent to 26 public-credentials@w3.org [3]. 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 May 19, 2018. 45 Copyright Notice 47 Copyright (c) 2017 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 . . . . . . . . . . . . 3 61 1.2. Using Signatures in HTTP Responses . . . . . . . . . . . 4 62 2. The Components of a Signature . . . . . . . . . . . . . . . . 4 63 2.1. Signature Parameters . . . . . . . . . . . . . . . . . . 4 64 2.1.1. keyId . . . . . . . . . . . . . . . . . . . . . . . . 4 65 2.1.2. algorithm . . . . . . . . . . . . . . . . . . . . . . 4 66 2.1.3. headers . . . . . . . . . . . . . . . . . . . . . . . 4 67 2.1.4. signature . . . . . . . . . . . . . . . . . . . . . . 5 68 2.2. Ambiguous Parameters . . . . . . . . . . . . . . . . . . 5 69 2.3. Signature String Construction . . . . . . . . . . . . . . 5 70 2.4. Creating a Signature . . . . . . . . . . . . . . . . . . 6 71 2.5. Verifying a Signature . . . . . . . . . . . . . . . . . . 7 72 3. The 'Signature' HTTP Authentication Scheme . . . . . . . . . 7 73 3.1. Authorization Header . . . . . . . . . . . . . . . . . . 7 74 3.1.1. Initiating Signature Authorization . . . . . . . . . 8 75 3.1.2. RSA Example . . . . . . . . . . . . . . . . . . . . . 8 76 3.1.3. HMAC Example . . . . . . . . . . . . . . . . . . . . 9 77 4. The 'Signature' HTTP Header . . . . . . . . . . . . . . . . . 9 78 4.1. Signature Header . . . . . . . . . . . . . . . . . . . . 10 79 4.1.1. RSA Example . . . . . . . . . . . . . . . . . . . . . 10 80 4.1.2. HMAC Example . . . . . . . . . . . . . . . . . . . . 11 81 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 82 5.1. Normative References . . . . . . . . . . . . . . . . . . 11 83 5.2. Informative References . . . . . . . . . . . . . . . . . 12 84 5.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12 85 Appendix A. Security Considerations . . . . . . . . . . . . . . 13 86 Appendix B. Extensions . . . . . . . . . . . . . . . . . . . . . 13 87 Appendix C. Test Values . . . . . . . . . . . . . . . . . . . . 14 88 C.1. Default Test . . . . . . . . . . . . . . . . . . . . . . 15 89 C.2. Basic Test . . . . . . . . . . . . . . . . . . . . . . . 15 90 C.3. All Headers Test . . . . . . . . . . . . . . . . . . . . 16 91 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 16 92 Appendix E. IANA Considerations . . . . . . . . . . . . . . . . 16 93 E.1. Signature Authentication Scheme . . . . . . . . . . . . . 16 94 E.2. Signature Algorithm Registry . . . . . . . . . . . . . . 17 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 97 1. Introduction 99 This protocol extension is intended to provide a simple and standard 100 way for clients to sign HTTP messages. 102 HTTP Authentication [RFC2617] defines Basic and Digest authentication 103 mechanisms, TLS 1.2 [RFC5246] defines cryptographically strong 104 transport layer security, and OAuth 2.0 [RFC6749] provides a fully- 105 specified alternative for authorization of web service requests. 106 Each of these approaches are employed on the Internet today with 107 varying degrees of protection. However, none of these schemes are 108 designed to cryptographically sign the HTTP messages themselves, 109 which is required in order to ensure end-to-end message integrity. 110 An added benefit of signing the HTTP message for the purposes of end- 111 to-end message integrity is that the client can be authenticated 112 using the same mechanism without the need for multiple round-trips. 114 Several web service providers have invented their own schemes for 115 signing HTTP messages, but to date, none have been standardized. 116 While there are no techniques in this proposal that are novel beyond 117 the previous art, it is useful to standardize a simple and 118 cryptographically strong mechanism for digitally signing HTTP 119 messages. 121 1.1. Using Signatures in HTTP Requests 123 It is common practice to protect sensitive website API functionality 124 via authentication mechanisms. Often, the entity accessing these 125 APIs is a piece of automated software outside of an interactive human 126 session. While there are mechanisms like OAuth and API secrets that 127 are used to grant API access, each have their weaknesses such as 128 unnecessary complexity for particular use cases or the use of shared 129 secrets which may not be acceptable to an implementer. 131 Digital signatures are widely used to provide authentication without 132 the need for shared secrets. They also do not require a round-trip 133 in order to authenticate the client. A server need only have a 134 mapping between the key being used to sign the content and the 135 authorized entity to verify that a message was signed by that entity. 137 This specification provides two mechanisms that can be used by a 138 server to authenticate a client. The first is the 'Signature' HTTP 139 Authentication Scheme, which may be used for interactive sessions. 141 The second is the Signature HTTP Header, which is typically used by 142 automated software agents. 144 1.2. Using Signatures in HTTP Responses 146 For high security transactions, having an additional signature on the 147 HTTP header allows a client to ensure that even if the transport 148 channel has been compromised, that the content of the messages have 149 not been compromised. This specification provides a HTTP Signature 150 Header mechanism that can be used by a client to authenticate the 151 sender of a message and ensure that particular headers have not been 152 modified in transit. 154 2. The Components of a Signature 156 There are a number of components in a signature that are common 157 between the 'Signature' HTTP Authentication Scheme and the 158 'Signature' HTTP Header. This section details the components of a 159 digital signature. 161 2.1. Signature Parameters 163 The following section details the signature parameters. 165 2.1.1. keyId 167 REQUIRED. The `keyId` field is an opaque string that the server can 168 use to look up the component they need to validate the signature. It 169 could be an SSH key fingerprint, a URL to machine-readable key data, 170 an LDAP DN, etc. Management of keys and assignment of `keyId` is out 171 of scope for this document. 173 2.1.2. algorithm 175 REQUIRED. The `algorithm` parameter is used to specify the digital 176 signature algorithm to use when generating the signature. Valid 177 values for this parameter can be found in the Signature Algorithms 178 registry located at http://www.iana.org/assignments/signature- 179 algorithms [4] and MUST NOT be marked "deprecated". 181 2.1.3. headers 183 OPTIONAL. The `headers` parameter is used to specify the list of 184 HTTP headers included when generating the signature for the message. 185 If specified, it should be a lowercased, quoted list of HTTP header 186 fields, separated by a single space character. If not specified, 187 implementations MUST operate as if the field were specified with a 188 single value, the `Date` header, in the list of HTTP headers. Note 189 that the list order is important, and MUST be specified in the order 190 the HTTP header field-value pairs are concatenated together during 191 signing. 193 2.1.4. signature 195 REQUIRED. The `signature` parameter is a base 64 encoded digital 196 signature, as described in RFC 4648 [RFC4648], Section 4 [5]. The 197 client uses the `algorithm` and `headers` signature parameters to 198 form a canonicalized `signing string`. This `signing string` is then 199 signed with the key associated with `keyId` and the algorithm 200 corresponding to `algorithm`. The `signature` parameter is then set 201 to the base 64 encoding of the signature. 203 2.2. Ambiguous Parameters 205 If any of the parameters listed above are erroneously duplicated in 206 the associated header field, then the last parameter defined MUST be 207 used. Any parameter that is not recognized as a parameter, or is not 208 well-formed, MUST be ignored. 210 2.3. Signature String Construction 212 In order to generate the string that is signed with a key, the client 213 MUST use the values of each HTTP header field in the `headers` 214 Signature parameter, in the order they appear in the `headers` 215 Signature parameter. It is out of scope for this document to dictate 216 what header fields an application will want to enforce, but 217 implementers SHOULD at minimum include the request target and Date 218 header fields. 220 To include the HTTP request target in the signature calculation, use 221 the special `(request-target)` header field name. 223 1. If the header field name is `(request-target)` then generate the 224 header field value by concatenating the lowercased :method, an 225 ASCII space, and the :path pseudo-headers (as specified in 226 HTTP/2, Section 8.1.2.3 [6]). 228 2. Create the header field string by concatenating the lowercased 229 header field name followed with an ASCII colon `:`, an ASCII 230 space ` `, and the header field value. Leading and trailing 231 optional whitespace (OWS) in the header field value MUST be 232 omitted (as specified in RFC7230 [RFC7230], Section 3.2.4 [7]). 233 If there are multiple instances of the same header field, all 234 header field values associated with the header field MUST be 235 concatenated, separated by a ASCII comma and an ASCII space `, `, 236 and used in the order in which they will appear in the 237 transmitted HTTP message. Any other modification to the header 238 field value MUST NOT be made. 240 3. If value is not the last value then append an ASCII newline `\n`. 242 To illustrate the rules specified above, assume a `headers` parameter 243 list with the value of `(request-target) host date cache-control 244 x-example` with the following HTTP request headers: 246 GET /foo HTTP/1.1 247 Host: example.org 248 Date: Tue, 07 Jun 2014 20:51:35 GMT 249 X-Example: Example header 250 with some whitespace. 251 Cache-Control: max-age=60 252 Cache-Control: must-revalidate 254 For the HTTP request headers above, the corresponding signature 255 string is: 257 (request-target): get /foo 258 host: example.org 259 date: Tue, 07 Jun 2014 20:51:35 GMT 260 cache-control: max-age=60, must-revalidate 261 x-example: Example header with some whitespace. 263 2.4. Creating a Signature 265 In order to create a signature, a client MUST: 267 1. Use the contents of the HTTP message, the `headers` value, and 268 the Signature String Construction algorithm to create the 269 signature string. 271 2. The `algorithm` and key associated with `keyId` must then be used 272 to generate a digital signature on the signature string. 274 3. The `signature` is then generated by base 64 encoding the output 275 of the digital signature algorithm. 277 For example, assume that the `algorithm` value was "rsa-sha256". 278 This would signal to the application that the data associated with 279 `keyId` is an RSA Private Key (as defined in RFC 3447 [RFC3447]), the 280 signature string hashing function is SHA-256, and the signing 281 algorithm is the one defined in RFC 3447 [RFC3447], 282 Section Section 8.2.1 [8]. The result of the signature creation 283 algorithm specified in RFC 3447 [RFC3447] should result in a binary 284 string, which is then base 64 encoded and placed into the `signature` 285 value. 287 2.5. Verifying a Signature 289 In order to verify a signature, a server MUST: 291 1. Use the received HTTP message, the `headers` value, and the 292 Signature String Construction algorithm to recreate the signature 293 string. 295 2. The `algorithm`, `keyId`, and base 64 decoded `signature` listed 296 in the signature parameters are then used to verify the 297 authenticity of the digital signature. 299 For example, assume that the `algorithm` value was "rsa-sha256". 300 This would signal to the application that the data associated with 301 `keyId` is an RSA Public Key (as defined in RFC 3447 [RFC3447]), the 302 signature string hashing function is SHA-256, and the `signature` 303 verification algorithm to use to verify the signature is the one 304 defined in RFC 3447 [RFC3447], Section Section 8.2.2 [9]. The result 305 of the signature verification algorithm specified in RFC 3447 306 [RFC3447] should result in a successful verification unless the 307 headers protected by the signature were tampered with in transit. 309 3. The 'Signature' HTTP Authentication Scheme 311 The "signature" authentication scheme is based on the model that the 312 client must authenticate itself with a digital signature produced by 313 either a private asymmetric key (e.g., RSA) or a shared symmetric key 314 (e.g., HMAC). The scheme is parameterized enough such that it is not 315 bound to any particular key type or signing algorithm. However, it 316 does explicitly assume that clients can send an HTTP `Date` header. 318 3.1. Authorization Header 320 The client is expected to send an Authorization header (as defined in 321 RFC 7235 [RFC7235], Section 4.1 [10]) where the "auth-scheme" is 322 "Signature" and the "auth-param" parameters meet the requirements 323 listed in Section 2: The Components of a Signature. 325 The rest if this section uses the following HTTP request as an 326 example. 328 POST /foo HTTP/1.1 329 Host: example.org 330 Date: Tue, 07 Jun 2014 20:51:35 GMT 331 Content-Type: application/json 332 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 333 Content-Length: 18 335 {"hello": "world"} 337 Note that the use of the `Digest` header field is per RFC 3230 338 [RFC3230], Section 4.3.2 [11] and is included merely as a 339 demonstration of how an implementer could include information about 340 the body of the message in the signature. The following sections 341 also assume that the "rsa-key-1" keyId refers to a private key known 342 to the client and a public key known to the server. The "hmac-key-1" 343 keyId refers to key known to the client and server. 345 3.1.1. Initiating Signature Authorization 347 A server may notify a client when a protected resource could be 348 accessed by authenticating itself to the server. To initiate this 349 process, the server will request that the client authenticate itself 350 via a 401 response code. The server may optionally specify which 351 HTTP headers it expects to be signed by specifying the `headers` 352 parameter in the WWW-Authenticate header. For example: 354 HTTP/1.1 401 Unauthorized 355 Date: Thu, 08 Jun 2014 18:32:30 GMT 356 Content-Length: 1234 357 Content-Type: text/html 358 WWW-Authenticate: Signature realm="Example",headers="(request-target) date" 360 ... 362 3.1.2. RSA Example 364 The authorization header and signature would be generated as: 366 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256", 367 headers="(request-target) host date digest content-length", 368 signature="Base64(RSA-SHA256(signing string))" 370 The client would compose the signing string as: 372 (request-target): post /foo\n 373 host: example.org\n 374 date: Tue, 07 Jun 2014 20:51:35 GMT\n 375 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 376 content-length: 18 378 Note that the '\n' symbols above are included to demonstrate where 379 the new line character should be inserted. There is no new line on 380 the final line of the signing string. 382 For an RSA-based signature, the authorization header and signature 383 would then be generated as: 385 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256", 386 headers="(request-target) host date digest content-length", 387 signature="Base64(RSA-SHA256(signing string))" 389 3.1.3. HMAC Example 391 For an HMAC-based signature without a list of headers specified, the 392 authorization header and signature would be generated as: 394 Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha256", 395 headers="(request-target) host date digest content-length", 396 signature="Base64(HMAC-SHA256(signing string))" 398 The only difference between the RSA Example and the HMAC Example is 399 the signature algorithm that is used. The client would compose the 400 signing string in the same way as the RSA Example above: 402 (request-target): post /foo\n 403 host: example.org\n 404 date: Tue, 07 Jun 2014 20:51:35 GMT\n 405 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 406 content-length: 18 408 4. The 'Signature' HTTP Header 410 The "signature" HTTP Header is based on the model that the sender 411 must authenticate itself with a digital signature produced by either 412 a private asymmetric key (e.g., RSA) or a shared symmetric key (e.g., 413 HMAC). The scheme is parameterized enough such that it is not bound 414 to any particular key type or signing algorithm. However, it does 415 explicitly assume that senders can send an HTTP `Date` header. 417 4.1. Signature Header 419 The sender is expected to transmit a header (as defined in RFC 7230 420 [RFC7230], Section 3.2 [12]) where the "field-name" is "Signature", 421 and the "field-value" contains one or more "auth-param"s (as defined 422 in RFC 7235 [RFC7235], Section 4.1 [13]) where the "auth-param" 423 parameters meet the requirements listed in Section 2: The Components 424 of a Signature. 426 The rest if this section uses the following HTTP request as an 427 example. 429 POST /foo HTTP/1.1 430 Host: example.org 431 Date: Tue, 07 Jun 2014 20:51:35 GMT 432 Content-Type: application/json 433 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 434 Content-Length: 18 436 {"hello": "world"} 438 The following sections assume that the "rsa-key-1" keyId refers to a 439 private key known to the client and a public key known to the server. 440 The "hmac-key-1" keyId refers to key known to the client and server. 442 4.1.1. RSA Example 444 The signature header and signature would be generated as: 446 Signature: keyId="rsa-key-1",algorithm="rsa-sha256", 447 headers="(request-target) host date digest content-length", 448 signature="Base64(RSA-SHA256(signing string))" 450 The client would compose the signing string as: 452 (request-target): post /foo\n 453 host: example.org\n 454 date: Tue, 07 Jun 2014 20:51:35 GMT\n 455 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 456 content-length: 18 458 Note that the '\n' symbols above are included to demonstrate where 459 the new line character should be inserted. There is no new line on 460 the final line of the signing string. 462 For an RSA-based signature, the authorization header and signature 463 would then be generated as: 465 Signature: keyId="rsa-key-1",algorithm="rsa-sha256", 466 headers="(request-target) host date digest content-length", 467 signature="Base64(RSA-SHA256(signing string))" 469 4.1.2. HMAC Example 471 For an HMAC-based signature without a list of headers specified, the 472 authorization header and signature would be generated as: 474 Signature: keyId="hmac-key-1",algorithm="hmac-sha256", 475 headers="(request-target) host date digest content-length", 476 signature="Base64(HMAC-SHA256(signing string))" 478 The only difference between the RSA Example and the HMAC Example is 479 the signature algorithm that is used. The client would compose the 480 signing string in the same way as the RSA Example above: 482 (request-target): post /foo\n 483 host: example.org\n 484 date: Tue, 07 Jun 2014 20:51:35 GMT\n 485 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 486 content-length: 18 488 5. References 490 5.1. Normative References 492 [I-D.ietf-jose-json-web-algorithms] 493 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 494 json-web-algorithms-20 (work in progress), January 2014. 496 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 497 Requirement Levels", BCP 14, RFC 2119, 498 DOI 10.17487/RFC2119, March 1997, 499 . 501 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 502 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 503 . 505 [RFC6376] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 506 "DomainKeys Identified Mail (DKIM) Signatures", STD 76, 507 RFC 6376, DOI 10.17487/RFC6376, September 2011, 508 . 510 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 511 Protocol (HTTP/1.1): Message Syntax and Routing", 512 RFC 7230, DOI 10.17487/RFC7230, June 2014, 513 . 515 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 516 Protocol (HTTP/1.1): Authentication", RFC 7235, 517 DOI 10.17487/RFC7235, June 2014, 518 . 520 5.2. Informative References 522 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 523 Leach, P., Luotonen, A., and L. Stewart, "HTTP 524 Authentication: Basic and Digest Access Authentication", 525 RFC 2617, DOI 10.17487/RFC2617, June 1999, 526 . 528 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 529 RFC 3230, DOI 10.17487/RFC3230, January 2002, 530 . 532 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 533 Standards (PKCS) #1: RSA Cryptography Specifications 534 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 535 2003, . 537 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 538 (TLS) Protocol Version 1.2", RFC 5246, 539 DOI 10.17487/RFC5246, August 2008, 540 . 542 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 543 RFC 6749, DOI 10.17487/RFC6749, October 2012, 544 . 546 5.3. URIs 548 [1] https://w3c-dvcg.github.io/ 550 [2] https://w3c-ccg.github.io/ 552 [3] mailto:public-credentials@w3.org 554 [4] http://www.iana.org/assignments/signature-algorithms 556 [5] http://tools.ietf.org/html/rfc4648#section-4 558 [6] https://tools.ietf.org/html/rfc7540#section-8.1.2.3 560 [7] http://tools.ietf.org/html/rfc7230#section-3.2.4 562 [8] http://tools.ietf.org/html/rfc3447#section-8.2.1 564 [9] http://tools.ietf.org/html/rfc3447#section-8.2.2 566 [10] http://tools.ietf.org/html/draft-ietf-rfc7235-auth-25#section- 567 4.1 569 [11] http://tools.ietf.org/html/rfc3230#section-4.3.2 571 [12] http://tools.ietf.org/html/rfc7230#section-3.2 573 [13] http://tools.ietf.org/html/rfc7235#section-4.1 575 [14] https://web-payments.org/specs/source/http-signatures-audit/ 577 [15] https://web-payments.org/specs/source/http-signature-nonces/ 579 [16] https://web-payments.org/specs/source/http-signature-trailers/ 581 [17] http://www.iana.org/assignments/http-auth-scheme-signature 583 [18] http://www.iana.org/assignments/http-authschemes 585 [19] http://www.iana.org/assignments/signature-algorithms 587 Appendix A. Security Considerations 589 There are a number of security considerations to take into account 590 when implementing or utilizing this specification. A thorough 591 security analysis of this protocol, including its strengths and 592 weaknesses, can be found in Security Considerations for HTTP 593 Signatures [14]. 595 Appendix B. Extensions 597 This specification was designed to be simple, modular, and 598 extensible. There are a number of other specifications that build on 599 this one. For example, the HTTP Signature Nonces [15] specification 600 details how to use HTTP Signatures over a non-secured channel like 601 HTTP and the HTTP Signature Trailers [16] specification explains how 602 to apply HTTP Signatures to streaming content. Developers that 603 desire more functionality than this specification provides are urged 604 to ensure that an extension specification doesn't already exist 605 before implementing a proprietary extension. 607 If extensions to this specification are made by adding new Signature 608 Parameters, those extension parameters MUST be registered in the 609 Signature Authentication Scheme Registry. The registry will be 610 created and maintained at (the suggested URI) 611 http://www.iana.org/assignments/http-auth-scheme-signature [17]. An 612 example entry in this registry is included below: 614 Signature Parameter: nonce 615 Reference to specification: [HTTP_AUTH_SIGNATURE_NONCE], Section XYZ. 616 Notes (optional): The HTTP Signature Nonces specification details 617 how to use HTTP Signatures over a unsecured channel like HTTP. 619 Appendix C. Test Values 621 The following test data uses the following RSA 2048-bit keys, which 622 we will refer to as `keyId=Test` in the following samples: 624 -----BEGIN PUBLIC KEY----- 625 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3 626 6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6 627 Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw 628 oYi+1hqp1fIekaxsyQIDAQAB 629 -----END PUBLIC KEY----- 631 -----BEGIN RSA PRIVATE KEY----- 632 MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF 633 NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F 634 UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB 635 AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA 636 QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK 637 kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg 638 f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u 639 412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc 640 mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7 641 kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA 642 gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW 643 G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI 644 7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA== 645 -----END RSA PRIVATE KEY----- 647 All examples use this request: 649 POST /foo?param=value&pet=dog HTTP/1.1 650 Host: example.com 651 Date: Sun, 05 Jan 2014 21:31:40 GMT 652 Content-Type: application/json 653 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 654 Content-Length: 18 656 {"hello": "world"} 658 C.1. Default Test 660 If a list of headers is not included, the date is the only header 661 that is signed by default. The string to sign would be: 663 date: Sun, 05 Jan 2014 21:31:40 GMT 665 The Authorization header would be: 667 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 668 signature="SjWJWbWN7i0wzBvtPl8rbASWz5xQW6mcJmn+ibttBqtifLN7Sazz 669 6m79cNfwwb8DMJ5cou1s7uEGKKCs+FLEEaDV5lp7q25WqS+lavg7T8hc0GppauB 670 6hbgEKTwblDHYGEtbGmtdHgVCk9SuS13F0hZ8FD0k/5OxEPXe5WozsbM=" 672 The Signature header would be: 674 Signature: keyId="Test",algorithm="rsa-sha256", 675 signature="SjWJWbWN7i0wzBvtPl8rbASWz5xQW6mcJmn+ibttBqtifLN7Sazz 676 6m79cNfwwb8DMJ5cou1s7uEGKKCs+FLEEaDV5lp7q25WqS+lavg7T8hc0GppauB 677 6hbgEKTwblDHYGEtbGmtdHgVCk9SuS13F0hZ8FD0k/5OxEPXe5WozsbM=" 679 C.2. Basic Test 681 The minimum recommended data to sign is the (request-target), host, 682 and date. In this case, the string to sign would be: 684 (request-target): post /foo?param=value&pet=dog 685 host: example.com 686 date: Sun, 05 Jan 2014 21:31:40 GMT 688 The Authorization header would be: 690 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 691 headers="(request-target) host date", signature="qdx+H7PHHDZgy4 692 y/Ahn9Tny9V3GP6YgBPyUXMmoxWtLbHpUnXS2mg2+SbrQDMCJypxBLSPQR2aAjn 693 7ndmw2iicw3HMbe8VfEdKFYRqzic+efkb3nndiv/x1xSHDJWeSWkx3ButlYSuBs 694 kLu6kd9Fswtemr3lgdDEmn04swr2Os0=" 696 C.3. All Headers Test 698 A strong signature including all of the headers and a digest of the 699 body of the HTTP request would result in the following signing 700 string: 702 (request-target): post /foo?param=value&pet=dog 703 host: example.com 704 date: Sun, 05 Jan 2014 21:31:40 GMT 705 content-type: application/json 706 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 707 content-length: 18 709 The Authorization header would be: 711 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 712 headers="(request-target) host date content-type digest content-length", 713 signature="vSdrb+dS3EceC9bcwHSo4MlyKS59iFIrhgYkz8+oVLEEzmYZZvRs 714 8rgOp+63LEM3v+MFHB32NfpB2bEKBIvB1q52LaEUHFv120V01IL+TAD48XaERZF 715 ukWgHoBTLMhYS2Gb51gWxpeIq8knRmPnYePbF5MOkR0Zkly4zKH7s1dE=" 717 The Signature header would be: 719 Signature: keyId="Test",algorithm="rsa-sha256", 720 headers="(request-target) host date content-type digest content-length", 721 signature="vSdrb+dS3EceC9bcwHSo4MlyKS59iFIrhgYkz8+oVLEEzmYZZvRs 722 8rgOp+63LEM3v+MFHB32NfpB2bEKBIvB1q52LaEUHFv120V01IL+TAD48XaERZF 723 ukWgHoBTLMhYS2Gb51gWxpeIq8knRmPnYePbF5MOkR0Zkly4zKH7s1dE=" 725 Appendix D. Acknowledgements 727 The editor would like to thank the following individuals for feedback 728 on and implementations of the specification (in alphabetical order): 729 Stephen Farrell, Phillip Hallam-Baker, Dave Lehn, Dave Longley, James 730 H. Manger, Mark Nottingham, Yoav Nir, Julian Reschke, and Michael 731 Richardson. 733 Appendix E. IANA Considerations 735 E.1. Signature Authentication Scheme 737 The following entry should be added to the Authentication Scheme 738 Registry located at http://www.iana.org/assignments/http-authschemes 739 [18] 741 Authentication Scheme Name: Signature 742 Reference: [RFC_THIS_DOCUMENT], Section 2. 744 Notes (optional): The Signature scheme is designed for clients to 745 authenticate themselves with a server. 747 E.2. Signature Algorithm Registry 749 The following initial entries should be added to the Signature 750 Algorithm Registry to be created and maintained at (the suggested 751 URI) http://www.iana.org/assignments/signature-algorithms [19]: 753 Editor's note: The references in this section are problematic as many 754 of the specifications that they refer to are too implementation 755 specific, rather than just pointing to the proper signature and 756 hashing specifications. A better approach might be just specifying 757 the signature and hashing function specifications, leaving 758 implementers to connect the dots (which are not that hard to 759 connect). 761 Algorithm Name: rsa-sha1 762 Reference: RFC 6376 [RFC6376], Section 3.3.1 763 Status: deprecated 765 Algorithm Name: rsa-sha256 766 Reference: RFC 6376 [RFC6376], Section 3.3.2 767 Status: active 769 Algorithm Name: hmac-sha256 770 Reference: HS256 in JOSE JSON Web Algorithms 771 [I-D.ietf-jose-json-web-algorithms], Section 3.2 772 Status: active 774 Algorithm Name: ecdsa-sha256 775 Reference: ES256 in JOSE JSON Web Algorithms 776 [I-D.ietf-jose-json-web-algorithms], Section 3.4 777 Status: active 779 Authors' Addresses 781 Mark Cavage 782 Oracle 783 500 Oracle Parkway 784 Redwood Shores, CA 94065 785 US 787 Phone: +1 415 400 0626 788 Email: mcavage@gmail.com 789 URI: http://www.oracle.com/ 790 Manu Sporny 791 Digital Bazaar 792 203 Roanoke Street W. 793 Blacksburg, VA 24060 794 US 796 Phone: +1 540 961 4469 797 Email: msporny@digitalbazaar.com 798 URI: http://manu.sporny.org/