DOCSP-19396: CSFLE credential note improvements (#779)

* DOCSP-19396: CSFLE credential note improvements

Author: Chris Cho

source/includes/steps-fle-convert-to-a-remote-master-key-aws.yaml

@@ -74,8 +74,8 @@ content: |
 
   2. Next, add your authentication credentials to your CSFLE-enabled client
      code:
-     
-  .. include:: /includes/substitute-placeholders.rst
+
+  .. include:: /includes/substitute-placeholders-aws.rst
 
   .. tabs-drivers::
 
@@ -93,7 +93,7 @@ content: |
            providerDetails.put("secretAccessKey", awsSecretAccessKey);
 
            kmsProviders.put("aws", providerDetails);
-           
+
      .. tab::
         :tabid: nodejs
 
@@ -197,9 +197,9 @@ content: |
 
   2. Once you have the required information, update and run the following code
      to generate the new data encryption key:
-     
-  .. include:: /includes/substitute-placeholders.rst
-  
+
+  .. include:: /includes/substitute-placeholders-aws-key.rst
+
   .. tabs-drivers::
 
      .. tab::
@@ -269,7 +269,7 @@ content: |
               kms_providers, # pass in the kms_providers from the previous step
               key_vault_namespace
            )
-         
+
            client = MongoClient(connection_string)
            client_encryption = pymongo.encryption.ClientEncryption(
               {

source/includes/steps-fle-convert-to-a-remote-master-key-azure.yaml

@@ -81,7 +81,7 @@ content: |
   2. Next, update the KMS Provider configuration in your CSFLE-enabled client
      creation code:
 
-     .. include:: /includes/substitute-placeholders.rst
+     .. include:: /includes/substitute-placeholders-azure.rst
 
      .. tabs-drivers::
 
@@ -249,8 +249,8 @@ content: |
   2. Once you have the required information, update and run the following code
      to generate a new data encryption key:
 
-     .. include:: /includes/substitute-placeholders.rst
-     
+     .. include:: /includes/substitute-placeholders-azure-key.rst
+
      .. tabs-drivers::
 
         .. tab::

source/includes/steps-fle-convert-to-a-remote-master-key-gcp.yaml

@@ -67,7 +67,7 @@ content: |
      .. list-table::
         :header-rows: 1
         :stub-columns: 1
-        :widths: 30 15 45
+        :widths: 20 12 68
 
         * - Field
           - Required
@@ -79,10 +79,32 @@ content: |
 
         * - privateKey
           - Yes
-          - Identifies your service account private key in either
-            `base64 string <https://en.wikipedia.org/wiki/Base64>`__ or
-            :manual:`Binary subtype 0 <reference/mongodb-extended-json/#bson.Binary>`
-            format.
+          - | Identifies your service account private key in either
+              `base64 string <https://en.wikipedia.org/wiki/Base64>`__ or
+              :manual:`Binary subtype 0 </reference/mongodb-extended-json/#bson.Binary>`
+              format without the prefix and suffix markers.
+            |
+            | Suppose your service account private key value is as follows:
+
+            .. code-block:: none
+               :copyable: false
+
+               -----BEGIN PRIVATE KEY-----\nyour-private-key\n-----END PRIVATE KEY-----\n
+
+            | The value you would specify for this field is:
+
+            .. code-block:: none
+               :copyable: false
+
+               your-private-key
+
+            | If you have a ``user-key.json`` credential file, you can extract
+              the string by executing the following command in a bash or
+              similar shell:
+
+            .. code-block:: shell
+
+               cat user-key.json | jq -r .private_key | openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER | base64 -w 0
 
         * - endpoint
           - No
@@ -91,8 +113,8 @@ content: |
 
   2. Next, add your authentication credentials to your CSFLE-enabled client
      code:
-      
-     .. include:: /includes/substitute-placeholders.rst
+
+     .. include:: /includes/substitute-placeholders-gcp.rst
 
      .. tabs-drivers::
 
@@ -202,7 +224,7 @@ content: |
            .. note::
 
               To use the GCP KMS, you must use
-              `libmongocrypt <https://github.com/mongodb/libmongocrypt>`__ 
+              `libmongocrypt <https://github.com/mongodb/libmongocrypt>`__
               version 1.1 or later in your application's environment.
 
 ---
@@ -258,8 +280,8 @@ content: |
   2. Once you have the required information, update and run the following code
      to generate a new data encryption key:
 
-     .. include:: /includes/substitute-placeholders.rst
-     
+     .. include:: /includes/substitute-placeholders-gcp-key.rst
+
      .. tabs-drivers::
 
         .. tab::
@@ -280,7 +302,7 @@ content: |
                       .append("endpoint", "<GCP KMS API endpoint>"));
 
               BsonBinary dataKeyId = clientEncryption.createDataKey("gcp", dataKeyOptions);
-        
+
         .. tab::
            :tabid: nodejs
 

source/includes/substitute-placeholders-aws-key.rst

@@ -0,0 +1,27 @@
+.. note:: Placeholder Text
+
+   You must substitute all text in quotes and angle brackets with
+   your KMS configuration values.
+
+   For example, the Node.js code prompts you to include a master key value
+   as follows:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      masterKey: {
+        key: "<Master Key ARN>"
+        ...
+      }
+
+
+   If your master key is "arn:aws:kms:us-east-2:111122223333:alias/test-key",
+   substitute the text as follows:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      masterKey: {
+        key: "arn:aws:kms:us-east-2:111122223333:alias/test-key"
+        ...
+      }

source/includes/substitute-placeholders-aws.rst

@@ -0,0 +1,20 @@
+.. note:: Placeholder Text
+
+    You must substitute all text in quotes and angle brackets with
+    your KMS configuration values.
+
+    For example, the Node.js code prompts you to include a private access key
+    id value as follows:
+
+    .. code-block:: javascript
+       :copyable: false
+
+       privateKey: "<IAM User Access Key ID>"
+
+    If your AWS user access key is "23478207027842073230762374023", substitute
+    the text as follows:
+
+    .. code-block:: javascript
+       :copyable: false
+
+       privateKey: "23478207027842073230762374023"

source/includes/substitute-placeholders-azure-key.rst

@@ -0,0 +1,26 @@
+.. note:: Placeholder Text
+
+   You must substitute all text in quotes and angle brackets with
+   your KMS configuration values.
+
+   For example, the Node.js code prompts you to include a key name value
+   as follows:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      azure: {
+        keyName: "<Azure key name>"
+        ...
+      }
+
+   If your Azure master key name is "my-key-name", you should substitute the
+   text as follows:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      azure: {
+        keyName: "my-key-name"
+        ...
+      }

source/includes/substitute-placeholders-azure.rst

@@ -0,0 +1,26 @@
+.. note:: Placeholder Text
+
+    You must substitute all text in quotes and angle brackets with
+    your KMS configuration values.
+
+    For example, the Node.js code prompts you to include a client ID value as
+    follows:
+
+    .. code-block:: javascript
+       :copyable: false
+
+       azure: {
+         clientId: "<Azure client ID>"
+         ...
+       }
+
+    If your Azure client ID is "12345678", you should substitute the text as
+    follows:
+
+    .. code-block:: javascript
+       :copyable: false
+
+       azure: {
+         clientId: "12345678"
+         ...
+       }

source/includes/substitute-placeholders-gcp-key.rst

@@ -0,0 +1,26 @@
+.. note:: Placeholder Text
+
+   You must substitute all text in quotes and angle brackets with
+   your KMS configuration values.
+
+   For example, the Node.js code prompts you to include a key ring value as
+   follows:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      masterKey: {
+        keyRing: "<GCP key ring name>"
+        ...
+      }
+
+   If your GCP key ring is "my-key-ring", you should substitute the text as
+   follows:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      masterKey: {
+        keyRing: "my-key-ring"
+        ...
+      }

source/includes/substitute-placeholders-gcp.rst

@@ -0,0 +1,26 @@
+.. note:: Placeholder Text
+
+   You must substitute all text in quotes and angle brackets with your KMS
+   configuration values.
+
+   For example, the Node.js code prompts you to include a private key value
+   as follows:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      privateKey: "<GCP service account private key>"
+
+   Suppose your GCP service account private key is the following:
+
+   .. code-block:: none
+      :copyable: false
+
+      -----BEGIN PRIVATE KEY-----\nyour-private-key\n-----END PRIVATE KEY-----\n
+
+   Substitute the placeholder text as follows:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      privateKey: "your-private-key"