Requests-Hawk
#############
|pypi| |travis|
.. |travis| image:: https://travis-ci.org/mozilla-services/requests-hawk.png
:target: https://travis-ci.org/mozilla-services/requests-hawk
.. |pypi| image:: https://img.shields.io/pypi/v/requests-hawk.svg
:target: https://pypi.python.org/pypi/requests-hawk
This project allows you to use `the python requests library
<http://python-requests.org/>`_ with `the hawk authentication
<https://github.com/hueniverse/hawk>`_ mechanism.
Hawk itself does not provide any mechanism for obtaining or transmitting the
set of shared credentials required, but this project proposes a scheme we use
across mozilla services projects.
Great, how can I use it?
========================
First, you'll need to install it:
.. code-block:: bash
pip install requests-hawk
Then, in your project, if you know the `id` and `key`, you can use:
.. code-block:: python
import requests
from requests_hawk import HawkAuth
hawk_auth = HawkAuth(id='my-hawk-id', key='my-hawk-secret-key')
requests.post("https://example.com/url", auth=hawk_auth)
Or if you need to derive them from the hawk session token, instead use:
.. code-block:: python
import requests
from requests_hawk import HawkAuth
hawk_auth = HawkAuth(
hawk_session=resp.headers['hawk-session-token'],
server_url=self.server_url
)
requests.post("/url", auth=hawk_auth)
In the second example, the ``server_url`` parameter to ``HawkAuth`` was used to
provide a default host name, to avoid having to repeat it for each request.
If you wish to override the default algorithm of ``sha256``, pass the desired
algorithm name using the optional ``algorithm`` parameter.
Note: The ``credentials`` parameter has been removed. Instead pass ``id`` and
``key`` separately (as above), or pass the existing dict as ``**credentials``.
Integration with httpie
=======================
`Httpie <https://github.com/jakubroztocil/httpie>`_ is a tool which lets you do
requests to a distant server in a nice and easy way. Under the hood, ``httpie``
uses the requests library. We've made it simple for you to plug hawk with it.
If you know the id and key, use it like that:
.. code-block:: bash
http POST localhost:5000/registration\
--auth-type=hawk --auth='id:key'
Or, if you want to use the hawk session token, you can do as follows:
.. code-block:: bash
http POST localhost:5000/registration\
--auth-type=hawk --auth='c0d8cd2ec579a3599bef60f060412f01f5dc46f90465f42b5c47467481315f51:'
Take care, don't forget to add the extra ``:`` at the end of the hawk session
token for it to be considered like so.
How are the shared credentials shared?
======================================
Okay, on to the actual details.
The server gives you a session token, that you'll need to derive to get the
hawk credentials.
Do an HKDF derivation on the given session token. You'll need to use the
following parameters:
.. code-block:: python
key_material = HKDF(hawk_session, '', 'identity.mozilla.com/picl/v1/sessionToken', 32*2)
The key material you'll get out of the HKDF needs to be separated into two
parts, the first 32 hex characters are the ``hawk id``, and the next 32 ones are the
``hawk key``:
.. code-block:: python
credentials = {
'id': keyMaterial[0:32]
'key': keyMaterial[32:64]
'algorithm': 'sha256'
}
Run tests
=========
To run test, you can use tox:
.. code-block:: bash
tox
CHANGELOG
=========
1.2.1 (2023-05-03)
------------------
- Add support for ext external data string (#34)
(thanks @jtmaclachlan)
1.2.0 (unreleased)
------------------
- Nothing changed yet.
1.1.1 (2021-06-04)
------------------
- Handle cases where Content-Type is defined as bytes rather than string. (#25)
- Allow for app mohawk sender parameter configuration
1.1.0 (2020-12-16)
------------------
- Allow to skip hashing request and response bodies with `always_hash_content`.
1.0.1 (2020-01-20)
------------------
- Add Python 3 support. (#22)
1.0.0 (2015-12-15)
------------------
- Simplified API for using HawkAuth when the id and key are known. (#8)
- Added support for overriding the default algorithm (sha256) when deriving
credentials from the hawk session token, via a new ``algorithm`` parameter.
See the README for migration advice if you use the ``credentials`` parameter.
0.2.1 (2015-10-14)
------------------
- Make sure the requests json parameter is handled properly. (#7)
0.2.0 (2015-05-19)
------------------
- Fix encoding error in setup.py with Python 3.4
- Add a configuration parameter in order to be able to set the
timestamp to use.
0.1.2 (2014-08-13)
------------------
- Add Python3 support
0.1.1 (2014-07-21)
------------------
- First version
Raw data
{
"_id": null,
"home_page": "https://github.com/mozilla-services/requests-hawk",
"name": "requests-hawk",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "authentication token hawk requests",
"author": "Mozilla Services",
"author_email": "services-dev@mozilla.org",
"download_url": "https://files.pythonhosted.org/packages/af/48/35c2adbe796eee460dc3b69704dae66c2b6647c3f9d85ab156aa4b0443a6/requests-hawk-1.2.1.tar.gz",
"platform": null,
"description": "Requests-Hawk\n#############\n\n|pypi| |travis|\n\n.. |travis| image:: https://travis-ci.org/mozilla-services/requests-hawk.png\n :target: https://travis-ci.org/mozilla-services/requests-hawk\n\n.. |pypi| image:: https://img.shields.io/pypi/v/requests-hawk.svg\n :target: https://pypi.python.org/pypi/requests-hawk\n\n\nThis project allows you to use `the python requests library\n<http://python-requests.org/>`_ with `the hawk authentication\n<https://github.com/hueniverse/hawk>`_ mechanism.\n\nHawk itself does not provide any mechanism for obtaining or transmitting the\nset of shared credentials required, but this project proposes a scheme we use\nacross mozilla services projects.\n\nGreat, how can I use it?\n========================\n\nFirst, you'll need to install it:\n\n.. code-block:: bash\n\n pip install requests-hawk\n\nThen, in your project, if you know the `id` and `key`, you can use:\n\n.. code-block:: python\n\n import requests\n from requests_hawk import HawkAuth\n\n hawk_auth = HawkAuth(id='my-hawk-id', key='my-hawk-secret-key')\n requests.post(\"https://example.com/url\", auth=hawk_auth)\n\nOr if you need to derive them from the hawk session token, instead use:\n\n.. code-block:: python\n\n import requests\n from requests_hawk import HawkAuth\n\n hawk_auth = HawkAuth(\n hawk_session=resp.headers['hawk-session-token'],\n server_url=self.server_url\n )\n requests.post(\"/url\", auth=hawk_auth)\n\nIn the second example, the ``server_url`` parameter to ``HawkAuth`` was used to\nprovide a default host name, to avoid having to repeat it for each request.\n\nIf you wish to override the default algorithm of ``sha256``, pass the desired\nalgorithm name using the optional ``algorithm`` parameter.\n\nNote: The ``credentials`` parameter has been removed. Instead pass ``id`` and\n``key`` separately (as above), or pass the existing dict as ``**credentials``.\n\nIntegration with httpie\n=======================\n\n`Httpie <https://github.com/jakubroztocil/httpie>`_ is a tool which lets you do\nrequests to a distant server in a nice and easy way. Under the hood, ``httpie``\nuses the requests library. We've made it simple for you to plug hawk with it.\n\nIf you know the id and key, use it like that:\n\n.. code-block:: bash\n\n http POST localhost:5000/registration\\\n --auth-type=hawk --auth='id:key'\n\nOr, if you want to use the hawk session token, you can do as follows:\n\n.. code-block:: bash\n\n http POST localhost:5000/registration\\\n --auth-type=hawk --auth='c0d8cd2ec579a3599bef60f060412f01f5dc46f90465f42b5c47467481315f51:'\n\nTake care, don't forget to add the extra ``:`` at the end of the hawk session\ntoken for it to be considered like so.\n\nHow are the shared credentials shared?\n======================================\n\nOkay, on to the actual details.\n\nThe server gives you a session token, that you'll need to derive to get the\nhawk credentials.\n\nDo an HKDF derivation on the given session token. You'll need to use the\nfollowing parameters:\n\n.. code-block:: python\n\n key_material = HKDF(hawk_session, '', 'identity.mozilla.com/picl/v1/sessionToken', 32*2)\n\nThe key material you'll get out of the HKDF needs to be separated into two\nparts, the first 32 hex characters are the ``hawk id``, and the next 32 ones are the\n``hawk key``:\n\n.. code-block:: python\n\n credentials = {\n 'id': keyMaterial[0:32]\n 'key': keyMaterial[32:64]\n 'algorithm': 'sha256'\n }\n\nRun tests\n=========\n\nTo run test, you can use tox:\n\n.. code-block:: bash\n\n tox\n\n\nCHANGELOG\n=========\n\n1.2.1 (2023-05-03)\n------------------\n\n- Add support for ext external data string (#34)\n (thanks @jtmaclachlan)\n\n1.2.0 (unreleased)\n------------------\n\n- Nothing changed yet.\n\n\n1.1.1 (2021-06-04)\n------------------\n\n- Handle cases where Content-Type is defined as bytes rather than string. (#25)\n- Allow for app mohawk sender parameter configuration\n\n\n1.1.0 (2020-12-16)\n------------------\n\n- Allow to skip hashing request and response bodies with `always_hash_content`.\n\n\n1.0.1 (2020-01-20)\n------------------\n\n- Add Python 3 support. (#22)\n\n\n1.0.0 (2015-12-15)\n------------------\n\n- Simplified API for using HawkAuth when the id and key are known. (#8)\n- Added support for overriding the default algorithm (sha256) when deriving\n credentials from the hawk session token, via a new ``algorithm`` parameter.\n\nSee the README for migration advice if you use the ``credentials`` parameter.\n\n\n0.2.1 (2015-10-14)\n------------------\n\n- Make sure the requests json parameter is handled properly. (#7)\n\n\n0.2.0 (2015-05-19)\n------------------\n\n- Fix encoding error in setup.py with Python 3.4\n- Add a configuration parameter in order to be able to set the\n timestamp to use.\n\n\n0.1.2 (2014-08-13)\n------------------\n\n- Add Python3 support\n\n\n0.1.1 (2014-07-21)\n------------------\n\n- First version\n",
"bugtrack_url": null,
"license": "Apache License (2.0)",
"summary": "requests-hawk",
"version": "1.2.1",
"project_urls": {
"Homepage": "https://github.com/mozilla-services/requests-hawk"
},
"split_keywords": [
"authentication",
"token",
"hawk",
"requests"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e1da6bd7c2ea86b4b8e33704d942a3c7c2ecd03cffb7ecb315241de989b79003",
"md5": "a9ccbc6ecac0283538bbacc3365f7303",
"sha256": "afe8add3c72a21405543a07464b62e36a5f378585e5cf3b54b1307e884f67324"
},
"downloads": -1,
"filename": "requests_hawk-1.2.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "a9ccbc6ecac0283538bbacc3365f7303",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 7427,
"upload_time": "2023-05-04T16:15:55",
"upload_time_iso_8601": "2023-05-04T16:15:55.743522Z",
"url": "https://files.pythonhosted.org/packages/e1/da/6bd7c2ea86b4b8e33704d942a3c7c2ecd03cffb7ecb315241de989b79003/requests_hawk-1.2.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "af4835c2adbe796eee460dc3b69704dae66c2b6647c3f9d85ab156aa4b0443a6",
"md5": "7d893696b12f0913e3e6355b0d86e9fa",
"sha256": "ad9205042c94bdb15afaa19b0780e11077b24d9e5cffac1fb3d26cb08aa435b7"
},
"downloads": -1,
"filename": "requests-hawk-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "7d893696b12f0913e3e6355b0d86e9fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6798,
"upload_time": "2023-05-04T16:15:57",
"upload_time_iso_8601": "2023-05-04T16:15:57.397276Z",
"url": "https://files.pythonhosted.org/packages/af/48/35c2adbe796eee460dc3b69704dae66c2b6647c3f9d85ab156aa4b0443a6/requests-hawk-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-04 16:15:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mozilla-services",
"github_project": "requests-hawk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"tox": true,
"lcname": "requests-hawk"
}
JSON
