drf-httpsig 1.0.1

HTTP Signature support for Django REST framework

Easy HTTP Signature authentication support for the Django REST framework.

Overview

The HTTP Signature scheme provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to Amazon’s HTTP Signature scheme, used by many of its services. The HTTP Signature specification is currently an IETF draft.

Contents

• Overview

• Requirements

• Installation

• Running the Tests

• Usage

• Support

• Example Usage and Session w/cURL

Requirements

• Python 2.7, 3.2+ (currently tested up to 3.4.1)

• httpsig

Installation

This module uses setuptools and is hosted on PyPi so installation is as easy as:

pip install drf-httpsig

This should also install the httpsig module which houses all the magic; this module is pure DRF glue (as it should be).

You can also run setup.py from inside a clone of the repository:

python setup.py install

Note that if you do so, modules with a version requirement may attempt to re-install the module as versioneer may report a different version, especially if your clone of the repo has any uncommitted/untagged changes.

Running the Tests

To run the tests for the module, use the following command on the repository root directory:

python setup.py test

Note that testing depends on django-nose, which will be installed before testing. You may also run the tests with tox using the included tox.ini file which has the benefit of keeping all testing dependances in a venv automatically.:

tox -e py27,py32,…

Usage

To actually authenticate HTTP requests with this module, you need to extend the SignatureAuthentication class, as follows:

# my_api/auth.py

from drf_httpsig.authentication import SignatureAuthentication

class MyAPISignatureAuthentication(SignatureAuthentication):
    # The HTTP header used to pass the consumer key ID.

    # A method to fetch (User instance, user_secret_string) from the
    # consumer key ID, or None in case it is not found. Algorithm
    # will be what the client has sent, in the case that both RSA
    # and HMAC are supported at your site (and also for expansion).
    def fetch_user_data(self, key_id, algorithm="hmac-sha256"):
        # ...
        # example implementation:
        try:
            user = User.objects.get(keyId=key_id, algo=algorithm)
            return (user, user.secret)
        except User.DoesNotExist:
            return (None, None)

4. Configure DRF to use your authentication class; e.g.:

# my_project/settings.py

# ...
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
       'my_api.auth.MyAPISignatureAuthentication',
    ),
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated',
    )
}
# The above will force HTTP signature for all requests.
# ...

Support

Please file any issues in the issue tracker. You are also welcome to contribute features and fixes via pull requests.

Example Usage and Session w/cURL

Assuming the setup detailed above, a project running on localhost:8000 could be probed with cURL as follows:

# Pre-calculate this first bit.
~$ SSS=Base64(Hmac(SECRET, "Date: Mon, 17 Feb 2014 06:11:05 GMT", SHA256))
~$ curl -v -H 'Date: "Mon, 17 Feb 2014 06:11:05 GMT"' -H 'Authorization: Signature keyId="my-key",algorithm="hmac-sha256",headers="date",signature="SSS"'

And, with much less pain, using the modules requests and httpsig:

import requests
from httpsig.requests_auth import HTTPSignatureAuth

KEY_ID = 'su-key'
SECRET = 'my secret string'

signature_headers = ['(request-line)', 'accept', 'date', 'host']
headers = {
  'Host': 'localhost:8000',
  'Accept': 'application/json',
  'Date': "Mon, 17 Feb 2014 06:11:05 GMT"
}

auth = HTTPSignatureAuth(key_id=KEY_ID, secret=SECRET,
                       algorithm='hmac-sha256',
                       headers=signature_headers)
req = requests.get('http://localhost:8000/resource/',
                 auth=auth, headers=headers)
print(req.content)