3 This document describes a way to add origin authentication, message integrity,
4 and replay resistance to HTTP REST requests. It is intended to be used over
9 Copyright (c) 2011 Joyent, Inc. and the persons identified as document authors.
12 Code Components extracted from this document must include MIT License text.
16 This protocol is intended to provide a standard way for clients to sign HTTP
17 requests. RFC2617 (HTTP Authentication) defines Basic and Digest authentication
18 mechanisms, and RFC5246 (TLS 1.2) defines client-auth, both of which are widely
19 employed on the Internet today. However, it is common place that the burdens of
20 PKI prevent web service operators from deploying that methodology, and so many
21 fall back to Basic authentication, which has poor security characteristics.
23 Additionally, OAuth provides a fully-specified alternative for authorization
24 of web service requests, but is not (always) ideal for machine to machine
25 communication, as the key acquisition steps (generally) imply a fixed
26 infrastructure that may not make sense to a service provider (e.g., symmetric
29 Several web service providers have invented their own schemes for signing
30 HTTP requests, but to date, none have been placed in the public domain as a
31 standard. This document serves that purpose. There are no techniques in this
32 proposal that are novel beyond previous art, however, this aims to be a simple
33 mechanism for signing these requests.
35 # Signature Authentication Scheme
37 The "signature" authentication scheme is based on the model that the client must
38 authenticate itself with a digital signature produced by either a private
39 asymmetric key (e.g., RSA) or a shared symmetric key (e.g., HMAC). The scheme
40 is parameterized enough such that it is not bound to any particular key type or
41 signing algorithm. However, it does explicitly assume that clients can send an
44 ## Authorization Header
46 The client is expected to send an Authorization header (as defined in RFC 2617)
47 with the following parameterization:
49 credentials := "Signature" params
50 params := 1#(keyId | algorithm | [headers] | [ext] | signature)
51 digitalSignature := plain-string
53 keyId := "keyId" "=" <"> plain-string <">
54 algorithm := "algorithm" "=" <"> plain-string <">
55 headers := "headers" "=" <"> 1#headers-value <">
56 ext := "ext" "=" <"> plain-string <">
57 signature := "signature" "=" <"> plain-string <">
59 headers-value := plain-string
60 plain-string = 1*( %x20-21 / %x23-5B / %x5D-7E )
62 ### Signature Parameters
66 REQUIRED. The `keyId` field is an opaque string that the server can use to look
67 up the component they need to validate the signature. It could be an SSH key
68 fingerprint, an LDAP DN, etc. Management of keys and assignment of `keyId` is
69 out of scope for this document.
73 REQUIRED. The `algorithm` parameter is used if the client and server agree on a
74 non-standard digital signature algorithm. The full list of supported signature
75 mechanisms is listed below.
79 OPTIONAL. The `headers` parameter is used to specify the list of HTTP headers
80 used to sign the request. If specified, it should be a quoted list of HTTP
81 header names, separated by a single space character. By default, only one
82 HTTP header is signed, which is the `Date` header. Note that the list MUST be
83 specified in the order the values are concatenated together during signing. To
84 include the HTTP request line in the signature calculation, use the special
85 `request-line` value. While this is overloading the definition of `headers` in
86 HTTP linguism, the request-line is defined in RFC 2616, and as the outlier from
87 headers in useful signature calculation, it is deemed simpler to simply use
88 `request-line` than to add a separate parameter for it.
92 OPTIONAL. The `extensions` parameter is used to include additional information
93 which is covered by the request. The content and format of the string is out of
94 scope for this document, and expected to be specified by implementors.
98 REQUIRED. The `signature` parameter is a `Base64` encoded digital signature
99 generated by the client. The client uses the `algorithm` and `headers` request
100 parameters to form a canonicalized `signing string`. This `signing string` is
101 then signed with the key associated with `keyId` and the algorithm
102 corresponding to `algorithm`. The `signature` parameter is then set to the
103 `Base64` encoding of the signature.
105 ### Signing String Composition
107 In order to generate the string that is signed with a key, the client MUST take
108 the values of each HTTP header specified by `headers` in the order they appear.
110 1. If the header name is not `request-line` then append the lowercased header
111 name followed with an ASCII colon `:` and an ASCII space ` `.
112 2. If the header name is `request-line` then append the HTTP request line,
113 otherwise append the header value.
114 3. If value is not the last value then append an ASCII newline `\n`. The string
115 MUST NOT include a trailing ASCII newline.
119 All requests refer to the following request (body omitted):
123 Date: Tue, 07 Jun 2014 20:51:35 GMT
124 Content-Type: application/json
125 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
128 The "rsa-key-1" keyId refers to a private key known to the client and a public
129 key known to the server. The "hmac-key-1" keyId refers to key known to the
132 ## Default parameterization
134 The authorization header and signature would be generated as:
136 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256",signature="Base64(RSA-SHA256(signing string))"
138 The client would compose the signing string as:
140 date: Tue, 07 Jun 2014 20:51:35 GMT
144 The authorization header and signature would be generated as:
146 Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256",headers="(request-target) date content-type digest",signature="Base64(RSA-SHA256(signing string))"
148 The client would compose the signing string as (`+ "\n"` inserted for
151 (request-target) post /foo + "\n"
152 date: Tue, 07 Jun 2011 20:51:35 GMT + "\n"
153 content-type: application/json + "\n"
154 digest: SHA-256=Base64(SHA256(Body))
158 The authorization header and signature would be generated as:
160 Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha1",signature="Base64(HMAC-SHA1(signing string))"
162 The client would compose the signing string as:
164 date: Tue, 07 Jun 2011 20:51:35 GMT
168 Currently supported algorithm names are:
178 # Security Considerations
180 ## Default Parameters
182 Note the default parameterization of the `Signature` scheme is only safe if all
183 requests are carried over a secure transport (i.e., TLS). Sending the default
184 scheme over a non-secure transport will leave the request vulnerable to
185 spoofing, tampering, replay/repudiation, and integrity violations (if using the
186 STRIDE threat-modeling methodology).
188 ## Insecure Transports
190 If sending the request over plain HTTP, service providers SHOULD require clients
191 to sign ALL HTTP headers, and the `request-line`. Additionally, service
192 providers SHOULD require `Content-MD5` calculations to be performed to ensure
193 against any tampering from clients.
197 Nonces are out of scope for this document simply because many service providers
198 fail to implement them correctly, or do not adopt security specifications
199 because of the infrastructure complexity. Given the `header` parameterization,
200 a service provider is fully enabled to add nonce semantics into this scheme by
201 using something like an `x-request-nonce` header, and ensuring it is signed
202 with the `Date` header.
206 As the default scheme is to sign the `Date` header, service providers SHOULD
207 protect against logged replay attacks by enforcing a clock skew. The server
208 SHOULD be synchronized with NTP, and the recommendation in this specification
209 is to allow 300s of clock skew (in either direction).
211 ## Required Headers to Sign
213 It is out of scope for this document to dictate what headers a service provider
214 will want to enforce, but service providers SHOULD at minimum include the
219 ## Normative References
221 * [RFC2616] Hypertext Transfer Protocol -- HTTP/1.1
222 * [RFC2617] HTTP Authentication: Basic and Digest Access Authentication
223 * [RFC5246] The Transport Layer Security (TLS) Protocol Version 1.2
225 ## Informative References
227 Name: Mark Cavage (editor)
228 Company: Joyent, Inc.
229 Email: mark.cavage@joyent.com
230 URI: http://www.joyent.com
232 # Appendix A - Test Values
234 The following test data uses the RSA (1024b) keys, which we will refer
235 to as `keyId=Test` in the following samples:
237 -----BEGIN PUBLIC KEY-----
238 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3
239 6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6
240 Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw
241 oYi+1hqp1fIekaxsyQIDAQAB
242 -----END PUBLIC KEY-----
244 -----BEGIN RSA PRIVATE KEY-----
245 MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF
246 NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F
247 UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB
248 AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA
249 QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK
250 kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg
251 f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u
252 412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc
253 mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7
254 kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA
255 gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW
256 G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI
257 7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA==
258 -----END RSA PRIVATE KEY-----
260 And all examples use this request:
264 POST /foo?param=value&pet=dog HTTP/1.1
266 Date: Thu, 05 Jan 2014 21:31:40 GMT
267 Content-Type: application/json
268 Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
277 The string to sign would be:
279 <!-- sign {"name": "Default", "options": {"keyId":"Test", "algorithm": "rsa-sha256"}} -->
282 date: Thu, 05 Jan 2014 21:31:40 GMT
286 The Authorization header would be:
290 Authorization: Signature keyId="Test",algorithm="rsa-sha256",headers="date",signature="jKyvPcxB4JbmYY4mByyBY7cZfNl4OW9HpFQlG7N4YcJPteKTu4MWCLyk+gIr0wDgqtLWf9NLpMAMimdfsH7FSWGfbMFSrsVTHNTk0rK3usrfFnti1dxsM4jl0kYJCKTGI/UWkqiaxwNiKqGcdlEDrTcUhhsFsOIo8VhddmZTZ8w="
296 Parameterized to include all headers, the string to sign would be (`+ "\n"`
297 inserted for readability):
299 <!-- sign {"name": "All Headers", "options": {"keyId":"Test", "algorithm": "rsa-sha256", "headers": ["(request-target)", "host", "date", "content-type", "digest", "content-length"]}} -->
302 (request-target): post /foo?param=value&pet=dog
304 date: Thu, 05 Jan 2014 21:31:40 GMT
305 content-type: application/json
306 digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
311 The Authorization header would be:
315 Authorization: Signature keyId="Test",algorithm="rsa-sha256",headers="(request-target) host date content-type digest content-length",signature="Ef7MlxLXoBovhil3AlyjtBwAL9g4TN3tibLj7uuNB3CROat/9KaeQ4hW2NiJ+pZ6HQEOx9vYZAyi+7cmIkmJszJCut5kQLAwuX+Ms/mUFvpKlSo9StS2bMXDBNjOh4Auj774GFj4gwjS+3NhFeoqyr/MuN6HsEnkvn6zdgfE2i0="
319 ## Generating and verifying signatures using `openssl`
321 The `openssl` commandline tool can be used to generate or verify the signatures listed above.
323 Compose the signing string as usual, and pipe it into the the `openssl dgst` command, then into `openssl enc -base64`, as follows:
325 $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \
326 openssl dgst -binary -sign /path/to/private.pem -sha256 | \
328 jKyvPcxB4JbmYY4mByyBY7cZfNl4OW9Hp...
331 The `-sha256` option is necessary to produce an `rsa-sha256` signature. You can select other hash algorithms such as `sha1` by changing this argument.
333 To verify a signature, first save the signature data, Base64-decoded, into a file, then use `openssl dgst` again with the `-verify` option:
335 $ echo 'jKyvPcxB4JbmYY4mByy...' | openssl enc -A -d -base64 > signature
336 $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \
337 openssl dgst -sha256 -verify /path/to/public.pem -signature ./signature
341 ## Generating and verifying signatures using `sshpk-sign`
343 You can also generate and check signatures using the `sshpk-sign` tool which is
344 included with the `sshpk` package in `npm`.
346 Compose the signing string as above, and pipe it into `sshpk-sign` as follows:
348 $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \
349 sshpk-sign -i /path/to/private.pem
350 jKyvPcxB4JbmYY4mByyBY7cZfNl4OW9Hp...
353 This will produce an `rsa-sha256` signature by default, as you can see using
356 sshpk-sign: using rsa-sha256 with a 1024 bit key
358 You can also use `sshpk-verify` in a similar manner:
360 $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \
361 sshpk-verify -i ./public.pem -s 'jKyvPcxB4JbmYY...'