Metadata-Version: 2.0
Name: drf-httpsig
Version: 1.0.0
Summary: HTTP Signature support for Django REST framework
Home-page: https://github.com/ahknight/drf-httpsig
Author: Adam Knight
Author-email: adam@movq.us
License: MIT
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Dist: djangorestframework (>=2.3,<2.4)
Requires-Dist: httpsig

drf-httpsig
-----------

Overview
--------

Provides `HTTP Signature`_ support for `Django REST framework`_. The HTTP Signature package 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::

Installation
------------

Installing the package via the repository::

   pip install drf-httpsig

The current implementation depends on the `httpsig`_ package, which is a modified version of the `http_signature package by David Lehn`_.


Running the tests
-----------------

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

  python manage.py test


Usage
-----

To authenticate HTTP requests via HTTP signature, you need to:

1. Install this package in your Django project, as instructed in `Installation`_.
2. Add ``drf_httpsig`` to your ``settings.py`` INSTALLED_APPS.
3. In your app code, 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.
        def fetch_user_data(self, keyId):
            # ...
            # example implementation:
            try:
                user = User.objects.get(keyId=keyId)
                return (user, user.secret)
            except User.DoesNotExist:
                return (None, None)


4. Configure Django REST framework to use you 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.
    # ...


Roadmap
-------

- Currently, the library only supports HMAC-SHA256 for signing.
- Since HTTP Signature uses a HTTP header for the request date and time, the authentication class could deal with request expiry.


Example usage & session w/cURL
------------------------------

Assuming the setup detailed in `Usage`_, a project running on ``localhost:8000`` could be probed with cURL as follows::

  ~$ 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 ``http_signature``::

  import requests
  from http_signature.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


.. References:
.. _`HTTP Signature`: https://datatracker.ietf.org/doc/draft-cavage-http-signatures/
.. _`Django REST framework`: http://django-rest-framework.org/
.. _`HTTP Signature scheme`: http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html
.. _`httpsig`: https://github.com/ahknight/httpsig
.. _`http_signature package by David Lehn`: https://github.com/digitalbazaar/py-http-signature


drf-httpsig Changes
-------------------

v1.0b2 (2014-Jul-01)
~~~~~~~~~~~~~~~~~~~~
* Added versioneer.
* Updated requirements to use latest httpsig.
* Added "setup.py test" and tox support.
* Fixed a unit test.

v1.0b1 (2014-Jun-27)
~~~~~~~~~~~~~~~~~~~~
* Renamed to drf-httpsig because I don't hate my hands.
* Updated requirements versions to be more sane.
* Switched to a different branch for http_signature.
* Removed API_KEY_HEADER in favor of the keyId, per spec.
* Cleaned up the repo a bit.
* Cleaned up the code a bit.


djangorestframework-httpsignature (previous)
--------------------------------------------

v0.1.5, 20140613 -- Document installation issue

* Document workaround on installation problems.

v0.1.4, 20140613 -- Improve installation

* Make requirements file comply with docs.
* Decide on http_signature commit.

v0.1.3, 20140220 -- Upload to PyPI

* Prepare docs to upload package to PyPI

v0.1.2, 20140219 -- Package data and clean up

* Updated package classifiers
* Cleaned up unused code in authentication.py

v0.1.1, 20140217 -- Documentation and clean up

* The package can be installed.
* Continuous integration via Travis.
* Unit tests for the authentication code.
* General docuementation in the README file.

v0.1.0, 20140217 -- Initial release


