Encrypted fields¶

Added in version 6.0.1.

To use encrypted fields, you must configure Queryable Encryption.

The following tables detailed which fields have encrypted counterparts. In all cases, the encrypted field names are simply prefixed with Encrypted, e.g. EncryptedCharField. They are importable from django_mongodb_backend.fields.

`django.db.models`¶
Model Field	Encrypted version available?
`BigIntegerField`	Yes
`BinaryField`	Yes
`BooleanField`	Yes
`CharField`	Yes
`DateField`	Yes
`DateTimeField`	Yes
`DecimalField`	Yes
`DurationField`	Yes
`EmailField`	Yes
`FileField`	No: the use case for encrypting this field is unclear.
`FilePathField`	No: the use case for encrypting this field is unclear.
`GenericIPAddressField`	Yes
`ImageField`	No: the use case for encrypting this field is unclear.
`IntegerField`	Yes
`JSONField`	No: `JSONField` isn’t recommended.
`PositiveIntegerField`	Yes
`PositiveBigIntegerField`	Yes
`PositiveSmallIntegerField`	Yes
`SlugField`	No: it requires a unique index which Queryable Encryption doesn’t support.
`SmallIntegerField`	Yes
`TimeField`	Yes
`TextField`	Yes
`URLField`	Yes
`UUIDField`	Yes

`django_mongodb_backend.fields`¶
Model Field	Encrypted version available?
`ArrayField`	Yes
`EmbeddedModelArrayField`	Yes
`EmbeddedModelField`	Yes
`ObjectIdField`	Yes
`PolymorphicEmbeddedModelField`	No: may be implemented in the future.
`PolymorphicEmbeddedModelArrayField`	No: may be implemented in the future.

`EncryptedField.queries`¶

Most encrypted fields* take an optional queries argument. It’s a dictionary that specifies the type of queries that can be performed on the field, as well as any query options.

The available query types depend on your version of MongoDB. For example, in MongoDB 8.0, the supported types are equality and range.

The supported lookups for equality queries are: exact and lookup:in. The supported operators are AND (&) and OR (|).

The supported lookups for range queries include those of equality queries as well as lt, lte, gt, and gte.

* These fields don’t support the queries argument:

EncryptedArrayField
EncryptedEmbeddedModelArrayField
EncryptedEmbeddedModelField

Embedded model encryption¶

There are two ways to encrypt embedded models. You can either encrypt the entire subdocument, in which case you can’t query any the subdocuments fields, or you can encrypt only selected fields of the subdocument.

Encrypting the entire subdocument¶

To encrypt a subdocument, use EncryptedEmbeddedModelField or EncryptedEmbeddedModelArrayField. In this case, the field’s embedded model cannot have any encrypted fields.

Encrypting selected fields of a subdocument¶

To encrypt only select fields of a subdocument, use EmbeddedModelField and any of the other encrypted fields on the embedded model.

MongoDB doesn’t support encrypting selected fields of EmbeddedModelArrayField.

Limitations¶

MongoDB imposes some restrictions on encrypted fields:

They cannot be indexed.
They cannot be part of a unique constraint.
They cannot be null.

`QuerySet` limitations¶

In addition to Django MongoDB Backend’s QuerySet limitations, some QuerySet methods aren’t supported on encrypted fields. Each unsupported method is followed by a sample error message from the database. Depending on the exact query, error messages may vary.

order_by(): Cannot add an encrypted field as a prefix of another encrypted field.
alias(), annotate(), distinct(): Cannot group on field ‘<encrypted_field>’ which is encrypted with the random algorithm or whose encryption properties are not known until runtime.
dates(), datetimes(): If the value type is a date, the type of the index must also be date (and vice versa).
in_bulk(): Encrypted fields can’t have unique constraints.
Queries that join multiple collections and require the let operator. Such queries usually involve expressions or subqueries: Non-empty ‘let’ field is not allowed in the $lookup aggregation stage over an encrypted collection.

There are also several QuerySet methods that aren’t permitted on any models (regardless of whether or not they have encrypted fields) that use a database connection with Automatic Encryption. Each unsupported method is followed by a sample error message from the database.

update(): Multi-document updates are not allowed with Queryable Encryption.
aggregate(): Invalid reference to an encrypted field within aggregate expression.
union(): Aggregation stage $unionWith is not allowed or supported with automatic encryption.

`EncryptedFieldMixin`¶

class EncryptedFieldMixin¶

Added in version 6.0.1.

Use this mixin to create encrypted versions of your own custom fields. For example, to create an encrypted version of MyField:

from django.db import models
from django_mongodb_backend.fields import EncryptedFieldMixin
from myapp.fields import MyField


class MyEncryptedField(EncryptedFieldMixin, MyField):
    pass

This adds the queries argument to the field.