Metadata-Version: 2.1
Name: django-tink-fields
Version: 0.2.0
Summary: Tink-based encrypted model fields for Django
Home-page: https://github.com/script3r/django-tink-fields/
Author: Isaac Elbaz
Author-email: script3r@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Framework :: Django
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: AUTHORS.md


# Django Tink Fields

Leverages [Google Tink](https://developers.google.com/tink) to encrypt Django's core model fields. This work is heavily based on the work of [Django Fernet Fields](https://github.com/orcasgit/django-fernet-fields) which seems to have been abandoned last few years.

## Installation

Use `pip` to install `django-tink-fields`:

```bash
pip install django-tink-fields
```

Edit `settings.py` and introduce a configuration section for `TINK_FIELDS_CONFIG`:

```python
TINK_FIELDS_CONFIG = {
    "default": {
        "cleartext": False,
        "path": "/path/to/an/encryted_keyset.json",
    },
    "another": {
        "cleartext": True,
        "path": "/path/to/a/cleartext_keyset.json",
    }
}
```

Tink keysets can be created via `tinkey` and may optionally be wrapped via a key-management system such as `AWS KMS` or `GCP KMS`.

To create a cleartext keyset for testing purposes:

```bash
tinkey create-keyset --out-format json --out test_plaintext_keyset.json --key-template AES128_GCM
```

Alternatively, to create an encrypted keyset that is wrapped by `GCP KMS`, specify `--master-key-uri` as follow:

```bash
tinkey create-keyset --out-format json --out test_encrypted_keyset.json --key-template AES128_GCM --master-key-uri=gcp-kms://projects/foo1/locations/global/keyRings/foo2/cryptoKeys/foo3
```

To learn more about `tinkey` [read the relevant documentation](https://github.com/google/tink/blob/master/docs/TINKEY.md).

## Examples

The following model creates an encrypted char field that makes use of the `default` keyset.

```python
from django.db import models
from tink_fields import EncryptedCharField

class SomeModel(models.Model):
    some_value = EncryptedCharField(max_length=32)

```

You may specify a specific keyset by providing a `keyset` keyword argument:

```python
from django.db import models
from tink_fields import EncryptedCharField

class AnotherModel(models.Model):
    some_value = EncryptedCharField(max_length=32, keyset="another")

```

Supported field types include: `EncryptedCharField`, `EncryptedTextField`, `EncryptedDateField`, `EncryptedDateTimeField`, `EncryptedEmailField`, and `EncryptedIntegerField`.

### Associated Data

The encrypted fields make use of `Authenticated Encryption With Associated Data (AEAD)` which offers confidentiality and integrity within the same mode of operation. This allows the caller to specify a cleartext fragment named `additional authenticated data (aad)` to the encryption and decryption operations and receive cryptographic guarantees that the ciphertext data has not been tampered with.

To specify the `aad` fragment, provide a callback function `aad_callback` in the keyword arguments:

```python
from django.db import models
from tink_fields import EncryptedCharField

class AnotherModel(models.Model):
    some_value = EncryptedCharField(max_length=32, aad_callback=lambda x: b"some value")

```

The value passed to the callback is the instance of the model field, with a signature of `Callable[[models.Field], bytes]`. As a reminder, the associated data is *not* encrypted so **do not store sensitive data in it**.

## Acknowledgements

- [Google Tink](https://github.com/google/tink/blob/master/docs/PYTHON-HOWTO.md)
- [Django Fernet Fields](https://github.com/orcasgit/django-fernet-fields)

## Authors

- [@script3r](https://www.github.com/script3r)


