diff options
Diffstat (limited to 'deps/npm/node_modules/hawk/README.md')
| -rwxr-xr-x | deps/npm/node_modules/hawk/README.md | 99 |
1 files changed, 48 insertions, 51 deletions
diff --git a/deps/npm/node_modules/hawk/README.md b/deps/npm/node_modules/hawk/README.md index fc5dd6deb1..63725034fc 100755 --- a/deps/npm/node_modules/hawk/README.md +++ b/deps/npm/node_modules/hawk/README.md @@ -3,11 +3,11 @@ <img align="right" src="https://raw.github.com/hueniverse/hawk/master/images/logo.png" /> **Hawk** is an HTTP authentication scheme using a message authentication code (MAC) algorithm to provide partial HTTP request cryptographic verification. For more complex use cases such as access delegation, see [Oz](https://github.com/hueniverse/oz). -Current version: **6.x** +Current version: **3.x** -Note: 6.x, 5.x, 4.x, 3.x, and 2.x are the same exact protocol as 1.1. The version increments reflect changes in the node API. +Note: 3.x and 2.x are the same exact protocol as 1.1. The version increments reflect changes in the node API. -[](https://travis-ci.org/hueniverse/hawk) +[](http://travis-ci.org/hueniverse/hawk) # Table of Content @@ -18,8 +18,10 @@ Note: 6.x, 5.x, 4.x, 3.x, and 2.x are the same exact protocol as 1.1. The versio - [Payload Validation](#payload-validation) - [Response Payload Validation](#response-payload-validation) - [Browser Support and Considerations](#browser-support-and-considerations) +<p></p> - [**Single URI Authorization**](#single-uri-authorization) - [Usage Example](#bewit-usage-example) +<p></p> - [**Security Considerations**](#security-considerations) - [MAC Keys Transmission](#mac-keys-transmission) - [Confidentiality of Requests](#confidentiality-of-requests) @@ -31,7 +33,9 @@ Note: 6.x, 5.x, 4.x, 3.x, and 2.x are the same exact protocol as 1.1. The versio - [Client Clock Poisoning](#client-clock-poisoning) - [Bewit Limitations](#bewit-limitations) - [Host Header Forgery](#host-header-forgery) +<p></p> - [**Frequently Asked Questions**](#frequently-asked-questions) +<p></p> - [**Implementations**](#implementations) - [**Acknowledgements**](#acknowledgements) @@ -78,7 +82,7 @@ making requests. This gives the server enough information to prevent replay atta The nonce is generated by the client, and is a string unique across all requests with the same timestamp and key identifier combination. -The timestamp enables the server to restrict the validity period of the credentials where requests occurring afterwards +The timestamp enables the server to restrict the validity period of the credentials where requests occuring afterwards are rejected. It also removes the need for the server to retain an unbounded number of nonce values for future checks. By default, **Hawk** uses a time window of 1 minute to allow for time skew between the client and server (which in practice translates to a maximum of 2 minutes as the skew can be positive or negative). @@ -99,15 +103,15 @@ the number of round trips required to authenticate the first request. Server code: ```javascript -const Http = require('http'); -const Hawk = require('hawk'); +var Http = require('http'); +var Hawk = require('hawk'); // Credentials lookup function -const credentialsFunc = function (id, callback) { +var credentialsFunc = function (id, callback) { - const credentials = { + var credentials = { key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn', algorithm: 'sha256', user: 'Steve' @@ -118,20 +122,20 @@ const credentialsFunc = function (id, callback) { // Create HTTP server -const handler = function (req, res) { +var handler = function (req, res) { // Authenticate incoming request - Hawk.server.authenticate(req, credentialsFunc, {}, (err, credentials, artifacts) => { + Hawk.server.authenticate(req, credentialsFunc, {}, function (err, credentials, artifacts) { // Prepare response - const payload = (!err ? `Hello ${credentials.user} ${artifacts.ext}` : 'Shoosh!'); - const headers = { 'Content-Type': 'text/plain' }; + var payload = (!err ? 'Hello ' + credentials.user + ' ' + artifacts.ext : 'Shoosh!'); + var headers = { 'Content-Type': 'text/plain' }; // Generate Server-Authorization response header - const header = Hawk.server.header(credentials, artifacts, { payload, contentType: headers['Content-Type'] }); + var header = Hawk.server.header(credentials, artifacts, { payload: payload, contentType: headers['Content-Type'] }); headers['Server-Authorization'] = header; // Send the response back @@ -149,13 +153,13 @@ Http.createServer(handler).listen(8000, 'example.com'); Client code: ```javascript -const Request = require('request'); -const Hawk = require('hawk'); +var Request = require('request'); +var Hawk = require('hawk'); // Client credentials -const credentials = { +var credentials = { id: 'dh37fgj492je', key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn', algorithm: 'sha256' @@ -163,7 +167,7 @@ const credentials = { // Request options -const requestOptions = { +var requestOptions = { uri: 'http://example.com:8000/resource/1?b=1&a=2', method: 'GET', headers: {} @@ -171,7 +175,7 @@ const requestOptions = { // Generate Authorization request header -const header = Hawk.client.header('http://example.com:8000/resource/1?b=1&a=2', 'GET', { credentials: credentials, ext: 'some-app-data' }); +var header = Hawk.client.header('http://example.com:8000/resource/1?b=1&a=2', 'GET', { credentials: credentials, ext: 'some-app-data' }); requestOptions.headers.Authorization = header.field; // Send authenticated request @@ -180,16 +184,16 @@ Request(requestOptions, function (error, response, body) { // Authenticate the server's response - const isValid = Hawk.client.authenticate(response, credentials, header.artifacts, { payload: body }); + var isValid = Hawk.client.authenticate(response, credentials, header.artifacts, { payload: body }); // Output results - console.log(`${response.statusCode}: ${body}` + (isValid ? ' (valid)' : ' (invalid)')); + console.log(response.statusCode + ': ' + body + (isValid ? ' (valid)' : ' (invalid)')); }); ``` **Hawk** utilized the [**SNTP**](https://github.com/hueniverse/sntp) module for time sync management. By default, the local -machine time is used. To automatically retrieve and synchronize the clock within the application, use the SNTP 'start()' method. +machine time is used. To automatically retrieve and synchronice the clock within the application, use the SNTP 'start()' method. ```javascript Hawk.sntp.start(); @@ -213,13 +217,12 @@ HTTP/1.1 401 Unauthorized WWW-Authenticate: Hawk ``` -The client has previously obtained a set of **Hawk** credentials for accessing resources on the "`http://example.com/`" +The client has previously obtained a set of **Hawk** credentials for accessing resources on the "http://example.com/" server. The **Hawk** credentials issued to the client include the following attributes: -* Key identifier: `dh37fgj492je` -* Key: `werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn` -* Algorithm: `hmac sha256` -* Hash: `6R4rV5iE+NPoym+WwjeHzjAGXUtLNIxmo1vpMofpLAE=` +* Key identifier: dh37fgj492je +* Key: werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn +* Algorithm: sha256 The client generates the authentication header by calculating a timestamp (e.g. the number of seconds since January 1, 1970 00:00:00 GMT), generating a nonce, and constructing the normalized request string (each value followed by a newline @@ -238,7 +241,7 @@ some-app-ext-data ``` -The request MAC is calculated using HMAC with the specified hash algorithm "`sha256`" and the key over the normalized request string. +The request MAC is calculated using HMAC with the specified hash algorithm "sha256" and the key over the normalized request string. The result is base64-encoded to produce the request MAC: ``` @@ -270,8 +273,7 @@ For example: * Payload: `Thank you for flying Hawk` * Content Type: `text/plain` -* Algorithm: `sha256` -* Hash: `Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=` +* Hash (sha256): `Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=` Results in the following input to the payload hash function (newline terminated values): @@ -312,7 +314,7 @@ Host: example.com:8000 Authorization: Hawk id="dh37fgj492je", ts="1353832234", nonce="j4h3g2", hash="Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=", ext="some-app-ext-data", mac="aSe1DERmZuRl3pI36/9BdZmnErTw3sNzOOAUlfeKjVw=" ``` -It is up to the server if and when it validates the payload for any given request, based solely on its security policy +It is up to the server if and when it validates the payload for any given request, based solely on it's security policy and the nature of the data included. If the payload is available at the time of authentication, the server uses the hash value provided by the client to construct @@ -334,7 +336,7 @@ by the client, the payload may be modified by an attacker. client to authenticate the response and ensure it is talking to the right server. **Hawk** defines the HTTP `Server-Authorization` header as a response header using the exact same syntax as the `Authorization` request header field. -The header is constructed using the same process as the client's request header. The server uses the same credentials and other +The header is contructed using the same process as the client's request header. The server uses the same credentials and other artifacts provided by the client to constructs the normalized request string. The `ext` and `hash` values are replaced with new values based on the server response. The rest as identical to those used by the client. @@ -379,15 +381,15 @@ the granted access timeframe. Server code: ```javascript -const Http = require('http'); -const Hawk = require('hawk'); +var Http = require('http'); +var Hawk = require('hawk'); // Credentials lookup function -const credentialsFunc = function (id, callback) { +var credentialsFunc = function (id, callback) { - const credentials = { + var credentials = { key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn', algorithm: 'sha256' }; @@ -397,9 +399,9 @@ const credentialsFunc = function (id, callback) { // Create HTTP server -const handler = function (req, res) { +var handler = function (req, res) { - Hawk.uri.authenticate(req, credentialsFunc, {}, (err, credentials, attributes) => { + Hawk.uri.authenticate(req, credentialsFunc, {}, function (err, credentials, attributes) { res.writeHead(!err ? 200 : 401, { 'Content-Type': 'text/plain' }); res.end(!err ? 'Access granted' : 'Shoosh!'); @@ -412,13 +414,13 @@ Http.createServer(handler).listen(8000, 'example.com'); Bewit code generation: ```javascript -const Request = require('request'); -const Hawk = require('hawk'); +var Request = require('request'); +var Hawk = require('hawk'); // Client credentials -const credentials = { +var credentials = { id: 'dh37fgj492je', key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn', algorithm: 'sha256' @@ -426,13 +428,9 @@ const credentials = { // Generate bewit -const duration = 60 * 5; // 5 Minutes -const bewit = Hawk.uri.getBewit('http://example.com:8000/resource/1?b=1&a=2', { credentials: credentials, ttlSec: duration, ext: 'some-app-data' }); -const uri = 'http://example.com:8000/resource/1?b=1&a=2' + '&bewit=' + bewit; - -// Output URI - -console.log('URI: ' + uri); +var duration = 60 * 5; // 5 Minutes +var bewit = Hawk.uri.getBewit('http://example.com:8080/resource/1?b=1&a=2', { credentials: credentials, ttlSec: duration, ext: 'some-app-data' }); +var uri = 'http://example.com:8000/resource/1?b=1&a=2' + '&bewit=' + bewit; ``` @@ -499,8 +497,8 @@ or value of such headers, an attacker can manipulate the request headers without `ext` feature to pass application-specific information via the `Authorization` header which is protected by the request MAC. The response authentication, when performed, only covers the response payload, content-type, and the request information -provided by the client in its request (method, resource, timestamp, nonce, etc.). It does not cover the HTTP status code or -any other response header field (e.g. `Location`) which can affect the client's behaviour. +provided by the client in it's request (method, resource, timestamp, nonce, etc.). It does not cover the HTTP status code or +any other response header field (e.g. Location) which can affect the client's behaviour. ### Future Time Manipulation @@ -533,7 +531,7 @@ and sensitive information. ### Host Header Forgery Hawk validates the incoming request MAC against the incoming HTTP Host header. However, unless the optional `host` and `port` -options are used with `server.authenticate()`, a malicious client can mint new host names pointing to the server's IP address and +options are used with `server.authenticate()`, a malicous client can mint new host names pointing to the server's IP address and use that to craft an attack by sending a valid request that's meant for another hostname than the one used by the server. Server implementors must manually verify that the host header received matches their expectation (or use the options mentioned above). @@ -625,7 +623,6 @@ of delegating access to a third party. If you are looking for an OAuth alternati - [Tent Hawk in Ruby](https://github.com/tent/hawk-ruby) - [Wealdtech in Java](https://github.com/wealdtech/hawk) - [Kumar's Mohawk in Python](https://github.com/kumar303/mohawk/) -- [Hiyosi in Go](https://github.com/hiyosi/hawk) # Acknowledgements |