libmongocrypt-helper 1.8.0.0.1001 → 1.11.0.0.1001

data/ext/libmongocrypt/libmongocrypt/src/mc-rangeopts.c

@@ -17,16 +17,21 @@
 #include "mc-rangeopts-private.h"
 
 #include "mc-check-conversions-private.h"
+#include "mc-range-edge-generation-private.h" // mc_count_leading_zeros_XX
+#include "mc-range-encoding-private.h"        // mc_getTypeInfoXX
 #include "mongocrypt-private.h"
 #include "mongocrypt-util-private.h" // mc_bson_type_to_string
 
 #include <float.h> // DBL_MAX
 
+#define CLIENT_ERR_PREFIXED_HELPER(Prefix, ErrorString, ...) CLIENT_ERR(Prefix ": " ErrorString, ##__VA_ARGS__)
+#define CLIENT_ERR_PREFIXED(ErrorString, ...) CLIENT_ERR_PREFIXED_HELPER(ERROR_PREFIX, ErrorString, ##__VA_ARGS__)
+
 // Common logic for testing field name, tracking duplication, and presence.
-#define IF_FIELD(Name, ErrorPrefix)                                                                                    \
+#define IF_FIELD(Name)                                                                                                 \
     if (0 == strcmp(field, #Name)) {                                                                                   \
         if (has_##Name) {                                                                                              \
-            CLIENT_ERR("%sUnexpected duplicate field '" #Name "'", ErrorPrefix);                                       \
+            CLIENT_ERR_PREFIXED("Unexpected duplicate field '" #Name "'");                                             \
             return false;                                                                                              \
         }                                                                                                              \
         has_##Name = true;
@@ -35,17 +40,17 @@
     continue;                                                                                                          \
     }
 
-#define CHECK_HAS(Name, ErrorPrefix)                                                                                   \
+#define CHECK_HAS(Name)                                                                                                \
     if (!has_##Name) {                                                                                                 \
-        CLIENT_ERR("%sMissing field '" #Name "'", ErrorPrefix);                                                        \
+        CLIENT_ERR_PREFIXED("Missing field '" #Name "'");                                                              \
         return false;                                                                                                  \
     }
 
-bool mc_RangeOpts_parse(mc_RangeOpts_t *ro, const bson_t *in, mongocrypt_status_t *status) {
-    bson_iter_t iter;
-    bool has_min = false, has_max = false, has_sparsity = false, has_precision = false;
-    const char *const error_prefix = "Error parsing RangeOpts: ";
+#define ERROR_PREFIX "Error parsing RangeOpts"
 
+bool mc_RangeOpts_parse(mc_RangeOpts_t *ro, const bson_t *in, bool use_range_v2, mongocrypt_status_t *status) {
+    bson_iter_t iter = {0};
+    bool has_min = false, has_max = false, has_sparsity = false, has_precision = false, has_trimFactor = false;
     BSON_ASSERT_PARAM(ro);
     BSON_ASSERT_PARAM(in);
     BSON_ASSERT(status || true);
@@ -54,7 +59,7 @@ bool mc_RangeOpts_parse(mc_RangeOpts_t *ro, const bson_t *in, mongocrypt_status_
     ro->bson = bson_copy(in);
 
     if (!bson_iter_init(&iter, ro->bson)) {
-        CLIENT_ERR("%sInvalid BSON", error_prefix);
+        CLIENT_ERR_PREFIXED("Invalid BSON");
         return false;
     }
 
@@ -62,74 +67,91 @@ bool mc_RangeOpts_parse(mc_RangeOpts_t *ro, const bson_t *in, mongocrypt_status_
         const char *field = bson_iter_key(&iter);
         BSON_ASSERT(field);
 
-        IF_FIELD(min, error_prefix)
+        IF_FIELD(min)
         ro->min.set = true;
         ro->min.value = iter;
         END_IF_FIELD
 
-        IF_FIELD(max, error_prefix)
+        IF_FIELD(max)
         ro->max.set = true;
         ro->max.value = iter;
         END_IF_FIELD
 
-        IF_FIELD(sparsity, error_prefix)
+        IF_FIELD(sparsity)
         if (!BSON_ITER_HOLDS_INT64(&iter)) {
-            CLIENT_ERR("%sExpected int64 for sparsity, got: %s",
-                       error_prefix,
-                       mc_bson_type_to_string(bson_iter_type(&iter)));
+            CLIENT_ERR_PREFIXED("Expected int64 for sparsity, got: %s", mc_bson_type_to_string(bson_iter_type(&iter)));
             return false;
         };
         ro->sparsity = bson_iter_int64(&iter);
         END_IF_FIELD
 
-        IF_FIELD(precision, error_prefix) {
+        IF_FIELD(precision) {
             if (!BSON_ITER_HOLDS_INT32(&iter)) {
-                CLIENT_ERR("%s'precision' must be an int32", error_prefix);
+                CLIENT_ERR_PREFIXED("'precision' must be an int32");
+                return false;
+            }
+            int32_t val = bson_iter_int32(&iter);
+            if (val < 0) {
+                CLIENT_ERR_PREFIXED("'precision' must be non-negative");
                 return false;
             }
+            ro->precision = OPT_I32(val);
+        }
+        END_IF_FIELD
+
+        IF_FIELD(trimFactor) {
+            if (!BSON_ITER_HOLDS_INT32(&iter)) {
+                CLIENT_ERR_PREFIXED("Expected int32 for trimFactor, got: %s",
+                                    mc_bson_type_to_string(bson_iter_type(&iter)));
+                return false;
+            };
             int32_t val = bson_iter_int32(&iter);
             if (val < 0) {
-                CLIENT_ERR("%s'precision' must be non-negative", error_prefix);
+                CLIENT_ERR_PREFIXED("'trimFactor' must be non-negative");
                 return false;
             }
-            ro->precision = OPT_U32((uint32_t)val);
+            ro->trimFactor = OPT_I32(val);
         }
         END_IF_FIELD
 
-        CLIENT_ERR("%sUnrecognized field: '%s'", error_prefix, field);
+        CLIENT_ERR_PREFIXED("Unrecognized field: '%s'", field);
         return false;
     }
 
     // Do not error if min/max are not present. min/max are optional.
-    CHECK_HAS(sparsity, error_prefix);
     // Do not error if precision is not present. Precision is optional and only
     // applies to double/decimal128.
+    // Do not error if trimFactor is not present. It is optional.
+
+    if (!has_sparsity && use_range_v2) {
+        ro->sparsity = mc_FLERangeSparsityDefault;
+    }
 
     // Expect precision only to be set for double or decimal128.
     if (has_precision) {
         if (!ro->min.set) {
-            CLIENT_ERR("setting precision requires min");
+            CLIENT_ERR_PREFIXED("setting precision requires min");
             return false;
         }
 
         bson_type_t minType = bson_iter_type(&ro->min.value);
         if (minType != BSON_TYPE_DOUBLE && minType != BSON_TYPE_DECIMAL128) {
-            CLIENT_ERR("expected 'precision' to be set with double or decimal128 "
-                       "index, but got: %s min",
-                       mc_bson_type_to_string(minType));
+            CLIENT_ERR_PREFIXED("expected 'precision' to be set with double or decimal128 "
+                                "index, but got: %s min",
+                                mc_bson_type_to_string(minType));
             return false;
         }
 
         if (!ro->max.set) {
-            CLIENT_ERR("setting precision requires max");
+            CLIENT_ERR_PREFIXED("setting precision requires max");
             return false;
         }
 
         bson_type_t maxType = bson_iter_type(&ro->max.value);
         if (maxType != BSON_TYPE_DOUBLE && maxType != BSON_TYPE_DECIMAL128) {
-            CLIENT_ERR("expected 'precision' to be set with double or decimal128 "
-                       "index, but got: %s max",
-                       mc_bson_type_to_string(maxType));
+            CLIENT_ERR_PREFIXED("expected 'precision' to be set with double or decimal128 "
+                                "index, but got: %s max",
+                                mc_bson_type_to_string(maxType));
             return false;
         }
     }
@@ -138,10 +160,10 @@ bool mc_RangeOpts_parse(mc_RangeOpts_t *ro, const bson_t *in, mongocrypt_status_
     if (ro->min.set && ro->max.set) {
         bson_type_t minType = bson_iter_type(&ro->min.value), maxType = bson_iter_type(&ro->max.value);
         if (minType != maxType) {
-            CLIENT_ERR("expected 'min' and 'max' to be same type, but got: %s "
-                       "min and %s max",
-                       mc_bson_type_to_string(minType),
-                       mc_bson_type_to_string(maxType));
+            CLIENT_ERR_PREFIXED("expected 'min' and 'max' to be same type, but got: %s "
+                                "min and %s max",
+                                mc_bson_type_to_string(minType),
+                                mc_bson_type_to_string(maxType));
             return false;
         }
     }
@@ -152,7 +174,8 @@ bool mc_RangeOpts_parse(mc_RangeOpts_t *ro, const bson_t *in, mongocrypt_status_
             bson_type_t minType = bson_iter_type(&ro->min.value);
             if (minType == BSON_TYPE_DOUBLE || minType == BSON_TYPE_DECIMAL128) {
                 if (!has_precision) {
-                    CLIENT_ERR("expected 'precision' to be set with 'min' for %s", mc_bson_type_to_string(minType));
+                    CLIENT_ERR_PREFIXED("expected 'precision' to be set with 'min' for %s",
+                                        mc_bson_type_to_string(minType));
                     return false;
                 }
             }
@@ -162,39 +185,53 @@ bool mc_RangeOpts_parse(mc_RangeOpts_t *ro, const bson_t *in, mongocrypt_status_
             bson_type_t maxType = bson_iter_type(&ro->max.value);
             if (maxType == BSON_TYPE_DOUBLE || maxType == BSON_TYPE_DECIMAL128) {
                 if (!has_precision) {
-                    CLIENT_ERR("expected 'precision' to be set with 'max' for %s", mc_bson_type_to_string(maxType));
+                    CLIENT_ERR_PREFIXED("expected 'precision' to be set with 'max' for %s",
+                                        mc_bson_type_to_string(maxType));
                     return false;
                 }
             }
         }
     }
 
+    if (ro->trimFactor.set) {
+        if (!use_range_v2) {
+            // Once `use_range_v2` is default true, this block may be removed.
+            CLIENT_ERR_PREFIXED("'trimFactor' is not supported for QE range v1");
+            return false;
+        }
+        // At this point, we do not know the type of the field if min and max are unspecified. Wait to
+        // validate the value of trimFactor.
+    }
+
     return true;
 }
 
+#undef ERROR_PREFIX
+#define ERROR_PREFIX "Error making FLE2RangeInsertSpec"
+
 bool mc_RangeOpts_to_FLE2RangeInsertSpec(const mc_RangeOpts_t *ro,
                                          const bson_t *v,
                                          bson_t *out,
+                                         bool use_range_v2,
                                          mongocrypt_status_t *status) {
     BSON_ASSERT_PARAM(ro);
     BSON_ASSERT_PARAM(v);
     BSON_ASSERT_PARAM(out);
     BSON_ASSERT(status || true);
 
-    const char *const error_prefix = "Error making FLE2RangeInsertSpec: ";
     bson_iter_t v_iter;
     if (!bson_iter_init_find(&v_iter, v, "v")) {
-        CLIENT_ERR("Unable to find 'v' in input");
+        CLIENT_ERR_PREFIXED("Unable to find 'v' in input");
         return false;
     }
 
     bson_t child;
     if (!BSON_APPEND_DOCUMENT_BEGIN(out, "v", &child)) {
-        CLIENT_ERR("%sError appending to BSON", error_prefix);
+        CLIENT_ERR_PREFIXED("Error appending to BSON");
         return false;
     }
     if (!bson_append_iter(&child, "v", 1, &v_iter)) {
-        CLIENT_ERR("%sError appending to BSON", error_prefix);
+        CLIENT_ERR_PREFIXED("Error appending to BSON");
         return false;
     }
 
@@ -209,17 +246,26 @@ bool mc_RangeOpts_to_FLE2RangeInsertSpec(const mc_RangeOpts_t *ro,
     if (ro->precision.set) {
         BSON_ASSERT(ro->precision.value <= INT32_MAX);
         if (!BSON_APPEND_INT32(&child, "precision", (int32_t)ro->precision.value)) {
-            CLIENT_ERR("%sError appending to BSON", error_prefix);
+            CLIENT_ERR_PREFIXED("Error appending to BSON");
+            return false;
+        }
+    }
+
+    if (use_range_v2) {
+        if (!mc_RangeOpts_appendTrimFactor(ro, bson_iter_type(&v_iter), "trimFactor", &child, status, use_range_v2)) {
             return false;
         }
     }
     if (!bson_append_document_end(out, &child)) {
-        CLIENT_ERR("%sError appending to BSON", error_prefix);
+        CLIENT_ERR_PREFIXED("Error appending to BSON");
         return false;
     }
     return true;
 }
 
+#undef ERROR_PREFIX
+#define ERROR_PREFIX "Error appending min to FLE2RangeInsertSpec"
+
 bool mc_RangeOpts_appendMin(const mc_RangeOpts_t *ro,
                             bson_type_t valueType,
                             const char *fieldName,
@@ -232,46 +278,49 @@ bool mc_RangeOpts_appendMin(const mc_RangeOpts_t *ro,
 
     if (ro->min.set) {
         if (bson_iter_type(&ro->min.value) != valueType) {
-            CLIENT_ERR("expected matching 'min' and value type. Got range option "
-                       "'min' of type %s and value of type %s",
-                       mc_bson_type_to_string(bson_iter_type(&ro->min.value)),
-                       mc_bson_type_to_string(valueType));
+            CLIENT_ERR_PREFIXED("expected matching 'min' and value type. Got range option "
+                                "'min' of type %s and value of type %s",
+                                mc_bson_type_to_string(bson_iter_type(&ro->min.value)),
+                                mc_bson_type_to_string(valueType));
             return false;
         }
         if (!bson_append_iter(out, fieldName, -1, &ro->min.value)) {
-            CLIENT_ERR("failed to append BSON");
+            CLIENT_ERR_PREFIXED("failed to append BSON");
             return false;
         }
         return true;
     }
 
     if (valueType == BSON_TYPE_INT32 || valueType == BSON_TYPE_INT64 || valueType == BSON_TYPE_DATE_TIME) {
-        CLIENT_ERR("Range option 'min' is required for type: %s", mc_bson_type_to_string(valueType));
+        CLIENT_ERR_PREFIXED("Range option 'min' is required for type: %s", mc_bson_type_to_string(valueType));
         return false;
     } else if (valueType == BSON_TYPE_DOUBLE) {
         if (!BSON_APPEND_DOUBLE(out, fieldName, -DBL_MAX)) {
-            CLIENT_ERR("failed to append BSON");
+            CLIENT_ERR_PREFIXED("failed to append BSON");
             return false;
         }
     } else if (valueType == BSON_TYPE_DECIMAL128) {
 #if MONGOCRYPT_HAVE_DECIMAL128_SUPPORT
         const bson_decimal128_t min = mc_dec128_to_bson_decimal128(MC_DEC128_LARGEST_NEGATIVE);
         if (!BSON_APPEND_DECIMAL128(out, fieldName, &min)) {
-            CLIENT_ERR("failed to append BSON");
+            CLIENT_ERR_PREFIXED("failed to append BSON");
             return false;
         }
 #else  // ↑↑↑↑↑↑↑↑ With Decimal128 / Without ↓↓↓↓↓↓↓↓↓↓
-        CLIENT_ERR("unsupported BSON type (Decimal128) for range: libmongocrypt "
-                   "was built without extended Decimal128 support");
+        CLIENT_ERR_PREFIXED("unsupported BSON type (Decimal128) for range: libmongocrypt "
+                            "was built without extended Decimal128 support");
         return false;
 #endif // MONGOCRYPT_HAVE_DECIMAL128_SUPPORT
     } else {
-        CLIENT_ERR("unsupported BSON type: %s for range", mc_bson_type_to_string(valueType));
+        CLIENT_ERR_PREFIXED("unsupported BSON type: %s for range", mc_bson_type_to_string(valueType));
         return false;
     }
     return true;
 }
 
+#undef ERROR_PREFIX
+#define ERROR_PREFIX "Error appending max to FLE2RangeInsertSpec"
+
 bool mc_RangeOpts_appendMax(const mc_RangeOpts_t *ro,
                             bson_type_t valueType,
                             const char *fieldName,
@@ -284,46 +333,193 @@ bool mc_RangeOpts_appendMax(const mc_RangeOpts_t *ro,
 
     if (ro->max.set) {
         if (bson_iter_type(&ro->max.value) != valueType) {
-            CLIENT_ERR("expected matching 'max' and value type. Got range option "
-                       "'max' of type %s and value of type %s",
-                       mc_bson_type_to_string(bson_iter_type(&ro->max.value)),
-                       mc_bson_type_to_string(valueType));
+            CLIENT_ERR_PREFIXED("expected matching 'max' and value type. Got range option "
+                                "'max' of type %s and value of type %s",
+                                mc_bson_type_to_string(bson_iter_type(&ro->max.value)),
+                                mc_bson_type_to_string(valueType));
             return false;
         }
         if (!bson_append_iter(out, fieldName, -1, &ro->max.value)) {
-            CLIENT_ERR("failed to append BSON");
+            CLIENT_ERR_PREFIXED("failed to append BSON");
             return false;
         }
         return true;
     }
 
     if (valueType == BSON_TYPE_INT32 || valueType == BSON_TYPE_INT64 || valueType == BSON_TYPE_DATE_TIME) {
-        CLIENT_ERR("Range option 'max' is required for type: %s", mc_bson_type_to_string(valueType));
+        CLIENT_ERR_PREFIXED("Range option 'max' is required for type: %s", mc_bson_type_to_string(valueType));
         return false;
     } else if (valueType == BSON_TYPE_DOUBLE) {
         if (!BSON_APPEND_DOUBLE(out, fieldName, DBL_MAX)) {
-            CLIENT_ERR("failed to append BSON");
+            CLIENT_ERR_PREFIXED("failed to append BSON");
             return false;
         }
     } else if (valueType == BSON_TYPE_DECIMAL128) {
 #if MONGOCRYPT_HAVE_DECIMAL128_SUPPORT
         const bson_decimal128_t max = mc_dec128_to_bson_decimal128(MC_DEC128_LARGEST_POSITIVE);
         if (!BSON_APPEND_DECIMAL128(out, fieldName, &max)) {
-            CLIENT_ERR("failed to append BSON");
+            CLIENT_ERR_PREFIXED("failed to append BSON");
             return false;
         }
 #else  // ↑↑↑↑↑↑↑↑ With Decimal128 / Without ↓↓↓↓↓↓↓↓↓↓
-        CLIENT_ERR("unsupported BSON type (Decimal128) for range: libmongocrypt "
-                   "was built without extended Decimal128 support");
+        CLIENT_ERR_PREFIXED("unsupported BSON type (Decimal128) for range: libmongocrypt "
+                            "was built without extended Decimal128 support");
         return false;
 #endif // MONGOCRYPT_HAVE_DECIMAL128_SUPPORT
     } else {
-        CLIENT_ERR("unsupported BSON type: %s for range", mc_bson_type_to_string(valueType));
+        CLIENT_ERR_PREFIXED("unsupported BSON type: %s for range", mc_bson_type_to_string(valueType));
         return false;
     }
     return true;
 }
 
+#undef ERROR_PREFIX
+#define ERROR_PREFIX "Error in getNumberOfBits"
+
+// Used to calculate max trim factor. Returns the number of bits required to represent any number in
+// the domain.
+bool mc_getNumberOfBits(const mc_RangeOpts_t *ro,
+                        bson_type_t valueType,
+                        uint32_t *bitsOut,
+                        mongocrypt_status_t *status,
+                        bool use_range_v2) {
+    BSON_ASSERT_PARAM(ro);
+    BSON_ASSERT_PARAM(bitsOut);
+
+    // For each type, we use getTypeInfo to get the total number of values in the domain (-1)
+    // which tells us how many bits are needed to represent the whole domain.
+    // note - can't use a switch statement because of -Werror=switch-enum
+    if (valueType == BSON_TYPE_INT32) {
+        int32_t value = 0;
+        mc_optional_int32_t rmin = {false, 0}, rmax = {false, 0};
+        if (ro->min.set) {
+            BSON_ASSERT(ro->max.set);
+            value = bson_iter_int32(&ro->min.value);
+            rmin = OPT_I32(value);
+            rmax = OPT_I32(bson_iter_int32(&ro->max.value));
+        }
+        mc_getTypeInfo32_args_t args = {value, rmin, rmax};
+        mc_OSTType_Int32 out;
+        if (!mc_getTypeInfo32(args, &out, status)) {
+            return false;
+        }
+        *bitsOut = 32 - (uint32_t)mc_count_leading_zeros_u32(out.max);
+        return true;
+    } else if (valueType == BSON_TYPE_INT64) {
+        int64_t value = 0;
+        mc_optional_int64_t rmin = {false, 0}, rmax = {false, 0};
+        if (ro->min.set) {
+            BSON_ASSERT(ro->max.set);
+            value = bson_iter_int64(&ro->min.value);
+            rmin = OPT_I64(value);
+            rmax = OPT_I64(bson_iter_int64(&ro->max.value));
+        }
+        mc_getTypeInfo64_args_t args = {value, rmin, rmax};
+        mc_OSTType_Int64 out;
+        if (!mc_getTypeInfo64(args, &out, status)) {
+            return false;
+        }
+        *bitsOut = 64 - (uint32_t)mc_count_leading_zeros_u64(out.max);
+        return true;
+    } else if (valueType == BSON_TYPE_DATE_TIME) {
+        int64_t value = 0;
+        mc_optional_int64_t rmin = {false, 0}, rmax = {false, 0};
+        if (ro->min.set) {
+            BSON_ASSERT(ro->max.set);
+            value = bson_iter_date_time(&ro->min.value);
+            rmin = OPT_I64(value);
+            rmax = OPT_I64(bson_iter_date_time(&ro->max.value));
+        }
+        mc_getTypeInfo64_args_t args = {value, rmin, rmax};
+        mc_OSTType_Int64 out;
+        if (!mc_getTypeInfo64(args, &out, status)) {
+            return false;
+        }
+        *bitsOut = 64 - (uint32_t)mc_count_leading_zeros_u64(out.max);
+        return true;
+    } else if (valueType == BSON_TYPE_DOUBLE) {
+        double value = 0;
+        mc_optional_double_t rmin = {false, 0}, rmax = {false, 0};
+        mc_optional_int32_t prec = ro->precision;
+        if (ro->min.set) {
+            BSON_ASSERT(ro->max.set);
+            value = bson_iter_double(&ro->min.value);
+            rmin = OPT_DOUBLE(value);
+            rmax = OPT_DOUBLE(bson_iter_double(&ro->max.value));
+        }
+        mc_getTypeInfoDouble_args_t args = {value, rmin, rmax, prec};
+        mc_OSTType_Double out;
+        if (!mc_getTypeInfoDouble(args, &out, status, use_range_v2)) {
+            return false;
+        }
+        *bitsOut = 64 - (uint32_t)mc_count_leading_zeros_u64(out.max);
+        return true;
+    }
+#if MONGOCRYPT_HAVE_DECIMAL128_SUPPORT
+    else if (valueType == BSON_TYPE_DECIMAL128) {
+        mc_dec128 value = MC_DEC128_ZERO;
+        mc_optional_dec128_t rmin = {false, MC_DEC128_ZERO}, rmax = {false, MC_DEC128_ZERO};
+        mc_optional_int32_t prec = ro->precision;
+        if (ro->min.set) {
+            BSON_ASSERT(ro->max.set);
+            value = mc_dec128_from_bson_iter(&ro->min.value);
+            rmin = OPT_MC_DEC128(value);
+            rmax = OPT_MC_DEC128(mc_dec128_from_bson_iter(&ro->max.value));
+        }
+        mc_getTypeInfoDecimal128_args_t args = {value, rmin, rmax, prec};
+        mc_OSTType_Decimal128 out;
+        if (!mc_getTypeInfoDecimal128(args, &out, status, use_range_v2)) {
+            return false;
+        }
+        *bitsOut = 128 - (uint32_t)mc_count_leading_zeros_u128(out.max);
+        return true;
+    }
+#endif
+    CLIENT_ERR_PREFIXED("unsupported BSON type: %s for range", mc_bson_type_to_string(valueType));
+    return false;
+}
+
+#undef ERROR_PREFIX
+#define ERROR_PREFIX "Error appending trim factor to FLE2RangeInsertSpec"
+
+bool mc_RangeOpts_appendTrimFactor(const mc_RangeOpts_t *ro,
+                                   bson_type_t valueType,
+                                   const char *fieldName,
+                                   bson_t *out,
+                                   mongocrypt_status_t *status,
+                                   bool use_range_v2) {
+    BSON_ASSERT_PARAM(ro);
+    BSON_ASSERT_PARAM(fieldName);
+    BSON_ASSERT_PARAM(out);
+    BSON_ASSERT(status || true);
+
+    if (!ro->trimFactor.set) {
+        // A default `trimFactor` will be selected later with `trimFactorDefault`
+        return true;
+    }
+
+    uint32_t nbits;
+    if (!mc_getNumberOfBits(ro, valueType, &nbits, status, use_range_v2)) {
+        return false;
+    }
+    // if nbits = 0, we want to allow trim factor = 0.
+    uint32_t test = nbits ? nbits : 1;
+    if (bson_cmp_greater_equal_su(ro->trimFactor.value, test)) {
+        CLIENT_ERR_PREFIXED("Trim factor (%d) must be less than the total number of bits (%d) used to represent "
+                            "any element in the domain.",
+                            ro->trimFactor.value,
+                            nbits);
+        return false;
+    }
+    if (!BSON_APPEND_INT32(out, fieldName, ro->trimFactor.value)) {
+        CLIENT_ERR_PREFIXED("failed to append BSON");
+        return false;
+    }
+    return true;
+}
+
+#undef ERROR_PREFIX
+
 void mc_RangeOpts_cleanup(mc_RangeOpts_t *ro) {
     if (!ro) {
         return;

data/ext/libmongocrypt/libmongocrypt/src/mc-tokens-private.h

@@ -24,7 +24,7 @@
  *
  * v is a BSON value. It is the bytes after "e_name" in "element" in
  * https://bsonspec.org/spec.html.
- * u is a "contention factor" counter. It is a uint64_t.
+ * u is a "contention factor". It is a uint64_t.
  * HMAC is the HMAC-SHA-256 function.
  * Integers are represented as uint64_t in little-endian.
  *
@@ -40,11 +40,21 @@
  * ESCDerivedFromDataToken = HMAC(ESCToken, v)
  * ECCDerivedFromDataToken = HMAC(ECCToken, v)
  *
- * EDCDerivedFromDataTokenAndCounter = HMAC(EDCDerivedFromDataToken, u)
- * ESCDerivedFromDataTokenAndCounter = HMAC(ESCDerivedFromDataToken, u)
- * ECCDerivedFromDataTokenAndCounter = HMAC(ECCDerivedFromDataToken, u)
+ * EDCDerivedFromDataTokenAndContentionFactor = HMAC(EDCDerivedFromDataToken, u)
+ * ESCDerivedFromDataTokenAndContentionFactor = HMAC(ESCDerivedFromDataToken, u)
+ * ECCDerivedFromDataTokenAndContentionFactor = HMAC(ECCDerivedFromDataToken, u)
+ *
+ * EDCTwiceDerivedToken      = HMAC(EDCDerivedFromDataTokenAndContentionFactor, 1)
+
+ * ESCTwiceDerivedTagToken   = HMAC(ESCDerivedFromDataTokenAndContentionFactor, 1)
+ * ESCTwiceDerivedValueToken = HMAC(ESCDerivedFromDataTokenAndContentionFactor, 2)
+
+ * ECCTwiceDerivedTagToken   = HMAC(ECCDerivedFromDataTokenAndContentionFactor, 1)
+ * ECCTwiceDerivedValueToken = HMAC(ECCDerivedFromDataTokenAndContentionFactor, 2)
  *
  * Note: ECC related tokens are used in FLE2v1 only.
+ *       Further, ECCTwiceDerivedValue(Tag|Token) have been omitted entirely.
+ *       The above comment describing derivation is for doc purposes only.
  * ----------------------------------------------------------------------------
  * Added in FLE2v2:
  *
@@ -54,38 +64,35 @@
  * ServerCountAndContentionFactorEncryptionToken =
  *    HMAC(ServerDerivedFromDataToken, 1)
  * ServerZerosEncryptionToken = HMAC(ServerDerivedFromDataToken, 2)
+ * ----------------------------------------------------------------------------
+ * Added in Range V2:
+ *
+ * d is a 17-byte blob of zeros.
+ *
+ * AnchorPaddingTokenRoot   = HMAC(ESCToken, d)
+ * Server-side:
+ *      AnchorPaddingTokenKey    = HMAC(AnchorPaddingTokenRoot, 1)
+ *      AnchorPaddingTokenValue  = HMAC(AnchorPaddingTokenRoot, 2)
  * ======================== End: FLE 2 Token Reference ========================
  */
 
-// TODO: replace `CONCAT` with `BSON_CONCAT` after libbson dependency is
-// upgraded to 1.20.0 or higher.
-#ifndef CONCAT
-#define CONCAT_1(a, b) a##b
-#define CONCAT(a, b) CONCAT_1(a, b)
-#endif
-// TODO: replace `CONCAT3` with `BSON_CONCAT3` after libbson dependency is
-// upgraded to 1.20.0 or higher.
-#ifndef CONCAT3
-#define CONCAT3(a, b, c) CONCAT(a, CONCAT(b, c))
-#endif
-
 /// Declare a token type named 'Name', with constructor parameters given by the
 /// remaining arguments. Each constructor will also have the implicit first
 /// argument '_mongocrypt_crypto_t* crypto' and a final argument
 /// 'mongocrypt_status_t* status'
-#define DECL_TOKEN_TYPE(Name, ...) DECL_TOKEN_TYPE_1(Name, CONCAT(Name, _t), __VA_ARGS__)
+#define DECL_TOKEN_TYPE(Name, ...) DECL_TOKEN_TYPE_1(Name, BSON_CONCAT(Name, _t), __VA_ARGS__)
 
 #define DECL_TOKEN_TYPE_1(Prefix, T, ...)                                                                              \
     /* Opaque typedef the struct */                                                                                    \
     typedef struct T T;                                                                                                \
     /* Data-getter */                                                                                                  \
-    extern const _mongocrypt_buffer_t *CONCAT(Prefix, _get)(const T *t);                                               \
+    extern const _mongocrypt_buffer_t *BSON_CONCAT(Prefix, _get)(const T *t);                                          \
     /* Destructor */                                                                                                   \
-    extern void CONCAT(Prefix, _destroy)(T * t);                                                                       \
+    extern void BSON_CONCAT(Prefix, _destroy)(T * t);                                                                  \
     /* Constructor for server to create tokens from raw buffer */                                                      \
-    extern T *CONCAT(Prefix, _new_from_buffer)(_mongocrypt_buffer_t * buf);                                            \
+    extern T *BSON_CONCAT(Prefix, _new_from_buffer)(_mongocrypt_buffer_t * buf);                                       \
     /* Constructor. Parameter list given as variadic args */                                                           \
-    extern T *CONCAT(Prefix, _new)(_mongocrypt_crypto_t * crypto, __VA_ARGS__, mongocrypt_status_t * status)
+    extern T *BSON_CONCAT(Prefix, _new)(_mongocrypt_crypto_t * crypto, __VA_ARGS__, mongocrypt_status_t * status)
 
 DECL_TOKEN_TYPE(mc_CollectionsLevel1Token, const _mongocrypt_buffer_t *);
 DECL_TOKEN_TYPE(mc_ServerTokenDerivationLevel1Token, const _mongocrypt_buffer_t *);
@@ -100,16 +107,23 @@ DECL_TOKEN_TYPE(mc_EDCDerivedFromDataToken, const mc_EDCToken_t *EDCToken, const
 DECL_TOKEN_TYPE(mc_ECCDerivedFromDataToken, const mc_ECCToken_t *ECCToken, const _mongocrypt_buffer_t *v);
 DECL_TOKEN_TYPE(mc_ESCDerivedFromDataToken, const mc_ESCToken_t *ESCToken, const _mongocrypt_buffer_t *v);
 
-DECL_TOKEN_TYPE(mc_EDCDerivedFromDataTokenAndCounter,
+DECL_TOKEN_TYPE(mc_EDCDerivedFromDataTokenAndContentionFactor,
                 const mc_EDCDerivedFromDataToken_t *EDCDerivedFromDataToken,
                 uint64_t u);
-DECL_TOKEN_TYPE(mc_ESCDerivedFromDataTokenAndCounter,
+DECL_TOKEN_TYPE(mc_ESCDerivedFromDataTokenAndContentionFactor,
                 const mc_ESCDerivedFromDataToken_t *ESCDerivedFromDataToken,
                 uint64_t u);
-DECL_TOKEN_TYPE(mc_ECCDerivedFromDataTokenAndCounter,
+DECL_TOKEN_TYPE(mc_ECCDerivedFromDataTokenAndContentionFactor,
                 const mc_ECCDerivedFromDataToken_t *ECCDerivedFromDataToken,
                 uint64_t u);
 
+DECL_TOKEN_TYPE(mc_EDCTwiceDerivedToken,
+                const mc_EDCDerivedFromDataTokenAndContentionFactor_t *EDCDerivedFromDataTokenAndContentionFactor);
+DECL_TOKEN_TYPE(mc_ESCTwiceDerivedTagToken,
+                const mc_ESCDerivedFromDataTokenAndContentionFactor_t *ESCDerivedFromDataTokenAndContentionFactor);
+DECL_TOKEN_TYPE(mc_ESCTwiceDerivedValueToken,
+                const mc_ESCDerivedFromDataTokenAndContentionFactor_t *ESCDerivedFromDataTokenAndContentionFactor);
+
 DECL_TOKEN_TYPE(mc_ServerDerivedFromDataToken,
                 const mc_ServerTokenDerivationLevel1Token_t *ServerTokenDerivationToken,
                 const _mongocrypt_buffer_t *v);
@@ -118,6 +132,8 @@ DECL_TOKEN_TYPE(mc_ServerCountAndContentionFactorEncryptionToken,
                 const mc_ServerDerivedFromDataToken_t *serverDerivedFromDataToken);
 DECL_TOKEN_TYPE(mc_ServerZerosEncryptionToken, const mc_ServerDerivedFromDataToken_t *serverDerivedFromDataToken);
 
+DECL_TOKEN_TYPE(mc_AnchorPaddingTokenRoot, const mc_ESCToken_t *ESCToken);
+
 #undef DECL_TOKEN_TYPE
 #undef DECL_TOKEN_TYPE_1