@@ -4,4 +4,98 @@ Queryable Encryption
44
55.. versionadded :: 5.2.0rc1
66
7- Use :doc: `/ref/models/encrypted-fields ` to structure your sensitive data.
7+ Once you have configured your Django project and MongoDB deployment for
8+ Queryable Encryption, you’re ready to start developing applications that take
9+ advantage of these enhanced security features.
10+
11+ Encrypted fields
12+ ================
13+
14+ You can use :doc: `encrypted fields </ref/models/encrypted-fields >` to structure
15+ your sensitive data.
16+
17+
18+ The basics
19+ ----------
20+
21+ For example, you can define a model with encrypted fields
22+ like this:
23+
24+ .. code-block :: python
25+
26+ from django.db import models
27+ from django_mongodb_backend.fields import EncryptedCharField
28+
29+
30+ class Patient (models .Model ):
31+ name = models.CharField(max_length = 255 )
32+ ssn = models.EncryptedCharField(max_length = 11 )
33+
34+ def __str__ (self
35+ return self .name
36+
37+ python manage.py
38+ makemigrations `` and run migrations with ``python manage.py migrate ``, you can
39+ create and manipulate instances of the data just like any other Django model
40+ data. The fields will automatically handle encryption and decryption, ensuring
41+ that sensitive data is stored securely in the database.
42+
43+ From an encrypted client, you can access the data::
44+
45+ from myapp.models import Patient
46+
47+ >>> bob = Patient.objects.create(name="Bob", ssn="123-45-6789")
48+ >>> bob.ssn
49+ '123-45-6789'
50+
51+ From an unencrypted client, you can still access the data, but the sensitive
52+ fields will be encrypted. For example, if you try to access the ``ssn `` field
53+ from an unencrypted client, you will see the encrypted value::
54+
55+ from myapp.models import Patient
56+
57+ >>> bob = Patient.objects.get(name="Bob")
58+ >>> bob.ssn
59+ Binary(b'\x0e\x97sv\xecY\x19Jp\x81\xf1\\\x9cz\t1\r\x02...', 6)
60+
61+ Querying encrypted fields
62+ -------------------------
63+
64+ In order to query encrypted fields, you must define the queryable encryption
65+ query type in the model field definition. For example, if you want to query the
66+ ``ssn `` field for equality, you can define it as follows:
67+
68+ .. code-block :: python
69+
70+ from django.db import models
71+ from django_mongodb_backend.fields import EncryptedCharField
72+
73+
74+ class Patient (models .Model ):
75+ name = models.CharField(max_length = 255 )
76+ ssn = models.EncryptedCharField(max_length = 11 , queries = {" equality" True })
77+
78+ def __str__ (self
79+ return self .name
80+
81+
82+ ~~~~~~~~~~~
83+
84+ The ``queries `` option should be a dictionary that specifies the type of queries
85+ that can be performed on the field. The :ref: `available query types
86+ <manual:qe-fundamentals-encrypt-query>` are as follows:
87+
88+ - ``equality ``: Supports equality queries.
89+ - ``range ``: Supports range queries.
90+
91+ You can configure an encrypted field for either equality or range queries, but
92+ not both.
93+
94+ Now you can perform queries on the ``ssn `` field using the defined query type.
95+ For example, to find a patient by their SSN, you can do the following::
96+
97+ from myapp.models import Patient
98+
99+ >>> patient = Patient.objects.get(ssn="123-45-6789")
100+ >>> patient.name
101+ 'Bob'
0 commit comments