From a8cc9181b7ed902abd58efed34161baa8b8d76ab Mon Sep 17 00:00:00 2001 From: Dmitry Rybakov Date: Thu, 6 Aug 2026 13:13:02 +0200 Subject: [PATCH 1/2] Document Range and String algorithms in ClientEncryption#encrypt The docs for #encrypt still described only the Indexed and Unindexed algorithms, so Range was missing from the algorithm list, range_opts and string_opts were undocumented, and the @raise clause named the wrong set of algorithms. Also add the note the client-side encryption spec requires drivers to document: payloads produced by the Indexed, Range and String algorithms have to be inserted or queried through a client configured with :auto_encryption_options. Same fixes applied to ExplicitEncrypter#encrypt, which #encrypt delegates to. --- lib/mongo/client_encryption.rb | 30 +++++++++++++++++++-------- lib/mongo/crypt/explicit_encrypter.rb | 26 +++++++++++++++-------- 2 files changed, 38 insertions(+), 18 deletions(-) diff --git a/lib/mongo/client_encryption.rb b/lib/mongo/client_encryption.rb index b333c21109..2ba2821962 100644 --- a/lib/mongo/client_encryption.rb +++ b/lib/mongo/client_encryption.rb @@ -106,20 +106,32 @@ def create_data_key(kms_provider, options = {}) # 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", "String". + # "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" 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" or "String". + # 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 "String". Allowed values - # are "equality" (for "Indexed") and "prefix", "suffix", "substring" - # (for "String"). + # 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". Allowed options are :min, :max, :trim_factor, + # :sparsity, :precision. # @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". Allowed options are # :case_sensitive, :diacritic_sensitive, :prefix, :suffix, :substring. # + # @note The result of explicit encryption with the "Indexed", "Range", or + # "String" algorithm must be processed by the server to insert or query. + # To insert or query with such a payload, use a Mongo::Client configured + # with :auto_encryption_options. The :bypass_query_analysis option may be + # true; the :bypass_auto_encryption option must be false. + # # @note The "substring" query type is unstable and subject to backwards # breaking changes. # @@ -129,8 +141,8 @@ def create_data_key(kms_provider, options = {}) # @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 = {}) @encrypter.encrypt(value, options) end diff --git a/lib/mongo/crypt/explicit_encrypter.rb b/lib/mongo/crypt/explicit_encrypter.rb index 1536b9620a..f90dc65319 100644 --- a/lib/mongo/crypt/explicit_encrypter.rb +++ b/lib/mongo/crypt/explicit_encrypter.rb @@ -100,23 +100,31 @@ def create_and_insert_data_key(master_key_document, key_alt_names, key_material # 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". + # 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". Query type should be set - # only if encryption algorithm is set to "Indexed". The only allowed - # value is "equality". + # 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, From b26c78f98f8d3605df1748c0afd4d7edd63b4545 Mon Sep 17 00:00:00 2001 From: Dmitry Rybakov Date: Thu, 6 Aug 2026 13:26:58 +0200 Subject: [PATCH 2/2] Fix typos --- lib/mongo/client_encryption.rb | 2 +- lib/mongo/crypt/explicit_encrypter.rb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/mongo/client_encryption.rb b/lib/mongo/client_encryption.rb index 2ba2821962..9438c7e3dd 100644 --- a/lib/mongo/client_encryption.rb +++ b/lib/mongo/client_encryption.rb @@ -173,7 +173,7 @@ def encrypt(value, options = {}) # expression. The only allowed value is "Range" # @option options [ Integer | nil ] :contention_factor Contention factor # to be applied If not provided, it defaults to a value of 0. - # @option options [ String | nil ] query_type Query type to be applied. + # @option options [ String | nil ] :query_type Query type to be applied. # The only allowed value is "range". # # @note The :key_id and :key_alt_name options are mutually exclusive. Only diff --git a/lib/mongo/crypt/explicit_encrypter.rb b/lib/mongo/crypt/explicit_encrypter.rb index f90dc65319..f48de2a683 100644 --- a/lib/mongo/crypt/explicit_encrypter.rb +++ b/lib/mongo/crypt/explicit_encrypter.rb @@ -107,7 +107,7 @@ def create_and_insert_data_key(master_key_document, key_alt_names, key_material # "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 + # @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").