Skip to main content

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:

https://npmjs.org/package/hawk

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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hawkauthlib-2.0.0.tar.gz (14.9 kB view details)

Uploaded Source

Built Distribution

hawkauthlib-2.0.0-py2.py3-none-any.whl (32.4 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file hawkauthlib-2.0.0.tar.gz.

File metadata

  • Download URL: hawkauthlib-2.0.0.tar.gz
  • Upload date:
  • Size: 14.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for hawkauthlib-2.0.0.tar.gz
Algorithm Hash digest
SHA256 effd64a2572e3c0d9090b55ad2180b36ad50e7760bea225cb6ce2248f421510d
MD5 bb2257a488c9971ba226bc6ade06c11f
BLAKE2b-256 26b70ec2846e5e2b3591ca867d7b06b67b5242f73bfe6da164b7232b8bffc657

See more details on using hashes here.

File details

Details for the file hawkauthlib-2.0.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for hawkauthlib-2.0.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 935878d3a75832aa76f78ddee13491f1466cbd69a8e7e4248902763cf9953ba9
MD5 efe71dcc5c5fdeca2c59881cd64faac9
BLAKE2b-256 53ec23dd5cbd5e950543fdd30d91ddac4f56e395d14316677aa4cb78a029f8e2

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page