ormar/docs/fields/encryption.md

# Encryption

`ormar` provides you with a way to encrypt a field in the database only.
Provided encryption backends allow for both one-way encryption (`HASH` backend) as
well as both-way encryption/decryption (`FERNET` backend).

!!!warning
    Note that in order for encryption to work you need to install optional `cryptography` package.

    You can do it manually `pip install cryptography` or with ormar by `pip install ormar[crypto]`

!!!warning
    Note that adding `encrypt_backend` changes the database column type to `TEXT`, 
    which needs to be reflected in db either by migration (`alembic`) or manual change

## Defining a field encryption

To encrypt a field you need to pass at minimum `encrypt_secret` and `encrypt_backend` parameters.

```python hl_lines="10-12"
base_ormar_config = ormar.OrmarConfig(
    metadata=metadata
    database=database
)

class Filter(ormar.Model):
    ormar_config = base_ormar_config.copy()

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=100, 
                             encrypt_secret="secret123", 
                             encrypt_backend=ormar.EncryptBackends.FERNET)
```

!!!warning
    You can encrypt all `Field` types apart from `primary_key` column and relation 
    columns (`ForeignKey` and `ManyToMany`). Check backends details for more information.

## Available backends

### HASH

HASH is a one-way hash (like for password), never decrypted on retrieval

To set it up pass appropriate backend value.

```python
... # rest of model definition
password: str = ormar.String(max_length=128,
                         encrypt_secret="secret123", 
                         encrypt_backend=ormar.EncryptBackends.HASH)
```

Note that since this backend never decrypt the stored value it's only applicable for
`String` fields. Used hash is a `sha512` hash, so the field length has to be >=128.

!!!warning
    Note that in `HASH` backend you can filter by full value but filters like `contain` will not work as comparison is make on encrypted values

!!!note 
    Note that provided `encrypt_secret` is first hashed itself and used as salt, so in order to
    compare to stored string you need to recreate this steps. The `order_by` will not work as encrypted strings are compared so you cannot reliably order by.

```python
class Hash(ormar.Model):
    ormar_config = base_ormar_config.copy(tablename="hashes")

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=128,
                             encrypt_secret="udxc32",
                             encrypt_backend=ormar.EncryptBackends.HASH)


await Hash(name='test1').save()

# note the steps to recreate the stored value
# you can use also cryptography package instead of hashlib
secret = hashlib.sha256("udxc32".encode()).digest()
secret = base64.urlsafe_b64encode(secret)
hashed_test1 = hashlib.sha512(secret + 'test1'.encode()).hexdigest()

# full value comparison works
hash1 = await Hash.objects.get(name='test1')
assert hash1.name == hashed_test1

# but partial comparison does not (hashed strings are compared)
with pytest.raises(NoMatch):
    await Filter.objects.get(name__icontains='test')
```

### FERNET

FERNET is a two-way encrypt/decrypt backend

To set it up pass appropriate backend value.

```python
... # rest of model definition
year: int = ormar.Integer(encrypt_secret="secret123", 
                          encrypt_backend=ormar.EncryptBackends.FERNET)
```

Value is encrypted on way to database end decrypted on way out. Can be used on all types,
as the returned value is parsed to corresponding python type.

!!!warning
    Note that in `FERNET` backend you loose `filter`ing possibility altogether as part of the encrypted value is a timestamp.
    The same goes for `order_by` as encrypted strings are compared so you cannot reliably order by. 

```python
class Filter(ormar.Model):
    ormar_config = base_ormar_config.copy()

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=100, 
                             encrypt_secret="asd123", 
                             encrypt_backend=ormar.EncryptBackends.FERNET)

await Filter(name='test1').save()
await Filter(name='test1').save()

# values are properly encrypted and later decrypted
filters = await Filter.objects.all()
assert filters[0].name == filters[1].name == 'test1'

# but you cannot filter at all since part of the fernet hash is a timestamp
# which means that even if you encrypt the same string 2 times it will be different
with pytest.raises(NoMatch):
    await Filter.objects.get(name='test1')
```

## Custom Backends

If you wish to support other type of encryption (i.e. AES) you can provide your own `EncryptionBackend`.

To setup a backend all you need to do is subclass `ormar.fields.EncryptBackend` class and provide required backend.

Sample dummy backend (that does nothing) can look like following:

```python
class DummyBackend(ormar.fields.EncryptBackend):
    def _initialize_backend(self, secret_key: bytes) -> None:
        pass

    def encrypt(self, value: Any) -> str:
        return value

    def decrypt(self, value: Any) -> str:
        return value
```

To use this backend set `encrypt_backend` to `CUSTOM` and provide your backend as
argument by `encrypt_custom_backend`.

```python
class Filter(ormar.Model):
    ormar_config = base_ormar_config.copy()

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=100, 
                             encrypt_secret="secret123", 
                             encrypt_backend=ormar.EncryptBackends.CUSTOM,
                             encrypt_custom_backend=DummyBackend
                             )
```