PYTHON-4580 Add key_expiration_ms option for DEK cache lifetime

Author: ShaneHarvey

pymongo/asynchronous/encryption.py

@@ -445,6 +445,7 @@ def _get_internal_client(
                 bypass_encryption=opts._bypass_auto_encryption,
                 encrypted_fields_map=encrypted_fields_map,
                 bypass_query_analysis=opts._bypass_query_analysis,
+                key_expiration_ms=opts._key_expiration_ms,
             ),
         )
         self._closed = False
@@ -564,6 +565,7 @@ def __init__(
         key_vault_client: AsyncMongoClient[_DocumentTypeArg],
         codec_options: CodecOptions[_DocumentTypeArg],
         kms_tls_options: Optional[Mapping[str, Any]] = None,
+        key_expiration_ms: Optional[int] = None,
     ) -> None:
         """Explicit client-side field level encryption.
 
@@ -630,7 +632,12 @@ def __init__(
             Or to supply a client certificate::
 
               kms_tls_options={'kmip': {'tlsCertificateKeyFile': 'client.pem'}}
+        :param key_expiration_ms: The cache expiration time for data encryption keys.
+            Defaults to ``None`` which defers to libmongocrypt's default which is currently 60000.
+            Set to 0 to disable key expiration.
 
+        .. versionchanged:: 4.12
+           Added the `key_expiration_ms` parameter.
         .. versionchanged:: 4.0
            Added the `kms_tls_options` parameter and the "kmip" KMS provider.
 
@@ -666,14 +673,19 @@ def __init__(
         key_vault_coll = key_vault_client[db][coll]
 
         opts = AutoEncryptionOpts(
-            kms_providers, key_vault_namespace, kms_tls_options=kms_tls_options
+            kms_providers,
+            key_vault_namespace,
+            kms_tls_options=kms_tls_options,
+            key_expiration_ms=key_expiration_ms,
         )
         self._io_callbacks: Optional[_EncryptionIO] = _EncryptionIO(
             None, key_vault_coll, None, opts
         )
         self._encryption = AsyncExplicitEncrypter(
             self._io_callbacks,
-            _create_mongocrypt_options(kms_providers=kms_providers, schema_map=None),
+            _create_mongocrypt_options(
+                kms_providers=kms_providers, schema_map=None, key_expiration_ms=key_expiration_ms
+            ),
         )
         # Use the same key vault collection as the callback.
         assert self._io_callbacks.key_vault_coll is not None
@@ -700,6 +712,7 @@ async def create_encrypted_collection(
         creation. :class:`~pymongo.errors.EncryptionError` will be
         raised if the collection already exists.
 
+        :param database: the database to create the collection
         :param name: the name of the collection to create
         :param encrypted_fields: Document that describes the encrypted fields for
             Queryable Encryption. The "keyId" may be set to ``None`` to auto-generate the data keys.  For example:

pymongo/encryption_options.py

@@ -57,6 +57,7 @@ def __init__(
         crypt_shared_lib_required: bool = False,
         bypass_query_analysis: bool = False,
         encrypted_fields_map: Optional[Mapping[str, Any]] = None,
+        key_expiration_ms: Optional[int] = None,
     ) -> None:
         """Options to configure automatic client-side field level encryption.
 
@@ -191,9 +192,14 @@ def __init__(
                       ]
                   }
                 }
+        :param key_expiration_ms: The cache expiration time for data encryption keys.
+            Defaults to ``None`` which defers to libmongocrypt's default which is currently 60000.
+            Set to 0 to disable key expiration.
 
+        .. versionchanged:: 4.12
+           Added the `key_expiration_ms` parameter.
         .. versionchanged:: 4.2
-           Added `encrypted_fields_map` `crypt_shared_lib_path`, `crypt_shared_lib_required`,
+           Added the `encrypted_fields_map`, `crypt_shared_lib_path`, `crypt_shared_lib_required`,
            and `bypass_query_analysis` parameters.
 
         .. versionchanged:: 4.0
@@ -210,7 +216,6 @@ def __init__(
         if encrypted_fields_map:
             validate_is_mapping("encrypted_fields_map", encrypted_fields_map)
         self._encrypted_fields_map = encrypted_fields_map
-        self._bypass_query_analysis = bypass_query_analysis
         self._crypt_shared_lib_path = crypt_shared_lib_path
         self._crypt_shared_lib_required = crypt_shared_lib_required
         self._kms_providers = kms_providers
@@ -233,6 +238,7 @@ def __init__(
         # Maps KMS provider name to a SSLContext.
         self._kms_ssl_contexts = _parse_kms_tls_options(kms_tls_options)
         self._bypass_query_analysis = bypass_query_analysis
+        self._key_expiration_ms = key_expiration_ms
 
 
 class RangeOpts:

pymongo/synchronous/encryption.py

@@ -442,6 +442,7 @@ def _get_internal_client(
                 bypass_encryption=opts._bypass_auto_encryption,
                 encrypted_fields_map=encrypted_fields_map,
                 bypass_query_analysis=opts._bypass_query_analysis,
+                key_expiration_ms=opts._key_expiration_ms,
             ),
         )
         self._closed = False
@@ -561,6 +562,7 @@ def __init__(
         key_vault_client: MongoClient[_DocumentTypeArg],
         codec_options: CodecOptions[_DocumentTypeArg],
         kms_tls_options: Optional[Mapping[str, Any]] = None,
+        key_expiration_ms: Optional[int] = None,
     ) -> None:
         """Explicit client-side field level encryption.
 
@@ -627,7 +629,12 @@ def __init__(
             Or to supply a client certificate::
 
               kms_tls_options={'kmip': {'tlsCertificateKeyFile': 'client.pem'}}
+        :param key_expiration_ms: The cache expiration time for data encryption keys.
+            Defaults to ``None`` which defers to libmongocrypt's default which is currently 60000.
+            Set to 0 to disable key expiration.
 
+        .. versionchanged:: 4.12
+           Added the `key_expiration_ms` parameter.
         .. versionchanged:: 4.0
            Added the `kms_tls_options` parameter and the "kmip" KMS provider.
 
@@ -659,14 +666,19 @@ def __init__(
         key_vault_coll = key_vault_client[db][coll]
 
         opts = AutoEncryptionOpts(
-            kms_providers, key_vault_namespace, kms_tls_options=kms_tls_options
+            kms_providers,
+            key_vault_namespace,
+            kms_tls_options=kms_tls_options,
+            key_expiration_ms=key_expiration_ms,
         )
         self._io_callbacks: Optional[_EncryptionIO] = _EncryptionIO(
             None, key_vault_coll, None, opts
         )
         self._encryption = ExplicitEncrypter(
             self._io_callbacks,
-            _create_mongocrypt_options(kms_providers=kms_providers, schema_map=None),
+            _create_mongocrypt_options(
+                kms_providers=kms_providers, schema_map=None, key_expiration_ms=key_expiration_ms
+            ),
         )
         # Use the same key vault collection as the callback.
         assert self._io_callbacks.key_vault_coll is not None
@@ -693,6 +705,7 @@ def create_encrypted_collection(
         creation. :class:`~pymongo.errors.EncryptionError` will be
         raised if the collection already exists.
 
+        :param database: the database to create the collection
         :param name: the name of the collection to create
         :param encrypted_fields: Document that describes the encrypted fields for
             Queryable Encryption. The "keyId" may be set to ``None`` to auto-generate the data keys.  For example: