Class: Mongo::Crypt::ExplicitEncrypter Private

Inherits:
Object
  • Object
show all
Defined in:
build/ruby-driver-master/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) ⇒ 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”.

  • options (Hash)

    a customizable set of options



35
36
37
38
39
40
41
42
# File 'build/ruby-driver-master/lib/mongo/crypt/explicit_encrypter.rb', line 35

def initialize(key_vault_client, key_vault_namespace, kms_providers)
  @crypt_handle = Handle.new(kms_providers)

  @encryption_io = EncryptionIO.new(
    key_vault_client: key_vault_client,
    key_vault_namespace: key_vault_namespace
  )
end

Instance Method Details

#create_and_insert_data_key(kms_provider, 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.

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:

  • kms_provider (String)

    The KMS provider to use. Valid values are “aws” and “local”.

  • options (Hash)

Options Hash (options):

  • :master_key (Hash)

    Information about the AWS master key. Required if kms_provider is “aws”.

    • :region [ String ] The The AWS region of the master key (required).

    • :key [ String ] The Amazon Resource Name (ARN) of the master key (required).

    • :endpoint [ String ] An alternate host to send KMS requests to (optional). endpoint should be a host name with an optional port number separated by a colon (e.g. “kms.us-east-1.amazonaws.com” or “kms.us-east-1.amazonaws.com:443”). An endpoint in any other format will not be properly parsed.

  • :key_alt_names (Array<String>)

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

Returns:

  • (BSON::Binary)

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



66
67
68
69
70
71
72
73
74
75
# File 'build/ruby-driver-master/lib/mongo/crypt/explicit_encrypter.rb', line 66

def create_and_insert_data_key(kms_provider, options)
  data_key_document = Crypt::DataKeyContext.new(
    @crypt_handle,
    @encryption_io,
    kms_provider,
    options
  ).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



111
112
113
114
115
116
117
# File 'build/ruby-driver-master/lib/mongo/crypt/explicit_encrypter.rb', line 111

def decrypt(value)
  result = Crypt::ExplicitDecryptionContext.new(
    @crypt_handle,
    @encryption_io,
    { 'v': value },
  ).run_state_machine['v']
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

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” or “AEAD_AES_256_CBC_HMAC_SHA_512-Random”.

Returns:

  • (BSON::Binary)

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



96
97
98
99
100
101
102
103
# File 'build/ruby-driver-master/lib/mongo/crypt/explicit_encrypter.rb', line 96

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