shopcloud-django-encrypted-fields

Transparently encrypted Django model fields, backed by Fernet (AES-128-CBC + HMAC-SHA256) from cryptography.

The value is encrypted on its way into the database and decrypted on its way out. Everything in between — forms, DRF serializers, model_to_dict, templates — sees the plaintext, so existing code keeps working unchanged.

from shopcloud_django_encrypted_fields import EncryptedCharField

class Credential(models.Model):
    title = models.CharField(max_length=255)
    password = EncryptedCharField(max_length=255, null=True, blank=True)

>>> Credential.objects.create(title="GitHub", password="hunter2").password
'hunter2'
>>> # what the database actually holds:
'gAAAAABm...T7Q=='

Installation

pip install shopcloud-django-encrypted-fields

Generate a key and put it in the environment:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

# settings.py
DJ_ENCRYPTED_FIELDS = {
    "KEYS": [os.environ["ENCRYPTION_KEY"]],   # newest key first
    "READ_PLAINTEXT": True,                   # see "Migrating existing data"
}

The app is not added to INSTALLED_APPS — there is nothing to install, only fields to import.

Field types

Any other text-backed field is three lines:

from shopcloud_django_encrypted_fields import EncryptedMixin

class EncryptedURLField(EncryptedMixin, models.URLField):
    pass

What this protects against

Database dumps, backups in a bucket, direct Cloud SQL access, and anyone reading rows who is not the application. It does not protect against a compromised application instance: the key is in the app's environment, because the app has to show the value to the user. That is a deliberate trade-off, not an oversight — genuine zero-knowledge (key derived from the user's password, crypto in the browser) rules out shared credentials and SSO, and is a different product.

Consequences you have to plan for

Filtering is impossible. Fernet is non-deterministic — the same plaintext encrypts to a different token every time — so filter(password="hunter2") could never match. Rather than silently returning an empty queryset, every lookup except isnull raises FieldError:

>>> Credential.objects.filter(password="hunter2")
FieldError: Lookup 'exact' is not supported on EncryptedCharField — the stored
value is a non-deterministic ciphertext and would never match.

If you need to search a value, keep a separate searchable column (a blind index, or a hash) next to the encrypted one.

The column becomes TEXT. A Fernet token is roughly twice the length of its plaintext, so varchar(255) would truncate. get_internal_type() returns "TextField" for every encrypted field. max_length keeps validating the plaintext in forms.

A wrong key raises, it never renders. A value that looks like a Fernet token but cannot be opened by any configured key raises DecryptionError — in every mode, including while READ_PLAINTEXT is on. The alternative would be worse than an error page: the raw token would reach the view as if it were the secret, and saving that form would encrypt the ciphertext a second time, destroying the original value. Plaintext rows are told apart from tokens structurally, so the migration fallback still works.

>>> Credential.objects.get(pk=1).password
DecryptionError: Value is a Fernet token but no configured key decrypts it.
Check DJ_ENCRYPTED_FIELDS['KEYS'] — a retired key has to stay in the list
until everything it wrote has been rotated.

A missing or malformed key is reported by manage.py check (encrypted_fields.E001), so it fails the deploy rather than the first user who opens a record.

Never assign a database expression. update(field=F("other")) is compiled straight to SQL, so no field hook runs and the value lands in the column as plaintext — silently. Django offers nothing to intercept this from inside a field. Assign the value in Python and call save(); update() with a literal and bulk_create() both encrypt correctly.

No database-side uniqueness or ordering. unique=True compares ciphertexts, which are always different. order_by sorts ciphertexts, which is meaningless.

Migrating existing data

While READ_PLAINTEXT is True (the default), rows that are not encrypted yet are read as-is. That makes the switch a normal deploy instead of a maintenance window:

1. Change the field type and run makemigrations / migrate — this only widens the column to TEXT, the data stays untouched.

2. Backfill. Reading gives plaintext, saving writes ciphertext, so this is all it takes:

   for obj in Credential.objects.all().iterator():
       obj.save(update_fields=["password"])
   

3. Set READ_PLAINTEXT: False. From then on an undecryptable value raises instead of being handed out as plaintext — which is what you want, because after the backfill it means the key is wrong, not that the row is old.

Key rotation

KEYS is a list, newest first. Every key in it can decrypt; only the first one encrypts. So rotating is: prepend the new key, deploy, re-encrypt, drop the old key.

from shopcloud_django_encrypted_fields import rotate
# re-encrypts a token with the newest key without exposing the plaintext

Keep the retired key in the list until the backfill has run — a token it wrote is unreadable without it.

Performance

Measured on 2000 rows, SQLite, Python 3.14:

For a single credential the crypto is far below the 1–5 ms of one Cloud SQL round trip — it does not show up in a request. It only becomes visible on list views that load every row, and there it is avoidable: list serializers usually do not output the secret anyway, so exclude the column from the query.

queryset = Credential.objects.defer("password", "otp_secret")

The Fernet instance is cached on the key tuple, so the key is not rebuilt per value.

Development

pip install -e ".[dev]"
pytest tests/
tox            # Python 3.12/3.13 x Django 5.0-6.0

License

MIT — Talk-Point GmbH