idnits 2.17.1 draft-cavage-http-signatures-00.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 7 instances of too long lines in the document, the longest one being 246 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 (May 4, 2013) is 4010 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 361, 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) Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). 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: November 5, 2013 Digital Bazaar 6 May 4, 2013 8 HTTP Signatures 9 draft-cavage-http-signatures-00 11 Abstract 13 This document describes a way to add origin authentication, message 14 integrity, and replay resistance to HTTP requests. It is intended to 15 be used over the HTTPS protocol. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on November 5, 2013. 34 Copyright Notice 36 Copyright (c) 2013 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 49 2. Signature Authentication Scheme . . . . . . . . . . . . . . . . 3 50 2.1. Authorization Header . . . . . . . . . . . . . . . . . . . 3 51 2.1.1. Signature Parameters . . . . . . . . . . . . . . . . . 4 52 2.1.2. Signature String Construction . . . . . . . . . . . . . 5 53 3. Appendix A: Security Considerations . . . . . . . . . . . . . . 6 54 3.1. Default Parameters . . . . . . . . . . . . . . . . . . . . 6 55 3.2. Insecure Transports . . . . . . . . . . . . . . . . . . . . 7 56 3.3. Nonces . . . . . . . . . . . . . . . . . . . . . . . . . . 7 57 3.4. Clock Skew . . . . . . . . . . . . . . . . . . . . . . . . 7 58 3.5. Required Headers to Sign . . . . . . . . . . . . . . . . . 7 59 4. Appendix B: Test Values . . . . . . . . . . . . . . . . . . . . 8 60 4.1. Default Test . . . . . . . . . . . . . . . . . . . . . . . 8 61 4.2. All Headers Test . . . . . . . . . . . . . . . . . . . . . 9 62 5. Normative References . . . . . . . . . . . . . . . . . . . . . 9 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 65 1. Introduction 67 This protocol is intended to provide a standard way for clients to 68 sign HTTP requests. RFC 2617 [RFC2617] (HTTP Authentication) defines 69 Basic and Digest authentication mechanisms, and RFC 5246 [RFC5246] 70 (TLS 1.2) defines client-auth, both of which are widely employed on 71 the Internet today. However, it is common place that the burdens of 72 PKI prevent web service operators from deploying that methodoloy, and 73 so many fall back to Basic authentication, which has poor security 74 characteristics. 76 Additionally, OAuth provides a fully-specified alternative for 77 authorization of web service requests, but is not (always) ideal for 78 machine to machine communication, as the key acquisition steps 79 (generally) imply a fixed infrastructure that may not make sense to a 80 service provider (e.g., symmetric keys). 82 Several web service providers have invented their own schemes for 83 signing HTTP requests, but to date, none have been placed in the 84 public domain as a standard. This document serves that purpose. 85 There are no techniques in this proposal that are novel beyond 86 previous art, however, this aims to be a simple mechanism for signing 87 these requests. 89 2. Signature Authentication Scheme 91 The "signature" authentication scheme is based on the model that the 92 client must authenticate itself with a digital signature produced by 93 either a private asymmetric key (e.g., RSA) or a shared symmetric key 94 (e.g., HMAC). The scheme is parameterized enough such that it is not 95 bound to any particular key type or signing algorithm. However, it 96 does explicitly assume that clients can send an HTTP `Date` header. 98 2.1. Authorization Header 100 The client is expected to send an Authorization header (as defined in 101 RFC 2617) with the following parameterization: 103 credentials := "Signature" SP params 104 params := keyId "," algorithm [", " headers] [", " ext] ", " signature 106 keyId := "keyId" "=" plain-string 107 algorithm := "algorithm" "=" DQUOTE ( rsa-sha1 / rsa-sha256 / rsa-sha512 / 108 dsa-sha1 / hmac-sha1 / hmac-sha256 / 109 hmac-sha512 ) 110 DQUOTE 111 headers := "headers" "=" plain-string 112 ext := "ext" "=" plain-string 113 signature := "signature" "=" plain-string 115 plain-string = DQUOTE *( %x20-21 / %x23-5B / %x5D-7E ) DQUOTE 117 2.1.1. Signature Parameters 119 The following section details the signature parameters of the 120 Authorization Header. 122 2.1.1.1. keyId 124 REQUIRED. The `keyId` field is an opaque string that the server can 125 use to look up the component they need to validate the signature. It 126 could be an SSH key fingerprint, an LDAP DN, etc. Management of keys 127 and assignment of `keyId` is out of scope for this document. 129 2.1.1.2. algorithm 131 REQUIRED. The `algorithm` parameter is used if the client and server 132 agree on a non-standard digital signature algorithm. The full list 133 of supported signature mechanisms is listed below. 135 2.1.1.3. headers 137 OPTIONAL. The `headers` parameter is used to specify the list of 138 HTTP headers used to sign the request. If specified, it should be a 139 quoted list of HTTP header names, separated by a single space 140 character. By default, only one HTTP header is signed, which is the 141 `Date` header. Note that the list MUST be specified in the order the 142 values are concatenated together during signing. To include the HTTP 143 request line in the signature calculation, use the special `request- 144 line` value. While this is overloading the definition of `headers` 145 in HTTP linguism, the request-line is defined in RFC 2616 [RFC2616], 146 and as the outlier from headers in useful signature calculation, it 147 is deemed simpler to simply use `request-line` than to add a separate 148 parameter for it. 150 2.1.1.4. extensions 152 OPTIONAL. The `extensions` parameter is used to include additional 153 information which is covered by the request. The content and format 154 of the string is out of scope for this document, and expected to be 155 specified by implementors. 157 2.1.1.5. signature 159 REQUIRED. The `signature` parameter is a `Base64` encoded digital 160 signature generated by the client. The client uses the `algorithm` 161 and `headers` request parameters to form a canonicalized `signing 162 string`. This `signing string` is then signed with the key 163 associated with `keyId` and the algorithm corresponding to 164 `algorithm`. The `signature` parameter is then set to the `Base64` 165 encoding of the signature. 167 2.1.2. Signature String Construction 169 In order to generate the string that is signed with a key, the client 170 MUST take the values of each HTTP header specified by `headers` in 171 the order they appear. 173 1. If the header name is not `request-line` then append the 174 lowercased header name followed with an ASCII colon `:` and an 175 ASCII space ` `. 177 2. If the header name is `request-line` then appened the HTTP 178 request line, otherwise append the header value. 180 3. If value is not the last value then append an ASCII newline `\n`. 181 The string MUST NOT include a trailing ASCII newline. 183 The rest of this section uses the following HTTP request as an 184 example. 186 POST /foo HTTP/1.1 187 Host: example.org 188 Date: Tue, 07 Jun 2011 20:51:35 GMT 189 Content-Type: application/json 190 Content-MD5: lCMsW4/JJy9vc6HjbraPzw== 191 Content-Length: 15 193 {"bar": "baz"} 195 The following sections also assume that the "rsa-key-1" keyId refers 196 to a private key known to the client and a public key known to the 197 server. The "hmac-key-1" keyId refers to key known to the client and 198 server. 200 2.1.2.1. RSA Example 202 The authorization header and signature would be generated as: 204 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256",signature="Base64(RSA-SHA256(signing string))" 206 The client would compose the signing string as: 208 date: Tue, 07 Jun 2011 20:51:35 GMT 210 For an RSA-based signature, the authorization header and signature 211 would be generated as: 213 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256",headers="request-line date content-type content-md5",signature="Base64(RSA-SHA256(signing string))" 215 The client would compose the signing string as (`+ "\n"` inserted for 216 readability): 218 POST /foo HTTP/1.1 + "\n" 219 date: Tue, 07 Jun 2011 20:51:35 GMT + "\n" 220 content-type: application/json + "\n" 221 content-md5: lCMsW4/JJy9vc6HjbraPzw== 223 2.1.2.2. HMAC Example 225 For an HMAC-based signature without a list of headers specified, the 226 authorization header and signature would be generated as: 228 Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha1",signature="Base64(HMAC-SHA1(signing string))" 230 The client would compose the signing string as: 232 date: Tue, 07 Jun 2011 20:51:35 GMT 234 3. Appendix A: Security Considerations 236 There are a number of security considerations to take into account 237 when deploying HTTP Signatures. 239 3.1. Default Parameters 241 Note the default parameterization of the `Signature` scheme is only 242 safe if all requests are carried over a secure transport (i.e., TLS). 243 Sending the default scheme over a non-secure transport will leave the 244 request vulnerable to spoofing, tampering, replay/repudiaton, and 245 integrity violations (if using the STRIDE threat-modeling 246 methodology). 248 3.2. Insecure Transports 250 If sending the request over plain HTTP, service providers SHOULD 251 require clients to sign ALL HTTP headers, and the `request-line`. 252 Additionally, service providers SHOULD require `Content-MD5` 253 calculations to be performed to ensure against any tampering from 254 clients. 256 3.3. Nonces 258 Nonces are out of scope for this document simply because many service 259 providers fail to implement them correctly, or do not adopt security 260 specfiications because of the infrastructure complexity. Given the 261 `header` parameterization, a service provider is fully enabled to add 262 nonce semantics into this scheme by using something like an 263 `x-request-nonce` header, and ensuring it is signed with the `Date` 264 header. 266 ISSUE: This specification should probably explain exactly how to 267 implement nonces for implementers that would like a fully vetted 268 solution that protects against replay. This would be useful for 269 implementers implementing HTTP signatures in a clear channel 270 environment. Another consideration for nonces is the probability 271 that multiple clients may share the same public key. In this 272 instance, due to clock skew issues, it is possible that some clients 273 may accidentally trigger replay protection by sending a date in the 274 past. The balance that this spec attempts to achieve is a simple 275 per-client, time-based counter. Thus, the nonce would need to 276 include something like a UUID-based client identifier, plus an 277 incredibly accurate UTC datetime-based nonce as described in RFC 3339 278 [RFC3339]. For example: "598ef3e8-98b0-435d-8ca3-fecefdd87568 2013- 279 05-04 20:00:35.808785840+00:00" 281 3.4. Clock Skew 283 As the default scheme is to sign the `Date` header, service providers 284 SHOULD protect against logged replay attacks by enforcing a clock 285 skew. The server SHOULD be synchronized with NTP, and the 286 recommendation in this specification is to allow 300s of clock skew 287 (in either direction). 289 3.5. Required Headers to Sign 291 It is out of scope for this document to dictate what headers a 292 service provider will want to enforce, but service providers SHOULD 293 at minimum include the `Date` header. 295 4. Appendix B: Test Values 297 The following test data uses the following RSA 2048-bit keys, which 298 we will refer to as `keyId=Test` in the following samples: 300 -----BEGIN PUBLIC KEY----- 301 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3 302 6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6 303 Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw 304 oYi+1hqp1fIekaxsyQIDAQAB 305 -----END PUBLIC KEY----- 307 -----BEGIN RSA PRIVATE KEY----- 308 MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF 309 NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F 310 UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB 311 AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA 312 QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK 313 kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg 314 f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u 315 412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc 316 mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7 317 kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA 318 gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW 319 G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI 320 7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA== 321 -----END RSA PRIVATE KEY----- 323 And all examples use this request: 325 POST /foo?param=value&pet=dog HTTP/1.1 326 Host: example.com 327 Date: Thu, 05 Jan 2012 21:31:40 GMT 328 Content-Type: application/json 329 Content-MD5: Sd/dVLAcvNLSq16eXua5uQ== 330 Content-Length: 18 332 {"hello": "world"} 334 4.1. Default Test 336 The string to sign would be: 338 date: Thu, 05 Jan 2012 21:31:40 GMT 339 The Authorization header would be: 341 Authorization: Signature keyId="Test",algorithm="rsa-sha256",signature="JldXnt8W9t643M2Sce10gqCh/+E7QIYLiI+bSjnFBGCti7s+mPPvOjVb72sbd1FjeOUwPTDpKbrQQORrm+xBYfAwCxF3LBSSzORvyJ5nRFCFxfJ3nlQD6Kdxhw8wrVZX5nSem4A/W3C8qH5uhFTRwF4ruRjh+ENHWuovPgO/HGQ=" 343 4.2. All Headers Test 345 Parameterized to include all headers, the string to sign would be (`+ 346 "\n"` inserted for readability): 348 POST /foo?param=value&pet=dog HTTP/1.1 + "\n" 349 host: example.com + "\n" 350 date: Thu, 05 Jan 2012 21:31:40 GMT + "\n" 351 content-type: application/json + "\n" 352 content-md5: Sd/dVLAcvNLSq16eXua5uQ== + "\n" 353 content-length: 18 355 The Authorization header would be: 357 Authorization: Signature keyId="Test",algorithm="rsa-sha256",headers="request-line host date content-type content-md5 content-length",signature="Gm7W/r+e90REDpWytALMrft4MqZxCmslOTOvwJX17ViEBA5E65QqvWI0vIH3l/vSsGiaMVmuUgzYsJLYMLcm5dGrv1+a+0fCoUdVKPZWHyImQEqpLkopVwqEH67LVECFBqFTAKlQgBn676zrfXQbb+b/VebAsNUtvQMe6cTjnDY=" 359 5. Normative References 361 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 362 Requirement Levels", BCP 14, RFC 2119, March 1997. 364 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 365 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 366 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 368 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 369 Leach, P., Luotonen, A., and L. Stewart, "HTTP 370 Authentication: Basic and Digest Access Authentication", 371 RFC 2617, June 1999. 373 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 374 Internet: Timestamps", RFC 3339, July 2002. 376 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 377 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 379 Authors' Addresses 381 Mark Cavage 382 Joyent 383 One Embarcadero Center 384 9th Floor 385 San Francisco, CA 94111 386 US 388 Phone: +1 ??? ??? ???? 389 Email: mark.cavage@joyent.com 390 URI: http://www.joyent.com/ 392 Manu Sporny 393 Digital Bazaar 394 1700 Kraft Drive 395 Suite 2408 396 Blacksburg, VA 24060 397 US 399 Phone: +1 540 961 4469 400 Email: msporny@digitalbazaar.com 401 URI: http://manu.sporny.org/