Class supporting operations for MongoDB Client-Side Field Level Encryption. More...

#include <client_encryption.hpp>

Public Member Functions
	client_encryption (options::client_encryption opts)
	Creates a client_encryption object.

	~client_encryption () noexcept
	Destroys a client_encryption.

	client_encryption (client_encryption &&)
	Move-constructs a client_encryption object.

client_encryption &	operator= (client_encryption &&)
	Move-assigns a client_encryption object.

bsoncxx::v_noabi::types::bson_value::value	create_data_key (std::string kms_provider, const options::data_key &opts={})
	Creates a new key document and inserts into the key vault collection.

collection	create_encrypted_collection (const database &db, const std::string &coll_name, const bsoncxx::v_noabi::document::view &options, bsoncxx::v_noabi::document::value &out_options, const std::string &kms_provider, const stdx::optional< bsoncxx::v_noabi::document::view > &masterkey=stdx::nullopt)
	Create a collection with client-side-encryption enabled, automatically filling any datakeys for encrypted fields.

bsoncxx::v_noabi::types::bson_value::value	encrypt (bsoncxx::v_noabi::types::bson_value::view value, const options::encrypt &opts)
	Encrypts a BSON value with a given key and algorithm.

bsoncxx::v_noabi::document::value	encrypt_expression (bsoncxx::v_noabi::document::view_or_value expr, const options::encrypt &opts)
	Encrypts a Match Expression or Aggregate Expression to query a range index.

bsoncxx::v_noabi::types::bson_value::value	decrypt (bsoncxx::v_noabi::types::bson_value::view value)
	Decrypts an encrypted value (BSON binary of subtype 6).

result::rewrap_many_datakey	rewrap_many_datakey (bsoncxx::v_noabi::document::view_or_value filter, const options::rewrap_many_datakey &opts)
	Decrypts multiple data keys and (re-)encrypts them with a new masterKey, or with their current masterKey if a new one is not given.

result::delete_result	delete_key (bsoncxx::v_noabi::types::bson_value::view_or_value id)
	Removes the key document with the given UUID (BSON binary subtype 0x04) from the key vault collection.

stdx::optional< bsoncxx::v_noabi::document::value >	get_key (bsoncxx::v_noabi::types::bson_value::view_or_value id)
	Finds a single key document with the given UUID (BSON binary subtype 0x04).

mongocxx::v_noabi::cursor	get_keys ()
	Finds all documents in the key vault collection.

stdx::optional< bsoncxx::v_noabi::document::value >	add_key_alt_name (bsoncxx::v_noabi::types::bson_value::view_or_value id, bsoncxx::v_noabi::string::view_or_value key_alt_name)
	Adds a keyAltName to the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04).

stdx::optional< bsoncxx::v_noabi::document::value >	remove_key_alt_name (bsoncxx::v_noabi::types::bson_value::view_or_value id, bsoncxx::v_noabi::string::view_or_value key_alt_name)
	Removes a keyAltName from the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04).

stdx::optional< bsoncxx::v_noabi::document::value >	get_key_by_alt_name (bsoncxx::v_noabi::string::view_or_value key_alt_name)
	Get the key document from the key vault collection with the provided name.

Detailed Description

Class supporting operations for MongoDB Client-Side Field Level Encryption.

Constructor & Destructor Documentation

◆ client_encryption()

mongocxx::v_noabi::client_encryption::client_encryption ( options::client_encryption opts )

Creates a client_encryption object.

Parameters

opts	An object representing encryption options.

See also: https://www.mongodb.com/docs/ecosystem/use-cases/client-side-field-level-encryption-guide

Member Function Documentation

◆ add_key_alt_name()

stdx::optional< bsoncxx::v_noabi::document::value > mongocxx::v_noabi::client_encryption::add_key_alt_name	(	bsoncxx::v_noabi::types::bson_value::view_or_value	id,
		bsoncxx::v_noabi::string::view_or_value	key_alt_name
	)

Adds a keyAltName to the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04).

Parameters

id	Binary id of the key to add the key alternate name to
key_alt_name	String alternative name for the key

Exceptions

mongocxx::v_noabi::exception if there is an error adding the key alt name.

Returns: the previous version of the key document.

See also: https://www.mongodb.com/docs/manual/reference/method/KeyVault.addKeyAlternateName/

◆ create_data_key()

bsoncxx::v_noabi::types::bson_value::value mongocxx::v_noabi::client_encryption::create_data_key	(	std::string	kms_provider,
		const options::data_key &	opts = `{}`
	)

Creates a new key document and inserts into the key vault collection.

Parameters

kms_provider	A string identifying the KMS service to use to encrypt the datakey. Must be one of "aws", "azure", "gcp", "kmip", or "local".
opts	Optional arguments, see options::data_key.

Returns: The id of the created document as a bson_value::value containing a UUID (BSON binary subtype 4).

Exceptions

mongocxx::v_noabi::exception if there is an error creating the key.

See also: https://www.mongodb.com/docs/ecosystem/use-cases/client-side-field-level-encryption-guide/#b-create-a-data-encryption-key

◆ create_encrypted_collection()

collection mongocxx::v_noabi::client_encryption::create_encrypted_collection	(	const database &	db,
		const std::string &	coll_name,
		const bsoncxx::v_noabi::document::view &	options,
		bsoncxx::v_noabi::document::value &	out_options,
		const std::string &	kms_provider,
		const stdx::optional< bsoncxx::v_noabi::document::view > &	masterkey = `stdx::nullopt`
	)

Create a collection with client-side-encryption enabled, automatically filling any datakeys for encrypted fields.

Parameters

db	The database in which the collection will be created
coll_name	The name of the new collection
options	The options for creating the collection.

See also: database::create_collection

Parameters

out_options	Output parameter to receive the generated collection options.
kms_provider	The KMS provider to use when creating data encryption keys for the collection's encrypted fields
masterkey	If non-null, specify the masterkey to be used when creating data keys in the collection.

Returns: collection A handle to the newly created collection

◆ decrypt()

bsoncxx::v_noabi::types::bson_value::value mongocxx::v_noabi::client_encryption::decrypt ( bsoncxx::v_noabi::types::bson_value::view value )

Decrypts an encrypted value (BSON binary of subtype 6).

Parameters

value The encrypted value.

Returns: The original BSON value.

Exceptions

mongocxx::v_noabi::exception if there is an error decrypting the value.

See also: https://www.mongodb.com/docs/manual/reference/method/ClientEncryption.decrypt/#ClientEncryption.decrypt

◆ delete_key()

result::delete_result mongocxx::v_noabi::client_encryption::delete_key ( bsoncxx::v_noabi::types::bson_value::view_or_value id )

Removes the key document with the given UUID (BSON binary subtype 0x04) from the key vault collection.

Parameters

id	Binary id of which key to delete

Exceptions

mongocxx::v_noabi::exception if there is an error deleting the key.

Returns: the result of the internal deleteOne() operation on the key vault collection.

See also: https://www.mongodb.com/docs/manual/reference/method/KeyVault.deleteKey/

◆ encrypt()

bsoncxx::v_noabi::types::bson_value::value mongocxx::v_noabi::client_encryption::encrypt	(	bsoncxx::v_noabi::types::bson_value::view	value,
		const options::encrypt &	opts
	)

Encrypts a BSON value with a given key and algorithm.

Parameters

value	The BSON value to encrypt.
opts	Options must be given in order to specify an encryption algorithm and a key_id or key_alt_name. See options::encrypt.

Returns: The encrypted value (BSON binary subtype 6).

Exceptions

mongocxx::v_noabi::exception if there is an error encrypting the value.

See also: https://www.mongodb.com/docs/manual/reference/method/ClientEncryption.encrypt/#ClientEncryption.encrypt

◆ encrypt_expression()

bsoncxx::v_noabi::document::value mongocxx::v_noabi::client_encryption::encrypt_expression	(	bsoncxx::v_noabi::document::view_or_value	expr,
		const options::encrypt &	opts
	)

Encrypts a Match Expression or Aggregate Expression to query a range index.

Note: Only supported when queryType is "rangePreview" and algorithm is "RangePreview".

Parameters

expr	A BSON document corresponding to either a Match Expression or an Aggregate Expression.
opts	Options must be given in order to specify queryType and algorithm.

Returns: The encrypted expression.

Warning: The Range algorithm is experimental only. It is not intended for public use. It is subject to breaking changes.

◆ get_key()

stdx::optional< bsoncxx::v_noabi::document::value > mongocxx::v_noabi::client_encryption::get_key ( bsoncxx::v_noabi::types::bson_value::view_or_value id )

Finds a single key document with the given UUID (BSON binary subtype 0x04).

Parameters

id	Binary id of which key to delete

Exceptions

mongocxx::v_noabi::exception if there is an error getting the key.

Returns: The result of the internal find() operation on the key vault collection.

See also: https://www.mongodb.com/docs/manual/reference/method/KeyVault.getKey/

◆ get_key_by_alt_name()

stdx::optional< bsoncxx::v_noabi::document::value > mongocxx::v_noabi::client_encryption::get_key_by_alt_name ( bsoncxx::v_noabi::string::view_or_value key_alt_name )

Get the key document from the key vault collection with the provided name.

Parameters

key_alt_name String alternative name for the key

Exceptions

mongocxx::v_noabi::exception if there is an error getting the key by alt name.

Returns: A key document in the key vault collection with the given keyAltName.

See also: https://www.mongodb.com/docs/manual/reference/method/KeyVault.getKeyByAltName/

◆ get_keys()

mongocxx::v_noabi::cursor mongocxx::v_noabi::client_encryption::get_keys ( )

Finds all documents in the key vault collection.

Exceptions

mongocxx::v_noabi::exception if there is an error getting the keys.

Returns: the result of the internal find() operation on the key vault collection.

See also: https://www.mongodb.com/docs/manual/reference/method/KeyVault.getKeys/

◆ remove_key_alt_name()

stdx::optional< bsoncxx::v_noabi::document::value > mongocxx::v_noabi::client_encryption::remove_key_alt_name	(	bsoncxx::v_noabi::types::bson_value::view_or_value	id,
		bsoncxx::v_noabi::string::view_or_value	key_alt_name
	)

Removes a keyAltName from the keyAltNames array of the key document in the key vault collection with the given UUID (BSON binary subtype 0x04).

Parameters

id	Binary id of the key to remove the key alternate name from
key_alt_name	String alternative name for the key

Exceptions

mongocxx::v_noabi::exception if there is an error removing the key alt name.

Returns: The previous version of the key document.

See also: https://www.mongodb.com/docs/manual/reference/method/KeyVault.removeKeyAlternateName/

◆ rewrap_many_datakey()

result::rewrap_many_datakey mongocxx::v_noabi::client_encryption::rewrap_many_datakey	(	bsoncxx::v_noabi::document::view_or_value	filter,
		const options::rewrap_many_datakey &	opts
	)

Decrypts multiple data keys and (re-)encrypts them with a new masterKey, or with their current masterKey if a new one is not given.

The updated fields of each rewrapped data key is updated in the key vault collection as part of a single bulk write operation. If no data key matches the given filter, no bulk write operation is executed.

Parameters

filter	Document to filter which keys get re-wrapped.
opts	Options to specify which provider to encrypt the data keys and an optional master key document.

Returns: a RewrapManyDataKeyResult.

Exceptions

mongocxx::v_noabi::exception if there is an error rewrapping the key.

See also: https://www.mongodb.com/docs/manual/reference/method/KeyVault.rewrapManyDataKey/

The documentation for this class was generated from the following file:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client_encryption.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ client_encryption()

Member Function Documentation

◆ add_key_alt_name()

◆ create_data_key()

◆ create_encrypted_collection()

◆ decrypt()

◆ delete_key()

◆ encrypt()

◆ encrypt_expression()

◆ get_key()

◆ get_key_by_alt_name()

◆ get_keys()

◆ remove_key_alt_name()

◆ rewrap_many_datakey()