idnits 2.17.1 draft-cavage-http-signatures-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document 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. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. 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 (October 7, 2015) is 3123 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 537 -- Looks like a reference, but probably isn't: '4' on line 542 -- Looks like a reference, but probably isn't: '5' on line 544 -- Looks like a reference, but probably isn't: '6' on line 546 -- Looks like a reference, but probably isn't: '7' on line 548 -- Looks like a reference, but probably isn't: '8' on line 550 -- Looks like a reference, but probably isn't: '9' on line 552 -- Looks like a reference, but probably isn't: '10' on line 554 -- Looks like a reference, but probably isn't: '11' on line 556 -- Looks like a reference, but probably isn't: '12' on line 558 -- Looks like a reference, but probably isn't: '3' on line 539 -- Looks like a reference, but probably isn't: '13' on line 568 -- Looks like a reference, but probably isn't: '14' on line 574 -- Looks like a reference, but probably isn't: '15' on line 576 == 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 (~~), 5 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: April 9, 2016 Digital Bazaar 6 October 7, 2015 8 Signing HTTP Messages 9 draft-cavage-http-signatures-05 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 April 9, 2016. 44 Copyright Notice 46 Copyright (c) 2015 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 . . . . . . . . . . . . . . . . . . . . 13 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.1 [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, March 1997. 497 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 498 Encodings", RFC 4648, October 2006. 500 [RFC6376] Crocker, D., Hansen, T., and M. Kucherawy, "DomainKeys 501 Identified Mail (DKIM) Signatures", STD 76, RFC 6376, 502 September 2011. 504 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 505 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 506 7230, DOI 10.17487/RFC7230, June 2014, 507 . 509 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 510 Protocol (HTTP/1.1): Authentication", RFC 7235, DOI 511 10.17487/RFC7235, June 2014, 512 . 514 5.2. Informative References 516 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 517 Leach, P., Luotonen, A., and L. Stewart, "HTTP 518 Authentication: Basic and Digest Access Authentication", 519 RFC 2617, June 1999. 521 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", RFC 522 3230, January 2002. 524 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 525 Standards (PKCS) #1: RSA Cryptography Specifications 526 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 527 2003, . 529 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 530 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 532 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 533 6749, October 2012. 535 5.3. URIs 537 [2] http://tools.ietf.org/html/rfc4648#section-4 539 [3] http://tools.ietf.org/html/draft-ietf-httpbis-http2-13#section- 540 8.1.2.1 542 [4] http://tools.ietf.org/html/rfc7230#section-3.2.4 544 [5] http://tools.ietf.org/html/rfc3447#section-8.2.1 546 [6] http://tools.ietf.org/html/rfc3447#section-8.2.2 548 [7] http://tools.ietf.org/html/draft-ietf-rfc7235-auth-25#section-4.1 550 [8] http://tools.ietf.org/html/rfc3230#section-4.3.2 552 [9] http://tools.ietf.org/html/rfc7230#section-3.2 554 [10] http://tools.ietf.org/html/rfc7235#section-4.1 556 [11] https://web-payments.org/specs/source/http-signatures-audit/ 558 [12] https://web-payments.org/specs/source/http-signature-nonces/ 560 [13] https://web-payments.org/specs/source/http-signature-trailers/ 562 Appendix A. Security Considerations 564 There are a number of security considerations to take into account 565 when implementing or utilizing this specification. A thorough 566 security analysis of this protocol, including its strengths and 567 weaknesses, can be found in Security Considerations for HTTP 568 Signatures [13]. 570 Appendix B. Extensions 572 This specification was designed to be simple, modular, and 573 extensible. There are a number of other specifications that build on 574 this one. For example, the HTTP Signature Nonces [14] specification 575 details how to use HTTP Signatures over a non-secured channel like 576 HTTP and the HTTP Signature Trailers [15] specification explains how 577 to apply HTTP Signatures to streaming content. Developers that 578 desire more functionality than this specification provides are urged 579 to ensure that an extension specification doesn't already exist 580 before implementing a proprietary extension. 582 If extensions to this specification are made by adding new Signature 583 Parameters, those extension parameters MUST be registered in the 584 Signature Authentication Scheme Registry. The registry will be 585 created and maintained at (the suggested URI) 586 http://www.iana.org/assignments/http-auth-scheme-signature . An 587 example entry in this registry is included below: 589 Signature Parameter: nonce 590 Reference to specification: [HTTP_AUTH_SIGNATURE_NONCE], Section XYZ. 591 Notes (optional): The HTTP Signature Nonces specification details 592 how to use HTTP Signatures over a unsecured channel like HTTP. 594 Appendix C. Test Values 596 The following test data uses the following RSA 2048-bit keys, which 597 we will refer to as `keyId=Test` in the following samples: 599 -----BEGIN PUBLIC KEY----- 600 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3 601 6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6 602 Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw 603 oYi+1hqp1fIekaxsyQIDAQAB 604 -----END PUBLIC KEY----- 605 -----BEGIN RSA PRIVATE KEY----- 606 MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF 607 NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F 608 UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB 609 AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA 610 QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK 611 kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg 612 f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u 613 412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc 614 mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7 615 kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA 616 gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW 617 G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI 618 7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA== 619 -----END RSA PRIVATE KEY----- 621 All examples use this request: 623 POST /foo?param=value&pet=dog HTTP/1.1 624 Host: example.com 625 Date: Thu, 05 Jan 2014 21:31:40 GMT 626 Content-Type: application/json 627 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 628 Content-Length: 18 630 {"hello": "world"} 632 C.1. Default Test 634 If a list of headers is not included, the date is the only header 635 that is signed by default. The string to sign would be: 637 date: Thu, 05 Jan 2014 21:31:40 GMT 639 The Authorization header would be: 641 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 642 signature="ATp0r26dbMIxOopqw0OfABDT7CKMIoENumuruOtarj8n/97Q3htH 643 FYpH8yOSQk3Z5zh8UxUym6FYTb5+A0Nz3NRsXJibnYi7brE/4tx5But9kkFGzG+ 644 xpUmimN4c3TMN7OFH//+r8hBf7BT9/GmHDUVZT2JzWGLZES2xDOUuMtA=" 646 The Signature header would be: 648 Signature: keyId="Test",algorithm="rsa-sha256", 649 signature="ATp0r26dbMIxOopqw0OfABDT7CKMIoENumuruOtarj8n/97Q3htH 650 FYpH8yOSQk3Z5zh8UxUym6FYTb5+A0Nz3NRsXJibnYi7brE/4tx5But9kkFGzG+ 651 xpUmimN4c3TMN7OFH//+r8hBf7BT9/GmHDUVZT2JzWGLZES2xDOUuMtA=" 653 C.2. Basic Test 655 The minimum recommended data to sign is the (request-target), host, 656 and date. In this case, the string to sign would be: 658 (request-target): post /foo?param=value&pet=dog 659 host: example.com 660 date: Thu, 05 Jan 2014 21:31:40 GMT 662 The Authorization header would be: 664 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 665 headers="(request-target) host date", signature="KcLSABBj/m3v2Dhxi 666 CKJmzYJvnx74tDO1SaURD8Dr8XpugN5wpy8iBVJtpkHUIp4qBYpzx2QvD16t8X 667 0BUMiKc53Age+baQFWwb2iYYJzvuUL+krrl/Q7H6fPBADBsHqEZ7IE8rR0Ys3l 668 b7J5A6VB9J/4yVTRiBcxTypW/mpr5w=" 670 C.3. All Headers Test 672 A strong signature including all of the headers and a digest of the 673 body of the HTTP request would result in the following signing 674 string: 676 (request-target): post /foo?param=value&pet=dog 677 host: example.com 678 date: Thu, 05 Jan 2014 21:31:40 GMT 679 content-type: application/json 680 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 681 content-length: 18 683 The Authorization header would be: 685 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 686 headers="(request-target) host date content-type digest content-length", 687 signature="jgSqYK0yKclIHfF9zdApVEbDp5eqj8C4i4X76pE+XHoxugXv7q 688 nVrGR+30bmBgtpR39I4utq17s9ghz/2QFVxlnToYAvbSVZJ9ulLd1HQBugO0j 689 Oyn9sXOtcN7uNHBjqNCqUsnt0sw/cJA6B6nJZpyNqNyAXKdxZZItOuhIs78w=" 691 The Signature header would be: 693 Signature: keyId="Test",algorithm="rsa-sha256", 694 headers="(request-target) host date content-type digest content-length", 695 signature="jgSqYK0yKclIHfF9zdApVEbDp5eqj8C4i4X76pE+XHoxugXv7q 696 nVrGR+30bmBgtpR39I4utq17s9ghz/2QFVxlnToYAvbSVZJ9ulLd1HQBugO0j 697 Oyn9sXOtcN7uNHBjqNCqUsnt0sw/cJA6B6nJZpyNqNyAXKdxZZItOuhIs78w=" 698 Appendix D. Acknowledgements 700 The editor would like to thank the following individuals for feedback 701 on and implementations of the specification (in alphabetical order): 702 Stephen Farrell, Phillip Hallam-Baker, Dave Lehn, Dave Longley, James 703 H. Manger, Mark Nottingham, Yoav Nir, Julian Reschke, and Michael 704 Richardson. 706 Appendix E. IANA Considerations 708 E.1. Signature Authentication Scheme 710 The following entry should be added to the Authentication Scheme 711 Registry located at http://www.iana.org/assignments/http-authschemes 713 Authentication Scheme Name: Signature 714 Reference: [RFC_THIS_DOCUMENT], Section 2. 715 Notes (optional): The Signature scheme is designed for clients to 716 authenticate themselves with a server. 718 E.2. Signature Algorithm Registry 720 The following initial entries should be added to the Signature 721 Algorithm Registry to be created and maintained at (the suggested 722 URI) http://www.iana.org/assignments/signature-algorithms : 724 Editor's note: The references in this section are problematic as many 725 of the specifications that they refer to are too implementation 726 specific, rather than just pointing to the proper signature and 727 hashing specifications. A better approach might be just specifying 728 the signature and hashing function specifications, leaving 729 implementers to connect the dots (which are not that hard to 730 connect). 732 Algorithm Name: rsa-sha1 733 Reference: RFC 6376 [RFC6376], Section 3.3.1 734 Status: deprecated 736 Algorithm Name: rsa-sha256 737 Reference: RFC 6376 [RFC6376], Section 3.3.2 738 Status: active 740 Algorithm Name: hmac-sha256 741 Reference: HS256 in JOSE JSON Web Algorithms 742 [I-D.ietf-jose-json-web-algorithms], Section 3.2 743 Status: active 745 Algorithm Name: ecdsa-sha256 746 Reference: ES256 in JOSE JSON Web Algorithms 747 [I-D.ietf-jose-json-web-algorithms], Section 3.4 748 Status: active 750 Authors' Addresses 752 Mark Cavage 753 Oracle 754 500 Oracle Parkway 755 Redwood Shores, CA 94065 756 US 758 Phone: +1 415 400 0626 759 Email: mcavage@gmail.com 760 URI: http://www.oracle.com/ 762 Manu Sporny 763 Digital Bazaar 764 1700 Kraft Drive 765 Suite 2408 766 Blacksburg, VA 24060 767 US 769 Phone: +1 540 961 4469 770 Email: msporny@digitalbazaar.com 771 URI: http://manu.sporny.org/