Method: Mongo::ClientEncryption#create_data_key

Defined in:

lib/mongo/client_encryption.rb

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

• :key_material (String | 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.

# File 'lib/mongo/client_encryption.rb', line 84

def create_data_key(kms_provider, options={})
  key_document = Crypt::KMS::MasterKeyDocument.new(kms_provider, options)

  key_alt_names = options[:key_alt_names]
  key_material = options[:key_material]
  @encrypter.create_and_insert_data_key(key_document, key_alt_names, key_material)
end