From 99254858bb55470a99b73875a324f5e07efcd1d5 Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross.lawley@gmail.com>
Date: Mon, 28 Apr 2025 09:58:28 +0100
Subject: [PATCH 1/7] Added option to configure DEK cache lifetime

Added the `AutoEncryptionSettings.Builder#keyExpiration` method
and `ClientEncryptionSettings.Builder#keyExpiration` method
to configure the cache expiration time for data encryption keys.

JAVA-5547
---
 .../com/mongodb/AutoEncryptionSettings.java   | 37 ++++++++++++++++++
 .../com/mongodb/ClientEncryptionSettings.java | 38 +++++++++++++++++++
 .../internal/capi/MongoCryptHelper.java       | 10 +++--
 .../internal/capi/MongoCryptHelperTest.java   |  7 ++++
 .../AbstractClientSideEncryptionTest.java     |  4 +-
 .../client/JsonPoweredCrudTestHelper.java     |  9 +++++
 .../com/mongodb/client/unified/Entities.java  |  3 ++
 .../UnifiedClientEncryptionHelper.java        |  5 ++-
 .../mongodb/client/unified/UnifiedTest.java   |  3 +-
 .../com/mongodb/internal/crypt/capi/CAPI.java | 11 ++++++
 .../internal/crypt/capi/MongoCryptImpl.java   |  6 +++
 .../crypt/capi/MongoCryptOptions.java         | 28 ++++++++++++++
 12 files changed, 154 insertions(+), 7 deletions(-)

diff --git a/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java b/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
index 904f148e891..e5850e3292b 100644
--- a/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
+++ b/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
@@ -24,8 +24,10 @@
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.concurrent.TimeUnit;
 import java.util.function.Supplier;
 
+import static com.mongodb.assertions.Assertions.assertTrue;
 import static com.mongodb.assertions.Assertions.notNull;
 import static java.util.Collections.unmodifiableMap;
 
@@ -73,6 +75,8 @@ public final class AutoEncryptionSettings {
     private final boolean bypassAutoEncryption;
     private final Map<String, BsonDocument> encryptedFieldsMap;
     private final boolean bypassQueryAnalysis;
+    @Nullable
+    private final Long keyExpirationMS;
 
     /**
      * A builder for {@code AutoEncryptionSettings} so that {@code AutoEncryptionSettings} can be immutable, and to support easier
@@ -90,6 +94,7 @@ public static final class Builder {
         private boolean bypassAutoEncryption;
         private Map<String, BsonDocument> encryptedFieldsMap = Collections.emptyMap();
         private boolean bypassQueryAnalysis;
+        @Nullable private Long keyExpirationMS;
 
         /**
          * Sets the key vault settings.
@@ -236,6 +241,22 @@ public Builder bypassQueryAnalysis(final boolean bypassQueryAnalysis) {
             return this;
         }
 
+        /**
+         * The cache expiration time for data encryption keys.
+         * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently 60000. Set to 0 to disable key expiration.</p>
+         *
+         * @param keyExpiration the cache expiration time in milliseconds or null to use libmongocrypt's default.
+         * @param timeUnit the time unit
+         * @return this
+         * @see #getKeyExpiration(TimeUnit)
+         * @since 5.5
+         */
+        public Builder keyExpiration(@Nullable final Long keyExpiration, final TimeUnit timeUnit) {
+            assertTrue(keyExpiration == null || keyExpiration >= 0, "keyExpiration must be >= 0 or null");
+            this.keyExpirationMS = keyExpiration == null ? null : TimeUnit.MILLISECONDS.convert(keyExpiration, timeUnit);
+            return this;
+        }
+
         /**
          * Build an instance of {@code AutoEncryptionSettings}.
          *
@@ -488,6 +509,21 @@ public boolean isBypassQueryAnalysis() {
         return bypassQueryAnalysis;
     }
 
+    /**
+     * Returns the cache expiration time for data encryption keys.
+     *
+     * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently {@code 60000}.
+     * Set to {@code 0} to disable key expiration.</p>
+     *
+     * @param timeUnit the time unit, which may not be null
+     * @return the cache expiration time or null if not set.
+     * @since 5.5
+     */
+    @Nullable
+    public Long getKeyExpiration(final TimeUnit timeUnit) {
+        return keyExpirationMS == null ? null : timeUnit.convert(keyExpirationMS, TimeUnit.MILLISECONDS);
+    }
+
     private AutoEncryptionSettings(final Builder builder) {
         this.keyVaultMongoClientSettings = builder.keyVaultMongoClientSettings;
         this.keyVaultNamespace = notNull("keyVaultNamespace", builder.keyVaultNamespace);
@@ -499,6 +535,7 @@ private AutoEncryptionSettings(final Builder builder) {
         this.bypassAutoEncryption = builder.bypassAutoEncryption;
         this.encryptedFieldsMap = builder.encryptedFieldsMap;
         this.bypassQueryAnalysis = builder.bypassQueryAnalysis;
+        this.keyExpirationMS = builder.keyExpirationMS;
     }
 
     @Override
diff --git a/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java b/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java
index d2188b3d329..ac50133aeb8 100644
--- a/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java
+++ b/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java
@@ -27,6 +27,7 @@
 import java.util.concurrent.TimeUnit;
 import java.util.function.Supplier;
 
+import static com.mongodb.assertions.Assertions.assertTrue;
 import static com.mongodb.assertions.Assertions.notNull;
 import static com.mongodb.internal.TimeoutSettings.convertAndValidateTimeout;
 import static java.util.Collections.unmodifiableMap;
@@ -50,6 +51,9 @@ public final class ClientEncryptionSettings {
     private final Map<String, SSLContext> kmsProviderSslContextMap;
     @Nullable
     private final Long timeoutMS;
+    @Nullable
+    private final Long keyExpirationMS;
+
     /**
      * A builder for {@code ClientEncryptionSettings} so that {@code ClientEncryptionSettings} can be immutable, and to support easier
      * construction through chaining.
@@ -63,6 +67,8 @@ public static final class Builder {
         private Map<String, SSLContext> kmsProviderSslContextMap = new HashMap<>();
         @Nullable
         private Long timeoutMS;
+        @Nullable
+        private Long keyExpirationMS;
 
         /**
          * Sets the {@link MongoClientSettings} that will be used to access the key vault.
@@ -130,6 +136,22 @@ public Builder kmsProviderSslContextMap(final Map<String, SSLContext> kmsProvide
             return this;
         }
 
+        /**
+         * The cache expiration time for data encryption keys.
+         * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently 60000. Set to 0 to disable key expiration.</p>
+         *
+         * @param keyExpiration the cache expiration time in milliseconds or null to use libmongocrypt's default.
+         * @param timeUnit the time unit
+         * @return this
+         * @see #getKeyExpiration(TimeUnit)
+         * @since 5.5
+         */
+        public Builder keyExpiration(@Nullable final Long keyExpiration, final TimeUnit timeUnit) {
+            assertTrue(keyExpiration == null || keyExpiration >= 0, "keyExpiration must be >= 0 or null");
+            this.keyExpirationMS = keyExpiration == null ? null : TimeUnit.MILLISECONDS.convert(keyExpiration, timeUnit);
+            return this;
+        }
+
         /**
          * Sets the time limit for the full execution of an operation.
          *
@@ -308,6 +330,21 @@ public Map<String, SSLContext> getKmsProviderSslContextMap() {
         return unmodifiableMap(kmsProviderSslContextMap);
     }
 
+    /**
+     * Returns the cache expiration time for data encryption keys.
+     *
+     * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently {@code 60000}.
+     * Set to {@code 0} to disable key expiration.</p>
+     *
+     * @param timeUnit the time unit, which may not be null
+     * @return the cache expiration time or null if not set.
+     * @since 5.5
+     */
+    @Nullable
+    public Long getKeyExpiration(final TimeUnit timeUnit) {
+        return keyExpirationMS == null ? null : timeUnit.convert(keyExpirationMS, TimeUnit.MILLISECONDS);
+    }
+
     /**
      * The time limit for the full execution of an operation.
      *
@@ -348,6 +385,7 @@ private ClientEncryptionSettings(final Builder builder) {
         this.kmsProviderPropertySuppliers = notNull("kmsProviderPropertySuppliers", builder.kmsProviderPropertySuppliers);
         this.kmsProviderSslContextMap = notNull("kmsProviderSslContextMap", builder.kmsProviderSslContextMap);
         this.timeoutMS = builder.timeoutMS;
+        this.keyExpirationMS = builder.keyExpirationMS;
     }
 
 }
diff --git a/driver-core/src/main/com/mongodb/internal/capi/MongoCryptHelper.java b/driver-core/src/main/com/mongodb/internal/capi/MongoCryptHelper.java
index 1ba51797bea..240f5051c92 100644
--- a/driver-core/src/main/com/mongodb/internal/capi/MongoCryptHelper.java
+++ b/driver-core/src/main/com/mongodb/internal/capi/MongoCryptHelper.java
@@ -53,7 +53,8 @@
 public final class MongoCryptHelper {
 
     public static MongoCryptOptions createMongoCryptOptions(final ClientEncryptionSettings settings) {
-        return createMongoCryptOptions(settings.getKmsProviders(), false, emptyList(), emptyMap(), null, null);
+        return createMongoCryptOptions(settings.getKmsProviders(), false, emptyList(), emptyMap(), null, null,
+                settings.getKeyExpiration(TimeUnit.MILLISECONDS));
     }
 
     public static MongoCryptOptions createMongoCryptOptions(final AutoEncryptionSettings settings) {
@@ -63,7 +64,8 @@ public static MongoCryptOptions createMongoCryptOptions(final AutoEncryptionSett
                 settings.isBypassAutoEncryption() ? emptyList() :  singletonList("$SYSTEM"),
                 settings.getExtraOptions(),
                 settings.getSchemaMap(),
-                settings.getEncryptedFieldsMap());
+                settings.getEncryptedFieldsMap(),
+                settings.getKeyExpiration(TimeUnit.MILLISECONDS));
     }
 
     public static void validateRewrapManyDataKeyOptions(final RewrapManyDataKeyOptions options) {
@@ -78,7 +80,8 @@ private static MongoCryptOptions createMongoCryptOptions(
             final List<String> searchPaths,
             @Nullable final Map<String, Object> extraOptions,
             @Nullable final Map<String, BsonDocument> localSchemaMap,
-            @Nullable final Map<String, BsonDocument> encryptedFieldsMap) {
+            @Nullable final Map<String, BsonDocument> encryptedFieldsMap,
+            @Nullable final Long keyExpirationMS) {
         MongoCryptOptions.Builder mongoCryptOptionsBuilder = MongoCryptOptions.builder();
         mongoCryptOptionsBuilder.kmsProviderOptions(getKmsProvidersAsBsonDocument(kmsProviders));
         mongoCryptOptionsBuilder.bypassQueryAnalysis(bypassQueryAnalysis);
@@ -87,6 +90,7 @@ private static MongoCryptOptions createMongoCryptOptions(
         mongoCryptOptionsBuilder.localSchemaMap(localSchemaMap);
         mongoCryptOptionsBuilder.encryptedFieldsMap(encryptedFieldsMap);
         mongoCryptOptionsBuilder.needsKmsCredentialsStateEnabled(true);
+        mongoCryptOptionsBuilder.keyExpirationMS(keyExpirationMS);
         return mongoCryptOptionsBuilder.build();
     }
     public static BsonDocument fetchCredentials(final Map<String, Map<String, Object>> kmsProviders,
diff --git a/driver-core/src/test/functional/com/mongodb/internal/capi/MongoCryptHelperTest.java b/driver-core/src/test/functional/com/mongodb/internal/capi/MongoCryptHelperTest.java
index d76371775b9..832e0d5eeb3 100644
--- a/driver-core/src/test/functional/com/mongodb/internal/capi/MongoCryptHelperTest.java
+++ b/driver-core/src/test/functional/com/mongodb/internal/capi/MongoCryptHelperTest.java
@@ -27,6 +27,7 @@
 
 import java.util.HashMap;
 import java.util.Map;
+import java.util.concurrent.TimeUnit;
 
 import static com.mongodb.internal.capi.MongoCryptHelper.isMongocryptdSpawningDisabled;
 import static com.mongodb.internal.capi.MongoCryptHelper.validateRewrapManyDataKeyOptions;
@@ -94,6 +95,11 @@ public void createsExpectedMongoCryptOptionsUsingAutoEncryptionSettings() {
 
         assertMongoCryptOptions(mongoCryptOptionsBuilder.build(), mongoCryptOptions);
 
+        // Ensure can set key expiration
+        autoEncryptionSettingsBuilder.keyExpiration(10L, TimeUnit.SECONDS);
+        mongoCryptOptions = MongoCryptHelper.createMongoCryptOptions(autoEncryptionSettingsBuilder.build());
+        assertMongoCryptOptions(mongoCryptOptionsBuilder.keyExpirationMS(10_000L).build(), mongoCryptOptions);
+
         // Ensure search Paths is empty when bypassAutoEncryption is true
         autoEncryptionSettingsBuilder.bypassAutoEncryption(true);
         mongoCryptOptions = MongoCryptHelper.createMongoCryptOptions(autoEncryptionSettingsBuilder.build());
@@ -143,5 +149,6 @@ void assertMongoCryptOptions(final MongoCryptOptions expected, final MongoCryptO
         assertEquals(expected.getSearchPaths(), actual.getSearchPaths(), "SearchPaths not equal");
         assertEquals(expected.isBypassQueryAnalysis(), actual.isBypassQueryAnalysis(), "isBypassQueryAnalysis not equal");
         assertEquals(expected.isNeedsKmsCredentialsStateEnabled(), actual.isNeedsKmsCredentialsStateEnabled(), "isNeedsKmsCredentialsStateEnabled not equal");
+        assertEquals(expected.getKeyExpirationMS(), actual.getKeyExpirationMS(), "keyExpirationMS not equal");
     }
 }
diff --git a/driver-sync/src/test/functional/com/mongodb/client/AbstractClientSideEncryptionTest.java b/driver-sync/src/test/functional/com/mongodb/client/AbstractClientSideEncryptionTest.java
index 3f7d104a986..f7089755d91 100644
--- a/driver-sync/src/test/functional/com/mongodb/client/AbstractClientSideEncryptionTest.java
+++ b/driver-sync/src/test/functional/com/mongodb/client/AbstractClientSideEncryptionTest.java
@@ -135,7 +135,6 @@ public void setUp() {
                 description.equals("timeoutMS applied to listCollections to get collection schema"));
         assumeFalse("runOn requirements not satisfied", skipTest);
         assumeFalse("Skipping count tests", filename.startsWith("count."));
-        assumeFalse("https://jira.mongodb.org/browse/JAVA-5297", description.equals("Insert with deterministic encryption, then find it"));
 
         assumeFalse(definition.getString("skipReason", new BsonString("")).getValue(), definition.containsKey("skipReason"));
 
@@ -185,6 +184,8 @@ public void setUp() {
         BsonDocument kmsProviders = cryptOptions.getDocument("kmsProviders", new BsonDocument());
         boolean bypassAutoEncryption = cryptOptions.getBoolean("bypassAutoEncryption", BsonBoolean.FALSE).getValue();
         boolean bypassQueryAnalysis = cryptOptions.getBoolean("bypassQueryAnalysis", BsonBoolean.FALSE).getValue();
+        Long keyExpirationMS = cryptOptions.containsKey("keyExpirationMS")
+                ? cryptOptions.getNumber("keyExpirationMS").longValue() : null;
 
         Map<String, BsonDocument> namespaceToSchemaMap = new HashMap<>();
 
@@ -285,6 +286,7 @@ public void setUp() {
                     .bypassQueryAnalysis(bypassQueryAnalysis)
                     .bypassAutoEncryption(bypassAutoEncryption)
                     .extraOptions(extraOptions)
+                    .keyExpiration(keyExpirationMS, TimeUnit.MILLISECONDS)
                     .build());
         }
         createMongoClient(mongoClientSettingsBuilder.build());
diff --git a/driver-sync/src/test/functional/com/mongodb/client/JsonPoweredCrudTestHelper.java b/driver-sync/src/test/functional/com/mongodb/client/JsonPoweredCrudTestHelper.java
index eae85a2da63..7e0225e8c51 100644
--- a/driver-sync/src/test/functional/com/mongodb/client/JsonPoweredCrudTestHelper.java
+++ b/driver-sync/src/test/functional/com/mongodb/client/JsonPoweredCrudTestHelper.java
@@ -1198,6 +1198,15 @@ BsonDocument getDatabaseWatchResult(final BsonDocument collectionOptions, final
         }
     }
 
+    BsonDocument wait(final BsonDocument options, final BsonDocument rawArguments, @Nullable final ClientSession clientSession) {
+        try {
+            Thread.sleep(rawArguments.getNumber("ms").longValue());
+            return new BsonDocument();
+        } catch (InterruptedException e) {
+            throw new RuntimeException(e);
+        }
+    }
+
     Collation getCollation(final BsonDocument bsonCollation) {
         Collation.Builder builder = Collation.builder();
         if (bsonCollation.containsKey("locale")) {
diff --git a/driver-sync/src/test/functional/com/mongodb/client/unified/Entities.java b/driver-sync/src/test/functional/com/mongodb/client/unified/Entities.java
index 1890b2e48a3..f1429431690 100644
--- a/driver-sync/src/test/functional/com/mongodb/client/unified/Entities.java
+++ b/driver-sync/src/test/functional/com/mongodb/client/unified/Entities.java
@@ -754,6 +754,9 @@ private void initClientEncryption(final BsonDocument entity, final String id,
                 case "kmsProviders":
                     builder.kmsProviders(createKmsProvidersMap(entry.getValue().asDocument()));
                     break;
+                case "keyExpirationMS":
+                    builder.keyExpiration(entry.getValue().asNumber().longValue(), TimeUnit.MILLISECONDS);
+                    break;
                 default:
                     throw new UnsupportedOperationException("Unsupported client encryption option: " + entry.getKey());
             }
diff --git a/driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedClientEncryptionHelper.java b/driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedClientEncryptionHelper.java
index 8e545841c6a..59f96aa9492 100644
--- a/driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedClientEncryptionHelper.java
+++ b/driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedClientEncryptionHelper.java
@@ -166,9 +166,10 @@ private static void setKmsProviderProperty(final Map<String, Object> kmsProvider
             }
 
             if (explicitPropertySupplier == null) {
-                throw new UnsupportedOperationException("Non-placeholder value is not supported for: " + key + " :: " + kmsProviderOptions.toJson());
+                kmsProviderMap.put(key, kmsProviderOptions.get(key));
+            } else {
+                kmsProviderMap.put(key, explicitPropertySupplier.get());
             }
-            kmsProviderMap.put(key, explicitPropertySupplier.get());
         }
     }
 
diff --git a/driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedTest.java b/driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedTest.java
index 9e09d2061bc..84eb40b4e29 100644
--- a/driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedTest.java
+++ b/driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedTest.java
@@ -109,7 +109,7 @@ public abstract class UnifiedTest {
     private static final Set<String> PRESTART_POOL_ASYNC_WORK_MANAGER_FILE_DESCRIPTIONS = Collections.singleton(
             "wait queue timeout errors include details about checked out connections");
 
-    private static final String MAX_SUPPORTED_SCHEMA_VERSION = "1.21";
+    private static final String MAX_SUPPORTED_SCHEMA_VERSION = "1.22";
     private static final List<Integer> MAX_SUPPORTED_SCHEMA_VERSION_COMPONENTS = Arrays.stream(MAX_SUPPORTED_SCHEMA_VERSION.split("\\."))
             .map(Integer::parseInt)
             .collect(Collectors.toList());
@@ -265,6 +265,7 @@ public void setUp(
         skips(fileDescription, testDescription);
 
         assumeTrue(isSupportedSchemaVersion(schemaVersion), format("Unsupported schema version %s", schemaVersion));
+
         if (runOnRequirements != null) {
             assumeTrue(runOnRequirementsMet(runOnRequirements, getMongoClientSettings(), getServerVersion()),
                     "Run-on requirements not met");
diff --git a/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/CAPI.java b/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/CAPI.java
index 075bbe15c9c..34a102fbdeb 100644
--- a/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/CAPI.java
+++ b/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/CAPI.java
@@ -486,6 +486,17 @@ public interface mongocrypt_random_fn extends Callback {
     public static native void
     mongocrypt_setopt_bypass_query_analysis (mongocrypt_t crypt);
 
+    /**
+     * Set the expiration time for the data encryption key cache. Defaults to 60 seconds if not set.
+     *
+     * @param crypt The @ref mongocrypt_t object to update
+     * @param cache_expiration_ms if 0 the cache never expires
+     * @return A boolean indicating success. If false, an error status is set.
+     * @since 5.4
+     */
+    public static native boolean
+    mongocrypt_setopt_key_expiration (mongocrypt_t crypt, long cache_expiration_ms);
+
     /**
      * Opt-into enabling sending multiple collection info documents.
      *
diff --git a/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptImpl.java b/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptImpl.java
index d365f7f7671..4f131f5d4e9 100644
--- a/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptImpl.java
+++ b/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptImpl.java
@@ -67,6 +67,7 @@
 import static com.mongodb.internal.crypt.capi.CAPI.mongocrypt_setopt_crypto_hooks;
 import static com.mongodb.internal.crypt.capi.CAPI.mongocrypt_setopt_enable_multiple_collinfo;
 import static com.mongodb.internal.crypt.capi.CAPI.mongocrypt_setopt_encrypted_field_config_map;
+import static com.mongodb.internal.crypt.capi.CAPI.mongocrypt_setopt_key_expiration;
 import static com.mongodb.internal.crypt.capi.CAPI.mongocrypt_setopt_kms_provider_aws;
 import static com.mongodb.internal.crypt.capi.CAPI.mongocrypt_setopt_kms_provider_local;
 import static com.mongodb.internal.crypt.capi.CAPI.mongocrypt_setopt_kms_providers;
@@ -194,6 +195,11 @@ class MongoCryptImpl implements MongoCrypt {
             mongocrypt_setopt_bypass_query_analysis(wrapped);
         }
 
+        Long keyExpirationMS = options.getKeyExpirationMS();
+        if (keyExpirationMS != null) {
+            configure(() -> mongocrypt_setopt_key_expiration(wrapped, keyExpirationMS));
+        }
+
         if (options.getEncryptedFieldsMap() != null) {
             BsonDocument localEncryptedFieldsMap = new BsonDocument();
             localEncryptedFieldsMap.putAll(options.getEncryptedFieldsMap());
diff --git a/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptOptions.java b/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptOptions.java
index 46c9898a9a1..4c7ee5aab7c 100644
--- a/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptOptions.java
+++ b/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptOptions.java
@@ -39,6 +39,7 @@ public final class MongoCryptOptions {
     private final BsonDocument extraOptions;
     private final boolean bypassQueryAnalysis;
     private final List<String> searchPaths;
+    private final Long keyExpirationMS;
 
 
     /**
@@ -135,6 +136,19 @@ public List<String> getSearchPaths() {
         return searchPaths;
     }
 
+    /**
+     * Returns the cache expiration time for data encryption keys.
+     *
+     * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently {@code 60000}.
+     * Set to {@code 0} to disable key expiration.</p>
+     *
+     * @return the cache expiration time or null if not set.
+     * @since 5.5
+     */
+    public Long getKeyExpirationMS() {
+        return keyExpirationMS;
+    }
+
     /**
      * The builder for the options
      */
@@ -148,6 +162,7 @@ public static final class Builder {
         private boolean bypassQueryAnalysis;
         private BsonDocument extraOptions = new BsonDocument();
         private List<String> searchPaths = emptyList();
+        private Long keyExpirationMS = null;
 
         private Builder() {
         }
@@ -258,6 +273,18 @@ public Builder searchPaths(final List<String> searchPaths) {
             return this;
         }
 
+        /**
+         * The cache expiration time for data encryption keys.
+         *
+         * @param keyExpirationMS the cache expiration time in milliseconds or null to use libmongocrypt's default.
+         * @return this
+         * @since 5.5
+         */
+        public Builder keyExpirationMS(final Long keyExpirationMS) {
+            this.keyExpirationMS = keyExpirationMS;
+            return this;
+        }
+
         /**
          * Build the options.
          *
@@ -281,5 +308,6 @@ private MongoCryptOptions(final Builder builder) {
         this.bypassQueryAnalysis = builder.bypassQueryAnalysis;
         this.extraOptions = builder.extraOptions;
         this.searchPaths = builder.searchPaths;
+        this.keyExpirationMS = builder.keyExpirationMS;
     }
 }

From ef7bb326bc89a269de3ce5eb65ba31dae016ccc3 Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross@mongodb.com>
Date: Wed, 30 Apr 2025 14:45:49 +0100
Subject: [PATCH 2/7] Update
 driver-core/src/main/com/mongodb/AutoEncryptionSettings.java

Co-authored-by: Nabil Hachicha <nabil.hachicha@gmail.com>
---
 driver-core/src/main/com/mongodb/AutoEncryptionSettings.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java b/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
index e5850e3292b..d53a232408a 100644
--- a/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
+++ b/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
@@ -243,7 +243,7 @@ public Builder bypassQueryAnalysis(final boolean bypassQueryAnalysis) {
 
         /**
          * The cache expiration time for data encryption keys.
-         * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently 60000. Set to 0 to disable key expiration.</p>
+         * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently 60000 ms. Set to 0 to disable key expiration.</p>
          *
          * @param keyExpiration the cache expiration time in milliseconds or null to use libmongocrypt's default.
          * @param timeUnit the time unit

From b11823944cf272d0acd1ca222cd2696751c8ed70 Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross@mongodb.com>
Date: Wed, 30 Apr 2025 14:45:59 +0100
Subject: [PATCH 3/7] Update
 driver-core/src/main/com/mongodb/AutoEncryptionSettings.java

Co-authored-by: Nabil Hachicha <nabil.hachicha@gmail.com>
---
 driver-core/src/main/com/mongodb/AutoEncryptionSettings.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java b/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
index d53a232408a..076c85a8fac 100644
--- a/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
+++ b/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
@@ -512,7 +512,7 @@ public boolean isBypassQueryAnalysis() {
     /**
      * Returns the cache expiration time for data encryption keys.
      *
-     * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently {@code 60000}.
+     * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently {@code 60000 ms}.
      * Set to {@code 0} to disable key expiration.</p>
      *
      * @param timeUnit the time unit, which may not be null

From c1c326a6993439b5d92335d36bca4ab7b517dd02 Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross@mongodb.com>
Date: Wed, 30 Apr 2025 14:46:13 +0100
Subject: [PATCH 4/7] Update
 driver-core/src/main/com/mongodb/AutoEncryptionSettings.java

Co-authored-by: Nabil Hachicha <nabil.hachicha@gmail.com>
---
 driver-core/src/main/com/mongodb/AutoEncryptionSettings.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java b/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
index 076c85a8fac..187d3421235 100644
--- a/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
+++ b/driver-core/src/main/com/mongodb/AutoEncryptionSettings.java
@@ -515,7 +515,7 @@ public boolean isBypassQueryAnalysis() {
      * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently {@code 60000 ms}.
      * Set to {@code 0} to disable key expiration.</p>
      *
-     * @param timeUnit the time unit, which may not be null
+     * @param timeUnit the time unit, which must not be null
      * @return the cache expiration time or null if not set.
      * @since 5.5
      */

From c524c52da93c9b8a4ef0f1e36987acc1bda4f190 Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross@mongodb.com>
Date: Wed, 30 Apr 2025 14:46:21 +0100
Subject: [PATCH 5/7] Update
 driver-core/src/main/com/mongodb/ClientEncryptionSettings.java

Co-authored-by: Nabil Hachicha <nabil.hachicha@gmail.com>
---
 driver-core/src/main/com/mongodb/ClientEncryptionSettings.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java b/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java
index ac50133aeb8..37952a67a5a 100644
--- a/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java
+++ b/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java
@@ -138,7 +138,7 @@ public Builder kmsProviderSslContextMap(final Map<String, SSLContext> kmsProvide
 
         /**
          * The cache expiration time for data encryption keys.
-         * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently 60000. Set to 0 to disable key expiration.</p>
+         * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently 60000 ms. Set to 0 to disable key expiration.</p>
          *
          * @param keyExpiration the cache expiration time in milliseconds or null to use libmongocrypt's default.
          * @param timeUnit the time unit

From 333a27fb5d566da0e7cdbacaa3d0f6cc005158c8 Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross@mongodb.com>
Date: Wed, 30 Apr 2025 14:46:27 +0100
Subject: [PATCH 6/7] Update
 mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptOptions.java

Co-authored-by: Nabil Hachicha <nabil.hachicha@gmail.com>
---
 .../main/com/mongodb/internal/crypt/capi/MongoCryptOptions.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptOptions.java b/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptOptions.java
index 4c7ee5aab7c..782e278e7c8 100644
--- a/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptOptions.java
+++ b/mongodb-crypt/src/main/com/mongodb/internal/crypt/capi/MongoCryptOptions.java
@@ -139,7 +139,7 @@ public List<String> getSearchPaths() {
     /**
      * Returns the cache expiration time for data encryption keys.
      *
-     * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently {@code 60000}.
+     * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently {@code 60000 ms}.
      * Set to {@code 0} to disable key expiration.</p>
      *
      * @return the cache expiration time or null if not set.

From 9efdaeec2c36ba1ab2a93a55e0e839fe7539aef7 Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross@mongodb.com>
Date: Wed, 30 Apr 2025 14:46:51 +0100
Subject: [PATCH 7/7] Update
 driver-core/src/main/com/mongodb/ClientEncryptionSettings.java

Co-authored-by: Nabil Hachicha <nabil.hachicha@gmail.com>
---
 driver-core/src/main/com/mongodb/ClientEncryptionSettings.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java b/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java
index 37952a67a5a..6f0411d749c 100644
--- a/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java
+++ b/driver-core/src/main/com/mongodb/ClientEncryptionSettings.java
@@ -333,7 +333,7 @@ public Map<String, SSLContext> getKmsProviderSslContextMap() {
     /**
      * Returns the cache expiration time for data encryption keys.
      *
-     * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently {@code 60000}.
+     * <p>Defaults to {@code null} which defers to libmongocrypt's default which is currently {@code 60000 ms}.
      * Set to {@code 0} to disable key expiration.</p>
      *
      * @param timeUnit the time unit, which may not be null