idnits 2.17.1 draft-cavage-http-signatures-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. ** The abstract seems to contain references ([2], [3], [4], [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 (May 14, 2018) is 2174 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 560 -- Looks like a reference, but probably isn't: '2' on line 562 -- Looks like a reference, but probably isn't: '3' on line 564 -- Looks like a reference, but probably isn't: '4' on line 566 -- Looks like a reference, but probably isn't: '5' on line 568 -- Looks like a reference, but probably isn't: '6' on line 570 -- Looks like a reference, but probably isn't: '7' on line 572 -- Looks like a reference, but probably isn't: '8' on line 574 -- Looks like a reference, but probably isn't: '9' on line 576 -- Looks like a reference, but probably isn't: '10' on line 578 -- Looks like a reference, but probably isn't: '11' on line 580 -- Looks like a reference, but probably isn't: '12' on line 583 -- Looks like a reference, but probably isn't: '13' on line 585 -- Looks like a reference, but probably isn't: '14' on line 587 -- Looks like a reference, but probably isn't: '15' on line 607 -- Looks like a reference, but probably isn't: '16' on line 613 -- Looks like a reference, but probably isn't: '17' on line 615 -- Looks like a reference, but probably isn't: '18' on line 625 -- Looks like a reference, but probably isn't: '19' on line 753 -- Looks like a reference, but probably isn't: '20' on line 764 == Unused Reference: 'RFC2119' is defined on line 508, 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 (==), 25 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: November 15, 2018 Digital Bazaar 6 May 14, 2018 8 Signing HTTP Messages 9 draft-cavage-http-signatures-10 11 Abstract 13 When communicating over the Internet using the HTTP protocol, it can 14 be desirable for a server or client to authenticate the sender of a 15 particular message. It can also be desirable to ensure that the 16 message was not tampered with during transit. This document 17 describes a way for servers and clients to simultaneously add 18 authentication and message integrity to HTTP messages by using a 19 digital signature. 21 Feedback 23 This specification is a joint work product of the W3C Digital 24 Verification Community Group [1] and the W3C Credentials Community 25 Group [2]. Feedback related to this specification should logged in 26 the issue tracker [3] or be sent to public-credentials@w3.org [4]. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on November 15, 2018. 45 Copyright Notice 47 Copyright (c) 2018 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Using Signatures in HTTP Requests . . . . . . . . . . . . 3 61 1.2. Using Signatures in HTTP Responses . . . . . . . . . . . 4 62 2. The Components of a Signature . . . . . . . . . . . . . . . . 4 63 2.1. Signature Parameters . . . . . . . . . . . . . . . . . . 4 64 2.1.1. keyId . . . . . . . . . . . . . . . . . . . . . . . . 4 65 2.1.2. signature . . . . . . . . . . . . . . . . . . . . . . 4 66 2.1.3. headers . . . . . . . . . . . . . . . . . . . . . . . 4 67 2.1.4. algorithm . . . . . . . . . . . . . . . . . . . . . . 5 68 2.2. Ambiguous Parameters . . . . . . . . . . . . . . . . . . 5 69 2.3. Signature String Construction . . . . . . . . . . . . . . 5 70 2.4. Creating a Signature . . . . . . . . . . . . . . . . . . 6 71 2.5. Verifying a Signature . . . . . . . . . . . . . . . . . . 7 72 3. The 'Signature' HTTP Authentication Scheme . . . . . . . . . 7 73 3.1. Authorization Header . . . . . . . . . . . . . . . . . . 8 74 3.1.1. Initiating Signature Authorization . . . . . . . . . 8 75 3.1.2. RSA Example . . . . . . . . . . . . . . . . . . . . . 9 76 3.1.3. HMAC Example . . . . . . . . . . . . . . . . . . . . 9 77 4. The 'Signature' HTTP Header . . . . . . . . . . . . . . . . . 10 78 4.1. Signature Header . . . . . . . . . . . . . . . . . . . . 10 79 4.1.1. RSA Example . . . . . . . . . . . . . . . . . . . . . 10 80 4.1.2. HMAC Example . . . . . . . . . . . . . . . . . . . . 11 81 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 82 5.1. Normative References . . . . . . . . . . . . . . . . . . 11 83 5.2. Informative References . . . . . . . . . . . . . . . . . 12 84 5.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 13 85 Appendix A. Security Considerations . . . . . . . . . . . . . . 13 86 Appendix B. Extensions . . . . . . . . . . . . . . . . . . . . . 14 87 Appendix C. Test Values . . . . . . . . . . . . . . . . . . . . 14 88 C.1. Default Test . . . . . . . . . . . . . . . . . . . . . . 15 89 C.2. Basic Test . . . . . . . . . . . . . . . . . . . . . . . 16 90 C.3. All Headers Test . . . . . . . . . . . . . . . . . . . . 16 91 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 17 92 Appendix E. IANA Considerations . . . . . . . . . . . . . . . . 17 93 E.1. Signature Authentication Scheme . . . . . . . . . . . . . 17 94 E.2. Signature Algorithm Registry . . . . . . . . . . . . . . 17 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 97 1. Introduction 99 This protocol extension is intended to provide a simple and standard 100 way for clients to sign HTTP messages. 102 HTTP Authentication [RFC2617] defines Basic and Digest authentication 103 mechanisms, TLS 1.2 [RFC5246] defines cryptographically strong 104 transport layer security, and OAuth 2.0 [RFC6749] provides a fully- 105 specified alternative for authorization of web service requests. 106 Each of these approaches are employed on the Internet today with 107 varying degrees of protection. However, none of these schemes are 108 designed to cryptographically sign the HTTP messages themselves, 109 which is required in order to ensure end-to-end message integrity. 110 An added benefit of signing the HTTP message for the purposes of end- 111 to-end message integrity is that the client can be authenticated 112 using the same mechanism without the need for multiple round-trips. 114 Several web service providers have invented their own schemes for 115 signing HTTP messages, but to date, none have been standardized. 116 While there are no techniques in this proposal that are novel beyond 117 the previous art, it is useful to standardize a simple and 118 cryptographically strong mechanism for digitally signing HTTP 119 messages. 121 1.1. Using Signatures in HTTP Requests 123 It is common practice to protect sensitive website API functionality 124 via authentication mechanisms. Often, the entity accessing these 125 APIs is a piece of automated software outside of an interactive human 126 session. While there are mechanisms like OAuth and API secrets that 127 are used to grant API access, each have their weaknesses such as 128 unnecessary complexity for particular use cases or the use of shared 129 secrets which may not be acceptable to an implementer. 131 Digital signatures are widely used to provide authentication without 132 the need for shared secrets. They also do not require a round-trip 133 in order to authenticate the client. A server need only have a 134 mapping between the key being used to sign the content and the 135 authorized entity to verify that a message was signed by that entity. 137 This specification provides two mechanisms that can be used by a 138 server to authenticate a client. The first is the 'Signature' HTTP 139 Authentication Scheme, which may be used for interactive sessions. 141 The second is the Signature HTTP Header, which is typically used by 142 automated software agents. 144 1.2. Using Signatures in HTTP Responses 146 For high security transactions, having an additional signature on the 147 HTTP header allows a client to ensure that even if the transport 148 channel has been compromised, that the content of the messages have 149 not been compromised. This specification provides a HTTP Signature 150 Header mechanism that can be used by a client to authenticate the 151 sender of a message and ensure that particular headers have not been 152 modified in transit. 154 2. The Components of a Signature 156 There are a number of components in a signature that are common 157 between the 'Signature' HTTP Authentication Scheme and the 158 'Signature' HTTP Header. This section details the components of a 159 digital signature. 161 2.1. Signature Parameters 163 The following section details the signature parameters. 165 2.1.1. keyId 167 REQUIRED. The `keyId` field is an opaque string that the server can 168 use to look up the component they need to validate the signature. It 169 could be an SSH key fingerprint, a URL to machine-readable key data, 170 an LDAP DN, etc. Management of keys and assignment of `keyId` is out 171 of scope for this document. 173 2.1.2. signature 175 REQUIRED. The `signature` parameter is a base 64 encoded digital 176 signature, as described in RFC 4648 [RFC4648], Section 4 [5]. The 177 client uses the `algorithm` and `headers` signature parameters to 178 form a canonicalized `signing string`. This `signing string` is then 179 signed with the key associated with `keyId` and the algorithm 180 corresponding to `algorithm`. The `signature` parameter is then set 181 to the base 64 encoding of the signature. 183 2.1.3. headers 185 OPTIONAL. The `headers` parameter is used to specify the list of 186 HTTP headers included when generating the signature for the message. 187 If specified, it should be a lowercased, quoted list of HTTP header 188 fields, separated by a single space character. If not specified, 189 implementations MUST operate as if the field were specified with a 190 single value, the `Date` header, in the list of HTTP headers. Note 191 that the list order is important, and MUST be specified in the order 192 the HTTP header field-value pairs are concatenated together during 193 signing. 195 2.1.4. algorithm 197 OPTIONAL. The `algorithm` parameter is used to specify the digital 198 signature algorithm to use when generating the signature. Valid 199 values for this parameter can be found in the Signature Algorithms 200 registry located at http://www.iana.org/assignments/signature- 201 algorithms [6] and MUST NOT be marked "deprecated". It is preferred 202 that the algorithm used by an implementation be derived from the key 203 metadata identified by the `keyId` rather than from this field. If 204 `algorithm` is provided and differs from the key metadata identified 205 by the `keyId` then an implementation MUST produce an error. The 206 `algorithm` parameter, which may be specified by an attacker, has the 207 potential to create security vulnerabilities and will most likely be 208 deprecated in the future. 210 2.2. Ambiguous Parameters 212 If any of the parameters listed above are erroneously duplicated in 213 the associated header field, then the last parameter defined MUST be 214 used. Any parameter that is not recognized as a parameter, or is not 215 well-formed, MUST be ignored. 217 2.3. Signature String Construction 219 In order to generate the string that is signed with a key, the client 220 MUST use the values of each HTTP header field in the `headers` 221 Signature parameter, in the order they appear in the `headers` 222 Signature parameter. It is out of scope for this document to dictate 223 what header fields an application will want to enforce, but 224 implementers SHOULD at minimum include the request target and Date 225 header fields. 227 To include the HTTP request target in the signature calculation, use 228 the special `(request-target)` header field name. 230 1. If the header field name is `(request-target)` then generate the 231 header field value by concatenating the lowercased :method, an 232 ASCII space, and the :path pseudo-headers (as specified in 233 HTTP/2, Section 8.1.2.3 [7]). Note: For the avoidance of doubt, 234 lowercasing only applies to the :method pseudo-header and not to 235 the :path pseudo-header. 237 2. Create the header field string by concatenating the lowercased 238 header field name followed with an ASCII colon `:`, an ASCII 239 space ` `, and the header field value. Leading and trailing 240 optional whitespace (OWS) in the header field value MUST be 241 omitted (as specified in RFC7230 [RFC7230], Section 3.2.4 [8]). 242 If there are multiple instances of the same header field, all 243 header field values associated with the header field MUST be 244 concatenated, separated by a ASCII comma and an ASCII space `, `, 245 and used in the order in which they will appear in the 246 transmitted HTTP message. Any other modification to the header 247 field value MUST NOT be made. 249 3. If value is not the last value then append an ASCII newline `\n`. 251 To illustrate the rules specified above, assume a `headers` parameter 252 list with the value of `(request-target) host date cache-control 253 x-example` with the following HTTP request headers: 255 GET /foo HTTP/1.1 256 Host: example.org 257 Date: Tue, 07 Jun 2014 20:51:35 GMT 258 X-Example: Example header 259 with some whitespace. 260 Cache-Control: max-age=60 261 Cache-Control: must-revalidate 263 For the HTTP request headers above, the corresponding signature 264 string is: 266 (request-target): get /foo 267 host: example.org 268 date: Tue, 07 Jun 2014 20:51:35 GMT 269 cache-control: max-age=60, must-revalidate 270 x-example: Example header with some whitespace. 272 2.4. Creating a Signature 274 In order to create a signature, a client MUST: 276 1. Use the contents of the HTTP message, the `headers` value, and 277 the Signature String Construction algorithm to create the 278 signature string. 280 2. The `algorithm` and key associated with `keyId` must then be used 281 to generate a digital signature on the signature string. 283 3. The `signature` is then generated by base 64 encoding the output 284 of the digital signature algorithm. 286 For example, assume that the `algorithm` value was "rsa-sha256". 287 This would signal to the application that the data associated with 288 `keyId` is an RSA Private Key (as defined in RFC 3447 [RFC3447]), the 289 signature string hashing function is SHA-256, and the signing 290 algorithm is the one defined in RFC 3447 [RFC3447], 291 Section Section 8.2.1 [9]. The result of the signature creation 292 algorithm specified in RFC 3447 [RFC3447] should result in a binary 293 string, which is then base 64 encoded and placed into the `signature` 294 value. 296 2.5. Verifying a Signature 298 In order to verify a signature, a server MUST: 300 1. Use the received HTTP message, the `headers` value, and the 301 Signature String Construction algorithm to recreate the signature 302 string. 304 2. The `algorithm`, `keyId`, and base 64 decoded `signature` listed 305 in the signature parameters are then used to verify the 306 authenticity of the digital signature. Note: The application 307 verifying the signature MUST derive the `algorithm` from the 308 metadata associated with the `keyId` and MUST NOT use the value 309 of `algorithm` from the signed message. 311 For example, assume that the `algorithm` value was "rsa-sha256". 312 This would signal to the application that the metadata associated 313 with `keyId` will express a RSA Public Key (as defined in RFC 3447 314 [RFC3447]), the a signature string hashing function of SHA-256, and 315 the `signature` verification algorithm to use to verify the signature 316 is the one defined in RFC 3447 [RFC3447], Section Section 8.2.2 [10]. 317 The result of the signature verification algorithm specified in RFC 318 3447 [RFC3447] should result in a successful verification unless the 319 headers protected by the signature were tampered with in transit. 321 3. The 'Signature' HTTP Authentication Scheme 323 The "signature" authentication scheme is based on the model that the 324 client must authenticate itself with a digital signature produced by 325 either a private asymmetric key (e.g., RSA) or a shared symmetric key 326 (e.g., HMAC). The scheme is parameterized enough such that it is not 327 bound to any particular key type or signing algorithm. However, it 328 does explicitly assume that clients can send an HTTP `Date` header. 330 3.1. Authorization Header 332 The client is expected to send an Authorization header (as defined in 333 RFC 7235 [RFC7235], Section 4.1 [11]) where the "auth-scheme" is 334 "Signature" and the "auth-param" parameters meet the requirements 335 listed in Section 2: The Components of a Signature. 337 The rest if this section uses the following HTTP request as an 338 example. 340 POST /foo HTTP/1.1 341 Host: example.org 342 Date: Tue, 07 Jun 2014 20:51:35 GMT 343 Content-Type: application/json 344 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 345 Content-Length: 18 347 {"hello": "world"} 349 Note that the use of the `Digest` header field is per RFC 3230 350 [RFC3230], Section 4.3.2 [12] and is included merely as a 351 demonstration of how an implementer could include information about 352 the body of the message in the signature. The following sections 353 also assume that the "rsa-key-1" keyId refers to a private key known 354 to the client and a public key known to the server. The "hmac-key-1" 355 keyId refers to key known to the client and server. 357 3.1.1. Initiating Signature Authorization 359 A server may notify a client when a protected resource could be 360 accessed by authenticating itself to the server. To initiate this 361 process, the server will request that the client authenticate itself 362 via a 401 response code. The server may optionally specify which 363 HTTP headers it expects to be signed by specifying the `headers` 364 parameter in the WWW-Authenticate header. For example: 366 HTTP/1.1 401 Unauthorized 367 Date: Thu, 08 Jun 2014 18:32:30 GMT 368 Content-Length: 1234 369 Content-Type: text/html 370 WWW-Authenticate: Signature realm="Example",headers="(request-target) date" 372 ... 374 3.1.2. RSA Example 376 The authorization header and signature would be generated as: 378 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256", 379 headers="(request-target) host date digest content-length", 380 signature="Base64(RSA-SHA256(signing string))" 382 The client would compose the signing string as: 384 (request-target): post /foo\n 385 host: example.org\n 386 date: Tue, 07 Jun 2014 20:51:35 GMT\n 387 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 388 content-length: 18 390 Note that the '\n' symbols above are included to demonstrate where 391 the new line character should be inserted. There is no new line on 392 the final line of the signing string. 394 For an RSA-based signature, the authorization header and signature 395 would then be generated as: 397 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256", 398 headers="(request-target) host date digest content-length", 399 signature="Base64(RSA-SHA256(signing string))" 401 3.1.3. HMAC Example 403 For an HMAC-based signature without a list of headers specified, the 404 authorization header and signature would be generated as: 406 Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha256", 407 headers="(request-target) host date digest content-length", 408 signature="Base64(HMAC-SHA256(signing string))" 410 The only difference between the RSA Example and the HMAC Example is 411 the signature algorithm that is used. The client would compose the 412 signing string in the same way as the RSA Example above: 414 (request-target): post /foo\n 415 host: example.org\n 416 date: Tue, 07 Jun 2014 20:51:35 GMT\n 417 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 418 content-length: 18 420 4. The 'Signature' HTTP Header 422 The "signature" HTTP Header is based on the model that the sender 423 must authenticate itself with a digital signature produced by either 424 a private asymmetric key (e.g., RSA) or a shared symmetric key (e.g., 425 HMAC). The scheme is parameterized enough such that it is not bound 426 to any particular key type or signing algorithm. However, it does 427 explicitly assume that senders can send an HTTP `Date` header. 429 4.1. Signature Header 431 The sender is expected to transmit a header (as defined in RFC 7230 432 [RFC7230], Section 3.2 [13]) where the "field-name" is "Signature", 433 and the "field-value" contains one or more "auth-param"s (as defined 434 in RFC 7235 [RFC7235], Section 4.1 [14]) where the "auth-param" 435 parameters meet the requirements listed in Section 2: The Components 436 of a Signature. 438 The rest if this section uses the following HTTP request as an 439 example. 441 POST /foo HTTP/1.1 442 Host: example.org 443 Date: Tue, 07 Jun 2014 20:51:35 GMT 444 Content-Type: application/json 445 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 446 Content-Length: 18 448 {"hello": "world"} 450 The following sections assume that the "rsa-key-1" keyId refers to a 451 private key known to the client and a public key known to the server. 452 The "hmac-key-1" keyId refers to key known to the client and server. 454 4.1.1. RSA Example 456 The signature header and signature would be generated as: 458 Signature: keyId="rsa-key-1",algorithm="rsa-sha256", 459 headers="(request-target) host date digest content-length", 460 signature="Base64(RSA-SHA256(signing string))" 462 The client would compose the signing string as: 464 (request-target): post /foo\n 465 host: example.org\n 466 date: Tue, 07 Jun 2014 20:51:35 GMT\n 467 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 468 content-length: 18 470 Note that the '\n' symbols above are included to demonstrate where 471 the new line character should be inserted. There is no new line on 472 the final line of the signing string. 474 For an RSA-based signature, the authorization header and signature 475 would then be generated as: 477 Signature: keyId="rsa-key-1",algorithm="rsa-sha256", 478 headers="(request-target) host date digest content-length", 479 signature="Base64(RSA-SHA256(signing string))" 481 4.1.2. HMAC Example 483 For an HMAC-based signature without a list of headers specified, the 484 authorization header and signature would be generated as: 486 Signature: keyId="hmac-key-1",algorithm="hmac-sha256", 487 headers="(request-target) host date digest content-length", 488 signature="Base64(HMAC-SHA256(signing string))" 490 The only difference between the RSA Example and the HMAC Example is 491 the signature algorithm that is used. The client would compose the 492 signing string in the same way as the RSA Example above: 494 (request-target): post /foo\n 495 host: example.org\n 496 date: Tue, 07 Jun 2014 20:51:35 GMT\n 497 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 498 content-length: 18 500 5. References 502 5.1. Normative References 504 [I-D.ietf-jose-json-web-algorithms] 505 Jones, M., "JSON Web Algorithms (JWA)", draft-ietf-jose- 506 json-web-algorithms-20 (work in progress), January 2014. 508 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 509 Requirement Levels", BCP 14, RFC 2119, 510 DOI 10.17487/RFC2119, March 1997, 511 . 513 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 514 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 515 . 517 [RFC6376] Crocker, D., Ed., Hansen, T., Ed., and M. Kucherawy, Ed., 518 "DomainKeys Identified Mail (DKIM) Signatures", STD 76, 519 RFC 6376, DOI 10.17487/RFC6376, September 2011, 520 . 522 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 523 Protocol (HTTP/1.1): Message Syntax and Routing", 524 RFC 7230, DOI 10.17487/RFC7230, June 2014, 525 . 527 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 528 Protocol (HTTP/1.1): Authentication", RFC 7235, 529 DOI 10.17487/RFC7235, June 2014, 530 . 532 5.2. Informative References 534 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 535 Leach, P., Luotonen, A., and L. Stewart, "HTTP 536 Authentication: Basic and Digest Access Authentication", 537 RFC 2617, DOI 10.17487/RFC2617, June 1999, 538 . 540 [RFC3230] Mogul, J. and A. Van Hoff, "Instance Digests in HTTP", 541 RFC 3230, DOI 10.17487/RFC3230, January 2002, 542 . 544 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 545 Standards (PKCS) #1: RSA Cryptography Specifications 546 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 547 2003, . 549 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 550 (TLS) Protocol Version 1.2", RFC 5246, 551 DOI 10.17487/RFC5246, August 2008, 552 . 554 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 555 RFC 6749, DOI 10.17487/RFC6749, October 2012, 556 . 558 5.3. URIs 560 [1] https://w3c-dvcg.github.io/ 562 [2] https://w3c-ccg.github.io/ 564 [3] https://github.com/w3c-dvcg/http-signatures/issues 566 [4] mailto:public-credentials@w3.org 568 [5] http://tools.ietf.org/html/rfc4648#section-4 570 [6] http://www.iana.org/assignments/signature-algorithms 572 [7] https://tools.ietf.org/html/rfc7540#section-8.1.2.3 574 [8] http://tools.ietf.org/html/rfc7230#section-3.2.4 576 [9] http://tools.ietf.org/html/rfc3447#section-8.2.1 578 [10] http://tools.ietf.org/html/rfc3447#section-8.2.2 580 [11] http://tools.ietf.org/html/draft-ietf-rfc7235-auth-25#section- 581 4.1 583 [12] http://tools.ietf.org/html/rfc3230#section-4.3.2 585 [13] http://tools.ietf.org/html/rfc7230#section-3.2 587 [14] http://tools.ietf.org/html/rfc7235#section-4.1 589 [15] https://web-payments.org/specs/source/http-signatures-audit/ 591 [16] https://web-payments.org/specs/source/http-signature-nonces/ 593 [17] https://web-payments.org/specs/source/http-signature-trailers/ 595 [18] http://www.iana.org/assignments/http-auth-scheme-signature 597 [19] http://www.iana.org/assignments/http-authschemes 599 [20] http://www.iana.org/assignments/signature-algorithms 601 Appendix A. Security Considerations 603 There are a number of security considerations to take into account 604 when implementing or utilizing this specification. A thorough 605 security analysis of this protocol, including its strengths and 606 weaknesses, can be found in Security Considerations for HTTP 607 Signatures [15]. 609 Appendix B. Extensions 611 This specification was designed to be simple, modular, and 612 extensible. There are a number of other specifications that build on 613 this one. For example, the HTTP Signature Nonces [16] specification 614 details how to use HTTP Signatures over a non-secured channel like 615 HTTP and the HTTP Signature Trailers [17] specification explains how 616 to apply HTTP Signatures to streaming content. Developers that 617 desire more functionality than this specification provides are urged 618 to ensure that an extension specification doesn't already exist 619 before implementing a proprietary extension. 621 If extensions to this specification are made by adding new Signature 622 Parameters, those extension parameters MUST be registered in the 623 Signature Authentication Scheme Registry. The registry will be 624 created and maintained at (the suggested URI) 625 http://www.iana.org/assignments/http-auth-scheme-signature [18]. An 626 example entry in this registry is included below: 628 Signature Parameter: nonce 629 Reference to specification: [HTTP_AUTH_SIGNATURE_NONCE], Section XYZ. 630 Notes (optional): The HTTP Signature Nonces specification details 631 how to use HTTP Signatures over a unsecured channel like HTTP. 633 Appendix C. Test Values 635 The following test data uses the following RSA 2048-bit keys, which 636 we will refer to as `keyId=Test` in the following samples: 638 -----BEGIN PUBLIC KEY----- 639 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3 640 6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6 641 Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw 642 oYi+1hqp1fIekaxsyQIDAQAB 643 -----END PUBLIC KEY----- 644 -----BEGIN RSA PRIVATE KEY----- 645 MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF 646 NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F 647 UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB 648 AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA 649 QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK 650 kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg 651 f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u 652 412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc 653 mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7 654 kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA 655 gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW 656 G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI 657 7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA== 658 -----END RSA PRIVATE KEY----- 660 All examples use this request: 662 POST /foo?param=value&pet=dog HTTP/1.1 663 Host: example.com 664 Date: Sun, 05 Jan 2014 21:31:40 GMT 665 Content-Type: application/json 666 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 667 Content-Length: 18 669 {"hello": "world"} 671 C.1. Default Test 673 If a list of headers is not included, the date is the only header 674 that is signed by default. The string to sign would be: 676 date: Sun, 05 Jan 2014 21:31:40 GMT 678 The Authorization header would be: 680 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 681 signature="SjWJWbWN7i0wzBvtPl8rbASWz5xQW6mcJmn+ibttBqtifLN7Sazz 682 6m79cNfwwb8DMJ5cou1s7uEGKKCs+FLEEaDV5lp7q25WqS+lavg7T8hc0GppauB 683 6hbgEKTwblDHYGEtbGmtdHgVCk9SuS13F0hZ8FD0k/5OxEPXe5WozsbM=" 685 The Signature header would be: 687 Signature: keyId="Test",algorithm="rsa-sha256", 688 signature="SjWJWbWN7i0wzBvtPl8rbASWz5xQW6mcJmn+ibttBqtifLN7Sazz 689 6m79cNfwwb8DMJ5cou1s7uEGKKCs+FLEEaDV5lp7q25WqS+lavg7T8hc0GppauB 690 6hbgEKTwblDHYGEtbGmtdHgVCk9SuS13F0hZ8FD0k/5OxEPXe5WozsbM=" 692 C.2. Basic Test 694 The minimum recommended data to sign is the (request-target), host, 695 and date. In this case, the string to sign would be: 697 (request-target): post /foo?param=value&pet=dog 698 host: example.com 699 date: Sun, 05 Jan 2014 21:31:40 GMT 701 The Authorization header would be: 703 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 704 headers="(request-target) host date", signature="qdx+H7PHHDZgy4 705 y/Ahn9Tny9V3GP6YgBPyUXMmoxWtLbHpUnXS2mg2+SbrQDMCJypxBLSPQR2aAjn 706 7ndmw2iicw3HMbe8VfEdKFYRqzic+efkb3nndiv/x1xSHDJWeSWkx3ButlYSuBs 707 kLu6kd9Fswtemr3lgdDEmn04swr2Os0=" 709 C.3. All Headers Test 711 A strong signature including all of the headers and a digest of the 712 body of the HTTP request would result in the following signing 713 string: 715 (request-target): post /foo?param=value&pet=dog 716 host: example.com 717 date: Sun, 05 Jan 2014 21:31:40 GMT 718 content-type: application/json 719 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 720 content-length: 18 722 The Authorization header would be: 724 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 725 headers="(request-target) host date content-type digest content-length", 726 signature="vSdrb+dS3EceC9bcwHSo4MlyKS59iFIrhgYkz8+oVLEEzmYZZvRs 727 8rgOp+63LEM3v+MFHB32NfpB2bEKBIvB1q52LaEUHFv120V01IL+TAD48XaERZF 728 ukWgHoBTLMhYS2Gb51gWxpeIq8knRmPnYePbF5MOkR0Zkly4zKH7s1dE=" 730 The Signature header would be: 732 Signature: keyId="Test",algorithm="rsa-sha256", 733 headers="(request-target) host date content-type digest content-length", 734 signature="vSdrb+dS3EceC9bcwHSo4MlyKS59iFIrhgYkz8+oVLEEzmYZZvRs 735 8rgOp+63LEM3v+MFHB32NfpB2bEKBIvB1q52LaEUHFv120V01IL+TAD48XaERZF 736 ukWgHoBTLMhYS2Gb51gWxpeIq8knRmPnYePbF5MOkR0Zkly4zKH7s1dE=" 737 Appendix D. Acknowledgements 739 The editor would like to thank the following individuals for feedback 740 on and implementations of the specification (in alphabetical order): 741 Mark Adamcin, Mark Allen, Paul Annesley, Karl Boehlmark, Stephen 742 Farrell, Phillip Hallam-Baker, Andrey Kislyuk, Adam Knight, Dave 743 Lehn, Dave Longley, James H. Manger, Ilari Liusvaara, Mark 744 Nottingham, Yoav Nir, Adrian Palmer, Lucas Pardue, Julian Reschke, 745 Michael Richardson, Adam Scarr, and Dirk Stein. 747 Appendix E. IANA Considerations 749 E.1. Signature Authentication Scheme 751 The following entry should be added to the Authentication Scheme 752 Registry located at http://www.iana.org/assignments/http-authschemes 753 [19] 755 Authentication Scheme Name: Signature 756 Reference: [RFC_THIS_DOCUMENT], Section 2. 757 Notes (optional): The Signature scheme is designed for clients to 758 authenticate themselves with a server. 760 E.2. Signature Algorithm Registry 762 The following initial entries should be added to the Signature 763 Algorithm Registry to be created and maintained at (the suggested 764 URI) http://www.iana.org/assignments/signature-algorithms [20]: 766 Editor's note: The references in this section are problematic as many 767 of the specifications that they refer to are too implementation 768 specific, rather than just pointing to the proper signature and 769 hashing specifications. A better approach might be just specifying 770 the signature and hashing function specifications, leaving 771 implementers to connect the dots (which are not that hard to 772 connect). 774 Algorithm Name: rsa-sha1 775 Reference: RFC 6376 [RFC6376], Section 3.3.1 776 Status: deprecated 778 Algorithm Name: rsa-sha256 779 Reference: RFC 6376 [RFC6376], Section 3.3.2 780 Status: active 782 Algorithm Name: hmac-sha256 783 Reference: HS256 in JOSE JSON Web Algorithms 784 [I-D.ietf-jose-json-web-algorithms], Section 3.2 785 Status: active 787 Algorithm Name: ecdsa-sha256 788 Reference: ES256 in JOSE JSON Web Algorithms 789 [I-D.ietf-jose-json-web-algorithms], Section 3.4 790 Status: active 792 Authors' Addresses 794 Mark Cavage 795 Oracle 796 500 Oracle Parkway 797 Redwood Shores, CA 94065 798 US 800 Phone: +1 415 400 0626 801 Email: mcavage@gmail.com 802 URI: http://www.oracle.com/ 804 Manu Sporny 805 Digital Bazaar 806 203 Roanoke Street W. 807 Blacksburg, VA 24060 808 US 810 Phone: +1 540 961 4469 811 Email: msporny@digitalbazaar.com 812 URI: http://manu.sporny.org/