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>`_.