123456789_123456789_123456789_123456789_123456789_

Class: Mongo::Crypt::ExplicitEncryptionContext Private

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
ExplicitEncryptionExpressionContext
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Context, Forwardable
Instance Chain:
self, Context
Inherits: Mongo::Crypt::Context
Defined in: lib/mongo/crypt/explicit_encryption_context.rb

Overview

A Context object initialized for explicit encryption

Class Method Summary

Context - Inherited

.new

Create a new Context object.

Instance Attribute Summary

Context - Inherited

#ctx_p

Instance Method Summary

Context - Inherited

#bson_mode

Which BSON mode to use when creating documents from the outcome of the state machine.
#run_state_machine

Runs the mongocrypt_ctx_t state machine and handles all I/O on behalf of.
#state

Returns the state of the mongocrypt_ctx_t.
#azure_access_token

Returns an Azure access token, retrieving it if necessary.
#feed_collection_info, #feed_kms,
#gcp_access_token

Retrieves a GCP access token.
#mongocrypt_done

Indicate that state machine is done feeding I/O responses back to libmongocrypt.
#mongocrypt_feed

Feeds the result of a ::Mongo operation back to libmongocrypt.
#provide_collection_info, #provide_collection_info_with_db, #provide_keys, #provide_markings,
#retrieve_kms_credentials

Retrieves KMS credentials for providers that are configured for automatic credentials retrieval.

Constructor Details

.new(mongocrypt, io, doc, options = {}) ⇒ ExplicitEncryptionContext

Note:

The Range algorithm is experimental only. It is not intended for

Create a new ExplicitEncryptionContext object

public use.

Parameters:

  • mongocrypt (Mongo::Crypt::Handle) —

    a Handle that wraps a mongocrypt_t object used to create a new mongocrypt_ctx_t

  • io (ClientEncryption::IO) —

    A instance of the IO class that implements driver I/O methods required to run the state machine

  • doc (BSON::Document) —

    A document to encrypt

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :key_id (BSON::Binary) —

    A BSON::Binary object of type :uuid representing the UUID of the data key to use for encryption.

  • :key_alt_name (String) —

    The alternate name of the data key that will be used to encrypt the value.

  • :algorithm (String) —

    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".

  • :contention_factor (Integer | nil) —

    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".

  • query_type (String | nil) —

    Query type to be applied if encryption algorithm is set to "Indexed" or "Range". Allowed values are "equality" and "range".

  • :range_opts (Hash | nil) —

    Specifies index options for a Queryable Encryption field supporting "range" queries. Allowed options are:

    • :min
    • :max
    • :trim_factor
    • :sparsity
    • :precision min, max, trim_factor, sparsity, and precision must match the values set in the encryptedFields of the destination collection. For double and decimal128, min/max/precision must all be set, or all be unset.

Raises:

[ GitHub ] 

  


# File 'lib/mongo/crypt/explicit_encryption_context.rb', line 64



def initialize(mongocrypt, io, doc, options = {})
  super(mongocrypt, io)
  set_key_opts(options)
  set_algorithm_opts(options)
  init(doc)
end


  







Instance Method Details



  

    #convert_range_opts(range_opts)   (private)
  

  [ GitHub ]


  

  


# File 'lib/mongo/crypt/explicit_encryption_context.rb', line 133



def convert_range_opts(range_opts)
  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


  








  

    #init(doc)  
  

  [ GitHub ]


  

  


# File 'lib/mongo/crypt/explicit_encryption_context.rb', line 71



def init(doc)
  Binding.ctx_explicit_encrypt_init(self, doc)
end


  








  

    #set_algorithm_opts(options)   (private)
  

  [ GitHub ]


  

  


# File 'lib/mongo/crypt/explicit_encryption_context.rb', line 115



def set_algorithm_opts(options)
  Binding.ctx_setopt_algorithm(self, options[:algorithm])
  if %w[Indexed Range].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')
    end
    if options[:query_type]
      raise ArgumentError.new(':query_type is allowed only for "Indexed" or "Range" algorithms')
    end
  end
  return unless options[:algorithm] == 'Range'

  Binding.ctx_setopt_algorithm_range(self, convert_range_opts(options[:range_opts]))
end


  








  

    #set_key_alt_name(key_alt_name)   (private)
  



  

    
  





  
Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongo/crypt/explicit_encryption_context.rb', line 109



def set_key_alt_name(key_alt_name)
  raise ArgumentError.new(':key_alt_name option must be a String') unless key_alt_name.is_a?(String)

  Binding.ctx_setopt_key_alt_names(self, [ key_alt_name ])
end


  








  

    #set_key_id(key_id)   (private)
  

  [ GitHub ]


  

  


# File 'lib/mongo/crypt/explicit_encryption_context.rb', line 98



def set_key_id(key_id)
  unless key_id.is_a?(BSON::Binary) &&
         key_id.type == :uuid
    raise ArgumentError.new(
      'Expected the :key_id option to be a BSON::Binary object with ' +
      "type :uuid. #{key_id} is an invalid :key_id option"
    )
  end
  Binding.ctx_setopt_key_id(self, key_id.data)
end


  








  

    #set_key_opts(options)   (private)
  

  [ GitHub ]


  

  


# File 'lib/mongo/crypt/explicit_encryption_context.rb', line 77



def set_key_opts(options)
  if options[:key_id].nil? && options[:key_alt_name].nil?
    raise ArgumentError.new(
      'The :key_id and :key_alt_name options cannot both be nil. ' +
      'Specify a :key_id option or :key_alt_name option (but not both)'
    )
  end
  if options[:key_id] && options[:key_alt_name]
    raise ArgumentError.new(
      'The :key_id and :key_alt_name options cannot both be present. ' +
      'Identify the data key by specifying its id with the :key_id ' +
      'option or specifying its alternate name with the :key_alt_name option'
    )
  end
  if options[:key_id]
    set_key_id(options[:key_id])
  elsif options[:key_alt_name]
    set_key_alt_name(options[:key_alt_name])
  end
end