diff options
Diffstat (limited to 'deps/npm/node_modules/http-signature/http_signing.md')
| -rw-r--r-- | deps/npm/node_modules/http-signature/http_signing.md | 363 |
1 files changed, 363 insertions, 0 deletions
diff --git a/deps/npm/node_modules/http-signature/http_signing.md b/deps/npm/node_modules/http-signature/http_signing.md new file mode 100644 index 0000000000..4f24d28c3c --- /dev/null +++ b/deps/npm/node_modules/http-signature/http_signing.md @@ -0,0 +1,363 @@ +# Abstract + +This document describes a way to add origin authentication, message integrity, +and replay resistance to HTTP REST requests. It is intended to be used over +the HTTPS protocol. + +# Copyright Notice + +Copyright (c) 2011 Joyent, Inc. and the persons identified as document authors. +All rights reserved. + +Code Components extracted from this document must include MIT License text. + +# Introduction + +This protocol is intended to provide a standard way for clients to sign HTTP +requests. RFC2617 (HTTP Authentication) defines Basic and Digest authentication +mechanisms, and RFC5246 (TLS 1.2) defines client-auth, both of which are widely +employed on the Internet today. However, it is common place that the burdens of +PKI prevent web service operators from deploying that methodology, and so many +fall back to Basic authentication, which has poor security characteristics. + +Additionally, OAuth provides a fully-specified alternative for authorization +of web service requests, but is not (always) ideal for machine to machine +communication, as the key acquisition steps (generally) imply a fixed +infrastructure that may not make sense to a service provider (e.g., symmetric +keys). + +Several web service providers have invented their own schemes for signing +HTTP requests, but to date, none have been placed in the public domain as a +standard. This document serves that purpose. There are no techniques in this +proposal that are novel beyond previous art, however, this aims to be a simple +mechanism for signing these requests. + +# Signature Authentication Scheme + +The "signature" authentication scheme is based on the model that the client must +authenticate itself with a digital signature produced by either a private +asymmetric key (e.g., RSA) or a shared symmetric key (e.g., HMAC). The scheme +is parameterized enough such that it is not bound to any particular key type or +signing algorithm. However, it does explicitly assume that clients can send an +HTTP `Date` header. + +## Authorization Header + +The client is expected to send an Authorization header (as defined in RFC 2617) +with the following parameterization: + + credentials := "Signature" params + params := 1#(keyId | algorithm | [headers] | [ext] | signature) + digitalSignature := plain-string + + keyId := "keyId" "=" <"> plain-string <"> + algorithm := "algorithm" "=" <"> plain-string <"> + headers := "headers" "=" <"> 1#headers-value <"> + ext := "ext" "=" <"> plain-string <"> + signature := "signature" "=" <"> plain-string <"> + + headers-value := plain-string + plain-string = 1*( %x20-21 / %x23-5B / %x5D-7E ) + +### Signature Parameters + +#### keyId + +REQUIRED. The `keyId` field is an opaque string that the server can use to look +up the component they need to validate the signature. It could be an SSH key +fingerprint, an LDAP DN, etc. Management of keys and assignment of `keyId` is +out of scope for this document. + +#### algorithm + +REQUIRED. The `algorithm` parameter is used if the client and server agree on a +non-standard digital signature algorithm. The full list of supported signature +mechanisms is listed below. + +#### headers + +OPTIONAL. The `headers` parameter is used to specify the list of HTTP headers +used to sign the request. If specified, it should be a quoted list of HTTP +header names, separated by a single space character. By default, only one +HTTP header is signed, which is the `Date` header. Note that the list MUST be +specified in the order the values are concatenated together during signing. To +include the HTTP request line in the signature calculation, use the special +`request-line` value. While this is overloading the definition of `headers` in +HTTP linguism, the request-line is defined in RFC 2616, and as the outlier from +headers in useful signature calculation, it is deemed simpler to simply use +`request-line` than to add a separate parameter for it. + +#### extensions + +OPTIONAL. The `extensions` parameter is used to include additional information +which is covered by the request. The content and format of the string is out of +scope for this document, and expected to be specified by implementors. + +#### signature + +REQUIRED. The `signature` parameter is a `Base64` encoded digital signature +generated by the client. The client uses the `algorithm` and `headers` request +parameters to form a canonicalized `signing string`. This `signing string` is +then signed with the key associated with `keyId` and the algorithm +corresponding to `algorithm`. The `signature` parameter is then set to the +`Base64` encoding of the signature. + +### Signing String Composition + +In order to generate the string that is signed with a key, the client MUST take +the values of each HTTP header specified by `headers` in the order they appear. + +1. If the header name is not `request-line` then append the lowercased header + name followed with an ASCII colon `:` and an ASCII space ` `. +2. If the header name is `request-line` then append the HTTP request line, + otherwise append the header value. +3. If value is not the last value then append an ASCII newline `\n`. The string + MUST NOT include a trailing ASCII newline. + +# Example Requests + +All requests refer to the following request (body omitted): + + POST /foo HTTP/1.1 + Host: example.org + Date: Tue, 07 Jun 2014 20:51:35 GMT + Content-Type: application/json + Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= + Content-Length: 18 + +The "rsa-key-1" keyId refers to a private key known to the client and a public +key known to the server. The "hmac-key-1" keyId refers to key known to the +client and server. + +## Default parameterization + +The authorization header and signature would be generated as: + + Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256",signature="Base64(RSA-SHA256(signing string))" + +The client would compose the signing string as: + + date: Tue, 07 Jun 2014 20:51:35 GMT + +## Header List + +The authorization header and signature would be generated as: + + Authorization: Signature keyId="rsa-key-1",algorithm="rsa-sha256",headers="(request-target) date content-type digest",signature="Base64(RSA-SHA256(signing string))" + +The client would compose the signing string as (`+ "\n"` inserted for +readability): + + (request-target) post /foo + "\n" + date: Tue, 07 Jun 2011 20:51:35 GMT + "\n" + content-type: application/json + "\n" + digest: SHA-256=Base64(SHA256(Body)) + +## Algorithm + +The authorization header and signature would be generated as: + + Authorization: Signature keyId="hmac-key-1",algorithm="hmac-sha1",signature="Base64(HMAC-SHA1(signing string))" + +The client would compose the signing string as: + + date: Tue, 07 Jun 2011 20:51:35 GMT + +# Signing Algorithms + +Currently supported algorithm names are: + +* rsa-sha1 +* rsa-sha256 +* rsa-sha512 +* dsa-sha1 +* hmac-sha1 +* hmac-sha256 +* hmac-sha512 + +# Security Considerations + +## Default Parameters + +Note the default parameterization of the `Signature` scheme is only safe if all +requests are carried over a secure transport (i.e., TLS). Sending the default +scheme over a non-secure transport will leave the request vulnerable to +spoofing, tampering, replay/repudiation, and integrity violations (if using the +STRIDE threat-modeling methodology). + +## Insecure Transports + +If sending the request over plain HTTP, service providers SHOULD require clients +to sign ALL HTTP headers, and the `request-line`. Additionally, service +providers SHOULD require `Content-MD5` calculations to be performed to ensure +against any tampering from clients. + +## Nonces + +Nonces are out of scope for this document simply because many service providers +fail to implement them correctly, or do not adopt security specifications +because of the infrastructure complexity. Given the `header` parameterization, +a service provider is fully enabled to add nonce semantics into this scheme by +using something like an `x-request-nonce` header, and ensuring it is signed +with the `Date` header. + +## Clock Skew + +As the default scheme is to sign the `Date` header, service providers SHOULD +protect against logged replay attacks by enforcing a clock skew. The server +SHOULD be synchronized with NTP, and the recommendation in this specification +is to allow 300s of clock skew (in either direction). + +## Required Headers to Sign + +It is out of scope for this document to dictate what headers a service provider +will want to enforce, but service providers SHOULD at minimum include the +`Date` header. + +# References + +## Normative References + +* [RFC2616] Hypertext Transfer Protocol -- HTTP/1.1 +* [RFC2617] HTTP Authentication: Basic and Digest Access Authentication +* [RFC5246] The Transport Layer Security (TLS) Protocol Version 1.2 + +## Informative References + + Name: Mark Cavage (editor) + Company: Joyent, Inc. + Email: mark.cavage@joyent.com + URI: http://www.joyent.com + +# Appendix A - Test Values + +The following test data uses the RSA (1024b) keys, which we will refer +to as `keyId=Test` in the following samples: + + -----BEGIN PUBLIC KEY----- + MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCFENGw33yGihy92pDjZQhl0C3 + 6rPJj+CvfSC8+q28hxA161QFNUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6 + Z4UMR7EOcpfdUE9Hf3m/hs+FUR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJw + oYi+1hqp1fIekaxsyQIDAQAB + -----END PUBLIC KEY----- + + -----BEGIN RSA PRIVATE KEY----- + MIICXgIBAAKBgQDCFENGw33yGihy92pDjZQhl0C36rPJj+CvfSC8+q28hxA161QF + NUd13wuCTUcq0Qd2qsBe/2hFyc2DCJJg0h1L78+6Z4UMR7EOcpfdUE9Hf3m/hs+F + UR45uBJeDK1HSFHD8bHKD6kv8FPGfJTotc+2xjJwoYi+1hqp1fIekaxsyQIDAQAB + AoGBAJR8ZkCUvx5kzv+utdl7T5MnordT1TvoXXJGXK7ZZ+UuvMNUCdN2QPc4sBiA + QWvLw1cSKt5DsKZ8UETpYPy8pPYnnDEz2dDYiaew9+xEpubyeW2oH4Zx71wqBtOK + kqwrXa/pzdpiucRRjk6vE6YY7EBBs/g7uanVpGibOVAEsqH1AkEA7DkjVH28WDUg + f1nqvfn2Kj6CT7nIcE3jGJsZZ7zlZmBmHFDONMLUrXR/Zm3pR5m0tCmBqa5RK95u + 412jt1dPIwJBANJT3v8pnkth48bQo/fKel6uEYyboRtA5/uHuHkZ6FQF7OUkGogc + mSJluOdc5t6hI1VsLn0QZEjQZMEOWr+wKSMCQQCC4kXJEsHAve77oP6HtG/IiEn7 + kpyUXRNvFsDE0czpJJBvL/aRFUJxuRK91jhjC68sA7NsKMGg5OXb5I5Jj36xAkEA + gIT7aFOYBFwGgQAQkWNKLvySgKbAZRTeLBacpHMuQdl1DfdntvAyqpAZ0lY0RKmW + G6aFKaqQfOXKCyWoUiVknQJAXrlgySFci/2ueKlIE1QqIiLSZ8V8OlpFLRnb1pzI + 7U1yQXnTAEFYM560yJlzUpOb1V4cScGd365tiSMvxLOvTA== + -----END RSA PRIVATE KEY----- + +And all examples use this request: + +<!-- httpreq --> + + POST /foo?param=value&pet=dog HTTP/1.1 + Host: example.com + Date: Thu, 05 Jan 2014 21:31:40 GMT + Content-Type: application/json + Digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= + Content-Length: 18 + + {"hello": "world"} + +<!-- /httpreq --> + +### Default + +The string to sign would be: + +<!-- sign {"name": "Default", "options": {"keyId":"Test", "algorithm": "rsa-sha256"}} --> +<!-- signstring --> + + date: Thu, 05 Jan 2014 21:31:40 GMT + +<!-- /signstring --> + +The Authorization header would be: + +<!-- authz --> + + Authorization: Signature keyId="Test",algorithm="rsa-sha256",headers="date",signature="jKyvPcxB4JbmYY4mByyBY7cZfNl4OW9HpFQlG7N4YcJPteKTu4MWCLyk+gIr0wDgqtLWf9NLpMAMimdfsH7FSWGfbMFSrsVTHNTk0rK3usrfFnti1dxsM4jl0kYJCKTGI/UWkqiaxwNiKqGcdlEDrTcUhhsFsOIo8VhddmZTZ8w=" + +<!-- /authz --> + +### All Headers + +Parameterized to include all headers, the string to sign would be (`+ "\n"` +inserted for readability): + +<!-- sign {"name": "All Headers", "options": {"keyId":"Test", "algorithm": "rsa-sha256", "headers": ["(request-target)", "host", "date", "content-type", "digest", "content-length"]}} --> +<!-- signstring --> + + (request-target): post /foo?param=value&pet=dog + host: example.com + date: Thu, 05 Jan 2014 21:31:40 GMT + content-type: application/json + digest: SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= + content-length: 18 + +<!-- /signstring --> + +The Authorization header would be: + +<!-- authz --> + + 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=" + +<!-- /authz --> + +## Generating and verifying signatures using `openssl` + +The `openssl` commandline tool can be used to generate or verify the signatures listed above. + +Compose the signing string as usual, and pipe it into the the `openssl dgst` command, then into `openssl enc -base64`, as follows: + + $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \ + openssl dgst -binary -sign /path/to/private.pem -sha256 | \ + openssl enc -base64 + jKyvPcxB4JbmYY4mByyBY7cZfNl4OW9Hp... + $ + +The `-sha256` option is necessary to produce an `rsa-sha256` signature. You can select other hash algorithms such as `sha1` by changing this argument. + +To verify a signature, first save the signature data, Base64-decoded, into a file, then use `openssl dgst` again with the `-verify` option: + + $ echo 'jKyvPcxB4JbmYY4mByy...' | openssl enc -A -d -base64 > signature + $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \ + openssl dgst -sha256 -verify /path/to/public.pem -signature ./signature + Verified OK + $ + +## Generating and verifying signatures using `sshpk-sign` + +You can also generate and check signatures using the `sshpk-sign` tool which is +included with the `sshpk` package in `npm`. + +Compose the signing string as above, and pipe it into `sshpk-sign` as follows: + + $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \ + sshpk-sign -i /path/to/private.pem + jKyvPcxB4JbmYY4mByyBY7cZfNl4OW9Hp... + $ + +This will produce an `rsa-sha256` signature by default, as you can see using +the `-v` option: + + sshpk-sign: using rsa-sha256 with a 1024 bit key + +You can also use `sshpk-verify` in a similar manner: + + $ printf 'date: Thu, 05 Jan 2014 21:31:40 GMT' | \ + sshpk-verify -i ./public.pem -s 'jKyvPcxB4JbmYY...' + OK + $ |