Crypto Keypair Authorization for Django Rest Framework
Project description
Crypto Keypair Authorization for Django Rest Framework
Cavage HTTP Key-Pair Authorization functions as an alternative for API tokens, OAuth, or JWT for REST and GraphQL APIs or web applications.
It works by having a web client sign HTTP headers and/or create a hash digest of the HTTP message body. In doing so, it verifies that the web client is the true creator of the message and that the message has not been tampered with during transport.
It can be used for:
- Authentication and resource access restriction
- Access throttling
- Collecting usage statistics
- and much, much more
Just like in traditional API token or OAuth system, a server expects to verify the the client has permission to access a resource such as a URL endpoint. However, with this system the client can also know if the server is the true creator of the HTTP response and that the message has not been tampered with during transport. Therefore this system creates two-way security for web applications.
How Traditional API Authorization Works
With API tokens, OAuth and JWT, the server creates a token that is given to the client. The client must store the token and send it to the server with each subsequent request that is verified by the server. If the client loses the token, it no longer has access to the resource. If another client else gains access to the token, the other client can access the resource as if they are the owner of the token.
How Key-Pair Authorization Works
With this HTTP key-pair authorization, the client generates a public key and private key. The private key is stored locally but does not need to be sent across the network. The public key is sent one time to the server, where it is stored and given an ID. This id is shared with the client. From there, only the public key ID is used to communicate about the client's public key.
When the client accesses a resource from a server, it makes a list of HTTP headers which will be used to create a cryptographic signature. This signature is signed using the client's private key and the list of headers is sent as a part of the signature. The server sends this list and the key ID it received when it registered its public key with the server in the Authorization HTTP header. The server then uses these same headers to verify the signature using the stored public key for that client.
Furthermore, the client can create a hash digest of the message body. The server can verify the hash to know that the message has not been altered since it was created. It can incorporate the digest in the signature to further verify that the digest has not been altered and that the creator of both the digest and the HTTP message body is the client.
This system has the added benefit of being able to work the other way around. It ensures that, once a server's public key is registered in a client application, all subsequent HTTP responses originated from the server.
For full documentation visit drf-keypair-permissions.readthedocs.io.
Why this library exists
This Django module was created to give "Cavage" HTTP Signatures capabilities to the Django Rest Framework.
This enables HTTP authorization based on public key/private key encryption as an alternative to session cookies or API tokens.
In your Django code, it looks like this:
from keypair_permissions.permissions import HasHttpCryptoAuthorization
class EchoServerApiView(GenericApiView):
permission_classes = [HasHttpCryptoAuthorization]
def get(self, request):
return Response(request.body)
Doing so will require an Authorization
HTTP header that looks like this:
HTTP/1.1 POST /foo
Authorization: Signature algorithm="hs2019",keyId="keyname",signature="MEUCIGGB0P3P/iZCzCbX1fj1Q6AbYPJr9dEBYcsuiLoS3q6uAiEAkEjvmWfuN1UDPmYCkBywnI/MwisCuNEmlAxPB3ZBVgc="
... other headers ...
This authorization header is created by signing Request headers with a private key on the client. The server then verifies the Request was sent by a known client by verifying the signature using the client's public key.
Additionally, a Digest
header can be added to ensure the Request body was transported in tact:
Digest: SHA512=WZDPaVn/7XgHaAy8pmojAkGWoRx2UFChF41A2svX+TaPm+AbwAgBWnrIiYllu7BNNyealdVLvRwEmTHWXvJwew==
Each public key can be associated with a Django User, so the User can be accessed from the View:
class EchoServerApiView(GenericApiView):
permission_classes = [HasHttpCryptoAuthorization]
def get(self, request):
user = request.public_key.user
return Response(request.body)
For more information see Draft Cavage HTTP Signatures 12
Using a NodeJS or JavaScript client? Try the client-http-keypair-authorization-headers library.
Quickstart
Install:
$ pip install drf-keypair-permissions
Add keypair_permissions
to your settings.INSTALLED_APPS
:
settings.py
:
INSTALLED_APPS = [
...
'keypair_permissions',
]
Migrate the database
$ ./manage.py makemigrations
$ ./manage.py migrate
Include to your project
views.py
:
from keypair_permissions.permissions import HasHttpCryptoAuthorization
Set the permission_classes
of API views to include HasHttpCryptoAuthorization
:
class EchoServerApiView(GenericApiView):
permission_classes = [HasHttpCryptoAuthorization]
def get(self, request):
return Response(request.body)
Or use across your entire API by setting REST_FRAMEWORK['DEFAULT_PERMISSION_CLASSES']
:
REST_FRAMEWORK = {
'DEFAULT_PERMISSION_CLASSES': [
'keypair_permissions.permissions.HasHttpCryptoAuthorization',
]
}
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for drf-keypair-permissions-1.0.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | ffd8dc363717f0e8c64c1729354e63fc4d49bd9f95572b33deff4452b0bca0cd |
|
MD5 | fd3b3421eba8136ad912f31a6d2d204d |
|
BLAKE2b-256 | c5a0327a2d706703949071c0169a1c432646cb6f08737db88e3ab199c1d42a2b |
Hashes for drf_keypair_permissions-1.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 86984f91b979b35ad3de255bda6a307ada1d23d5edcaa6198f7c9428caa055b3 |
|
MD5 | d481eea9412292617698475503bbee73 |
|
BLAKE2b-256 | d81a7ca9c3a8158c3491e8ea1250b3adf0d7f4ae103ea6090496253fd2441a46 |