Metadata-Version: 2.4
Name: django-pgcrypto
Version: 3.0.3
Summary: Python and Django utilities for encrypted fields using pgcrypto.
Project-URL: Repository, https://github.com/dcwatson/django-pgcrypto
Author-email: Dan Watson <dcwatson@gmail.com>
License: BSD-2-Clause
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Requires-Python: >=3.8
Requires-Dist: cryptography
Description-Content-Type: text/markdown

![CI](https://github.com/dcwatson/django-pgcrypto/workflows/CI/badge.svg)

# django-pgcrypto

A set of utility functions for dealing with ASCII Armor (http://www.ietf.org/rfc/rfc2440.txt) and padding, and a collection of Django field classes that utilize these functions in a way that is compatible with pgcrypto functions.

## Installation

`pip install django-pgcrypto`

## Quickstart

There are several encrypted versions of Django fields that you can use (mostly) as you would use a normal Django field:

```python
from django.db import models
import pgcrypto

class Employee (models.Model):
    name = models.CharField(max_length=100)
    ssn = pgcrypto.EncryptedTextField()
    pay_rate = pgcrypto.EncryptedDecimalField()
    date_hired = pgcrypto.EncryptedDateField(key="datekey", auto_now_add=True)
```

If not specified when creating the field (as in `ssn` and `pay_rate` above), fields are encrypted according to the following settings:

* `PGCRYPTO_DEFAULT_CIPHER` (only `aes` is currently supported) - The default algorithm to use when encrypting fields.
* `PGCRYPTO_DEFAULT_KEY` (default: `settings.SECRET_KEY`) - The default key to use for encryption.

You must also make sure the pgcrypto extension is installed in your database. Django makes this easy with a [CryptoExtension](https://docs.djangoproject.com/en/dev/ref/contrib/postgres/operations/#cryptoextension) migration.

## Querying

It is possible to filter on encrypted fields as you would normal fields via `exact`, `gt`, `gte`, `lt`, `lte`, `contains`, `icontains`, `startswith`, `istartswith`, `endswith`, and `iendswith` lookups. For example, querying the model above is possible like so:

```python
Employee.objects.filter(date_hired__gt="1981-01-01", salary__lt=60000)
```

## Caveats

This library encrypts and encodes data in a way that works with pgcrypto's [raw encryption functions](https://www.postgresql.org/docs/current/pgcrypto.html#id-1.11.7.34.8). All the warnings there about using direct keys and the lack of integrity checking apply here.

This library also predates Django's [BinaryField](https://docs.djangoproject.com/en/dev/ref/models/fields/#binaryfield), which is why the fields are essentially `TextField`s that store armored encrypted data. This may or may not be ideal for your application, and a hypothetical future version might include a switch to store binary data.
