Skip to content

Commit 04515d8

Browse files
jmd-mongobiniona-mongodb
jmd-mongo
and
biniona-mongodb
authored
DOCSP-23206 adds Manual Encryption page for QE (#1506)
* DOCSP-23206 adds Manual Encryption page for QE * re-point ref * additional ref * internal review feedback * updates section on specifying fields to encrypt and removes admonition re no docs on manual enc * removes examples and updates man enc page * internal review feedback * adds TODO * updates ref * admonition re incoming code examples * remove addl admonition * Update source/core/queryable-encryption/fundamentals/manual-encryption.txt Co-authored-by: Aleksander Binion <[email protected]> * Update source/core/queryable-encryption/fundamentals/manual-encryption.txt Co-authored-by: Aleksander Binion <[email protected]> Co-authored-by: Aleksander Binion <[email protected]>
1 parent 2810f30 commit 04515d8

File tree

6 files changed

+150
-7
lines changed

6 files changed

+150
-7
lines changed

‎source/core/csfle/fundamentals/manual-encryption.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ Overview
2020
Learn how to use the **{+manual-enc+}** mechanism of {+csfle+}
2121
({+csfle-abbrev+}).
2222

23+
.. include:: /includes/fact-manual-enc-definition.rst
24+
2325
{+manual-enc-first+} is a mechanism in which you specify how you would
2426
like to encrypt and decrypt fields in your document in each operation you
2527
perform on your database.
@@ -224,4 +226,4 @@ To learn more about {+key-vault-long+}s, {+dek-long+}s, and {+cmk-long+}s,
224226
see :ref:`csfle-reference-keys-key-vaults`.
225227

226228
To learn more about {+kms-abbr+} providers and ``kmsProviders`` objects,
227-
see :ref:`csfle-reference-kms-providers`.
229+
see :ref:`csfle-reference-kms-providers`.

‎source/core/queryable-encryption.txt

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -67,12 +67,6 @@ mechanisms:
6767
- | No
6868
- | Yes
6969

70-
.. important:: No Documentation on {+manual-enc-title+}
71-
72-
At present, we do not have documentation detailing how to perform
73-
{+manual-enc+} with {+qe+}. We will publish documentation for
74-
this feature soon.
75-
7670
To learn which MongoDB drivers support {+qe+}, see
7771
:ref:`qe-compatibility-reference`.
7872

‎source/core/queryable-encryption/fundamentals.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,15 @@ Read the following sections to learn how {+qe+} works and how to use it:
1818
- :ref:`qe-fundamentals-collection-management`
1919
- :ref:`qe-reference-keys-key-vaults`
2020
- :ref:`qe-fundamentals-manage-keys`
21+
- :ref:`qe-fundamentals-manual-encryption`
2122
- :ref:`qe-fundamentals-kms-providers`
2223

2324
.. toctree::
2425
:titlesonly:
2526

2627
/core/queryable-encryption/fundamentals/encrypt-and-query
2728
/core/queryable-encryption/fundamentals/manage-collections
29+
/core/queryable-encryption/fundamentals/manual-encryption
2830
/core/queryable-encryption/fundamentals/keys-key-vaults
2931
/core/queryable-encryption/fundamentals/manage-keys
3032
/core/queryable-encryption/fundamentals/kms-providers

‎source/core/queryable-encryption/fundamentals/encrypt-and-query.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ In this guide, you can learn about the following {+qe+} topics:
2222
- Query types and which ones you can use on encrypted fields.
2323
- What to consider when deciding whether to enable queries on an encrypted field.
2424

25+
.. _qe-specify-fields-for-encryption:
26+
2527
Specify Fields for Encryption
2628
-----------------------------
2729

‎source/core/queryable-encryption/fundamentals/manual-encryption.txt

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
.. _qe-fundamentals-manual-encryption:
2+
3+
=================
4+
{+manual-enc-title+}
5+
=================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
Overview
16+
--------
17+
18+
Learn how to use the **{+manual-enc+}** mechanism of {+qe+}.
19+
20+
.. include:: /includes/fact-manual-enc-definition.rst
21+
22+
{+manual-enc-first+} is available in the following MongoDB products
23+
using version 6.0 or later:
24+
25+
- MongoDB Community Server
26+
- MongoDB Enterprise Advanced
27+
- MongoDB Atlas
28+
29+
Use {+manual-enc-title+}
30+
---------------------
31+
32+
To use {+manual-enc+} you must perform the following actions in your
33+
{+qe+}-enabled application:
34+
35+
- :ref:`qe-fundamentals-manual-encryption-client-enc`
36+
- :ref:`qe-fundamentals-manual-encryption-update-operations`
37+
- :ref:`qe-fundamentals-manual-encryption-automatic-decryption`
38+
39+
.. _qe-fundamentals-manual-encryption-client-enc:
40+
41+
Create a ``ClientEncryption`` Instance
42+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43+
44+
``ClientEncryption`` is an abstraction used across drivers and
45+
:binary:`~bin.mongosh` that encapsulates the {+key-vault-long+}
46+
and {+kms-abbr+} operations involved in {+manual-enc+}.
47+
48+
To create a ``ClientEncryption`` instance, specify:
49+
50+
- A ``kmsProviders`` object configured with access to the
51+
{+kms-abbr+} hosting your {+cmk-long+}
52+
- The namespace of your {+key-vault-long+}
53+
- If you use MongoDB Community Server, set the ``bypassQueryAnalysis``
54+
option to ``True``
55+
- A ``MongoClient`` instance with access to your {+key-vault-long+}
56+
57+
For more ``ClientEncryption`` options, see :ref:`qe-reference-mongo-client`.
58+
59+
.. note::
60+
61+
Code examples are not currently available but are coming soon.
62+
63+
.. _qe-fundamentals-manual-encryption-update-operations:
64+
65+
Encrypt Fields in Read and Write Operations
66+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
67+
68+
You must update read and write operations throughout your application
69+
such that your application encrypts fields before performing
70+
read and write operations.
71+
72+
To encrypt fields, use the ``encrypt`` method of your ``ClientEncryption``
73+
instance. Specify the following:
74+
75+
- The value to be encrypted
76+
- The algorithm used, either ``"Indexed"`` or ``"Unindexed"``
77+
- The ID of the {+dek-long+}
78+
- The contention factor (if you are using the ``INDEXED`` algorithm)
79+
- The query type defined for your field (if you are using the ``INDEXED`` algorithm)
80+
81+
.. note:: Query Types
82+
83+
The query type only applies when the algorithm is set to ``INDEXED``.
84+
85+
To learn more about query types, see :ref:`qe-query-types`.
86+
87+
.. TODO: Need tech review on this section to ensure correctness and potentially add details
88+
89+
Algorithm Choice
90+
````````````````
91+
92+
If you specify a ``queryType`` on a field, use the ``Indexed`` algorithm to encrypt and decrypt that field.
93+
94+
.. _qe-fundamentals-manual-encryption-automatic-decryption:
95+
96+
Automatic Decryption
97+
~~~~~~~~~~~~~~~~~~~~
98+
99+
To decrypt your fields automatically, you must configure your
100+
``MongoClient`` instance as follows:
101+
102+
- Specify a ``kmsProviders`` object
103+
- Specify your {+key-vault-long+}
104+
- If you use MongoDB Community Server, set the ``bypassQueryAnalysis``
105+
option to ``True``
106+
107+
.. note:: Automatic Decryption is Available in MongoDB Community Server
108+
109+
Although automatic encryption requires MongoDB Enterprise or MongoDB
110+
Atlas, automatic decryption is available in the following MongoDB
111+
products using version 6.0 or later:
112+
113+
- MongoDB Community Server
114+
- MongoDB Enterprise Advanced
115+
- MongoDB Atlas
116+
117+
.. _qe-fundamentals-manual-encryption-server-side-schema:
118+
119+
Server-Side Field Level Encryption Enforcement
120+
----------------------------------------------
121+
122+
You can also :ref:`qe-specify-fields-for-encryption` to enforce
123+
encryption of specific fields in a collection.
124+
125+
A client performing {+qe+} with the {+manual-enc+}
126+
mechanism on a MongoDB instance configured to enforce encryption
127+
of certain fields must encrypt those fields as specified on
128+
the MongoDB instance.
129+
130+
To learn how to set up server-side {+qe+}
131+
enforcement, see :ref:`qe-fundamentals-encrypt-query`.
132+
133+
Learn More
134+
----------
135+
136+
To learn more about {+key-vault-long+}s, {+dek-long+}s, and {+cmk-long+}s,
137+
see :ref:`csfle-reference-keys-key-vaults`.
138+
139+
To learn more about {+kms-abbr+} providers and ``kmsProviders`` objects,
140+
see :ref:`csfle-reference-kms-providers`.

‎source/includes/fact-manual-enc-definition.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{+manual-enc-first+} is a mechanism in which you specify how you would
2+
like to encrypt and decrypt fields in your document in each operation you
3+
perform on your database.

0 commit comments

Comments
 (0)