CDRIVER-6044 Text search explicit encryption API and prose tests (#2084)

Author: mdb-ad

src/libmongoc/CMakeLists.txt

@@ -489,10 +489,10 @@ elseif (NOT ENABLE_CLIENT_SIDE_ENCRYPTION STREQUAL OFF)
       find_package (mongocrypt QUIET)
    endif ()
 
-   if (mongocrypt_FOUND AND "${mongocrypt_VERSION}" VERSION_LESS 1.15.0)
+   if (mongocrypt_FOUND AND "${mongocrypt_VERSION}" VERSION_LESS 1.15.1)
       message (STATUS "  libmongocrypt found at ${mongocrypt_DIR}")
       message (STATUS "  libmongocrypt version ${mongocrypt_VERSION} found")
-      message (STATUS "  libmongocrypt version 1.15.0 is required to enable In-Use Encryption Support.")
+      message (STATUS "  libmongocrypt version 1.15.1 is required to enable In-Use Encryption Support.")
       set (REQUIRED_MONGOCRYPT_VERSION_FOUND OFF)
    elseif (mongocrypt_FOUND)
       set (REQUIRED_MONGOCRYPT_VERSION_FOUND ON)

src/libmongoc/doc/api.rst

@@ -23,6 +23,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_text_opts_t
    mongoc_client_encryption_encrypt_range_opts_t
    mongoc_client_encryption_opts_t
    mongoc_client_pool_t

src/libmongoc/doc/conf.py

@@ -193,6 +193,12 @@ def _maybe_update_inventories(app: Sphinx):
 .. |bson_t-opt-storage-ptr| replace::
     maybe-``NULL`` pointer to `overwritable storage <bson_lifetimes_>`_ for a :symbol:`bson_t`
 
+.. |encrypt-text-is-experimental| replace::
+    The "TextPreview" algorithm is in preview and should be used for experimental workloads only.
+    These features are unstable and their security is not guaranteed until released as Generally
+    Available (GA). The GA version of these features may not be backwards compatible with the
+    preview version.
+
 .. _mongodb_docs_cdriver: https://www.mongodb.com/docs/languages/c/c-driver/current/
 
 .. _queryable-encryption: https://www.mongodb.com/docs/languages/c/c-driver/current/libmongoc/guides/queryable-encryption/

src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_text_opts.rst

@@ -0,0 +1,33 @@
+:man_page: mongoc_client_encryption_encrypt_opts_set_text_opts
+
+mongoc_client_encryption_encrypt_opts_set_text_opts()
+=====================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_client_encryption_encrypt_opts_set_text_opts(
+      mongoc_client_encryption_encrypt_opts_t *opts,
+      const mongoc_client_encryption_encrypt_text_opts_t *text_opts);
+
+.. versionadded:: 2.2.0
+
+Sets the text search encryption options for explicit encryption.
+
+|encrypt-text-is-experimental|
+
+Parameters
+----------
+
+* ``opts``: A :symbol:`mongoc_client_encryption_encrypt_opts_t`.
+* ``text_opts``: A :symbol:`mongoc_client_encryption_encrypt_text_opts_t` specifying text search options.
+
+.. seealso::
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_t`
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_new`
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_set_prefix`
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_set_suffix`
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_set_substring`

src/libmongoc/doc/mongoc_client_encryption_encrypt_text_opts_destroy.rst

@@ -0,0 +1,26 @@
+:man_page: mongoc_client_encryption_encrypt_text_opts_destroy
+
+mongoc_client_encryption_encrypt_text_opts_destroy()
+====================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_client_encryption_encrypt_text_opts_destroy(mongoc_client_encryption_encrypt_text_opts_t *topts);
+
+.. versionadded:: 2.2.0
+
+Frees a :symbol:`mongoc_client_encryption_encrypt_text_opts_t` created with :symbol:`mongoc_client_encryption_encrypt_text_opts_new()`.
+
+|encrypt-text-is-experimental|
+
+Parameters
+----------
+
+* ``topts``: A :symbol:`mongoc_client_encryption_encrypt_text_opts_t` to destroy.
+
+.. seealso::
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_new`

src/libmongoc/doc/mongoc_client_encryption_encrypt_text_opts_new.rst

@@ -0,0 +1,27 @@
+:man_page: mongoc_client_encryption_encrypt_text_opts_new
+
+mongoc_client_encryption_encrypt_text_opts_new()
+================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   mongoc_client_encryption_encrypt_text_opts_t *
+   mongoc_client_encryption_encrypt_text_opts_new(void);
+
+.. versionadded:: 2.2.0
+
+|encrypt-text-is-experimental|
+
+Returns
+-------
+
+A new :symbol:`mongoc_client_encryption_encrypt_text_opts_t` that must be freed with :symbol:`mongoc_client_encryption_encrypt_text_opts_destroy()`.
+
+.. seealso::
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_destroy`
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_set_prefix`
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_set_suffix`
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_set_substring`

src/libmongoc/doc/mongoc_client_encryption_encrypt_text_opts_set_case_sensitive.rst

@@ -0,0 +1,29 @@
+:man_page: mongoc_client_encryption_encrypt_text_opts_set_case_sensitive
+
+mongoc_client_encryption_encrypt_text_opts_set_case_sensitive()
+===============================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_client_encryption_encrypt_text_opts_set_case_sensitive(
+      mongoc_client_encryption_encrypt_text_opts_t *opts,
+      bool case_sensitive);
+
+.. versionadded:: 2.2.0
+
+Sets whether text search is case sensitive.
+
+|encrypt-text-is-experimental|
+
+Parameters
+----------
+
+* ``opts``: A :symbol:`mongoc_client_encryption_encrypt_text_opts_t`.
+* ``case_sensitive``: If true, text search is case sensitive.
+
+.. seealso::
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_t`

src/libmongoc/doc/mongoc_client_encryption_encrypt_text_opts_set_diacritic_sensitive.rst

@@ -0,0 +1,29 @@
+:man_page: mongoc_client_encryption_encrypt_text_opts_set_diacritic_sensitive
+
+mongoc_client_encryption_encrypt_text_opts_set_diacritic_sensitive()
+====================================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_client_encryption_encrypt_text_opts_set_diacritic_sensitive(
+      mongoc_client_encryption_encrypt_text_opts_t *opts,
+      bool diacritic_sensitive);
+
+.. versionadded:: 2.2.0
+
+Sets whether text search is diacritic sensitive.
+
+|encrypt-text-is-experimental|
+
+Parameters
+----------
+
+* ``opts``: A :symbol:`mongoc_client_encryption_encrypt_text_opts_t`.
+* ``diacritic_sensitive``: If true, text search is diacritic sensitive.
+
+.. seealso::
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_t`

src/libmongoc/doc/mongoc_client_encryption_encrypt_text_opts_set_prefix.rst

@@ -0,0 +1,30 @@
+:man_page: mongoc_client_encryption_encrypt_text_opts_set_prefix
+
+mongoc_client_encryption_encrypt_text_opts_set_prefix()
+=======================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_client_encryption_encrypt_text_opts_set_prefix(
+      mongoc_client_encryption_encrypt_text_opts_t *opts,
+      mongoc_client_encryption_encrypt_text_prefix_opts_t *popts);
+
+.. versionadded:: 2.2.0
+
+Sets the prefix options for text search encryption.
+
+|encrypt-text-is-experimental|
+
+Parameters
+----------
+
+* ``opts``: A :symbol:`mongoc_client_encryption_encrypt_text_opts_t`.
+* ``popts``: A :symbol:`mongoc_client_encryption_encrypt_text_prefix_opts_t` to set as prefix options.
+
+.. seealso::
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_new`
+   | :symbol:`mongoc_client_encryption_encrypt_text_prefix_opts_new`

src/libmongoc/doc/mongoc_client_encryption_encrypt_text_opts_set_substring.rst

@@ -0,0 +1,30 @@
+:man_page: mongoc_client_encryption_encrypt_text_opts_set_substring
+
+mongoc_client_encryption_encrypt_text_opts_set_substring()
+==========================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_client_encryption_encrypt_text_opts_set_substring(
+      mongoc_client_encryption_encrypt_text_opts_t *opts,
+      mongoc_client_encryption_encrypt_text_substring_opts_t *ssopts);
+
+.. versionadded:: 2.2.0
+
+Sets the substring options for text search encryption.
+
+|encrypt-text-is-experimental|
+
+Parameters
+----------
+
+* ``opts``: A :symbol:`mongoc_client_encryption_encrypt_text_opts_t`.
+* ``ssopts``: A :symbol:`mongoc_client_encryption_encrypt_text_substring_opts_t` to set as substring options.
+
+.. seealso::
+   | :symbol:`mongoc_client_encryption_encrypt_text_opts_new`
+   | :symbol:`mongoc_client_encryption_encrypt_text_substring_opts_new`