(DOCSP-24380) reWrapManyDataKey Update (#1598)

* edits first draft

* wip - bad render

* tweak

* cc - re-wrap to rewrap

* cc - issues

* tweak

* monospace issue

* mw - suggestion

* mw - edits

* mw - suggestion

Author: biniona-mongodb

snooty.toml

@@ -246,6 +246,7 @@ cmk-abbr = ":abbr:`CMK ({+cmk-long+})`"
 dek-long = "Data Encryption Key"
 dek-abbr = ":abbr:`DEK ({+dek-long+})`"
 dek-abbr-no-hover = "DEK"
+cmk-abbr-no-hover = "CMK"
 key-vault-long = "Key Vault collection"
 key-vault-long-title = "Key Vault Collection"
 java-driver-version = "4.6"

source/core/csfle/reference/decryption.txt

@@ -17,6 +17,8 @@ How CSFLE Decrypts Documents
 This page describes how {+csfle-abbrev+} uses metadata from your
 {+dek-long+} and {+cmk-long+} to decrypt data.
 
+.. _csfle-reference-decryption-metadata:
+
 Metadata Used for Decryption
 ----------------------------
 

source/reference/method/KeyVault.rewrapManyDataKey.txt

@@ -14,9 +14,18 @@ KeyVault.rewrapManyDataKey()
 
 .. method:: KeyVault.rewrapManyDataKey(filter, options)
 
-   ``KeyVault.rewrapManyDataKey`` decrypts multiple data 
-   keys and re-encrypts them with a new ``masterKey``. If a new 
-   ``masterKey`` is not given, the current ``masterKey`` is used.
+   Decrypts multiple {+dek-long+}s ({+dek-abbr-no-hover+}) 
+   and re-encrypts them with a new {+cmk-long+} ({+cmk-abbr-no-hover+}).
+   Use this method to rotate the {+cmk-abbr-no-hover+} that encrypts your
+   {+dek-abbr-no-hover+}s. To learn more about {+cmk-abbr-no-hover+}s
+   and {+dek-abbr-no-hover+}s, see :ref:`<csfle-key-architecture>`.
+
+   You specify a {+cmk-abbr-no-hover+} through the ``masterKey`` parameter.
+   If you do not include a ``masterKey`` argument, the method decrypts
+   and encrypts each {+dek-abbr-no-hover+} with the {+cmk-abbr-no-hover+}
+   referenced in that {+dek-abbr-no-hover+}'s metadata. To learn more about
+   the metadata of {+dek-abbr-no-hover+}s, see
+   :ref:`<csfle-reference-decryption-metadata>`.
 
    ``KeyVault.rewrapManyDataKey`` has the following syntax:
 
@@ -43,7 +52,7 @@ KeyVault.rewrapManyDataKey()
 
         - :ref:`query filter document <document-query-filter>` 
 
-        - The query filter for the keyvault collection.
+        - The query filter for the keyvault collection
 
       * - ``options``
 
@@ -56,7 +65,7 @@ KeyVault.rewrapManyDataKey()
             <qe-fundamentals-kms-providers>` (AWS KMS, Azure Key Vault, 
             GCP KMS, the local provider, or KMIP)
           - ``masterKey``: A KMS-specific key used to encrypt the new 
-            data key.
+            data key
 
    :returns:
 
@@ -96,14 +105,14 @@ encryption. For specific examples using each supported
 .. include:: /includes/extracts/csfle-connection-boilerplate.rst
 
 Retrieve the :method:`KeyVault <getKeyVault()>` object and use the
-:method:`KeyVault.rewrapManyDataKey` method to re-wrap the existing
+:method:`KeyVault.rewrapManyDataKey` method to rewrap the existing
 keys in a new ``masterKey``. If no new ``masterKey`` is given, each
 data key retains its respective current ``masterKey``. 
 
-Re-wrap Data Keys with Current``masterKey``
+Rewrap Data Keys with Current ``masterKey``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~	
 
-The following example show how you can re-wrap each data key with its 
+The following example shows how you can rewrap each data key with its 
 respective current ``masterKey``:
 
 .. code-block:: javascript
@@ -116,7 +125,7 @@ Migrate to a New ``masterKey``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~	
 
 The following example shows how you can use 
-:method:KeyVault.rewrapManyDataKey()` to migrate to a new ``masterKey``:
+:method:`KeyVault.rewrapManyDataKey()` to migrate to a new ``masterKey``:
 
 .. code-block:: javascript
 
@@ -130,11 +139,11 @@ The following example shows how you can use
      }
    })
 
-Re-wrap Data Keys that have not been Re-wrapped Recently
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Rewrap Data Keys That Have Not Been Rewrapped Recently
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following example shows how to re-wrap data keys that have not
-been re-wrapped in the previous thirty days.
+The following example shows how to rewrap data keys that have not
+been rewrapped in the previous thirty days.
 
 .. code-block:: javascript
 

source/reference/method/js-client-side-field-level-encryption.txt

@@ -77,6 +77,7 @@ client-side field level encryption.
    /reference/method/KeyVault.addKeyAlternateName
    /reference/method/KeyVault.removeKeyAlternateName
    /reference/method/KeyVault.getKeyByAltName
+   /reference/method/KeyVault.rewrapManyDataKey
    /reference/method/getClientEncryption
    /reference/method/ClientEncryption.encrypt
    /reference/method/ClientEncryption.decrypt