ClientEncryption — Documentation by YARD 0.9.37 (original) (raw)

Class: Mongo::ClientEncryption

Inherits:

Object

Defined in:

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 Summarycollapse

Constructor Details

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

Create a new ClientEncryption object with the provided options.

Instance Method Details

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

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

183 184 185 # File 'lib/mongo/client_encryption.rb', line 183 def add_key_alt_name(id, key_alt_name) @encrypter.add_key_alt_name(id, key_alt_name) end

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

84 85 86 87 88 89 90 # 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

#create_encrypted_collection(database, coll_name, coll_opts, kms_provider, master_key) ⇒ Array<Operation::Result, Hash>

Note:

This method does not update the :encrypted_fields_map in the client’s :auto_encryption_options. Therefore, in order to use the collection created by this method with automatic encryption, the user must create a new client after calling this function with the :encrypted_fields returned.

Create collection with encrypted fields.

If :encryption_fields contains a keyId with a null value, a data key will be automatically generated and assigned to keyId value.

270 271 272 273 274 275 276 277 278 279 280 281 # File 'lib/mongo/client_encryption.rb', line 270 def create_encrypted_collection(database, coll_name, coll_opts, kms_provider, master_key) raise ArgumentError, 'coll_opts must contain :encrypted_fields' unless coll_opts[:encrypted_fields] encrypted_fields = create_data_keys(coll_opts[:encrypted_fields], kms_provider, master_key) begin new_coll_opts = coll_opts.dup.merge(encrypted_fields: encrypted_fields) [database[coll_name].create(new_coll_opts), encrypted_fields] rescue Mongo::Error => e raise Error::CryptError, "Error creating collection with encrypted fields \ #{encrypted_fields}: #{e.class}: #{e.message}" end end

#decrypt(value) ⇒ Object

Decrypts a value that has already been encrypted.

172 173 174 # File 'lib/mongo/client_encryption.rb', line 172 def decrypt(value) @encrypter.decrypt(value) end

#delete_key(id) ⇒ Operation::Result

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

193 194 195 # File 'lib/mongo/client_encryption.rb', line 193 def delete_key(id) @encrypter.delete_key(id) 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.

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".
122 123 124 # File 'lib/mongo/client_encryption.rb', line 122 def encrypt(value, options={}) @encrypter.encrypt(value, options) end

#encrypt_expression(expression, 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 Match Expression or Aggregate Expression to query a range index.

Only supported when queryType is “range” and algorithm is “Range”. @note: The Range algorithm is experimental only. It is not intended

for public use. It is subject to breaking changes.

# @param [ Hash ] options

162 163 164 # File 'lib/mongo/client_encryption.rb', line 162 def encrypt_expression(expression, options = {}) @encrypter.encrypt_expression(expression, options) end

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

Finds a single key with the given id.

203 204 205 # File 'lib/mongo/client_encryption.rb', line 203 def get_key(id) @encrypter.get_key(id) end

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

Returns a key in the key vault collection with the given key_alt_name.

213 214 215 # File 'lib/mongo/client_encryption.rb', line 213 def get_key_by_alt_name(key_alt_name) @encrypter.get_key_by_alt_name(key_alt_name) end

#get_keys ⇒ Collection::View Also known as:keys

Returns all keys in the key vault collection.

220 221 222 # File 'lib/mongo/client_encryption.rb', line 220 def get_keys @encrypter.get_keys end

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

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

232 233 234 # File 'lib/mongo/client_encryption.rb', line 232 def remove_key_alt_name(id, key_alt_name) @encrypter.remove_key_alt_name(id, key_alt_name) end

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

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.
247 248 249 # File 'lib/mongo/client_encryption.rb', line 247 def rewrap_many_data_key(filter, opts = {}) @encrypter.rewrap_many_data_key(filter, opts) end