<a href="https://piiano.com/pii-data-privacy-vault/">
<img alt="Piiano Vault" src="https://docs.piiano.com/img/logo-developers.svg" height="40" />
</a>
# Django Encrypted Model Fields
[](https://pypi.org/project/django-encryption/)
## 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.0.
For a Vault client compatible with other versions of Vault, check [other versions of this package](https://pypi.org/project/django-encryption/).
## Usage
First install the library:
```commandline
pip install django-encryption
```
Add to your `settings.py` (Example in [here](../../examples/django-encryption-example/vault_sample_django/local_settings_example.py)):
- `VAULT_ADDRESS`
- `VAULT_API_KEY`
- `VAULT_DEFAULT_COLLECTION`
**Note** it is best practice to provide `VAULT_ADDRESS` and `VAULT_API_KEY` via environment variables in production
- Add `django_encryption` to `INSTALLED_APPS`
In your `models.py` (Example in [here](../../examples/django-encryption-example/customers/models.py)):
1. Import any desired field type, for example:
```python
from django_encryption.fields import EncryptedCharField
```
2. 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 be `EncryptionType.randomized` or `EncryptionType.deterministic`
- `expiration_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 randomized `encryption_type`
- `vault_collection` (**optional**) - The name of the vault collection that this field is related to. Defaults to `settings.VAULT_DEFAULT_COLLECTION`
- `vault_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_collection` together with `vault_property` to 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 `transform` context manager. See [Built-in transformations](https://piiano.com/docs/guides/manage-transformations/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](https://github.com/piiano/vault-python/tree/main/examples/django-encryption-example).
## Installation for local development (with VSCode)
1. Clone the repo: `git clone https://github.com/piiano/vault-python`
1. Ensure you have [python poetry](https://python-poetry.org/) installed on your machine (a global installation). Example: `pipx install poetry`
1. Run the following commands from the `sdk/orm-django` directory:
```commandline
poetry install
poetry shell
code .
```
1. 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](https://piiano.com/docs/guides/get-started/).
Raw data
{
"_id": null,
"home_page": "https://github.com/piiano/vault-python",
"name": "django-encryption",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "encryption, django, fields",
"author": "Imri Goldberg",
"author_email": "imri.goldberg@piiano.com",
"download_url": "https://files.pythonhosted.org/packages/63/01/4a46cc2c07962fabb5edf889d9fc16dd9b8acc8b5ca17969a4d546845c30/django_encryption-0.3.47.tar.gz",
"platform": null,
"description": "<a href=\"https://piiano.com/pii-data-privacy-vault/\">\n <img alt=\"Piiano Vault\" src=\"https://docs.piiano.com/img/logo-developers.svg\" height=\"40\" />\n</a>\n\n# Django Encrypted Model Fields\n\n\n\n\n[](https://pypi.org/project/django-encryption/)\n\n## About\n\nThis 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.\nThis helps you:\n\n- Achieve compliance with various privacy standards\n- Implement TTL or expiration for data\n- Get Masked or transformed versions of your data\n- Rely on Vault's permission model\n\nThis is a fork of\n<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\nbeen renamed, and updated to support encryption through Piiano Vault's API.\n\n**Note:**\n\nActively tested with Python 3.11.5. Should work with any Python 3.x.\nThis package is compatible with Vault version 1.15.0.\nFor a Vault client compatible with other versions of Vault, check [other versions of this package](https://pypi.org/project/django-encryption/).\n\n\n## Usage\n\nFirst install the library:\n\n```commandline\npip install django-encryption\n```\n\nAdd to your `settings.py` (Example in [here](../../examples/django-encryption-example/vault_sample_django/local_settings_example.py)):\n\n- `VAULT_ADDRESS`\n- `VAULT_API_KEY`\n- `VAULT_DEFAULT_COLLECTION`\n **Note** it is best practice to provide `VAULT_ADDRESS` and `VAULT_API_KEY` via environment variables in production\n- Add `django_encryption` to `INSTALLED_APPS`\n\nIn your `models.py` (Example in [here](../../examples/django-encryption-example/customers/models.py)):\n\n1. Import any desired field type, for example:\n\n```python\nfrom django_encryption.fields import EncryptedCharField\n```\n\n2. 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`).\n\n You can customize the field by providing additional parameters such as:\n\n - `encryption_type` (**optional**) - Can be `EncryptionType.randomized` or `EncryptionType.deterministic`\n - `expiration_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 randomized `encryption_type`\n - `vault_collection` (**optional**) - The name of the vault collection that this field is related to. Defaults to `settings.VAULT_DEFAULT_COLLECTION`\n - `vault_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.\n - `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.\n - `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.\n\n **Note**: use `vault_collection` together with `vault_property` to 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.\n\nQuery your model as usual, keeping the following in mind:\n\n* 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.\n* By default all fields are eagerly fetched - similarly to calling prefetch_related(field_name) on a foreign key.\n\nThe 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.\n\n- This tells the encryption SDK to mask the values of MyModel.my_field. So for example, for an SSN you would get \"**\\*-**-6789\".\n- All vault's supported transformations are also supported using the `transform` context manager. See [Built-in transformations](https://piiano.com/docs/guides/manage-transformations/built-in-transformations) in Vault's API documentation for a list of Vault's supported transformations.\n\n## Sample code\n\n```\nfrom django.db import models\nfrom django_encryption.fields import EncryptedCharField, EncryptedEmailField, EncryptedDateField, EncryptionType\n\n\nclass Customer(models.Model):\n name = EncryptedCharField(data_type_name='NAME')\n email = EncryptedEmailField(data_type_name='EMAIL')\n phone = EncryptedCharField(\n data_type_name='PHONE_NUMBER', null=True, blank=True)\n ssn = EncryptedCharField(\n encryption_type=EncryptionType.randomized, data_type_name='SSN', null=True, blank=True)\n dob = EncryptedDateField(\n data_type_name='DATE_OF_BIRTH', null=True, blank=True)\n state = models.CharField(max_length=100, null=True, blank=True)\n```\n\nYou can see a full working example in [our sample](https://github.com/piiano/vault-python/tree/main/examples/django-encryption-example).\n\n## Installation for local development (with VSCode)\n\n1. Clone the repo: `git clone https://github.com/piiano/vault-python`\n1. Ensure you have [python poetry](https://python-poetry.org/) installed on your machine (a global installation). Example: `pipx install poetry`\n1. Run the following commands from the `sdk/orm-django` directory:\n ```commandline\n poetry install\n poetry shell\n code .\n ```\n1. To run tests: `python manage.py test`. Tests should also be available from within vscode.\n\n**NOTE** Make sure you have a local copy of vault running on your machine. To do so, follow the [Installations Instructions](https://piiano.com/docs/guides/get-started/).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A set of fields that wrap standard Django fields with encryption provided Piiano Vault.",
"version": "0.3.47",
"project_urls": {
"Homepage": "https://github.com/piiano/vault-python",
"Repository": "https://github.com/piiano/vault-python"
},
"split_keywords": [
"encryption",
" django",
" fields"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "97714b65452e97068b533356bffb723a224dd26a594bac20b6b4bdc0eba8f854",
"md5": "2596b36d3c8e61e6ef0eab83ce18fda6",
"sha256": "d3c7c0af45d253697451eee8d7da5b8deb294f29718bf590aa9128a96de9be7b"
},
"downloads": -1,
"filename": "django_encryption-0.3.47-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2596b36d3c8e61e6ef0eab83ce18fda6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 12237,
"upload_time": "2025-01-20T10:08:08",
"upload_time_iso_8601": "2025-01-20T10:08:08.613839Z",
"url": "https://files.pythonhosted.org/packages/97/71/4b65452e97068b533356bffb723a224dd26a594bac20b6b4bdc0eba8f854/django_encryption-0.3.47-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "63014a46cc2c07962fabb5edf889d9fc16dd9b8acc8b5ca17969a4d546845c30",
"md5": "ce5f5e849fd3240a99784e56edc9f6a2",
"sha256": "bc0b061460b09764d3767384480c703eb5c661e57cfefd1e75a1c63c2e65c61f"
},
"downloads": -1,
"filename": "django_encryption-0.3.47.tar.gz",
"has_sig": false,
"md5_digest": "ce5f5e849fd3240a99784e56edc9f6a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 12981,
"upload_time": "2025-01-20T10:08:10",
"upload_time_iso_8601": "2025-01-20T10:08:10.818234Z",
"url": "https://files.pythonhosted.org/packages/63/01/4a46cc2c07962fabb5edf889d9fc16dd9b8acc8b5ca17969a4d546845c30/django_encryption-0.3.47.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-20 10:08:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "piiano",
"github_project": "vault-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-encryption"
}
JSON
