Skip to content

Document Range and String algorithms in ClientEncryption#encrypt #3100

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
comandeo-mongo merged 2 commits into from
Aug 18, 2026
+40 −20
Merged

Document Range and String algorithms in ClientEncryption#encrypt #3100

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a8cc918
Document Range and String algorithms in ClientEncryption#encrypt
comandeo-mongo Aug 6, 2026
b26c78f
Fix typos
comandeo-mongo Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 22 additions & 10 deletions lib/mongo/client_encryption.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
#
Expand All @@ -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
Expand Down Expand Up @@ -161,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
Expand Down
28 changes: 18 additions & 10 deletions lib/mongo/crypt/explicit_encrypter.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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".
# @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,
Expand Down
Loading