DOCSP-23206 QE Manual Encryption Page (Updated PR) (#1698)

* 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

* tech review updates

* removes reference/mongo from snooty.toml

* re-adds reference/mongo to snooty.toml

* resets snooty.toml to master branch version

Author: jmd-mongo

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

@@ -20,6 +20,8 @@ Overview
 Learn how to use the **{+manual-enc+}** mechanism of {+csfle+}
 ({+csfle-abbrev+}).
 
+.. include:: /includes/fact-manual-enc-definition.rst
+
 {+manual-enc-first+} is a mechanism in which you specify how you would
 like to encrypt and decrypt fields in your document in each operation you
 perform on your database.
@@ -224,4 +226,4 @@ To learn more about {+key-vault-long+}s, {+dek-long+}s, and {+cmk-long+}s,
 see :ref:`csfle-reference-keys-key-vaults`.
 
 To learn more about {+kms-abbr+} providers and ``kmsProviders`` objects,
-see :ref:`csfle-reference-kms-providers`.
+see :ref:`csfle-reference-kms-providers`.

source/core/queryable-encryption.txt

@@ -67,12 +67,6 @@ mechanisms:
      - | No
      - | Yes
 
-.. important:: No Documentation on {+manual-enc-title+}
-
-   At present, we do not have documentation detailing how to perform
-   {+manual-enc+} with {+qe+}. We will publish documentation for
-   this feature soon.
-
 To learn which MongoDB drivers support {+qe+}, see
 :ref:`qe-compatibility-reference`.
 

source/core/queryable-encryption/fundamentals.txt

@@ -18,13 +18,15 @@ Read the following sections to learn how {+qe+} works and how to use it:
 - :ref:`qe-fundamentals-collection-management`
 - :ref:`qe-reference-keys-key-vaults`
 - :ref:`qe-fundamentals-manage-keys`
+- :ref:`qe-fundamentals-manual-encryption`
 - :ref:`qe-fundamentals-kms-providers`
 
 .. toctree::
    :titlesonly:
 
    /core/queryable-encryption/fundamentals/encrypt-and-query
    /core/queryable-encryption/fundamentals/manage-collections
+   /core/queryable-encryption/fundamentals/manual-encryption    
    /core/queryable-encryption/fundamentals/keys-key-vaults
    /core/queryable-encryption/fundamentals/manage-keys
    /core/queryable-encryption/fundamentals/kms-providers

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

@@ -22,6 +22,8 @@ In this guide, you can learn about the following {+qe+} topics:
 - Query types and which ones you can use on encrypted fields.
 - What to consider when deciding whether to enable queries on an encrypted field.
 
+.. _qe-specify-fields-for-encryption:
+
 Specify Fields for Encryption
 -----------------------------
 

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

@@ -0,0 +1,150 @@
+.. _qe-fundamentals-manual-encryption:
+
+=================
+{+manual-enc-title+}
+=================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+Learn how to use the **{+manual-enc+}** mechanism of {+qe+}.
+
+.. include:: /includes/fact-manual-enc-definition.rst
+
+{+manual-enc-first+} is available in the following MongoDB products
+using version 6.0 or later:
+
+- MongoDB Community Server
+- MongoDB Enterprise Advanced
+- MongoDB Atlas
+
+Use {+manual-enc-title+}
+---------------------
+
+The following sections provide an overview of using {+manual-enc+} in 
+your {+qe+}-enabled application:
+
+- :ref:`qe-fundamentals-manual-encryption-client-enc`
+- :ref:`qe-fundamentals-manual-encryption-update-operations`
+- :ref:`qe-fundamentals-manual-encryption-automatic-decryption`
+
+.. _qe-fundamentals-manual-encryption-client-enc:
+
+Create a ``ClientEncryption`` Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``ClientEncryption`` is an abstraction used across drivers and
+:binary:`~bin.mongosh` that encapsulates the {+key-vault-long+}
+and {+kms-abbr+} operations involved in {+manual-enc+}.
+
+To create a ``ClientEncryption`` instance, specify:
+
+- A ``kmsProviders`` object configured with access to the
+  {+kms-abbr+} hosting your {+cmk-long+}
+- The namespace of your {+key-vault-long+}
+- If you use MongoDB Community Server, set the ``bypassQueryAnalysis``
+  option to ``True``
+- A ``MongoClient`` instance with access to your {+key-vault-long+}
+
+For more ``ClientEncryption`` options, see :ref:`qe-reference-mongo-client`. 
+
+.. note::
+
+   Code examples are not currently available but are coming soon.
+
+.. _qe-fundamentals-manual-encryption-update-operations:
+
+Encrypt Fields in Read and Write Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You must update read and write operations throughout your application
+such that your application encrypts fields before performing
+read and write operations.
+
+To encrypt fields, use the ``encrypt`` method of your ``ClientEncryption``
+instance. Specify the following:
+
+- The value to be encrypted
+- The algorithm used, either ``Indexed`` or ``Unindexed``
+- The ID of the {+dek-long+}
+- The contention factor (if you are using the ``Indexed`` algorithm)
+- If performing a read operation, set the query type defined for your 
+  field (if you are using the ``Indexed`` algorithm)
+
+.. note:: Query Types
+
+   The query type only applies to read operations.
+
+   To learn more about query types, see :ref:`qe-query-types`. 
+
+.. TODO: Need tech review on this section to ensure correctness and potentially add details
+
+Algorithm Choice
+````````````````
+
+Use the ``Indexed`` algorithm if you specify a ``queryType`` on the 
+field.
+
+``Indexed`` supports equality queries. ``Indexed`` fields require an 
+index on the server. The index is created by specifying the 
+``encryptedFields`` option in :method:`db.createCollection()`. 
+
+.. _qe-fundamentals-manual-encryption-automatic-decryption:
+
+Automatic Decryption
+~~~~~~~~~~~~~~~~~~~~
+
+To decrypt your fields automatically, you must configure your
+``MongoClient`` instance as follows:
+
+- Specify a ``kmsProviders`` object
+- Specify your {+key-vault-long+}
+- If you use MongoDB Community Server, set the ``bypassQueryAnalysis``
+  option to ``True``
+
+.. note:: Automatic Decryption is Available in MongoDB Community Server
+
+   Although automatic encryption requires MongoDB Enterprise or MongoDB
+   Atlas, automatic decryption is available in the following MongoDB
+   products using version 6.0 or later:
+
+   - MongoDB Community Server
+   - MongoDB Enterprise Advanced
+   - MongoDB Atlas
+
+.. _qe-fundamentals-manual-encryption-server-side-schema:
+
+Server-Side Field Level Encryption Enforcement
+----------------------------------------------
+
+:ref:`qe-specify-fields-for-encryption` to enforce 
+encryption of specific fields in a collection.
+
+``Indexed`` fields require an index on the server. The index is created 
+by specifying the ``encryptedFields`` option in 
+:method:`db.createCollection()`.
+
+A client performing {+qe+} with the {+manual-enc+}
+mechanism on a MongoDB instance configured to enforce encryption
+of certain fields must encrypt those fields as specified on
+the MongoDB instance.
+
+To learn how to set up server-side {+qe+}
+enforcement, see :ref:`qe-fundamentals-encrypt-query`.
+
+Learn More
+----------
+
+To learn more about {+key-vault-long+}s, {+dek-long+}s, and {+cmk-long+}s,
+see :ref:`csfle-reference-keys-key-vaults`.
+
+To learn more about {+kms-abbr+} providers and ``kmsProviders`` objects,
+see :ref:`csfle-reference-kms-providers`.

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

@@ -0,0 +1,3 @@
+{+manual-enc-first+} is a mechanism in which you specify how you would
+like to encrypt and decrypt fields in your document in each operation you
+perform on your database.