idnits 2.17.1 draft-cavage-http-signatures-03.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 (July 21, 2014) is 3565 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 510 -- Looks like a reference, but probably isn't: '4' on line 515 -- Looks like a reference, but probably isn't: '5' on line 517 -- Looks like a reference, but probably isn't: '6' on line 519 -- Looks like a reference, but probably isn't: '7' on line 521 -- Looks like a reference, but probably isn't: '8' on line 523 -- Looks like a reference, but probably isn't: '9' on line 525 -- Looks like a reference, but probably isn't: '10' on line 527 -- Looks like a reference, but probably isn't: '11' on line 529 -- Looks like a reference, but probably isn't: '12' on line 531 -- Looks like a reference, but probably isn't: '3' on line 512 -- Looks like a reference, but probably isn't: '13' on line 541 -- Looks like a reference, but probably isn't: '14' on line 547 -- Looks like a reference, but probably isn't: '15' on line 549 == Unused Reference: 'RFC2119' is defined on line 471, 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 Joyent 4 Intended status: Standards Track M. Sporny 5 Expires: January 22, 2015 Digital Bazaar 6 July 21, 2014 8 Signing HTTP Messages 9 draft-cavage-http-signatures-03 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 January 22, 2015. 44 Copyright Notice 46 Copyright (c) 2014 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 . . . . . . . . . . . . . . . . . . 6 71 3. The 'Signature' HTTP Authentication Scheme . . . . . . . . . 7 72 3.1. Authorization Header . . . . . . . . . . . . . . . . . . 7 73 3.1.1. Initiating Signature Authorization . . . . . . . . . 7 74 3.1.2. RSA Example . . . . . . . . . . . . . . . . . . . . . 8 75 3.1.3. HMAC Example . . . . . . . . . . . . . . . . . . . . 8 76 4. The 'Signature' HTTP Header . . . . . . . . . . . . . . . . . 9 77 4.1. Signature Header . . . . . . . . . . . . . . . . . . . . 9 78 4.1.1. RSA Example . . . . . . . . . . . . . . . . . . . . . 9 79 4.1.2. HMAC Example . . . . . . . . . . . . . . . . . . . . 10 80 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 81 5.1. Normative References . . . . . . . . . . . . . . . . . . 10 82 5.2. Informative References . . . . . . . . . . . . . . . . . 11 83 5.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 11 84 Appendix A. Security Considerations . . . . . . . . . . . . . . 12 85 Appendix B. Extensions . . . . . . . . . . . . . . . . . . . . . 12 86 Appendix C. Test Values . . . . . . . . . . . . . . . . . . . . 13 87 C.1. Default Test . . . . . . . . . . . . . . . . . . . . . . 13 88 C.2. Basic Test . . . . . . . . . . . . . . . . . . . . . . . 14 89 C.3. All Headers Test . . . . . . . . . . . . . . . . . . . . 14 90 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 15 91 Appendix E. IANA Considerations . . . . . . . . . . . . . . . . 15 92 E.1. Signature Authentication Scheme . . . . . . . . . . . . . 15 93 E.2. Signature Algorithm Registry . . . . . . . . . . . . . . 15 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 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 Any other modification to the header field value MUST NOT be 232 made. If there are multiple instances of the same header field, 233 all header field values associated with the header field MUST be 234 concatenated and used in the order in which they will appear in 235 the transmitted HTTP message. 237 3. If value is not the last value then append an ASCII newline `\n`. 239 2.4. Creating a Signature 241 In order to create a signature, a client MUST: 243 1. Use the contents of the HTTP message, the `headers` value, and 244 the Signature String Construction algorithm to create the 245 signature string. 247 2. The `algorithm` and key associated with `keyId` must then be used 248 to generate a digital signature on the signature string. 250 3. The `signature` is then generated by base 64 encoding the output 251 of the digital signature algorithm. 253 For example, assume that the `algorithm` value was "rsa-sha256". 254 This would signal to the application that the data associated with 255 `keyId` is an RSA Private Key (as defined in RFC 3447 [RFC3447]), the 256 signature string hashing function is SHA-256, and the signing 257 algorithm is the one defined in RFC 3447 [RFC3447], 258 Section Section 8.2.1 [7]. The result of the signature creation 259 algorithm specified in RFC 3447 [RFC3447] should result in a binary 260 string, which is then base 64 encoded and placed into the `signature` 261 value. 263 2.5. Verifying a Signature 265 In order to verify a signature, a server MUST: 267 1. Use the received HTTP message, the `headers` value, and the 268 Signature String Construction algorithm to recreate the signature 269 string. 271 2. The `algorithm`, `keyId`, and base 64 decoded `signature` listed 272 in the signature parameters are then used to verify the 273 authenticity of the digital signature. 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 Public Key (as defined in RFC 3447 [RFC3447]), the 278 signature string hashing function is SHA-256, and the `signature` 279 verification algorithm to use to verify the signature is the one 280 defined in RFC 3447 [RFC3447], Section Section 8.2.2 [8]. The result 281 of the signature verification algorithm specified in RFC 3447 282 [RFC3447] should result in a successful verification unless the 283 headers protected by the signature were tampered with in transit. 285 3. The 'Signature' HTTP Authentication Scheme 287 The "signature" authentication scheme is based on the model that the 288 client must authenticate itself with a digital signature produced by 289 either a private asymmetric key (e.g., RSA) or a shared symmetric key 290 (e.g., HMAC). The scheme is parameterized enough such that it is not 291 bound to any particular key type or signing algorithm. However, it 292 does explicitly assume that clients can send an HTTP `Date` header. 294 3.1. Authorization Header 296 The client is expected to send an Authorization header (as defined in 297 RFC 7235 [RFC7235], Section 4.1 [9]) where the "auth-scheme" is 298 "Signature" and the "auth-param" parameters meet the requirements 299 listed in Section 2: The Components of a Signature. 301 The rest if this section uses the following HTTP request as an 302 example. 304 POST /foo HTTP/1.1 305 Host: example.org 306 Date: Tue, 07 Jun 2014 20:51:35 GMT 307 Content-Type: application/json 308 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 309 Content-Length: 18 311 {"hello": "world"} 313 Note that the use of the `Digest` header field is per RFC 3230 314 [RFC3230], Section 4.3.2 [10] and is included merely as a 315 demonstration of how an implementer could include information about 316 the body of the message in the signature. The following sections 317 also assume that the "rsa-key-1" keyId refers to a private key known 318 to the client and a public key known to the server. The "hmac-key-1" 319 keyId refers to key known to the client and server. 321 3.1.1. Initiating Signature Authorization 323 A server may notify a client when a protected resource could be 324 accessed by authenticating itself to the server. To initiate this 325 process, the server will request that the client authenticate itself 326 via a 401 response code. The server may optionally specify which 327 HTTP headers it expects to be signed by specifying the `headers` 328 parameter in the WWW-Authenticate header. For example: 330 HTTP/1.1 401 Unauthorized 331 Date: Thu, 08 Jun 2014 18:32:30 GMT 332 Content-Length: 1234 333 Content-Type: text/html 334 WWW-Authenticate: Signature realm="Example",headers="(request-target) date" 336 ... 338 3.1.2. RSA Example 340 The authorization header and signature would be generated as: 342 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256", 343 headers="(request-target) host date digest content-length", 344 signature="Base64(RSA-SHA256(signing string))" 346 The client would compose the signing string as: 348 (request-target): post /foo\n 349 host: example.org\n 350 date: Tue, 07 Jun 2014 20:51:35 GMT\n 351 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 352 content-length: 18 354 Note that the '\n' symbols above are included to demonstrate where 355 the new line character should be inserted. There is no new line on 356 the final line of the signing string. 358 For an RSA-based signature, the authorization header and signature 359 would then be generated as: 361 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256", 362 headers="(request-target) host date digest content-length", 363 signature="Base64(RSA-SHA256(signing string))" 365 3.1.3. HMAC Example 367 For an HMAC-based signature without a list of headers specified, the 368 authorization header and signature would be generated as: 370 Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha256", 371 headers="(request-target) host date digest content-length", 372 signature="Base64(HMAC-SHA256(signing string))" 374 The only difference between the RSA Example and the HMAC Example is 375 the signature algorithm that is used. The client would compose the 376 signing string in the same way as the RSA Example above: 378 (request-target): post /foo\n 379 host: example.org\n 380 date: Tue, 07 Jun 2014 20:51:35 GMT\n 381 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 382 content-length: 18 384 4. The 'Signature' HTTP Header 386 The "signature" HTTP Header is based on the model that the sender 387 must authenticate itself with a digital signature produced by either 388 a private asymmetric key (e.g., RSA) or a shared symmetric key (e.g., 389 HMAC). The scheme is parameterized enough such that it is not bound 390 to any particular key type or signing algorithm. However, it does 391 explicitly assume that senders can send an HTTP `Date` header. 393 4.1. Signature Header 395 The sender is expected to transmit a header (as defined in RFC 7230 396 [RFC7230], Section 3.2 [11]) where the "field-name" is "Signature", 397 and the "field-value" contains one or more "auth-param"s (as defined 398 in RFC 7235 [RFC7235], Section 4.1 [12]) where the "auth-param" 399 parameters meet the requirements listed in Section 2: The Components 400 of a Signature. 402 The rest if this section uses the following HTTP request as an 403 example. 405 POST /foo HTTP/1.1 406 Host: example.org 407 Date: Tue, 07 Jun 2014 20:51:35 GMT 408 Content-Type: application/json 409 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 410 Content-Length: 18 412 {"hello": "world"} 414 The following sections assume that the "rsa-key-1" keyId refers to a 415 private key known to the client and a public key known to the server. 416 The "hmac-key-1" keyId refers to key known to the client and server. 418 4.1.1. RSA Example 420 The signature header and signature would be generated as: 422 Signature: keyId="rsa-key-1",algorithm="rsa-sha256", 423 headers="(request-target) host date digest content-length", 424 signature="Base64(RSA-SHA256(signing string))" 425 The client would compose the signing string as: 427 (request-target): post /foo\n 428 host: example.org\n 429 date: Tue, 07 Jun 2014 20:51:35 GMT\n 430 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 431 content-length: 18 433 Note that the '\n' symbols above are included to demonstrate where 434 the new line character should be inserted. There is no new line on 435 the final line of the signing string. 437 For an RSA-based signature, the authorization header and signature 438 would then be generated as: 440 Signature: keyId="rsa-key-1",algorithm="rsa-sha256", 441 headers="(request-target) host date digest content-length", 442 signature="Base64(RSA-SHA256(signing string))" 444 4.1.2. HMAC Example 446 For an HMAC-based signature without a list of headers specified, the 447 authorization header and signature would be generated as: 449 Signature: keyId="hmac-key-1",algorithm="hmac-sha256", 450 headers="(request-target) host date digest content-length", 451 signature="Base64(HMAC-SHA256(signing string))" 453 The only difference between the RSA Example and the HMAC Example is 454 the signature algorithm that is used. The client would compose the 455 signing string in the same way as the RSA Example above: 457 (request-target): post /foo\n 458 host: example.org\n 459 date: Tue, 07 Jun 2014 20:51:35 GMT\n 460 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 461 content-length: 18 463 5. References 465 5.1. Normative References 467 [I-D.ietf-jose-json-web-algorithms] 468 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 469 json-web-algorithms-20 (work in progress), January 2014. 471 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 472 Requirement Levels", BCP 14, RFC 2119, March 1997. 474 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 475 Encodings", RFC 4648, October 2006. 477 [RFC6376] Crocker, D., Hansen, T., and M. Kucherawy, "DomainKeys 478 Identified Mail (DKIM) Signatures", STD 76, RFC 6376, 479 September 2011. 481 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 482 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 483 2014. 485 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 486 (HTTP/1.1): Authentication", RFC 7235, June 2014. 488 5.2. Informative References 490 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 491 Leach, P., Luotonen, A., and L. Stewart, "HTTP 492 Authentication: Basic and Digest Access Authentication", 493 RFC 2617, June 1999. 495 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", RFC 496 3230, January 2002. 498 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 499 Standards (PKCS) #1: RSA Cryptography Specifications 500 Version 2.1", RFC 3447, February 2003. 502 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 503 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 505 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 506 6749, October 2012. 508 5.3. URIs 510 [2] http://tools.ietf.org/html/rfc4648#section-4 512 [3] http://tools.ietf.org/html/draft-ietf-httpbis- 513 http2-13#section-8.1.2.1 515 [4] http://tools.ietf.org/html/rfc7230#section-3.2.4 517 [5] http://tools.ietf.org/html/rfc3447#section-8.2.1 519 [6] http://tools.ietf.org/html/rfc3447#section-8.2.2 521 [7] http://tools.ietf.org/html/draft-ietf-rfc7235-auth-25#section-4.1 523 [8] http://tools.ietf.org/html/rfc3230#section-4.3.2 525 [9] http://tools.ietf.org/html/rfc7230#section-3.2 527 [10] http://tools.ietf.org/html/rfc7235#section-4.1 529 [11] https://web-payments.org/specs/source/http-signatures-audit/ 531 [12] https://web-payments.org/specs/source/http-signature-nonces/ 533 [13] https://web-payments.org/specs/source/http-signature-trailers/ 535 Appendix A. Security Considerations 537 There are a number of security considerations to take into account 538 when implementing or utilizing this specification. A thorough 539 security analysis of this protocol, including its strengths and 540 weaknesses, can be found in Security Considerations for HTTP 541 Signatures [13]. 543 Appendix B. Extensions 545 This specification was designed to be simple, modular, and 546 extensible. There are a number of other specifications that build on 547 this one. For example, the HTTP Signature Nonces [14] specification 548 details how to use HTTP Signatures over a non-secured channel like 549 HTTP and the HTTP Signature Trailers [15] specification explains how 550 to apply HTTP Signatures to streaming content. Developers that 551 desire more functionality than this specification provides are urged 552 to ensure that an extension specification doesn't already exist 553 before implementing a proprietary extension. 555 If extensions to this specification are made by adding new Signature 556 Parameters, those extension parameters MUST be registered in the 557 Signature Authentication Scheme Registry. The registry will be 558 created and maintained at (the suggested URI) http://www.iana.org/ 559 assignments/http-auth-scheme-signature . An example entry in this 560 registry is included below: 562 Signature Parameter: nonce 563 Reference to specification: [HTTP_AUTH_SIGNATURE_NONCE], Section XYZ. 564 Notes (optional): The HTTP Signature Nonces specification details 565 how to use HTTP Signatures over a unsecured channel like HTTP. 567 Appendix C. Test Values 569 The following test data uses the following RSA 2048-bit keys, which 570 we will refer to as `keyId=Test` in the following samples: 572 -----BEGIN PUBLIC KEY----- 573 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3 574 6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6 575 Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw 576 oYi+1hqp1fIekaxsyQIDAQAB 577 -----END PUBLIC KEY----- 579 -----BEGIN RSA PRIVATE KEY----- 580 MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF 581 NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F 582 UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB 583 AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA 584 QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK 585 kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg 586 f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u 587 412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc 588 mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7 589 kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA 590 gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW 591 G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI 592 7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA== 593 -----END RSA PRIVATE KEY----- 595 All examples use this request: 597 POST /foo?param=value&pet=dog HTTP/1.1 598 Host: example.com 599 Date: Thu, 05 Jan 2014 21:31:40 GMT 600 Content-Type: application/json 601 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 602 Content-Length: 18 604 {"hello": "world"} 606 C.1. Default Test 608 If a list of headers is not included, the date is the only header 609 that is signed by default. The string to sign would be: 611 date: Thu, 05 Jan 2014 21:31:40 GMT 613 The Authorization header would be: 615 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 616 signature="ATp0r26dbMIxOopqw0OfABDT7CKMIoENumuruOtarj8n/97Q3htH 617 FYpH8yOSQk3Z5zh8UxUym6FYTb5+A0Nz3NRsXJibnYi7brE/4tx5But9kkFGzG+ 618 xpUmimN4c3TMN7OFH//+r8hBf7BT9/GmHDUVZT2JzWGLZES2xDOUuMtA=" 620 The Signature header would be: 622 Signature: keyId="Test",algorithm="rsa-sha256", 623 signature="ATp0r26dbMIxOopqw0OfABDT7CKMIoENumuruOtarj8n/97Q3htH 624 FYpH8yOSQk3Z5zh8UxUym6FYTb5+A0Nz3NRsXJibnYi7brE/4tx5But9kkFGzG+ 625 xpUmimN4c3TMN7OFH//+r8hBf7BT9/GmHDUVZT2JzWGLZES2xDOUuMtA=" 627 C.2. Basic Test 629 The minimum recommended data to sign is the (request-target), host, 630 and date. In this case, the string to sign would be: 632 (request-target): post /foo?param=value&pet=dog 633 host: example.com 634 date: Thu, 05 Jan 2014 21:31:40 GMT 636 The Authorization header would be: 638 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 639 headers="(request-target) host date", signature="KcLSABBj/m3v2Dhxi 640 CKJmzYJvnx74tDO1SaURD8Dr8XpugN5wpy8iBVJtpkHUIp4qBYpzx2QvD16t8X 641 0BUMiKc53Age+baQFWwb2iYYJzvuUL+krrl/Q7H6fPBADBsHqEZ7IE8rR0Ys3l 642 b7J5A6VB9J/4yVTRiBcxTypW/mpr5w=" 644 C.3. All Headers Test 646 A strong signature including all of the headers and a digest of the 647 body of the HTTP request would result in the following signing 648 string: 650 (request-target): post /foo?param=value&pet=dog 651 host: example.com 652 date: Thu, 05 Jan 2014 21:31:40 GMT 653 content-type: application/json 654 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 655 content-length: 18 657 The Authorization header would be: 659 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 660 headers="(request-target) host date content-type digest content-length", 661 signature="jgSqYK0yKclIHfF9zdApVEbDp5eqj8C4i4X76pE+XHoxugXv7q 662 nVrGR+30bmBgtpR39I4utq17s9ghz/2QFVxlnToYAvbSVZJ9ulLd1HQBugO0j 663 Oyn9sXOtcN7uNHBjqNCqUsnt0sw/cJA6B6nJZpyNqNyAXKdxZZItOuhIs78w=" 665 The Signature header would be: 667 Signature: keyId="Test",algorithm="rsa-sha256", 668 headers="(request-target) host date content-type digest content-length", 669 signature="jgSqYK0yKclIHfF9zdApVEbDp5eqj8C4i4X76pE+XHoxugXv7q 670 nVrGR+30bmBgtpR39I4utq17s9ghz/2QFVxlnToYAvbSVZJ9ulLd1HQBugO0j 671 Oyn9sXOtcN7uNHBjqNCqUsnt0sw/cJA6B6nJZpyNqNyAXKdxZZItOuhIs78w=" 673 Appendix D. Acknowledgements 675 The editor would like to thank the following individuals for feedback 676 on and implementations of the specification (in alphabetical order): 677 Stephen Farrell, Phillip Hallam-Baker, Dave Lehn, Dave Longley, James 678 H. Manger, Mark Nottingham, Yoav Nir, Julian Reschke, and Michael 679 Richardson. 681 Appendix E. IANA Considerations 683 E.1. Signature Authentication Scheme 685 The following entry should be added to the Authentication Scheme 686 Registry located at http://www.iana.org/assignments/http-authschemes 688 Authentication Scheme Name: Signature 689 Reference: [RFC_THIS_DOCUMENT], Section 2. 690 Notes (optional): The Signature scheme is designed for clients to 691 authenticate themselves with a server. 693 E.2. Signature Algorithm Registry 695 The following initial entries should be added to the Signature 696 Algorithm Registry to be created and maintained at (the suggested 697 URI) http://www.iana.org/assignments/signature-algorithms : 699 Editor's note: The references in this section are problematic as many 700 of the specifications that they refer to are too implementation 701 specific, rather than just pointing to the proper signature and 702 hashing specifications. A better approach might be just specifying 703 the signature and hashing function specifications, leaving 704 implementers to connect the dots (which are not that hard to 705 connect). 707 Algorithm Name: rsa-sha1 708 Reference: RFC 6376 [RFC6376], Section 3.3.1 709 Status: deprecated 711 Algorithm Name: rsa-sha256 712 Reference: RFC 6376 [RFC6376], Section 3.3.2 713 Status: active 715 Algorithm Name: hmac-sha256 716 Reference: HS256 in JOSE JSON Web Algorithms 717 [I-D.ietf-jose-json-web-algorithms], Section 3.2 718 Status: active 720 Algorithm Name: ecdsa-sha256 721 Reference: ES256 in JOSE JSON Web Algorithms 722 [I-D.ietf-jose-json-web-algorithms], Section 3.4 723 Status: active 725 Authors' Addresses 727 Mark Cavage 728 Joyent 729 One Embarcadero Center 730 9th Floor 731 San Francisco, CA 94111 732 US 734 Phone: +1 415 400 0626 735 Email: mark.cavage@joyent.com 736 URI: http://www.joyent.com/ 738 Manu Sporny 739 Digital Bazaar 740 1700 Kraft Drive 741 Suite 2408 742 Blacksburg, VA 24060 743 US 745 Phone: +1 540 961 4469 746 Email: msporny@digitalbazaar.com 747 URI: http://manu.sporny.org/