Django Encrypted Model Fields
About
This library allows you to specify specific fields to encrypt in your Django models using Vault's API in a transparent manner, taking advantage of Vault's advanced capabilities. This helps you:
- Achieve compliance with various privacy standards
- Implement TTL or expiration for data
- Get Masked or transformed versions of your data
- Rely on Vault's permission model
This is a fork of https://gitlab.com/lansharkconsulting/django/django-encrypted-model-fields which in turn is a fork of https://github.com/foundertherapy/django-cryptographic-fields. It has been renamed, and updated to support encryption through Piiano Vault's API.
Note:
Actively tested with Python 3.11.5. Should work with any Python 3.x. This package is compatible with Vault version 1.15.1. For a Vault client compatible with other versions of Vault, check other versions of this package.
Usage
First install the library:
pip install django-encryption
Add to your settings.py (Example in here):
VAULT_ADDRESSVAULT_API_KEYVAULT_DEFAULT_COLLECTIONNote it is best practice to provideVAULT_ADDRESSandVAULT_API_KEYvia environment variables in production- Add
django_encryptiontoINSTALLED_APPS
In your models.py (Example in here):
- Import any desired field type, for example:
from django_encryption.fields import EncryptedCharField
-
For each model field you would like to encrypt, replace the field name with any of the fields you imported in step 1 (For example,
EncryptedCharField).You can customize the field by providing additional parameters such as:
encryption_type(optional) - Can beEncryptionType.randomizedorEncryptionType.deterministicexpiration_secs(optional) - An integer or None. If an integer, the number of seconds before the encrypted data is expired, and cannot be decrypted anymore. Works only with randomizedencryption_typevault_collection(optional) - The name of the vault collection that this field is related to. Defaults tosettings.VAULT_DEFAULT_COLLECTIONvault_property(optional) - The name of the property in the vault collection that this field is related to. Defaults to the name of the field in django.data_type_name(optional) - The name of the data type in vault. Defaults to 'string'. This only has impact when generating a vault migration, and does not change the way your django model would behave.eager(default: true) - whether or not value will be decrypted (in a batch operation) as soon as it is fetched from the DB. If not, the value will be decrypted the first time it is accessed.
Note: use
vault_collectiontogether withvault_propertyto specify the collection and property in vault that represent this field. This is important for permission control and audit logs. For more advanced use-cases, this would allow you to transition smoothly to using Vault as a secure storage for PII data.
Query your model as usual, keeping the following in mind:
- Read queries are batched. Reading from the Database will generate a single API call per field. Writing to the Database is not batched and will generate an API call for each field in each instance.
- By default all fields are eagerly fetched - similarly to calling prefetch_related(field_name) on a foreign key.
The SDK also supports masking and other vault transformations by using mask(MyModel.my_field) or transform('transformation-name', MyModel.my_field) as part of the query.
- This tells the encryption SDK to mask the values of MyModel.my_field. So for example, for an SSN you would get "*--6789".
- All vault's supported transformations are also supported using the
transformcontext manager. See Built-in transformations in Vault's API documentation for a list of Vault's supported transformations.
Sample code
from django.db import models
from django_encryption.fields import EncryptedCharField, EncryptedEmailField, EncryptedDateField, EncryptionType
class Customer(models.Model):
name = EncryptedCharField(data_type_name='NAME')
email = EncryptedEmailField(data_type_name='EMAIL')
phone = EncryptedCharField(
data_type_name='PHONE_NUMBER', null=True, blank=True)
ssn = EncryptedCharField(
encryption_type=EncryptionType.randomized, data_type_name='SSN', null=True, blank=True)
dob = EncryptedDateField(
data_type_name='DATE_OF_BIRTH', null=True, blank=True)
state = models.CharField(max_length=100, null=True, blank=True)
You can see a full working example in our sample.
Installation for local development (with VSCode)
- Clone the repo:
git clone https://github.com/piiano/vault-python - Ensure you have python poetry installed on your machine (a global installation). Example:
pipx install poetry - Run the following commands from the
sdk/orm-djangodirectory:poetry install poetry shell code .
- To run tests:
python manage.py test. Tests should also be available from within vscode.
NOTE Make sure you have a local copy of vault running on your machine. To do so, follow the Installations Instructions.
1 maintainer
Metadata
1 maintainer
Release files for django-encryption 0.3.48
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 | |
|---|---|---|---|---|
| django_encryption-0.3.48.tar.gz | 13.0 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| django_encryption-0.3.48-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 25.2 kB
Release files / django_encryption-0.3.48.tar.gz
| Download URL | django_encryption-0.3.48.tar.gz |
|---|---|
| Size | 13.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b3e23043369d79d920d9d52b2f6f7adebb817bd50a9f9cc29492571f96f79820
|
|
BLAKE2b-256 checksum How to use checksums |
5456299f7a70df8c569cfae51e3e63e20f0ea8b4f9d09d4e69c3f1f33ce131a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.1 CPython/3.12.3 Linux/6.8.0-1021-azure
|
Release files / django_encryption-0.3.48-py3-none-any.whl
| Download URL | django_encryption-0.3.48-py3-none-any.whl |
|---|---|
| Size | 12.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
062c91808743ccb38e8b794c449b857dc3899c87e262db8ef5011c219cb95919
|
|
BLAKE2b-256 checksum How to use checksums |
68126c74204dde5bbe8f11007e61e01ecaa1c650381b86561600e48c18e1e704
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.1.1 CPython/3.12.3 Linux/6.8.0-1021-azure
|
Security for django-encryption 0.3.48
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.
