libmongocrypt-helper 1.11.0.0.1001 → 1.13.2.0.1001

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

@@ -25,6 +25,32 @@
 #include "mongocrypt-private.h"
 #include "mongocrypt.h"
 
+#define DEF_TEXT_SEARCH_TOKEN_SET(Type)                                                                                \
+    typedef struct {                                                                                                   \
+        _mongocrypt_buffer_t edcDerivedToken;                                                                          \
+        _mongocrypt_buffer_t escDerivedToken;                                                                          \
+        _mongocrypt_buffer_t serverDerivedFromDataToken;                                                               \
+        _mongocrypt_buffer_t encryptedTokens;                                                                          \
+    } mc_Text##Type##TokenSet_t;                                                                                       \
+    void mc_Text##Type##TokenSet_init(mc_Text##Type##TokenSet_t *);                                                    \
+    void mc_Text##Type##TokenSet_cleanup(mc_Text##Type##TokenSet_t *);                                                 \
+    void mc_Text##Type##TokenSet_shallow_copy(const mc_Text##Type##TokenSet_t *src, mc_Text##Type##TokenSet_t *dest)
+
+DEF_TEXT_SEARCH_TOKEN_SET(Exact);
+DEF_TEXT_SEARCH_TOKEN_SET(Substring);
+DEF_TEXT_SEARCH_TOKEN_SET(Suffix);
+DEF_TEXT_SEARCH_TOKEN_SET(Prefix);
+
+typedef struct {
+    mc_TextExactTokenSet_t exact; // e
+    mc_array_t substringArray;    // s
+    mc_array_t suffixArray;       // u
+    mc_array_t prefixArray;       // p
+} mc_TextSearchTokenSets_t;
+
+void mc_TextSearchTokenSets_init(mc_TextSearchTokenSets_t *);
+void mc_TextSearchTokenSets_cleanup(mc_TextSearchTokenSets_t *);
+
 /**
  * FLE2InsertUpdatePayloadV2 represents an FLE2 payload of an indexed field to
  * insert or update. It is created client side.
@@ -83,10 +109,21 @@ typedef struct {
     mc_optional_int32_t trimFactor;                  // tf
     bson_value_t indexMin;                           // mn
     bson_value_t indexMax;                           // mx
+
+    struct {
+        mc_TextSearchTokenSets_t tsts;
+        bool set;
+    } textSearchTokenSets; // b
+
     _mongocrypt_buffer_t plaintext;
     _mongocrypt_buffer_t userKeyId;
 } mc_FLE2InsertUpdatePayloadV2_t;
 
+// `mc_FLE2InsertUpdatePayloadV2_t` inherits extended alignment from libbson. To dynamically allocate, use
+// aligned allocation (e.g. BSON_ALIGNED_ALLOC)
+BSON_STATIC_ASSERT2(alignof_mc_FLE2InsertUpdatePayloadV2_t,
+                    BSON_ALIGNOF(mc_FLE2InsertUpdatePayloadV2_t) >= BSON_ALIGNOF(bson_value_t));
+
 /**
  * EdgeTokenSetV2 is the following BSON document:
  * d: <binary> // EDCDerivedFromDataTokenAndContentionFactor
@@ -125,6 +162,8 @@ bool mc_FLE2InsertUpdatePayloadV2_serializeForRange(const mc_FLE2InsertUpdatePay
                                                     bson_t *out,
                                                     bool use_range_v2);
 
+bool mc_FLE2InsertUpdatePayloadV2_serializeForTextSearch(const mc_FLE2InsertUpdatePayloadV2_t *payload, bson_t *out);
+
 void mc_FLE2InsertUpdatePayloadV2_cleanup(mc_FLE2InsertUpdatePayloadV2_t *payload);
 
 #endif /* MC_FLE2_INSERT_UPDATE_PAYLOAD_PRIVATE_V2_H */

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

@@ -21,11 +21,71 @@
 #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 +116,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)                                                                                                 \
@@ -239,7 +300,6 @@ bool mc_FLE2InsertUpdatePayloadV2_parse(mc_FLE2InsertUpdatePayloadV2_t *out,
 
     return true;
 fail:
-    mc_FLE2InsertUpdatePayloadV2_cleanup(out);
     return false;
 }
 
@@ -348,8 +408,112 @@ bool mc_FLE2InsertUpdatePayloadV2_serializeForRange(const mc_FLE2InsertUpdatePay
     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

@@ -167,7 +167,6 @@ bool mc_FLE2InsertUpdatePayload_parse(mc_FLE2InsertUpdatePayload_t *out,
 
     return true;
 fail:
-    mc_FLE2InsertUpdatePayload_cleanup(out);
     return false;
 }
 

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

@@ -17,65 +17,28 @@
 #ifndef MONGOCRYPT_INDEXED_ENCRYPTED_VALUE_PRIVATE_V2_H
 #define MONGOCRYPT_INDEXED_ENCRYPTED_VALUE_PRIVATE_V2_H
 
+#include "mc-fle2-tag-and-encrypted-metadata-block-private.h"
 #include "mc-tokens-private.h"
 #include "mongocrypt-buffer-private.h"
 #include "mongocrypt-crypto-private.h"
 #include "mongocrypt-status-private.h"
 
 /*
- * FLE2IndexedEqualityEncryptedValueV2 and FLE2IndexedRangeEncryptedValueV2
- * share a common internal implementation.  Accessors such as add/get_[SK]_Key
- * may be called for either type and produce appropriate results,
- * however the _parse() method is unique per type.
+ * FLE2IndexedEqualityEncryptedValueV2, FLE2IndexedRangeEncryptedValueV2, and FLEIndexedTextEncryptedValue
+ * share a common internal implementation.
  *
  * Lifecycle:
  * 1. mc_FLE2IndexedEncryptedValueV2_init
- * 2. mc_FLE2Indexed(Equality|Range)EncryptedValueV2_parse
+ * 2. mc_FLE2IndexedEncryptedValueV2_parse
  * 3. mc_FLE2IndexedEncryptedValueV2_get_S_KeyId
  * 4. mc_FLE2IndexedEncryptedValueV2_add_S_Key
  * 5. mc_FLE2IndexedEncryptedValueV2_get_K_KeyId
  * 6. mc_FLE2IndexedEncryptedValueV2_add_K_Key
  * 7. mc_FLE2IndexedEncryptedValueV2_get_ClientValue
- * 8. mc_FLE2IndexedEncryptedValueV2_destroy
- */
-
-typedef struct _mc_FLE2IndexedEncryptedValueV2_t mc_FLE2IndexedEncryptedValueV2_t;
-
-mc_FLE2IndexedEncryptedValueV2_t *mc_FLE2IndexedEncryptedValueV2_new(void);
-
-bool mc_FLE2IndexedEncryptedValueV2_parse(mc_FLE2IndexedEncryptedValueV2_t *iev,
-                                          const _mongocrypt_buffer_t *buf,
-                                          mongocrypt_status_t *status);
-
-bson_type_t mc_FLE2IndexedEncryptedValueV2_get_bson_value_type(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);
-
-bool mc_FLE2IndexedEncryptedValueV2_add_S_Key(_mongocrypt_crypto_t *crypto,
-                                              mc_FLE2IndexedEncryptedValueV2_t *iev,
-                                              const _mongocrypt_buffer_t *S_Key,
-                                              mongocrypt_status_t *status);
-
-const _mongocrypt_buffer_t *
-mc_FLE2IndexedEncryptedValueV2_get_ClientEncryptedValue(const mc_FLE2IndexedEncryptedValueV2_t *iev,
-                                                        mongocrypt_status_t *status);
-
-const _mongocrypt_buffer_t *mc_FLE2IndexedEncryptedValueV2_get_K_KeyId(const mc_FLE2IndexedEncryptedValueV2_t *iev,
-                                                                       mongocrypt_status_t *status);
-
-bool mc_FLE2IndexedEncryptedValueV2_add_K_Key(_mongocrypt_crypto_t *crypto,
-                                              mc_FLE2IndexedEncryptedValueV2_t *iev,
-                                              const _mongocrypt_buffer_t *K_Key,
-                                              mongocrypt_status_t *status);
-
-const _mongocrypt_buffer_t *mc_FLE2IndexedEncryptedValueV2_get_ClientValue(const mc_FLE2IndexedEncryptedValueV2_t *iev,
-                                                                           mongocrypt_status_t *status);
-
-void mc_FLE2IndexedEncryptedValueV2_destroy(mc_FLE2IndexedEncryptedValueV2_t *iev);
-
-/*
+ * 8. mc_FLE2IndexedEncryptedValueV2_serialize
+ * 9. mc_FLE2IndexedEncryptedValueV2_destroy
+ *
+ *
  * FLE2IndexedEqualityEncryptedValueV2 has the following data layout:
  *
  * struct FLE2IndexedEqualityEncryptedValueV2 {
@@ -90,8 +53,6 @@ void mc_FLE2IndexedEncryptedValueV2_destroy(mc_FLE2IndexedEncryptedValueV2_t *ie
  *   EncryptCTR(ServerEncryptionToken, K_KeyId || ClientEncryptedValue)
  * ClientEncryptedValue := EncryptCBCAEAD(K_Key, clientValue, AD=K_KeyId)
  *
- * The MetadataBlock is ignored by libmongocrypt,
- *   but has the following structure and a fixed size of 96 octets:
  *
  * struct FLE2TagAndEncryptedMetadataBlock {
  *   uint8_t encryptedCount[32]; // EncryptCTR(countEncryptionToken,
@@ -99,13 +60,8 @@ void mc_FLE2IndexedEncryptedValueV2_destroy(mc_FLE2IndexedEncryptedValueV2_t *ie
  *   uint8_t tag[32];            // HMAC-SHA256(count, edcTwiceDerived)
  *   uint8_t encryptedZeros[32]; // EncryptCTR(zerosEncryptionToken, 0*)
  * }
- */
-
-bool mc_FLE2IndexedEqualityEncryptedValueV2_parse(mc_FLE2IndexedEncryptedValueV2_t *iev,
-                                                  const _mongocrypt_buffer_t *buf,
-                                                  mongocrypt_status_t *status);
-
-/*
+ *
+ *
  * FLE2IndexedRangeEncryptedValueV2 has the following data layout:
  *
  * struct FLE2IndexedRangeEncryptedValueV2 {
@@ -119,15 +75,182 @@ bool mc_FLE2IndexedEqualityEncryptedValueV2_parse(mc_FLE2IndexedEncryptedValueV2
  *
  * 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.
  *
- * Since libmongocrypt ignores metadata blocks, we can ignore most all
- * differences between Equality and Range types for IndexedEncrypted data.
+ * 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.
  */
 
-bool mc_FLE2IndexedRangeEncryptedValueV2_parse(mc_FLE2IndexedEncryptedValueV2_t *iev,
-                                               const _mongocrypt_buffer_t *buf,
-                                               mongocrypt_status_t *status);
+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,
+                                                               mongocrypt_status_t *status);
+
+/*
+ * Populates an mc_FLE2IndexedEncryptedValueV2_t from a buffer.
+ *
+ * Input buffer must take the form of:
+ * fle_blob_subtype (8u)
+ * S_KeyId (8u * 16u)
+ * 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 || text ? edge_count : 1u})
+ *
+ * Returns an error if the input buffer is not valid.
+ */
+bool mc_FLE2IndexedEncryptedValueV2_parse(mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                          const _mongocrypt_buffer_t *buf,
+                                          mongocrypt_status_t *status);
+
+/*
+ * Serializes an mc_FLE2IndexedEncryptedValueV2_t into a buffer.
+ *
+ * The serialized output follows the same layout as the input `buf` to
+ * mc_FLE2IndexedEncryptedValueV2_parse, allowing for round-trip
+ * conversions between the serialized and parsed forms.
+ *
+ * Returns an error if the input structure is not valid, or if the buffer
+ * provided is insufficient to hold the serialized data.
+ */
+bool mc_FLE2IndexedEncryptedValueV2_serialize(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                              _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);
+
+bool mc_FLE2IndexedEncryptedValueV2_add_S_Key(_mongocrypt_crypto_t *crypto,
+                                              mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                              const _mongocrypt_buffer_t *S_Key,
+                                              mongocrypt_status_t *status);
+
+const _mongocrypt_buffer_t *
+mc_FLE2IndexedEncryptedValueV2_get_ClientEncryptedValue(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                                        mongocrypt_status_t *status);
+
+const _mongocrypt_buffer_t *mc_FLE2IndexedEncryptedValueV2_get_K_KeyId(const mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                                                       mongocrypt_status_t *status);
+
+bool mc_FLE2IndexedEncryptedValueV2_add_K_Key(_mongocrypt_crypto_t *crypto,
+                                              mc_FLE2IndexedEncryptedValueV2_t *iev,
+                                              const _mongocrypt_buffer_t *K_Key,
+                                              mongocrypt_status_t *status);
+
+const _mongocrypt_buffer_t *mc_FLE2IndexedEncryptedValueV2_get_ClientValue(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 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 */