mongocxx::v_noabi::client_encryption Class Reference

#include <mongocxx/v_noabi/mongocxx/client_encryption.hpp>

Description

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

Public Member Functions
	client_encryption (client_encryption &&) noexcept
	Move-constructs a client_encryption object.
	client_encryption (options::client_encryption opts)
	Creates a client_encryption object.
	~client_encryption ()
	Destroys a client_encryption.
bsoncxx::v_noabi::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).
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 bsoncxx::v_noabi::stdx::optional< bsoncxx::v_noabi::document::view > &masterkey=bsoncxx::v_noabi::stdx::nullopt)
	Create a collection with client-side-encryption enabled, automatically filling any datakeys for encrypted fields.
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::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.
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::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).
bsoncxx::v_noabi::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.
mongocxx::v_noabi::cursor	get_keys ()
	Finds all documents in the key vault collection.
client_encryption &	operator= (client_encryption &&) noexcept
	Move-assigns a client_encryption object.
bsoncxx::v_noabi::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).
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. 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.

Constructor & Destructor Documentation

client_encryption() [1/2]

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

~client_encryption()

mongocxx::v_noabi::client_encryption::~client_encryption

(

)

Destroys a client_encryption.

client_encryption() [2/2]

mongocxx::v_noabi::client_encryption::client_encryption ( client_encryption && )

noexcept

Move-constructs a client_encryption object.

Member Function Documentation

add_key_alt_name()

bsoncxx::v_noabi::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 bsoncxx::v_noabi::stdx::optional< bsoncxx::v_noabi::document::view > &	masterkey = bsoncxx::v_noabi::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 database::create_collection.
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 "range" and algorithm is "Range".

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.

get_key()

bsoncxx::v_noabi::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()

bsoncxx::v_noabi::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/

operator=()

client_encryption & mongocxx::v_noabi::client_encryption::operator= ( client_encryption && )

noexcept

Move-assigns a client_encryption object.

remove_key_alt_name()

bsoncxx::v_noabi::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:

• mongocxx/v_noabi/mongocxx/client_encryption.hpp