In-Use Encryption

Overview

You can use the C++ driver to encrypt specific document fields by using a set of features called in-use encryption. In-use encryption allows your application to encrypt data before sending it to MongoDB and query documents with encrypted fields.

In-use encryption prevents unauthorized users from viewing plaintext data as it is sent to MongoDB or while it is in an encrypted database. To enable in-use encryption in an application and authorize it to decrypt data, you must create encryption keys that only your application can access. Only applications that have access to your encryption keys can access the decrypted, plaintext data. If an attacker gains access to the database, they can see only the encrypted ciphertext data because they lack access to the encryption keys.

You can use in-use encryption to encrypt fields in your MongoDB documents that contain the following types of sensitive data:

• Credit card numbers

• Addresses

• Health information

• Financial information

• Any other sensitive or personally identifiable information (PII)

MongoDB offers the following features to enable in-use encryption:

• Queryable Encryption

• Client-side Field Level Encryption

Queryable Encryption

Queryable Encryption is the next-generation in-use encryption feature, first introduced as a preview feature in MongoDB Server version 6.0 and as a generally available (GA) feature in MongoDB 7.0. Queryable Encryption supports searching encrypted fields for equality and encrypts each value uniquely.

To learn more about Queryable Encryption, see Queryable Encryption in the MongoDB Server manual.

Client-side Field Level Encryption

Client-side Field Level Encryption (CSFLE) was introduced in MongoDB Server version 4.2 and supports searching encrypted fields for equality. CSFLE differs from Queryable Encryption in that you can select either a deterministic or random encryption algorithm to encrypt fields. You can only query encrypted fields that use a deterministic encryption algorithm when using CSFLE. When you use a random encryption algorithm to encrypt fields in CSFLE, they can be decrypted, but you cannot perform equality queries on those fields. When you use Queryable Encryption, you cannot specify the encryption algorithm, but you can query all encrypted fields.

When you deterministically encrypt a value, the same input value produces the same output value. While deterministic encryption allows you to perform queries on those encrypted fields, encrypted data with low cardinality is susceptible to code breaking by frequency analysis.

This section shows how to configure CSFLE by using the following mechanisms:

• Automatic Encryption

• Explicit Encryption

auto data_key_id = client_encryption.create_data_key("local");
auto json_schema = document{} << "properties" << open_document << "encryptedFieldName" << open_document << "encrypt"
                                << open_document << "keyId" << open_array << data_key_id << close_array << "bsonType"
                                << "string"
                                << "algorithm"
                                << "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" << close_document << close_document
                                << close_document << "bsonType"
                                << "object" << finalize;

// Configure your MongoDB client's encryption options here
class client_encryption client_encryption(std::move(client_encryption_opts));
auto data_key_id = client_encryption.create_data_key("local");
options::encrypt encrypt_opts{};
encrypt_opts.key_id(data_key_id.view());
encrypt_opts.algorithm(options::encrypt::encryption_algorithm::k_deterministic);
// Explicitly encrypts a BSON value
auto to_encrypt = bsoncxx::types::bson_value::make_value("secret message");
auto encrypted_message = client_encryption.encrypt(to_encrypt, encrypt_opts);
// Explicitly decrypts a BSON value
auto decrypted_message = client_encryption.decrypt(encrypted_message);
// Inserts the encrypted value into the database
coll.insert_one(make_document(kvp("encryptedField", encrypted_message)));

options::auto_encryption auto_encrypt_opts{};
auto_encrypt_opts.bypass_auto_encryption(true);
options::client client_opts{};
client_opts.auto_encryption_opts(std::move(auto_encrypt_opts));
class client client_encrypted {uri{}, std::move(client_opts)};

Additional Information

To learn more about CSFLE, see CSFLE in the MongoDB Server manual.