Skip to content

Commit 0f84103

Browse files
timgrahamtimgraham
committed
polish howto
1 parent c1cfc25 commit 0f84103

File tree

1 file changed

+70
-87
lines changed

1 file changed

+70
-87
lines changed

‎docs/howto/queryable-encryption.rst‎

Lines changed: 70 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -35,21 +35,11 @@ Configuring the ``DATABASES`` setting
3535
=====================================
3636

3737
In addition to the :ref:`database settings <configuring-databases-setting>`
38-
required to use Django MongoDB Backend, Queryable Encryption requires you to
39-
configure a separate encrypted database connection in your
40-
:setting:`django:DATABASES` setting.
38+
required to use Django MongoDB Backend, Queryable Encryption requires
39+
configuring a separate database connection that uses use PyMongo's
40+
:class:`~pymongo.encryption_options.AutoEncryptionOpts`.
4141

42-
.. admonition:: Encrypted database
43-
44-
An encrypted database is a separate database connection in your
45-
:setting:`django:DATABASES` setting that is configured to use PyMongo's
46-
:class:`automatic encryption
47-
<pymongo.encryption_options.AutoEncryptionOpts>`.
48-
49-
Here's how to configure an encrypted database using a local KMS provider and
50-
encryption keys stored in the ``encryption.__keyVault`` collection::
51-
52-
import os
42+
Here's a sample configuration using a local KMS provider::
5343

5444
from pymongo.encryption_options import AutoEncryptionOpts
5545

@@ -63,25 +53,33 @@ encryption keys stored in the ``encryption.__keyVault`` collection::
6353
"encrypted": {
6454
"ENGINE": "django_mongodb_backend",
6555
"HOST": "mongodb+srv://cluster0.example.mongodb.net",
66-
"NAME": "my_database_encrypted",
67-
"USER": "my_user",
68-
"PASSWORD": "my_password",
69-
"PORT": 27017,
56+
"NAME": "my_encrypted_database",
57+
# ...
7058
"OPTIONS": {
7159
"auto_encryption_opts": AutoEncryptionOpts(
72-
key_vault_namespace="encryption.__keyVault",
73-
kms_providers={"local": {"key": os.urandom(96)}},
60+
key_vault_namespace="my_encrypted_database.__keyVault",
61+
kms_providers={
62+
"local": {
63+
# Generated by os.urandom(96)
64+
"key": (
65+
b'-\xc3\x0c\xe3\x93\xc3\x8b\xc0\xf8\x12\xc5#b'
66+
b'\x19\xf3\xbc\xccR\xc8\xedI\xda\\ \xfb\x9cB'
67+
b'\x7f\xab5\xe7\xb5\xc9x\xb8\xd4d\xba\xdc\x9c'
68+
b'\x9a\xdb9J]\xe6\xce\x104p\x079q.=\xeb\x9dK*'
69+
b'\x97\xea\xf8\x1e\xc3\xd49K\x18\x81\xc3\x1a"'
70+
b'\xdc\x00U\xc4u"X\xe7xy\xa5\xb2\x0e\xbc\xd6+-'
71+
b'\x80\x03\xef\xc2\xc4\x9bU'
72+
},
73+
},
7474
)
7575
},
7676
},
7777
}
7878

79-
.. admonition:: Local KMS provider key
80-
81-
In the example above, a random key is generated for the local KMS provider
82-
using ``os.urandom(96)``. In a production environment, you should securely
83-
:ref:`store and manage your encryption keys
84-
<manual:qe-fundamentals-kms-providers>`.
79+
``key_vault_namespace`` specifies where to store the data encryption keys.
80+
The database name of the key vault must be the same as in ``"NAME"``. The
81+
vault's collection name can be whatever you wish, but by convention, it's often
82+
``__keyVault``.
8583

8684
.. _qe-configuring-database-routers-setting:
8785

@@ -90,11 +88,11 @@ Configuring the ``DATABASE_ROUTERS`` setting
9088

9189
Similar to configuring the :ref:`DATABASE_ROUTERS
9290
<configuring-database-routers-setting>` setting for
93-
:doc:`embedded models </topics/embedded-models>`, Queryable Encryption
94-
requires a :setting:`DATABASE_ROUTERS <django:DATABASE_ROUTERS>` setting to
95-
route database operations to the encrypted database.
91+
:doc:`embedded models </topics/embedded-models>`, Queryable Encryption requires
92+
a :setting:`DATABASE_ROUTERS` setting to route database operations to the
93+
encrypted database.
9694

97-
The following example shows how to configure a router for the "myapp"
95+
The following example shows how to configure a router for the ``"myapp"``
9896
application that routes database operations to the encrypted database for all
9997
models in that application::
10098

@@ -119,37 +117,37 @@ Then in your Django settings, add the custom database router to the
119117
:setting:`django:DATABASE_ROUTERS` setting::
120118

121119
# settings.py
122-
DATABASE_ROUTERS = ["myapp.routers.EncryptedRouter"]
120+
DATABASE_ROUTERS = [
121+
"django_mongodb_backend.routers.MongoRouter",
122+
"myapp.routers.EncryptedRouter",
123+
]
123124

124125
.. _qe-configuring-kms:
125126

126127
Configuring the Key Management Service (KMS)
127128
============================================
128129

130+
A local KMS provider with a hardcoded key is suitable for local development and
131+
testing, but production environment, you should securely :ref:`store and manage your
132+
encryption keys <manual:qe-fundamentals-kms-providers>`.
133+
129134
To use Queryable Encryption, you must configure a Key Management Service (KMS)
130-
to store and manage your encryption keys. Django MongoDB Backend allows you to
131-
configure multiple KMS providers and select the appropriate provider for each
132-
model using a custom database router.
133-
134-
The KMS is responsible for managing the encryption keys used to encrypt and
135-
decrypt data. The following table summarizes the available KMS configuration
136-
options followed by an example of how to use them.
137-
138-
+-------------------------------------------------------------------------+--------------------------------------------------------+
139-
| :setting:`KMS_CREDENTIALS <DATABASE-KMS-CREDENTIALS>` | A dictionary of Key Management Service (KMS) |
140-
| | credentials configured in the |
141-
| | :setting:`django:DATABASES` setting. |
142-
+-------------------------------------------------------------------------+--------------------------------------------------------+
143-
| :class:`kms_providers <pymongo.encryption_options.AutoEncryptionOpts>` | A dictionary of KMS provider credentials used to |
144-
| | access the KMS with ``kms_provider``. |
145-
+-------------------------------------------------------------------------+--------------------------------------------------------+
146-
| :ref:`kms_provider <qe-configuring-database-routers-setting>` | A single KMS provider name |
147-
| | configured in your custom database |
148-
| | router. |
149-
+-------------------------------------------------------------------------+--------------------------------------------------------+
150-
151-
Example of KMS configuration with ``aws`` in your :class:`kms_providers
152-
<pymongo.encryption_options.AutoEncryptionOpts>` setting::
135+
to store and manage the encryption keys used to encrypt and decrypt data.
136+
137+
There are two primary configuration points:
138+
139+
#. The ``kms_providers`` parameter of
140+
:class:`~pymongo.encryption_options.AutoEncryptionOpts` (see the
141+
``kms_providers`` parameter in
142+
:class:`~pymongo.encryption_options.AutoEncryptionOpts` for the available
143+
providers (``aws``, ``azure``, ``gcp``, etc.) and provider options).
144+
145+
#. The :setting:`KMS_CREDENTIALS <DATABASE-KMS-CREDENTIALS>` inner option of
146+
:setting:`DATABASES`. The keys for each provider are documented under the
147+
``master_key`` parameter of
148+
:meth:`~pymongo.encryption.ClientEncryption.create_data_key`.
149+
150+
Here's an example of KMS configuration with ``aws``::
153151

154152
from pymongo.encryption_options import AutoEncryptionOpts
155153

@@ -169,8 +167,8 @@ Example of KMS configuration with ``aws`` in your :class:`kms_providers
169167
},
170168
"KMS_CREDENTIALS": {
171169
"aws": {
172-
"key": os.getenv("AWS_KEY_ARN", ""),
173-
"region": os.getenv("AWS_KEY_REGION", ""),
170+
"key": "...", # Amazon Resource Name
171+
"region": "...", # AWS region
174172
},
175173
},
176174
},
@@ -193,22 +191,17 @@ the provider for each model in your :ref:`database router
193191
Configuring the ``encrypted_fields_map`` option
194192
===============================================
195193

196-
When you configure the :ref:`DATABASES <qe-configuring-databases-setting>`
197-
setting for Queryable Encryption *without* specifying an
198-
``encrypted_fields_map``, Django MongoDB Backend will create encrypted
199-
collections, including encryption keys, when you :ref:`run migrations for models
200-
that have encrypted fields <qe-migrations>`.
194+
Encryption keys are created when you :ref:`run migrations for models that have
195+
encrypted fields <qe-migrations>`.
201196

202-
Encryption keys for encrypted fields are stored in the key vault specified in
203-
the :ref:`DATABASES <qe-configuring-kms>` setting. To see the keys created by
204-
Django MongoDB Backend, along with the entire schema, you can run the
205-
:djadmin:`showencryptedfieldsmap` command::
197+
To see the encrypted fields map for your models (which includes the encryption
198+
key IDs), run the :djadmin:`showencryptedfieldsmap` command::
206199

207200
$ python manage.py showencryptedfieldsmap --database encrypted
208201

209-
Use the output of :djadmin:`showencryptedfieldsmap` to set the
210-
``encrypted_fields_map`` in :class:`AutoEncryptionOpts
211-
<pymongo.encryption_options.AutoEncryptionOpts>` in your Django settings::
202+
In a production environment, it's recommended to include this map in your
203+
settings to protect against a malicious server advertising a false encrypted
204+
fields map::
212205

213206
from bson import json_util
214207
from pymongo.encryption_options import AutoEncryptionOpts
@@ -244,12 +237,6 @@ Use the output of :djadmin:`showencryptedfieldsmap` to set the
244237
},
245238
}
246239

247-
.. admonition:: Security consideration
248-
249-
Supplying an encrypted fields map provides more security than relying on an
250-
encrypted fields map obtained from the server. It protects against a
251-
malicious server advertising a false encrypted fields map.
252-
253240
Configuring the Automatic Encryption Shared Library
254241
===================================================
255242

@@ -263,12 +250,13 @@ recommended for use with Queryable Encryption.
263250

264251
You can :ref:`download the shared library
265252
<manual:qe-csfle-shared-library-download>` from the
266-
:ref:`manual:enterprise-official-packages` and configure it in your Django
267-
settings using the ``crypt_shared_lib_path`` option in
268-
:class:`AutoEncryptionOpts <pymongo.encryption_options.AutoEncryptionOpts>`.
253+
:ref:`manual:enterprise-official-packages`. The shared library is
254+
platform‑specific. Make sure to download the correct version for your operating
255+
system and architecture.
269256

270-
The following example shows how to configure the shared library in your Django
271-
settings::
257+
To configure it in your Django settings, use
258+
:class:`~pymongo.encryption_options.AutoEncryptionOpts`\'s
259+
``crypt_shared_lib_path`` parameter::
272260

273261
from pymongo.encryption_options import AutoEncryptionOpts
274262

@@ -281,18 +269,13 @@ settings::
281269
crypt_shared_lib_path="/path/to/mongo_crypt_shared_v1.dylib",
282270
)
283271
},
284-
# ...
285272
},
286273
}
287274

288-
289275
.. admonition:: Dynamic library path configuration
290276

291-
The Automatic Encryption Shared Library is platform‑specific. Make sure to
292-
download the correct version for your operating system and architecture,
293-
and configure your environment so the system can locate it.
294-
295-
Use the following variables depending on your platform:
277+
You may also need to configure an environment variable so that your system
278+
can locate the library:
296279

297280
+---------------+---------------------------------+
298281
| **Platform** | **Environment Variable** |
@@ -304,7 +287,7 @@ settings::
304287
| Linux | ``LD_LIBRARY_PATH`` |
305288
+---------------+---------------------------------+
306289

307-
For example on macOS, you can set the ``DYLD_FALLBACK_LIBRARY_PATH``
290+
For example, on macOS you can set the ``DYLD_FALLBACK_LIBRARY_PATH``
308291
environment variable in your shell before starting your Django application::
309292

310293
$ export DYLD_FALLBACK_LIBRARY_PATH="/path/to/mongo_crypt_shared_v1.dylib:$DYLD_FALLBACK_LIBRARY_PATH"

0 commit comments

Comments
 (0)