Class: Mongo::ClientEncryption

Inherits:
Object
  • Object
show all
Defined in:
build/ruby-driver-master/lib/mongo/client_encryption.rb

Overview

ClientEncryption encapsulates explicit operations on a key vault collection that cannot be done directly on a MongoClient. It provides an API for explicitly encrypting and decrypting values, and creating data keys.

Instance Method Summary collapse

Constructor Details

#initialize(key_vault_client, options = {}) ⇒ ClientEncryption

Create a new ClientEncryption object with the provided options.

Parameters:

  • key_vault_client (Mongo::Client) —

    A Mongo::Client that is connected to the MongoDB instance where the key vault collection is stored.

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

    The ClientEncryption options.

Options Hash (options):

  • :key_vault_namespace (String) —

    The name of the key vault collection in the format “database.collection”.

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



46
47
48
49
50
51
52
53
 
# File 'build/ruby-driver-master/lib/mongo/client_encryption.rb', line 46

def initialize(key_vault_client, options={})
  @encrypter = Crypt::ExplicitEncrypter.new(
    key_vault_client,
    options[:key_vault_namespace],
    Crypt::KMS::Credentials.new(options[:kms_providers]),
    Crypt::KMS::Validations.validate_tls_options(options[:kms_tls_options])
  )
end

Instance Method Details

#create_data_key(kms_provider, options = {}) ⇒ BSON::Binary

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) (defaults to: {})

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.



77
78
79
80
81
 
# File 'build/ruby-driver-master/lib/mongo/client_encryption.rb', line 77

def create_data_key(kms_provider, options={})
  key_document = Crypt::KMS::MasterKeyDocument.new(kms_provider, options)
  key_alt_names = options[:key_alt_names]
  @encrypter.create_and_insert_data_key(key_document, key_alt_names)
end

#decrypt(value) ⇒ Object

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.



112
113
114
 
# File 'build/ruby-driver-master/lib/mongo/client_encryption.rb', line 112

def decrypt(value)
  @encrypter.decrypt(value)
end

#encrypt(value, options = {}) ⇒ BSON::Binary

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) (defaults to: {})

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.



102
103
104
 
# File 'build/ruby-driver-master/lib/mongo/client_encryption.rb', line 102

def encrypt(value, options={})
  @encrypter.encrypt(value, options)
end