DOCSP-27783 updates TEST_LOCAL_KEY examples to more securely use process.env (#2487)

jmd-mongo · web-flow · commit 6cfb955bb8ea · 2023-02-03T09:27:14.000-08:00
* DOCSP-27783 * internal review feedback
diff --git a/source/includes/csfle-connection-boilerplate-example.rst b/source/includes/csfle-connection-boilerplate-example.rst
@@ -0,0 +1,40 @@
+To configure client-side field level encryption for a locally managed
+key:
+
+- generate a base64-encoded 96-byte string with no line breaks
+- use :binary:`mongosh` to load the key
+
+.. code-block:: bash
+   :emphasize-lines: 1
+
+   export TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
+
+   mongosh --nodb
+
+Create the client-side field level encryption object using the
+generated local key string:
+
+.. code-block:: javascript
+   :emphasize-lines: 5
+
+    var autoEncryptionOpts = {
+      "keyVaultNamespace" : "encryption.__dataKeys",
+      "kmsProviders" : {
+        "local" : {
+          "key" : BinData(0, process.env["TEST_LOCAL_KEY"])
+        }
+      }
+    }
+
+Use the :method:`Mongo()` constructor with the client-side field level 
+encryption options configured to create a database connection. Replace 
+the ``mongodb://myMongo.example.net`` URI with the :ref:`connection 
+string URI <mongodb-uri>` of the target cluster.
+
+.. code-block:: javascript
+   :emphasize-lines: 2
+      
+   encryptedClient = Mongo( 
+     "mongodb://myMongo.example.net:27017/?replSetName=myMongo", 
+      autoEncryptionOpts
+   )
diff --git a/source/includes/extracts-client-side-field-level-encryption.yaml b/source/includes/extracts-client-side-field-level-encryption.yaml
@@ -68,50 +68,6 @@ content: |
   variables in the shell to reference the AWS credentials.
 
 ---
-ref: csfle-connection-boilerplate
-content: |
-
-  Configuring client-side field level encryption for a locally
-  managed key requires specifying a base64-encoded 96-byte
-  string with no line breaks. The following operation generates
-  a key that meets the stated requirements and loads it into
-  :binary:`~bin.mongosh`:
-
-  .. code-block:: bash
-     :emphasize-lines: 1
-
-     TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
-     
-     mongosh --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"
-
-  Create the client-side field level encryption object using the
-  generated local key string:
-
-  .. code-block:: javascript
-     :emphasize-lines: 5
-
-     var autoEncryptionOpts = {
-       "keyVaultNamespace" : "encryption.__dataKeys",
-       "kmsProviders" : {
-         "local" : {
-           "key" : BinData(0, TEST_LOCAL_KEY)
-         }
-       }
-     }
-
-  Use the :method:`Mongo()` constructor to create a database connection
-  with the client-side field level encryption options. Replace the
-  ``mongodb://myMongo.example.net`` URI with the :ref:`connection string
-  URI <mongodb-uri>` of the target cluster.
-
-  .. code-block:: javascript
-     :emphasize-lines: 2
-       
-     encryptedClient = Mongo( 
-       "mongodb://myMongo.example.net:27017/?replSetName=myMongo", 
-       autoEncryptionOpts
-     )
----
 ref: csfle-enterprise-atlas-only
 content: |
 
diff --git a/source/reference/method/ClientEncryption.decrypt.txt b/source/reference/method/ClientEncryption.decrypt.txt
@@ -54,7 +54,7 @@ Example
 The following example uses a locally managed KMS for the client-side
 field level encryption configuration.
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Retrieve the :method:`ClientEncryption <getClientEncryption()>` object
 and use the :method:`ClientEncryption.decrypt()` method to decrypt
diff --git a/source/reference/method/ClientEncryption.encrypt.txt b/source/reference/method/ClientEncryption.encrypt.txt
@@ -174,7 +174,7 @@ Client-Side Field Level Encryption
 The following example uses a locally managed KMS for the client-side
 field level encryption configuration.
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Retrieve the :method:`ClientEncryption <getClientEncryption()>` object
 and use the :method:`ClientEncryption.encrypt()` method to encrypt
diff --git a/source/reference/method/KeyVault.addKeyAlternateName.txt b/source/reference/method/KeyVault.addKeyAlternateName.txt
@@ -60,7 +60,7 @@ client-side field level encryption. For specific examples of using
 :abbr:`KMS (Key Management Service)` provider, see
 :ref:`field-level-encryption-data-key-manage`.
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Retrieve the :method:`KeyVault <getKeyVault()>` object and use the
 :method:`KeyVault.addKeyAlternateName()` method to add a new key
diff --git a/source/reference/method/KeyVault.createKey.txt b/source/reference/method/KeyVault.createKey.txt
@@ -182,7 +182,7 @@ client-side field level encryption. For specific examples of using
 :abbr:`KMS (Key Management Service)` provider, see
 :ref:`qe-field-level-encryption-data-key-create`.
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Retrieve the :method:`keyVault <getKeyVault()>` object and
 use the :method:`KeyVault.createKey()` method to 
diff --git a/source/reference/method/KeyVault.deleteKey.txt b/source/reference/method/KeyVault.deleteKey.txt
@@ -49,7 +49,7 @@ client-side field level encryption. For specific examples of using
 :abbr:`KMS (Key Management Service)` provider, see
 :ref:`field-level-encryption-data-key-delete`.
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Retrieve the :method:`KeyVault <getKeyVault()>` object and
 use the :method:`KeyVault.deleteKey()` method to 
diff --git a/source/reference/method/KeyVault.getKey.txt b/source/reference/method/KeyVault.getKey.txt
@@ -54,7 +54,7 @@ The following example uses a :ref:`locally managed KMS
 <field-level-encryption-local-kms>` for the client-side field level
 encryption configuration. 
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Retrieve the :method:`keyVault <getKeyVault()>` object and
 use the :method:`KeyVault.getKey()` to retrieve
diff --git a/source/reference/method/KeyVault.getKeyByAltName.txt b/source/reference/method/KeyVault.getKeyByAltName.txt
@@ -48,7 +48,7 @@ Example
 The following example uses a locally managed KMS for the client-side
 field level encryption configuration. 
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Retrieve the :method:`KeyVault <getKeyVault()>` object and use the
 :method:`KeyVault.getKeyByAltName()` method to retrieve the data
diff --git a/source/reference/method/KeyVault.getKeys.txt b/source/reference/method/KeyVault.getKeys.txt
@@ -48,7 +48,7 @@ The following example uses a :ref:`locally managed KMS
 <field-level-encryption-local-kms>` for the client-side field level
 encryption configuration. 
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Retrieve the :method:`KeyVault <getKeyVault()>` object and use the
 :method:`KeyVault.getKeys()` method to retrieve all data encryption keys
diff --git a/source/reference/method/KeyVault.removeKeyAlternateName.txt b/source/reference/method/KeyVault.removeKeyAlternateName.txt
@@ -52,7 +52,7 @@ client-side field level encryption. For specific examples of using
 :abbr:`KMS (Key Management Service)` provider, see
 :ref:`field-level-encryption-data-key-manage`.
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Retrieve the :method:`keyVault <getKeyVault()>` object and use the
 :method:`KeyVault.removeKeyAlternateName()` method to remove the
diff --git a/source/reference/method/KeyVault.rewrapManyDataKey.txt b/source/reference/method/KeyVault.rewrapManyDataKey.txt
@@ -102,7 +102,7 @@ encryption. For specific examples using each supported
 :abbr:`KMS (Key Management Service)` provider, see
 :ref:`field-level-encryption-data-key-manage`.
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Retrieve the :method:`KeyVault <getKeyVault()>` object and use the
 :method:`KeyVault.rewrapManyDataKey` method to rewrap the existing
diff --git a/source/reference/method/Mongo.txt b/source/reference/method/Mongo.txt
@@ -316,41 +316,7 @@ Issue operations against the ``cluster`` object to interact with the
 Connect to a Cluster with Client-Side Encryption Enabled
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Configuring client-side field level encryption for a :ref:`locally
-managed key <field-level-encryption-local-kms>` requires specifying a
-base64-encoded 96-byte string with no line breaks. The following
-operation generates a key that meets the stated requirements and loads
-it into :binary:`~bin.mongosh`:
-
-.. code-block:: bash
-   :emphasize-lines: 1
-
-   TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
-
-   mongosh --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"
-
-The following operation creates a new connection object from within a
-:binary:`~bin.mongosh` session. The
-:ref:`{+auto-encrypt-options+}` option specifies
-the required options for enabling client-side field level encryption
-using a locally managed key:
-
-.. code-block:: javascript
-   :emphasize-lines: 4-6, 10-13
-
-   var autoEncryptionOpts = {
-     "keyVaultNamespace" : "encryption.dataKeys",
-     "kmsProviders" : {
-       "local" : {
-         "key" : BinData(0, TEST_LOCAL_KEY)
-       }
-     }
-   }
-
-   cluster = Mongo(
-     "mongodb://mymongo.example.net:27017/?replicaSet=myMongoCluster",
-     autoEncryptionOpts
-   )
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Issue operations against the ``cluster`` object to interact with the
 ``mymongo.example.net:27017`` cluster and perform explicit encryption:
@@ -377,18 +343,18 @@ a complete list of client-side field level encryption methods.
 Connect to a Cluster with Automatic Client-Side Encryption Enabled
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Configuring client-side field level encryption for a :ref:`locally
-managed key <field-level-encryption-local-kms>` requires specifying a
-base64-encoded 96-byte string with no line breaks. The following
-operation generates a key that meets the stated requirements and loads
-it into :binary:`~bin.mongosh`:
+To configure client-side field level encryption for a locally managed
+key:
+
+- generate a base64-encoded 96-byte string with no line breaks
+- use :binary:`mongosh` to load the key
 
 .. code-block:: bash
    :emphasize-lines: 1
 
-   TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
+   export TEST_LOCAL_KEY=$(echo "$(head -c 96 /dev/urandom | base64 | tr -d '\n')")
 
-   mongosh --nodb --shell --eval "var TEST_LOCAL_KEY='$TEST_LOCAL_KEY'"
+   mongosh --nodb
 
 The following operation creates a new connection object from within a
 :binary:`~bin.mongosh` session. The
@@ -400,10 +366,10 @@ the required options for enabling :ref:`automatic client-side encryption
    :emphasize-lines: 4-6, 8-21, 24-27
 
    var autoEncryptionOpts = {
-     "keyVaultNamespace" : "encryption.dataKeys",
+     "keyVaultNamespace" : "encryption.__dataKeys",
      "kmsProviders" : {
        "local" : {
-         "key" : BinData(0,"BASE64-ENCODED-96-BYTE-LOCAL-KEY")
+         "key" : BinData(0, process.env["TEST_LOCAL_KEY"])
        }
      },
      schemaMap : {
diff --git a/source/reference/method/getClientEncryption.txt b/source/reference/method/getClientEncryption.txt
@@ -51,7 +51,7 @@ Example
 The following example uses a locally managed KMS for the client-side
 field level encryption configuration.
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Use the :method:`getClientEncryption()` method to
 retrieve the client encryption object:
diff --git a/source/reference/method/getKeyVault.txt b/source/reference/method/getKeyVault.txt
@@ -63,7 +63,7 @@ The following example uses a :ref:`locally managed key
 <field-level-encryption-local-kms>` for the client-side field level
 encryption configuration. 
 
-.. include:: /includes/extracts/csfle-connection-boilerplate.rst
+.. include:: /includes/csfle-connection-boilerplate-example.rst
 
 Use the :method:`getKeyVault()` method to retrieve the
 key vault object:
