Metadata-Version: 1.0
Name: PyHawk
Version: 0.1.1
Summary: 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.

Home-page: https://github.com/mozilla/PyHawk
Author: Austin King
Author-email: ozten@mozilla.com
License: UNKNOWN
Description: 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.
        
        0.1 - XXXX-XX-XX
        ================
        
        - Implemented the first working version of PyHawk
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
