(DOCSP-24764) QE Explicit Encryption Tutorial (#1693)

* tutorial init

* build errors

* update java file names in qe

* remove incorrectly committed files

* fix build files

* capitalize built java files

* python tweaks

* remove extra line

* proofread

* cc - feedback

* cc - feedback

* cc - feedback

* cc - feedback

* build error

* build error

* variable name fixes

* nl - suggestion

* nl - suggestion

* move exp tut out of exp directory

* remove unused keys

* remove extra keys go

* remove extra keys java

* remove extra keys node

* remove extra keys python

* cc feedback

* cc - output should not be copyable

* add link to learn more about algorithms

* clarify links

* cc - suggestion

Author: biniona-mongodb

snooty.toml

@@ -257,9 +257,9 @@ aws-long = "Amazon Web Services"
 azure-kv = "Azure Key Vault"
 gcp-kms = "Google Cloud Key Management Service"
 gcp-kms-abbr = "Google Cloud KMS"
-manual-enc = "manual encryption"
-manual-enc-title = "Manual Encryption"
-manual-enc-first = "Manual encryption"
+manual-enc = "explicit encryption"
+manual-enc-title = "Explicit Encryption"
+manual-enc-first = "Explicit encryption"
 kmip-hover = ":abbr:`KMIP (Key Management Interoperability Protocol)`"
 kmip-kms-no-hover = "KMIP-compliant Key Management System"
 kmip-kms = "{+kmip-hover+}-compliant {+kms-abbr+}"

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

@@ -1,8 +1,8 @@
 .. _csfle-fundamentals-manual-encryption:
 
-=================
+===================
 {+manual-enc-title+}
-=================
+===================
 
 .. default-domain:: mongodb
 
@@ -32,7 +32,7 @@ of version 4.2 or later:
 - MongoDB Atlas
 
 Use {+manual-enc-title+}
----------------------
+-----------------------
 
 To use {+manual-enc+} you must perform the following actions in your
 {+csfle-abbrev+}-enabled application:

source/core/queryable-encryption/quick-start.txt

@@ -26,15 +26,7 @@ and software:
 - A working, but not production-ready, client application that
   utilizes automatic {+qe+}.
 
-.. important:: Do Not Use this Application In Production
-
-   Since this example application stores an encryption key on your
-   application's filesystem, you risk unauthorized access to the key or
-   loss of the key to decrypt your data.
-
-   To view a tutorial that demonstrates how to create a production-ready
-   {+qe+} enabled application, see
-   :ref:`<qe-tutorial-automatic-encryption>`.
+.. include:: /includes/queryable-encryption/quick-start/production-warning.rst
 
 .. _qe-guide-intro:
 .. _qe-create-a-master-key:
@@ -120,7 +112,7 @@ Procedure
                :tabid: java-sync
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/java/local/reader/src/main/java/com/mongodb/csfle/makeDataKey.java>`__.
+               `our Github repository <{+sample-app-url-qe+}/java/local/reader/src/main/java/com/mongodb/qe/MakeDataKey.java>`__.
 
             .. tab::
                :tabid: go
@@ -163,7 +155,7 @@ Procedure
                :tabid: java-sync
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/java/local/reader/src/main/java/com/mongodb/csfle/insertEncryptedDocument.java>`__.
+               `our Github repository <{+sample-app-url-qe+}/java/local/reader/src/main/java/com/mongodb/qe/InsertEncryptedDocument.java>`__.
 
             .. tab::
                :tabid: go
@@ -202,7 +194,7 @@ Procedure
                :tabid: java-sync
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/java/local/reader/src/main/java/com/mongodb/csfle/insertEncryptedDocument.java>`__.
+               `our Github repository <{+sample-app-url-qe+}/java/local/reader/src/main/java/com/mongodb/qe/InsertEncryptedDocument.java>`__.
 
             .. tab::
                :tabid: go

source/core/queryable-encryption/tutorials.txt

@@ -30,9 +30,13 @@ Read the following pages to learn how to use {+qe+} with your preferred
 
   - :ref:`qe-tutorial-automatic-gcp`
 
+To learn how to use {+manual-enc+} with {+qe+}, read
+:ref:`<qe-tutorials-manual-encryption>`.
+
 .. toctree::
    :titlesonly:
 
    /core/queryable-encryption/tutorials/aws/aws-automatic
    /core/queryable-encryption/tutorials/azure/azure-automatic
    /core/queryable-encryption/tutorials/gcp/gcp-automatic
+   /core/queryable-encryption/tutorials/explicit-encryption

source/core/queryable-encryption/tutorials/aws/aws-automatic.txt

@@ -102,31 +102,31 @@ Create the Application
                :tabid: nodejs
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/node/aws/reader/make_data_key.js>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/node/aws/reader/make_data_key.js>`__.
 
             .. tab::
                :tabid: python
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/python/aws/reader/make_data_key.py>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/python/aws/reader/make_data_key.py>`__.
 
             .. tab::
                :tabid: java-sync
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/java/aws/reader/src/main/java/com/mongodb/csfle/makeDataKey.java>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/java/aws/reader/src/main/java/com/mongodb/qe/MakeDataKey.java>`__.
 
             .. tab::
                :tabid: go
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/go/aws/reader/make-data-key.go>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/go/aws/reader/make-data-key.go>`__.
 
             .. tab::
                :tabid: csharp
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/dotnet/aws/reader/QueryableEncryption/MakeDataKey.cs>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/dotnet/aws/reader/QueryableEncryption/MakeDataKey.cs>`__.
 
 
    .. step:: Configure your MongoClient for Encrypted Reads and Writes
@@ -145,31 +145,31 @@ Create the Application
                :tabid: nodejs
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/node/aws/reader/insert_encrypted_document.js>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/node/aws/reader/insert_encrypted_document.js>`__.
 
             .. tab::
                :tabid: python
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/python/aws/reader/insert_encrypted_document.py>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/python/aws/reader/insert_encrypted_document.py>`__.
 
             .. tab::
                :tabid: java-sync
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/java/aws/reader/src/main/java/com/mongodb/csfle/insertEncryptedDocument.java>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/java/aws/reader/src/main/java/com/mongodb/qe/InsertEncryptedDocument.java>`__.
 
             .. tab::
                :tabid: go
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/go/aws/reader/insert-encrypted-document.go>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/go/aws/reader/insert-encrypted-document.go>`__.
 
             .. tab::
                :tabid: csharp
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/dotnet/aws/reader/QueryableEncryption/InsertEncryptedDocument.cs>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/dotnet/aws/reader/QueryableEncryption/InsertEncryptedDocument.cs>`__.
 
 
    .. step:: Retrieve Your Encrypted Document
@@ -184,31 +184,31 @@ Create the Application
                :tabid: nodejs
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/node/aws/reader/insert_encrypted_document.js>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/node/aws/reader/insert_encrypted_document.js>`__.
 
             .. tab::
                :tabid: python
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/python/aws/reader/insert_encrypted_document.py>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/python/aws/reader/insert_encrypted_document.py>`__.
 
             .. tab::
                :tabid: java-sync
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/java/aws/reader/src/main/java/com/mongodb/csfle/insertEncryptedDocument.java>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/java/aws/reader/src/main/java/com/mongodb/qe/InsertEncryptedDocument.java>`__.
 
             .. tab::
                :tabid: go
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/go/aws/reader/insert-encrypted-document.go>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/go/aws/reader/insert-encrypted-document.go>`__.
 
             .. tab::
                :tabid: csharp
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/dotnet/aws/reader/QueryableEncryption/InsertEncryptedDocument.cs>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/dotnet/aws/reader/QueryableEncryption/InsertEncryptedDocument.cs>`__.
 
 
 

source/core/queryable-encryption/tutorials/azure/azure-automatic.txt

@@ -101,31 +101,31 @@ Create the Application
                :tabid: nodejs
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/node/azure/reader/make_data_key.js>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/node/azure/reader/make_data_key.js>`__.
 
             .. tab::
                :tabid: python
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/python/azure/reader/make_data_key.py>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/python/azure/reader/make_data_key.py>`__.
 
             .. tab::
                :tabid: java-sync
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/java/azure/reader/src/main/java/com/mongodb/csfle/makeDataKey.java>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/java/azure/reader/src/main/java/com/mongodb/qe/MakeDataKey.java>`__.
 
             .. tab::
                :tabid: go
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/go/azure/reader/make-data-key.go>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/go/azure/reader/make-data-key.go>`__.
 
             .. tab::
                :tabid: csharp
 
                To view the complete code for making a {+dek-long+}, see
-               `our Github repository <{+sample-app-url-qe+}/dotnet/azure/reader/QueryableEncryption/MakeDataKey.cs>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/dotnet/azure/reader/QueryableEncryption/MakeDataKey.cs>`__.
 
 
    .. step:: Configure your MongoClient for Encrypted Reads and Writes
@@ -144,31 +144,31 @@ Create the Application
                :tabid: nodejs
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/node/azure/reader/insert_encrypted_document.js>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/node/azure/reader/insert_encrypted_document.js>`__.
 
             .. tab::
                :tabid: python
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/python/azure/reader/insert_encrypted_document.py>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/python/azure/reader/insert_encrypted_document.py>`__.
 
             .. tab::
                :tabid: java-sync
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/java/azure/reader/src/main/java/com/mongodb/csfle/insertEncryptedDocument.java>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/java/azure/reader/src/main/java/com/mongodb/qe/InsertEncryptedDocument.java>`__.
 
             .. tab::
                :tabid: go
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/go/azure/reader/insert-encrypted-document.go>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/go/azure/reader/insert-encrypted-document.go>`__.
 
             .. tab::
                :tabid: csharp
 
                To view the complete code for inserting an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/dotnet/azure/reader/QueryableEncryption/InsertEncryptedDocument.cs>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/dotnet/azure/reader/QueryableEncryption/InsertEncryptedDocument.cs>`__.
 
 
    .. step:: Retrieve Your Encrypted Document
@@ -183,31 +183,31 @@ Create the Application
                :tabid: nodejs
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/node/azure/reader/insert_encrypted_document.js>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/node/azure/reader/insert_encrypted_document.js>`__.
 
             .. tab::
                :tabid: python
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/python/azure/reader/insert_encrypted_document.py>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/python/azure/reader/insert_encrypted_document.py>`__.
 
             .. tab::
                :tabid: java-sync
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/java/azure/reader/src/main/java/com/mongodb/csfle/insertEncryptedDocument.java>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/java/azure/reader/src/main/java/com/mongodb/qe/InsertEncryptedDocument.java>`__.
 
             .. tab::
                :tabid: go
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/go/azure/reader/insert-encrypted-document.go>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/go/azure/reader/insert-encrypted-document.go>`__.
 
             .. tab::
                :tabid: csharp
 
                To view the complete code for finding an encrypted document, see
-               `our Github repository <{+sample-app-url-qe+}/dotnet/azure/reader/QueryableEncryption/InsertEncryptedDocument.cs>`__.
+               `the {+qe+} sample application repository <{+sample-app-url-qe+}/dotnet/azure/reader/QueryableEncryption/InsertEncryptedDocument.cs>`__.
 
 
 Learn More