idnits 2.17.1 draft-cavage-http-signatures-06.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], [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 (January 10, 2017) is 2661 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 23 -- Looks like a reference, but probably isn't: '2' on line 546 -- Looks like a reference, but probably isn't: '4' on line 550 -- Looks like a reference, but probably isn't: '5' on line 552 -- Looks like a reference, but probably isn't: '6' on line 554 -- Looks like a reference, but probably isn't: '7' on line 556 -- Looks like a reference, but probably isn't: '8' on line 558 -- Looks like a reference, but probably isn't: '9' on line 560 -- Looks like a reference, but probably isn't: '10' on line 562 -- Looks like a reference, but probably isn't: '11' on line 564 -- Looks like a reference, but probably isn't: '12' on line 566 -- Looks like a reference, but probably isn't: '3' on line 548 -- Looks like a reference, but probably isn't: '13' on line 576 -- Looks like a reference, but probably isn't: '14' on line 582 -- Looks like a reference, but probably isn't: '15' on line 584 == Unused Reference: 'RFC2119' is defined on line 494, 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 (==), 20 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: July 14, 2017 Digital Bazaar 6 January 10, 2017 8 Signing HTTP Messages 9 draft-cavage-http-signatures-06 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 part of the Web Payments [1] work. Feedback 24 related to this specification should be sent to public- 25 webpayments@w3.org [2]. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on July 14, 2017. 44 Copyright Notice 46 Copyright (c) 2017 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Using Signatures in HTTP Requests . . . . . . . . . . . . 3 60 1.2. Using Signatures in HTTP Responses . . . . . . . . . . . 4 61 2. The Components of a Signature . . . . . . . . . . . . . . . . 4 62 2.1. Signature Parameters . . . . . . . . . . . . . . . . . . 4 63 2.1.1. keyId . . . . . . . . . . . . . . . . . . . . . . . . 4 64 2.1.2. algorithm . . . . . . . . . . . . . . . . . . . . . . 4 65 2.1.3. headers . . . . . . . . . . . . . . . . . . . . . . . 4 66 2.1.4. signature . . . . . . . . . . . . . . . . . . . . . . 5 67 2.2. Ambiguous Parameters . . . . . . . . . . . . . . . . . . 5 68 2.3. Signature String Construction . . . . . . . . . . . . . . 5 69 2.4. Creating a Signature . . . . . . . . . . . . . . . . . . 6 70 2.5. Verifying a Signature . . . . . . . . . . . . . . . . . . 7 71 3. The 'Signature' HTTP Authentication Scheme . . . . . . . . . 7 72 3.1. Authorization Header . . . . . . . . . . . . . . . . . . 7 73 3.1.1. Initiating Signature Authorization . . . . . . . . . 8 74 3.1.2. RSA Example . . . . . . . . . . . . . . . . . . . . . 8 75 3.1.3. HMAC Example . . . . . . . . . . . . . . . . . . . . 9 76 4. The 'Signature' HTTP Header . . . . . . . . . . . . . . . . . 9 77 4.1. Signature Header . . . . . . . . . . . . . . . . . . . . 10 78 4.1.1. RSA Example . . . . . . . . . . . . . . . . . . . . . 10 79 4.1.2. HMAC Example . . . . . . . . . . . . . . . . . . . . 11 80 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 81 5.1. Normative References . . . . . . . . . . . . . . . . . . 11 82 5.2. Informative References . . . . . . . . . . . . . . . . . 12 83 5.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12 84 Appendix A. Security Considerations . . . . . . . . . . . . . . 13 85 Appendix B. Extensions . . . . . . . . . . . . . . . . . . . . . 13 86 Appendix C. Test Values . . . . . . . . . . . . . . . . . . . . 14 87 C.1. Default Test . . . . . . . . . . . . . . . . . . . . . . 14 88 C.2. Basic Test . . . . . . . . . . . . . . . . . . . . . . . 15 89 C.3. All Headers Test . . . . . . . . . . . . . . . . . . . . 15 90 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 16 91 Appendix E. IANA Considerations . . . . . . . . . . . . . . . . 16 92 E.1. Signature Authentication Scheme . . . . . . . . . . . . . 16 93 E.2. Signature Algorithm Registry . . . . . . . . . . . . . . 16 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 96 1. Introduction 98 This protocol extension is intended to provide a simple and standard 99 way for clients to sign HTTP messages. 101 HTTP Authentication [RFC2617] defines Basic and Digest authentication 102 mechanisms, TLS 1.2 [RFC5246] defines cryptographically strong 103 transport layer security, and OAuth 2.0 [RFC6749] provides a fully- 104 specified alternative for authorization of web service requests. 105 Each of these approaches are employed on the Internet today with 106 varying degrees of protection. However, none of these schemes are 107 designed to cryptographically sign the HTTP messages themselves, 108 which is required in order to ensure end-to-end message integrity. 109 An added benefit of signing the HTTP message for the purposes of end- 110 to-end message integrity is that the client can be authenticated 111 using the same mechanism without the need for multiple round-trips. 113 Several web service providers have invented their own schemes for 114 signing HTTP messages, but to date, none have been standardized. 115 While there are no techniques in this proposal that are novel beyond 116 the previous art, it is useful to standardize a simple and 117 cryptographically strong mechanism for digitally signing HTTP 118 messages. 120 1.1. Using Signatures in HTTP Requests 122 It is common practice to protect sensitive website API functionality 123 via authentication mechanisms. Often, the entity accessing these 124 APIs is a piece of automated software outside of an interactive human 125 session. While there are mechanisms like OAuth and API secrets that 126 are used to grant API access, each have their weaknesses such as 127 unnecessary complexity for particular use cases or the use of shared 128 secrets which may not be acceptable to an implementer. 130 Digital signatures are widely used to provide authentication without 131 the need for shared secrets. They also do not require a round-trip 132 in order to authenticate the client. A server need only have a 133 mapping between the key being used to sign the content and the 134 authorized entity to verify that a message was signed by that entity. 136 This specification provides two mechanisms that can be used by a 137 server to authenticate a client. The first is the 'Signature' HTTP 138 Authentication Scheme, which may be used for interactive sessions. 139 The second is the Signature HTTP Header, which is typically used by 140 automated software agents. 142 1.2. Using Signatures in HTTP Responses 144 For high security transactions, having an additional signature on the 145 HTTP header allows a client to ensure that even if the transport 146 channel has been compromised, that the content of the messages have 147 not been compromised. This specification provides a HTTP Signature 148 Header mechanism that can be used by a client to authenticate the 149 sender of a message and ensure that particular headers have not been 150 modified in transit. 152 2. The Components of a Signature 154 There are a number of components in a signature that are common 155 between the 'Signature' HTTP Authentication Scheme and the 156 'Signature' HTTP Header. This section details the components of a 157 digital signature. 159 2.1. Signature Parameters 161 The following section details the signature parameters. 163 2.1.1. keyId 165 REQUIRED. The `keyId` field is an opaque string that the server can 166 use to look up the component they need to validate the signature. It 167 could be an SSH key fingerprint, a URL to machine-readable key data, 168 an LDAP DN, etc. Management of keys and assignment of `keyId` is out 169 of scope for this document. 171 2.1.2. algorithm 173 REQUIRED. The `algorithm` parameter is used to specify the digital 174 signature algorithm to use when generating the signature. Valid 175 values for this parameter can be found in the Signature Algorithms 176 registry located at http://www.iana.org/assignments/signature- 177 algorithms and MUST NOT be marked "deprecated". 179 2.1.3. headers 181 OPTIONAL. The `headers` parameter is used to specify the list of 182 HTTP headers included when generating the signature for the message. 183 If specified, it should be a lowercased, quoted list of HTTP header 184 fields, separated by a single space character. If not specified, 185 implementations MUST operate as if the field were specified with a 186 single value, the `Date` header, in the list of HTTP headers. Note 187 that the list order is important, and MUST be specified in the order 188 the HTTP header field-value pairs are concatenated together during 189 signing. 191 2.1.4. signature 193 REQUIRED. The `signature` parameter is a base 64 encoded digital 194 signature, as described in RFC 4648 [RFC4648], Section 4 [4]. The 195 client uses the `algorithm` and `headers` signature parameters to 196 form a canonicalized `signing string`. This `signing string` is then 197 signed with the key associated with `keyId` and the algorithm 198 corresponding to `algorithm`. The `signature` parameter is then set 199 to the base 64 encoding of the signature. 201 2.2. Ambiguous Parameters 203 If any of the parameters listed above are erroneously duplicated in 204 the associated header field, then the last parameter defined MUST be 205 used. Any parameter that is not recognized as a parameter, or is not 206 well-formed, MUST be ignored. 208 2.3. Signature String Construction 210 In order to generate the string that is signed with a key, the client 211 MUST use the values of each HTTP header field in the `headers` 212 Signature parameter, in the order they appear in the `headers` 213 Signature parameter. It is out of scope for this document to dictate 214 what header fields an application will want to enforce, but 215 implementers SHOULD at minimum include the request target and Date 216 header fields. 218 To include the HTTP request target in the signature calculation, use 219 the special `(request-target)` header field name. 221 1. If the header field name is `(request-target)` then generate the 222 header field value by concatenating the lowercased :method, an 223 ASCII space, and the :path pseudo-headers (as specified in 224 HTTP/2, Section 8.1.2.3 [5]). 226 2. Create the header field string by concatenating the lowercased 227 header field name followed with an ASCII colon `:`, an ASCII 228 space ` `, and the header field value. Leading and trailing 229 optional whitespace (OWS) in the header field value MUST be 230 omitted (as specified in RFC7230 [RFC7230], Section 3.2.4 [6]). 231 If there are multiple instances of the same header field, all 232 header field values associated with the header field MUST be 233 concatenated, separated by a ASCII comma and an ASCII space `, `, 234 and used in the order in which they will appear in the 235 transmitted HTTP message. Any other modification to the header 236 field value MUST NOT be made. 238 3. If value is not the last value then append an ASCII newline `\n`. 240 To illustrate the rules specified above, assume a `headers` parameter 241 list with the value of `(request-target) host date cache-control 242 x-example` with the following HTTP request headers: 244 GET /foo HTTP/1.1 245 Host: example.org 246 Date: Tue, 07 Jun 2014 20:51:35 GMT 247 X-Example: Example header 248 with some whitespace. 249 Cache-Control: max-age=60 250 Cache-Control: must-revalidate 252 For the HTTP request headers above, the corresponding signature 253 string is: 255 (request-target): get /foo 256 host: example.org 257 date: Tue, 07 Jun 2014 20:51:35 GMT 258 cache-control: max-age=60, must-revalidate 259 x-example: Example header with some whitespace. 261 2.4. Creating a Signature 263 In order to create a signature, a client MUST: 265 1. Use the contents of the HTTP message, the `headers` value, and 266 the Signature String Construction algorithm to create the 267 signature string. 269 2. The `algorithm` and key associated with `keyId` must then be used 270 to generate a digital signature on the signature string. 272 3. The `signature` is then generated by base 64 encoding the output 273 of the digital signature algorithm. 275 For example, assume that the `algorithm` value was "rsa-sha256". 276 This would signal to the application that the data associated with 277 `keyId` is an RSA Private Key (as defined in RFC 3447 [RFC3447]), the 278 signature string hashing function is SHA-256, and the signing 279 algorithm is the one defined in RFC 3447 [RFC3447], 280 Section Section 8.2.1 [7]. The result of the signature creation 281 algorithm specified in RFC 3447 [RFC3447] should result in a binary 282 string, which is then base 64 encoded and placed into the `signature` 283 value. 285 2.5. Verifying a Signature 287 In order to verify a signature, a server MUST: 289 1. Use the received HTTP message, the `headers` value, and the 290 Signature String Construction algorithm to recreate the signature 291 string. 293 2. The `algorithm`, `keyId`, and base 64 decoded `signature` listed 294 in the signature parameters are then used to verify the 295 authenticity of the digital signature. 297 For example, assume that the `algorithm` value was "rsa-sha256". 298 This would signal to the application that the data associated with 299 `keyId` is an RSA Public Key (as defined in RFC 3447 [RFC3447]), the 300 signature string hashing function is SHA-256, and the `signature` 301 verification algorithm to use to verify the signature is the one 302 defined in RFC 3447 [RFC3447], Section Section 8.2.2 [8]. The result 303 of the signature verification algorithm specified in RFC 3447 304 [RFC3447] should result in a successful verification unless the 305 headers protected by the signature were tampered with in transit. 307 3. The 'Signature' HTTP Authentication Scheme 309 The "signature" authentication scheme is based on the model that the 310 client must authenticate itself with a digital signature produced by 311 either a private asymmetric key (e.g., RSA) or a shared symmetric key 312 (e.g., HMAC). The scheme is parameterized enough such that it is not 313 bound to any particular key type or signing algorithm. However, it 314 does explicitly assume that clients can send an HTTP `Date` header. 316 3.1. Authorization Header 318 The client is expected to send an Authorization header (as defined in 319 RFC 7235 [RFC7235], Section 4.1 [9]) where the "auth-scheme" is 320 "Signature" and the "auth-param" parameters meet the requirements 321 listed in Section 2: The Components of a Signature. 323 The rest if this section uses the following HTTP request as an 324 example. 326 POST /foo HTTP/1.1 327 Host: example.org 328 Date: Tue, 07 Jun 2014 20:51:35 GMT 329 Content-Type: application/json 330 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 331 Content-Length: 18 333 {"hello": "world"} 335 Note that the use of the `Digest` header field is per RFC 3230 336 [RFC3230], Section 4.3.2 [10] and is included merely as a 337 demonstration of how an implementer could include information about 338 the body of the message in the signature. The following sections 339 also assume that the "rsa-key-1" keyId refers to a private key known 340 to the client and a public key known to the server. The "hmac-key-1" 341 keyId refers to key known to the client and server. 343 3.1.1. Initiating Signature Authorization 345 A server may notify a client when a protected resource could be 346 accessed by authenticating itself to the server. To initiate this 347 process, the server will request that the client authenticate itself 348 via a 401 response code. The server may optionally specify which 349 HTTP headers it expects to be signed by specifying the `headers` 350 parameter in the WWW-Authenticate header. For example: 352 HTTP/1.1 401 Unauthorized 353 Date: Thu, 08 Jun 2014 18:32:30 GMT 354 Content-Length: 1234 355 Content-Type: text/html 356 WWW-Authenticate: Signature realm="Example",headers="(request-target) date" 358 ... 360 3.1.2. RSA Example 362 The authorization header and signature would be generated as: 364 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256", 365 headers="(request-target) host date digest content-length", 366 signature="Base64(RSA-SHA256(signing string))" 368 The client would compose the signing string as: 370 (request-target): post /foo\n 371 host: example.org\n 372 date: Tue, 07 Jun 2014 20:51:35 GMT\n 373 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 374 content-length: 18 376 Note that the '\n' symbols above are included to demonstrate where 377 the new line character should be inserted. There is no new line on 378 the final line of the signing string. 380 For an RSA-based signature, the authorization header and signature 381 would then be generated as: 383 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256", 384 headers="(request-target) host date digest content-length", 385 signature="Base64(RSA-SHA256(signing string))" 387 3.1.3. HMAC Example 389 For an HMAC-based signature without a list of headers specified, the 390 authorization header and signature would be generated as: 392 Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha256", 393 headers="(request-target) host date digest content-length", 394 signature="Base64(HMAC-SHA256(signing string))" 396 The only difference between the RSA Example and the HMAC Example is 397 the signature algorithm that is used. The client would compose the 398 signing string in the same way as the RSA Example above: 400 (request-target): post /foo\n 401 host: example.org\n 402 date: Tue, 07 Jun 2014 20:51:35 GMT\n 403 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 404 content-length: 18 406 4. The 'Signature' HTTP Header 408 The "signature" HTTP Header is based on the model that the sender 409 must authenticate itself with a digital signature produced by either 410 a private asymmetric key (e.g., RSA) or a shared symmetric key (e.g., 411 HMAC). The scheme is parameterized enough such that it is not bound 412 to any particular key type or signing algorithm. However, it does 413 explicitly assume that senders can send an HTTP `Date` header. 415 4.1. Signature Header 417 The sender is expected to transmit a header (as defined in RFC 7230 418 [RFC7230], Section 3.2 [11]) where the "field-name" is "Signature", 419 and the "field-value" contains one or more "auth-param"s (as defined 420 in RFC 7235 [RFC7235], Section 4.1 [12]) where the "auth-param" 421 parameters meet the requirements listed in Section 2: The Components 422 of a Signature. 424 The rest if this section uses the following HTTP request as an 425 example. 427 POST /foo HTTP/1.1 428 Host: example.org 429 Date: Tue, 07 Jun 2014 20:51:35 GMT 430 Content-Type: application/json 431 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 432 Content-Length: 18 434 {"hello": "world"} 436 The following sections assume that the "rsa-key-1" keyId refers to a 437 private key known to the client and a public key known to the server. 438 The "hmac-key-1" keyId refers to key known to the client and server. 440 4.1.1. RSA Example 442 The signature header and signature would be generated as: 444 Signature: keyId="rsa-key-1",algorithm="rsa-sha256", 445 headers="(request-target) host date digest content-length", 446 signature="Base64(RSA-SHA256(signing string))" 448 The client would compose the signing string as: 450 (request-target): post /foo\n 451 host: example.org\n 452 date: Tue, 07 Jun 2014 20:51:35 GMT\n 453 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 454 content-length: 18 456 Note that the '\n' symbols above are included to demonstrate where 457 the new line character should be inserted. There is no new line on 458 the final line of the signing string. 460 For an RSA-based signature, the authorization header and signature 461 would then be generated as: 463 Signature: keyId="rsa-key-1",algorithm="rsa-sha256", 464 headers="(request-target) host date digest content-length", 465 signature="Base64(RSA-SHA256(signing string))" 467 4.1.2. HMAC Example 469 For an HMAC-based signature without a list of headers specified, the 470 authorization header and signature would be generated as: 472 Signature: keyId="hmac-key-1",algorithm="hmac-sha256", 473 headers="(request-target) host date digest content-length", 474 signature="Base64(HMAC-SHA256(signing string))" 476 The only difference between the RSA Example and the HMAC Example is 477 the signature algorithm that is used. The client would compose the 478 signing string in the same way as the RSA Example above: 480 (request-target): post /foo\n 481 host: example.org\n 482 date: Tue, 07 Jun 2014 20:51:35 GMT\n 483 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 484 content-length: 18 486 5. References 488 5.1. Normative References 490 [I-D.ietf-jose-json-web-algorithms] 491 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 492 json-web-algorithms-20 (work in progress), January 2014. 494 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 495 Requirement Levels", BCP 14, RFC 2119, 496 DOI 10.17487/RFC2119, March 1997, 497 . 499 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 500 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 501 . 503 [RFC6376] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 504 "DomainKeys Identified Mail (DKIM) Signatures", STD 76, 505 RFC 6376, DOI 10.17487/RFC6376, September 2011, 506 . 508 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 509 Protocol (HTTP/1.1): Message Syntax and Routing", 510 RFC 7230, DOI 10.17487/RFC7230, June 2014, 511 . 513 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 514 Protocol (HTTP/1.1): Authentication", RFC 7235, 515 DOI 10.17487/RFC7235, June 2014, 516 . 518 5.2. Informative References 520 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 521 Leach, P., Luotonen, A., and L. Stewart, "HTTP 522 Authentication: Basic and Digest Access Authentication", 523 RFC 2617, DOI 10.17487/RFC2617, June 1999, 524 . 526 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 527 RFC 3230, DOI 10.17487/RFC3230, January 2002, 528 . 530 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 531 Standards (PKCS) #1: RSA Cryptography Specifications 532 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 533 2003, . 535 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 536 (TLS) Protocol Version 1.2", RFC 5246, 537 DOI 10.17487/RFC5246, August 2008, 538 . 540 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 541 RFC 6749, DOI 10.17487/RFC6749, October 2012, 542 . 544 5.3. URIs 546 [2] http://tools.ietf.org/html/rfc4648#section-4 548 [3] https://tools.ietf.org/html/rfc7540#section-8.1.2.3 550 [4] http://tools.ietf.org/html/rfc7230#section-3.2.4 552 [5] http://tools.ietf.org/html/rfc3447#section-8.2.1 554 [6] http://tools.ietf.org/html/rfc3447#section-8.2.2 556 [7] http://tools.ietf.org/html/draft-ietf-rfc7235-auth-25#section-4.1 558 [8] http://tools.ietf.org/html/rfc3230#section-4.3.2 560 [9] http://tools.ietf.org/html/rfc7230#section-3.2 562 [10] http://tools.ietf.org/html/rfc7235#section-4.1 564 [11] https://web-payments.org/specs/source/http-signatures-audit/ 566 [12] https://web-payments.org/specs/source/http-signature-nonces/ 568 [13] https://web-payments.org/specs/source/http-signature-trailers/ 570 Appendix A. Security Considerations 572 There are a number of security considerations to take into account 573 when implementing or utilizing this specification. A thorough 574 security analysis of this protocol, including its strengths and 575 weaknesses, can be found in Security Considerations for HTTP 576 Signatures [13]. 578 Appendix B. Extensions 580 This specification was designed to be simple, modular, and 581 extensible. There are a number of other specifications that build on 582 this one. For example, the HTTP Signature Nonces [14] specification 583 details how to use HTTP Signatures over a non-secured channel like 584 HTTP and the HTTP Signature Trailers [15] specification explains how 585 to apply HTTP Signatures to streaming content. Developers that 586 desire more functionality than this specification provides are urged 587 to ensure that an extension specification doesn't already exist 588 before implementing a proprietary extension. 590 If extensions to this specification are made by adding new Signature 591 Parameters, those extension parameters MUST be registered in the 592 Signature Authentication Scheme Registry. The registry will be 593 created and maintained at (the suggested URI) 594 http://www.iana.org/assignments/http-auth-scheme-signature . An 595 example entry in this registry is included below: 597 Signature Parameter: nonce 598 Reference to specification: [HTTP_AUTH_SIGNATURE_NONCE], Section XYZ. 599 Notes (optional): The HTTP Signature Nonces specification details 600 how to use HTTP Signatures over a unsecured channel like HTTP. 602 Appendix C. Test Values 604 The following test data uses the following RSA 2048-bit keys, which 605 we will refer to as `keyId=Test` in the following samples: 607 -----BEGIN PUBLIC KEY----- 608 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3 609 6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6 610 Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw 611 oYi+1hqp1fIekaxsyQIDAQAB 612 -----END PUBLIC KEY----- 614 -----BEGIN RSA PRIVATE KEY----- 615 MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF 616 NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F 617 UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB 618 AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA 619 QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK 620 kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg 621 f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u 622 412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc 623 mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7 624 kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA 625 gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW 626 G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI 627 7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA== 628 -----END RSA PRIVATE KEY----- 630 All examples use this request: 632 POST /foo?param=value&pet=dog HTTP/1.1 633 Host: example.com 634 Date: Thu, 05 Jan 2014 21:31:40 GMT 635 Content-Type: application/json 636 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 637 Content-Length: 18 639 {"hello": "world"} 641 C.1. Default Test 643 If a list of headers is not included, the date is the only header 644 that is signed by default. The string to sign would be: 646 date: Thu, 05 Jan 2014 21:31:40 GMT 648 The Authorization header would be: 650 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 651 signature="ATp0r26dbMIxOopqw0OfABDT7CKMIoENumuruOtarj8n/97Q3htH 652 FYpH8yOSQk3Z5zh8UxUym6FYTb5+A0Nz3NRsXJibnYi7brE/4tx5But9kkFGzG+ 653 xpUmimN4c3TMN7OFH//+r8hBf7BT9/GmHDUVZT2JzWGLZES2xDOUuMtA=" 655 The Signature header would be: 657 Signature: keyId="Test",algorithm="rsa-sha256", 658 signature="ATp0r26dbMIxOopqw0OfABDT7CKMIoENumuruOtarj8n/97Q3htH 659 FYpH8yOSQk3Z5zh8UxUym6FYTb5+A0Nz3NRsXJibnYi7brE/4tx5But9kkFGzG+ 660 xpUmimN4c3TMN7OFH//+r8hBf7BT9/GmHDUVZT2JzWGLZES2xDOUuMtA=" 662 C.2. Basic Test 664 The minimum recommended data to sign is the (request-target), host, 665 and date. In this case, the string to sign would be: 667 (request-target): post /foo?param=value&pet=dog 668 host: example.com 669 date: Thu, 05 Jan 2014 21:31:40 GMT 671 The Authorization header would be: 673 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 674 headers="(request-target) host date", signature="KcLSABBj/m3v2Dhxi 675 CKJmzYJvnx74tDO1SaURD8Dr8XpugN5wpy8iBVJtpkHUIp4qBYpzx2QvD16t8X 676 0BUMiKc53Age+baQFWwb2iYYJzvuUL+krrl/Q7H6fPBADBsHqEZ7IE8rR0Ys3l 677 b7J5A6VB9J/4yVTRiBcxTypW/mpr5w=" 679 C.3. All Headers Test 681 A strong signature including all of the headers and a digest of the 682 body of the HTTP request would result in the following signing 683 string: 685 (request-target): post /foo?param=value&pet=dog 686 host: example.com 687 date: Thu, 05 Jan 2014 21:31:40 GMT 688 content-type: application/json 689 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 690 content-length: 18 692 The Authorization header would be: 694 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 695 headers="(request-target) host date content-type digest content-length", 696 signature="jgSqYK0yKclIHfF9zdApVEbDp5eqj8C4i4X76pE+XHoxugXv7q 697 nVrGR+30bmBgtpR39I4utq17s9ghz/2QFVxlnToYAvbSVZJ9ulLd1HQBugO0j 698 Oyn9sXOtcN7uNHBjqNCqUsnt0sw/cJA6B6nJZpyNqNyAXKdxZZItOuhIs78w=" 700 The Signature header would be: 702 Signature: keyId="Test",algorithm="rsa-sha256", 703 headers="(request-target) host date content-type digest content-length", 704 signature="jgSqYK0yKclIHfF9zdApVEbDp5eqj8C4i4X76pE+XHoxugXv7q 705 nVrGR+30bmBgtpR39I4utq17s9ghz/2QFVxlnToYAvbSVZJ9ulLd1HQBugO0j 706 Oyn9sXOtcN7uNHBjqNCqUsnt0sw/cJA6B6nJZpyNqNyAXKdxZZItOuhIs78w=" 708 Appendix D. Acknowledgements 710 The editor would like to thank the following individuals for feedback 711 on and implementations of the specification (in alphabetical order): 712 Stephen Farrell, Phillip Hallam-Baker, Dave Lehn, Dave Longley, James 713 H. Manger, Mark Nottingham, Yoav Nir, Julian Reschke, and Michael 714 Richardson. 716 Appendix E. IANA Considerations 718 E.1. Signature Authentication Scheme 720 The following entry should be added to the Authentication Scheme 721 Registry located at http://www.iana.org/assignments/http-authschemes 723 Authentication Scheme Name: Signature 724 Reference: [RFC_THIS_DOCUMENT], Section 2. 725 Notes (optional): The Signature scheme is designed for clients to 726 authenticate themselves with a server. 728 E.2. Signature Algorithm Registry 730 The following initial entries should be added to the Signature 731 Algorithm Registry to be created and maintained at (the suggested 732 URI) http://www.iana.org/assignments/signature-algorithms : 734 Editor's note: The references in this section are problematic as many 735 of the specifications that they refer to are too implementation 736 specific, rather than just pointing to the proper signature and 737 hashing specifications. A better approach might be just specifying 738 the signature and hashing function specifications, leaving 739 implementers to connect the dots (which are not that hard to 740 connect). 742 Algorithm Name: rsa-sha1 743 Reference: RFC 6376 [RFC6376], Section 3.3.1 744 Status: deprecated 746 Algorithm Name: rsa-sha256 747 Reference: RFC 6376 [RFC6376], Section 3.3.2 748 Status: active 750 Algorithm Name: hmac-sha256 751 Reference: HS256 in JOSE JSON Web Algorithms 752 [I-D.ietf-jose-json-web-algorithms], Section 3.2 753 Status: active 755 Algorithm Name: ecdsa-sha256 756 Reference: ES256 in JOSE JSON Web Algorithms 757 [I-D.ietf-jose-json-web-algorithms], Section 3.4 758 Status: active 760 Authors' Addresses 762 Mark Cavage 763 Oracle 764 500 Oracle Parkway 765 Redwood Shores, CA 94065 766 US 768 Phone: +1 415 400 0626 769 Email: mcavage@gmail.com 770 URI: http://www.oracle.com/ 772 Manu Sporny 773 Digital Bazaar 774 203 Roanoke Street W. 775 Blacksburg, VA 24060 776 US 778 Phone: +1 540 961 4469 779 Email: msporny@digitalbazaar.com 780 URI: http://manu.sporny.org/