Docs Menu

Manual Encryption

On this page

Learn how to use the manual encryption mechanism of Client-Side Field Level Encryption (CSFLE).

Manual 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.

Manual encryption is available in the following MongoDB products of version 4.2 or later:

  • MongoDB Community Server
  • MongoDB Enterprise Advanced
  • MongoDB Atlas

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

To use manual 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 manual 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 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 manual 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, you must 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 manual 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 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 KMS Providers.

←  Automatic EncryptionEncryption Schemas →

Select your language

Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.