Class: Mongo::Crypt::ExplicitEncrypter Private

Inherits:
Object
  • Object
show all
Defined in:
build/ruby-driver-v2.18/lib/mongo/crypt/explicit_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 ExplicitEncrypter is an object that performs explicit encryption operations and handles all associated options and instance variables.

Instance Method Summary collapse

Constructor Details

#initialize(key_vault_client, key_vault_namespace, kms_providers, kms_tls_options) ⇒ ExplicitEncrypter

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.

Create a new ExplicitEncrypter object.

Parameters:

  • key_vault_client (Mongo::Client)

    An instance of Mongo::Client to connect to the key vault collection.

  • key_vault_namespace (String)

    The namespace of the key vault collection in the format “db_name.collection_name”.

  • kms_providers (Crypt::KMS::Credentials)

    A hash of key management service configuration information.

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



38
39
40
41
42
43
44
45
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 38

def initialize(key_vault_client, key_vault_namespace, kms_providers, kms_tls_options)
  @crypt_handle = Handle.new(kms_providers, kms_tls_options)
  @encryption_io = EncryptionIO.new(
    key_vault_client: key_vault_client,
    metadata_client: nil,
    key_vault_namespace: key_vault_namespace,
  )
end

Instance Method Details

#add_key_alt_name(id, key_alt_name) ⇒ BSON::Document | nil

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.

Adds a key_alt_name for the key in the key vault collection with the given id.

Parameters:

  • id (BSON::Binary)

    Id of the key to add new key alt name.

  • key_alt_name (String)

    New key alt name to add.

Returns:

  • (BSON::Document | nil)

    Document describing the identified key before adding the key alt name, or nil if no such key.



133
134
135
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 133

def add_key_alt_name(id, key_alt_name)
  @encryption_io.add_key_alt_name(id, key_alt_name)
end

#create_and_insert_data_key(master_key_document, key_alt_names, key_material = nil) ⇒ BSON::Binary

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.

Generates a data key used for encryption/decryption and stores that key in the KMS collection. The generated key is encrypted with the KMS master key.

Parameters:

  • master_key_document (Mongo::Crypt::KMS::MasterKeyDocument)

    The master key document that contains master encryption key parameters.

  • key_alt_names (Array<String> | nil)

    An optional array of strings specifying alternate names for the new data key.

  • key_material (String | nil) (defaults to: nil)

    Optional 96 bytes to use as custom key material for the data key being created. If key_material option is given, the custom key material is used for encrypting and decrypting data.

Returns:

  • (BSON::Binary)

    The 16-byte UUID of the new data key as a BSON::Binary object with type :uuid.



62
63
64
65
66
67
68
69
70
71
72
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 62

def create_and_insert_data_key(master_key_document, key_alt_names, key_material = nil)
  data_key_document = Crypt::DataKeyContext.new(
    @crypt_handle,
    @encryption_io,
    master_key_document,
    key_alt_names,
    key_material
  ).run_state_machine

  @encryption_io.insert_data_key(data_key_document).inserted_id
end

#decrypt(value) ⇒ 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.

Decrypts a value that has already been encrypted

Parameters:

  • value (BSON::Binary)

    A BSON Binary object of subtype 6 (ciphertext) that will be decrypted

Returns:

  • (Object)

    The decrypted value



118
119
120
121
122
123
124
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 118

def decrypt(value)
  result = Crypt::ExplicitDecryptionContext.new(
    @crypt_handle,
    @encryption_io,
    { 'v': value },
  ).run_state_machine['v']
end

#delete_key(id) ⇒ Operation::Result

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.

Removes the key with the given id from the key vault collection.

Parameters:

  • id (BSON::Binary)

    Id of the key to delete.

Returns:

  • (Operation::Result)

    The response from the database for the delete_one operation that deletes the key.



143
144
145
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 143

def delete_key(id)
  @encryption_io.delete_key(id)
end

#encrypt(value, options) ⇒ BSON::Binary

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.

Note:

The :key_id and :key_alt_name options are mutually exclusive. Only one is required to perform explicit encryption.

Encrypts a value using the specified encryption key and algorithm

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

Parameters:

  • value (Object)

    The value to encrypt

  • options (Hash)

Options Hash (options):

  • :key_id (BSON::Binary)

    A BSON::Binary object of type :uuid representing the UUID of the encryption key as it is stored in the key vault collection.

  • :key_alt_name (String)

    The alternate name for the encryption key.

  • :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”.

  • :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

Returns:

  • (BSON::Binary)

    A BSON Binary object of subtype 6 (ciphertext) representing the encrypted value

Raises:

  • (ArgumentError)

    if either contention_factor or query_type is set, and algorithm is not “Indexed”.



103
104
105
106
107
108
109
110
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 103

def encrypt(value, options)
  Crypt::ExplicitEncryptionContext.new(
    @crypt_handle,
    @encryption_io,
    { 'v': value },
    options
  ).run_state_machine['v']
end

#get_key(id) ⇒ BSON::Document | nil

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.

Finds a single key with the given id.

Parameters:

  • id (BSON::Binary)

    Id of the key to get.

Returns:

  • (BSON::Document | nil)

    The found key document or nil if not found.



153
154
155
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 153

def get_key(id)
  @encryption_io.get_key(id)
end

#get_key_by_alt_name(key_alt_name) ⇒ BSON::Document | nil

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 a key in the key vault collection with the given key_alt_name.

Parameters:

  • key_alt_name (String)

    Key alt name to find a key.

Returns:

  • (BSON::Document | nil)

    The found key document or nil if not found.



163
164
165
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 163

def get_key_by_alt_name(key_alt_name)
  @encryption_io.get_key_by_alt_name(key_alt_name)
end

#get_keysCollection::View

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 all keys in the key vault collection.

Returns:



170
171
172
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 170

def get_keys
  @encryption_io.get_keys
end

#remove_key_alt_name(id, key_alt_name) ⇒ BSON::Document | nil

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.

Removes a key_alt_name from a key in the key vault collection with the given id.

Parameters:

  • id (BSON::Binary)

    Id of the key to remove key alt name.

  • key_alt_name (String)

    Key alt name to remove.

Returns:

  • (BSON::Document | nil)

    Document describing the identified key before removing the key alt name, or nil if no such key.



181
182
183
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 181

def remove_key_alt_name(id, key_alt_name)
  @encryption_io.remove_key_alt_name(id, key_alt_name)
end

#rewrap_many_data_key(filter, opts = {}) ⇒ Crypt::RewrapManyDataKeyResult

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.

Decrypts multiple data keys and (re-)encrypts them with a new master_key,

or with their current master_key if a new one is not given.

Parameters:

  • filter (Hash)

    Filter used to find keys to be updated.

  • options (Hash)

Returns:



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
# File 'build/ruby-driver-v2.18/lib/mongo/crypt/explicit_encrypter.rb', line 196

def rewrap_many_data_key(filter, opts = {})
  master_key_document = if opts[:provider]
    options = opts.dup
    provider = options.delete(:provider)
    KMS::MasterKeyDocument.new(provider, options)
  end

  rewrap_result = Crypt::RewrapManyDataKeyContext.new(
    @crypt_handle,
    @encryption_io,
    filter,
    master_key_document
  ).run_state_machine
  if rewrap_result.nil?
    return RewrapManyDataKeyResult.new(nil)
  end
  data_key_documents = rewrap_result.fetch('v')
  updates = data_key_documents.map do |doc|
    {
      update_one: {
        filter: { _id: doc[:_id] },
        update: {
          '$set' => {
            masterKey: doc[:masterKey],
            keyMaterial: doc[:keyMaterial]
          },
          '$currentDate' => { updateDate: true },
        },
      }
    }
  end
  RewrapManyDataKeyResult.new(
    @encryption_io.update_data_keys(updates)
  )
end