idnits 2.17.1 draft-cavage-http-signatures-01.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. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 2 instances of too long lines in the document, the longest one being 2 characters in excess of 72. 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 (February 1, 2014) is 3737 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) == Unused Reference: 'RFC2119' is defined on line 359, but no explicit reference was found in the text == Unused Reference: 'RFC3339' is defined on line 371, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' -- Possible downref: Non-RFC (?) normative reference: ref. '3' Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 4 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: August 5, 2014 Digital Bazaar 6 February 1, 2014 8 HTTP Signatures 9 draft-cavage-http-signatures-01 11 Abstract 13 When communicating over the Internet using the HTTP protocol, it is 14 often desirable to be able to securely verify the sender of a message 15 as well as ensure that the message was not tampered with during 16 transit. This document describes a way to add origin authentication 17 and message integrity to HTTP messages. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on August 5, 2014. 36 Copyright Notice 38 Copyright (c) 2014 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. Signature Authentication Scheme . . . . . . . . . . . . . . . 3 52 2.1. Authorization Header . . . . . . . . . . . . . . . . . . . 3 53 2.1.1. Signature Parameters . . . . . . . . . . . . . . . . . 4 54 2.1.2. Signature String Construction . . . . . . . . . . . . 5 55 3. Appendix A: Security Considerations . . . . . . . . . . . . . 7 56 4. Appendix B: Extensions . . . . . . . . . . . . . . . . . . . . 7 57 5. Appendix C: Test Values . . . . . . . . . . . . . . . . . . . 7 58 5.1. Default Test . . . . . . . . . . . . . . . . . . . . . . . 8 59 5.2. Basic Test . . . . . . . . . . . . . . . . . . . . . . . . 8 60 5.3. All Headers Test . . . . . . . . . . . . . . . . . . . . . 9 61 6. Normative References . . . . . . . . . . . . . . . . . . . . . 9 62 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 64 1. Introduction 66 This protocol is intended to provide a standard way for clients to 67 sign HTTP requests. RFC 2617 [RFC2617] (HTTP Authentication) defines 68 Basic and Digest authentication mechanisms, and RFC 5246 [RFC5246] 69 (TLS 1.2) defines client-auth, both of which are widely employed on 70 the Internet today. However, it is common place that the burdens of 71 PKI prevent web service operators from deploying that methodoloy, and 72 so many fall back to Basic authentication, which has poor security 73 characteristics. 75 Additionally, OAuth provides a fully-specified alternative for 76 authorization of web service requests, but is not (always) ideal for 77 machine to machine communication, as the key acquisition steps 78 (generally) imply a fixed infrastructure that may not make sense to a 79 service provider (e.g., symmetric keys). 81 Several web service providers have invented their own schemes for 82 signing HTTP requests, but to date, none have been placed in the 83 public domain as a standard. This document serves that purpose. 84 There are no techniques in this proposal that are novel beyond 85 previous art, however, this aims to be a simple mechanism for signing 86 these requests. 88 2. Signature Authentication Scheme 90 The "signature" authentication scheme is based on the model that the 91 client must authenticate itself with a digital signature produced by 92 either a private asymmetric key (e.g., RSA) or a shared symmetric key 93 (e.g., HMAC). The scheme is parameterized enough such that it is not 94 bound to any particular key type or signing algorithm. However, it 95 does explicitly assume that clients can send an HTTP `Date` header. 97 2.1. Authorization Header 99 The client is expected to send an Authorization header (as defined in 100 RFC 2617) with the following parameterization: 102 credentials := "Signature" SP params 103 params := keyId "," algorithm [", " headers] [", " ext] ", " signature 105 keyId := "keyId" "=" plain-string 106 algorithm := "algorithm" "=" DQUOTE ( rsa-sha1 / rsa-sha256 / rsa-sha512 / 107 dsa-sha1 / hmac-sha1 / hmac-sha256 / 108 hmac-sha512 ) 109 DQUOTE 110 headers := "headers" "=" plain-string 111 ext := "ext" "=" plain-string 112 signature := "signature" "=" plain-string 114 plain-string = DQUOTE *( %x20-21 / %x23-5B / %x5D-7E ) DQUOTE 116 2.1.1. Signature Parameters 118 The following section details the signature parameters of the 119 Authorization Header. 121 2.1.1.1. keyId 123 REQUIRED. The `keyId` field is an opaque string that the server can 124 use to look up the component they need to validate the signature. It 125 could be an SSH key fingerprint, an LDAP DN, etc. Management of keys 126 and assignment of `keyId` is out of scope for this document. 128 2.1.1.2. algorithm 130 REQUIRED. The `algorithm` parameter is used if the client and server 131 agree on a non-standard digital signature algorithm. The full list 132 of supported signature mechanisms is listed below. 134 2.1.1.3. headers 136 OPTIONAL. The `headers` parameter is used to specify the list of 137 HTTP headers used to sign the request. If specified, it should be a 138 quoted list of HTTP header names, separated by a single space 139 character. By default, only one HTTP header is signed, which is the 140 `Date` header. Note that the list MUST be specified in the order the 141 values are concatenated together during signing. To include the HTTP 142 request line in the signature calculation, use the special `request- 143 line` value. While this is overloading the definition of `headers` 144 in HTTP linguism, the request-line is defined in RFC 2616 [RFC2616], 145 and as the outlier from headers in useful signature calculation, it 146 is deemed simpler to use `request-line` than to add a separate 147 parameter for it. 149 2.1.1.4. extensions 151 OPTIONAL. The `extensions` parameter is used to include additional 152 information which is covered by the request. The content and format 153 of the string is out of scope for this document, and expected to be 154 specified by implementors. 156 2.1.1.5. signature 158 REQUIRED. The `signature` parameter is a `Base64` encoded digital 159 signature generated by the client. The client uses the `algorithm` 160 and `headers` request parameters to form a canonicalized `signing 161 string`. This `signing string` is then signed with the key 162 associated with `keyId` and the algorithm corresponding to 163 `algorithm`. The `signature` parameter is then set to the `Base64` 164 encoding of the signature. 166 2.1.2. Signature String Construction 168 In order to generate the string that is signed with a key, the client 169 MUST take the values of each HTTP header specified by `headers` in 170 the order they appear. It is out of scope for this document to 171 dictate what headers a service provider will want to enforce, but 172 service providers SHOULD at minimum include the request line, Host, 173 and Date headers. 175 1. If the header name is not `request-line` then append the 176 lowercased header name followed with an ASCII colon `:` and an 177 ASCII space ` `. 179 2. If the header name is `request-line` then appened the HTTP 180 request line, otherwise append the header value. 182 3. If value is not the last value then append an ASCII newline `\n`. 183 The string MUST NOT include a trailing ASCII newline. 185 The rest of this section uses the following HTTP request as an 186 example. 188 POST /foo HTTP/1.1 189 Host: example.org 190 Date: Tue, 07 Jun 2014 20:51:35 GMT 191 Content-Type: application/json 192 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 193 Content-Length: 18 195 {"hello": "world"} 196 The following sections also assume that the "rsa-key-1" keyId refers 197 to a private key known to the client and a public key known to the 198 server. The "hmac-key-1" keyId refers to key known to the client and 199 server. 201 2.1.2.1. RSA Example 203 The authorization header and signature would be generated as: 205 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256", 206 headers="request-line host date digest content-length", 207 signature="Base64(RSA-SHA256(signing string))" 209 The client would compose the signing string as: 211 POST /foo HTTP/1.1\n 212 host: example.org\n 213 date: Tue, 07 Jun 2014 20:51:35 GMT\n 214 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 215 content-length: 18 217 Note that the '\n' symbols above are included to demonstrate where 218 the new line character should be inserted. There is no new line on 219 the final line of the signing string. 221 For an RSA-based signature, the authorization header and signature 222 would then be generated as: 224 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256", 225 headers="request-line host date digest content-length", 226 signature="Base64(RSA-SHA256(signing string))" 228 2.1.2.2. HMAC Example 230 For an HMAC-based signature without a list of headers specified, the 231 authorization header and signature would be generated as: 233 Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha1", 234 headers="request-line host date digest content-length", 235 signature="Base64(HMAC-SHA1(signing string))" 237 The only difference between the RSA Example and the HMAC Example is 238 the signature algorithm that is used. The client would compose the 239 signing string in the same way as the RSA Example above: 241 POST /foo HTTP/1.1\n 242 host: example.org\n 243 date: Tue, 07 Jun 2014 20:51:35 GMT\n 244 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=\n 245 content-length: 18 247 3. Appendix A: Security Considerations 249 There are a number of security considerations to take into account 250 when implementing or utilizing this specification. A thorough 251 security analysis of this protocol, including its strengths and 252 weaknesses, can be found in Security Considerations for HTTP 253 Signatures [1]. 255 4. Appendix B: Extensions 257 This specification was designed to be simple, modular, and 258 extensible. There are a number of other specifications that build on 259 this one. For example, the HTTP Signature Nonces [2] specification 260 details how to use HTTP Signatures over a non-secured channel like 261 HTTP and the HTTP Signature Trailers [3] specification explains how 262 to apply HTTP Signatures to streaming content. Developers that 263 desire more functionality than this specification provides are urged 264 to ensure that an extension specification doesn't already exist 265 before implementing a proprietary extension. 267 5. Appendix C: Test Values 269 The following test data uses the following RSA 2048-bit keys, which 270 we will refer to as `keyId=Test` in the following samples: 272 -----BEGIN PUBLIC KEY----- 273 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3 274 6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6 275 Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw 276 oYi+1hqp1fIekaxsyQIDAQAB 277 -----END PUBLIC KEY----- 278 -----BEGIN RSA PRIVATE KEY----- 279 MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF 280 NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F 281 UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB 282 AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA 283 QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK 284 kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg 285 f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u 286 412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc 287 mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7 288 kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA 289 gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW 290 G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI 291 7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA== 292 -----END RSA PRIVATE KEY----- 294 All examples use this request: 296 POST /foo?param=value&pet=dog HTTP/1.1 297 Host: example.com 298 Date: Thu, 05 Jan 2014 21:31:40 GMT 299 Content-Type: application/json 300 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 301 Content-Length: 18 303 {"hello": "world"} 305 5.1. Default Test 307 If a list of headers is not included, the date is the only header 308 that is signed by default. The string to sign would be: 310 date: Thu, 05 Jan 2014 21:31:40 GMT 312 The Authorization header would be: 314 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 315 signature="ATp0r26dbMIxOopqw0OfABDT7CKMIoENumuruOtarj8n/97Q3htH 316 FYpH8yOSQk3Z5zh8UxUym6FYTb5+A0Nz3NRsXJibnYi7brE/4tx5But9kkFGzG+ 317 xpUmimN4c3TMN7OFH//+r8hBf7BT9/GmHDUVZT2JzWGLZES2xDOUuMtA=" 319 5.2. Basic Test 321 The minimum recommended data to sign is the request-line, host, and 322 date. In this case, the string to sign would be: 324 POST /foo?param=value&pet=dog HTTP/1.1 325 host: example.com 326 date: Thu, 05 Jan 2014 21:31:40 GMT 328 The Authorization header would be: 330 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 331 headers="request-line host date", signature="KcLSABBj/m3v2Dhxi 332 CKJmzYJvnx74tDO1SaURD8Dr8XpugN5wpy8iBVJtpkHUIp4qBYpzx2QvD16t8X 333 0BUMiKc53Age+baQFWwb2iYYJzvuUL+krrl/Q7H6fPBADBsHqEZ7IE8rR0Ys3l 334 b7J5A6VB9J/4yVTRiBcxTypW/mpr5w=" 336 5.3. All Headers Test 338 A strong signature including all of the headers and a digest of the 339 body of the HTTP request would result in the following signing 340 string: 342 POST /foo?param=value&pet=dog HTTP/1.1 343 host: example.com 344 date: Thu, 05 Jan 2014 21:31:40 GMT 345 content-type: application/json 346 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= 347 content-length: 18 349 The Authorization header would be: 351 Authorization: Signature keyId="Test",algorithm="rsa-sha256", 352 headers="request-line host date content-type digest content-length", 353 signature="jgSqYK0yKclIHfF9zdApVEbDp5eqj8C4i4X76pE+XHoxugXv7q 354 nVrGR+30bmBgtpR39I4utq17s9ghz/2QFVxlnToYAvbSVZJ9ulLd1HQBugO0j 355 Oyn9sXOtcN7uNHBjqNCqUsnt0sw/cJA6B6nJZpyNqNyAXKdxZZItOuhIs78w=" 357 6. Normative References 359 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 360 Requirement Levels", BCP 14, RFC 2119, March 1997. 362 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 363 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 364 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 366 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 367 Leach, P., Luotonen, A., and L. Stewart, "HTTP 368 Authentication: Basic and Digest Access Authentication", 369 RFC 2617, June 1999. 371 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 372 Internet: Timestamps", RFC 3339, July 2002. 374 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 375 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 377 [1] 379 [2] 381 [3] 383 Authors' Addresses 385 Mark Cavage 386 Joyent 387 One Embarcadero Center 388 9th Floor 389 San Francisco, CA 94111 390 US 392 Phone: +1 415 400 0626 393 Email: mark.cavage@joyent.com 394 URI: http://www.joyent.com/ 396 Manu Sporny 397 Digital Bazaar 398 1700 Kraft Drive 399 Suite 2408 400 Blacksburg, VA 24060 401 US 403 Phone: +1 540 961 4469 404 Email: msporny@digitalbazaar.com 405 URI: http://manu.sporny.org/