MongoDB C++ Driver  mongocxx-3.10.2
Public Member Functions | List of all members
mongocxx::v_noabi::client_encryption Class Reference

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. More...
 
 ~client_encryption () noexcept
 Destroys a client_encryption.
 
 client_encryption (client_encryption &&)
 Move-constructs a client_encryption object.
 
client_encryptionoperator= (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. More...
 
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. More...
 
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. More...
 
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. More...
 
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). More...
 
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. More...
 
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. More...
 
stdx::optional< bsoncxx::v_noabi::document::valueget_key (bsoncxx::v_noabi::types::bson_value::view_or_value id)
 Finds a single key document with the given UUID (BSON binary subtype 0x04). More...
 
mongocxx::v_noabi::cursor get_keys ()
 Finds all documents in the key vault collection. More...
 
stdx::optional< bsoncxx::v_noabi::document::valueadd_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). More...
 
stdx::optional< bsoncxx::v_noabi::document::valueremove_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). More...
 
stdx::optional< bsoncxx::v_noabi::document::valueget_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. More...
 

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
optsAn 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
idBinary id of the key to add the key alternate name to
key_alt_nameString alternative name for the key
Exceptions
mongocxx::v_noabi::exceptionif 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_providerA string identifying the KMS service to use to encrypt the datakey. Must be one of "aws", "azure", "gcp", "kmip", or "local".
optsOptional 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::exceptionif 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
dbThe database in which the collection will be created
coll_nameThe name of the new collection
optionsThe options for creating the collection.
See also
database::create_collection
Parameters
out_optionsOutput parameter to receive the generated collection options.
kms_providerThe KMS provider to use when creating data encryption keys for the collection's encrypted fields
masterkeyIf 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
valueThe encrypted value.
Returns
The original BSON value.
Exceptions
mongocxx::v_noabi::exceptionif 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
idBinary id of which key to delete
Exceptions
mongocxx::v_noabi::exceptionif 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
valueThe BSON value to encrypt.
optsOptions 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::exceptionif 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
exprA BSON document corresponding to either a Match Expression or an Aggregate Expression.
optsOptions 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
idBinary id of which key to delete
Exceptions
mongocxx::v_noabi::exceptionif 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_nameString alternative name for the key
Exceptions
mongocxx::v_noabi::exceptionif 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::exceptionif 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
idBinary id of the key to remove the key alternate name from
key_alt_nameString alternative name for the key
Exceptions
mongocxx::v_noabi::exceptionif 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
filterDocument to filter which keys get re-wrapped.
optsOptions to specify which provider to encrypt the data keys and an optional master key document.
Returns
a RewrapManyDataKeyResult.
Exceptions
mongocxx::v_noabi::exceptionif 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: