On this page

Overview¶

Learn how to use the **** mechanism of ().

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.

is available in the following MongoDB products

of version 4.2 or later:

MongoDB Community Server
MongoDB Enterprise Advanced
MongoDB Atlas

Use¶

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

Create a ClientEncryption Instance
Encrypt Fields in Read and Write Operations
Manually or Automatically Decrypt Fields in Your Documents

Create a ClientEncryption Instance¶

To use , you must create a ClientEncryption instance. ClientEncryption is an abstraction used across drivers and mongosh that encapsulates the and operations involved in .

To create a ClientEncryption instance, you must specify the following information:

A MongoClient instance with access to your
The namespace of your
A kmsProviders object configured with access to the

hosting your

For more ClientEncryption options, see -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 .

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
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:

Example¶

Assume you want to insert documents with the following structure into your MongoDB instance:

copy

{
  "name": "<name of person>",
  "age": <age of person>,
  "favorite-foods": ["<array of foods>"]
}

Server-Side Field Level Encryption Enforcement¶

MongoDB supports using schema validation to enforce encryption of specific fields in a collection.

A client performing with the 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 enforcement, see Server-Side Schema Enforcement.

Learn More¶

To learn more about s, s, and s, see Keys and Key Vaults.

← Automatic Encryption Encryption Schemas →