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/