Merge pull request #95 from andf-mongodb/DOCSP-15145-minor-updates-csfle-section

DOCSP-15145 minor updates to csfle section

Author: andf-mongodb

source/field-level-encryption.txt

@@ -40,25 +40,25 @@ appropriate for your deployment:
 
 .. tabs::
 
-   .. tab:: Amazon KMS
+   .. tab:: Amazon Web Services KMS
       :tabid: aws-kms
 
-      .. include:: /includes/steps/aws-kms.rst
+      .. include:: /includes/steps/createkey-aws-kms.rst
 
    .. tab:: Azure Key Vault
       :tabid: azure-vault
 
-      .. include:: /includes/steps/azure-vault.rst
+      .. include:: /includes/steps/createkey-azure-vault.rst
 
    .. tab:: Google Cloud KMS
       :tabid: gcp-kms
 
-      .. include:: /includes/steps/gcp-kms.rst
+      .. include:: /includes/steps/createkey-gcp-kms.rst
 
    .. tab:: Local Keyfile
       :tabid: local-keyfile
 
-      .. include:: /includes/steps/local-keyfile.rst
+      .. include:: /includes/steps/createkey-local-keyfile.rst
 
 .. seealso::
 

source/includes/steps-aws-kms.yaml renamed to source/includes/steps-createkey-aws-kms.yaml

@@ -89,16 +89,29 @@ content: |
 
      keyVault.createKey(
        "aws",
-       { region: "regionname", key: "awsarn" }
+       { region: "regionname", key: "awsarn" },
+       [ "keyAlternateName" ]
      )
 
   Where:
-  
-  - ``regionname`` is the AWS region you are connecting to, such as
-    ``us-west-2``
-  - ``awsarn`` is the `Amazon Resource Name (ARN)
-    <https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html>`__
-    to the AWS customer master key (CMK).
+
+  - The first parameter *must* be ``"aws"`` to specify the configured
+    Amazon Web Services KMS.
+
+  - The second parameter *must* be a document containing the following:
+
+    - the AWS region you are connecting to, such as ``us-west-2``
+
+    - the `Amazon Resource Name (ARN)
+      <https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html>`__
+      to the AWS customer master key (CMK).
+
+  - The third parameter *may* be an array of one or more
+    ``keyAltNames`` for the data encryption key. Each key alternate
+    name *must* be unique. :method:`getKeyVault()` creates a
+    :ref:`unique index <index-type-unique>` on ``keyAltNames`` to
+    enforce uniqueness on the field if one does not already exist. Key
+    alternate names facilitate data encryption key findability.
 
   .. include:: /includes/fact-getkey-options.rst
 ...

source/includes/steps-azure-vault.yaml renamed to source/includes/steps-createkey-azure-vault.yaml

@@ -88,14 +88,28 @@ content: |
 
      keyVault.createKey(
        "azure",
-       { keyName: "keyvaultname", keyVaultEndpoint: "endpointname" }
+       { keyName: "keyvaultname", keyVaultEndpoint: "endpointname" },
+       [ "keyAlternateName" ]
      )
 
   Where:
+
+  - The first parameter *must* be ``"azure"`` to specify the configured
+    Azure Key Vault.
+
+  - The second parameter *must* be a document containing:
   
-  - ``keyvaultname`` is the name of your `Azure Key Vault
-    <https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#vault-name-and-object-name>`__
-  - ``endpointname`` is the name of the Key Vault Endpoint to use
+    - the name of your `Azure Key Vault
+      <https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#vault-name-and-object-name>`__
+    - the DNS name of the Azure Key Vault to use (e.g.
+      ``my-key-vault.vault.azure.net``)
+
+  - The third parameter *may* be an array of one or more
+    ``keyAltNames`` for the data encryption key. Each key alternate
+    name *must* be unique. :method:`getKeyVault()` creates a
+    :ref:`unique index <index-type-unique>` on ``keyAltNames`` to
+    enforce uniqueness on the field if one does not already exist. Key
+    alternate names facilitate data encryption key findability.
 
   .. include:: /includes/fact-getkey-options.rst
 ...

source/includes/steps-gcp-kms.yaml renamed to source/includes/steps-createkey-gcp-kms.yaml

@@ -91,18 +91,31 @@ content: |
          location: "locationname",
          keyRing: "keyringname",
          keyName: "keyname"
-       }
+       },
+       [ "keyAlternateName" ]
      )
 
   Where:
-  
-  - ``projectid`` is the name of your GCP project, such as
-    ``my-project``
-  - ``locationname`` is the location of the KMS keyring, such as
-    ``global``
-  - ``keyringname`` is the name of the KMS keyring, such as
-    ``my-keyring``
-  - ``keyname`` is the name of your key.
+
+  - The first parameter *must* be ``"gcp"`` to specify the configured
+    Google Cloud KMS.
+
+  - The second parameter *must* be a document containing
+
+    - ``projectid`` is the name of your GCP project, such as
+      ``my-project``
+    - ``locationname`` is the location of the KMS keyring, such as
+      ``global``
+    - ``keyringname`` is the name of the KMS keyring, such as
+      ``my-keyring``
+    - ``keyname`` is the name of your key.
+
+  - The third parameter *may* be an array of one or more
+    ``keyAltNames`` for the data encryption key. Each key alternate
+    name *must* be unique. :method:`getKeyVault()` creates a
+    :ref:`unique index <index-type-unique>` on ``keyAltNames`` to
+    enforce uniqueness on the field if one does not already exist. Key
+    alternate names facilitate data encryption key findability.
 
   .. include:: /includes/fact-getkey-options.rst
 ...

source/includes/steps-local-keyfile.yaml renamed to source/includes/steps-createkey-local-keyfile.yaml

@@ -94,8 +94,20 @@ content: |
 
       keyVault.createKey(
         "local",
-        ["keyAltName"]
+        [ "keyAlternateName" ]
       )
 
+  Where:
+
+  - The first parameter *must* be ``local`` to specify the configured
+    Locally Managed Key.
+
+  - The second parameter *may* be an array of one or more
+    ``keyAltNames`` for the data encryption key. Each key alternate
+    name *must* be unique. :method:`getKeyVault()` creates a unique
+    index on ``keyAltNames`` to enforce uniqueness on the field if
+    one does not already exist. Key alternate names facilitate data
+    encryption key findability.
+
   .. include:: /includes/fact-getkey-options.rst
 ...