Hawk Access Authentication protocol
Project description
This is a low-level library for implementing Hawk Access Authentication, a simple HTTP request-signing scheme described in:
To access resources using Hawk Access Authentication, the client must have obtained a set of Hawk credentials including an id and a secret key. They use these credentials to make signed requests to the server.
When accessing a protected resource, the server will generate a 401 challenge response with the scheme “Hawk” as follows:
> GET /protected_resource HTTP/1.1 > Host: example.com < HTTP/1.1 401 Unauthorized < WWW-Authenticate: Hawk
The client will use their Hawk credentials to build a request signature and include it in the Authorization header like so:
> GET /protected_resource HTTP/1.1 > Host: example.com > Authorization: Hawk id="h480djs93hd8", > ts="1336363200", > nonce="dj83hs9s", > mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM=" < HTTP/1.1 200 OK < Content-Type: text/plain < < For your eyes only: secret data!
This library provices the low-level functions necessary to implement such an authentication scheme. For Hawk Auth clients, it provides the following function:
sign_request(req, id, key, algorithm=”sha256”): sign a request using Hawk Access Auth.
For Hawk Auth servers, it provides the following functions:
get_id(req): get the claimed Hawk Auth id from the request.
check_signature(req, key, algorithm=”sha256”): check that the request was signed with the given key.
The request objects passed to these functions can be any of a variety of common object types:
a WSGI environment dict
a webob.Request object
a requests.Request object
a string or file-like object of request data
A typical use for a client program might be to install the sign_request function as an authentication hook when using the requests library, like this:
import requests import functools import hawkauthlib # Hook up sign_request() to be called on every request. def auth_hook(req): hawkauthlib.sign_request(req, id="<AUTH-ID>", key="<AUTH-KEY>") return req session = requests.session(hooks={"pre_request": auth_hook}) # Then use the session as normal, and the auth is applied transparently. session.get("http://www.secret-data.com/get-my-data")
A typical use for a server program might be to verify requests using a WSGI middleware component, like this:
class HawkAuthMiddleware(object): # ...setup code goes here... def __call__(self, environ, start_response): # Find the identity claimed by the request. id = hawkauthlib.get_id(environ) # Look up their secret key. key = self.SECRET_KEYS[id] # If the signature is invalid, error out. if not hawkauthlib.check_signature(environ, key): start_response("401 Unauthorized", [("WWW-Authenticate", "Hawk")]) return [""] # Otherwise continue to the main application. return self.application(environ, start_response)
The following features of the Hawk protocol are not yet supported:
Bewits.
Timestamp adjustment.
Calculating or verifying the server’s response signature.
Calculating or verifying payload hashes.
2.0.0 - 2016-01-16
Py27, Py35 compatible
0.1.1 - 2013-11-12
Let key be any binary string; id must still be ascii.
0.1.0 - 2013-08-19
Initial release; this is essentially the macauthlib codebase, ported over to the new Hawk auth specification.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for hawkauthlib-2.0.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 935878d3a75832aa76f78ddee13491f1466cbd69a8e7e4248902763cf9953ba9 |
|
MD5 | efe71dcc5c5fdeca2c59881cd64faac9 |
|
BLAKE2b-256 | 53ec23dd5cbd5e950543fdd30d91ddac4f56e395d14316677aa4cb78a029f8e2 |