Class: Mongo::Crypt::Handle Private

Inherits:
Object
  • Object
show all
Defined in:
lib/mongo/crypt/handle.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

A handle to the libmongocrypt library that wraps a mongocrypt_t object, allowing clients to set options on that object or perform operations such as encryption and decryption

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(kms_providers, kms_tls_options, options = {}) ⇒ Handle

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a new Handle object and initializes it with options

Parameters:

  • kms_providers (Crypt::KMS::Credentials) —

    Credentials for KMS providers.

  • kms_tls_options (Hash) —

    TLS options to connect to KMS providers. Keys of the hash should be KSM provider names; values should be hashes of TLS connection options. The options are equivalent to TLS connection options of Mongo::Client.

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

    A hash of options.

Options Hash (options):

  • :schema_map (Hash | nil) —

    A hash representing the JSON schema of the collection that stores auto encrypted documents. This option is mutually exclusive with :schema_map_path.

  • :schema_map_path (String | nil) —

    A path to a file contains the JSON schema of the collection that stores auto encrypted documents. This option is mutually exclusive with :schema_map.

  • :encrypted_fields_map (Hash | nil) —

    maps a collection namespace to an encryptedFields.

    • Note: If a collection is present on both the encryptedFieldsMap and schemaMap, an error will be raised.
  • :bypass_query_analysis (Boolean | nil) —

    When true disables automatic analysis of outgoing commands.

  • :crypt_shared_lib_path (String | nil) —

    Path that should be the used to load the crypt shared library. Providing this option overrides default crypt shared library load paths for libmongocrypt.

  • :crypt_shared_lib_required (Boolean | nil) —

    Whether crypt_shared library is required. If 'true', an error will be raised if a crypt_shared library cannot be loaded by libmongocrypt.

  • :explicit_encryption_only (Boolean | nil) —

    Whether this handle is going to be used only for explicit encryption. If true, libmongocrypt is instructed not to load crypt shared library.

  • :disable_crypt_shared_lib_search (Boolean | nil) —

    When true, suppresses the automatic "$SYSTEM" search for crypt_shared. Use this when a previous Handle in the same process has already loaded the library via a path override and you want to avoid the conflicting-load error that libmongocrypt raises on a subsequent "$SYSTEM" search.

  • :logger (Logger) —

    A Logger object to which libmongocrypt logs will be sent

  • :key_expiration_ms (Integer | nil) —

    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.

Raises:



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/mongo/crypt/handle.rb', line 73

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
  @mongocrypt = FFI::AutoPointer.new(
    Binding.mongocrypt_new,
    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

  maybe_set_schema_map(options)

  @encrypted_fields_map = options[:encrypted_fields_map]
  set_encrypted_fields_map if @encrypted_fields_map

  @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]
  if @crypt_shared_lib_path
    Binding.setopt_set_crypt_shared_lib_path_override(self, @crypt_shared_lib_path)
  elsif !@bypass_query_analysis && !@explicit_encryption_only && !@disable_crypt_shared_lib_search
    Binding.setopt_append_crypt_shared_lib_search_path(self, '$SYSTEM')
  end

  @logger = options[:logger]
  set_logger_callback if @logger

  set_crypto_hooks

  Binding.setopt_kms_providers(self, @kms_providers.to_document)

  if @kms_providers.any_on_demand?
    Binding.setopt_use_need_kms_credentials_state(self)
  end

  initialize_mongocrypt

  @crypt_shared_lib_required = !!options[:crypt_shared_lib_required]
  return unless @crypt_shared_lib_required && crypt_shared_lib_version == 0

  raise Mongo::Error::CryptError.new(
    'Crypt shared library is required, but cannot be loaded  according to libmongocrypt'
  )
end

Instance Attribute Details

#kms_providers ⇒ Crypt::KMS::Credentials (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns Credentials for KMS providers.

Returns:



29
30
31
 
# File 'lib/mongo/crypt/handle.rb', line 29

def kms_providers
  @kms_providers
end

Instance Method Details

#crypt_shared_lib_available? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


158
159
160
 
# File 'lib/mongo/crypt/handle.rb', line 158

def crypt_shared_lib_available?
  crypt_shared_lib_version != 0
end

#crypt_shared_lib_version ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



154
155
156
 
# File 'lib/mongo/crypt/handle.rb', line 154

def crypt_shared_lib_version
  Binding.crypt_shared_lib_version(self)
end

#kms_tls_options(provider) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return TLS options for KMS provider. If there are no TLS options set, 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.

Parameters:

  • provider (String) —

    KMS provider name or named identifier.

Returns:

  • (Hash) —

    TLS options to connect to KMS provider.



141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/mongo/crypt/handle.rb', line 141

def kms_tls_options(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

#ref ⇒ FFI::Pointer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Return the reference to the underlying @mongocrypt object

Returns:

  • (FFI::Pointer) 


130
131
132
 
# File 'lib/mongo/crypt/handle.rb', line 130

def ref
  @mongocrypt
end