+++ /dev/null
-![hawk Logo](https://raw.github.com/hueniverse/hawk/master/images/hawk.png)\r
-\r
-<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\r
-HTTP request cryptographic verification. For more complex use cases such as access delegation, see [Oz](https://github.com/hueniverse/oz).\r
-\r
-Current version: **3.x**\r
-\r
-Note: 3.x and 2.x are the same exact protocol as 1.1. The version increments reflect changes in the node API.\r
-\r
-[![Build Status](https://secure.travis-ci.org/hueniverse/hawk.png)](http://travis-ci.org/hueniverse/hawk)\r
-\r
-# Table of Content\r
-\r
-- [**Introduction**](#introduction)\r
- - [Replay Protection](#replay-protection)\r
- - [Usage Example](#usage-example)\r
- - [Protocol Example](#protocol-example)\r
- - [Payload Validation](#payload-validation)\r
- - [Response Payload Validation](#response-payload-validation)\r
- - [Browser Support and Considerations](#browser-support-and-considerations)\r
-<p></p>\r
-- [**Single URI Authorization**](#single-uri-authorization)\r
- - [Usage Example](#bewit-usage-example)\r
-<p></p>\r
-- [**Security Considerations**](#security-considerations)\r
- - [MAC Keys Transmission](#mac-keys-transmission)\r
- - [Confidentiality of Requests](#confidentiality-of-requests)\r
- - [Spoofing by Counterfeit Servers](#spoofing-by-counterfeit-servers)\r
- - [Plaintext Storage of Credentials](#plaintext-storage-of-credentials)\r
- - [Entropy of Keys](#entropy-of-keys)\r
- - [Coverage Limitations](#coverage-limitations)\r
- - [Future Time Manipulation](#future-time-manipulation)\r
- - [Client Clock Poisoning](#client-clock-poisoning)\r
- - [Bewit Limitations](#bewit-limitations)\r
- - [Host Header Forgery](#host-header-forgery)\r
-<p></p>\r
-- [**Frequently Asked Questions**](#frequently-asked-questions)\r
-<p></p>\r
-- [**Implementations**](#implementations)\r
-- [**Acknowledgements**](#acknowledgements)\r
-\r
-# Introduction\r
-\r
-**Hawk** is an HTTP authentication scheme providing mechanisms for making authenticated HTTP requests with\r
-partial cryptographic verification of the request and response, covering the HTTP method, request URI, host,\r
-and optionally the request payload.\r
-\r
-Similar to the HTTP [Digest access authentication schemes](http://www.ietf.org/rfc/rfc2617.txt), **Hawk** uses a set of\r
-client credentials which include an identifier (e.g. username) and key (e.g. password). Likewise, just as with the Digest scheme,\r
-the key is never included in authenticated requests. Instead, it is used to calculate a request MAC value which is\r
-included in its place.\r
-\r
-However, **Hawk** has several differences from Digest. In particular, while both use a nonce to limit the possibility of\r
-replay attacks, in **Hawk** the client generates the nonce and uses it in combination with a timestamp, leading to less\r
-"chattiness" (interaction with the server).\r
-\r
-Also unlike Digest, this scheme is not intended to protect the key itself (the password in Digest) because\r
-the client and server must both have access to the key material in the clear.\r
-\r
-The primary design goals of this scheme are to:\r
-* simplify and improve HTTP authentication for services that are unwilling or unable to deploy TLS for all resources,\r
-* secure credentials against leakage (e.g., when the client uses some form of dynamic configuration to determine where\r
- to send an authenticated request), and\r
-* avoid the exposure of credentials sent to a malicious server over an unauthenticated secure channel due to client\r
- failure to validate the server's identity as part of its TLS handshake.\r
-\r
-In addition, **Hawk** supports a method for granting third-parties temporary access to individual resources using\r
-a query parameter called _bewit_ (in falconry, a leather strap used to attach a tracking device to the leg of a hawk).\r
-\r
-The **Hawk** scheme requires the establishment of a shared symmetric key between the client and the server,\r
-which is beyond the scope of this module. Typically, the shared credentials are established via an initial\r
-TLS-protected phase or derived from some other shared confidential information available to both the client\r
-and the server.\r
-\r
-\r
-## Replay Protection\r
-\r
-Without replay protection, an attacker can use a compromised (but otherwise valid and authenticated) request more \r
-than once, gaining access to a protected resource. To mitigate this, clients include both a nonce and a timestamp when \r
-making requests. This gives the server enough information to prevent replay attacks.\r
-\r
-The nonce is generated by the client, and is a string unique across all requests with the same timestamp and\r
-key identifier combination. \r
-\r
-The timestamp enables the server to restrict the validity period of the credentials where requests occuring afterwards\r
-are rejected. It also removes the need for the server to retain an unbounded number of nonce values for future checks.\r
-By default, **Hawk** uses a time window of 1 minute to allow for time skew between the client and server (which in\r
-practice translates to a maximum of 2 minutes as the skew can be positive or negative).\r
-\r
-Using a timestamp requires the client's clock to be in sync with the server's clock. **Hawk** requires both the client\r
-clock and the server clock to use NTP to ensure synchronization. However, given the limitations of some client types\r
-(e.g. browsers) to deploy NTP, the server provides the client with its current time (in seconds precision) in response\r
-to a bad timestamp.\r
-\r
-There is no expectation that the client will adjust its system clock to match the server (in fact, this would be a\r
-potential attack vector). Instead, the client only uses the server's time to calculate an offset used only\r
-for communications with that particular server. The protocol rewards clients with synchronized clocks by reducing\r
-the number of round trips required to authenticate the first request.\r
-\r
-\r
-## Usage Example\r
-\r
-Server code:\r
-\r
-```javascript\r
-var Http = require('http');\r
-var Hawk = require('hawk');\r
-\r
-\r
-// Credentials lookup function\r
-\r
-var credentialsFunc = function (id, callback) {\r
-\r
- var credentials = {\r
- key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn',\r
- algorithm: 'sha256',\r
- user: 'Steve'\r
- };\r
-\r
- return callback(null, credentials);\r
-};\r
-\r
-// Create HTTP server\r
-\r
-var handler = function (req, res) {\r
-\r
- // Authenticate incoming request\r
-\r
- Hawk.server.authenticate(req, credentialsFunc, {}, function (err, credentials, artifacts) {\r
-\r
- // Prepare response\r
-\r
- var payload = (!err ? 'Hello ' + credentials.user + ' ' + artifacts.ext : 'Shoosh!');\r
- var headers = { 'Content-Type': 'text/plain' };\r
-\r
- // Generate Server-Authorization response header\r
-\r
- var header = Hawk.server.header(credentials, artifacts, { payload: payload, contentType: headers['Content-Type'] });\r
- headers['Server-Authorization'] = header;\r
-\r
- // Send the response back\r
-\r
- res.writeHead(!err ? 200 : 401, headers);\r
- res.end(payload);\r
- });\r
-};\r
-\r
-// Start server\r
-\r
-Http.createServer(handler).listen(8000, 'example.com');\r
-```\r
-\r
-Client code:\r
-\r
-```javascript\r
-var Request = require('request');\r
-var Hawk = require('hawk');\r
-\r
-\r
-// Client credentials\r
-\r
-var credentials = {\r
- id: 'dh37fgj492je',\r
- key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn',\r
- algorithm: 'sha256'\r
-}\r
-\r
-// Request options\r
-\r
-var requestOptions = {\r
- uri: 'http://example.com:8000/resource/1?b=1&a=2',\r
- method: 'GET',\r
- headers: {}\r
-};\r
-\r
-// Generate Authorization request header\r
-\r
-var header = Hawk.client.header('http://example.com:8000/resource/1?b=1&a=2', 'GET', { credentials: credentials, ext: 'some-app-data' });\r
-requestOptions.headers.Authorization = header.field;\r
-\r
-// Send authenticated request\r
-\r
-Request(requestOptions, function (error, response, body) {\r
-\r
- // Authenticate the server's response\r
-\r
- var isValid = Hawk.client.authenticate(response, credentials, header.artifacts, { payload: body });\r
-\r
- // Output results\r
-\r
- console.log(response.statusCode + ': ' + body + (isValid ? ' (valid)' : ' (invalid)'));\r
-});\r
-```\r
-\r
-**Hawk** utilized the [**SNTP**](https://github.com/hueniverse/sntp) module for time sync management. By default, the local\r
-machine time is used. To automatically retrieve and synchronice the clock within the application, use the SNTP 'start()' method.\r
-\r
-```javascript\r
-Hawk.sntp.start();\r
-```\r
-\r
-\r
-## Protocol Example\r
-\r
-The client attempts to access a protected resource without authentication, sending the following HTTP request to\r
-the resource server:\r
-\r
-```\r
-GET /resource/1?b=1&a=2 HTTP/1.1\r
-Host: example.com:8000\r
-```\r
-\r
-The resource server returns an authentication challenge.\r
-\r
-```\r
-HTTP/1.1 401 Unauthorized\r
-WWW-Authenticate: Hawk\r
-```\r
-\r
-The client has previously obtained a set of **Hawk** credentials for accessing resources on the "http://example.com/"\r
-server. The **Hawk** credentials issued to the client include the following attributes:\r
-\r
-* Key identifier: dh37fgj492je\r
-* Key: werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn\r
-* Algorithm: sha256\r
-\r
-The client generates the authentication header by calculating a timestamp (e.g. the number of seconds since January 1,\r
-1970 00:00:00 GMT), generating a nonce, and constructing the normalized request string (each value followed by a newline\r
-character):\r
-\r
-```\r
-hawk.1.header\r
-1353832234\r
-j4h3g2\r
-GET\r
-/resource/1?b=1&a=2\r
-example.com\r
-8000\r
-\r
-some-app-ext-data\r
-\r
-```\r
-\r
-The request MAC is calculated using HMAC with the specified hash algorithm "sha256" and the key over the normalized request string.\r
-The result is base64-encoded to produce the request MAC:\r
-\r
-```\r
-6R4rV5iE+NPoym+WwjeHzjAGXUtLNIxmo1vpMofpLAE=\r
-```\r
-\r
-The client includes the **Hawk** key identifier, timestamp, nonce, application specific data, and request MAC with the request using\r
-the HTTP `Authorization` request header field:\r
-\r
-```\r
-GET /resource/1?b=1&a=2 HTTP/1.1\r
-Host: example.com:8000\r
-Authorization: Hawk id="dh37fgj492je", ts="1353832234", nonce="j4h3g2", ext="some-app-ext-data", mac="6R4rV5iE+NPoym+WwjeHzjAGXUtLNIxmo1vpMofpLAE="\r
-```\r
-\r
-The server validates the request by calculating the request MAC again based on the request received and verifies the validity\r
-and scope of the **Hawk** credentials. If valid, the server responds with the requested resource.\r
-\r
-\r
-### Payload Validation\r
-\r
-**Hawk** provides optional payload validation. When generating the authentication header, the client calculates a payload hash\r
-using the specified hash algorithm. The hash is calculated over the concatenated value of (each followed by a newline character):\r
-* `hawk.1.payload`\r
-* the content-type in lowercase, without any parameters (e.g. `application/json`)\r
-* the request payload prior to any content encoding (the exact representation requirements should be specified by the server for payloads other than simple single-part ascii to ensure interoperability)\r
-\r
-For example:\r
-\r
-* Payload: `Thank you for flying Hawk`\r
-* Content Type: `text/plain`\r
-* Hash (sha256): `Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=`\r
-\r
-Results in the following input to the payload hash function (newline terminated values):\r
-\r
-```\r
-hawk.1.payload\r
-text/plain\r
-Thank you for flying Hawk\r
-\r
-```\r
-\r
-Which produces the following hash value:\r
-\r
-```\r
-Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=\r
-```\r
-\r
-The client constructs the normalized request string (newline terminated values):\r
-\r
-```\r
-hawk.1.header\r
-1353832234\r
-j4h3g2\r
-POST\r
-/resource/1?a=1&b=2\r
-example.com\r
-8000\r
-Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=\r
-some-app-ext-data\r
-\r
-```\r
-\r
-Then calculates the request MAC and includes the **Hawk** key identifier, timestamp, nonce, payload hash, application specific data,\r
-and request MAC, with the request using the HTTP `Authorization` request header field:\r
-\r
-```\r
-POST /resource/1?a=1&b=2 HTTP/1.1\r
-Host: example.com:8000\r
-Authorization: Hawk id="dh37fgj492je", ts="1353832234", nonce="j4h3g2", hash="Yi9LfIIFRtBEPt74PVmbTF/xVAwPn7ub15ePICfgnuY=", ext="some-app-ext-data", mac="aSe1DERmZuRl3pI36/9BdZmnErTw3sNzOOAUlfeKjVw="\r
-```\r
-\r
-It is up to the server if and when it validates the payload for any given request, based solely on it's security policy\r
-and the nature of the data included.\r
-\r
-If the payload is available at the time of authentication, the server uses the hash value provided by the client to construct\r
-the normalized string and validates the MAC. If the MAC is valid, the server calculates the payload hash and compares the value\r
-with the provided payload hash in the header. In many cases, checking the MAC first is faster than calculating the payload hash.\r
-\r
-However, if the payload is not available at authentication time (e.g. too large to fit in memory, streamed elsewhere, or processed\r
-at a different stage in the application), the server may choose to defer payload validation for later by retaining the hash value\r
-provided by the client after validating the MAC.\r
-\r
-It is important to note that MAC validation does not mean the hash value provided by the client is valid, only that the value\r
-included in the header was not modified. Without calculating the payload hash on the server and comparing it to the value provided\r
-by the client, the payload may be modified by an attacker.\r
-\r
-\r
-## Response Payload Validation\r
-\r
-**Hawk** provides partial response payload validation. The server includes the `Server-Authorization` response header which enables the\r
-client to authenticate the response and ensure it is talking to the right server. **Hawk** defines the HTTP `Server-Authorization` header\r
-as a response header using the exact same syntax as the `Authorization` request header field.\r
-\r
-The header is contructed using the same process as the client's request header. The server uses the same credentials and other\r
-artifacts provided by the client to constructs the normalized request string. The `ext` and `hash` values are replaced with\r
-new values based on the server response. The rest as identical to those used by the client.\r
-\r
-The result MAC digest is included with the optional `hash` and `ext` values:\r
-\r
-```\r
-Server-Authorization: Hawk mac="XIJRsMl/4oL+nn+vKoeVZPdCHXB4yJkNnBbTbHFZUYE=", hash="f9cDF/TDm7TkYRLnGwRMfeDzT6LixQVLvrIKhh0vgmM=", ext="response-specific"\r
-```\r
-\r
-\r
-## Browser Support and Considerations\r
-\r
-A browser script is provided for including using a `<script>` tag in [lib/browser.js](/lib/browser.js). It's also a [component](http://component.io/hueniverse/hawk).\r
-\r
-**Hawk** relies on the _Server-Authorization_ and _WWW-Authenticate_ headers in its response to communicate with the client.\r
-Therefore, in case of CORS requests, it is important to consider sending _Access-Control-Expose-Headers_ with the value\r
-_"WWW-Authenticate, Server-Authorization"_ on each response from your server. As explained in the\r
-[specifications](http://www.w3.org/TR/cors/#access-control-expose-headers-response-header), it will indicate that these headers\r
-can safely be accessed by the client (using getResponseHeader() on the XmlHttpRequest object). Otherwise you will be met with a\r
-["simple response header"](http://www.w3.org/TR/cors/#simple-response-header) which excludes these fields and would prevent the\r
-Hawk client from authenticating the requests.You can read more about the why and how in this\r
-[article](http://www.html5rocks.com/en/tutorials/cors/#toc-adding-cors-support-to-the-server)\r
-\r
-\r
-# Single URI Authorization\r
-\r
-There are cases in which limited and short-term access to a protected resource is granted to a third party which does not\r
-have access to the shared credentials. For example, displaying a protected image on a web page accessed by anyone. **Hawk**\r
-provides limited support for such URIs in the form of a _bewit_ - a URI query parameter appended to the request URI which contains\r
-the necessary credentials to authenticate the request.\r
-\r
-Because of the significant security risks involved in issuing such access, bewit usage is purposely limited only to GET requests\r
-and for a finite period of time. Both the client and server can issue bewit credentials, however, the server should not use the same\r
-credentials as the client to maintain clear traceability as to who issued which credentials.\r
-\r
-In order to simplify implementation, bewit credentials do not support single-use policy and can be replayed multiple times within\r
-the granted access timeframe. \r
-\r
-\r
-## Bewit Usage Example\r
-\r
-Server code:\r
-\r
-```javascript\r
-var Http = require('http');\r
-var Hawk = require('hawk');\r
-\r
-\r
-// Credentials lookup function\r
-\r
-var credentialsFunc = function (id, callback) {\r
-\r
- var credentials = {\r
- key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn',\r
- algorithm: 'sha256'\r
- };\r
-\r
- return callback(null, credentials);\r
-};\r
-\r
-// Create HTTP server\r
-\r
-var handler = function (req, res) {\r
-\r
- Hawk.uri.authenticate(req, credentialsFunc, {}, function (err, credentials, attributes) {\r
-\r
- res.writeHead(!err ? 200 : 401, { 'Content-Type': 'text/plain' });\r
- res.end(!err ? 'Access granted' : 'Shoosh!');\r
- });\r
-};\r
-\r
-Http.createServer(handler).listen(8000, 'example.com');\r
-```\r
-\r
-Bewit code generation:\r
-\r
-```javascript\r
-var Request = require('request');\r
-var Hawk = require('hawk');\r
-\r
-\r
-// Client credentials\r
-\r
-var credentials = {\r
- id: 'dh37fgj492je',\r
- key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn',\r
- algorithm: 'sha256'\r
-}\r
-\r
-// Generate bewit\r
-\r
-var duration = 60 * 5; // 5 Minutes\r
-var bewit = Hawk.uri.getBewit('http://example.com:8080/resource/1?b=1&a=2', { credentials: credentials, ttlSec: duration, ext: 'some-app-data' });\r
-var uri = 'http://example.com:8000/resource/1?b=1&a=2' + '&bewit=' + bewit;\r
-```\r
-\r
-\r
-# Security Considerations\r
-\r
-The greatest sources of security risks are usually found not in **Hawk** but in the policies and procedures surrounding its use.\r
-Implementers are strongly encouraged to assess how this module addresses their security requirements. This section includes\r
-an incomplete list of security considerations that must be reviewed and understood before deploying **Hawk** on the server.\r
-Many of the protections provided in **Hawk** depends on whether and how they are used.\r
-\r
-### MAC Keys Transmission\r
-\r
-**Hawk** does not provide any mechanism for obtaining or transmitting the set of shared credentials required. Any mechanism used\r
-to obtain **Hawk** credentials must ensure that these transmissions are protected using transport-layer mechanisms such as TLS.\r
-\r
-### Confidentiality of Requests\r
-\r
-While **Hawk** provides a mechanism for verifying the integrity of HTTP requests, it provides no guarantee of request\r
-confidentiality. Unless other precautions are taken, eavesdroppers will have full access to the request content. Servers should\r
-carefully consider the types of data likely to be sent as part of such requests, and employ transport-layer security mechanisms\r
-to protect sensitive resources.\r
-\r
-### Spoofing by Counterfeit Servers\r
-\r
-**Hawk** provides limited verification of the server authenticity. When receiving a response back from the server, the server\r
-may choose to include a response `Server-Authorization` header which the client can use to verify the response. However, it is up to\r
-the server to determine when such measure is included, to up to the client to enforce that policy.\r
-\r
-A hostile party could take advantage of this by intercepting the client's requests and returning misleading or otherwise\r
-incorrect responses. Service providers should consider such attacks when developing services using this protocol, and should\r
-require transport-layer security for any requests where the authenticity of the resource server or of server responses is an issue.\r
-\r
-### Plaintext Storage of Credentials\r
-\r
-The **Hawk** key functions the same way passwords do in traditional authentication systems. In order to compute the request MAC,\r
-the server must have access to the key in plaintext form. This is in contrast, for example, to modern operating systems, which\r
-store only a one-way hash of user credentials.\r
-\r
-If an attacker were to gain access to these keys - or worse, to the server's database of all such keys - he or she would be able\r
-to perform any action on behalf of any resource owner. Accordingly, it is critical that servers protect these keys from unauthorized\r
-access.\r
-\r
-### Entropy of Keys\r
-\r
-Unless a transport-layer security protocol is used, eavesdroppers will have full access to authenticated requests and request\r
-MAC values, and will thus be able to mount offline brute-force attacks to recover the key used. Servers should be careful to\r
-assign keys which are long enough, and random enough, to resist such attacks for at least the length of time that the **Hawk**\r
-credentials are valid.\r
-\r
-For example, if the credentials are valid for two weeks, servers should ensure that it is not possible to mount a brute force\r
-attack that recovers the key in less than two weeks. Of course, servers are urged to err on the side of caution, and use the\r
-longest key reasonable.\r
-\r
-It is equally important that the pseudo-random number generator (PRNG) used to generate these keys be of sufficiently high\r
-quality. Many PRNG implementations generate number sequences that may appear to be random, but which nevertheless exhibit\r
-patterns or other weaknesses which make cryptanalysis or brute force attacks easier. Implementers should be careful to use\r
-cryptographically secure PRNGs to avoid these problems.\r
-\r
-### Coverage Limitations\r
-\r
-The request MAC only covers the HTTP `Host` header and optionally the `Content-Type` header. It does not cover any other headers\r
-which can often affect how the request body is interpreted by the server. If the server behavior is influenced by the presence\r
-or value of such headers, an attacker can manipulate the request headers without being detected. Implementers should use the\r
-`ext` feature to pass application-specific information via the `Authorization` header which is protected by the request MAC.\r
-\r
-The response authentication, when performed, only covers the response payload, content-type, and the request information \r
-provided by the client in it's request (method, resource, timestamp, nonce, etc.). It does not cover the HTTP status code or\r
-any other response header field (e.g. Location) which can affect the client's behaviour.\r
-\r
-### Future Time Manipulation\r
-\r
-The protocol relies on a clock sync between the client and server. To accomplish this, the server informs the client of its\r
-current time when an invalid timestamp is received.\r
-\r
-If an attacker is able to manipulate this information and cause the client to use an incorrect time, it would be able to cause\r
-the client to generate authenticated requests using time in the future. Such requests will fail when sent by the client, and will\r
-not likely leave a trace on the server (given the common implementation of nonce, if at all enforced). The attacker will then\r
-be able to replay the request at the correct time without detection.\r
-\r
-The client must only use the time information provided by the server if:\r
-* it was delivered over a TLS connection and the server identity has been verified, or\r
-* the `tsm` MAC digest calculated using the same client credentials over the timestamp has been verified.\r
-\r
-### Client Clock Poisoning\r
-\r
-When receiving a request with a bad timestamp, the server provides the client with its current time. The client must never use\r
-the time received from the server to adjust its own clock, and must only use it to calculate an offset for communicating with\r
-that particular server.\r
-\r
-### Bewit Limitations\r
-\r
-Special care must be taken when issuing bewit credentials to third parties. Bewit credentials are valid until expiration and cannot\r
-be revoked or limited without using other means. Whatever resource they grant access to will be completely exposed to anyone with\r
-access to the bewit credentials which act as bearer credentials for that particular resource. While bewit usage is limited to GET\r
-requests only and therefore cannot be used to perform transactions or change server state, it can still be used to expose private\r
-and sensitive information.\r
-\r
-### Host Header Forgery\r
-\r
-Hawk validates the incoming request MAC against the incoming HTTP Host header. However, unless the optional `host` and `port`\r
-options are used with `server.authenticate()`, a malicous client can mint new host names pointing to the server's IP address and\r
-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\r
-implementors must manually verify that the host header received matches their expectation (or use the options mentioned above).\r
-\r
-# Frequently Asked Questions\r
-\r
-### Where is the protocol specification?\r
-\r
-If you are looking for some prose explaining how all this works, **this is it**. **Hawk** is being developed as an open source\r
-project instead of a standard. In other words, the [code](/hueniverse/hawk/tree/master/lib) is the specification. Not sure about\r
-something? Open an issue!\r
-\r
-### Is it done?\r
-\r
-As of version 0.10.0, **Hawk** is feature-complete. However, until this module reaches version 1.0.0 it is considered experimental\r
-and is likely to change. This also means your feedback and contribution are very welcome. Feel free to open issues with questions\r
-and suggestions.\r
-\r
-### Where can I find **Hawk** implementations in other languages?\r
-\r
-**Hawk**'s only reference implementation is provided in JavaScript as a node.js module. However, it has been ported to other languages.\r
-The full list is maintained [here](https://github.com/hueniverse/hawk/issues?labels=port&state=closed). Please add an issue if you are\r
-working on another port. A cross-platform test-suite is in the works.\r
-\r
-### Why isn't the algorithm part of the challenge or dynamically negotiated?\r
-\r
-The algorithm used is closely related to the key issued as different algorithms require different key sizes (and other\r
-requirements). While some keys can be used for multiple algorithm, the protocol is designed to closely bind the key and algorithm\r
-together as part of the issued credentials.\r
-\r
-### Why is Host and Content-Type the only headers covered by the request MAC?\r
-\r
-It is really hard to include other headers. Headers can be changed by proxies and other intermediaries and there is no\r
-well-established way to normalize them. Many platforms change the case of header field names and values. The only\r
-straight-forward solution is to include the headers in some blob (say, base64 encoded JSON) and include that with the request,\r
-an approach taken by JWT and other such formats. However, that design violates the HTTP header boundaries, repeats information,\r
-and introduces other security issues because firewalls will not be aware of these "hidden" headers. In addition, any information\r
-repeated must be compared to the duplicated information in the header and therefore only moves the problem elsewhere.\r
-\r
-### Why not just use HTTP Digest?\r
-\r
-Digest requires pre-negotiation to establish a nonce. This means you can't just make a request - you must first send\r
-a protocol handshake to the server. This pattern has become unacceptable for most web services, especially mobile\r
-where extra round-trip are costly.\r
-\r
-### Why bother with all this nonce and timestamp business?\r
-\r
-**Hawk** is an attempt to find a reasonable, practical compromise between security and usability. OAuth 1.0 got timestamp\r
-and nonces halfway right but failed when it came to scalability and consistent developer experience. **Hawk** addresses\r
-it by requiring the client to sync its clock, but provides it with tools to accomplish it.\r
-\r
-In general, replay protection is a matter of application-specific threat model. It is less of an issue on a TLS-protected\r
-system where the clients are implemented using best practices and are under the control of the server. Instead of dropping\r
-replay protection, **Hawk** offers a required time window and an optional nonce verification. Together, it provides developers\r
-with the ability to decide how to enforce their security policy without impacting the client's implementation.\r
-\r
-### What are `app` and `dlg` in the authorization header and normalized mac string?\r
-\r
-The original motivation for **Hawk** was to replace the OAuth 1.0 use cases. This included both a simple client-server mode which\r
-this module is specifically designed for, and a delegated access mode which is being developed separately in\r
-[Oz](https://github.com/hueniverse/oz). In addition to the **Hawk** use cases, Oz requires another attribute: the application id `app`.\r
-This provides binding between the credentials and the application in a way that prevents an attacker from tricking an application\r
-to use credentials issued to someone else. It also has an optional 'delegated-by' attribute `dlg` which is the application id of the\r
-application the credentials were directly issued to. The goal of these two additions is to allow Oz to utilize **Hawk** directly,\r
-but with the additional security of delegated credentials.\r
-\r
-### What is the purpose of the static strings used in each normalized MAC input?\r
-\r
-When calculating a hash or MAC, a static prefix (tag) is added. The prefix is used to prevent MAC values from being\r
-used or reused for a purpose other than what they were created for (i.e. prevents switching MAC values between a request,\r
-response, and a bewit use cases). It also protects against exploits created after a potential change in how the protocol\r
-creates the normalized string. For example, if a future version would switch the order of nonce and timestamp, it\r
-can create an exploit opportunity for cases where the nonce is similar in format to a timestamp.\r
-\r
-### Does **Hawk** have anything to do with OAuth?\r
-\r
-Short answer: no.\r
-\r
-**Hawk** was originally proposed as the OAuth MAC Token specification. However, the OAuth working group in its consistent\r
-incompetence failed to produce a final, usable solution to address one of the most popular use cases of OAuth 1.0 - using it\r
-to authenticate simple client-server transactions (i.e. two-legged). As you can guess, the OAuth working group is still hard\r
-at work to produce more garbage.\r
-\r
-**Hawk** provides a simple HTTP authentication scheme for making client-server requests. It does not address the OAuth use case\r
-of delegating access to a third party. If you are looking for an OAuth alternative, check out [Oz](https://github.com/hueniverse/oz).\r
-\r
-# Implementations\r
-\r
-- [Logibit Hawk in F#/.Net](https://github.com/logibit/logibit.hawk/)\r
-- [Tent Hawk in Ruby](https://github.com/tent/hawk-ruby)\r
-- [Wealdtech in Java](https://github.com/wealdtech/hawk)\r
-- [Kumar's Mohawk in Python](https://github.com/kumar303/mohawk/)\r
-\r
-# Acknowledgements\r
-\r
-**Hawk** is a derivative work of the [HTTP MAC Authentication Scheme](http://tools.ietf.org/html/draft-hammer-oauth-v2-mac-token-05) proposal\r
-co-authored by Ben Adida, Adam Barth, and Eran Hammer, which in turn was based on the OAuth 1.0 community specification.\r
-\r
-Special thanks to Ben Laurie for his always insightful feedback and advice.\r
-\r
-The **Hawk** logo was created by [Chris Carrasco](http://chriscarrasco.com).\r