Explicit Encryption
On this page
- Overview
- Use Explicit Encryption
- Create a ClientEncryption Instance
- Encrypt Fields in Read and Write Operations
- Manual Decryption
- Automatic Decryption
- Example
- Create a MongoClient Instance
- Create a ClientEncryption Instance
- Encrypt Fields and Insert
- Retrieve Document and Decrypt Fields
- Server-Side Field Level Encryption Enforcement
- Learn More
Overview
Learn how to use the explicit encryption mechanism of Client-Side Field Level Encryption (CSFLE).
Explicit encryption is a mechanism in which you specify how you would like to encrypt and decrypt fields in your document in each operation you perform on your database.
Explicit encryption is a mechanism in which you specify how you would like to encrypt and decrypt fields in your document in each operation you perform on your database.
Explicit encryption is available in the following MongoDB products of version 4.2 or later:
MongoDB Community Server
MongoDB Enterprise Advanced
MongoDB Atlas
Use Explicit Encryption
To use explicit encryption you must perform the following actions in your CSFLE-enabled application:
Manually or Automatically Decrypt Fields in Your Documents
Create a ClientEncryption Instance
To use explicit encryption, you must 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, you must specify
the following information:
A
MongoClient
instance with access to your Key Vault collectionThe namespace of your Key Vault collection
A
kmsProviders
object configured with access to the KMS hosting your Customer Master Key
For more ClientEncryption
options, see CSFLE-Specific MongoClient Options.
To view code snippets that show how to create a ClientEncryption
instance, see the Example
section of this guide.
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.
To view code snippets that show how to use the encrypt
method,
see the Example
section of this guide.
Manual Decryption
You can decrypt your encrypted fields manually or automatically when using explicit encryption.
To decrypt your fields manually, use the decrypt
method of your
ClientEncryption
instance.
To view code snippets that show how to use the decrypt
method,
see the Example
section of this guide.
Automatic Decryption
To decrypt your fields automatically, you must configure your
MongoClient
instance as follows:
Specify your Key Vault collection
Specify a
kmsProviders
objectIf you use MongoDB Community Server, set the
bypassAutoEncryption
option toTrue
Note
Automatic Decryption is Available in MongoDB Community Server
Although automatic encryption requires MongoDB Enterprise or MongoDB Atlas, automatic decryption is available in the following MongoDB products of version 4.2 or later:
MongoDB Community Server
MongoDB Enterprise Advanced
MongoDB Atlas
To view a code snippet demonstrating how to enable automatic decryption, select the tab corresponding to your preferred language:
Example
Assume you want to insert documents with the following structure into your MongoDB instance:
{ "name": "<name of person>", "age": <age of person>, "favorite-foods": ["<array of foods>"] }
Encrypt Fields and Insert
You want to encrypt the fields of your document using the following algorithms:
Field Name | Encryption Algorithm | BSON Type of Field |
---|---|---|
name | Deterministic | String |
age | No encryption | Int |
favorite-foods | Random | Array |
The following code snippets show how to manually encrypt the fields in your document and insert your document into MongoDB:
Server-Side Field Level Encryption Enforcement
MongoDB supports using schema validation to enforce encryption of specific fields in a collection.
A client performing Client-Side Field Level Encryption with the explicit encryption mechanism on a MongoDB instance configured to enforce encryption of certain fields must encrypt those fields as specified on the MongoDB instance.
To learn how to set up server-side CSFLE enforcement, see CSFLE Server-Side Schema Enforcement.
Learn More
To learn more about Key Vault collections, Data Encryption Keys, and Customer Master Keys, see Keys and Key Vaults.
To learn more about KMS providers and kmsProviders
objects,
see CSFLE KMS Providers.