Explicit Encryption
On this page
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 KeyThe namespace of your Key Vault collection
If you use MongoDB Community Server, set the
bypassQueryAnalysis
option toTrue
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 algorithm used:
Indexed
,Unindexed
, orRange
The ID of the Data Encryption Key
The contention factor (if you are using the
Indexed
orRange
algorithm)If you are performing a read operation using the
Indexed
orRange
algorithm, set the query type defined for your field.The
range
options min, max (if you are using theRange
algorithm)
Note
Query Types
The query type only applies to read operations.
To learn more about query types, see Supported Query Types and Behavior.
Algorithm Choice
Use the Indexed
or Range
algorithm if you specify a
queryType
on the field.
Indexed
supports equality queries. Range
supports range
queries. Indexed
and Range
fields require an index on the
server. The index is created by specifying the encryptedFields
option in db.createCollection()
.
Automatic Decryption
To decrypt fields automatically, configure your MongoClient
instance as follows:
Specify a
kmsProviders
objectSpecify your Key Vault collection
If you use MongoDB Community Server, set the
bypassQueryAnalysis
option toTrue
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.
Indexed
and Range
fields require an index on the server. The
index is created by specifying the encryptedFields
option in
db.createCollection()
.
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.