CDRIVER-4394 Add explicit encryption support and tests for range indexes (#1152)

* require libmongocrypt 1.7.0-alpha1

Co-authored-by: Kevin Albertson <[email protected]>

Author: galon1

.evergreen/compile-test-azurekms.sh

@@ -8,7 +8,8 @@ ROOT=$(pwd)
 INSTALL_DIR=$ROOT/install
 . .evergreen/find-cmake.sh
 echo "Installing libmongocrypt ... begin"
-git clone https://github.com/mongodb/libmongocrypt --branch 1.6.0
+# TODO(CDRIVER-4394) update to use libmongocrypt 1.7.0 once there is a stable 1.7.0 release.
+git clone https://github.com/mongodb/libmongocrypt --branch 1.7.0-alpha1
 $CMAKE -DCMAKE_INSTALL_PREFIX="$INSTALL_DIR" \
     -DBUILD_TESTING=OFF \
     "-H$ROOT/libmongocrypt" \

.evergreen/compile-unix.sh

@@ -229,7 +229,8 @@ pkg-config --modversion libssl || true
 
 if [ "$COMPILE_LIBMONGOCRYPT" = "ON" ]; then
    # Build libmongocrypt, using the previously fetched installed source.
-   git clone https://github.com/mongodb/libmongocrypt --branch 1.6.0
+   # TODO(CDRIVER-4394) update to use libmongocrypt 1.7.0 once there is a stable 1.7.0 release.
+   git clone https://github.com/mongodb/libmongocrypt --branch 1.7.0-alpha1
 
    mkdir libmongocrypt/cmake-build
    cd libmongocrypt/cmake-build

.evergreen/compile-windows.sh

@@ -120,7 +120,8 @@ fi
 
 if [ "$COMPILE_LIBMONGOCRYPT" = "ON" ]; then
    # Build libmongocrypt, using the previously fetched installed source.
-   git clone https://github.com/mongodb/libmongocrypt --branch 1.6.0
+   # TODO(CDRIVER-4394) update to use libmongocrypt 1.7.0 once there is a stable 1.7.0 release.
+   git clone https://github.com/mongodb/libmongocrypt --branch 1.7.0-alpha1
    mkdir libmongocrypt/cmake-build
    cd libmongocrypt/cmake-build
    "$CMAKE" -G "$CC" "-DCMAKE_PREFIX_PATH=${INSTALL_DIR}/lib/cmake" -DENABLE_SHARED_BSON=ON -DCMAKE_INSTALL_PREFIX="$INSTALL_DIR" ../

src/libmongoc/CMakeLists.txt

@@ -441,6 +441,7 @@ elseif (NOT ENABLE_CLIENT_SIDE_ENCRYPTION STREQUAL OFF)
       find_package (mongocrypt QUIET)
    endif ()
 
+   # TODO(CDRIVER-4394) update to use libmongocrypt 1.7.0 once there is a stable 1.7.0 release.
    if (mongocrypt_FOUND AND "${mongocrypt_VERSION}" VERSION_LESS 1.6.0)
       message ("--   libmongocrypt found at ${mongocrypt_DIR}")
       message ("--   libmongocrypt version ${mongocrypt_VERSION} found")

src/libmongoc/doc/api.rst

@@ -17,6 +17,7 @@ API Reference
    mongoc_client_encryption_datakey_opts_t
    mongoc_client_encryption_rewrap_many_datakey_result_t
    mongoc_client_encryption_encrypt_opts_t
+   mongoc_client_encryption_encrypt_range_opts_t
    mongoc_client_encryption_opts_t
    mongoc_client_pool_t
    mongoc_client_session_t

src/libmongoc/doc/conf.py

@@ -71,6 +71,10 @@
 
     This API |qenc:is-experimental|
 
+.. |qenc:range-is-experimental| replace::
+
+    Range algorithm is experimental only and not intended for public use. It is subject to breaking changes.
+
 '''
 
 

src/libmongoc/doc/mongoc_client_encryption_encrypt.rst

@@ -20,15 +20,22 @@ Performs explicit encryption.
 
 ``ciphertext`` is always initialized (even on failure). Caller must call :symbol:`bson_value_destroy()` to free.
 
-To insert or query with an "Indexed" encrypted payload, use a
+To insert or query with an "Indexed" or "RangePreview" encrypted payload, use a
 :symbol:`mongoc_client_t` configured with
 :symbol:`mongoc_auto_encryption_opts_t`. The
 :symbol:`mongoc_auto_encryption_opts_t` may be configured to bypass query
 analysis with :symbol:`mongoc_auto_encryption_opts_set_bypass_query_analysis`.
 The :symbol:`mongoc_auto_encryption_opts_t` must not be configured to bypass
 automatic encryption with
 :symbol:`mongoc_auto_encryption_opts_set_bypass_auto_encryption`. **Note** that
-the ``"Indexed"`` payload type |qenc:is-experimental|
+the ``"Indexed"`` and ``"RangePreview"`` payload type |qenc:is-experimental|. The |qenc:range-is-experimental| 
+
+To insert with a ``RangePreview`` payload 
+:symbol:`mongoc_client_encryption_encrypt_range_opts_t` must be set in ``opts``.
+
+To query with a ``RangePreview`` payload, use :symbol:`mongoc_client_encryption_encrypt_expression()`
+
+**NOTE** that the |qenc:range-is-experimental|
 
 Parameters
 ----------
@@ -52,3 +59,4 @@ Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise.
 
   | :symbol:`mongoc_client_encryption_decrypt()`
 
+  | :symbol:`mongoc_client_encryption_encrypt_expression()`

src/libmongoc/doc/mongoc_client_encryption_encrypt_expression.rst

@@ -0,0 +1,72 @@
+:man_page: mongoc_client_encryption_encrypt_expression
+
+mongoc_client_encryption_encrypt_expression()
+=============================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   bool
+   mongoc_client_encryption_encrypt_expression (
+      mongoc_client_encryption_t *client_encryption,
+      const bson_t *expr,
+      mongoc_client_encryption_encrypt_opts_t *opts,
+      bson_t *expr_out,
+      bson_error_t *error);
+
+.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
+.. versionadded:: 1.24.0
+
+Encrypts a Match Expression or Aggregate Expression to query a range index.
+
+To query with a ``RangePreview`` encrypted payload, use a
+:symbol:`mongoc_client_t` configured with
+:symbol:`mongoc_auto_encryption_opts_t`. The
+:symbol:`mongoc_auto_encryption_opts_t` may be configured to bypass query
+analysis with :symbol:`mongoc_auto_encryption_opts_set_bypass_query_analysis`.
+The :symbol:`mongoc_auto_encryption_opts_t` must not be configured to bypass
+automatic encryption with
+:symbol:`mongoc_auto_encryption_opts_set_bypass_auto_encryption`. 
+
+To query with a ``RangePreview`` payload, ``expr`` must be one of the following forms: 
+
+#. A Match Expression of the following form: 
+
+   .. code-block:: javascript
+   
+      // $gt may also be $gte. $lt may also be $lte.
+      // Can include one of $gt/$gte/$lt/$lte. It is not required to include both.
+      {"$and": [{"<field>": {"$gt": "<value1>"}}, {"<field>": {"$lt": "<value2>" }}]}
+
+#. An Aggregation Expression of this form: 
+
+   .. code-block:: javascript
+   
+      // $gt may also be $gte. $lt may also be $lte
+      // Can include one of $gt/$gte/$lt/$lte. It is not required to include both.
+      {"$and": [{"$gt": ["<fieldpath>", "<value1>"]}, {"$lt": ["<fieldpath>", "<value2>"]}]
+
+Parameters
+----------
+
+* ``client_encryption``: A :symbol:`mongoc_client_encryption_t`
+* ``expr``: The expression to encrypt.
+* ``opts``: A :symbol:`mongoc_client_encryption_encrypt_opts_t`.
+* ``expr_out``: A :symbol:`bson_t` for the resulting encrypted expression. ``expr_out`` is always initialized (even on failure). Caller must call :symbol:`bson_destroy()` to free.
+* ``error``: A :symbol:`bson_error_t` set on failure.
+
+Returns
+-------
+
+Returns ``true`` if successful. Returns ``false`` and sets ``error`` otherwise.
+
+.. seealso::
+
+  | :symbol:`mongoc_client_encryption_encrypt_opts_t`
+
+  | :symbol:`mongoc_client_enable_auto_encryption()`
+
+  | :symbol:`mongoc_client_encryption_decrypt()`
+

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_algorithm.rst

@@ -18,6 +18,8 @@ Synopsis
    #define MONGOC_ENCRYPT_ALGORITHM_INDEXED "Indexed"
    // (Experimental: See below)
    #define MONGOC_ENCRYPT_ALGORITHM_UNINDEXED "Unindexed"
+   // (Experimental: See below)
+   #define MONGOC_ENCRYPT_ALGORITHM_RANGEPREVIEW "RangePreview"
 
 Identifies the algorithm to use for encryption. Valid values of ``algorithm`` are:
 
@@ -41,6 +43,12 @@ Identifies the algorithm to use for encryption. Valid values of ``algorithm`` ar
 
    .. note:: |qenc:opt-is-experimental|
 
+``"RangePreview"``
+
+   for range encryption.
+   
+   .. note:: The |qenc:range-is-experimental| |qenc:opt-is-experimental|
+
 Parameters
 ----------
 

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_contention_factor.rst

@@ -16,8 +16,8 @@ Synopsis
 .. versionadded:: 1.22.0
 
 Sets a contention factor for explicit encryption.
-Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Indexed".
-It is an error to set the contention factor when algorithm is not "Indexed".
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Indexed" or "RangePreview".
+It is an error to set the contention factor when algorithm is not "Indexed" or "RangePreview". **Note** that the |qenc:range-is-experimental|
 If contention factor is not supplied, it defaults to a value of 0.
 
 Parameters

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_query_type.rst

@@ -9,6 +9,7 @@ Synopsis
 .. code-block:: c
 
    #define MONGOC_ENCRYPT_QUERY_TYPE_EQUALITY "equality"
+   #define MONGOC_ENCRYPT_QUERY_TYPE_RANGEPREVIEW "rangePreview"
 
    MONGOC_EXPORT (void)
     mongoc_client_encryption_encrypt_opts_set_query_type (
@@ -17,11 +18,11 @@ Synopsis
 .. important:: |qenc:api-is-experimental|
 .. versionadded:: 1.22.0
 
-Sets a query type for explicit encryption. Currently, the only supported value
-for ``query_type`` is ``"equality"``.
+Sets a query type for explicit encryption. Currently, the supported values
+for ``query_type`` are ``"equality"`` and ``"rangePreview"``. **NOTE** that the |qenc:range-is-experimental|
 
-Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Indexed".
-It is an error to set the query type when algorithm is not "Indexed".
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Indexed" or "RangePreview".
+It is an error to set the query type when algorithm is not "Indexed" or "RangePreview".
 
 Parameters
 ----------

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_range_opts.rst

@@ -0,0 +1,31 @@
+:man_page: mongoc_client_encryption_encrypt_opts_set_range_opts
+
+mongoc_client_encryption_encrypt_opts_set_range_opts()
+======================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+    void
+    mongoc_client_encryption_encrypt_opts_set_range_opts (
+          mongoc_client_encryption_encrypt_opts_t *opts,
+          const mongoc_client_encryption_encrypt_range_opts_t *range_opts);
+
+.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
+.. versionadded:: 1.24.0
+
+Sets the ``range_opts`` for explicit encryption.
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "RangePreview".
+It is an error to set ``range_opts`` when algorithm is not "RangePreview".
+
+Parameters
+----------
+
+* ``opts``: A :symbol:`mongoc_client_encryption_encrypt_opts_t`
+* ``range_opts``: A :symbol:`mongoc_client_encryption_encrypt_range_opts_t`
+
+.. seealso::
+
+  | :symbol:`mongoc_client_encryption_encrypt_range_opts_new`

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_t.rst

@@ -29,6 +29,7 @@ Used to set options for :symbol:`mongoc_client_encryption_encrypt()`.
     mongoc_client_encryption_encrypt_opts_set_algorithm
     mongoc_client_encryption_encrypt_opts_set_contention_factor
     mongoc_client_encryption_encrypt_opts_set_query_type
+    mongoc_client_encryption_encrypt_opts_set_range_opts
 
 .. seealso::
 

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_destroy.rst

@@ -0,0 +1,25 @@
+:man_page: mongoc_client_encryption_encrypt_range_opts_destroy
+
+mongoc_client_encryption_encrypt_range_opts_destroy()
+=====================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_client_encryption_encrypt_range_opts_destroy (mongoc_client_encryption_encrypt_range_opts_t *range_opts);
+
+.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
+.. versionadded:: 1.24.0
+    
+Frees resources of a :symbol:`mongoc_client_encryption_encrypt_range_opts_t` created with :symbol:`mongoc_client_encryption_encrypt_range_opts_new()`. Does nothing if ``NULL`` is passed.
+
+Parameters
+----------
+
+* ``range_opts``: A :symbol:`mongoc_client_encryption_encrypt_range_opts_t`.
+
+.. seealso::
+    | :symbol:`mongoc_client_encryption_encrypt_range_opts_t`

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_new.rst

@@ -0,0 +1,25 @@
+:man_page: mongoc_client_encryption_encrypt_range_opts_new
+
+mongoc_client_encryption_encrypt_range_opts_new()
+=================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  mongoc_client_encryption_encrypt_range_opts_t *
+  mongoc_client_encryption_encrypt_range_opts_new (void);
+
+.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
+.. versionadded:: 1.24.0
+
+Returns
+-------
+
+A new :symbol:`mongoc_client_encryption_encrypt_range_opts_t` that must be freed with :symbol:`mongoc_client_encryption_encrypt_range_opts_destroy()`.
+
+
+.. seealso::
+    | :symbol:`mongoc_client_encryption_encrypt_range_opts_t`
+    | :symbol:`mongoc_client_encryption_encrypt_range_opts_destroy`

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_set_min_max.rst

@@ -0,0 +1,39 @@
+:man_page: mongoc_client_encryption_encrypt_range_opts_set_min_max
+
+mongoc_client_encryption_encrypt_range_opts_set_min_max()
+=========================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+    void
+    mongoc_client_encryption_encrypt_opts_set_min_max (
+         mongoc_client_encryption_encrypt_range_opts_t *range_opts, 
+         const bson_value_t *min,
+         const bson_value_t *max);
+
+.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
+.. versionadded:: 1.24.0
+
+Sets the minimum and maximum values of the range for explicit encryption.
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "RangePreview".
+It is an error to set minimum and maximum when algorithm is not "RangePreview".
+
+The minimum and maximum must match the values set in the encryptedFields of the destination collection.
+It is an error to set a different value.
+
+For double and decimal128 fields, min/max/precision must all be set, or all be unset.
+
+Parameters
+----------
+
+* ``range_opts``: A :symbol:`mongoc_client_encryption_encrypt_range_opts_t`
+* ``min``: The minimum bson value of the range. 
+* ``max``: The maximum bson value of the range. 
+
+.. seealso::
+
+  | :symbol:`mongoc_client_encryption_encrypt_range_opts_set_precision`
+  | :symbol:`mongoc_client_encryption_encrypt_range_opts_t`

src/libmongoc/doc/mongoc_client_encryption_encrypt_range_opts_set_precision.rst

@@ -0,0 +1,39 @@
+:man_page: mongoc_client_encryption_encrypt_range_opts_set_precision
+
+mongoc_client_encryption_encrypt_range_opts_set_precision()
+===========================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+    void
+    mongoc_client_encryption_encrypt_opts_set_precision (
+         mongoc_client_encryption_encrypt_range_opts_t *range_opts, int32_t precision);
+
+.. important:: The |qenc:range-is-experimental| |qenc:api-is-experimental|
+.. versionadded:: 1.24.0
+
+Sets precision for explicit encryption.
+Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "RangePreview".
+It is an error to set precision when algorithm is not "RangePreview".
+
+Precision can only be set with double or decimal128 fields. 
+It is an error to set precision if the type of the encryptedFields in the destination collection is not double or decimal128. 
+
+For double and decimal128 fields, min/max/precision must all be set, or all be unset.
+
+Precision must match the value set in the encryptedFields of the destination collection.
+It is an error to set a different value.
+
+Parameters
+----------
+
+* ``range_opts``: A :symbol:`mongoc_client_encryption_encrypt_range_opts_t`
+* ``precision``: A non-negative precision. 
+
+.. seealso::
+
+  | :symbol:`mongoc_client_encryption_encrypt_range_opts_set_min_max`
+  | :symbol:`mongoc_client_encryption_encrypt_range_opts_t`