PYTHON-3517 Add documentation for on-demand KMS providers

doc/changelog.rst

@@ -1,6 +1,23 @@
 Changelog
 =========
 
+Changes in Version 4.4
+----------------------
+
+Version 4.4 brings a number of improvements including:
+
+- Added support for :ref:`CSFLE on-demand credentials` for cloud KMS providers.
+
+
+Issues Resolved
+...............
+
+See the `PyMongo 4.4 release notes in JIRA`_ for the list of resolved issues
+in this release.
+
+.. _PyMongo 4.4 release notes in JIRA: https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=10004&version=34354
+
+
 Changes in Version 4.3.3
 ------------------------
 

doc/examples/encryption.rst

@@ -713,6 +713,81 @@ To configure automatic *decryption* without automatic *encryption* set
       client_encryption.close()
       client.close()
 
-
   if __name__ == "__main__":
       main()
+
+
+.. _CSFLE on-demand credentials:
+
+
+CSFLE on-demand credentials
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PyMongo 4.4 adds support for fetching on-demand KMS credentials for AWS,
+GCP, and Azure cloud environments.
+
+To enable the driver's behavior to obtain credentials from the environment, add the appropriate key ("aws", "gcp", or "azure") with an empty map to
+"kms_providers" in either :class:`~pymongo.encryption_options.AutoEncryptionOpts` or :class:`~pymongo.encryption.ClientEncryption` options.
+
+An application using AWS credentials would look like::
+
+    from pymongo import MongoClient
+    from pymongo.encryption import ClientEncryption
+    from pymongo.encryption_options import AutoEncryptionOpts
+    client = MongoClient()
+    client_encryption = ClientEncryption(
+          kms_providers={"aws": {}},
+          key_vault_namespace="keyvault.datakeys",
+          key_vault_client=client,
+          codec_options=client.codec_options,
+    )
+    master_key = {
+          "region": "us-east-1",
+          "key": ("arn:aws:kms:us-east-1:123456789:key/89fcc2c4-08b0-4bd9-9f25-e30687b580d0"),
+    }
+    client_encryption.create_data_key("aws", master_key)
+
+The above will enable the same behavior of obtaining AWS credentials from the environment as is used for :ref:`MONGODB-AWS` authentication, including the
+caching to avoid rate limiting.
+
+An application using GCP credentials would look like::
+
+    from pymongo import MongoClient
+    from pymongo.encryption import ClientEncryption
+    from pymongo.encryption_options import AutoEncryptionOpts
+    client = MongoClient()
+    client_encryption = ClientEncryption(
+          kms_providers={"gcp": {}},
+          key_vault_namespace="keyvault.datakeys",
+          key_vault_client=client,
+          codec_options=client.codec_options,
+    )
+    master_key = {
+        "projectId": "my-project",
+        "location": "global",
+        "keyRing": "key-ring-csfle",
+        "keyName": "key-name-csfle",
+    }
+    client_encryption.create_data_key("gcp", master_key)
+
+The driver will query the `VM instance metadata <https://cloud.google.com/compute/docs/metadata/default-metadata-values>`_ to obtain credentials.
+
+An application using Azure credentials would look like::
+
+    from pymongo import MongoClient
+    from pymongo.encryption import ClientEncryption
+    from pymongo.encryption_options import AutoEncryptionOpts
+    client = MongoClient()
+    client_encryption = ClientEncryption(
+          kms_providers={"azure": {}},
+          key_vault_namespace="keyvault.datakeys",
+          key_vault_client=client,
+          codec_options=client.codec_options,
+    )
+    master_key = {
+        "keyVaultEndpoint": "https://my-keyvault-address.vault.azure.net/keys/",
+        "keyName": "MY-KEY-NAME",
+    }
+    client_encryption.create_data_key("azure", master_key)
+
+The driver will `acquire an access token <https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token>`_ from the Azure VM.