# directory-signature-auth
[![code-climate-image]][code-climate]
[![circle-ci-image]][circle-ci]
[![codecov-image]][codecov]
[![pypi-image]][pypi]
**Library implementing Hawk authentication scheme using a message authentication code (MAC) algorithm to provide partial HTTP request cryptographic verification.**
---
The client implements `RequestSigner` to generate a secret-salted hash of the request URL and body. The secret-salt is shared with the target server.
The target server implements `RequestSignatureChecker` to check the signature provided in the request header accurately describes the request's URL and request body.
If `RequestSignatureChecker` accepts the header as genuine then the request is accepted, otherwise the request is rejected.
## RequestSigner usage
### Python requests
On the client, a signature can be generated for a [requests](http://docs.python-requests.org/en/master/)'s `requests.Request`:
```
import requests
from sigauth.utils import RequestSigner
from django.conf import settings
request_signer = RequestSigner(settings.API_SIGNATURE_SECRET)
def send_request(method, url, body):
request = requests.Request(method=method, url=url, body=body).prepare()
sign_request(request)
return requests.Session().send(request)
def sign_request(request):
headers = request_signer.get_signature_headers(
url=request.path_url,
body=request.body,
method=request.method,
content_type=request.headers.get('Content-Type'),
)
request.headers.update(headers)
```
## RequestSignatureChecker usage
### Django Rest Framework
This library implements a wrapper around `RequestSignatureChecker` for Django Rest Framework: `SignatureCheckPermissionBase`. It must be sub-classed to set the secret:
```
from sigauth import permissions
from django.conf import settings
class SignatureCheckPermission(permissions.SignatureCheckPermissionBase):
secret = settings.SIGNATURE_SECRET
```
On the target server, `SignatureCheckPermission` can then be set in the `DEFAULT_PERMISSION_CLASSES` setting, or on a specific DRF view's `permission_classes` attribute.
### Django View
On the target server, the signature checker can be implemented on views too:
```
from django.http import HttpResponseForbidden
from sigauth.utils import RequestSignatureChecker
api_checker = RequestSignatureChecker(settings.SIGNATURE_SECRET)
class SignatureCheckMixin:
def dispatch(self, request, *args, **kwargs):
if api_checker.test_signature(request) is False:
return HttpResponseForbidden()
return super().dispatch(request, path='', *args, **kwargs)
```
`SignatureCheckMixin` can then be used on a view to reject incoming requests that have been tampered with.
Note that in the above examples, the client's `settings.API_SIGNATURE_SECRET` must be the same value as api's `settings.SIGNATURE_SECRET`
### Middleware
Some services may expect every request to require signature checks. This library implements a wrapper around `RequestSignatureChecker` for Django middleware to facilitate this: `SignatureCheckMiddlewareBase`. It must be sub-classed to set the secret:
```
from sigauth.middleware import SignatureCheckMiddlewareBase
from django.conf import settings
class SignatureCheckMiddleware(SignatureCheckMiddlewareBase):
secret = settings.SIGNATURE_SECRET
```
`SignatureCheckMiddleware` can then be added to the `MIDDLEWARE` setting (or `MIDDLEWARE_CLASSES` if using Django < 2). Set `SIGAUTH_URL_NAMES_WHITELIST` settings to a list of url names that should be excluded from checks.
## Installation
```shell
pip install -e git+https://git@github.com/uktrade/directory-signature-auth.git@v1.0.0#egg=directory-signature-auth
```
## Development
$ git clone https://github.com/uktrade/directory-signature-auth
$ cd directory-signature-auth
$ make
## Publish to PyPI
The package should be published to PyPI on merge to master. If you need to do it locally then get the credentials from rattic and add the environment variables to your host machine:
| Setting |
| --------------------------- |
| DIRECTORY_PYPI_USERNAME |
| DIRECTORY_PYPI_PASSWORD |
Then run the following command:
make publish
[code-climate-image]: https://codeclimate.com/github/uktrade/directory-signature-auth/badges/issue_count.svg
[code-climate]: https://codeclimate.com/github/uktrade/directory-signature-auth
[circle-ci-image]: https://circleci.com/gh/uktrade/directory-signature-auth/tree/master.svg?style=svg
[circle-ci]: https://circleci.com/gh/uktrade/directory-signature-auth/tree/master
[codecov-image]: https://codecov.io/gh/uktrade/directory-signature-auth/branch/master/graph/badge.svg
[codecov]: https://codecov.io/gh/uktrade/directory-signature-auth
[pypi-image]: https://badge.fury.io/py/sigauth.svg
[pypi]: https://badge.fury.io/py/sigauth
Raw data
{
"_id": null,
"home_page": "https://github.com/uktrade/directory-signature-auth",
"name": "sigauth",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Department for International Trade",
"author_email": "",
"download_url": "",
"platform": null,
"description": "# directory-signature-auth\n\n[![code-climate-image]][code-climate]\n[![circle-ci-image]][circle-ci]\n[![codecov-image]][codecov]\n[![pypi-image]][pypi]\n\n**Library implementing Hawk authentication scheme using a message authentication code (MAC) algorithm to provide partial HTTP request cryptographic verification.**\n\n---\n\nThe client implements `RequestSigner` to generate a secret-salted hash of the request URL and body. The secret-salt is shared with the target server.\n\nThe target server implements `RequestSignatureChecker` to check the signature provided in the request header accurately describes the request's URL and request body.\n\nIf `RequestSignatureChecker` accepts the header as genuine then the request is accepted, otherwise the request is rejected.\n\n## RequestSigner usage\n\n### Python requests\n\nOn the client, a signature can be generated for a [requests](http://docs.python-requests.org/en/master/)'s `requests.Request`:\n\n```\nimport requests\n\nfrom sigauth.utils import RequestSigner\n\nfrom django.conf import settings\n\n\nrequest_signer = RequestSigner(settings.API_SIGNATURE_SECRET)\n\n\ndef send_request(method, url, body):\n request = requests.Request(method=method, url=url, body=body).prepare()\n sign_request(request)\n return requests.Session().send(request)\n\n\ndef sign_request(request):\n headers = request_signer.get_signature_headers(\n url=request.path_url,\n body=request.body,\n method=request.method,\n content_type=request.headers.get('Content-Type'),\n )\n request.headers.update(headers)\n```\n\n\n## RequestSignatureChecker usage\n\n### Django Rest Framework\n\nThis library implements a wrapper around `RequestSignatureChecker` for Django Rest Framework: `SignatureCheckPermissionBase`. It must be sub-classed to set the secret:\n\n```\nfrom sigauth import permissions\n\nfrom django.conf import settings\n\n\nclass SignatureCheckPermission(permissions.SignatureCheckPermissionBase):\n secret = settings.SIGNATURE_SECRET\n```\n\nOn the target server, `SignatureCheckPermission` can then be set in the `DEFAULT_PERMISSION_CLASSES` setting, or on a specific DRF view's `permission_classes` attribute.\n\n### Django View\n\nOn the target server, the signature checker can be implemented on views too:\n\n```\nfrom django.http import HttpResponseForbidden\n\nfrom sigauth.utils import RequestSignatureChecker\n\n\napi_checker = RequestSignatureChecker(settings.SIGNATURE_SECRET)\n\n\nclass SignatureCheckMixin:\n def dispatch(self, request, *args, **kwargs):\n if api_checker.test_signature(request) is False:\n return HttpResponseForbidden()\n return super().dispatch(request, path='', *args, **kwargs)\n```\n\n`SignatureCheckMixin` can then be used on a view to reject incoming requests that have been tampered with.\n\nNote that in the above examples, the client's `settings.API_SIGNATURE_SECRET` must be the same value as api's `settings.SIGNATURE_SECRET`\n\n### Middleware\n\nSome services may expect every request to require signature checks. This library implements a wrapper around `RequestSignatureChecker` for Django middleware to facilitate this: `SignatureCheckMiddlewareBase`. It must be sub-classed to set the secret:\n\n```\nfrom sigauth.middleware import SignatureCheckMiddlewareBase\n\nfrom django.conf import settings\n\nclass SignatureCheckMiddleware(SignatureCheckMiddlewareBase):\n secret = settings.SIGNATURE_SECRET\n\n```\n\n`SignatureCheckMiddleware` can then be added to the `MIDDLEWARE` setting (or `MIDDLEWARE_CLASSES` if using Django < 2). Set `SIGAUTH_URL_NAMES_WHITELIST` settings to a list of url names that should be excluded from checks.\n\n## Installation\n\n```shell\npip install -e git+https://git@github.com/uktrade/directory-signature-auth.git@v1.0.0#egg=directory-signature-auth\n```\n\n## Development\n\n $ git clone https://github.com/uktrade/directory-signature-auth\n $ cd directory-signature-auth\n $ make\n\n## Publish to PyPI\n\nThe package should be published to PyPI on merge to master. If you need to do it locally then get the credentials from rattic and add the environment variables to your host machine:\n\n| Setting |\n| --------------------------- |\n| DIRECTORY_PYPI_USERNAME |\n| DIRECTORY_PYPI_PASSWORD |\n\n\nThen run the following command:\n\n make publish\n\n[code-climate-image]: https://codeclimate.com/github/uktrade/directory-signature-auth/badges/issue_count.svg\n[code-climate]: https://codeclimate.com/github/uktrade/directory-signature-auth\n\n[circle-ci-image]: https://circleci.com/gh/uktrade/directory-signature-auth/tree/master.svg?style=svg\n[circle-ci]: https://circleci.com/gh/uktrade/directory-signature-auth/tree/master\n\n[codecov-image]: https://codecov.io/gh/uktrade/directory-signature-auth/branch/master/graph/badge.svg\n[codecov]: https://codecov.io/gh/uktrade/directory-signature-auth\n\n[pypi-image]: https://badge.fury.io/py/sigauth.svg\n[pypi]: https://badge.fury.io/py/sigauth\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Signature authentication library for Export Directory.",
"version": "5.2.7",
"project_urls": {
"Homepage": "https://github.com/uktrade/directory-signature-auth"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d685c03985ac21b99a246314dc3516c57c427f58e298489bf349720e822d18b8",
"md5": "dd00565eef79f8d814fc39b1f22c4f10",
"sha256": "4c2010061ba028840a78523290a18d15f87d1cc500f4768ed8f4c1ff53d808d1"
},
"downloads": -1,
"filename": "sigauth-5.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dd00565eef79f8d814fc39b1f22c4f10",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6881,
"upload_time": "2024-03-05T14:21:57",
"upload_time_iso_8601": "2024-03-05T14:21:57.165930Z",
"url": "https://files.pythonhosted.org/packages/d6/85/c03985ac21b99a246314dc3516c57c427f58e298489bf349720e822d18b8/sigauth-5.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-05 14:21:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "uktrade",
"github_project": "directory-signature-auth",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"circle": true,
"lcname": "sigauth"
}
JSON
