mongo 2.13.1 → 2.19.1

data/lib/mongo/crypt/binding.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
 # Copyright (C) 2019-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,20 +16,28 @@
 # limitations under the License.
 
 unless ENV['LIBMONGOCRYPT_PATH']
-  # It seems that MRI maintains autoload configuration for a module until
-  # that module is defined, but JRuby removes autoload configuration as soon
-  # as the referenced file is attempted to be loaded, even if the module
-  # never ends up being defined.
-  if BSON::Environment.jruby?
-    module Mongo
-      module Crypt
-        autoload :Binding, 'mongo/crypt/binding'
+  begin
+    require 'libmongocrypt_helper'
+  rescue LoadError => e
+    # It seems that MRI maintains autoload configuration for a module until
+    # that module is defined, but JRuby removes autoload configuration as soon
+    # as the referenced file is attempted to be loaded, even if the module
+    # never ends up being defined.
+    if BSON::Environment.jruby?
+      module Mongo
+        module Crypt
+          autoload :Binding, 'mongo/crypt/binding'
+        end
       end
     end
-  end
 
-  raise LoadError, "Cannot load Mongo::Crypt::Binding because there is no path " +
-      "to libmongocrypt specified in the LIBMONGOCRYPT_PATH environment variable."
+    # JRuby 9.3.2.0 replaces a LoadError with our custom message with a
+    # generic NameError, when this load is attempted as part of autoloading
+    # process. JRuby 9.2.20.0 propagates LoadError as expected.
+    raise LoadError, "Cannot load Mongo::Crypt::Binding because there is no path " +
+        "to libmongocrypt specified in the LIBMONGOCRYPT_PATH environment variable " +
+        "and libmongocrypt-helper is not installed: #{e.class}: #{e}"
+  end
 end
 
 require 'ffi'
@@ -47,15 +58,33 @@ module Mongo
     class Binding
       extend FFI::Library
 
-      begin
-        ffi_lib ENV['LIBMONGOCRYPT_PATH']
-      rescue LoadError => e
-        Crypt.reset_autoload
-        raise LoadError, "Cannot load Mongo::Crypt::Binding because the path to " +
-          "libmongocrypt specified in the LIBMONGOCRYPT_PATH environment variable " +
-          "is invalid: #{ENV['LIBMONGOCRYPT_PATH']}\n\n#{e.class}: #{e.message}"
+      if ENV['LIBMONGOCRYPT_PATH']
+        begin
+          ffi_lib ENV['LIBMONGOCRYPT_PATH']
+        rescue LoadError => e
+          Crypt.reset_autoload
+          raise LoadError, "Cannot load Mongo::Crypt::Binding because the path to " +
+            "libmongocrypt specified in the LIBMONGOCRYPT_PATH environment variable " +
+            "is invalid: #{ENV['LIBMONGOCRYPT_PATH']}\n\n#{e.class}: #{e.message}"
+        end
+      else
+        begin
+          ffi_lib LibmongocryptHelper.libmongocrypt_path
+        rescue LoadError => e
+          Crypt.reset_autoload
+          raise LoadError, "Cannot load Mongo::Crypt::Binding because the path to " +
+            "libmongocrypt specified in libmongocrypt-helper " +
+            "is invalid: #{LibmongocryptHelper.libmongocrypt_path}\n\n#{e.class}: #{e.message}"
+        end
       end
 
+      # Minimum version of libmongocrypt required by this version of the driver.
+      # An attempt to use the driver with any previous version of libmongocrypt
+      # will cause a `LoadError`.
+      #
+      # @api private
+      MIN_LIBMONGOCRYPT_VERSION = Gem::Version.new("1.7.0")
+
       # @!method self.mongocrypt_version(len)
       #   @api private
       #
@@ -65,6 +94,49 @@ module Mongo
       #   @return [ String ] A version string for libmongocrypt.
       attach_function :mongocrypt_version, [:pointer], :string
 
+      # Given a string representing a version number, parses it into a
+      # Gem::Version object. This handles the case where the string is not
+      # in a format supported by Gem::Version by doing some custom parsing.
+      #
+      # @param [ String ] version String representing a version number.
+      #
+      # @return [ Gem::Version ] the version number
+      #
+      # @raise [ ArgumentError ] if the string cannot be parsed.
+      #
+      # @api private
+      def self.parse_version(version)
+        Gem::Version.new(version)
+      rescue ArgumentError
+        match = version.match(/\A(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)?(-[A-Za-z\+\d]+)?\z/)
+        raise ArgumentError.new("Malformed version number string #{version}") if match.nil?
+
+        Gem::Version.new(
+          [
+            match[:major],
+            match[:minor],
+            match[:patch]
+          ].join('.')
+        )
+      end
+
+      # Validates if provided version of libmongocrypt is valid, i.e. equal or
+      # greater than minimum required version. Raises a LoadError if not.
+      #
+      # @param [ String ] lmc_version String representing libmongocrypt version.
+      #
+      # @raise [ LoadError ] if given version is lesser than minimum required version.
+      #
+      # @api private
+      def self.validate_version(lmc_version)
+        if (actual_version = parse_version(lmc_version)) < MIN_LIBMONGOCRYPT_VERSION
+          raise LoadError, "libmongocrypt version #{MIN_LIBMONGOCRYPT_VERSION} or above is required, " +
+            "but version #{actual_version} was found."
+        end
+      end
+
+      validate_version(mongocrypt_version(nil))
+
       # @!method self.mongocrypt_binary_new
       #   @api private
       #
@@ -250,69 +322,36 @@ module Mongo
         end
       end
 
-      # @!method self.mongocrypt_setopt_kms_provider_aws(crypt, aws_access_key_id, aws_access_key_id_len, aws_secret_access_key, aws_secret_access_key_len)
+      # @!method self.mongocrypt_setopt_kms_providers(crypt, kms_providers)
       #   @api private
       #
-      #   Configure mongocrypt_t object with AWS KMS provider options.
+      #   Configure KMS providers with a BSON document.
       #   @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
-      #   @param [ String ] aws_access_key_id The AWS access key id.
-      #   @param [ Integer ] aws_access_key_id_len The length of the AWS access
-      #     key string (or -1 for a null-terminated string).
-      #   @param [ String ] aws_secret_access_key The AWS secret access key.
-      #   @param [ Integer ] aws_secret_access_key_len The length of the AWS
-      #     secret access key (or -1 for a null-terminated string).
-      #   @return [ Boolean ] Returns whether the option was set successfully.
-      attach_function(
-        :mongocrypt_setopt_kms_provider_aws,
-        [:pointer, :string, :int, :string, :int],
-        :bool
-      )
-
-      # Configure the Handle object with AWS KMS provider options
-      #
-      # @param [ Mongo::Crypt::Handle ] handle
-      # @param [ String ] aws_access_key The AWS access key
-      # @param [ String ] aws_secret_access_key The AWS secret access key
-      #
-      # @raise [ Mongo::Error::CryptError ] If the option is not set successfully
-      def self.setopt_kms_provider_aws(handle,
-        aws_access_key, aws_secret_access_key
-      )
-        check_status(handle) do
-          mongocrypt_setopt_kms_provider_aws(
-            handle.ref,
-            aws_access_key,
-            -1,
-            aws_secret_access_key,
-            -1
-          )
-        end
-      end
-
-      # @!method self.mongocrypt_setopt_kms_provider_local(crypt, key)
-      #   @api private
+      #   @param [ FFI::Pointer ] kms_providers A pointer to a
+      #     mongocrypt_binary_t object that references a BSON document mapping
+      #     the KMS provider names to credentials.
+      #   @note Do not initialize ctx before calling this method.
       #
-      #   Configure mongocrypt_t object to take local KSM provider options.
-      #   @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
-      #   @param [ FFI::Pointer ] key A pointer to a mongocrypt_binary_t object
-      #     that references the 96-byte local master key.
-      #   @return [ Boolean ] Returns whether the option was set successfully.
+      #   @returns [ true | false ] Returns whether the options was set successfully.
       attach_function(
-        :mongocrypt_setopt_kms_provider_local,
+        :mongocrypt_setopt_kms_providers,
         [:pointer, :pointer],
         :bool
       )
 
-      # Set local KMS provider options on the Mongo::Crypt::Handle object
+      # Set KMS providers options on the Mongo::Crypt::Handle object
       #
       # @param [ Mongo::Crypt::Handle ] handle
-      # @param [ String ] master_key The 96-byte local KMS master key
+      # @param [ BSON::Document ] kms_providers BSON document mapping
+      #   the KMS provider names to credentials.
       #
       # @raise [ Mongo::Error::CryptError ] If the option is not set successfully
-      def self.setopt_kms_provider_local(handle, master_key)
-        Binary.wrap_string(master_key) do |master_key_p|
+      def self.setopt_kms_providers(handle, kms_providers)
+        validate_document(kms_providers)
+        data = kms_providers.to_bson.to_s
+        Binary.wrap_string(data) do |data_p|
           check_status(handle) do
-            mongocrypt_setopt_kms_provider_local(handle.ref, master_key_p)
+            mongocrypt_setopt_kms_providers(handle.ref, data_p)
           end
         end
       end
@@ -462,6 +501,38 @@ module Mongo
         end
       end
 
+      # @!method self.mongocrypt_ctx_setopt_key_material(ctx, binary)
+      #   @api private
+      #
+      #   When creating a data key, set a custom key material to use for
+      #     encrypting data.
+      #   @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      #   @param [ FFI::Pointer ] binary A pointer to a mongocrypt_binary_t
+      #     object that references the data encryption key to use.
+      #   @return [ Boolean ] Whether the custom key material was successfully set.
+      #   @note Do not initialize ctx before calling this method.
+      attach_function(
+        :mongocrypt_ctx_setopt_key_material,
+        [:pointer, :pointer],
+        :bool
+      )
+
+      # Set set a custom key material to use for
+      #     encrypting data.
+      #
+      # @param [ Mongo::Crypt::Context ] context A DataKeyContext
+      # @param [ BSON::Binary ] key_material 96 bytes of custom key material
+      #
+      # @raise [ Mongo::Error::CryptError ] If the key material is not 96 bytes.
+      def self.ctx_setopt_key_material(context, key_material)
+        data = {'keyMaterial' => key_material}.to_bson.to_s
+        Binary.wrap_string(data) do |data_p|
+          check_ctx_status(context) do
+            mongocrypt_ctx_setopt_key_material(context.ctx_p, data_p)
+          end
+        end
+      end
+
       # @!method self.mongocrypt_ctx_setopt_algorithm(ctx, algorithm, len)
       #   @api private
       #
@@ -493,95 +564,36 @@ module Mongo
         end
       end
 
-      # @!method self.mongocrypt_ctx_setopt_masterkey_aws(ctx, region, region_len, arn, arn_len)
-      #   @api private
-      #
-      #   Configure the ctx to take a master key from AWS.
-      #   @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_object.
-      #   @param [ String ] region The AWS region.
-      #   @param [ Integer ] region_len The length of the region string (or -1
-      #     for a null-terminated string).
-      #   @param [ String ] arn The Amazon Resource Name (ARN) of the mater key.
-      #   @param [ Integer ] arn_len The length of the ARN (or -1 for a
-      #     null-terminated string).
-      #   @return [ Boolean ] Returns whether the option was set successfully.
-      attach_function(
-        :mongocrypt_ctx_setopt_masterkey_aws,
-        [:pointer, :string, :int, :string, :int],
-        :bool
-      )
-
-      # Configure the Context object to take a master key from AWS
-      #
-      # @param [ Mongo::Crypt::Context ] context
-      # @param [ String ] region The AWS region (e.g. "us-east-2")
-      # @param [ String ] arn The master key Amazon Resource Name
-      #
-      # @raise [ Mongo::Error::CryptError ] If the operation failed
-      def self.ctx_setopt_master_key_aws(context, region, arn)
-        check_ctx_status(context) do
-          mongocrypt_ctx_setopt_masterkey_aws(
-            context.ctx_p,
-            region,
-            -1,
-            arn,
-            -1
-          )
-        end
-      end
-
-      # @!method self.mongocrypt_ctx_setopt_masterkey_aws_endpoint(ctx, endpoint, endpoint_len)
-      #   @api private
-      #
-      #   Set a custom endpoint at which to fetch the AWS master key
-      #   @param [ FFI::Pointer ] ctx
-      #   @param [ String ] endpoint The custom endpoint.
-      #   @param [ Integer ] endpoint_len The length of the endpoint string (or
-      #     -1 for a null-terminated string).
-      #   @return [ Boolean ] Returns whether the option was set successfully.
-      attach_function(
-        :mongocrypt_ctx_setopt_masterkey_aws_endpoint,
-        [:pointer, :string, :int],
-        :bool
-      )
-
-      # Configure the Context object to take a masterk ey from AWS
-      #
-      # @param [ Mongo::Crypt::Context ] context
-      # @param [ String ] endpoint The custom AWS master key endpoint
-      #
-      # @raise [ Mongo::Error::CryptError ] If the operation failed
-      def self.ctx_setopt_master_key_aws_endpoint(context, endpoint)
-        check_ctx_status(context) do
-          mongocrypt_ctx_setopt_masterkey_aws_endpoint(
-            context.ctx_p,
-            endpoint,
-            -1,
-          )
-        end
-      end
-
-      # @!method self.mongocrypt_ctx_setopt_masterkey_local(ctx)
+      # @!method self.mongocrypt_ctx_setopt_key_encryption_key(ctx)
       #   @api private
       #
-      #   Set the ctx to take a local master key.
+      #   Set key encryption key document for creating a data key.
       #   @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      #   @param [ FFI::Pointer ] bin A pointer to a mongocrypt_binary_t
+      #     object that references a BSON document representing the key
+      #     encryption key document with an additional "provider" field.
       #   @note Do not initialize ctx before calling this method.
       #   @return [ Boolean ] Whether the option was successfully set.
       attach_function(
-        :mongocrypt_ctx_setopt_masterkey_local,
-        [:pointer],
+        :mongocrypt_ctx_setopt_key_encryption_key,
+        [:pointer, :pointer],
         :bool
       )
 
-      # Tell the Context object to read the master key from local KMS options
+      # Set key encryption key document for creating a data key.
       #
       # @param [ Mongo::Crypt::Context ] context
+      # @param [ BSON::Document ] key_document BSON document representing the key
+      #     encryption key document with an additional "provider" field.
       #
       # @raise [ Mongo::Error::CryptError ] If the operation failed
-      def self.ctx_setopt_master_key_local(context)
-        check_ctx_status(context) do
-          mongocrypt_ctx_setopt_masterkey_local(context.ctx_p)
+      def self.ctx_setopt_key_encryption_key(context, key_document)
+        validate_document(key_document)
+        data = key_document.to_bson.to_s
+        Binary.wrap_string(data) do |data_p|
+          check_ctx_status(context) do
+            mongocrypt_ctx_setopt_key_encryption_key(context.ctx_p, data_p)
+          end
         end
       end
 
@@ -608,6 +620,40 @@ module Mongo
         end
       end
 
+      # @!method self.mongocrypt_ctx_datakey_init(ctx, filter)
+      #   @api private
+      #
+      # Initialize a context to rewrap datakeys.
+      #
+      # @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      # @param [ FFI::Pointer ] filter A pointer to a  mongocrypt_binary_t object
+      #   that represents filter to use for the find command on the key vault
+      #   collection to retrieve datakeys to rewrap.
+      #
+      # @return [ Boolean ] Whether the initialization was successful.
+      attach_function(
+        :mongocrypt_ctx_rewrap_many_datakey_init,
+        [:pointer, :pointer],
+        :bool
+      )
+
+      # Initialize a context to rewrap datakeys.
+      #
+      # @param [ Mongo::Crypt::Context ] context
+      # @param [ BSON::Document ] filter BSON Document
+      #   that represents filter to use for the find command on the key vault
+      #   collection to retrieve datakeys to rewrap.
+      #
+      # @return [ Boolean ] Whether the initialization was successful.
+      def self.ctx_rewrap_many_datakey_init(context, filter)
+        filter_data = filter.to_bson.to_s
+        Binary.wrap_string(filter_data) do |data_p|
+          check_ctx_status(context) do
+            mongocrypt_ctx_rewrap_many_datakey_init(context.ctx_p, data_p)
+          end
+        end
+      end
+
       # @!method self.mongocrypt_ctx_encrypt_init(ctx, db, db_len, cmd)
       #   @api private
       #
@@ -679,6 +725,40 @@ module Mongo
         end
       end
 
+      # @!method self.mongocrypt_ctx_explicit_encrypt_init(ctx, msg)
+      #   @api private
+      #
+      #   Initializes the ctx for explicit expression encryption.
+      #   @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      #   @param [ FFI::Pointer ] msg A pointer to a mongocrypt_binary_t object
+      #     that references the message to be encrypted as a binary string.
+      #   @note Before calling this method, set a key_id, key_alt_name (optional),
+      #     and encryption algorithm using the following methods:
+      #     mongocrypt_ctx_setopt_key_id, mongocrypt_ctx_setopt_key_alt_name,
+      #     and mongocrypt_ctx_setopt_algorithm.
+      #   @return [ Boolean ] Whether the initialization was successful.
+      attach_function(
+        :mongocrypt_ctx_explicit_encrypt_expression_init,
+        [:pointer, :pointer],
+        :bool
+      )
+
+      # Initialize the Context for explicit expression encryption.
+      #
+      # @param [ Mongo::Crypt::Context ] context
+      # @param [ Hash ] doc A BSON document to encrypt
+      #
+      # @raise [ Mongo::Error::CryptError ] If initialization fails
+      def self.ctx_explicit_encrypt_expression_init(context, doc)
+        validate_document(doc)
+        data = doc.to_bson.to_s
+        Binary.wrap_string(data) do |data_p|
+          check_ctx_status(context) do
+            mongocrypt_ctx_explicit_encrypt_expression_init(context.ctx_p, data_p)
+          end
+        end
+      end
+
       # @!method self.mongocrypt_ctx_decrypt_init(ctx, doc)
       #   @api private
       #
@@ -737,13 +817,14 @@ module Mongo
 
       # An enum labeling different libmognocrypt state machine states
       enum :mongocrypt_ctx_state, [
-        :error,               0,
-        :need_mongo_collinfo, 1,
-        :need_mongo_markings, 2,
-        :need_mongo_keys,     3,
-        :need_kms,            4,
-        :ready,               5,
-        :done,                6,
+        :error,                 0,
+        :need_mongo_collinfo,   1,
+        :need_mongo_markings,   2,
+        :need_mongo_keys,       3,
+        :need_kms,              4,
+        :ready,                 5,
+        :done,                  6,
+        :need_kms_credentials,  7,
       ]
 
       # @!method self.mongocrypt_ctx_state(ctx)
@@ -847,6 +928,58 @@ module Mongo
         end
       end
 
+      # @!method self.mongocrypt_kms_ctx_get_kms_provider(crypt, kms_providers)
+      #   @api private
+      #
+      # Get the KMS provider identifier associated with this KMS request.
+      #
+      # This is used to conditionally configure TLS connections based on the KMS
+      # request. It is useful for KMIP, which authenticates with a client
+      # certificate.
+      #
+      # @param [ FFI::Pointer ] kms Pointer mongocrypt_kms_ctx_t object.
+      # @param [ FFI::Pointer ] len (outparam) Receives the length of the
+      #   returned string. It may be NULL. If it is not NULL, it is set to
+      #   the length of the returned string without the NULL terminator.
+      #
+      # @returns [ FFI::Pointer ] One of the NULL terminated static strings: "aws", "azure", "gcp", or
+      # "kmip".
+      attach_function(
+        :mongocrypt_kms_ctx_get_kms_provider,
+        [:pointer, :pointer],
+        :pointer
+      )
+
+      # Get the KMS provider identifier associated with this KMS request.
+      #
+      # This is used to conditionally configure TLS connections based on the KMS
+      # request. It is useful for KMIP, which authenticates with a client
+      # certificate.
+      #
+      # @param [ FFI::Pointer ] kms Pointer mongocrypt_kms_ctx_t object.
+      #
+      # @returns [ Symbol | nil ] KMS provider identifier.
+      def self.kms_ctx_get_kms_provider(kms_context)
+        len_ptr = FFI::MemoryPointer.new(:uint32, 1)
+        provider = mongocrypt_kms_ctx_get_kms_provider(
+          kms_context.kms_ctx_p,
+          len_ptr
+        )
+        if len_ptr.nil?
+          nil
+        else
+          len = if BSON::Environment.jruby?
+            # JRuby FFI implementation does not have `read(type)` method, but it
+            # has this `get_uint32`.
+            len_ptr.get_uint32
+          else
+            # For MRI we use a documented `read` method - https://www.rubydoc.info/github/ffi/ffi/FFI%2FPointer:read
+            len_ptr.read(:uint32)
+          end
+          provider.read_string(len).to_sym
+        end
+      end
+
       # @!method self.mongocrypt_kms_ctx_message(kms, msg)
       #   @api private
       #
@@ -968,7 +1101,7 @@ module Mongo
           status = Status.new
 
           mongocrypt_kms_ctx_status(kms_context.kms_ctx_p, status.ref)
-          status.raise_crypt_error
+          status.raise_crypt_error(kms: true)
         end
       end
 
@@ -1171,6 +1304,439 @@ module Mongo
         end
       end
 
+      # @!method self.mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(crypt, sign_rsaes_pkcs1_v1_5, ctx=nil)
+      #   @api private
+      #
+      #   Set a crypto hook for the RSASSA-PKCS1-v1_5 algorithm with a SHA-256 hash.
+      #   @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      #   @param [ Proc ] sign_rsaes_pkcs1_v1_5 A RSASSA-PKCS1-v1_5 signing method.
+      #   @param [ FFI::Pointer | nil ] ctx An optional pointer to a context object
+      #     that may have been set when hooks were enabled.
+      #   @return [ Boolean ] Whether setting this option succeeded.
+      attach_function(
+        :mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5,
+        [
+          :pointer,
+          :mongocrypt_hmac_fn,
+          :pointer
+        ],
+        :bool
+      )
+
+      # Set a crypto hook for the RSASSA-PKCS1-v1_5 algorithm with
+      #   a SHA-256 hash oh the Handle.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      # @param [ Method ] rsaes_pkcs_signature_cb A RSASSA-PKCS1-v1_5 signing method.
+      #
+      # @raise [ Mongo::Error::CryptError ] If the callbacks aren't set successfully
+      def self.setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(
+        handle,
+        rsaes_pkcs_signature_cb
+      )
+        check_status(handle) do
+          mongocrypt_setopt_crypto_hook_sign_rsaes_pkcs1_v1_5(
+            handle.ref,
+            rsaes_pkcs_signature_cb,
+            nil
+          )
+        end
+      end
+
+      # @!method self.mongocrypt_setopt_encrypted_field_config_map(crypt, efc_map)
+      #   @api private
+      #
+      # Set a local EncryptedFieldConfigMap for encryption.
+      #
+      # @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      # @param [ FFI::Pointer ] efc_map A pointer to mongocrypt_binary_t object that
+      # references a BSON document representing the EncryptedFieldConfigMap
+      # supplied by the user. The keys are collection namespaces and values are
+      # EncryptedFieldConfigMap documents.
+      #
+      # @return [ Boolean ] Whether the operation succeeded.
+      attach_function(
+        :mongocrypt_setopt_encrypted_field_config_map,
+        [
+          :pointer,
+          :pointer
+        ],
+        :bool
+      )
+
+      # Set a local EncryptedFieldConfigMap for encryption.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      # @param [ BSON::Document ] efc_map A BSON document representing
+      #   the EncryptedFieldConfigMap supplied by the user.
+      #   The keys are collection namespaces and values are
+      #   EncryptedFieldConfigMap documents.
+      #
+      # @raise [ Mongo::Error::CryptError ] If the operation failed.
+      def self.setopt_encrypted_field_config_map(handle, efc_map)
+        validate_document(efc_map)
+        data = efc_map.to_bson.to_s
+        Binary.wrap_string(data) do |data_p|
+          check_status(handle) do
+            mongocrypt_setopt_encrypted_field_config_map(
+              handle.ref,
+              data_p
+            )
+          end
+        end
+      end
+
+      # @!method self.mongocrypt_setopt_bypass_query_analysis(crypt)
+      #   @api private
+      #
+      # Opt into skipping query analysis.
+      #
+      # If opted in:
+      # - The csfle shared library will not attempt to be loaded.
+      # - A mongocrypt_ctx_t will never enter the MONGOCRYPT_CTX_NEED_MARKINGS state.
+      #
+      # @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      attach_function(:mongocrypt_setopt_bypass_query_analysis, [:pointer], :void)
+
+      # Opt-into skipping query analysis.
+      #
+      # If opted in:
+      # - The csfle shared library will not attempt to be loaded.
+      # - A mongocrypt_ctx_t will never enter the MONGOCRYPT_CTX_NEED_MARKINGS state.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      def self.setopt_bypass_query_analysis(handle)
+        mongocrypt_setopt_bypass_query_analysis(handle.ref)
+      end
+
+      # @!method self.mongocrypt_setopt_aes_256_ctr(crypt, aes_256_ctr_encrypt, aes_256_ctr_decrypt, ctx)
+      #   @api private
+      #
+      #   Set a crypto hook for the AES256-CTR operations.
+      #
+      #   @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      #   @param [ Proc ] aes_enc_fn An AES-CTR encryption method.
+      #   @param [ Proc ] aes_dec_fn An AES-CTR decryption method.
+      #   @param [ FFI::Pointer | nil ] ctx An optional pointer to a context object
+      #     that may have been set when hooks were enabled.
+      #   @return [ Boolean ] Whether setting this option succeeded.
+      attach_function(
+        :mongocrypt_setopt_aes_256_ctr,
+        [
+          :pointer,
+          :mongocrypt_crypto_fn,
+          :mongocrypt_crypto_fn,
+          :pointer
+        ],
+        :bool
+      )
+
+      # Set a crypto hook for the AES256-CTR operations.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      # @param [ Method ] aes_encrypt_cb An AES-CTR encryption method
+      # @param [ Method ] aes_decrypt_cb A AES-CTR decryption method
+      #
+      # @raise [ Mongo::Error::CryptError ] If the callbacks aren't set successfully
+      def self.setopt_aes_256_ctr(handle, aes_ctr_encrypt_cb, aes_ctr_decrypt_cb)
+        check_status(handle) do
+          mongocrypt_setopt_aes_256_ctr(handle.ref,
+            aes_ctr_encrypt_cb, aes_ctr_decrypt_cb, nil
+          )
+        end
+      end
+
+      # @!method self.mongocrypt_setopt_append_crypt_shared_lib_search_path(crypt, path)
+      #   @api private
+      #
+      # Append an additional search directory to the search path for loading
+      #   the crypt_shared dynamic library.
+      #
+      # @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      # @param [ String ] path A path to search for the crypt shared library. If the leading element of
+      #   the path is the literal string "$ORIGIN", that substring will be replaced
+      #   with the directory path containing the executable libmongocrypt module. If
+      #   the path string is literal "$SYSTEM", then libmongocrypt will defer to the
+      #   system's library resolution mechanism to find the crypt_shared library.
+      attach_function(
+        :mongocrypt_setopt_append_crypt_shared_lib_search_path,
+        [
+          :pointer,
+          :string,
+        ],
+        :void
+      )
+
+      # Append an additional search directory to the search path for loading
+      #   the crypt_shared dynamic library.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      # @param [ String ] path A search path for the crypt shared library.
+      def self.setopt_append_crypt_shared_lib_search_path(handle, path)
+        check_status(handle) do
+          mongocrypt_setopt_append_crypt_shared_lib_search_path(handle.ref, path)
+        end
+      end
+
+      # @!method self.mongocrypt_setopt_set_crypt_shared_lib_path_override(crypt, path)
+      #   @api private
+      #
+      # Set a single override path for loading the crypt shared library.
+      #
+      # @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      # @param [ String ] path A path to crypt shared library file. If the leading element of
+      #   the path is the literal string "$ORIGIN", that substring will be replaced
+      #   with the directory path containing the executable libmongocrypt module.
+      attach_function(
+        :mongocrypt_setopt_set_crypt_shared_lib_path_override,
+        [
+          :pointer,
+          :string,
+        ],
+        :void
+      )
+
+      # Set a single override path for loading the crypt shared library.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      # @param [ String ] path A path to crypt shared library file.
+      def self.setopt_set_crypt_shared_lib_path_override(handle, path)
+        check_status(handle) do
+          mongocrypt_setopt_set_crypt_shared_lib_path_override(handle.ref, path)
+        end
+      end
+
+      # @!method self.mongocrypt_crypt_shared_lib_version(crypt)
+      #   @api private
+      #
+      # Obtain a 64-bit constant encoding the version of the loaded
+      # crypt_shared library, if available.
+      #
+      # The version is encoded as four 16-bit numbers, from high to low:
+      #
+      # - Major version
+      # - Minor version
+      # - Revision
+      # - Reserved
+      #
+      # For example, version 6.2.1 would be encoded as: 0x0006'0002'0001'0000
+      #
+      # @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      #
+      # @return [int64] A 64-bit encoded version number, with the version encoded as four
+      #   sixteen-bit integers, or zero if no crypt_shared library was loaded.
+      attach_function(
+        :mongocrypt_crypt_shared_lib_version,
+        [ :pointer ],
+        :uint64
+      )
+
+      # Obtain a 64-bit constant encoding the version of the loaded
+      # crypt_shared library, if available.
+      #
+      # The version is encoded as four 16-bit numbers, from high to low:
+      #
+      # - Major version
+      # - Minor version
+      # - Revision
+      # - Reserved
+      #
+      # For example, version 6.2.1 would be encoded as: 0x0006'0002'0001'0000
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      #
+      # @return [ Integer ] A 64-bit encoded version number, with the version encoded as four
+      #   sixteen-bit integers, or zero if no crypt_shared library was loaded.
+      def self.crypt_shared_lib_version(handle)
+        mongocrypt_crypt_shared_lib_version(handle.ref)
+      end
+
+      # @!method self.mongocrypt_setopt_use_need_kms_credentials_state(crypt)
+      #   @api private
+      #
+      # Opt-into handling the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state.
+      #
+      # If set, before entering the MONGOCRYPT_CTX_NEED_KMS state,
+      # contexts may enter the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state
+      # and then wait for credentials to be supplied through
+      # `mongocrypt_ctx_provide_kms_providers`.
+      #
+      # A context will only enter MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS
+      # if an empty document was set for a KMS provider in
+      # `mongocrypt_setopt_kms_providers`.
+      #
+      # @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      attach_function(
+        :mongocrypt_setopt_use_need_kms_credentials_state,
+        [ :pointer ],
+        :void
+      )
+
+      # Opt-into handling the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state.
+      #
+      # If set, before entering the MONGOCRYPT_CTX_NEED_KMS state,
+      # contexts may enter the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state
+      # and then wait for credentials to be supplied through
+      # `mongocrypt_ctx_provide_kms_providers`.
+      #
+      # A context will only enter MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS
+      # if an empty document was set for a KMS provider in
+      # `mongocrypt_setopt_kms_providers`.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      def self.setopt_use_need_kms_credentials_state(handle)
+        mongocrypt_setopt_use_need_kms_credentials_state(handle.ref)
+      end
+
+      # @!method self.mongocrypt_ctx_provide_kms_providers(ctx, kms_providers)
+      #   @api private
+      #
+      # Call in response to the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state
+      # to set per-context KMS provider settings. These follow the same format
+      # as `mongocrypt_setopt_kms_providers``. If no keys are present in the
+      # BSON input, the KMS provider settings configured for the mongocrypt_t
+      # at initialization are used.
+      #
+      # @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      # @param [ FFI::Pointer ] kms_providers A pointer to a
+      #   mongocrypt_binary_t object that references a BSON document mapping
+      #   the KMS provider names to credentials.
+      #
+      # @returns [ true | false ] Returns whether the options was set successfully.
+      attach_function(
+        :mongocrypt_ctx_provide_kms_providers,
+        [ :pointer, :pointer ],
+        :bool
+      )
+
+      # Call in response to the MONGOCRYPT_CTX_NEED_KMS_CREDENTIALS state
+      # to set per-context KMS provider settings. These follow the same format
+      # as `mongocrypt_setopt_kms_providers``. If no keys are present in the
+      # BSON input, the KMS provider settings configured for the mongocrypt_t
+      # at initialization are used.
+      #
+      # @param [ Mongo::Crypt::Context ] context Encryption context.
+      # @param [ BSON::Document ] kms_providers BSON document mapping
+      #   the KMS provider names to credentials.
+      #
+      # @raise [ Mongo::Error::CryptError ] If the option is not set successfully.
+      def self.ctx_provide_kms_providers(context, kms_providers)
+        validate_document(kms_providers)
+        data = kms_providers.to_bson.to_s
+        Binary.wrap_string(data) do |data_p|
+          check_ctx_status(context) do
+            mongocrypt_ctx_provide_kms_providers(context.ctx_p, data_p)
+          end
+        end
+      end
+
+      # @!method self.mongocrypt_ctx_setopt_query_type(ctx, mongocrypt_query_type)
+      #   @api private
+      #
+      # Set the query type to use for FLE 2 explicit encryption.
+      # The query type is only used for indexed FLE 2 encryption.
+      #
+      # @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      # @param [ String ] query_type Type of the query.
+      # @param [ Integer ] len The length of the query type string.
+      #
+      # @return [ Boolean ] Whether setting this option succeeded.
+      attach_function(
+        :mongocrypt_ctx_setopt_query_type,
+        [
+          :pointer,
+          :string,
+          :int
+        ],
+        :bool
+      )
+
+      # Set the query type to use for FLE 2 explicit encryption.
+      # The query type is only used for indexed FLE 2 encryption.
+      #
+      # @param [ Mongo::Crypt::Context ] context Explicit encryption context.
+      # @param [ String ] :mongocrypt_query_type query_type Type of the query.
+      #
+      # @raise [ Mongo::Error::CryptError ] If the operation failed.
+      def self.ctx_setopt_query_type(context, query_type)
+        check_ctx_status(context) do
+          mongocrypt_ctx_setopt_query_type(context.ctx_p, query_type, -1)
+        end
+      end
+
+      # @!method self.mongocrypt_ctx_setopt_contention_factor(ctx, contention_factor)
+      #   @api private
+      #
+      # Set the contention factor used for explicit encryption.
+      # The contention factor is only used for indexed FLE 2 encryption.
+      #
+      # @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      # @param [ int64 ] contention_factor
+      #
+      # @return [ Boolean ] Whether setting this option succeeded.
+      attach_function(
+        :mongocrypt_ctx_setopt_contention_factor,
+        [
+          :pointer,
+          :int64
+        ],
+        :bool
+      )
+
+      # Set the contention factor used for explicit encryption.
+      # The contention factor is only used for indexed FLE 2 encryption.
+      #
+      # @param [ Mongo::Crypt::Context ] context Explicit encryption context.
+      # @param [ Integer ] factor Contention factor used for explicit encryption.
+      #
+      # @raise [ Mongo::Error::CryptError ] If the operation failed.
+      def self.ctx_setopt_contention_factor(context, factor)
+        check_ctx_status(context) do
+          mongocrypt_ctx_setopt_contention_factor(context.ctx_p, factor)
+        end
+      end
+
+      # @!method self.mongocrypt_ctx_setopt_algorithm_range(ctx, opts)
+      #   @api private
+      #
+      # Set options for explicit encryption with the "rangePreview" algorithm.
+      #
+      # @note The RangePreview algorithm is experimental only. It is not intended for
+      # public use.
+      #
+      # @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      # @param [ FFI::Pointer ] opts opts A pointer to range
+      #   options document.
+      #
+      # @return [ Boolean ] Whether setting this option succeeded.
+      attach_function(
+        :mongocrypt_ctx_setopt_algorithm_range,
+        [
+          :pointer,
+          :pointer
+        ],
+        :bool
+      )
+
+      # Set options for explicit encryption with the "rangePreview" algorithm.
+      #
+      # @note The RangePreview algorithm is experimental only. It is not intended for
+      # public use.
+      #
+      # @param [ Mongo::Crypt::Context ] context
+      # @param [ Hash ] opts options
+      #
+      # @raise [ Mongo::Error::CryptError ] If the operation failed
+      def self.ctx_setopt_algorithm_range(context, opts)
+        validate_document(opts)
+        data = opts.to_bson.to_s
+        Binary.wrap_string(data) do |data_p|
+          check_ctx_status(context) do
+            mongocrypt_ctx_setopt_algorithm_range(context.ctx_p, data_p)
+          end
+        end
+      end
+
       # Raise a Mongo::Error::CryptError based on the status of the underlying
       # mongocrypt_t object.
       #