Django Cryptography

1.1 · active · verified Thu Apr 16

django-cryptography simplifies encrypting data within Django models and applications. It provides encrypted model fields and utilities based on the `cryptography` library. The current version is 1.1, with releases occurring periodically to maintain compatibility with Django and the underlying `cryptography` library.

Common errors

```
django.core.exceptions.ImproperlyConfigured: The DJANGO_CRYPTOGRAPHY_KEY setting must be configured.
```
cause The `DJANGO_CRYPTOGRAPHY_KEY` setting is not found or is an empty string in your Django `settings.py`.

fix Set `DJANGO_CRYPTOGRAPHY_KEY = os.environ.get('DJANGO_CRYPTOGRAPHY_KEY')` in your `settings.py` and ensure the `DJANGO_CRYPTOGRAPHY_KEY` environment variable is set with a valid base64-encoded Fernet key. Example: `export DJANGO_CRYPTOGRAPHY_KEY="$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"`.
```
cryptography.fernet.InvalidToken: Token is not URL-safe base64-encoded
```
cause The `DJANGO_CRYPTOGRAPHY_KEY` is not a correctly formatted base64-encoded Fernet key, or the encrypted data itself is corrupted/invalid.

fix Verify that your `DJANGO_CRYPTOGRAPHY_KEY` is exactly as generated by `Fernet.generate_key().decode()`. If the key is correct, the data itself might be corrupted or encrypted with a different key. Ensure the same key is used for encryption and decryption.
```
ModuleNotFoundError: No module named 'django_cryptography'
```
cause The `django-cryptography` package is not installed or not added to your `INSTALLED_APPS`.

fix First, ensure it's installed: `pip install django-cryptography`. Second, add `'django_cryptography'` to your `INSTALLED_APPS` list in `settings.py`.
```
AttributeError: 'module' object has no attribute 'KeyGeneratingEncryptedField'
```
cause You are trying to import `KeyGeneratingEncryptedField`, which was removed in version 1.0 of `django-cryptography`.

fix Remove any references to `KeyGeneratingEncryptedField` from your models and code. Manage your encryption key explicitly via the `DJANGO_CRYPTOGRAPHY_KEY` setting.

Warnings

breaking Version 1.0 introduced significant breaking changes to key management. The `KEY_NAME` and `KEY_STORE` settings were removed, and the `DJANGO_CRYPTOGRAPHY_KEY` setting (loaded from an environment variable) became the sole method for providing the encryption key.
Fix: Migrate your key management to use the `DJANGO_CRYPTOGRAPHY_KEY` environment variable. Generate a new Fernet key if you were using the old key generation methods, and update your `settings.py`.
breaking The `KeyGeneratingEncryptedField` was removed in version 1.0, simplifying the API by making key management an application-level concern via settings.
Fix: Remove `KeyGeneratingEncryptedField` usage from your models. Ensure `DJANGO_CRYPTOGRAPHY_KEY` is properly configured in your settings. If you need to generate a key, do so manually using `Fernet.generate_key()`.
gotcha The `DJANGO_CRYPTOGRAPHY_KEY` must be a valid base64-encoded Fernet key. If it's missing, malformed, or doesn't match the key used for encryption, data will not be encrypted/decrypted correctly, leading to `InvalidToken` errors.
Fix: Ensure `DJANGO_CRYPTOGRAPHY_KEY` is set correctly in your environment or `settings.py`. A valid key can be generated once with `from cryptography.fernet import Fernet; Fernet.generate_key().decode()`.
gotcha Changing an existing `CharField` or `TextField` to an `EncryptedCharField` or `EncryptedTextField` on a model with existing data requires a data migration to encrypt the old data. A simple `makemigrations` and `migrate` will not automatically encrypt existing plaintext data.
Fix: Manually create a data migration to iterate through existing records, decrypt (if necessary, e.g., if switching encryption libraries), and then re-save the data using the new encrypted field type. This will trigger the encryption on save.

Install

pip install django-cryptography Install stable version

Imports

EncryptedCharField

from django_cryptography.fields import EncryptedCharField

EncryptedTextField

from django_cryptography.fields import EncryptedTextField

encrypt

from django_cryptography.core import encrypt

decrypt

from django_cryptography.core import decrypt

KeyGeneratingEncryptedField
wrong:
```
from django_cryptography.fields import KeyGeneratingEncryptedField
```
correct:
```
N/A (removed in v1.0)
```
This field was removed in version 1.0. For key management, use the DJANGO_CRYPTOGRAPHY_KEY setting.

Quickstart

To get started, install the package, add `django_cryptography` to your `INSTALLED_APPS`, and configure the `DJANGO_CRYPTOGRAPHY_KEY` in your Django settings. This key must be a base64-encoded Fernet key, typically loaded from an environment variable for security. You can then use `EncryptedCharField` or `EncryptedTextField` in your models to automatically encrypt and decrypt data.

import os

# settings.py
INSTALLED_APPS = [
    # ...
    'django_cryptography',
]

# Generate a key once with: `from cryptography.fernet import Fernet; Fernet.generate_key().decode()`
# Set this as an environment variable, e.g., export DJANGO_CRYPTOGRAPHY_KEY='YOUR_GENERATED_KEY'
DJANGO_CRYPTOGRAPHY_KEY = os.environ.get('DJANGO_CRYPTOGRAPHY_KEY', '')


# myapp/models.py
from django.db import models
from django_cryptography.fields import EncryptedCharField

class SecretNote(models.Model):
    title = models.CharField(max_length=100)
    content = EncryptedCharField(max_length=500)

    def __str__(self):
        return self.title

# Example usage in a Django shell or view:
# from myapp.models import SecretNote
# note = SecretNote.objects.create(title='Top Secret', content='This is highly confidential information.')
# print(note.content) # decrypted value
# stored_value = SecretNote.objects.values_list('content', flat=True).get(pk=note.pk) # will be encrypted bytes
# print(f"Stored (encrypted): {stored_value}")

view raw JSON →