Metadata-Version: 2.1
Name: encipher
Version: 0.5.2
Summary: Secure key based authentication for HTTP APIs
Home-page: https://code.compassfoundation.io/console-modules/encipher
Author: Dave Burkholder
Author-email: dave@compassfoundation.io
License: ISC
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
License-File: LICENSE.md
Requires-Dist: aspen_crypto
Requires-Dist: django
Requires-Dist: djangorestframework
Requires-Dist: drf-spectacular
Requires-Dist: lclazy
Requires-Dist: lcrequests
Requires-Dist: pylogcabin
Requires-Dist: pyseto
Requires-Dist: lcconfig
Provides-Extra: development
Requires-Dist: coverage>=7.6; extra == "development"
Requires-Dist: django-stubs>=5.0; extra == "development"
Requires-Dist: freezegun>=1.5.1; extra == "development"
Requires-Dist: mypy>=1.11; extra == "development"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "development"
Requires-Dist: sphinx>=7.4; extra == "development"

Encipher
========

What?
-----

This is an library designed to handle authentication in
*machine-to-machine* API requests, via Paseto tokens.


Why?
----

The standard pattern of using username and password works well for
user-to-server requests, but is lacking for machine-to-machine
applications. In these scenarios, since the password doesn't need to be
memorable by a user, we can use something far more secure: asymmetric
key cryptography. This has the advantage that a password is never
actually sent to the server.


How?
----

A public / private key pair is generated by the client machine. The
server machine is then supplied with the public key, which it can store
in any method it likes. When this library is used with Django, it
provides a model for storing public keys associated with built-in User
objects. When a request is made, the client creates a Paseto Token including
several claims and signs it using it’s private key. Upon receipt, the
server verifies the claim to using the public key to ensure the issuer
is legitimately who they claim to be.

To make an authenticated request, the client must generate a Paseto Token
following the above format and include it as the HTTP Authorization
header in the following format:

::

    Authorization: Paseto <my_token>

**Important note**: the claim is *not* encrypted, only signed.
Additionally, the signature only prevents the claim from being tampered
with or re-used. Every other part of the request is still vulnerable to
tamper. Therefore, this is not a replacement for using SSL in the
transport layer.

See docs/usage.rst for specific details.


Acknowledgements
----------------

Inspired by `asymmetric-jwt-auth <https://github.com/crgwbr/asymmetric-jwt-auth>`_
and `django-rest-paseto-auth <https://github.com/moiseshiraldo/django-rest-paseto-auth>`_.
