Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

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

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 to encrypt and decrypt fields in your document for 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

To use explicit encryption you must perform the following actions in your CSFLE-enabled application:

  • Create a ClientEncryption Instance

  • Encrypt Fields in Read and Write Operations

  • Manually or Automatically Decrypt Fields in Your Documents

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 collection

  • The namespace of your Key Vault collection

  • A kmsProviders object configured with access to the KMS provider 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.

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.

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.

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

  • Specify your Key Vault collection

  • Specify a kmsProviders object

  • If you use MongoDB Community Server, set the bypassAutoEncryption option to True

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:

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>"]
}
1

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:

2

The following code snippets show how to create a ClientEncryption instance:

3

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:

4

The following code snippets show how to retrieve your inserted document and manually decrypt the encrypted fields:

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.

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.

←  Automatic EncryptionEncryption Schemas →