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
MongoClientinstance with access to your Key Vault collectionThe namespace of your Key Vault collection
A
kmsProvidersobject 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
kmsProvidersobjectIf you use MongoDB Community Server, set the
bypassAutoEncryptionoption 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>"] }
Create a MongoClient Instance
In this example, you use the same MongoClient instance to access your
Key Vault collection and to read and write encrypted data.
The following code snippets show how to create a MongoClient instance:
Create a ClientEncryption Instance
The following code snippets show how to create a ClientEncryption
instance:
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:
Retrieve Document and Decrypt Fields
The following code snippets show how to retrieve your inserted document and manually decrypt the encrypted fields:
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.