Class: Mongo::Crypt::AutoEncrypter Private

Inherits:
Object
  • Object
show all
Defined in:
build/ruby-driver-master/lib/mongo/crypt/auto_encrypter.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.

An AutoEcnrypter is an object that encapsulates the behavior of automatic encryption. It controls all resources associated with auto-encryption, including the libmongocrypt handle, key vault client object, mongocryptd client object, and encryption I/O.

The AutoEncrypter is kept as an instance on a Mongo::Client. Client objects with the same auto_encryption_options Hash may share AutoEncrypters.

Constant Summary collapse

DEFAULT_EXTRA_OPTIONS =

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

A Hash of default values for the :extra_options option

Options::Redacted.new({
  mongocryptd_uri: 'mongodb://localhost:27020',
  mongocryptd_bypass_spawn: false,
  mongocryptd_spawn_path: 'mongocryptd',
  mongocryptd_spawn_args: ['--idleShutdownTimeoutSecs=60'],
})

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ AutoEncrypter

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.

Set up encryption-related options and instance variables on the class that includes this module. Calls the same method on the Mongo::Crypt::Encrypter module.

Parameters:

  • options (Hash)

Options Hash (options):

  • :client (Mongo::Client)

    A client connected to the encrypted collection.

  • :key_vault_client (Mongo::Client | nil)

    A client connected to the MongoDB instance containing the encryption key vault; optional. If not provided, will default to :client option.

  • :key_vault_namespace (String)

    The namespace of the key vault in the format database.collection.

  • :schema_map (Hash | nil)

    The JSONSchema of the collection(s) with encrypted fields.

  • :bypass_auto_encryption (Boolean | nil)

    When true, disables auto-encryption. Default is false.

  • :extra_options (Hash | nil)

    Options related to spawning mongocryptd. These are set to default values if no option is passed in.

  • :kms_providers (Hash)

    A hash of key management service configuration information. @see Mongo::Crypt::KMS::Credentials for list of options for every supported provider. @note There may be more than one KMS provider specified.

  • :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. @see Mongo::Client#initialize for list of TLS options.

Raises:

  • (ArgumentError)

    If required options are missing or incorrectly formatted.



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
# File 'build/ruby-driver-master/lib/mongo/crypt/auto_encrypter.rb', line 77

def initialize(options)
  @options = set_default_options(options).freeze

  @crypt_handle = Crypt::Handle.new(
    Crypt::KMS::Credentials.new(@options[:kms_providers]),
    Crypt::KMS::Validations.validate_tls_options(@options[:kms_tls_options]),
    schema_map: @options[:schema_map]
  )

  @key_vault_client = @options[:key_vault_client]

  # Set server selection timeout to 1 to prevent the client waiting for a
  # long timeout before spawning mongocryptd
  @mongocryptd_client = Client.new(
    @options[:extra_options][:mongocryptd_uri],
    monitoring_io: @options[:client].options[:monitoring_io],
    server_selection_timeout: 10,
  )

  begin
    @encryption_io = EncryptionIO.new(
      client: @options[:client],
      mongocryptd_client: @mongocryptd_client,
      key_vault_namespace: @options[:key_vault_namespace],
      key_vault_client: @key_vault_client,
      mongocryptd_options: @options[:extra_options]
    )
  rescue
    begin
      @mongocryptd_client.close
    rescue => e
      log_warn("Error closing mongocryptd client in auto encrypter's constructor: #{e.class}: #{e}")
      # Drop this exception so that the original exception is raised
    end
    raise
  end
end

Instance Attribute Details

#key_vault_clientObject (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.



34
35
36
# File 'build/ruby-driver-master/lib/mongo/crypt/auto_encrypter.rb', line 34

def key_vault_client
  @key_vault_client
end

#mongocryptd_clientObject (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.



33
34
35
# File 'build/ruby-driver-master/lib/mongo/crypt/auto_encrypter.rb', line 33

def mongocryptd_client
  @mongocryptd_client
end

#optionsObject (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.



35
36
37
# File 'build/ruby-driver-master/lib/mongo/crypt/auto_encrypter.rb', line 35

def options
  @options
end

Instance Method Details

#closetrue

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.

Close the resources created by the AutoEncrypter.

Returns:

  • (true)

    Always true.



155
156
157
158
159
# File 'build/ruby-driver-master/lib/mongo/crypt/auto_encrypter.rb', line 155

def close
  @mongocryptd_client.close if @mongocryptd_client

  true
end

#decrypt(command) ⇒ BSON::Document

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.

Decrypt a database command.

Parameters:

  • command (Hash)

    The command with encrypted fields.

Returns:

  • (BSON::Document)

    The decrypted command.



144
145
146
147
148
149
150
# File 'build/ruby-driver-master/lib/mongo/crypt/auto_encrypter.rb', line 144

def decrypt(command)
  AutoDecryptionContext.new(
    @crypt_handle,
    @encryption_io,
    command
  ).run_state_machine
end

#encrypt(database_name, command) ⇒ BSON::Document

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.

Encrypt a database command.

Parameters:

  • database_name (String)

    The name of the database on which the command is being run.

  • command (Hash)

    The command to be encrypted.

Returns:

  • (BSON::Document)

    The encrypted command.



130
131
132
133
134
135
136
137
# File 'build/ruby-driver-master/lib/mongo/crypt/auto_encrypter.rb', line 130

def encrypt(database_name, command)
  AutoEncryptionContext.new(
    @crypt_handle,
    @encryption_io,
    database_name,
    command
  ).run_state_machine
end

#encrypt?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.

Whether this encrypter should perform encryption (returns false if the :bypass_auto_encryption option is set to true).

Returns:

  • (Boolean)

    Whether to perform encryption.



119
120
121
# File 'build/ruby-driver-master/lib/mongo/crypt/auto_encrypter.rb', line 119

def encrypt?
  !@options[:bypass_auto_encryption]
end