mongo 2.24.1 → 2.26.0

data/lib/mongo/crypt/binding.rb

@@ -81,7 +81,7 @@ module Mongo
       # will cause a `LoadError`.
       #
       # @api private
-      MIN_LIBMONGOCRYPT_VERSION = Gem::Version.new('1.12.0')
+      MIN_LIBMONGOCRYPT_VERSION = Gem::Version.new('1.20.0')
 
       # @!method self.mongocrypt_version(len)
       #   @api private
@@ -106,7 +106,7 @@ module Mongo
       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/)
+        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(
@@ -823,14 +823,15 @@ 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,
-        :need_kms_credentials,  7,
+        :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,
+        :need_mongo_collinfo_with_db,  8,
       ]
 
       # @!method self.mongocrypt_ctx_state(ctx)
@@ -1105,10 +1106,20 @@ module Mongo
       def self.check_kms_ctx_status(kms_context)
         return if yield
 
+        kms_ctx_status(kms_context).raise_crypt_error(kms: true)
+      end
+
+      # Read the status information for the given KmsContext into a Status
+      # object without raising.
+      #
+      # @param [ Mongo::Crypt::KmsContext ] kms_context
+      #
+      # @return [ Mongo::Crypt::Status ] The KMS context status.
+      def self.kms_ctx_status(kms_context)
         status = Status.new
 
         mongocrypt_kms_ctx_status(kms_context.kms_ctx_p, status.ref)
-        status.raise_crypt_error(kms: true)
+        status
       end
 
       # @!method self.mongocrypt_kms_ctx_usleep(ctx)
@@ -1468,6 +1479,31 @@ module Mongo
         mongocrypt_setopt_bypass_query_analysis(handle.ref)
       end
 
+      # @!method self.mongocrypt_setopt_key_expiration(crypt, cache_expiration_ms)
+      #   @api private
+      #
+      #   Set the expiration time for the data encryption key cache.
+      #
+      #   @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      #   @param [ Integer ] cache_expiration_ms The cache expiration time in
+      #     milliseconds. If zero, the cache never expires.
+      #   @return [ Boolean ] Returns whether the option was set successfully.
+      attach_function(:mongocrypt_setopt_key_expiration, %i[pointer uint64], :bool)
+
+      # Set the expiration time for the data encryption key cache on the
+      # Mongo::Crypt::Handle object.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      # @param [ Integer ] cache_expiration_ms The cache expiration time in
+      #   milliseconds. If zero, the cache never expires.
+      #
+      # @raise [ Mongo::Error::CryptError ] If the option is not set successfully.
+      def self.setopt_key_expiration(handle, cache_expiration_ms)
+        check_status(handle) do
+          mongocrypt_setopt_key_expiration(handle.ref, cache_expiration_ms)
+        end
+      end
+
       # @!method self.mongocrypt_setopt_aes_256_ctr(crypt, aes_256_ctr_encrypt, aes_256_ctr_decrypt, ctx)
       #   @api private
       #
@@ -1646,6 +1682,73 @@ module Mongo
         mongocrypt_setopt_use_need_kms_credentials_state(handle.ref)
       end
 
+      # @!method self.mongocrypt_setopt_enable_multiple_collinfo(crypt)
+      #   @api private
+      #
+      # Enable support for multiple collection schemas. Required to support $lookup.
+      #
+      # @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      # @pre mongocrypt_init has not been called on crypt.
+      # @return [ Boolean ] Whether the option was set successfully.
+      attach_function(
+        :mongocrypt_setopt_enable_multiple_collinfo,
+        [ :pointer ],
+        :bool
+      )
+
+      # Enable support for multiple collection schemas. Required to support $lookup.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      # @return [ Boolean ] Whether the option was set successfully.
+      def self.setopt_enable_multiple_collinfo(handle)
+        check_status(handle) do
+          mongocrypt_setopt_enable_multiple_collinfo(handle.ref)
+        end
+      end
+
+      # @!method self.mongocrypt_setopt_use_need_mongo_collinfo_with_db_state(crypt)
+      #   @api private
+      #
+      # Opt into handling the MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state.
+      # A context enters this state when processing a bulkWrite command whose
+      # target database differs from the command database ("admin").
+      #
+      # @param [ FFI::Pointer ] crypt A pointer to a mongocrypt_t object.
+      attach_function(
+        :mongocrypt_setopt_use_need_mongo_collinfo_with_db_state,
+        [ :pointer ],
+        :void
+      )
+
+      # Opt into handling the MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state.
+      #
+      # @param [ Mongo::Crypt::Handle ] handle
+      def self.setopt_use_need_mongo_collinfo_with_db_state(handle)
+        mongocrypt_setopt_use_need_mongo_collinfo_with_db_state(handle.ref)
+      end
+
+      # @!method self.mongocrypt_ctx_mongo_db(ctx)
+      #   @api private
+      #
+      # Get the database name for the current collinfo operation. Used in the
+      # MONGOCRYPT_CTX_NEED_MONGO_COLLINFO_WITH_DB state to determine which
+      # database to run listCollections against.
+      #
+      # @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      # @return [ String, nil ] The database name, or nil on error.
+      attach_function :mongocrypt_ctx_mongo_db, [ :pointer ], :string
+
+      # Get the database name for the current collinfo operation.
+      #
+      # @param [ Mongo::Crypt::Context ] context
+      # @return [ String ] The database name.
+      def self.ctx_mongo_db(context)
+        db_name = mongocrypt_ctx_mongo_db(context.ctx_p)
+        return db_name if db_name
+
+        check_ctx_status(context)
+      end
+
       # @!method self.mongocrypt_ctx_provide_kms_providers(ctx, kms_providers)
       #   @api private
       #
@@ -1795,6 +1898,46 @@ module Mongo
         end
       end
 
+      # @!method self.mongocrypt_ctx_setopt_algorithm_text(ctx, opts)
+      #   @api private
+      #
+      # Set options for explicit encryption with the "String" algorithm.
+      #
+      # @note The libmongocrypt C function is named `..._algorithm_text` (the
+      #   original "text" name), even though the algorithm string passed to
+      #   mongocrypt_ctx_setopt_algorithm is "String" (renamed for GA). There is
+      #   no `..._algorithm_string` symbol; `..._algorithm_text` is the correct
+      #   and only setter for these options.
+      #
+      # @param [ FFI::Pointer ] ctx A pointer to a mongocrypt_ctx_t object.
+      # @param [ FFI::Pointer ] opts A pointer to a string options document.
+      #
+      # @return [ Boolean ] Whether setting this option succeeded.
+      attach_function(
+        :mongocrypt_ctx_setopt_algorithm_text,
+        %i[
+          pointer
+          pointer
+        ],
+        :bool
+      )
+
+      # Set options for explicit encryption with the "String" algorithm.
+      #
+      # @param [ Mongo::Crypt::Context ] context
+      # @param [ Hash ] opts options
+      #
+      # @raise [ Mongo::Error::CryptError ] If the operation failed
+      def self.ctx_setopt_algorithm_text(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_text(context.ctx_p, data_p)
+          end
+        end
+      end
+
       # Raise a Mongo::Error::CryptError based on the status of the underlying
       # mongocrypt_t object.
       #

data/lib/mongo/crypt/context.rb

@@ -76,7 +76,7 @@ module Mongo
       # This method is not currently unit tested. It is integration tested
       # in spec/integration/explicit_encryption_spec.rb
       def run_state_machine(timeout_holder)
-        while true
+        loop do
           timeout_ms = timeout_holder.remaining_timeout_ms!
           case state
           when :error
@@ -90,6 +90,8 @@ module Mongo
             provide_keys(timeout_ms)
           when :need_mongo_collinfo
             provide_collection_info(timeout_ms)
+          when :need_mongo_collinfo_with_db
+            provide_collection_info_with_db(timeout_ms)
           when :need_mongo_markings
             provide_markings(timeout_ms)
           when :need_kms
@@ -122,17 +124,26 @@ module Mongo
       def provide_markings(timeout_ms)
         cmd = Binding.ctx_mongo_op(self)
 
-        result = @encryption_io.mark_command(cmd, timeout_ms: timeout_ms)
+        result = @encryption_io.mark_command(cmd, db_name: @db_name, timeout_ms: timeout_ms)
         mongocrypt_feed(result)
 
         mongocrypt_done
       end
 
       def provide_collection_info(timeout_ms)
+        feed_collection_info(@db_name, timeout_ms)
+      end
+
+      def provide_collection_info_with_db(timeout_ms)
+        feed_collection_info(Binding.ctx_mongo_db(self), timeout_ms)
+      end
+
+      def feed_collection_info(db_name, timeout_ms)
         filter = Binding.ctx_mongo_op(self)
 
-        result = @encryption_io.collection_info(@db_name, filter, timeout_ms: timeout_ms)
-        mongocrypt_feed(result) if result
+        @encryption_io.collection_info(db_name, filter, timeout_ms: timeout_ms).each do |result|
+          mongocrypt_feed(result)
+        end
 
         mongocrypt_done
       end
@@ -159,12 +170,29 @@ module Mongo
             raise unless e.network_error?
             next if Binding.kms_ctx_fail(kms_context)
 
-            raise
+            raise_kms_retry_error(kms_context, e)
           end
         end
         Binding.ctx_kms_done(self)
       end
 
+      # Raise a KmsError that wraps the KMS status message (which describes the
+      # retry exhaustion) with the error from the last attempt.
+      #
+      # @param [ Mongo::Crypt::KmsContext ] kms_context
+      # @param [ Mongo::Error::KmsError ] last_error The error from the last
+      #   KMS request attempt.
+      #
+      # @raise [ Mongo::Error::KmsError ]
+      def raise_kms_retry_error(kms_context, last_error)
+        status = Binding.kms_ctx_status(kms_context)
+        raise Error::KmsError.new(
+          "#{status.message}, last attempt failed with: #{last_error.message}",
+          code: status.code,
+          network_error: true
+        )
+      end
+
       # Indicate that state machine is done feeding I/O responses back to libmongocrypt
       def mongocrypt_done
         Binding.mongocrypt_ctx_mongo_done(ctx_p)
@@ -188,21 +216,24 @@ module Mongo
       #   KMS providers.
       def retrieve_kms_credentials(timeout_holder)
         providers = {}
-        if kms_providers.aws && kms_providers.aws.empty?
-          begin
-            aws_credentials = Mongo::Auth::Aws::CredentialsRetriever.new.credentials(timeout_holder)
-          rescue Auth::Aws::CredentialsNotFound
-            raise Error::CryptError.new(
-              'Could not locate AWS credentials (checked environment variables, ECS and EC2 metadata)'
-            )
+        kms_providers.credentials_map.each do |identifier, creds|
+          next unless creds.empty?
+
+          case KMS.provider_base_type(identifier)
+          when 'aws'
+            begin
+              aws_credentials = Mongo::Auth::Aws::CredentialsRetriever.new.credentials(timeout_holder)
+            rescue Auth::Aws::CredentialsNotFound
+              raise Error::CryptError.new(
+                'Could not locate AWS credentials (checked environment variables, ECS and EC2 metadata)'
+              )
+            end
+            providers[identifier] = aws_credentials.to_h
+          when 'gcp'
+            providers[identifier] = { access_token: gcp_access_token(timeout_holder) }
+          when 'azure'
+            providers[identifier] = { access_token: azure_access_token(timeout_holder) }
           end
-          providers[:aws] = aws_credentials.to_h
-        end
-        if kms_providers.gcp && kms_providers.gcp.empty?
-          providers[:gcp] = { access_token: gcp_access_token(timeout_holder) }
-        end
-        if kms_providers.azure && kms_providers.azure.empty?
-          providers[:azure] = { access_token: azure_access_token(timeout_holder) }
         end
         KMS::Credentials.new(providers)
       end

data/lib/mongo/crypt/encryption_io.rb

@@ -97,7 +97,7 @@ module Mongo
       #    Must be a non-negative integer. An explicit value of 0 means infinite.
       #    The default value is unset which means the feature is not enabled.
       #
-      # @return [ Hash ] The collection information
+      # @return [ Array<BSON::Document> ] The collection information documents
       def collection_info(db_name, filter, timeout_ms: nil)
         unless @metadata_client
           raise ArgumentError,
@@ -108,18 +108,22 @@ module Mongo
           .use(db_name)
           .database
           .list_collections(filter: filter, deserialize_as_bson: true, timeout_ms: timeout_ms)
-          .first
+          .to_a
       end
 
       # Send the command to mongocryptd to be marked with intent-to-encrypt markings
       #
       # @param [ Hash ] cmd
+      # @param [ String | nil ] :db_name The database against which the command
+      #   is being run. When provided, the command is sent to mongocryptd using
+      #   this database so that the namespace in the command matches the namespace
+      #   in encryptionInformation.
       # @param [ Integer ] :timeout_ms The operation timeout in milliseconds.
       #    Must be a non-negative integer. An explicit value of 0 means infinite.
       #    The default value is unset which means the feature is not enabled.
       #
       # @return [ Hash ] The marked command
-      def mark_command(cmd, timeout_ms: nil)
+      def mark_command(cmd, db_name: nil, timeout_ms: nil)
         unless @mongocryptd_client
           raise ArgumentError,
                 'mark_command requires mongocryptd_client to have been passed to the constructor, but it was not'
@@ -132,13 +136,15 @@ module Mongo
           timeout_ms: timeout_ms
         }
 
+        mongocryptd = db_name ? @mongocryptd_client.use(db_name) : @mongocryptd_client
+
         begin
-          response = @mongocryptd_client.database.command(cmd, options)
+          response = mongocryptd.database.command(cmd, options)
         rescue Error::NoServerAvailable => e
           raise e if @options[:mongocryptd_bypass_spawn]
 
           spawn_mongocryptd
-          response = @mongocryptd_client.database.command(cmd, options)
+          response = mongocryptd.database.command(cmd, options)
         end
 
         response.first

data/lib/mongo/crypt/explicit_encrypter.rb

@@ -37,12 +37,19 @@ module Mongo
       #   to TLS connection options of Mongo::Client.
       # @param [ Integer | nil ] timeout_ms Timeout for every operation executed
       #   on this object.
-      def initialize(key_vault_client, key_vault_namespace, kms_providers, kms_tls_options, timeout_ms = nil)
+      # @param [ Integer | nil ] key_expiration_ms The lifetime of the data
+      #   encryption key cache, in milliseconds. A value of 0 means the cache
+      #   never expires. When nil, libmongocrypt's default of 60000 is used.
+      def initialize(
+        key_vault_client, key_vault_namespace, kms_providers, kms_tls_options,
+        timeout_ms = nil, key_expiration_ms = nil
+      )
         Crypt.validate_ffi!
         @crypt_handle = Handle.new(
           kms_providers,
           kms_tls_options,
-          explicit_encryption_only: true
+          explicit_encryption_only: true,
+          key_expiration_ms: key_expiration_ms
         )
         @encryption_io = EncryptionIO.new(
           key_vault_client: key_vault_client,
@@ -93,23 +100,31 @@ module Mongo
       #   encryption key.
       # @option options [ String ] :algorithm The algorithm used to encrypt the value.
       #   Valid algorithms are "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
-      #   "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed".
+      #   "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed",
+      #   "Range", "String".
       # @option options [ Integer | nil ] :contention_factor Contention factor
-      #   to be applied if encryption algorithm is set to "Indexed". If not
-      #   provided, it defaults to a value of 0. Contention factor should be set
-      #   only if encryption algorithm is set to "Indexed".
-      # @option options [ String | nil ] query_type Query type to be applied
-      # if encryption algorithm is set to "Indexed". Query type should be set
-      #   only if encryption algorithm is set to "Indexed". The only allowed
-      #   value is "equality".
+      #   to be applied if encryption algorithm is set to "Indexed", "Range", or
+      #   "String". If not provided, it defaults to a value of 0. Contention
+      #   factor should be set only if encryption algorithm is set to "Indexed",
+      #   "Range", or "String".
+      # @option options [ String | nil ] :query_type Query type to be applied
+      #   if encryption algorithm is set to "Indexed", "Range", or "String".
+      #   Allowed values are "equality" (for "Indexed"), "range" (for "Range"),
+      #   and "prefix", "suffix", "substring" (for "String").
+      # @option options [ Hash | nil ] :range_opts Specifies index options for a
+      #   Queryable Encryption field supporting "range" queries. Required when
+      #   algorithm is "Range".
+      # @option options [ Hash | nil ] :string_opts Specifies index options for a
+      #   Queryable Encryption field supporting "prefix", "suffix", or
+      #   "substring" queries. Required when algorithm is "String".
       #
       # @note The :key_id and :key_alt_name options are mutually exclusive. Only
       #   one is required to perform explicit encryption.
       #
       # @return [ BSON::Binary ] A BSON Binary object of subtype 6 (ciphertext)
       #   representing the encrypted value
-      # @raise [ ArgumentError ] if either contention_factor or query_type
-      #   is set, and algorithm is not "Indexed".
+      # @raise [ ArgumentError ] if either contention_factor or query_type is
+      #   set, and algorithm is not "Indexed", "Range", or "String".
       def encrypt(value, options)
         Crypt::ExplicitEncryptionContext.new(
           @crypt_handle,

data/lib/mongo/crypt/explicit_encryption_context.rb

@@ -36,14 +36,16 @@ module Mongo
       #   that will be used to encrypt the value.
       # @option options [ String ] :algorithm The algorithm used to encrypt the
       #   value. Valid algorithms are "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic",
-      #   "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed", "Range".
+      #   "AEAD_AES_256_CBC_HMAC_SHA_512-Random", "Indexed", "Unindexed", "Range",
+      #   "String".
       # @option options [ Integer | nil ] :contention_factor Contention factor
-      #   to be applied if encryption algorithm is set to "Indexed". If not
-      #   provided, it defaults to a value of 0. Contention factor should be set
-      #   only if encryption algorithm is set to "Indexed".
+      #   to be applied if encryption algorithm is set to "Indexed", "Range", or "String".
+      #   If not provided, it defaults to a value of 0. Contention factor should be set
+      #   only if encryption algorithm is set to "Indexed", "Range", or "String".
       # @option options [ String | nil ] query_type Query type to be applied
-      #   if encryption algorithm is set to "Indexed" or "Range".
-      #   Allowed values are "equality" and "range".
+      #   if encryption algorithm is set to "Indexed", "Range", or "String".
+      #   Allowed values are "equality", "range", "prefix", "suffix", and
+      #   "substring".
       # @option options [ Hash | nil ] :range_opts Specifies index options for
       #   a Queryable Encryption field supporting "range" queries.
       #   Allowed options are:
@@ -56,9 +58,22 @@ module Mongo
       #   the encryptedFields of the destination collection.
       #   For double and decimal128, min/max/precision must all be set,
       #   or all be unset.
+      # @option options [ Hash | nil ] :string_opts Specifies index options for
+      #   a Queryable Encryption field supporting "prefix", "suffix", or
+      #   "substring" queries (algorithm "String"). Allowed options are:
+      #   - :case_sensitive
+      #   - :diacritic_sensitive
+      #   - :prefix (Hash with :str_min_query_length, :str_max_query_length)
+      #   - :suffix (Hash with :str_min_query_length, :str_max_query_length)
+      #   - :substring (Hash with :str_max_length, :str_min_query_length,
+      #     :str_max_query_length)
+      #   The options must match the values set in the encryptedFields of the
+      #   destination collection.
       #
       # @note The Range algorithm is experimental only. It is not intended for
       # public use.
+      # @note The "substring" query type is unstable and subject to backwards
+      # breaking changes.
       #
       # @raise [ ArgumentError|Mongo::Error::CryptError ] If invalid options are provided
       def initialize(mongocrypt, io, doc, options = {})
@@ -114,28 +129,52 @@ module Mongo
 
       def set_algorithm_opts(options)
         Binding.ctx_setopt_algorithm(self, options[:algorithm])
-        if %w[Indexed Range].include?(options[:algorithm])
+        if %w[Indexed Range String].include?(options[:algorithm])
           Binding.ctx_setopt_contention_factor(self, options[:contention_factor]) if options[:contention_factor]
           Binding.ctx_setopt_query_type(self, options[:query_type]) if options[:query_type]
         else
           if options[:contention_factor]
-            raise ArgumentError.new(':contention_factor is allowed only for "Indexed" or "Range" algorithms')
+            raise ArgumentError.new(':contention_factor is allowed only for "Indexed", "Range", or "String" algorithms')
           end
           if options[:query_type]
-            raise ArgumentError.new(':query_type is allowed only for "Indexed" or "Range" algorithms')
+            raise ArgumentError.new(':query_type is allowed only for "Indexed", "Range", or "String" algorithms')
           end
         end
-        return unless options[:algorithm] == 'Range'
-
-        Binding.ctx_setopt_algorithm_range(self, convert_range_opts(options[:range_opts]))
+        if options[:algorithm] == 'Range'
+          Binding.ctx_setopt_algorithm_range(self, convert_range_opts(options[:range_opts]))
+        elsif options[:algorithm] == 'String'
+          Binding.ctx_setopt_algorithm_text(self, convert_string_opts(options[:string_opts]))
+        end
       end
 
       def convert_range_opts(range_opts)
+        raise ArgumentError.new(':range_opts is required for the "Range" algorithm') if range_opts.nil?
+
         range_opts.dup.tap do |opts|
           opts[:sparsity] = BSON::Int64.new(opts[:sparsity]) if opts[:sparsity] && !opts[:sparsity].is_a?(BSON::Int64)
           opts[:trimFactor] = opts.delete(:trim_factor) if opts[:trim_factor]
         end
       end
+
+      def convert_string_opts(string_opts)
+        raise ArgumentError.new(':string_opts is required for the "String" algorithm') if string_opts.nil?
+
+        string_opts.dup.tap do |opts|
+          opts[:caseSensitive] = opts.delete(:case_sensitive) if opts.key?(:case_sensitive)
+          opts[:diacriticSensitive] = opts.delete(:diacritic_sensitive) if opts.key?(:diacritic_sensitive)
+          %i[substring prefix suffix].each do |query_type|
+            opts[query_type] = convert_string_query_opts(opts[query_type]) if opts[query_type]
+          end
+        end
+      end
+
+      def convert_string_query_opts(query_opts)
+        query_opts.dup.tap do |opts|
+          opts[:strMaxLength] = opts.delete(:str_max_length) if opts.key?(:str_max_length)
+          opts[:strMinQueryLength] = opts.delete(:str_min_query_length) if opts.key?(:str_min_query_length)
+          opts[:strMaxQueryLength] = opts.delete(:str_max_query_length) if opts.key?(:str_max_query_length)
+        end
+      end
     end
   end
 end

data/lib/mongo/crypt/handle.rb

@@ -66,6 +66,10 @@ module Mongo
       #   error that libmongocrypt raises on a subsequent "$SYSTEM" search.
       # @option options [ Logger ] :logger A Logger object to which libmongocrypt logs
       #   will be sent
+      # @option options [ Integer | nil ] :key_expiration_ms The lifetime of the
+      #   data encryption key cache, in milliseconds. A value of 0 means the
+      #   cache never expires. When nil, libmongocrypt's default of 60000 is
+      #   used.
       def initialize(kms_providers, kms_tls_options, options = {})
         # FFI::AutoPointer uses a custom release strategy to automatically free
         # the pointer once this object goes out of scope
@@ -74,6 +78,8 @@ module Mongo
           Binding.method(:mongocrypt_destroy)
         )
         Binding.kms_ctx_setopt_retry_kms(self, true)
+        Binding.setopt_enable_multiple_collinfo(self)
+        Binding.setopt_use_need_mongo_collinfo_with_db_state(self)
         @kms_providers = kms_providers
         @kms_tls_options = kms_tls_options
 
@@ -85,6 +91,9 @@ module Mongo
         @bypass_query_analysis = options[:bypass_query_analysis]
         set_bypass_query_analysis if @bypass_query_analysis
 
+        @key_expiration_ms = options[:key_expiration_ms]
+        set_key_expiration unless @key_expiration_ms.nil?
+
         @crypt_shared_lib_path = options[:crypt_shared_lib_path]
         @explicit_encryption_only = options[:explicit_encryption_only]
         @disable_crypt_shared_lib_search = options[:disable_crypt_shared_lib_search]
@@ -101,7 +110,7 @@ module Mongo
 
         Binding.setopt_kms_providers(self, @kms_providers.to_document)
 
-        if @kms_providers.aws&.empty? || @kms_providers.gcp&.empty? || @kms_providers.azure&.empty?
+        if @kms_providers.any_on_demand?
           Binding.setopt_use_need_kms_credentials_state(self)
         end
 
@@ -123,13 +132,23 @@ module Mongo
       end
 
       # Return TLS options for KMS provider. If there are no TLS options set,
-      # empty hash is returned.
+      # empty hash is returned. Named providers (e.g. "kmip:name1") fall back
+      # to the base-type options (e.g. :kmip) when no exact match is found.
       #
-      # @param [ String ] provider KSM provider name.
+      # @param [ String ] provider KMS provider name or named identifier.
       #
       # @return [ Hash ] TLS options to connect to KMS provider.
       def kms_tls_options(provider)
-        @kms_tls_options.fetch(provider, {})
+        provider_str = provider.to_s
+        base_type = KMS.provider_base_type(provider_str)
+
+        @kms_tls_options.fetch(provider_str) do
+          @kms_tls_options.fetch(provider_str.to_sym) do
+            @kms_tls_options.fetch(base_type) do
+              @kms_tls_options.fetch(base_type.to_sym, {})
+            end
+          end
+        end
       end
 
       def crypt_shared_lib_version
@@ -188,10 +207,21 @@ module Mongo
         Binding.setopt_bypass_query_analysis(self) if @bypass_query_analysis
       end
 
+      def set_key_expiration
+        unless @key_expiration_ms.is_a?(Integer) && !@key_expiration_ms.negative?
+          raise ArgumentError.new(
+            "#{@key_expiration_ms} is an invalid key_expiration_ms value; " \
+            'must be a non-negative Integer or nil'
+          )
+        end
+
+        Binding.setopt_key_expiration(self, @key_expiration_ms)
+      end
+
       # Send the logs from libmongocrypt to the Mongo::Logger
       def set_logger_callback
         @log_callback = proc do |level, msg|
-          @logger.send(level, msg)
+          @logger.public_send(level, msg)
         end
 
         Binding.setopt_log_handler(@mongocrypt, @log_callback)