Doc updates

Author: aclark4life

docs/howto/queryable-encryption.rst

@@ -24,10 +24,9 @@ Installation
 ============
 
 In addition to the :doc:`installation </intro/install>` and :doc:`configuration
-</intro/configure>` steps already required to use Django MongoDB Backend,
-Queryable Encryption requires the installation of additional dependencies.
-You can install these dependencies by using the ``encryption`` extra when
-installing ``django-mongodb-backend``:
+</intro/configure>` steps required to use Django MongoDB Backend, Queryable
+Encryption has additional dependencies. You can install these dependencies
+by using the ``encryption`` extra when installing ``django-mongodb-backend``:
 
 .. code-block:: console
 
@@ -39,13 +38,14 @@ Configuring the ``DATABASES`` setting
 =====================================
 
 In addition to the :ref:`database settings <configuring-databases-setting>`
-already required to use Django MongoDB Backend, you must configure an
-encrypted database to store encrypted data.
+required to use Django MongoDB Backend, Queryable Encryption requires you to
+configure a separate encrypted database connection in your
+:setting:`django:DATABASES` setting.
 
 .. admonition:: Encrypted database
 
     An encrypted database is a separate database connection in your
-    :setting:`django:DATABASES` setting that is configured to use
+    :setting:`django:DATABASES` setting that is configured to use PyMongo's
     :class:`automatic encryption
     <pymongo.encryption_options.AutoEncryptionOpts>`.
 
@@ -102,15 +102,16 @@ provider and encryption keys stored in the ``encryption.__keyVault`` collection.
 Configuring the ``DATABASE_ROUTERS`` setting
 ============================================
 
-Similar to configuring a :ref:`database router
-<configuring-database-routers-setting>` for
+Similar to configuring the :ref:`DATABASE_ROUTERS
+<configuring-database-routers-setting>` setting for
 :doc:`embedded models </topics/embedded-models>`, Queryable Encryption
-requires a :setting:`database router <django:DATABASE_ROUTERS>` to route
-queries to the encrypted database.
+requires a :setting:`DATABASE_ROUTERS <django:DATABASE_ROUTERS>` setting to
+route database operations to the encrypted database.
 
-The following example shows how to
-configure a custom router for the "myapp" application that routes queries to the
-encrypted database.
+The following example shows how to configure a router for the "myapp"
+application that routes database operations to the encrypted database for all
+models in that application. The router also specifies the :ref:`KMS provider
+<qe-configuring-kms>` to use.
 
 .. code-block:: python
 
@@ -148,7 +149,11 @@ Then in your Django settings, add the custom router to the
 Configuring the Key Management Service (KMS)
 ============================================
 
-To use Queryable Encryption, you must configure a Key Management Service (KMS).
+To use Queryable Encryption, you must configure a Key Management Service (KMS)
+to store and manage your encryption keys. Django MongoDB Backend allows you to
+configure multiple KMS providers and select the appropriate provider for each
+model using a custom database router.
+
 The KMS is responsible for managing the encryption keys used to encrypt and
 decrypt data. The following table summarizes the available KMS configuration
 options followed by an example of how to use them.
@@ -175,23 +180,7 @@ Example of KMS configuration with AWS KMS:
 
     DATABASES = {
         "encrypted": {
-            "ENGINE": "django_mongodb_backend",
-            "HOST": "mongodb+srv://cluster0.example.mongodb.net",
-            "NAME": "encrypted",
-            "USER": "my_user",
-            "PASSWORD": "my_password",
-            "PORT": 27017,
-            "OPTIONS": {
-                "auto_encryption_opts": AutoEncryptionOpts(
-                    key_vault_namespace="encryption.__keyVault",
-                    kms_providers={
-                        "aws": {
-                            "accessKeyId": "your-access-key-id",
-                            "secretAccessKey": "your-secret-access-key",
-                        }
-                    },
-                )
-            },
+            # ...
             "KMS_CREDENTIALS": {
                 "aws": {
                     "key": os.getenv("AWS_KEY_ARN", ""),
@@ -212,22 +201,22 @@ Example of KMS configuration with AWS KMS:
 Configuring the ``encrypted_fields_map``
 ========================================
 
-When you :ref:`configure an encrypted database connection
-<qe-configuring-databases-setting>` without specifying an
+When you configure the :ref:`DATABASES <qe-configuring-databases-setting>`
+setting for Queryable Encryption *without* specifying an
 ``encrypted_fields_map``, Django MongoDB Backend will create encrypted
-collections for you when you run ``python manage.py migrate --database
-encrypted``.
+collections, including data keys, when you run ``python manage.py migrate
+--database encrypted``.
 
-Encryption keys for encrypted fields are stored in the key vault
-:ref:`specified in the Django settings <qe-configuring-kms>`. To see the keys
-created by Django MongoDB Backend, along with the entire schema, you can run the
+Encryption keys for encrypted fields are stored in the key vault specified in
+the :ref:`DATABASES <qe-configuring-kms>` setting. To see the keys created by
+Django MongoDB Backend, along with the entire schema, you can run the
 :djadmin:`showencryptedfieldsmap` command::
 
     $ python manage.py showencryptedfieldsmap --database encrypted
 
-Use the output of the :djadmin:`showencryptedfieldsmap` command to set the
-``encrypted_fields_map`` in
-:class:`pymongo.encryption_options.AutoEncryptionOpts` in your Django settings.
+Use the output of :djadmin:`showencryptedfieldsmap` to set the
+``encrypted_fields_map`` in :class:`AutoEncryptionOpts
+<pymongo.encryption_options.AutoEncryptionOpts>` in your Django settings.
 
 .. code-block:: python
 
@@ -236,21 +225,10 @@ Use the output of the :djadmin:`showencryptedfieldsmap` command to set the
 
     DATABASES = {
         "encrypted": {
-            "ENGINE": "django_mongodb_backend",
-            "HOST": "mongodb+srv://cluster0.example.mongodb.net",
-            "NAME": "encrypted",
-            "USER": "my_user",
-            "PASSWORD": "my_password",
-            "PORT": 27017,
+            # ...
             "OPTIONS": {
                 "auto_encryption_opts": AutoEncryptionOpts(
-                    key_vault_namespace="encryption.__keyVault",
-                    kms_providers={
-                        "aws": {
-                            "accessKeyId": "your-access-key-id",
-                            "secretAccessKey": "your-secret-access-key",
-                        }
-                    },
+                    # ...
                     encrypted_fields_map=json_util.loads(
                         """{
                         "encrypt_patient": {
@@ -277,6 +255,13 @@ Use the output of the :djadmin:`showencryptedfieldsmap` command to set the
         },
     }
 
+
+.. admonition:: Security consideration
+
+   Supplying an encrypted fields map provides more security than relying on an
+   encrypted fields map obtained from the server. It protects against a
+   malicious server advertising a false encrypted fields map.
+
 Configuring the Automatic Encryption Shared Library
 ===================================================
 
@@ -288,60 +273,25 @@ You can :ref:`download the shared library
 <manual:qe-csfle-shared-library-download>` from the
 :ref:`manual:enterprise-official-packages` and configure it in your Django
 settings using the ``crypt_shared_lib_path`` option in
-:class:`pymongo.encryption_options.AutoEncryptionOpts`. The following example
-shows how to configure the shared library in your Django settings:
+:class:`AutoEncryptionOpts <pymongo.encryption_options.AutoEncryptionOpts>`.
+
+The following example shows how to configure the shared library in your Django
+settings:
 
 .. code-block:: python
 
     from pymongo.encryption_options import AutoEncryptionOpts
 
     DATABASES = {
         "encrypted": {
-            "ENGINE": "django_mongodb_backend",
-            "HOST": "mongodb+srv://cluster0.example.mongodb.net",
-            "NAME": "encrypted",
-            "USER": "my_user",
-            "PASSWORD": "my_password",
-            "PORT": 27017,
+            # ...
             "OPTIONS": {
                 "auto_encryption_opts": AutoEncryptionOpts(
-                    key_vault_namespace="encryption.__keyVault",
-                    kms_providers={
-                        "aws": {
-                            "accessKeyId": "your-access-key-id",
-                            "secretAccessKey": "your-secret-access-key",
-                        }
-                    },
-                    encrypted_fields_map=json_util.loads(
-                        """{
-                        "encrypt_patient": {
-                          "fields": [
-                            {
-                              "bsonType": "string",
-                              "path": "patient_record.ssn",
-                              "keyId": {
-                                "$binary": {
-                                  "base64": "2MA29LaARIOqymYHGmi2mQ==",
-                                  "subType": "04"
-                                }
-                              },
-                              "queries": {
-                                "queryType": "equality"
-                              }
-                            },
-                          ]
-                        }
-                    }"""
-                    ),
+                    # ...
                     crypt_shared_lib_path="/path/to/mongo_crypt_shared_v1.dylib",
                 )
             },
-            "KMS_CREDENTIALS": {
-                "aws": {
-                    "key": os.getenv("AWS_KEY_ARN", ""),
-                    "region": os.getenv("AWS_KEY_REGION", ""),
-                },
-            },
+            # ...
         },
     }