Code review fixes (6/6)

Author: aclark4life

django_mongodb_backend/fields/__init__.py

@@ -4,6 +4,7 @@
 from .embedded_model import EmbeddedModelField
 from .embedded_model_array import EmbeddedModelArrayField
 from .encryption import (
+    EncryptedBigIntegerField,
     EncryptedBinaryField,
     EncryptedBooleanField,
     EncryptedCharField,
@@ -16,6 +17,7 @@
     EncryptedFloatField,
     EncryptedGenericIPAddressField,
     EncryptedIntegerField,
+    EncryptedPositiveBigIntegerField,
     EncryptedPositiveIntegerField,
     EncryptedPositiveSmallIntegerField,
     EncryptedSmallIntegerField,
@@ -32,6 +34,7 @@
     "ArrayField",
     "EmbeddedModelArrayField",
     "EmbeddedModelField",
+    "EncryptedBigIntegerField",
     "EncryptedBinaryField",
     "EncryptedBooleanField",
     "EncryptedCharField",
@@ -44,6 +47,7 @@
     "EncryptedFloatField",
     "EncryptedGenericIPAddressField",
     "EncryptedIntegerField",
+    "EncryptedPositiveBigIntegerField",
     "EncryptedPositiveIntegerField",
     "EncryptedPositiveSmallIntegerField",
     "EncryptedSmallIntegerField",

django_mongodb_backend/fields/encryption.py

@@ -27,6 +27,10 @@ class EncryptedBinaryField(EncryptedFieldMixin, models.BinaryField):
     pass
 
 
+class EncryptedBigIntegerField(EncryptedFieldMixin, models.BigIntegerField):
+    pass
+
+
 class EncryptedBooleanField(EncryptedFieldMixin, models.BooleanField):
     pass
 
@@ -67,6 +71,10 @@ class EncryptedIntegerField(EncryptedFieldMixin, models.IntegerField):
     pass
 
 
+class EncryptedPositiveBigIntegerField(EncryptedFieldMixin, models.PositiveBigIntegerField):
+    pass
+
+
 class EncryptedPositiveIntegerField(EncryptedFieldMixin, models.PositiveIntegerField):
     pass
 

django_mongodb_backend/management/commands/showencryptedfieldsmap.py

@@ -22,7 +22,7 @@ def add_arguments(self, parser):
             Specifies the database to use. Defaults to ``default``.""",
         )
         parser.add_argument(
-            "--create-new-keys",
+            "--create-data-keys",
             action="store_true",
             help="""
             If specified, this option will create and show new encryption

docs/source/howto/queryable-encryption.rst

@@ -4,9 +4,12 @@ Configuring Queryable Encryption
 
 .. versionadded:: 5.2.0rc1
 
-This guide is similar to the
-:doc:`manual:core/queryable-encryption/quick-start` but with some additional
-steps required to configure Queryable Encryption with Django MongoDB Backend.
+Queryable Encryption is a powerful MongoDB feature that enables you to encrypt
+sensitive fields in your database while still allowing queries on that
+encrypted data.
+
+This section will guide you through the process of configuring Queryable
+Encryption in your Django project using the Django MongoDB Backend.
 
 .. admonition:: MongoDB requirements
 
@@ -239,5 +242,5 @@ settings as follows:
         ),
     }
 
-You are now ready to :doc:`develop with Queryable Encryption
-</topics/queryable-encryption>` in Django MongoDB Backend!
+You are now ready to :doc:`start developing applications
+</topics/queryable-encryption>` with Queryable Encryption!

docs/source/ref/django-admin.rst

@@ -30,7 +30,7 @@ Available commands
 
         Specifies the database to use. Defaults to ``default``.
 
-    .. django-admin-option:: --create-new-keys
+    .. django-admin-option:: --create-data-keys
 
         If specified, this option will create and show new encryption keys
         instead of showing existing keys from the configured key vault.

docs/source/ref/models/encrypted-fields.rst

@@ -20,6 +20,8 @@ Queryable Encryption.
 +========================================+======================================================+
 | ``EncryptedBooleanField``              | :class:`~django.db.models.BooleanField`              |
 +----------------------------------------+------------------------------------------------------+
+| ``EncryptedBigIntegerField``           | :class:`~django.db.models.BigIntegerField`           |
++----------------------------------------+------------------------------------------------------+
 | ``EncryptedCharField``                 | :class:`~django.db.models.CharField`                 |
 +----------------------------------------+------------------------------------------------------+
 | ``EncryptedDateField``                 | :class:`~django.db.models.DateField`                 |
@@ -38,6 +40,8 @@ Queryable Encryption.
 +----------------------------------------+------------------------------------------------------+
 | ``EncryptedPositiveIntegerField``      | :class:`~django.db.models.PositiveIntegerField`      |
 +----------------------------------------+------------------------------------------------------+
+| ``EncryptedPositiveBigIntegerField``   | :class:`~django.db.models.PositiveBigIntegerField`   |
++----------------------------------------+------------------------------------------------------+
 | ``EncryptedPositiveSmallIntegerField`` | :class:`~django.db.models.PositiveSmallIntegerField` |
 +----------------------------------------+------------------------------------------------------+
 | ``EncryptedSmallIntegerField``         | :class:`~django.db.models.SmallIntegerField`         |
@@ -67,20 +71,10 @@ supported by Queryable Encryption.
     MongoDB's Queryable Encryption.
 
     To create a custom encrypted field, inherit from ``EncryptedFieldMixin`` and
-    the desired Django field class. You can then specify the ``queries`` option
-    to define how the field can be queried.
-
-    The ``queries`` option should be a dictionary that specifies the type of
-    queries that can be performed on the field. The :ref:`available query types
-    <manual:qe-fundamentals-encrypt-query>` are as follows:
-
-    - ``equality``: Supports equality queries.
-    - ``range``: Supports range queries.
+    the desired Django field class.
 
-    You can configure an encrypted field for either equality or range queries,
-    but not both. Configure fields for the expected query type.
 
-    For example, to create a custom encrypted field that supports equality
+    For example, to create a custom encrypted field that supports ``equality``
     queries, you can define it as follows:
 
     .. code-block:: python

docs/source/topics/queryable-encryption.rst

@@ -4,4 +4,98 @@ Queryable Encryption
 
 .. versionadded:: 5.2.0rc1
 
-Use :doc:`/ref/models/encrypted-fields` to structure your sensitive data.
+Once you have configured your Django project and MongoDB deployment for
+Queryable Encryption, you’re ready to start developing applications that take
+advantage of these enhanced security features.
+
+Encrypted fields
+================
+
+You can use :doc:`encrypted fields </ref/models/encrypted-fields>` to structure
+your sensitive data.
+
+
+The basics
+----------
+
+For example, you can define a model with encrypted fields
+like this:
+
+.. code-block:: python
+
+    from django.db import models
+    from django_mongodb_backend.fields import EncryptedCharField
+
+
+    class Patient(models.Model):
+        name = models.CharField(max_length=255)
+        ssn = models.EncryptedCharField(max_length=11)
+
+        def __str__(self):
+            return self.name
+
+Once you have defined your model, created migrations with ``python manage.py
+makemigrations`` and run migrations with ``python manage.py migrate``, you can
+create and manipulate instances of the data just like any other Django model
+data. The fields will automatically handle encryption and decryption, ensuring
+that sensitive data is stored securely in the database.
+
+From an encrypted client, you can access the data::
+
+    from myapp.models import Patient
+
+    >>> bob = Patient.objects.create(name="Bob", ssn="123-45-6789")
+    >>> bob.ssn
+    '123-45-6789'
+
+From an unencrypted client, you can still access the data, but the sensitive
+fields will be encrypted. For example, if you try to access the ``ssn`` field
+from an unencrypted client, you will see the encrypted value::
+
+    from myapp.models import Patient
+
+    >>> bob = Patient.objects.get(name="Bob")
+    >>> bob.ssn
+    Binary(b'\x0e\x97sv\xecY\x19Jp\x81\xf1\\\x9cz\t1\r\x02...', 6)
+
+Querying encrypted fields
+-------------------------
+
+In order to query encrypted fields, you must define the queryable encryption
+query type in the model field definition. For example, if you want to query the
+``ssn`` field for equality, you can define it as follows:
+
+.. code-block:: python
+
+    from django.db import models
+    from django_mongodb_backend.fields import EncryptedCharField
+
+
+    class Patient(models.Model):
+        name = models.CharField(max_length=255)
+        ssn = models.EncryptedCharField(max_length=11, queries={"equality": True})
+
+        def __str__(self):
+            return self.name
+
+Query types
+~~~~~~~~~~~
+
+The ``queries`` option should be a dictionary that specifies the type of queries
+that can be performed on the field. The :ref:`available query types
+<manual:qe-fundamentals-encrypt-query>` are as follows:
+
+- ``equality``: Supports equality queries.
+- ``range``: Supports range queries.
+
+You can configure an encrypted field for either equality or range queries, but
+not both.
+
+Now you can perform queries on the ``ssn`` field using the defined query type.
+For example, to find a patient by their SSN, you can do the following::
+
+    from myapp.models import Patient
+
+    >>> patient = Patient.objects.get(ssn="123-45-6789")
+    >>> patient.name
+    'Bob'

tests/encryption_/models.py

@@ -76,8 +76,20 @@ class Meta:
 
 
 class EncryptedNumbers(models.Model):
+    # Not tested elsewhere
     pos_smallint = EncryptedPositiveSmallIntegerField(queries=EQUALITY_QUERY)
     smallint = EncryptedSmallIntegerField(queries=EQUALITY_QUERY)
 
     class Meta:
         required_db_features = {"supports_queryable_encryption"}
+
+
+class SensitiveData(models.Model):
+    # Example from documentation
+    name = EncryptedCharField(max_length=100)
+    email = EncryptedEmailField()
+    phone_number = EncryptedCharField(max_length=15)
+
+    sensitive_text = EncryptedTextField()
+    sensitive_integer = EncryptedIntegerField()
+    sensitive_date = EncryptedDateField()

tests/encryption_/test_management.py

@@ -72,7 +72,7 @@ def test_create_new_keys(self):
             "showencryptedfieldsmap",
             "--database",
             "encrypted",
-            "--create-new-keys",
+            "--create-data-keys",
             verbosity=0,
             stdout=out,
         )