/ /

Queryable Encryption with Explicit Encryption

Overview

Explicit encryption provides fine-grained control over security, at the cost of increased complexity when configuring collections and writing code for MongoDB Drivers. With explicit encryption, you specify how to encrypt fields in your document for each operation you perform on the database, and you include this logic throughout your application.

Explicit encryption is available in the following MongoDB products:

MongoDB Community Server
MongoDB Enterprise Advanced
MongoDB Atlas

Use Explicit Encryption

Create a ClientEncryption Instance

ClientEncryption is an abstraction used across drivers and mongosh that encapsulates the Key Vault collection and KMS operations involved in explicit encryption.

To create a ClientEncryption instance, specify:

A kmsProviders object configured with access to the KMS provider hosting your Customer Master Key
The namespace of your Key Vault collection
If you use MongoDB Community Server, set the bypassQueryAnalysis option to True
A MongoClient instance with access to your Key Vault collection

For more ClientEncryption options, see MongoClient Options for Queryable Encryption.

Encrypt Fields in Read and Write Operations

You must update read and write operations throughout your application such that your application encrypts fields before performing read and write operations.

To encrypt fields, use the encrypt method of your ClientEncryption instance. Specify the following:

The value to be encrypted
The ID of the Data Encryption Key
The algorithm
- unindexed: for non-queryable encrypted fields.
- indexed: supports equality queries.
- range: supports range queries.
- string: supports prefix, suffix, and substring queries.
The parameters for your chosen algorithm. Explicit encryption doesn't use an encryption schema, so you must pass these parameters on every call to encrypt, for both read and write operations.
Read operations must specify a queryType that matches the specified algorithm.

Note

The indexed, range, and string algorithms require an index on the server, which is created when you specify the encryptedFields option during db.createCollection().

Algorithms and QueryTypes

algorithm	queryType (read operations)	Additional Parameters
`indexed`	`equality`	(Required) contention factor
`range`	`range`	(Required) contention factor (Required if setting precision, otherwise optional but recommended) min, max queryable values (Optional, use with `double` and `decimal` fields only) precision (Optional) trimFactor (Optional) sparsity
`string`	`prefix` or `suffix`	(Required) contention factor (Required) caseSensitive, diacriticSensitive (Required) strMinQueryLength, strMaxQueryLength
`string`	`substring`	(Required) contention factor (Required) caseSensitive, diacriticSensitive (Required) strMinQueryLength, strMaxQueryLength (Required) strMaxLength

For write operations, you can specify prefix and suffix options in the same call to index a field for both query types. You can't set substring alongside prefix or suffix.

Note

Starting in MongoDB 9.0, the prefixPreview, suffixPreview, and substringPreview query types using the text algorithm are deprecated and removed. Use prefix, suffix, or substring query types with the string algorithm instead.

Automatic Decryption

To decrypt fields automatically, configure your MongoClient instance as follows:

Specify a kmsProviders object
Specify your Key Vault collection
If you use MongoDB Community Server, set the bypassQueryAnalysis option to True

Note

Automatic Decryption in MongoDB Community Server

Automatic decryption is available in MongoDB Community Server. Automatic encryption requires MongoDB Enterprise or MongoDB Atlas.

Server-Side Field Level Encryption Enforcement

Steps to enforce encryption of specific fields in a collection.

If your MongoDB instance enforces the encryption of specific fields, any client performing Queryable Encryption with explicit encryption must encrypt those fields as specified. To learn how to set up server-side Queryable Encryption enforcement, see Encrypted Fields and Enabled Queries.

Learn More

To learn more about Key Vault collections, Data Encryption Keys, and Customer Master Keys, see Encryption Keys and Key Vaults.

To learn more about KMS providers and kmsProviders objects, see KMS Providers.

Back

Collections

Manage Keys