CDRIVER-4372 Add FLE 2 API to explicit encryption (#997)

Author: kevinAlbs

src/libmongoc/doc/mongoc_client_encryption_encrypt.rst

@@ -20,6 +20,10 @@ 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 :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`.
+
 Parameters
 ----------
 

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_algorithm.rst

@@ -14,11 +14,15 @@ Synopsis
 
    #define MONGOC_AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
    #define MONGOC_AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
+   #define MONGOC_ENCRYPT_ALGORITHM_INDEXED "Indexed"
+   #define MONGOC_ENCRYPT_ALGORITHM_UNINDEXED "Unindexed"
 
 Identifies the algorithm to use for encryption. Valid values of ``algorithm`` are:
 
 * "AEAD_AES_256_CBC_HMAC_SHA_512-Random" for randomized encryption.
 * "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" for deterministic (queryable) encryption.
+* "Indexed" for indexed encryption.
+* "Unindexed" for unindexed encryption.
 
 Parameters
 ----------

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_contention_factor.rst

@@ -0,0 +1,24 @@
+:man_page: mongoc_client_encryption_encrypt_opts_set_contention_factor
+
+mongoc_client_encryption_encrypt_opts_set_contention_factor()
+=============================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   MONGOC_EXPORT (void)
+    mongoc_client_encryption_encrypt_opts_set_contention_factor (
+        mongoc_client_encryption_encrypt_opts_t *opts, int64_t contention_factor);
+
+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".
+If contention factor is not supplied, it defaults to a value of 0.
+
+Parameters
+----------
+
+* ``opts``: A :symbol:`mongoc_client_encryption_encrypt_opts_t`
+* ``contention_factor``: A non-negative contention factor.

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_query_type.rst

@@ -0,0 +1,25 @@
+:man_page: mongoc_client_encryption_encrypt_opts_set_query_type
+
+mongoc_client_encryption_encrypt_opts_set_query_type()
+======================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   typedef enum { MONGOC_ENCRYPT_QUERY_TYPE_EQUALITY } mongoc_encrypt_query_type_t;
+
+   MONGOC_EXPORT (void)
+    mongoc_client_encryption_encrypt_opts_set_query_type (
+        mongoc_client_encryption_encrypt_opts_t *opts, mongoc_encrypt_query_type_t query_type);
+
+Sets a query type 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 query type when algorithm is not "Indexed".
+
+Parameters
+----------
+
+* ``opts``: A :symbol:`mongoc_client_encryption_encrypt_opts_t`
+* ``query_type``: A query type to use for explicit encryption.

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_t.rst

@@ -27,6 +27,8 @@ Used to set options for :symbol:`mongoc_client_encryption_encrypt()`.
     mongoc_client_encryption_encrypt_opts_set_keyid
     mongoc_client_encryption_encrypt_opts_set_keyaltname
     mongoc_client_encryption_encrypt_opts_set_algorithm
+    mongoc_client_encryption_encrypt_opts_set_contention_factor
+    mongoc_client_encryption_encrypt_opts_set_query_type
 
 .. seealso::
 

src/libmongoc/src/mongoc/mongoc-client-side-encryption.c

@@ -401,6 +401,14 @@ struct _mongoc_client_encryption_encrypt_opts_t {
    bson_value_t keyid;
    char *algorithm;
    char *keyaltname;
+   struct {
+      int64_t value;
+      bool set;
+   } contention_factor;
+   struct {
+      mongoc_encrypt_query_type_t value;
+      bool set;
+   } query_type;
 };
 
 mongoc_client_encryption_encrypt_opts_t *
@@ -460,6 +468,29 @@ mongoc_client_encryption_encrypt_opts_set_algorithm (
    opts->algorithm = bson_strdup (algorithm);
 }
 
+void
+mongoc_client_encryption_encrypt_opts_set_contention_factor (
+   mongoc_client_encryption_encrypt_opts_t *opts, int64_t contention_factor)
+{
+   if (!opts) {
+      return;
+   }
+   opts->contention_factor.value = contention_factor;
+   opts->contention_factor.set = true;
+}
+
+void
+mongoc_client_encryption_encrypt_opts_set_query_type (
+   mongoc_client_encryption_encrypt_opts_t *opts,
+   mongoc_encrypt_query_type_t query_type)
+{
+   if (!opts) {
+      return;
+   }
+   opts->query_type.value = query_type;
+   opts->query_type.set = true;
+}
+
 /*--------------------------------------------------------------------------
  * RewrapManyDataKeyResult.
  *--------------------------------------------------------------------------
@@ -2011,14 +2042,17 @@ mongoc_client_encryption_encrypt (mongoc_client_encryption_t *client_encryption,
       GOTO (fail);
    }
 
-   if (!_mongoc_crypt_explicit_encrypt (client_encryption->crypt,
-                                        client_encryption->keyvault_coll,
-                                        opts->algorithm,
-                                        &opts->keyid,
-                                        opts->keyaltname,
-                                        value,
-                                        ciphertext,
-                                        error)) {
+   if (!_mongoc_crypt_explicit_encrypt (
+          client_encryption->crypt,
+          client_encryption->keyvault_coll,
+          opts->algorithm,
+          &opts->keyid,
+          opts->keyaltname,
+          opts->query_type.set ? &opts->query_type.value : NULL,
+          opts->contention_factor.set ? &opts->contention_factor.value : NULL,
+          value,
+          ciphertext,
+          error)) {
       GOTO (fail);
    }
 

src/libmongoc/src/mongoc/mongoc-client-side-encryption.h

@@ -29,6 +29,8 @@ struct _mongoc_client_pool_t;
    "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
 #define MONGOC_AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC \
    "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
+#define MONGOC_ENCRYPT_ALGORITHM_INDEXED "Indexed"
+#define MONGOC_ENCRYPT_ALGORITHM_UNINDEXED "Unindexed"
 
 BSON_BEGIN_DECLS
 
@@ -190,6 +192,17 @@ MONGOC_EXPORT (void)
 mongoc_client_encryption_encrypt_opts_set_algorithm (
    mongoc_client_encryption_encrypt_opts_t *opts, const char *algorithm);
 
+MONGOC_EXPORT (void)
+mongoc_client_encryption_encrypt_opts_set_contention_factor (
+   mongoc_client_encryption_encrypt_opts_t *opts, int64_t contention_factor);
+
+typedef enum { MONGOC_ENCRYPT_QUERY_TYPE_EQUALITY } mongoc_encrypt_query_type_t;
+
+MONGOC_EXPORT (void)
+mongoc_client_encryption_encrypt_opts_set_query_type (
+   mongoc_client_encryption_encrypt_opts_t *opts,
+   mongoc_encrypt_query_type_t query_type);
+
 MONGOC_EXPORT (mongoc_client_encryption_datakey_opts_t *)
 mongoc_client_encryption_datakey_opts_new (void) BSON_GNUC_WARN_UNUSED_RESULT;
 

src/libmongoc/src/mongoc/mongoc-crypt-private.h

@@ -79,6 +79,8 @@ Perform explicit encryption.
 - exactly one of keyid or keyaltname must be set, the other NULL, or an error is
 returned.
 - value_out is always initialized.
+- query_type may be NULL.
+- contention_factor may be NULL.
 - may return false and set error.
 */
 bool
@@ -87,6 +89,8 @@ _mongoc_crypt_explicit_encrypt (_mongoc_crypt_t *crypt,
                                 const char *algorithm,
                                 const bson_value_t *keyid,
                                 char *keyaltname,
+                                const mongoc_encrypt_query_type_t *query_type,
+                                const int64_t *contention_factor,
                                 const bson_value_t *value_in,
                                 bson_value_t *value_out,
                                 bson_error_t *error);

src/libmongoc/src/mongoc/mongoc-crypt.c

@@ -1134,6 +1134,8 @@ _mongoc_crypt_explicit_encrypt (_mongoc_crypt_t *crypt,
                                 const char *algorithm,
                                 const bson_value_t *keyid,
                                 char *keyaltname,
+                                const mongoc_encrypt_query_type_t *query_type,
+                                const int64_t *contention_factor,
                                 const bson_value_t *value_in,
                                 bson_value_t *value_out,
                                 bson_error_t *error)
@@ -1156,9 +1158,48 @@ _mongoc_crypt_explicit_encrypt (_mongoc_crypt_t *crypt,
       goto fail;
    }
 
-   if (!mongocrypt_ctx_setopt_algorithm (state_machine->ctx, algorithm, -1)) {
-      _ctx_check_error (state_machine->ctx, error, true);
-      goto fail;
+   if (NULL != algorithm &&
+       0 == strcmp (algorithm, MONGOC_ENCRYPT_ALGORITHM_INDEXED)) {
+      if (!mongocrypt_ctx_setopt_index_type (state_machine->ctx,
+                                             MONGOCRYPT_INDEX_TYPE_EQUALITY)) {
+         _ctx_check_error (state_machine->ctx, error, true);
+         goto fail;
+      }
+   } else if (NULL != algorithm &&
+              0 == strcmp (algorithm, MONGOC_ENCRYPT_ALGORITHM_UNINDEXED)) {
+      if (!mongocrypt_ctx_setopt_index_type (state_machine->ctx,
+                                             MONGOCRYPT_INDEX_TYPE_NONE)) {
+         _ctx_check_error (state_machine->ctx, error, true);
+         goto fail;
+      }
+   } else {
+      if (!mongocrypt_ctx_setopt_algorithm (
+             state_machine->ctx, algorithm, -1)) {
+         _ctx_check_error (state_machine->ctx, error, true);
+         goto fail;
+      }
+   }
+
+   if (query_type != NULL) {
+      mongocrypt_query_type_t converted;
+
+      switch (*query_type) {
+      case MONGOC_ENCRYPT_QUERY_TYPE_EQUALITY:
+         converted = MONGOCRYPT_QUERY_TYPE_EQUALITY;
+         break;
+      }
+      if (!mongocrypt_ctx_setopt_query_type (state_machine->ctx, converted)) {
+         _ctx_check_error (state_machine->ctx, error, true);
+         goto fail;
+      }
+   }
+
+   if (contention_factor != NULL) {
+      if (!mongocrypt_ctx_setopt_contention_factor (state_machine->ctx,
+                                                    *contention_factor)) {
+         _ctx_check_error (state_machine->ctx, error, true);
+         goto fail;
+      }
    }
 
    if (keyaltname) {

src/libmongoc/tests/client_side_encryption_prose/explicit_encryption/encryptedFields.json

@@ -0,0 +1,30 @@
+{
+  "fields": [
+    {
+      "keyId": {
+        "$binary": {
+          "base64": "EjRWeBI0mHYSNBI0VniQEg==",
+          "subType": "04"
+        }
+      },
+      "path": "encryptedIndexed",
+      "bsonType": "string",
+      "queries": {
+        "queryType": "equality",
+        "contention": {
+          "$numberLong": "0"
+        }
+      }
+    },
+    {
+      "keyId": {
+        "$binary": {
+          "base64": "q83vqxI0mHYSNBI0VniQEg==",
+          "subType": "04"
+        }
+      },
+      "path": "encryptedUnindexed",
+      "bsonType": "string"
+    }
+  ]
+}

src/libmongoc/tests/client_side_encryption_prose/explicit_encryption/key1-document.json

@@ -0,0 +1,30 @@
+{
+    "_id": {
+        "$binary": {
+            "base64": "EjRWeBI0mHYSNBI0VniQEg==",
+            "subType": "04"
+        }
+    },
+    "keyMaterial": {
+        "$binary": {
+            "base64": "sHe0kz57YW7v8g9VP9sf/+K1ex4JqKc5rf/URX3n3p8XdZ6+15uXPaSayC6adWbNxkFskuMCOifDoTT+rkqMtFkDclOy884RuGGtUysq3X7zkAWYTKi8QAfKkajvVbZl2y23UqgVasdQu3OVBQCrH/xY00nNAs/52e958nVjBuzQkSb1T8pKJAyjZsHJ60+FtnfafDZSTAIBJYn7UWBCwQ==",
+            "subType": "00"
+        }
+    },
+    "creationDate": {
+        "$date": {
+            "$numberLong": "1648914851981"
+        }
+    },
+    "updateDate": {
+        "$date": {
+            "$numberLong": "1648914851981"
+        }
+    },
+    "status": {
+        "$numberInt": "0"
+    },
+    "masterKey": {
+        "provider": "local"
+    }
+}

src/libmongoc/tests/test-libmongoc.c

@@ -2604,6 +2604,8 @@ WIRE_VERSION_CHECKS (9)
 WIRE_VERSION_CHECKS (13)
 /* wire version 14 begins with the 5.1 prerelease. */
 WIRE_VERSION_CHECKS (14)
+/* wire version 17 begins with the 6.0 release. */
+WIRE_VERSION_CHECKS (17)
 
 int
 test_framework_skip_if_no_dual_ip_hostname (void)

src/libmongoc/tests/test-libmongoc.h

@@ -199,6 +199,8 @@ WIRE_VERSION_CHECK_DECLS (9)
 WIRE_VERSION_CHECK_DECLS (13)
 /* wire version 14 begins with the 5.1 prerelease. */
 WIRE_VERSION_CHECK_DECLS (14)
+/* wire version 17 begins with the 6.0 release. */
+WIRE_VERSION_CHECK_DECLS (17)
 
 #undef WIRE_VERSION_CHECK_DECLS