DOCSP-22090 Key Rotation Content (#1415)

* adding key rotation content

* moved admonition

* update

* fix warning box

* feedback

Author: jordan-smith721

source/core/csfle/fundamentals/manage-keys.txt

@@ -266,10 +266,111 @@ As a result, the ``salary`` fields in the two example documents are
 uniquely encrypted using {+dek-long+}s specific to the individual
 document. The keys are assigned dynamically at runtime.
 
+.. _csfle_fundamentals_rotate_keys:
+
+Rotate Encryption Keys
+----------------------
+
+Key rotation is the process of retiring an existing encryption key and replacing 
+it with a new one. Regularly rotating encryption keys is considered a best practice.
+
+Rotate a {+cmk-long+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To rotate a {+cmk-long+} (CMK), you must perform the following actions:
+
+#. Decrypt all data using the {+dek-long+}s encrypted with your
+   previous CMK.
+   To learn more about decrypting your data, see :ref:`csfle-fundamentals-manual-encryption-manual-decryption`.
+#. Create a new CMK.
+#. Create new {+dek-long+}s using the new CMK.
+#. Encrypt your data with the new {+dek-long+}s that were created with your
+   new CMK.
+
+.. warning:: Don't Delete Keys Until the Rotation is Complete
+
+   Ensure you keep both your previous and new CMKs and
+   {+dek-long+}s until the rotation is complete. If you delete your
+   previous CMK before the rotation is complete, you will lose
+   all data with {+dek-long+}s that are still encrypted with your previous CMK. 
+   If you delete a previous {+dek-long+} before your rotation is complete, 
+   you risk losing data still encrypted with that {+dek-long+}.
+
+.. warning:: Switching from locally-managed master key to a remote KMS
+
+   Before you switch from a locally-managed master key to a remote KMS,
+   you must decrypt all documents containing field-encrypted data. 
+   Your existing data encryption keys can only be decrypted with the original
+   locally-managed master key and not the CMK that the KMS generates.
+
+   Failure to decrypt all data at this stage may cause permanent and
+   unrecoverable data loss.
+
+``mongosh`` provides a helper method to rotate your CMKs. To learn more, see
+:ref:`csfle-rotate-keys-mongo-shell`.
+
+Rotate a {+dek-long+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To rotate a {+dek-long+} (DEK), you must perform the following actions:
+
+#. Decrypt all data encrypted with that DEK.
+   To learn more about decrypting your data, see :ref:`csfle-fundamentals-manual-encryption-manual-decryption`.
+#. Create a new DEK.
+#. Encrypt your decrypted data with the new DEK.
+
+.. warning:: Don't Delete Keys Until the Rotation is Complete
+
+   Ensure you keep both your previous and new DEK until the rotation
+   is complete. If you delete your previous DEK before the rotation
+   is complete, you will lose all data still encrypted with that DEK.
+
+``mongosh`` provides a helper method to rotate your DEKs. To learn more, see
+:ref:`csfle-rotate-keys-mongo-shell`.
+
+.. _csfle-rotate-keys-mongo-shell:
+
+Procedure: Rotate Encryption Keys Using Mongo Shell
+---------------------------------------------------
+
+With version 1.5 and later of the Mongo Shell, you can rotate encryption keys 
+using the ``rewrapManyDataKey`` method. The ``rewrapManyDataKey`` method 
+automatically decrypts multiple data keys and re-encrypts them using a specified 
+{+cmk-long+} (CMK). It then updates the rotated keys in the key vault collection.
+This method allows you to rotate encryption keys based on two optional arguments:
+
+- A filter used to specify which keys to rotate. If no data key matches
+  the given filter, no keys will be rotated. Omit the filter to rotate all keys 
+  in your key vault collection.
+
+- An object that represents a new CMK. Omit this object to rotate
+  the data keys using their current CMKs.
+
+The ``rewrapManyDataKey`` uses the following syntax:
+
+.. code-block:: json
+
+   keyVault = db.getKeyVault()
+
+   keyVault.rewrapManyDataKey(
+      { 
+         "<Your custom filter>" 
+      },
+      {
+         provider: "<KMS provider>",
+         masterKey: {
+            "<dataKeyOpts Key>" : "<dataKeyOpts Value>"
+         }
+      }
+   )
+
+To learn more about the ``dataKeyOpts`` object for your KMS provider, see 
+:ref:`csfle-reference-kms-providers-supported-kms`.
+
 .. _field-level-encryption-data-key-delete:
 
 Delete a {+dek-long+}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 You can delete a {+dek-abbr+} from your {+key-vault-long+} using standard CRUD
 :ref:`delete operations <write-op-delete>`.