django-encryption-suite
Copyright 2026 J. Randall Emery. Licensed under the Apache License, Version 2.0.
django-encryption-suite aims to be a general tool to help you:
- isolate groups of users who share data
- define subsets of data that require extra protection
- use key management systems (KMS)
- manage keys through their lifecycle
- encrypt and decrypt data and files
- search encrypted data
It encrypts data in silos, groups of data that share key isolation. A silo is usually one of the groups of users your project defines, such as teams or tenants, each with its own keys; it is the operation that motivated the development of this project. A silo can also be a single user, or the one system silo for system-wide encryption of data that no group of users scopes. A key set binds the adapter that resolves silos to the key store that holds their key encryption keys, and each encrypted field names its key set.
It gives you the flexibility to choose which fields should be encrypted with new model fields and mixins, whether to have one or more key encryption keys (KEKs) on a key management system, whether those keys can be created (provisioned) automatically, and how narrowly to define the groups that share encrypted information.
It works with any database or storage backend, and performs the actual
encryption and decryption through a pluggable crypto backend. The
default backend is built on pyca/cryptography;
Google Tink is available as an
alternative via the [tink] extra.
Using django-encryption-suite involves:
- configuring pluggable adapters and options for isolating users, working with KMSs, and using encryption backends
- configuring system-wide keys
- connecting and testing connections to your KMS
- creating key encryption keys on your KMS (manually or automatically)
- updating your model fields
- migrating your data (for existing projects)
- rotating keys on your KMS periodically
Motivation
This package aims to support the scenario where you have a small group of people sharing sensitive data and files, reviewing them, and working with them online. Think about sharing the documents you would need to apply for a passport or a bank loan, or to make an insurance claim.
End-to-end encryption is one solution. This approach requires encrypting and decrypting data on a device, which on the positive side can support zero-knowledge solutions with a provider. The downside is that your data then becomes tied to a user's device. Imagine you have a small business helping people work with sensitive data, and a staff member who works with you and then leaves. Yes, you can rent or buy them a laptop and have it wiped automatically when they leave, but a lot of small businesses don't have the technical infrastructure to support that.
Server-side encryption with a single key, at the database or field level, is another possible solution. Several existing packages support this approach, and this package offers field-level encryption with a single system-wide key as well, but with a narrow use in mind: for encrypting information that must be available across groups of people (think login IDs).
The main focus is an easy-to-use solution that lets you both encrypt data and isolate encrypted data for groups of users using group-specific keys.
Beyond partitioning data by groups of users, this package provides adapters for industry-grade key management systems on popular cloud providers to support envelope encryption, where a key or set of keys is stored on a KMS, and those keys encrypt (or wrap) the keys you use to encrypt and decrypt data (also known as data encryption keys, or DEKs). Using a KMS means that the key encryption keys (KEKs) reside only in the KMS, and the DEKs are generated on the fly and kept only in memory.
Features
- Envelope encryption for model fields using authenticated encryption (AEAD)
EncryptedFileFieldfor encrypted file uploads with opaque on-disk names and an encrypted display-name column; works with any Django storage backend (S3, Azure, GCS, local disk), encrypting file contents with streaming AEAD- Crypto backend adapters: the local data-plane engine that generates
the DEK and performs field (AEAD) and file (streaming AEAD)
encryption/decryption — pyca/cryptography by default (a core
dependency), or Google Tink via the
[tink]extra; selected with theCRYPTO_BACKENDsetting - KMS adapters: GCP Cloud KMS, AWS KMS, Azure Key Vault, HashiCorp Vault, IBM Key Protect / HPCS, Oracle OCI Vault, Infisical, Fly.io KMS, and a system key alternative
- Keyless cross-cloud auth: any KMS provider that supports OIDC (AWS,
GCP, Azure, Vault, Infisical) can be reached via a pluggable OIDC
token source (Fly.io, file-based for Kubernetes / IRSA / Azure Workload
Identity / Nomad, GCP metadata, Vercel, SPIFFE) — pair any source with
any provider that exposes an OIDC-based auth method (AWS STS
AssumeRoleWithWebIdentity, GCP Workload Identity Federation, Azure AD federated credentials, Vault JWT auth, Infisical OIDC auth) - Key sets, chosen per field with
key_set: each one binds a silo adapter to a key store in theKEY_SETSsetting. A field withoutkey_set=will use thedefaultkey set. - Silo adapters, which cover:
- groups of users: SaaS Pegasus teams, django-tenants, a generic model-based adapter for your own team or organization model, composite (mixed tenant/cell KEKs), and an optional ready-made team app for projects with no team model of their own
- individual users:
ActingUserSiloAdapterencrypts under the acting user's keys, andActingUserOrOwnerSiloAdapteralso lets a write with nobody acting use the keys of the user who owns the row - the whole system: the built-in
systemkey set, one silo for columns that no group of users scopes, such as a user's email address or username, withkey_set="system"on any encrypted field
- Key stores: a KMS store (
KMS_KEY_STORES) wraps keys on a key management service, and an env store (ENV_KEY_STORES) wraps them locally under key material from your settings. Each key set names its store, so a project can put team data on a KMS and thesystemkey set on an env store, where signing in does not depend on an external KMS - An optional blind index on any encrypted column,
blind_index=True, which keeps it searchable by exact value and holds its plaintext unique; the digest comes from the index key of the column's silo in its key set, such as the system silo for akey_set="system"column
Quickstart
A local setup: a key held in settings in place of a KMS, files on local disk,
and teams managed in the Django admin by the optional simpleteams app, with
one team per user. It is for development only; see
Moving to production for a real KMS.
Install the package:
uv add django-encryption-suite
Generate one key and set it in your environment as ENC_LOGIN_KEK. It wraps every
key in this setup: each team's data keys, and the system silo's, which encrypt each
team's name:
openssl rand -base64 32
Configure settings.py, reading the key from the environment:
import os
INSTALLED_APPS = [
# ...
"django.contrib.admin",
"django.contrib.auth",
"encryption_suite",
"encryption_suite.contrib.simpleteams",
"yourapp",
]
MIDDLEWARE = [
# ...
"django.contrib.auth.middleware.AuthenticationMiddleware",
"encryption_suite.contrib.simpleteams.middleware.SimpleTeamSiloMiddleware",
]
ENCRYPTION = {
# The env key store: no external service, one key for every team.
"ENV_KEY_STORES": {"login": {"KEKS": {1: os.environ["ENC_LOGIN_KEK"]}}},
# The default key set: one silo per team, its keys wrapped by the "login" store.
# The built-in system key set uses the only configured store.
"KEY_SETS": {
"default": {
"silo": "encryption_suite.contrib.simpleteams.adapter.SimpleTeamSiloAdapter",
"key_store": "login",
},
},
}
STORAGES = {
"default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
"staticfiles": {"BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage"},
"encrypted": {
"BACKEND": "django.core.files.storage.FileSystemStorage",
"OPTIONS": {"location": "var/encrypted-files"},
},
}
Every team's key wraps under the one ENV_KEY_STORES entry. That suits a first run
on a work station; for a real KMS, see
KMS adapters.
Add a model that points at its team:
# yourapp/models.py
from django.db import models
from encryption_suite.contrib.simpleteams.models import SimpleTeam
from encryption_suite.fields import EncryptedCharField, EncryptedFileField
class Patient(models.Model):
team = models.ForeignKey(SimpleTeam, on_delete=models.PROTECT)
pseudonym = models.CharField(max_length=100) # plaintext, queryable
first_name = EncryptedCharField(max_length=100) # encrypted at rest
scan = EncryptedFileField(display_name_field="scan_name", null=True, blank=True)
scan_name = EncryptedCharField(max_length=255, null=True, blank=True)
Optional encrypted fields take null=True alongside blank=True; an
encrypted column cannot hold the empty string.
Migrate, create a superuser, and start the server:
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver
In the admin, add a team under Simple teams and add yourself as a member.
Requests you make while signed in then run with that team as the current
silo. Check a round trip from python manage.py shell, where no request sets
the team, so you set it yourself:
from encryption_suite.adapters.silos.context import override_current_silo
from encryption_suite.contrib.simpleteams.models import SimpleTeam
from yourapp.models import Patient
team = SimpleTeam.objects.get(name="Acme")
with override_current_silo(team):
patient = Patient.objects.create(team=team, pseudonym="p-1", first_name="Jane")
Patient.objects.get(pk=patient.pk).first_name # 'Jane'
The first_name column in the database holds ciphertext. From here,
Getting started adds the admin's key pages and test
console, Encrypted data covers the field types and
working with encrypted values, and
Serving encrypted files covers downloads.
Documentation
Full documentation starts at docs/index.md: a getting started guide, provider-specific setup guides, encrypted fields and files, the admin panel, KEK strategies, silo adapters, key rotation, system-wide encryption, blind indexes, management commands, and a configuration reference. To find your way around the source, see Understanding the code base.
Metadata
Release files for django-encryption-suite 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| django_encryption_suite-1.0.0.tar.gz | 1.7 MB | With provenance | Details for django_encryption_suite-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| django_encryption_suite-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for django_encryption_suite-1.0.0-py3-none-any.whl |
Total release size: 2.7 MB
Release files / django_encryption_suite-1.0.0.tar.gz
| Download URL | django_encryption_suite-1.0.0.tar.gz |
|---|---|
| Size | 1.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
db0dc714d77e137545755b6984ae348c2d38ab7de21a15cfb056cf67c47c9438
|
|
BLAKE2b-256 checksum How to use checksums |
96539dc6d35ed39a879cc2622c8b6e07195c566f9ebad9b5005dd39bf19a7da3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logRelease files / django_encryption_suite-1.0.0-py3-none-any.whl
| Download URL | django_encryption_suite-1.0.0-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d0babbb2e1d360813f5ab438a1860761ec47c68e77c201f6e02670cf551dbb59
|
|
BLAKE2b-256 checksum How to use checksums |
801cbe32e91ba28eab2c6b083cea45f36ec315d20c5904f3d19c432e6669f4b4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logSecurity for django-encryption-suite 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for django_encryption_suite-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.