libmongocrypt-helper 1.8.0.0.1001 → 1.11.0.0.1001

data/ext/libmongocrypt/libmongocrypt/src/mongocrypt-private.h

@@ -39,7 +39,7 @@
 
 #define CLIENT_ERR_W_CODE(code, ...) _mongocrypt_set_error(status, MONGOCRYPT_STATUS_ERROR_CLIENT, code, __VA_ARGS__)
 
-#define CLIENT_ERR(...) CLIENT_ERR_W_CODE(MONGOCRYPT_GENERIC_ERROR_CODE, __VA_ARGS__)
+#define CLIENT_ERR(fmt, ...) CLIENT_ERR_W_CODE(MONGOCRYPT_GENERIC_ERROR_CODE, fmt, ##__VA_ARGS__)
 
 #define KMS_ERR_W_CODE(code, ...) _mongocrypt_set_error(status, MONGOCRYPT_STATUS_ERROR_KMS, code, __VA_ARGS__)
 
@@ -49,9 +49,6 @@
 
 #define MONGOCRYPT_DATA_AND_LEN(x) ((uint8_t *)x), (sizeof(x) / sizeof((x)[0]) - 1)
 
-/* TODO: remove after integrating into libmongoc */
-#define BSON_SUBTYPE_ENCRYPTED 6
-
 /* TODO: Move these to mongocrypt-log-private.h? */
 const char *tmp_json(const bson_t *bson);
 
@@ -123,8 +120,7 @@ struct _mongocrypt_t {
     _mongocrypt_crypto_t *crypto;
     /* A counter, protected by mutex, for generating unique context ids */
     uint32_t ctx_counter;
-    _mongocrypt_cache_oauth_t *cache_oauth_azure;
-    _mongocrypt_cache_oauth_t *cache_oauth_gcp;
+    mc_mapof_kmsid_to_token_t *cache_oauth;
     /// A CSFLE DLL vtable, initialized by mongocrypt_init
     _mongo_crypt_v1_vtable csfle;
     /// Pointer to the global csfle_lib object. Should not be freed directly.
@@ -154,18 +150,15 @@ char *_mongocrypt_new_string_from_bytes(const void *in, int len);
 
 char *_mongocrypt_new_json_string_from_binary(mongocrypt_binary_t *binary);
 
-bool _mongocrypt_parse_kms_providers(mongocrypt_binary_t *kms_providers_definition,
-                                     _mongocrypt_opts_kms_providers_t *kms_providers,
-                                     mongocrypt_status_t *status,
-                                     _mongocrypt_log_t *log);
-
 /* _mongocrypt_needs_credentials returns true if @crypt was configured to
  * request credentials for any KMS provider. */
 bool _mongocrypt_needs_credentials(mongocrypt_t *crypt);
 
 /* _mongocrypt_needs_credentials returns true if @crypt was configured to
- * request credentials for @provider. */
-bool _mongocrypt_needs_credentials_for_provider(mongocrypt_t *crypt, _mongocrypt_kms_provider_t provider);
+ * request credentials for @provider and optional @name. @name may be NULL. */
+bool _mongocrypt_needs_credentials_for_provider(mongocrypt_t *crypt,
+                                                _mongocrypt_kms_provider_t provider,
+                                                const char *name);
 
 /**
  * Enable/disable the use of FLE2v2 payload types for write.

data/ext/libmongocrypt/libmongocrypt/src/mongocrypt-util.c

@@ -81,7 +81,7 @@ current_module_result current_module_path(void) {
 #elif defined(_GNU_SOURCE) || defined(_DARWIN_C_SOURCE) || defined(__FreeBSD__)
     // Darwin/BSD/glibc define extensions for finding dynamic library info from
     // the address of a symbol.
-    Dl_info info;
+    Dl_info info = {0};
     int rc = dladdr((const void *)current_module_path, &info);
     if (rc == 0) {
         // Failed to resolve the symbol
@@ -90,7 +90,8 @@ current_module_result current_module_path(void) {
         ret_str = mstr_copy_cstr(info.dli_fname);
     }
 #else
-#error "Don't know how to get the module path on this platform"
+    // Not supported on this system.
+    ret_error = ENOSYS;
 #endif
     return (current_module_result){.path = ret_str, .error = ret_error};
 }

data/ext/libmongocrypt/libmongocrypt/src/mongocrypt.c

@@ -119,8 +119,7 @@ mongocrypt_t *mongocrypt_new(void) {
     // Default to using FLEv2 (aka QEv2)
     crypt->opts.use_fle2_v2 = true;
     crypt->ctx_counter = 1;
-    crypt->cache_oauth_azure = _mongocrypt_cache_oauth_new();
-    crypt->cache_oauth_gcp = _mongocrypt_cache_oauth_new();
+    crypt->cache_oauth = mc_mapof_kmsid_to_token_new();
     crypt->csfle = (_mongo_crypt_v1_vtable){.okay = false};
 
     static mlib_once_flag init_flag = MLIB_ONCE_INITIALIZER;
@@ -154,6 +153,13 @@ bool mongocrypt_setopt_fle2v2(mongocrypt_t *crypt, bool enable) {
     return true;
 }
 
+bool mongocrypt_setopt_use_range_v2(mongocrypt_t *crypt) {
+    ASSERT_MONGOCRYPT_PARAM_UNINIT(crypt);
+
+    // Nothing to do. As of MONGOCRYPT-661, rangeV2 is the default.
+    return true;
+}
+
 bool mongocrypt_setopt_log_handler(mongocrypt_t *crypt, mongocrypt_log_fn_t log_fn, void *log_ctx) {
     ASSERT_MONGOCRYPT_PARAM_UNINIT(crypt);
     crypt->opts.log_fn = log_fn;
@@ -178,14 +184,14 @@ bool mongocrypt_setopt_kms_provider_aws(mongocrypt_t *crypt,
 
     if (!_mongocrypt_validate_and_copy_string(aws_access_key_id,
                                               aws_access_key_id_len,
-                                              &kms_providers->aws.access_key_id)) {
+                                              &kms_providers->aws_mut.access_key_id)) {
         CLIENT_ERR("invalid aws access key id");
         return false;
     }
 
     if (!_mongocrypt_validate_and_copy_string(aws_secret_access_key,
                                               aws_secret_access_key_len,
-                                              &kms_providers->aws.secret_access_key)) {
+                                              &kms_providers->aws_mut.secret_access_key)) {
         CLIENT_ERR("invalid aws secret access key");
         return false;
     }
@@ -196,11 +202,11 @@ bool mongocrypt_setopt_kms_provider_aws(mongocrypt_t *crypt,
                         "%s (%s=\"%s\", %s=%d, %s=\"%s\", %s=%d)",
                         BSON_FUNC,
                         "aws_access_key_id",
-                        kms_providers->aws.access_key_id,
+                        kms_providers->aws_mut.access_key_id,
                         "aws_access_key_id_len",
                         aws_access_key_id_len,
                         "aws_secret_access_key",
-                        kms_providers->aws.secret_access_key,
+                        kms_providers->aws_mut.secret_access_key,
                         "aws_secret_access_key_len",
                         aws_secret_access_key_len);
     }
@@ -345,7 +351,7 @@ bool mongocrypt_setopt_kms_provider_local(mongocrypt_t *crypt, mongocrypt_binary
         bson_free(key_val);
     }
 
-    _mongocrypt_buffer_copy_from_binary(&kms_providers->local.key, key);
+    _mongocrypt_buffer_copy_from_binary(&kms_providers->local_mut.key, key);
     kms_providers->configured_providers |= MONGOCRYPT_KMS_PROVIDER_LOCAL;
     return true;
 }
@@ -365,7 +371,7 @@ typedef struct {
  *
  * @param status is an optional status to set an error message if `mcr_dll_open` fails.
  */
-static _loaded_csfle _try_load_csfle(const char *filepath, _mongocrypt_log_t *log, mongocrypt_status_t *status) {
+static _loaded_csfle _try_load_csfle(const char *filepath, mongocrypt_status_t *status, _mongocrypt_log_t *log) {
     // Try to open the dynamic lib
     mcr_dll lib = mcr_dll_open(filepath);
     // Check for errors, which are represented by strings
@@ -479,7 +485,7 @@ static _loaded_csfle _try_find_csfle(mongocrypt_t *crypt) {
             // Do not allow a plain filename to go through, as that will cause the
             // DLL load to search the system.
             mstr_assign(&csfle_cand_filepath, mpath_absolute(csfle_cand_filepath.view, MPATH_NATIVE));
-            candidate_csfle = _try_load_csfle(csfle_cand_filepath.data, &crypt->log, crypt->status);
+            candidate_csfle = _try_load_csfle(csfle_cand_filepath.data, crypt->status, &crypt->log);
         }
     } else {
         // No override path was specified, so try to find it on the provided
@@ -501,7 +507,7 @@ static _loaded_csfle _try_find_csfle(mongocrypt_t *crypt) {
                 }
             }
             // Try to load the file:
-            candidate_csfle = _try_load_csfle(csfle_cand_filepath.data, &crypt->log, NULL /* status */);
+            candidate_csfle = _try_load_csfle(csfle_cand_filepath.data, NULL /* status */, &crypt->log);
             if (candidate_csfle.okay) {
                 // Stop searching:
                 break;
@@ -552,6 +558,14 @@ static bool _validate_csfle_singleton(mongocrypt_t *crypt, _loaded_csfle found)
 
     BSON_ASSERT_PARAM(crypt);
 
+    if (!mcr_dll_path_supported()) {
+        _mongocrypt_log(&crypt->log,
+                        MONGOCRYPT_LOG_LEVEL_WARNING,
+                        "Cannot get path of loaded library on this platform. Skipping validation to ensure "
+                        "exactly one csfle library is loaded.");
+        return true;
+    }
+
     status = crypt->status;
 
     // Path to the existing loaded csfle:
@@ -884,6 +898,14 @@ bool mongocrypt_init(mongocrypt_t *crypt) {
     return _try_enable_csfle(crypt);
 }
 
+bool mongocrypt_is_crypto_available(void) {
+#ifdef MONGOCRYPT_ENABLE_CRYPTO
+    return true;
+#else
+    return false;
+#endif
+}
+
 bool mongocrypt_status(mongocrypt_t *crypt, mongocrypt_status_t *out) {
     BSON_ASSERT_PARAM(crypt);
 
@@ -912,8 +934,7 @@ void mongocrypt_destroy(mongocrypt_t *crypt) {
     _mongocrypt_log_cleanup(&crypt->log);
     mongocrypt_status_destroy(crypt->status);
     bson_free(crypt->crypto);
-    _mongocrypt_cache_oauth_destroy(crypt->cache_oauth_azure);
-    _mongocrypt_cache_oauth_destroy(crypt->cache_oauth_gcp);
+    mc_mapof_kmsid_to_token_destroy(crypt->cache_oauth);
 
     if (crypt->csfle.okay) {
         _csfle_drop_global_ref();
@@ -1097,227 +1118,6 @@ bool mongocrypt_setopt_kms_providers(mongocrypt_t *crypt, mongocrypt_binary_t *k
                                            &crypt->log);
 }
 
-bool _mongocrypt_parse_kms_providers(mongocrypt_binary_t *kms_providers_definition,
-                                     _mongocrypt_opts_kms_providers_t *kms_providers,
-                                     mongocrypt_status_t *status,
-                                     _mongocrypt_log_t *log) {
-    bson_t as_bson;
-    bson_iter_t iter;
-
-    BSON_ASSERT_PARAM(kms_providers_definition);
-    BSON_ASSERT_PARAM(kms_providers);
-    if (!_mongocrypt_binary_to_bson(kms_providers_definition, &as_bson) || !bson_iter_init(&iter, &as_bson)) {
-        CLIENT_ERR("invalid BSON");
-        return false;
-    }
-
-    while (bson_iter_next(&iter)) {
-        const char *field_name;
-        bson_t field_bson;
-
-        field_name = bson_iter_key(&iter);
-        if (!mc_iter_document_as_bson(&iter, &field_bson, status)) {
-            return false;
-        }
-
-        if (0 == strcmp(field_name, "azure") && bson_empty(&field_bson)) {
-            kms_providers->need_credentials |= MONGOCRYPT_KMS_PROVIDER_AZURE;
-        } else if (0 == strcmp(field_name, "azure")) {
-            if (0 != (kms_providers->configured_providers & MONGOCRYPT_KMS_PROVIDER_AZURE)) {
-                CLIENT_ERR("azure KMS provider already set");
-                return false;
-            }
-
-            if (!_mongocrypt_parse_optional_utf8(&as_bson,
-                                                 "azure.accessToken",
-                                                 &kms_providers->azure.access_token,
-                                                 status)) {
-                return false;
-            }
-
-            if (kms_providers->azure.access_token) {
-                // Caller provides an accessToken directly
-                if (!_mongocrypt_check_allowed_fields(&as_bson, "azure", status, "accessToken")) {
-                    return false;
-                }
-                kms_providers->configured_providers |= MONGOCRYPT_KMS_PROVIDER_AZURE;
-                continue;
-            }
-
-            // No accessToken given, so we'll need to look one up on our own later
-            // using the Azure API
-
-            if (!_mongocrypt_parse_required_utf8(&as_bson, "azure.tenantId", &kms_providers->azure.tenant_id, status)) {
-                return false;
-            }
-
-            if (!_mongocrypt_parse_required_utf8(&as_bson, "azure.clientId", &kms_providers->azure.client_id, status)) {
-                return false;
-            }
-
-            if (!_mongocrypt_parse_required_utf8(&as_bson,
-                                                 "azure.clientSecret",
-                                                 &kms_providers->azure.client_secret,
-                                                 status)) {
-                return false;
-            }
-
-            if (!_mongocrypt_parse_optional_endpoint(&as_bson,
-                                                     "azure.identityPlatformEndpoint",
-                                                     &kms_providers->azure.identity_platform_endpoint,
-                                                     NULL /* opts */,
-                                                     status)) {
-                return false;
-            }
-
-            if (!_mongocrypt_check_allowed_fields(&as_bson,
-                                                  "azure",
-                                                  status,
-                                                  "tenantId",
-                                                  "clientId",
-                                                  "clientSecret",
-                                                  "identityPlatformEndpoint")) {
-                return false;
-            }
-            kms_providers->configured_providers |= MONGOCRYPT_KMS_PROVIDER_AZURE;
-        } else if (0 == strcmp(field_name, "gcp") && bson_empty(&field_bson)) {
-            kms_providers->need_credentials |= MONGOCRYPT_KMS_PROVIDER_GCP;
-        } else if (0 == strcmp(field_name, "gcp")) {
-            if (0 != (kms_providers->configured_providers & MONGOCRYPT_KMS_PROVIDER_GCP)) {
-                CLIENT_ERR("gcp KMS provider already set");
-                return false;
-            }
-
-            if (!_mongocrypt_parse_optional_utf8(&as_bson,
-                                                 "gcp.accessToken",
-                                                 &kms_providers->gcp.access_token,
-                                                 status)) {
-                return false;
-            }
-
-            if (NULL != kms_providers->gcp.access_token) {
-                /* "gcp" document has form:
-                 * {
-                 *    "accessToken": <required UTF-8>
-                 * }
-                 */
-                if (!_mongocrypt_check_allowed_fields(&as_bson, "gcp", status, "accessToken")) {
-                    return false;
-                }
-                kms_providers->configured_providers |= MONGOCRYPT_KMS_PROVIDER_GCP;
-                continue;
-            }
-
-            /* "gcp" document has form:
-             * {
-             *    "email": <required UTF-8>
-             *    "privateKey": <required UTF-8 or Binary>
-             * }
-             */
-            if (!_mongocrypt_parse_required_utf8(&as_bson, "gcp.email", &kms_providers->gcp.email, status)) {
-                return false;
-            }
-
-            if (!_mongocrypt_parse_required_binary(&as_bson,
-                                                   "gcp.privateKey",
-                                                   &kms_providers->gcp.private_key,
-                                                   status)) {
-                return false;
-            }
-
-            if (!_mongocrypt_parse_optional_endpoint(&as_bson,
-                                                     "gcp.endpoint",
-                                                     &kms_providers->gcp.endpoint,
-                                                     NULL /* opts */,
-                                                     status)) {
-                return false;
-            }
-
-            if (!_mongocrypt_check_allowed_fields(&as_bson, "gcp", status, "email", "privateKey", "endpoint")) {
-                return false;
-            }
-            kms_providers->configured_providers |= MONGOCRYPT_KMS_PROVIDER_GCP;
-        } else if (0 == strcmp(field_name, "local") && bson_empty(&field_bson)) {
-            kms_providers->need_credentials |= MONGOCRYPT_KMS_PROVIDER_LOCAL;
-        } else if (0 == strcmp(field_name, "local")) {
-            if (!_mongocrypt_parse_required_binary(&as_bson, "local.key", &kms_providers->local.key, status)) {
-                return false;
-            }
-
-            if (kms_providers->local.key.len != MONGOCRYPT_KEY_LEN) {
-                CLIENT_ERR("local key must be %d bytes", MONGOCRYPT_KEY_LEN);
-                return false;
-            }
-
-            if (!_mongocrypt_check_allowed_fields(&as_bson, "local", status, "key")) {
-                return false;
-            }
-            kms_providers->configured_providers |= MONGOCRYPT_KMS_PROVIDER_LOCAL;
-        } else if (0 == strcmp(field_name, "aws") && bson_empty(&field_bson)) {
-            kms_providers->need_credentials |= MONGOCRYPT_KMS_PROVIDER_AWS;
-        } else if (0 == strcmp(field_name, "aws")) {
-            if (!_mongocrypt_parse_required_utf8(&as_bson,
-                                                 "aws.accessKeyId",
-                                                 &kms_providers->aws.access_key_id,
-                                                 status)) {
-                return false;
-            }
-            if (!_mongocrypt_parse_required_utf8(&as_bson,
-                                                 "aws.secretAccessKey",
-                                                 &kms_providers->aws.secret_access_key,
-                                                 status)) {
-                return false;
-            }
-
-            if (!_mongocrypt_parse_optional_utf8(&as_bson,
-                                                 "aws.sessionToken",
-                                                 &kms_providers->aws.session_token,
-                                                 status)) {
-                return false;
-            }
-
-            if (!_mongocrypt_check_allowed_fields(&as_bson,
-                                                  "aws",
-                                                  status,
-                                                  "accessKeyId",
-                                                  "secretAccessKey",
-                                                  "sessionToken")) {
-                return false;
-            }
-            kms_providers->configured_providers |= MONGOCRYPT_KMS_PROVIDER_AWS;
-        } else if (0 == strcmp(field_name, "kmip") && bson_empty(&field_bson)) {
-            kms_providers->need_credentials |= MONGOCRYPT_KMS_PROVIDER_KMIP;
-        } else if (0 == strcmp(field_name, "kmip")) {
-            _mongocrypt_endpoint_parse_opts_t opts = {0};
-
-            opts.allow_empty_subdomain = true;
-            if (!_mongocrypt_parse_required_endpoint(&as_bson,
-                                                     "kmip.endpoint",
-                                                     &kms_providers->kmip.endpoint,
-                                                     &opts,
-                                                     status)) {
-                return false;
-            }
-
-            if (!_mongocrypt_check_allowed_fields(&as_bson, "kmip", status, "endpoint")) {
-                return false;
-            }
-            kms_providers->configured_providers |= MONGOCRYPT_KMS_PROVIDER_KMIP;
-        } else {
-            CLIENT_ERR("unsupported KMS provider: %s", field_name);
-            return false;
-        }
-    }
-
-    if (log && log->trace_enabled) {
-        char *as_str = bson_as_json(&as_bson, NULL);
-        _mongocrypt_log(log, MONGOCRYPT_LOG_LEVEL_TRACE, "%s (%s=\"%s\")", BSON_FUNC, "kms_providers", as_str);
-        bson_free(as_str);
-    }
-
-    return true;
-}
-
 void mongocrypt_setopt_append_crypt_shared_lib_search_path(mongocrypt_t *crypt, const char *path) {
     BSON_ASSERT_PARAM(crypt);
     BSON_ASSERT_PARAM(path);
@@ -1343,6 +1143,12 @@ void mongocrypt_setopt_use_need_kms_credentials_state(mongocrypt_t *crypt) {
     crypt->opts.use_need_kms_credentials_state = true;
 }
 
+void mongocrypt_setopt_use_need_mongo_collinfo_with_db_state(mongocrypt_t *crypt) {
+    BSON_ASSERT_PARAM(crypt);
+
+    crypt->opts.use_need_mongo_collinfo_with_db_state = true;
+}
+
 void mongocrypt_setopt_set_crypt_shared_lib_path_override(mongocrypt_t *crypt, const char *path) {
     BSON_ASSERT_PARAM(crypt);
     BSON_ASSERT_PARAM(path);
@@ -1360,9 +1166,16 @@ bool _mongocrypt_needs_credentials(mongocrypt_t *crypt) {
     return crypt->opts.kms_providers.need_credentials != 0;
 }
 
-bool _mongocrypt_needs_credentials_for_provider(mongocrypt_t *crypt, _mongocrypt_kms_provider_t provider) {
+bool _mongocrypt_needs_credentials_for_provider(mongocrypt_t *crypt,
+                                                _mongocrypt_kms_provider_t provider,
+                                                const char *name) {
     BSON_ASSERT_PARAM(crypt);
 
+    if (name != NULL) {
+        // Named KMS providers do not support on-demand credentials.
+        return false;
+    }
+
     if (!crypt->opts.use_need_kms_credentials_state) {
         return false;
     }

data/ext/libmongocrypt/libmongocrypt/src/mongocrypt.h

@@ -48,6 +48,17 @@
 MONGOCRYPT_EXPORT
 const char *mongocrypt_version(uint32_t *len);
 
+/**
+ * Returns true if libmongocrypt was built with native crypto support.
+ *
+ * If libmongocrypt was not built with native crypto support, setting crypto
+ * hooks is required.
+ *
+ * @returns True if libmongocrypt was built with native crypto support.
+ */
+MONGOCRYPT_EXPORT
+bool mongocrypt_is_crypto_available(void);
+
 /**
  * A non-owning view of a byte buffer.
  *
@@ -69,8 +80,14 @@ const char *mongocrypt_version(uint32_t *len);
  * mongocrypt_ctx_mongo_op guarantees that the viewed data of
  * mongocrypt_binary_t is valid until the parent ctx is destroyed with @ref
  * mongocrypt_ctx_destroy.
+ *
+ * The `mongocrypt_binary_t` struct definition is public.
+ * Consumers may rely on the struct layout.
  */
-typedef struct _mongocrypt_binary_t mongocrypt_binary_t;
+typedef struct _mongocrypt_binary_t {
+    void *data;
+    uint32_t len;
+} mongocrypt_binary_t;
 
 /**
  * Create a new non-owning view of a buffer (data + length).
@@ -456,6 +473,18 @@ void mongocrypt_setopt_set_crypt_shared_lib_path_override(mongocrypt_t *crypt, c
 MONGOCRYPT_EXPORT
 void mongocrypt_setopt_use_need_kms_credentials_state(mongocrypt_t *crypt);
 
+/**
+ * @brief Opt-into handling the MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state.
+ *
+ * A context enters the MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state when
+ * processing a `bulkWrite` command. The target database of the `bulkWrite` may differ from the command database
+ * ("admin").
+ *
+ * @param[in] crypt The @ref mongocrypt_t object to update
+ */
+MONGOCRYPT_EXPORT
+void mongocrypt_setopt_use_need_mongo_collinfo_with_db_state(mongocrypt_t *crypt);
+
 /**
  * Initialize new @ref mongocrypt_t object.
  *
@@ -657,10 +686,9 @@ bool mongocrypt_ctx_setopt_algorithm(mongocrypt_ctx_t *ctx, const char *algorith
 #define MONGOCRYPT_ALGORITHM_INDEXED_STR "Indexed"
 /// String constant for setopt_algorithm "Unindexed" explicit encryption
 #define MONGOCRYPT_ALGORITHM_UNINDEXED_STR "Unindexed"
-/// String constant for setopt_algorithm "rangePreview" explicit encryption
-/// NOTE: The RangePreview algorithm is experimental only. It is not intended
-/// for public use.
-#define MONGOCRYPT_ALGORITHM_RANGEPREVIEW_STR "RangePreview"
+// DEPRECATED: support "RangePreview" has been removed in favor of "range".
+#define MONGOCRYPT_ALGORITHM_RANGEPREVIEW_DEPRECATED_STR "RangePreview"
+#define MONGOCRYPT_ALGORITHM_RANGE_STR "Range"
 
 /**
  * Identify the AWS KMS master key to use for creating a data key.
@@ -849,9 +877,7 @@ bool mongocrypt_ctx_explicit_encrypt_init(mongocrypt_ctx_t *ctx, mongocrypt_bina
 /**
  * Explicit helper method to encrypt a Match Expression or Aggregate Expression.
  * Contexts created for explicit encryption will not go through mongocryptd.
- * Requires query_type to be "rangePreview".
- * NOTE: The RangePreview algorithm is experimental only. It is not intended for
- * public use.
+ * Requires query_type to be "range".
  *
  * This method expects the passed-in BSON to be of the form:
  * { "v" : FLE2RangeFindDriverSpec }
@@ -948,9 +974,10 @@ bool mongocrypt_ctx_rewrap_many_datakey_init(mongocrypt_ctx_t *ctx, mongocrypt_b
  */
 typedef enum {
     MONGOCRYPT_CTX_ERROR = 0,
-    MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1, /* run on main MongoClient */
-    MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2, /* run on mongocryptd. */
-    MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3,     /* run on key vault */
+    MONGOCRYPT_CTX_NEED_MONGO_COLLINFO = 1,         /* run on main MongoClient */
+    MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB = 8, /* run on main MongoClient */
+    MONGOCRYPT_CTX_NEED_MONGO_MARKINGS = 2,         /* run on mongocryptd. */
+    MONGOCRYPT_CTX_NEED_MONGO_KEYS = 3,             /* run on key vault */
     MONGOCRYPT_CTX_NEED_KMS = 4,
     MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS = 7, /* fetch/renew KMS credentials */
     MONGOCRYPT_CTX_READY = 5,                /* ready for encryption/decryption */
@@ -971,7 +998,7 @@ mongocrypt_ctx_state_t mongocrypt_ctx_state(mongocrypt_ctx_t *ctx);
  * is in MONGOCRYPT_CTX_NEED_MONGO_* states.
  *
  * @p op_bson is a BSON document to be used for the operation.
- * - For MONGOCRYPT_CTX_NEED_MONGO_COLLINFO it is a listCollections filter.
+ * - For MONGOCRYPT_CTX_NEED_MONGO_COLLINFO(_WITH_DB) it is a listCollections filter.
  * - For MONGOCRYPT_CTX_NEED_MONGO_KEYS it is a find filter.
  * - For MONGOCRYPT_CTX_NEED_MONGO_MARKINGS it is a command to send to
  * mongocryptd.
@@ -989,13 +1016,29 @@ mongocrypt_ctx_state_t mongocrypt_ctx_state(mongocrypt_ctx_t *ctx);
 MONGOCRYPT_EXPORT
 bool mongocrypt_ctx_mongo_op(mongocrypt_ctx_t *ctx, mongocrypt_binary_t *op_bson);
 
+/**
+ * Get the database to run the mongo operation.
+ *
+ * Only applies when mongocrypt_ctx_t is in the state:
+ * MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB.
+ *
+ * The lifetime of the returned string is tied to the lifetime of @p ctx. It is
+ * valid until @ref mongocrypt_ctx_destroy is called.
+ *
+ * @param[in] ctx The @ref mongocrypt_ctx_t object.
+ * @returns A string or NULL. If NULL, an error status is set. Retrieve it with
+ * @ref mongocrypt_ctx_status
+ */
+MONGOCRYPT_EXPORT
+const char *mongocrypt_ctx_mongo_db(mongocrypt_ctx_t *ctx);
+
 /**
  * Feed a BSON reply or result when mongocrypt_ctx_t is in
  * MONGOCRYPT_CTX_NEED_MONGO_* states. This may be called multiple times
  * depending on the operation.
  *
  * reply is a BSON document result being fed back for this operation.
- * - For MONGOCRYPT_CTX_NEED_MONGO_COLLINFO it is a doc from a listCollections
+ * - For MONGOCRYPT_CTX_NEED_MONGO_COLLINFO(_WITH_DB) it is a doc from a listCollections
  * cursor. (Note, if listCollections returned no result, do not call this
  * function.)
  * - For MONGOCRYPT_CTX_NEED_MONGO_KEYS it is a doc from a find cursor.
@@ -1305,8 +1348,7 @@ bool mongocrypt_setopt_crypto_hooks(mongocrypt_t *crypt,
  * operation.
  * @param[in] aes_256_ctr_decrypt The crypto callback function for decrypt
  * operation.
- * @param[in] ctx A context passed as an argument to the crypto callback
- * every invocation.
+ * @param[in] ctx Unused.
  * @pre @ref mongocrypt_init has not been called on @p crypt.
  * @returns A boolean indicating success. If false, an error status is set.
  * Retrieve it with @ref mongocrypt_status
@@ -1326,8 +1368,7 @@ bool mongocrypt_setopt_aes_256_ctr(mongocrypt_t *crypt,
  * @param[in] crypt The @ref mongocrypt_t object.
  * @param[in] aes_256_ecb_encrypt The crypto callback function for encrypt
  * operation.
- * @param[in] ctx A context passed as an argument to the crypto callback
- * every invocation.
+ * @param[in] ctx Unused.
  * @pre @ref mongocrypt_init has not been called on @p crypt.
  * @returns A boolean indicating success. If false, an error status is set.
  * Retrieve it with @ref mongocrypt_status
@@ -1370,6 +1411,17 @@ bool mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(mongocrypt_t *crypt,
 MONGOCRYPT_EXPORT
 void mongocrypt_setopt_bypass_query_analysis(mongocrypt_t *crypt);
 
+/**
+ * DEPRECATED: Use of `mongocrypt_setopt_use_range_v2` is deprecated. Range V2 is always enabled.
+ *
+ * @param[in] crypt The @ref mongocrypt_t object.
+ *
+ * @returns A boolean indicating success. If false, an error status is set.
+ * Retrieve it with @ref mongocrypt_status
+ */
+MONGOCRYPT_EXPORT
+bool mongocrypt_setopt_use_range_v2(mongocrypt_t *crypt);
+
 /**
  * Set the contention factor used for explicit encryption.
  * The contention factor is only used for indexed Queryable Encryption.
@@ -1415,16 +1467,15 @@ MONGOCRYPT_EXPORT
 bool mongocrypt_ctx_setopt_query_type(mongocrypt_ctx_t *ctx, const char *query_type, int len);
 
 /**
- * Set options for explicit encryption with the "rangePreview" algorithm.
- * NOTE: The RangePreview algorithm is experimental only. It is not intended for
- * public use.
+ * Set options for explicit encryption with the "range" algorithm.
  *
  * @p opts is a BSON document of the form:
  * {
  *    "min": Optional<BSON value>,
  *    "max": Optional<BSON value>,
  *    "sparsity": Int64,
- *    "precision": Optional<Int32>
+ *    "precision": Optional<Int32>,
+ *    "trimFactor": Optional<Int32>
  * }
  *
  * @param[in] ctx The @ref mongocrypt_ctx_t object.
@@ -1438,8 +1489,8 @@ bool mongocrypt_ctx_setopt_algorithm_range(mongocrypt_ctx_t *ctx, mongocrypt_bin
 
 /// String constants for setopt_query_type
 #define MONGOCRYPT_QUERY_TYPE_EQUALITY_STR "equality"
-// NOTE: The RangePreview algorithm is experimental only. It is not intended for
-// public use.
-#define MONGOCRYPT_QUERY_TYPE_RANGEPREVIEW_STR "rangePreview"
+// DEPRECATED: Support "rangePreview" has been removed in favor of "range".
+#define MONGOCRYPT_QUERY_TYPE_RANGEPREVIEW_DEPRECATED_STR "rangePreview"
+#define MONGOCRYPT_QUERY_TYPE_RANGE_STR "range"
 
 #endif /* MONGOCRYPT_H */