mozilla / pyhawk

DEPRECATED - **UNMAINTAINED** Python library for HAWK HTTP authentication

Important

2017: THIS LIBRARY IS UNMAINTAINED AND MAY BE INSECURE. PLEASE USE ONE OF THE ALTERNATIVES LISTED BELOW.

Python Libraries for HAWK

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

PyHawk is great for consuming or providing webservices from Python.

Alternatives

PyHawk's goal is to track as closely to the original NodeJS' hawk code, because hawk is a primarily an authentication scheme documented by the implementaiton (as opposed to a standard).

If you find this module un-pythonic, also consider:

• mohawk Pythonic Hawk library
• hawkauthlib

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.

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.

Logging

PyHawk uses python logging to emit information about why authorization is failing and so on. You can configure these logger channels with INFO, DEBUG, etc, to get some helpful output.

hawk

All hawk logging, including everything below.

hawk.client

All hawk client related messages, including header construction.

hawk.server

All hawk server related messages, including authorization.

hawk.hcrypto

All hawk crypto related messages, including bewit handling.

hawk.util

All shared hawk code such as header normalization.

Status

2017: This library is unmaintained and probably insecure.

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)

Publishing Versions

Edit setup.py and bump the version number.

python setup.py sdist upload

You should see your updates at https://pypi.python.org/pypi?%3Aaction=pkg_edit&name=PyHawk

pyhawk's Issues

CODE_OF_CONDUCT.md file missing

As of January 1 2019, Mozilla requires that all GitHub projects include this CODE_OF_CONDUCT.md file in the project root. The file has two parts:

1. Required Text - All text under the headings Community Participation Guidelines and How to Report, are required, and should not be altered.
2. Optional Text - The Project Specific Etiquette heading provides a space to speak more specifically about ways people can work effectively and inclusively together. Some examples of those can be found on the Firefox Debugger project, and Common Voice. (The optional part is commented out in the raw template file, and will not be visible until you modify and uncomment that part.)

If you have any questions about this file, or Code of Conduct policies and procedures, please reach out to [email protected].

(Message COC001)

Fix setup.py

setup.py and init.py aren't as good as they could be.

References:

• #10 (review)
• https://github.com/peterbe/mincss/blob/master/setup.py#L6-L11

Move sample_server.py and sample_client.py logic into a unit test

We need to get the logic out of sample_server.py and sample.client.py into tests_pyhawk.py.

Bonus points for keeping the ability to test client code against the Node.js reference server and server code testable from the Node reference client.

timestamps are not in UTC

PyHawk uses time.time() to create timestamps but that is not a UTC timestamp, it's local. The Hawk lib uses UTC timestamps via Date.now()

The code should be changed to:

import calendar
import time
calendar.timegm(time.gmtime())

(clunky, I know)

THIS LIBRARY IS NO LONGER MAINTAINED

Sorry for any inconvenience but PyHawk is no longer maintained so we can no longer respond to issues or accept patches. New issues and patches will be closed.

Please consider these alternatives:

• https://github.com/kumar303/mohawk
• https://github.com/mozilla-services/hawkauthlib

Improve randomness / security of client nonce

in hcrypto.py we use a naive method for generating the nonces. We should use a more secure random.

Reported via email by Jason:

The Python Docs for the random module say that it is not suitable for cryptographic uses and I thought it could be refactored to meet Eran's implementation a little better: For example:

from Crypto import Random
from base64 import urlsafe_b64encode
rng = Random.new()
random_string = urlsafe_b64encode(rng.read(len*6))

This could then be sliced to the specified string length.

Oz implementation

Hi @ozten great work on this. I spent about an hour doing this work then realised I should probably google it first and this project popped straight up and is far more robust than my code.

What I really want though is a Python Oz implementation, do you know of any?

Replace awkward dictionary key checking

In many places, I do a check for a key in a dict.

As @ludwigkraatz pointed out, we should instead use:

get('hash', None)

Go through and make these blocks Pythonic.

register in PyPI?

Hey, when you get a chance, could you register this in PyPI (the "cheese shop")? That would make it easier to install ("pip install PyHawk"). I can walk you through the process if you'd like. Thanks!

Wiki changes

FYI: The following changes were made to this repository's wiki:

• defacing spam has been removed

• the wiki has been disabled, as it was not used

These were made as the result of a recent automated defacement of publically writeable wikis.

Unused dependencies

I can see PyCrypto in requirements.txt and requests in both setup.py and requirements.txt

They do not seem like these are used for anything, can they be removed ?

Add syntax highlighting to code blocks in README

Syntax highlighting to the code in README.md will make it more readable 😃

Security Vulnerability in Payload Verification

The incoming (client supplied) hash of the payload is being trusted by the server and not verified before the signature is calculated.

See:

PyHawk/hawk/hcrypto.py

Line 65 in 142d6cb

options['hash']])

This vulnerability has persisted to hawkauthlib and reported, but is not present in mohawk as it has added robust payload verification

This mozilla/PyHawk repository is no longer maintained so this Security Vulnerability will not be addressed.

Use the mohawk repository if you are looking for a python implementation of Hawk Authentication.
Alternatively hawkauthlib may have merged my PR which addresses this vulnerability by the time you have read this.

Upgrade dependency to latest requests 2.2.1

I notice that your dev requirements file states that you are depending on requests 1.2.0

I ran the sample_client.py against requests 2.2.1 and it bombed with this error:
https://gist.github.com/javouhey/11240251

I checked the Custom Header docs for requests v1.2.3 and it expects the headers argument to be a dictionary.

res = requests.get(url, data=params, headers=headers)