class Mongo::Crypt::ExplicitEncrypter

An ExplicitEncrypter is an object that performs explicit encryption operations and handles all associated options and instance variables.

@api private

Public Class Methods

new(key_vault_client, key_vault_namespace, kms_providers) click to toggle source

Create a new ExplicitEncrypter object.

@param [ Mongo::Client ] key_vault_client An instance of Mongo::Client

to connect to the key vault collection.

@param [ String ] key_vault_namespace The namespace of the key vault

collection in the format "db_name.collection_name".

@option options [ Hash ] :kms_providers A hash of key management service

configuration information. Valid hash keys are :local or :aws. There
may be more than one KMS provider specified.
# File 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

Public Instance Methods

create_and_insert_data_key(kms_provider, options) click to toggle source

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.

@param [ String ] kms_provider The KMS provider to use. Valid values are

"aws" and "local".

@param [ Hash ] options

@option options [ Hash ] :master_key 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.

@option options [ Array<String> ] :key_alt_names An optional array of strings specifying

alternate names for the new data key.

@return [ BSON::Binary ] The 16-byte UUID of the new data key as a

BSON::Binary object with type :uuid.
# File 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) click to toggle source

Decrypts a value that has already been encrypted

@param [ BSON::Binary ] value A BSON Binary object of subtype 6 (ciphertext)

that will be decrypted

@return [ Object ] The decrypted value

# File 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) click to toggle source

Encrypts a value using the specified encryption key and algorithm

@param [ Object ] value The value to encrypt @param [ Hash ] options

@option options [ BSON::Binary ] :key_id A BSON::Binary object of type :uuid

representing the UUID of the encryption key as it is stored in the key
vault collection.

@option options [ String ] :key_alt_name The alternate name for the

encryption key.

@option options [ String ] :algorithm 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".

@note The :key_id and :key_alt_name options are mutually exclusive. Only

one is required to perform explicit encryption.

@return [ BSON::Binary ] A BSON Binary object of subtype 6 (ciphertext)

representing the encrypted value
# File 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