Skip to content

Commit 0abe5ee

Browse files
aclark4lifeaclark4life
committed
Doc updates
1 parent e9621d1 commit 0abe5ee

File tree

4 files changed

+147
-39
lines changed

4 files changed

+147
-39
lines changed

‎docs/howto/queryable-encryption.rst‎

Lines changed: 144 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Encryption in your Django project.
1414
.. admonition:: MongoDB requirements
1515

1616
Queryable Encryption can be used with MongoDB replica sets or sharded
17-
clusters running version 7.0 or later. Standalone instances are not
17+
clusters running version 8.0 or later. Standalone instances are not
1818
supported. The following table summarizes which MongoDB server products
1919
support each Queryable Encryption mechanism.
2020

@@ -51,21 +51,36 @@ encryption keys.
5151
5252
import os
5353
54-
from django_mongodb_backend import parse_uri
5554
from pymongo.encryption_options import AutoEncryptionOpts
5655
5756
DATABASES = {
58-
# ...
59-
"encrypted": parse_uri(
60-
DATABASE_URL,
61-
options={
57+
"default": {
58+
"ENGINE": "django_mongodb_backend",
59+
"HOST": "mongodb+srv://cluster0.example.mongodb.net",
60+
"NAME": "my_database",
61+
"USER": "my_user",
62+
"PASSWORD": "my_password",
63+
"PORT": 27017,
64+
"OPTIONS": {
65+
"retryWrites": "true",
66+
"w": "majority",
67+
"tls": "false",
68+
},
69+
},
70+
"encrypted": {
71+
"ENGINE": "django_mongodb_backend",
72+
"HOST": "mongodb+srv://cluster0.example.mongodb.net",
73+
"NAME": "encrypted",
74+
"USER": "my_user",
75+
"PASSWORD": "my_password",
76+
"PORT": 27017,
77+
"OPTIONS": {
6278
"auto_encryption_opts": AutoEncryptionOpts(
63-
key_vault_namespace="keyvault.keyvault",
79+
key_vault_namespace="encrypted.keyvault",
6480
kms_providers={"local": {"key": os.urandom(96)}},
6581
)
6682
},
67-
db_name="encrypted",
68-
),
83+
},
6984
}
7085
7186
Configuring the ``DATABASE_ROUTERS`` setting
@@ -88,10 +103,15 @@ configure a custom router for Queryable Encryption:
88103
Encryption.
89104
"""
90105
106+
def db_for_read(self, model, **hints):
107+
if model._meta.app_label == "myapp":
108+
return "encrypted"
109+
return None
110+
111+
db_for_write = db_for_read
112+
91113
def allow_migrate(self, db, app_label, model_name=None, **hints):
92-
# The patientdata app's models are only created in the encrypted
93-
# database.
94-
if app_label == "patientdata":
114+
if app_label == "myapp":
95115
return db == "encrypted"
96116
# Don't create other app's models in the encrypted database.
97117
if db == "encrypted":
@@ -132,15 +152,19 @@ Example of KMS configuration with AWS KMS:
132152

133153
.. code-block:: python
134154
135-
from django_mongodb_backend import parse_uri
136155
from pymongo.encryption_options import AutoEncryptionOpts
137156
138157
DATABASES = {
139-
"encrypted": parse_uri(
140-
DATABASE_URL,
141-
options={
158+
"encrypted": {
159+
"ENGINE": "django_mongodb_backend",
160+
"HOST": "mongodb+srv://cluster0.example.mongodb.net",
161+
"NAME": "encrypted",
162+
"USER": "my_user",
163+
"PASSWORD": "my_password",
164+
"PORT": 27017,
165+
"OPTIONS": {
142166
"auto_encryption_opts": AutoEncryptionOpts(
143-
key_vault_namespace="keyvault.keyvault",
167+
key_vault_namespace="encrypted.keyvault",
144168
kms_providers={
145169
"aws": {
146170
"accessKeyId": "your-access-key-id",
@@ -149,14 +173,12 @@ Example of KMS configuration with AWS KMS:
149173
},
150174
)
151175
},
152-
db_name="encrypted",
153-
),
154-
}
155-
156-
DATABASES["encrypted"]["KMS_CREDENTIALS"] = {
157-
"aws": {
158-
"key": os.getenv("AWS_KEY_ARN", ""),
159-
"region": os.getenv("AWS_KEY_REGION", ""),
176+
"KMS_CREDENTIALS": {
177+
"aws": {
178+
"key": os.getenv("AWS_KEY_ARN", ""),
179+
"region": os.getenv("AWS_KEY_REGION", ""),
180+
},
181+
},
160182
},
161183
}
162184
@@ -208,6 +230,57 @@ If you do not want to use the data keys created by Django MongoDB Backend (when
208230
In this scenario, Django MongoDB Backend will use the newly created data keys
209231
to create collections for models with encrypted fields.
210232

233+
Here is an example of how to configure the
234+
``encrypted_fields_map`` in your Django settings:
235+
236+
.. code-block:: python
237+
238+
from pymongo.encryption_options import AutoEncryptionOpts
239+
from bson import json_util
240+
241+
DATABASES = {
242+
"encrypted": {
243+
"ENGINE": "django_mongodb_backend",
244+
"HOST": "mongodb+srv://cluster0.example.mongodb.net",
245+
"NAME": "encrypted",
246+
"USER": "my_user",
247+
"PASSWORD": "my_password",
248+
"PORT": 27017,
249+
"OPTIONS": {
250+
"auto_encryption_opts": AutoEncryptionOpts(
251+
key_vault_namespace="encrypted.keyvault",
252+
kms_providers={
253+
"aws": {
254+
"accessKeyId": "your-access-key-id",
255+
"secretAccessKey": "your-secret-access-key",
256+
}
257+
},
258+
encrypted_fields_map=json_util.loads(
259+
"""{
260+
"encrypt_patient": {
261+
"fields": [
262+
{
263+
"bsonType": "string",
264+
"path": "patient_record.ssn",
265+
"keyId": {
266+
"$binary": {
267+
"base64": "2MA29LaARIOqymYHGmi2mQ==",
268+
"subType": "04"
269+
}
270+
},
271+
"queries": {
272+
"queryType": "equality"
273+
}
274+
},
275+
]
276+
}
277+
}"""
278+
),
279+
)
280+
},
281+
},
282+
}
283+
211284
Configuring the Automatic Encryption Shared Library
212285
===================================================
213286

@@ -218,25 +291,62 @@ to perform automatic encryption.
218291
You can :ref:`download the shared library
219292
<manual:qe-csfle-shared-library-download>` from the
220293
:ref:`manual:enterprise-official-packages` and configure it in your Django
221-
settings as follows:
294+
settings using the ``crypt_shared_lib_path`` option in
295+
:class:`pymongo.encryption_options.AutoEncryptionOpts`. The following example
296+
shows how to configure the shared library in your Django settings:
222297

223298
.. code-block:: python
224299
225-
from django_mongodb_backend import parse_uri
226300
from pymongo.encryption_options import AutoEncryptionOpts
227301
228302
DATABASES = {
229-
"encrypted": parse_uri(
230-
DATABASE_URL,
231-
options={
303+
"encrypted": {
304+
"ENGINE": "django_mongodb_backend",
305+
"HOST": "mongodb+srv://cluster0.example.mongodb.net",
306+
"NAME": "encrypted",
307+
"USER": "my_user",
308+
"PASSWORD": "my_password",
309+
"PORT": 27017,
310+
"OPTIONS": {
232311
"auto_encryption_opts": AutoEncryptionOpts(
233-
key_vault_namespace="keyvault.keyvault",
234-
kms_providers={"local": {"key": os.urandom(96)}},
312+
key_vault_namespace="encrypted.keyvault",
313+
kms_providers={
314+
"aws": {
315+
"accessKeyId": "your-access-key-id",
316+
"secretAccessKey": "your-secret-access-key",
317+
}
318+
},
319+
encrypted_fields_map=json_util.loads(
320+
"""{
321+
"encrypt_patient": {
322+
"fields": [
323+
{
324+
"bsonType": "string",
325+
"path": "patient_record.ssn",
326+
"keyId": {
327+
"$binary": {
328+
"base64": "2MA29LaARIOqymYHGmi2mQ==",
329+
"subType": "04"
330+
}
331+
},
332+
"queries": {
333+
"queryType": "equality"
334+
}
335+
},
336+
]
337+
}
338+
}"""
339+
),
235340
crypt_shared_lib_path="/path/to/mongo_crypt_shared_v1.dylib",
236341
)
237342
},
238-
db_name="encrypted",
239-
),
343+
"KMS_CREDENTIALS": {
344+
"aws": {
345+
"key": os.getenv("AWS_KEY_ARN", ""),
346+
"region": os.getenv("AWS_KEY_REGION", ""),
347+
},
348+
},
349+
},
240350
}
241351
242352
You are now ready to :doc:`start developing applications

‎docs/ref/django-admin.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Available commands
1717
``showencryptedfieldsmap``
1818
--------------------------
1919

20-
.. versionadded:: 5.2.2
20+
.. versionadded:: 5.2.3
2121

2222
.. django-admin:: showencryptedfieldsmap
2323

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Django MongoDB Backend supports :doc:`manual:core/queryable-encryption`.
99
See :doc:`/howto/queryable-encryption` for more information on how to use
1010
Queryable Encryption with Django MongoDB Backend.
1111

12-
See the :doc:`Queryable Encryption topic </topics/queryable-encryption>` for
12+
See the :doc:`/topics/queryable-encryption` topic guide for
1313
more information on developing applications with Queryable Encryption.
1414

1515
The following fields are supported by Django MongoDB Backend for use with

‎docs/topics/queryable-encryption.rst‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ For example, to find a patient by their SSN, you can do the following::
106106
'Bob'
107107

108108

109-
QuerySet Limitations
109+
QuerySet limitations
110110
~~~~~~~~~~~~~~~~~~~~
111111

112112
When using Django QuerySets with MongoDB Queryable Encryption, it’s important to
@@ -128,8 +128,6 @@ be done client-side after decryption. Key limitations include:
128128
- **No joins on encrypted fields** – Filtering across relationships using
129129
encrypted foreign keys is unsupported because matching must happen
130130
client-side.
131-
- **Admin/debug limitations** – You’ll need to integrate client-side decryption
132-
for Django admin or tools, otherwise you’ll see ciphertext.
133131

134132
In short, when working with Queryable Encryption, design your queries to use
135133
exact matches only on encrypted fields, and plan to handle any sorting or

0 commit comments

Comments
 (0)