Django Fernet Encrypted Fields

0.4.0 · active · verified Thu Apr 16

django-fernet-encrypted-fields provides symmetrically encrypted model fields for Django, leveraging Fernet encryption from the `cryptography` library. It ensures that data is encrypted before being stored in the database and automatically decrypted when accessed in the application. This library is actively maintained as part of the Jazzband project, with recent updates and a focus on security for sensitive data at rest.

Common errors

```
InvalidToken / Cannot decrypt data
```
cause The encryption key (`SALT_KEY` or `SECRET_KEY`) used to decrypt the data is different from the key used to encrypt it, or the data has been corrupted.

fix Verify that your `SALT_KEY` (or `SECRET_KEY`) in `settings.py` or environment variables matches the key used when the data was originally saved. Ensure no data corruption occurred. For key rotation, ensure all valid keys are provided in the `SALT_KEY` list or `SECRET_KEY_FALLBACKS` (Django >= 4.1).
```
django.core.exceptions.ImproperlyConfigured: EncryptedField cannot be indexed.
```
cause An `EncryptedField` (or its subclasses) has `db_index=True`, `unique=True`, or `primary_key=True` set.

fix Remove `db_index=True`, `unique=True`, and `primary_key=True` from the `EncryptedField` definition in your model. Encrypted data is not suitable for these database constraints.
```
incorrect padding
```
cause The Fernet key provided (either `SALT_KEY` or `SECRET_KEY` if `SALT_KEY` is not used) is not a valid 32-bit URL-safe base64-encoded bytestring, or the data is corrupted. This can happen if `FERNET_USE_HKDF = False` (from related libraries) and the key is not correctly formatted.

fix Ensure your `SALT_KEY` (or `SECRET_KEY`) is a correctly generated Fernet-compatible key. When `SALT_KEY` is used, the library handles the HKDF derivation, so ensure `SALT_KEY` is a strong, random string. If manually managing Fernet keys (not common with this library), generate them using `Fernet.generate_key()` from `cryptography`.
```
Data too long for field (e.g., 'value too long for type character varying(X)')
```
cause Encrypted data is typically longer than the original plaintext. The `max_length` of the underlying `CharField` might be insufficient.

fix Increase the `max_length` attribute for `EncryptedCharField` instances to accommodate the increased size of encrypted data. `EncryptedTextField` does not have a `max_length` limit, making it suitable for longer encrypted strings.

Warnings

breaking Changing an existing unencrypted field to an encrypted field, or vice-versa, requires a complex three-step data migration: add a new field (nullable), copy data using a data migration (which encrypts/decrypts), then remove the old field and optionally rename the new one. Direct field type changes in `models.py` will result in data loss or unreadable data.
Fix: Follow the three-step data migration process: 1. Add new encrypted field with a different name and `null=True`. 2. Create a data migration to copy values from old to new field. 3. Remove the old field and rename the new field if desired.
gotcha Fernet encryption is non-deterministic, meaning the same plaintext encrypts to a different ciphertext each time. This makes encrypted fields unsuitable for database indexing (`db_index=True`, `unique=True`, `primary_key=True`), lookups (other than `isnull`), or meaningful ordering, as these operations would be performed on the unhelpful ciphertext. Setting `db_index=True`, `unique=True`, or `primary_key=True` will raise a `django.core.exceptions.ImproperlyConfigured` error.
Fix: Avoid using `db_index=True`, `unique=True`, or `primary_key=True` on `EncryptedField` instances. Design your schema such that lookups and indexing are performed on unencrypted, non-sensitive fields.
breaking Loss of the `SALT_KEY` (or `SECRET_KEY` if `SALT_KEY` is not set) will render all encrypted data irrecoverable. The security of your encrypted data is entirely dependent on the secrecy and retention of this key.
Fix: Store `SALT_KEY` in a secure environment variable or secrets management system. Implement robust backup procedures for your keys. For key rotation, use `SALT_KEY` as a list of keys, or `SECRET_KEY_FALLBACKS` (Django >= 4.1) for `SECRET_KEY` rotation.
gotcha Nullable encrypted fields (`null=True`) trivially reveal the presence or absence of data to an attacker. If this is a concern, avoid nullable encrypted fields.
Fix: For sensitive fields, consider making them non-nullable and storing a 'sentinel' empty value (which will be encrypted) instead of `None`.
gotcha When deploying to platforms like Heroku, explicit pinning of `cryptography` and its underlying C library `libffi` might be required in `requirements.txt` to ensure proper build and deployment.
Fix: Ensure `cryptography` is explicitly listed in `requirements.txt` with a version pin. Run `pip freeze > requirements.txt` after installing all dependencies in a clean virtual environment.

Install

pip install django-fernet-encrypted-fields Install via pip

Imports

EncryptedCharField

from encrypted_fields.fields import EncryptedCharField

EncryptedTextField

from encrypted_fields.fields import EncryptedTextField

EncryptedIntegerField

from encrypted_fields.fields import EncryptedIntegerField

EncryptedEmailField

from encrypted_fields.fields import EncryptedEmailField

* (wildcard import)
wrong:
```
from encrypted_fields.fields import *
```
correct:
```
from encrypted_fields.fields import EncryptedTextField
```
While functional, wildcard imports are generally discouraged for clarity and to prevent namespace pollution.
EncryptedTextField (from old package)
wrong:
```
from fernet_fields import EncryptedTextField
```
correct:
```
from encrypted_fields.fields import EncryptedTextField
```
This import path belongs to an older, different package (`django-fernet-fields`) and will not work with `django-fernet-encrypted-fields`.

Quickstart

To get started, install the library and configure your `settings.py` with a `SALT_KEY` (or rely on `SECRET_KEY` as a fallback, which is less secure for specific field encryption). Define your model with an `EncryptedTextField` or other provided encrypted field types. Data will be automatically encrypted and decrypted during save and retrieve operations. Remember to run `makemigrations` and `migrate`.

import os
from django.db import models
from encrypted_fields.fields import EncryptedTextField

# In your Django settings.py file, define SALT_KEY
# For production, load from environment variables and ensure it's a strong, random string.
# Example for settings.py (not for production directly):
# import os
# os.environ.setdefault('DJANGO_SALT_KEY', '0123456789abcdefghijklmnopqrstuvwxyz')
SALT_KEY = os.environ.get('DJANGO_SALT_KEY', 'a_default_32_char_salt_key_for_dev')
# For Django >= 4.1, you can also use SECRET_KEY_FALLBACKS for SECRET_KEY rotation.
# SECRET_KEY_FALLBACKS = [os.environ.get('OLD_DJANGO_SECRET_KEY', '')]

class MyEncryptedModel(models.Model):
    sensitive_data = EncryptedTextField()
    name = models.CharField(max_length=255)

    def __str__(self):
        return self.name

# Example usage (assuming Django setup and migrations are run):
# from myapp.models import MyEncryptedModel
# instance = MyEncryptedModel.objects.create(name='Test User', sensitive_data='This is a secret message.')
# print(instance.sensitive_data) # Automatically decrypted: 'This is a secret message.'
# print(instance.pk)

view raw JSON →