diff options
Diffstat (limited to 'node_modules/http-signature/http_signing.md')
| -rw-r--r-- | node_modules/http-signature/http_signing.md | 363 |
1 files changed, 0 insertions, 363 deletions
diff --git a/node_modules/http-signature/http_signing.md b/node_modules/http-signature/http_signing.md deleted file mode 100644 index 4f24d28..0000000 --- a/node_modules/http-signature/http_signing.md +++ /dev/null @@ -1,363 +0,0 @@ -# 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 - $ |