libmongocrypt-helper 1.12.0.0.1001 → 1.14.0.0.1001

data/ext/libmongocrypt/libmongocrypt/src/mc-fle2-insert-update-payload-v2.c

@@ -17,15 +17,76 @@
 #include <bson/bson.h>
 
 #include "mc-fle2-insert-update-payload-private-v2.h"
+#include "mc-parse-utils-private.h"
 #include "mongocrypt-buffer-private.h"
 #include "mongocrypt-util-private.h" // mc_bson_type_to_string
 #include "mongocrypt.h"
 
+#define DEF_TEXT_SEARCH_TOKEN_SET_INIT_CLEANUP(Type)                                                                   \
+    void mc_Text##Type##TokenSet_init(mc_Text##Type##TokenSet_t *ts) {                                                 \
+        BSON_ASSERT_PARAM(ts);                                                                                         \
+        memset(ts, 0, sizeof(mc_Text##Type##TokenSet_t));                                                              \
+    }                                                                                                                  \
+    void mc_Text##Type##TokenSet_cleanup(mc_Text##Type##TokenSet_t *ts) {                                              \
+        BSON_ASSERT_PARAM(ts);                                                                                         \
+        _mongocrypt_buffer_cleanup(&ts->edcDerivedToken);                                                              \
+        _mongocrypt_buffer_cleanup(&ts->escDerivedToken);                                                              \
+        _mongocrypt_buffer_cleanup(&ts->serverDerivedFromDataToken);                                                   \
+        _mongocrypt_buffer_cleanup(&ts->encryptedTokens);                                                              \
+    }                                                                                                                  \
+    void mc_Text##Type##TokenSet_shallow_copy(const mc_Text##Type##TokenSet_t *src, mc_Text##Type##TokenSet_t *dst) {  \
+        BSON_ASSERT_PARAM(src);                                                                                        \
+        BSON_ASSERT_PARAM(dst);                                                                                        \
+        _mongocrypt_buffer_set_to(&src->edcDerivedToken, &dst->edcDerivedToken);                                       \
+        _mongocrypt_buffer_set_to(&src->escDerivedToken, &dst->escDerivedToken);                                       \
+        _mongocrypt_buffer_set_to(&src->serverDerivedFromDataToken, &dst->serverDerivedFromDataToken);                 \
+        _mongocrypt_buffer_set_to(&src->encryptedTokens, &dst->encryptedTokens);                                       \
+    }
+
+DEF_TEXT_SEARCH_TOKEN_SET_INIT_CLEANUP(Exact)
+DEF_TEXT_SEARCH_TOKEN_SET_INIT_CLEANUP(Substring)
+DEF_TEXT_SEARCH_TOKEN_SET_INIT_CLEANUP(Suffix)
+DEF_TEXT_SEARCH_TOKEN_SET_INIT_CLEANUP(Prefix)
+#undef DEF_TEXT_SEARCH_TOKEN_SET_INIT_CLEANUP
+
+void mc_TextSearchTokenSets_init(mc_TextSearchTokenSets_t *tsts) {
+    BSON_ASSERT_PARAM(tsts);
+    mc_TextExactTokenSet_init(&tsts->exact);
+    _mc_array_init(&tsts->substringArray, sizeof(mc_TextSubstringTokenSet_t));
+    _mc_array_init(&tsts->suffixArray, sizeof(mc_TextSuffixTokenSet_t));
+    _mc_array_init(&tsts->prefixArray, sizeof(mc_TextPrefixTokenSet_t));
+}
+
+void mc_TextSearchTokenSets_cleanup(mc_TextSearchTokenSets_t *tsts) {
+    BSON_ASSERT_PARAM(tsts);
+    mc_TextExactTokenSet_cleanup(&tsts->exact);
+
+    for (size_t i = 0; i < tsts->substringArray.len; i++) {
+        mc_TextSubstringTokenSet_t *entry = &_mc_array_index(&tsts->substringArray, mc_TextSubstringTokenSet_t, i);
+        mc_TextSubstringTokenSet_cleanup(entry);
+    }
+    _mc_array_destroy(&tsts->substringArray);
+
+    for (size_t i = 0; i < tsts->suffixArray.len; i++) {
+        mc_TextSuffixTokenSet_t *entry = &_mc_array_index(&tsts->suffixArray, mc_TextSuffixTokenSet_t, i);
+        mc_TextSuffixTokenSet_cleanup(entry);
+    }
+    _mc_array_destroy(&tsts->suffixArray);
+
+    // Free all prefix token set entries.
+    for (size_t i = 0; i < tsts->prefixArray.len; i++) {
+        mc_TextPrefixTokenSet_t *entry = &_mc_array_index(&tsts->prefixArray, mc_TextPrefixTokenSet_t, i);
+        mc_TextPrefixTokenSet_cleanup(entry);
+    }
+    _mc_array_destroy(&tsts->prefixArray);
+}
+
 void mc_FLE2InsertUpdatePayloadV2_init(mc_FLE2InsertUpdatePayloadV2_t *payload) {
     BSON_ASSERT_PARAM(payload);
 
     memset(payload, 0, sizeof(mc_FLE2InsertUpdatePayloadV2_t));
     _mc_array_init(&payload->edgeTokenSetArray, sizeof(mc_EdgeTokenSetV2_t));
+    mc_TextSearchTokenSets_init(&payload->textSearchTokenSets.tsts);
 }
 
 static void mc_EdgeTokenSetV2_cleanup(mc_EdgeTokenSetV2_t *etc) {
@@ -56,6 +117,7 @@ void mc_FLE2InsertUpdatePayloadV2_cleanup(mc_FLE2InsertUpdatePayloadV2_t *payloa
     _mc_array_destroy(&payload->edgeTokenSetArray);
     bson_value_destroy(&payload->indexMin);
     bson_value_destroy(&payload->indexMax);
+    mc_TextSearchTokenSets_cleanup(&payload->textSearchTokenSets.tsts);
 }
 
 #define IF_FIELD(Name)                                                                                                 \
@@ -72,21 +134,7 @@ void mc_FLE2InsertUpdatePayloadV2_cleanup(mc_FLE2InsertUpdatePayloadV2_t *payloa
 
 #define PARSE_BINDATA(Name, Type, Dest)                                                                                \
     IF_FIELD(Name) {                                                                                                   \
-        bson_subtype_t subtype;                                                                                        \
-        uint32_t len;                                                                                                  \
-        const uint8_t *data;                                                                                           \
-        if (bson_iter_type(&iter) != BSON_TYPE_BINARY) {                                                               \
-            CLIENT_ERR("Field '" #Name "' expected to be bindata, got: %d", bson_iter_type(&iter));                    \
-            goto fail;                                                                                                 \
-        }                                                                                                              \
-        bson_iter_binary(&iter, &subtype, &len, &data);                                                                \
-        if (subtype != Type) {                                                                                         \
-            CLIENT_ERR("Field '" #Name "' expected to be bindata subtype %d, got: %d", Type, subtype);                 \
-            goto fail;                                                                                                 \
-        }                                                                                                              \
-        if (!_mongocrypt_buffer_copy_from_binary_iter(&out->Dest, &iter)) {                                            \
-            CLIENT_ERR("Unable to create mongocrypt buffer for BSON binary "                                           \
-                       "field in '" #Name "'");                                                                        \
+        if (!parse_bindata(Type, &iter, &out->Dest, status)) {                                                         \
             goto fail;                                                                                                 \
         }                                                                                                              \
     }                                                                                                                  \
@@ -98,7 +146,8 @@ void mc_FLE2InsertUpdatePayloadV2_cleanup(mc_FLE2InsertUpdatePayloadV2_t *payloa
     if (!has_##Name) {                                                                                                 \
         CLIENT_ERR("Missing field '" #Name "' in payload");                                                            \
         goto fail;                                                                                                     \
-    }
+    } else                                                                                                             \
+        ((void)0)
 
 bool mc_FLE2InsertUpdatePayloadV2_parse(mc_FLE2InsertUpdatePayloadV2_t *out,
                                         const _mongocrypt_buffer_t *in,
@@ -239,14 +288,14 @@ bool mc_FLE2InsertUpdatePayloadV2_parse(mc_FLE2InsertUpdatePayloadV2_t *out,
 
     return true;
 fail:
-    mc_FLE2InsertUpdatePayloadV2_cleanup(out);
     return false;
 }
 
 #define IUPS_APPEND_BINDATA(dst, name, subtype, value)                                                                 \
     if (!_mongocrypt_buffer_append(&(value), dst, name, -1)) {                                                         \
         return false;                                                                                                  \
-    }
+    } else                                                                                                             \
+        ((void)0)
 
 bool mc_FLE2InsertUpdatePayloadV2_serialize(const mc_FLE2InsertUpdatePayloadV2_t *payload, bson_t *out) {
     BSON_ASSERT_PARAM(out);
@@ -269,9 +318,7 @@ bool mc_FLE2InsertUpdatePayloadV2_serialize(const mc_FLE2InsertUpdatePayloadV2_t
     return true;
 }
 
-bool mc_FLE2InsertUpdatePayloadV2_serializeForRange(const mc_FLE2InsertUpdatePayloadV2_t *payload,
-                                                    bson_t *out,
-                                                    bool use_range_v2) {
+bool mc_FLE2InsertUpdatePayloadV2_serializeForRange(const mc_FLE2InsertUpdatePayloadV2_t *payload, bson_t *out) {
     BSON_ASSERT_PARAM(out);
     BSON_ASSERT_PARAM(payload);
 
@@ -315,41 +362,143 @@ bool mc_FLE2InsertUpdatePayloadV2_serializeForRange(const mc_FLE2InsertUpdatePay
         return false;
     }
 
-    if (use_range_v2) {
-        // Encode parameters that were used to generate the payload.
-        BSON_ASSERT(payload->sparsity.set);
-        if (!BSON_APPEND_INT64(out, "sp", payload->sparsity.value)) {
-            return false;
-        }
-
-        // Precision may be unset.
-        if (payload->precision.set) {
-            if (!BSON_APPEND_INT32(out, "pn", payload->precision.value)) {
-                return false;
-            }
-        }
+    // Encode parameters that were used to generate the payload.
+    BSON_ASSERT(payload->sparsity.set);
+    if (!BSON_APPEND_INT64(out, "sp", payload->sparsity.value)) {
+        return false;
+    }
 
-        BSON_ASSERT(payload->trimFactor.set);
-        if (!BSON_APPEND_INT32(out, "tf", payload->trimFactor.value)) {
+    // Precision may be unset.
+    if (payload->precision.set) {
+        if (!BSON_APPEND_INT32(out, "pn", payload->precision.value)) {
             return false;
         }
+    }
 
-        BSON_ASSERT(payload->indexMin.value_type != BSON_TYPE_EOD);
-        if (!BSON_APPEND_VALUE(out, "mn", &payload->indexMin)) {
-            return false;
-        }
+    BSON_ASSERT(payload->trimFactor.set);
+    if (!BSON_APPEND_INT32(out, "tf", payload->trimFactor.value)) {
+        return false;
+    }
 
-        BSON_ASSERT(payload->indexMax.value_type != BSON_TYPE_EOD);
-        if (!BSON_APPEND_VALUE(out, "mx", &payload->indexMax)) {
-            return false;
-        }
+    BSON_ASSERT(payload->indexMin.value_type != BSON_TYPE_EOD);
+    if (!BSON_APPEND_VALUE(out, "mn", &payload->indexMin)) {
+        return false;
+    }
+
+    BSON_ASSERT(payload->indexMax.value_type != BSON_TYPE_EOD);
+    if (!BSON_APPEND_VALUE(out, "mx", &payload->indexMax)) {
+        return false;
     }
 
     return true;
 }
 
+#define SERIALIZE_TEXT_TOKEN_SET_FOR_TYPE_IMPL(Type)                                                                   \
+    static bool _fle2_serialize_Text##Type##TokenSet(bson_t *parent,                                                   \
+                                                     const char *field_name,                                           \
+                                                     const mc_Text##Type##TokenSet_t *ts) {                            \
+        BSON_ASSERT_PARAM(parent);                                                                                     \
+        BSON_ASSERT_PARAM(field_name);                                                                                 \
+        BSON_ASSERT_PARAM(ts);                                                                                         \
+        bson_t child;                                                                                                  \
+        if (!BSON_APPEND_DOCUMENT_BEGIN(parent, field_name, &child)) {                                                 \
+            return false;                                                                                              \
+        }                                                                                                              \
+        IUPS_APPEND_BINDATA(&child, "d", BSON_SUBTYPE_BINARY, ts->edcDerivedToken);                                    \
+        IUPS_APPEND_BINDATA(&child, "s", BSON_SUBTYPE_BINARY, ts->escDerivedToken);                                    \
+        IUPS_APPEND_BINDATA(&child, "l", BSON_SUBTYPE_BINARY, ts->serverDerivedFromDataToken);                         \
+        IUPS_APPEND_BINDATA(&child, "p", BSON_SUBTYPE_BINARY, ts->encryptedTokens);                                    \
+        if (!bson_append_document_end(parent, &child)) {                                                               \
+            return false;                                                                                              \
+        }                                                                                                              \
+        return true;                                                                                                   \
+    }
+SERIALIZE_TEXT_TOKEN_SET_FOR_TYPE_IMPL(Exact)
+SERIALIZE_TEXT_TOKEN_SET_FOR_TYPE_IMPL(Substring)
+SERIALIZE_TEXT_TOKEN_SET_FOR_TYPE_IMPL(Suffix)
+SERIALIZE_TEXT_TOKEN_SET_FOR_TYPE_IMPL(Prefix)
+#undef SERIALIZE_TEXT_TOKEN_SET_FOR_TYPE_IMPL
+
 #undef IUPS_APPEND_BINDATA
 
+#define SERIALIZE_ARRAY_OF_TEXT_TOKEN_SET_FOR_TYPE_IMPL(Type)                                                          \
+    static bool _fle2_serialize_array_of_Text##Type##TokenSet(bson_t *parent,                                          \
+                                                              const char *array_name,                                  \
+                                                              const mc_array_t *array) {                               \
+        BSON_ASSERT_PARAM(parent);                                                                                     \
+        BSON_ASSERT_PARAM(array_name);                                                                                 \
+        BSON_ASSERT_PARAM(array);                                                                                      \
+        bson_t arr_bson;                                                                                               \
+        if (!BSON_APPEND_ARRAY_BEGIN(parent, array_name, &arr_bson)) {                                                 \
+            return false;                                                                                              \
+        }                                                                                                              \
+                                                                                                                       \
+        const char *index_string = NULL;                                                                               \
+        char storage[16];                                                                                              \
+        uint32_t index = 0;                                                                                            \
+        uint32_t limit = (array->len > UINT32_MAX) ? UINT32_MAX : (uint32_t)array->len;                                \
+        for (; index < limit; index++) {                                                                               \
+            mc_Text##Type##TokenSet_t ts = _mc_array_index(array, mc_Text##Type##TokenSet_t, index);                   \
+            bson_uint32_to_string(index, &index_string, storage, sizeof(storage));                                     \
+                                                                                                                       \
+            if (!_fle2_serialize_Text##Type##TokenSet(&arr_bson, index_string, &ts)) {                                 \
+                return false;                                                                                          \
+            }                                                                                                          \
+        }                                                                                                              \
+        if (!bson_append_array_end(parent, &arr_bson)) {                                                               \
+            return false;                                                                                              \
+        }                                                                                                              \
+        return true;                                                                                                   \
+    }
+SERIALIZE_ARRAY_OF_TEXT_TOKEN_SET_FOR_TYPE_IMPL(Substring)
+SERIALIZE_ARRAY_OF_TEXT_TOKEN_SET_FOR_TYPE_IMPL(Suffix)
+SERIALIZE_ARRAY_OF_TEXT_TOKEN_SET_FOR_TYPE_IMPL(Prefix)
+#undef SERIALIZE_ARRAY_OF_TEXT_TOKEN_SET_FOR_TYPE_IMPL
+
+bool mc_FLE2InsertUpdatePayloadV2_serializeForTextSearch(const mc_FLE2InsertUpdatePayloadV2_t *payload, bson_t *out) {
+    BSON_ASSERT_PARAM(out);
+    BSON_ASSERT_PARAM(payload);
+    BSON_ASSERT(payload->textSearchTokenSets.set);
+
+    if (!mc_FLE2InsertUpdatePayloadV2_serialize(payload, out)) {
+        return false;
+    }
+
+    const mc_TextSearchTokenSets_t *tsts = &payload->textSearchTokenSets.tsts;
+
+    // Start serializing "b", the TextSearchTokenSets
+    bson_t b_bson;
+    if (!BSON_APPEND_DOCUMENT_BEGIN(out, "b", &b_bson)) {
+        return false;
+    }
+
+    // Serialize "b.e", the TextExactTokenSet
+    if (!_fle2_serialize_TextExactTokenSet(&b_bson, "e", &tsts->exact)) {
+        return false;
+    }
+
+    // Serialize "b.s", the array of TextSubstringTokenSet
+    if (!_fle2_serialize_array_of_TextSubstringTokenSet(&b_bson, "s", &tsts->substringArray)) {
+        return false;
+    }
+
+    // Serialize "b.u", the array of TextSuffixTokenSet
+    if (!_fle2_serialize_array_of_TextSuffixTokenSet(&b_bson, "u", &tsts->suffixArray)) {
+        return false;
+    }
+
+    // Serialize "b.p", the array of TextPrefixTokenSet
+    if (!_fle2_serialize_array_of_TextPrefixTokenSet(&b_bson, "p", &tsts->prefixArray)) {
+        return false;
+    }
+
+    // End serializing "b", the TextSearchTokenSets
+    if (!bson_append_document_end(out, &b_bson)) {
+        return false;
+    }
+    return true;
+}
+
 const _mongocrypt_buffer_t *mc_FLE2InsertUpdatePayloadV2_decrypt(_mongocrypt_crypto_t *crypto,
                                                                  mc_FLE2InsertUpdatePayloadV2_t *iup,
                                                                  const _mongocrypt_buffer_t *user_key,

data/ext/libmongocrypt/libmongocrypt/src/mc-fle2-insert-update-payload.c

@@ -17,6 +17,7 @@
 #include <bson/bson.h>
 
 #include "mc-fle2-insert-update-payload-private.h"
+#include "mc-parse-utils-private.h"
 #include "mongocrypt-buffer-private.h"
 #include "mongocrypt.h"
 
@@ -69,21 +70,7 @@ void mc_FLE2InsertUpdatePayload_cleanup(mc_FLE2InsertUpdatePayload_t *payload) {
 
 #define PARSE_BINDATA(Name, Type, Dest)                                                                                \
     IF_FIELD(Name) {                                                                                                   \
-        bson_subtype_t subtype;                                                                                        \
-        uint32_t len;                                                                                                  \
-        const uint8_t *data;                                                                                           \
-        if (bson_iter_type(&iter) != BSON_TYPE_BINARY) {                                                               \
-            CLIENT_ERR("Field '" #Name "' expected to be bindata, got: %d", bson_iter_type(&iter));                    \
-            goto fail;                                                                                                 \
-        }                                                                                                              \
-        bson_iter_binary(&iter, &subtype, &len, &data);                                                                \
-        if (subtype != Type) {                                                                                         \
-            CLIENT_ERR("Field '" #Name "' expected to be bindata subtype %d, got: %d", Type, subtype);                 \
-            goto fail;                                                                                                 \
-        }                                                                                                              \
-        if (!_mongocrypt_buffer_copy_from_binary_iter(&out->Dest, &iter)) {                                            \
-            CLIENT_ERR("Unable to create mongocrypt buffer for BSON binary "                                           \
-                       "field in '" #Name "'");                                                                        \
+        if (!parse_bindata(Type, &iter, &out->Dest, status)) {                                                         \
             goto fail;                                                                                                 \
         }                                                                                                              \
     }                                                                                                                  \
@@ -95,7 +82,8 @@ void mc_FLE2InsertUpdatePayload_cleanup(mc_FLE2InsertUpdatePayload_t *payload) {
     if (!has_##Name) {                                                                                                 \
         CLIENT_ERR("Missing field '" #Name "' in payload");                                                            \
         goto fail;                                                                                                     \
-    }
+    } else                                                                                                             \
+        ((void)0)
 
 bool mc_FLE2InsertUpdatePayload_parse(mc_FLE2InsertUpdatePayload_t *out,
                                       const _mongocrypt_buffer_t *in,
@@ -167,14 +155,14 @@ bool mc_FLE2InsertUpdatePayload_parse(mc_FLE2InsertUpdatePayload_t *out,
 
     return true;
 fail:
-    mc_FLE2InsertUpdatePayload_cleanup(out);
     return false;
 }
 
 #define IUPS_APPEND_BINDATA(dst, name, subtype, value)                                                                 \
     if (!_mongocrypt_buffer_append(&(value), dst, name, -1)) {                                                         \
         return false;                                                                                                  \
-    }
+    } else                                                                                                             \
+        ((void)0)
 
 bool mc_FLE2InsertUpdatePayload_serialize(const mc_FLE2InsertUpdatePayload_t *payload, bson_t *out) {
     BSON_ASSERT_PARAM(out);

data/ext/libmongocrypt/libmongocrypt/src/mc-fle2-payload-iev-private-v2.h

@@ -24,7 +24,7 @@
 #include "mongocrypt-status-private.h"
 
 /*
- * FLE2IndexedEqualityEncryptedValueV2 and FLE2IndexedRangeEncryptedValueV2
+ * FLE2IndexedEqualityEncryptedValueV2, FLE2IndexedRangeEncryptedValueV2, and FLEIndexedTextEncryptedValue
  * share a common internal implementation.
  *
  * Lifecycle:
@@ -75,12 +75,69 @@
  *
  * Note that this format differs from FLE2IndexedEqualityEncryptedValueV2
  * in only two ways:
- * 1/ `edge_count` is introduced as an octet following `original_bson_type`.
+ * 1/ `edge_count` is introduced as a 8 bit int following `original_bson_type`.
  * 2/ Rather than a single metadata block, we have {edge_count} blocks.
  *
+ * FLE2IndexedTextEncryptedValue has the following data layout:
+ *
+ * struct FLE2IndexedTextEncryptedValue {
+ *   uint8_t fle_blob_subtype = 17;
+ *   uint8_t S_KeyId[16];
+ *   uint8_t original_bson_type;
+ *   uint32_t edge_count;
+ *   uint32_t substr_tag_count;
+ *   uint32_t suffix_tag_count;
+ *   uint8_t ServerEncryptedValue[ServerEncryptedValue.length];
+ *   FLE2TagAndEncryptedMetadataBlock exact_metadata;
+ *   FLE2TagAndEncryptedMetadataBlock substr_metadata[substr_tag_count];
+ *   FLE2TagAndEncryptedMetadataBlock suffix_metadata[suffix_tag_count];
+ *   FLE2TagAndEncryptedMetadataBlock prefix_metadata[edge_count - suffix_tag_count - substr_tag_count - 1];
+ * }
+ * The main difference in this format is that we split `metadata` into 4
+ * sections, one for each text search index type. We expand edge_count
+ * to be a 32 bit integer rather than 8 bit. We add two 32 bit ints,
+ * `substr_tag_count` and `suffix_tag_count`, following `edge_count`
+ * in order to track the delineation of the metadata. Similarly to
+ * FLE2IndexedEqualityEncryptedValueV2, we have `edge_count` total
+ * blocks.
  */
 
-typedef struct _mc_FLE2IndexedEncryptedValueV2_t mc_FLE2IndexedEncryptedValueV2_t;
+typedef enum {
+    kFLE2IEVTypeInitV2,
+    kFLE2IEVTypeEqualityV2,
+    kFLE2IEVTypeRangeV2,
+    kFLE2IEVTypeText,
+} _mc_fle2_iev_v2_type;
+
+typedef struct _mc_FLE2IndexedEncryptedValueV2_t {
+    // Raw payload values
+    uint8_t fle_blob_subtype;
+    uint8_t bson_value_type;
+    uint32_t edge_count;
+    uint32_t substr_tag_count;
+    uint32_t suffix_tag_count;
+    _mongocrypt_buffer_t S_KeyId;
+    _mongocrypt_buffer_t ServerEncryptedValue;
+
+    // Decode State
+    _mc_fle2_iev_v2_type type;
+    bool ClientEncryptedValueDecoded;
+    bool ClientValueDecoded;
+
+    // Populated during _add_S_Key
+    // DecryptedServerEncryptedValue := DecryptCTR(S_Key, ServerEncryptedValue)
+    _mongocrypt_buffer_t DecryptedServerEncryptedValue;
+
+    // Views on DecryptedServerEncryptedValue (DSEV)
+    _mongocrypt_buffer_t K_KeyId;              // First 16 octets, UUID
+    _mongocrypt_buffer_t ClientEncryptedValue; // Remainder of DSEV
+
+    // Populated during _add_K_Key
+    // ClientValue := DecryptCBCAEAD(K_Key, ClientEncryptedValue, AD=K_KeyId)
+    _mongocrypt_buffer_t ClientValue;
+
+    mc_FLE2TagAndEncryptedMetadataBlock_t *metadata;
+} mc_FLE2IndexedEncryptedValueV2_t;
 
 mc_FLE2IndexedEncryptedValueV2_t *mc_FLE2IndexedEncryptedValueV2_new(void);
 bson_type_t mc_FLE2IndexedEncryptedValueV2_get_bson_value_type(const mc_FLE2IndexedEncryptedValueV2_t *iev,
@@ -95,8 +152,12 @@ bson_type_t mc_FLE2IndexedEncryptedValueV2_get_bson_value_type(const mc_FLE2Inde
  * original_bson_type (8u)
  * if (range)
  *   edge_count(8u)
+ * if (text)
+ *   edge_count(32u)
+ *   substr_tag_count(32u)
+ *   suffix_tag_count(32u)
  * ServerEncryptedValue (8u * SEV_len)
- * metadata (96u * {range ? edge_count : 1u})
+ * metadata (96u * {range || text ? edge_count : 1u})
  *
  * Returns an error if the input buffer is not valid.
  */
@@ -118,6 +179,12 @@ bool mc_FLE2IndexedEncryptedValueV2_serialize(const mc_FLE2IndexedEncryptedValue
                                               _mongocrypt_buffer_t *buf,
                                               mongocrypt_status_t *status);
 
+/**
+ * Validates that a mc_FLE2IndexedEncryptedValueV2_t is well-formed, i.e. values are in their valid
+ * ranges and buffers are correctly sized. Returns an error if the input structure is invalid.
+ */
+bool mc_FLE2IndexedEncryptedValueV2_validate(const mc_FLE2IndexedEncryptedValueV2_t *iev, mongocrypt_status_t *status);
+
 const _mongocrypt_buffer_t *mc_FLE2IndexedEncryptedValueV2_get_S_KeyId(const mc_FLE2IndexedEncryptedValueV2_t *iev,
                                                                        mongocrypt_status_t *status);
 
@@ -141,18 +208,49 @@ bool mc_FLE2IndexedEncryptedValueV2_add_K_Key(_mongocrypt_crypto_t *crypto,
 const _mongocrypt_buffer_t *mc_FLE2IndexedEncryptedValueV2_get_ClientValue(const mc_FLE2IndexedEncryptedValueV2_t *iev,
                                                                            mongocrypt_status_t *status);
 
-uint8_t mc_FLE2IndexedEncryptedValueV2_get_edge_count(const mc_FLE2IndexedEncryptedValueV2_t *iev,
-                                                      mongocrypt_status_t *status);
+uint32_t mc_FLE2IndexedEncryptedValueV2_get_edge_count(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                                       mongocrypt_status_t *status);
+
+bool mc_FLE2IndexedEncryptedValueV2_get_substr_tag_count(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                                         uint32_t *count,
+                                                         mongocrypt_status_t *status);
+
+bool mc_FLE2IndexedEncryptedValueV2_get_suffix_tag_count(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                                         uint32_t *count,
+                                                         mongocrypt_status_t *status);
+
+bool mc_FLE2IndexedEncryptedValueV2_get_prefix_tag_count(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                                         uint32_t *count,
+                                                         mongocrypt_status_t *status);
 
 bool mc_FLE2IndexedEncryptedValueV2_get_edge(const mc_FLE2IndexedEncryptedValueV2_t *iev,
                                              mc_FLE2TagAndEncryptedMetadataBlock_t *out,
-                                             const uint8_t edge_index,
+                                             const uint32_t edge_index,
                                              mongocrypt_status_t *status);
 
 bool mc_FLE2IndexedEncryptedValueV2_get_metadata(const mc_FLE2IndexedEncryptedValueV2_t *iev,
                                                  mc_FLE2TagAndEncryptedMetadataBlock_t *out,
                                                  mongocrypt_status_t *status);
 
+bool mc_FLE2IndexedEncryptedValueV2_get_exact_metadata(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                                       mc_FLE2TagAndEncryptedMetadataBlock_t *out,
+                                                       mongocrypt_status_t *status);
+
+bool mc_FLE2IndexedEncryptedValueV2_get_substr_metadata(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                                        mc_FLE2TagAndEncryptedMetadataBlock_t *out,
+                                                        const uint32_t block_index,
+                                                        mongocrypt_status_t *status);
+
+bool mc_FLE2IndexedEncryptedValueV2_get_suffix_metadata(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                                        mc_FLE2TagAndEncryptedMetadataBlock_t *out,
+                                                        const uint32_t block_index,
+                                                        mongocrypt_status_t *status);
+
+bool mc_FLE2IndexedEncryptedValueV2_get_prefix_metadata(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                                        mc_FLE2TagAndEncryptedMetadataBlock_t *out,
+                                                        const uint32_t block_index,
+                                                        mongocrypt_status_t *status);
+
 void mc_FLE2IndexedEncryptedValueV2_destroy(mc_FLE2IndexedEncryptedValueV2_t *iev);
 
 #endif /* MONGOCRYPT_INDEXED_ENCRYPTED_VALUE_PRIVATE_V2_H */