# PyHawk

**Repository Path**: mirrors_warner/PyHawk

## Basic Information

- **Project Name**: PyHawk
- **Description**: Python library for HAWK HTTP authentication
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-26
- **Last Updated**: 2026-01-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Python Libraries for HAWK
==========================

Hawk_ is an HTTP authentication scheme using a message authentication code (MAC) algorithm to provide partial HTTP request cryptographic verification.

.. _Hawk: https://github.com/hueniverse/hawk

PyHawk is great for consuming or providing webservices from Python.

Usage (Client Side)
-------------------

If you had code that consumed a HAWK authenticated webservice,
you could do something like the following

::

    import hawk
    import requests

    # Hawk is secured with a shared secret
    credentials = db.lookup_secrets(some_id)

    # Prepare your request headers
    header = hawk.client.header(url, 'GET', {
        'credentials': credentials,
        'ext': 'Yo Yo'})

    # Which goes into Authorization field of HTTP headers
    headers = [('Authorization', header['field'])]
    res = requests.get(url, data=params, headers=headers)

    response = { 'headers': res.headers }

    # We can verify we're talking to our trusted server
    verified = hawk.client.authenticate(response, credentials,
                                        header['artifacts'],
                                        {'payload': res.text})
    if verified:
        print res.text
    else:
        print "Something fishy going on."
        
See `sample_client.py`_ for details.

.. _`sample_client.py`: https://github.com/mozilla/PyHawk/blob/master/sample_client.py

Usage (Server side)
-------------------
If you provide a webservice and want to do authentication via HAWK,
do something like the following:

::


    import hawk

    # A callback function for looking up credentials
    def lookup_hawk_credentials(id):
        # Some collection of secrets
        return db.lookup(id)

    # req is a Request object from your webserver framework
    if 'Hawk ' in req.headers['Authorization']:
        return check_auth_via_hawk(req)
    else:
        return failure(req, res)

    def check_auth_via_hawk(req):
        server = hawk.Server(req, lookup_hawk_credentials)

        # This will raise a hawk.util.HawkException if it fails
        artifacts = server.authenticate()

        # Sign our response, so clients can trust us
        auth = server.header(artifacts,
                                 { 'payload': payload,
                                   'contentType': 'text/plain' })

        headers = [('Content-Type', 'text/plain'),
                       ('Server-Authorization', auth)]

        start_response(status, headers)

        return payload
        
See `sample_server.py`_ for details.

.. _`sample_server.py`: https://github.com/mozilla/PyHawk/blob/master/sample_client.py


Status
------

This is under development, ready for adventurous users.
There doesn't appear to be a Python library for HAWK.
Let me know if there is already a robust library.

Development
-----------

Optionally use `env` as a virtualenv

::

    virtualenv env
    source env/bin/activate


Locally install source:

::

    python setup.py develop

Unit tests are in `hawk/tests`.

::

    python hawk/tests/test_*.py


Additionally, one can test compatibility:

The `compatibility/nodejs` directory has a server.js and a client.js (Node code) which are from HAWK's usage.js.

To test the server, do the following:

1) python sample_server.py
2) cd compatibility/nodejs/
3) node client.js

Output should be 

::

    Authenticated Request is 200 (OK)
    Response validates (OK)
    Unauthenticated request should 401 - (OK)

Note: the port numbers in test_pyhawk.py and client.js must match.

To test the client, do the following:

1) cd compatibility/nodejs/
2) node server.js
3) cd ../..
4) python sample_client.py

Output should be

::

    Response validates (OK)

Plan
----

Iterate on a python library until it can communicate with the test client/server.

1) ✓ Write Server API
2) ✓ Write client API
3) ✓ Switch to callback style
4) Improve code style
5) Make API elegant
6) Put a release together

A source for inspiration on 4 and 5 should be macauthlib_, from the Mozilla Services team, which is basically PyHawk, before Hawk existed. (Thanks rfk!)

.. _macauthlib: https://github.com/mozilla-services/macauthlib

Status
------

Client and Server APIs are working according to the Node.js implementation. W00t!

Please file issues for code style, bugs, etc.