Docs Home → MongoDB Manual

How CSFLE Decrypts Documents

On this page

This page describes how CSFLE uses metadata from your Data Encryption Key and Customer Master Key to decrypt data.

Metadata Used for Decryption

When you encrypt data using CSFLE, the data you encrypt is stored as a BinData subtype 6 object that includes the following metadata:

  • The _id of the Data Encryption Key used to encrypt the data

  • The encryption algorithm used to encrypt the data

Data Encryption Keys contain metadata that describes what Customer Master Key was used to encrypt them.

Drivers and mongosh use this metadata to attempt to automatically decrypt your data.

Automatic Decryption Process

To automatically decrypt your data, your CSFLE-enabled client performs the following procedure:

  1. Check the BinData blob metadata of the field you intend to decrypt for the Data Encryption Key and encryption algorithm used to encrypt the value.

  2. Check the Key Vault collection configured in the current database connection for the specified Data Encryption Key. If the Key Vault collection does not contain the specified key, automatic decryption fails and the driver returns an error.

  3. Check the Data Encryption Key metadata for the Customer Master Key (CMK) used to encrypt the key material.

  4. Decrypt the Data Encryption Key. This process varies by KMS provider:

  5. Decrypt the BinData value using the decrypted Data Encryption Key and appropriate algorithm.

Applications with access to the MongoDB server that do not also have access to the required CMK and Data Encryption Keys cannot decrypt the BinData values.

Automatically Encrypted Read Behavior

For read operations, the driver encrypts field values in the query document using your encryption schema prior to issuing the read operation.

Your client application then uses the BinData metadata to automatically decrypt the document you receive from MongoDB.

To learn more about encryption schemas, see Encryption Schemas.

Learn More

To learn how to configure the database connection for Client-Side Field Level Encryption, see CSFLE-Specific MongoClient Options.

To learn more about the relationship between Data Encryption Keys and Customer Master Keys, see Keys and Key Vaults.