Skip to content

Commit fcb1151

Browse files
authored
PYTHON-3517 Add documentation for on-demand KMS providers (#1113)
1 parent 92e6150 commit fcb1151

File tree

2 files changed

+73
-2
lines changed

2 files changed

+73
-2
lines changed

doc/changelog.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Changelog
44
Changes in Version 4.3.3
55
------------------------
66

7-
Version 4.3.3 fixes a number of bugs:
7+
Version 4.3.3 documents support for :ref:`CSFLE on-demand credentials` for cloud KMS providers, and fixes the following bugs:
88

99
- Fixed a performance regression in :meth:`~gridfs.GridFSBucket.download_to_stream`
1010
and :meth:`~gridfs.GridFSBucket.download_to_stream_by_name` by reading in chunks

doc/examples/encryption.rst

Lines changed: 72 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -713,6 +713,77 @@ To configure automatic *decryption* without automatic *encryption* set
713713
client_encryption.close()
714714
client.close()
715715

716-
717716
if __name__ == "__main__":
718717
main()
718+
719+
720+
.. _CSFLE on-demand credentials:
721+
722+
723+
CSFLE on-demand credentials
724+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
725+
726+
``pymongocrypt`` 1.4 adds support for fetching on-demand KMS credentials for
727+
AWS, GCP, and Azure cloud environments.
728+
729+
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
730+
"kms_providers" in either :class:`~pymongo.encryption_options.AutoEncryptionOpts` or :class:`~pymongo.encryption.ClientEncryption` options.
731+
732+
An application using AWS credentials would look like::
733+
734+
from pymongo import MongoClient
735+
from pymongo.encryption import ClientEncryption
736+
client = MongoClient()
737+
client_encryption = ClientEncryption(
738+
# The empty dictionary enables on-demand credentials.
739+
kms_providers={"aws": {}},
740+
key_vault_namespace="keyvault.datakeys",
741+
key_vault_client=client,
742+
codec_options=client.codec_options,
743+
)
744+
master_key = {
745+
"region": "us-east-1",
746+
"key": ("arn:aws:kms:us-east-1:123456789:key/89fcc2c4-08b0-4bd9-9f25-e30687b580d0"),
747+
}
748+
client_encryption.create_data_key("aws", master_key)
749+
750+
The above will enable the same behavior of obtaining AWS credentials from the environment as is used for :ref:`MONGODB-AWS` authentication, including the
751+
caching to avoid rate limiting.
752+
753+
An application using GCP credentials would look like::
754+
755+
from pymongo import MongoClient
756+
from pymongo.encryption import ClientEncryption
757+
client = MongoClient()
758+
client_encryption = ClientEncryption(
759+
# The empty dictionary enables on-demand credentials.
760+
kms_providers={"gcp": {}},
761+
key_vault_namespace="keyvault.datakeys",
762+
key_vault_client=client,
763+
codec_options=client.codec_options,
764+
)
765+
master_key = {
766+
"projectId": "my-project",
767+
"location": "global",
768+
"keyRing": "key-ring-csfle",
769+
"keyName": "key-name-csfle",
770+
}
771+
client_encryption.create_data_key("gcp", master_key)
772+
773+
The driver will query the `VM instance metadata <https://cloud.google.com/compute/docs/metadata/default-metadata-values>`_ to obtain credentials.
774+
775+
An application using Azure credentials would look like, this time using
776+
:class:`~pymongo.encryption_options.AutoEncryptionOpts`::
777+
778+
from pymongo import MongoClient
779+
from pymongo.encryption_options import AutoEncryptionOpts
780+
# The empty dictionary enables on-demand credentials.
781+
kms_providers={"azure": {}},
782+
key_vault_namespace="keyvault.datakeys"
783+
auto_encryption_opts = AutoEncryptionOpts(
784+
kms_providers, key_vault_namespace)
785+
client = MongoClient(auto_encryption_opts=auto_encryption_opts)
786+
coll = client.test.coll
787+
coll.insert_one({"encryptedField": "123456789"})
788+
789+
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.

0 commit comments

Comments
 (0)