зеркало из https://github.com/mozilla/hawk.git
Security and FAQ sections
This commit is contained in:
Eran Hammer
Родитель
3873162f84
Коммит
b8017adcb8
204
README.md
204
README.md
|
|
@ -11,8 +11,12 @@ Current version: **0.0.x**
|
|||
# Table of Content
|
||||
|
||||
- [**Introduction**](#introduction)
|
||||
- [Protocol Example](#protocol-example)
|
||||
- [Usage Example](#usage-example)
|
||||
- [Protocol Example](#protocol-example)
|
||||
<p></p>
|
||||
- [**Security Considerations**](#security-considerations)
|
||||
<p></p>
|
||||
- [**Frequently Asked Questions**](#frequently-asked-questions)
|
||||
|
||||
|
||||
# Introduction
|
||||
|
|
@ -42,63 +46,6 @@ Digest, this mechanism is not intended to protect the key itself (user's passwor
|
|||
and server both have access to the key material in the clear.
|
||||
|
||||
|
||||
## Protocol Example
|
||||
|
||||
The client attempts to access a protected resource without authentication, sending the following HTTP request to
|
||||
the resource server:
|
||||
|
||||
```
|
||||
GET /resource/1?b=1&a=2 HTTP/1.1
|
||||
Host: 127.0.0.1:8000
|
||||
```
|
||||
|
||||
The resource server returns the following authentication challenge:
|
||||
|
||||
```
|
||||
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/"
|
||||
server. The **Hawk** credentials issued to the client include the following attributes:
|
||||
|
||||
* Key identifier: dh37fgj492je
|
||||
* Key: werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn
|
||||
* Algorithm: hmac-sha-256
|
||||
|
||||
The client generates the authentication header by calculating a timestamp (e.g. the number of seconds since January 1,
|
||||
1970 00:00:00 GMT) and constructs the normalized request string (newline separated values):
|
||||
|
||||
```
|
||||
1353832234
|
||||
dh37fgj492je
|
||||
GET
|
||||
/resource/1?b=1&a=2
|
||||
127.0.0.1
|
||||
8000
|
||||
some-app-data
|
||||
```
|
||||
|
||||
The request MAC is calculated using the specified algorithm "hmac-sha-256" and the key over the normalized request string.
|
||||
The result is base64-encoded to produce the request MAC:
|
||||
|
||||
```
|
||||
/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=
|
||||
```
|
||||
|
||||
The client includes the **Hawk** key identifier, timestamp, and request MAC with the request using the HTTP "Authorization"
|
||||
request header field:
|
||||
|
||||
```
|
||||
GET /resource/1?b=1&a=2 HTTP/1.1
|
||||
Host: 127.0.0.1:8000
|
||||
Authorization: Hawk id="dh37fgj492je", ts="1353832234", ext="some-app-data", mac="/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk="
|
||||
```
|
||||
|
||||
The server validates the request by calculating the request MAC again based on the request received and verifies the validity
|
||||
and scope of the **Hawk** credentials. If valid, the server responds with the requested resource.
|
||||
|
||||
|
||||
## Usage Example
|
||||
|
||||
Server code:
|
||||
|
|
@ -165,3 +112,144 @@ Request(options, function (error, response, body) {
|
|||
console.log(response.statusCode + ': ' + body);
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
## Protocol Example
|
||||
|
||||
The client attempts to access a protected resource without authentication, sending the following HTTP request to
|
||||
the resource server:
|
||||
|
||||
```
|
||||
GET /resource/1?b=1&a=2 HTTP/1.1
|
||||
Host: 127.0.0.1:8000
|
||||
```
|
||||
|
||||
The resource server returns the following authentication challenge:
|
||||
|
||||
```
|
||||
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/"
|
||||
server. The **Hawk** credentials issued to the client include the following attributes:
|
||||
|
||||
* Key identifier: dh37fgj492je
|
||||
* Key: werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn
|
||||
* Algorithm: hmac-sha-256
|
||||
|
||||
The client generates the authentication header by calculating a timestamp (e.g. the number of seconds since January 1,
|
||||
1970 00:00:00 GMT) and constructs the normalized request string (newline separated values):
|
||||
|
||||
```
|
||||
1353832234
|
||||
dh37fgj492je
|
||||
GET
|
||||
/resource/1?b=1&a=2
|
||||
127.0.0.1
|
||||
8000
|
||||
some-app-data
|
||||
```
|
||||
|
||||
The request MAC is calculated using the specified algorithm "hmac-sha-256" and the key over the normalized request string.
|
||||
The result is base64-encoded to produce the request MAC:
|
||||
|
||||
```
|
||||
/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk=
|
||||
```
|
||||
|
||||
The client includes the **Hawk** key identifier, timestamp, and request MAC with the request using the HTTP "Authorization"
|
||||
request header field:
|
||||
|
||||
```
|
||||
GET /resource/1?b=1&a=2 HTTP/1.1
|
||||
Host: 127.0.0.1:8000
|
||||
Authorization: Hawk id="dh37fgj492je", ts="1353832234", ext="some-app-data", mac="/uYWR6W5vTbY3WKUAN6fa+7p1t+1Yl6hFxKeMLfR6kk="
|
||||
```
|
||||
|
||||
The server validates the request by calculating the request MAC again based on the request received and verifies the validity
|
||||
and scope of the **Hawk** credentials. If valid, the server responds with the requested resource.
|
||||
|
||||
|
||||
# Security Considerations
|
||||
|
||||
The greatest sources of security risks are usually found not in **Hawk** but in the policies and procedures surrounding its use.
|
||||
Implementers are strongly encouraged to assess how this module addresses their security requirements. This section includes
|
||||
an incomplete list of security considerations that must be reviewed and understood before deploying **Hawk** on the server.
|
||||
|
||||
## MAC Keys Transmission
|
||||
|
||||
**Hawk** does not provide any mechanism for obtaining or transmitting the set of shared credentials required. Any mechanism used
|
||||
to obtain **Hawk** credentials must ensure that these transmissions are protected using transport-layer mechanisms such as TLS.
|
||||
|
||||
## Confidentiality of Requests
|
||||
|
||||
While **Hawk** provides a mechanism for verifying the integrity of HTTP requests, it provides no guarantee of request
|
||||
confidentiality. Unless other precautions are taken, eavesdroppers will have full access to the request content. Servers should
|
||||
carefully consider the types of data likely to be sent as part of such requests, and employ transport-layer security mechanisms
|
||||
to protect sensitive resources.
|
||||
|
||||
## Spoofing by Counterfeit Servers
|
||||
|
||||
**Hawk** makes no attempt to verify the authenticity of the server. A hostile party could take advantage of this by intercepting
|
||||
the client's requests and returning misleading or otherwise incorrect responses. Service providers should consider such attacks
|
||||
when developing services using this protocol, and should require transport-layer security for any requests where the authenticity
|
||||
of the resource server or of server responses is an issue.
|
||||
|
||||
## Plaintext Storage of Credentials
|
||||
|
||||
The **Hawk** key functions the same way passwords do in traditional authentication systems. In order to compute the request MAC,
|
||||
the server must have access to the key in plaintext form. This is in contrast, for example, to modern operating systems, which
|
||||
store only a one-way hash of user credentials.
|
||||
|
||||
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
|
||||
to perform any action on behalf of any resource owner. Accordingly, it is critical that servers protect these keys from unauthorized
|
||||
access.
|
||||
|
||||
## Entropy of Keys
|
||||
|
||||
Unless a transport-layer security protocol is used, eavesdroppers will have full access to authenticated requests and request
|
||||
MAC values, and will thus be able to mount offline brute-force attacks to recover the key used. Servers should be careful to
|
||||
assign keys which are long enough, and random enough, to resist such attacks for at least the length of time that the **Hawk**
|
||||
credentials are valid.
|
||||
|
||||
For example, if the credentials are valid for two weeks, servers should ensure that it is not possible to mount a brute force
|
||||
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
|
||||
longest key reasonable.
|
||||
|
||||
It is equally important that the pseudo-random number generator (PRNG) used to generate these keys be of sufficiently high
|
||||
quality. Many PRNG implementations generate number sequences that may appear to be random, but which nevertheless exhibit
|
||||
patterns or other weaknesses which make cryptanalysis or brute force attacks easier. Implementers should be careful to use
|
||||
cryptographically secure PRNGs to avoid these problems.
|
||||
|
||||
## Coverage Limitations
|
||||
|
||||
The request MAC only covers the HTTP `Host` header and does not cover any other headers which can often affect how the request
|
||||
body is interpreted by the server (i.e. Content-Type). If the server behavior is influenced by the presence or value of such headers,
|
||||
an attacker can manipulate the request header without being detected. Implementers should use the `ext` feature to pass
|
||||
application-specific information via the Authorization header which is protected by the request MAC.
|
||||
|
||||
|
||||
# Frequently Asked Questions
|
||||
|
||||
### Where is the protocol specification?
|
||||
|
||||
If you are looking for some prose explaining how all this works, there isn't any. **Hawk** is being developed as an open source
|
||||
project instead of a standard. In other words, the [code](tree/master/lib) is the specification.
|
||||
|
||||
### Does **Hawk** have anything to do with OAuth?
|
||||
|
||||
Short answer: no.
|
||||
|
||||
**Hawk** was originally proposed as the OAuth MAC Token specification. However, the OAuth working group in its consistent
|
||||
incompetence failed to produce a final, usable solution to address one of the most popular use cases of OAuth 1.0 - using it
|
||||
to authenticate simple client-server transactions (i.e. two-legged).
|
||||
|
||||
**Hawk** provides a simple HTTP authentication scheme for making client-server requests. It does not address the OAuth use case
|
||||
of delegating access to a third party. If you are looking for an OAuth alternative, check out [Oz](/hueniverse/oz).
|
||||
|
||||
### Where can I find **Hawk** implementations in other languages?
|
||||
|
||||
At this time, **Hawk** is only implemented in JavaScript as a node.js module. Check this space for future support of other
|
||||
languages (and such contributions are always welcome).
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче