Navigation

How CSFLE Decrypts Documents

On this page

This page describes how uses metadata from your
and to decrypt data.

Metadata Used for Decryption

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

  • The _id of the used to encrypt the data
  • The encryption algorithm used to encrypt the data

s contain metadata that describes what 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 -enabled client performs the following procedure:

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

  2. Check the configured in the current database connection for the specified . If the does not contain the specified key, automatic decryption fails and the driver returns the encrypted BinData blob.

  3. Check the metadata for the (CMK) used to encrypt the key material.

  4. Decrypt the . This process varies by KMS provider:

    For the Amazon Web Services (AWS) KMS, send the to your AWS KMS instance for decryption. If the CMK does not exist or if the connection configuration does not grant access to the CMK, decryption fails and the driver returns the encrypted BinData blob.

    Tip

    To learn how to use the Amazon Web Services KMS for automatic encryption, see Use Automatic with AWS.

    For the Google Cloud Platform (GCP) KMS, send the to your GCP KMS instance for decryption. If the CMK does not exist or if the connection configuration does not grant access to the CMK, decryption fails and the driver returns the encrypted BinData blob.

    Tip

    To learn how to use the Google Cloud Platform KMS for automatic encryption, see Use Automatic with GCP.

    For the Azure Key Vault, send the to the your Azure Key Vault instance for decryption. If the CMK does not exist or if the connection configuration does not grant access to the CMK, decryption fails and the driver returns the encrypted BinData blob.

    Tip

    To learn how to use the Azure Key Vault for automatic encryption, see Use Automatic with Azure.

    For a KMIP-compliant KMS, retrieve the CMK from the KMS and then use the CMK locally to decrypt the . If the CMK does not exist or if the connection configuration does not grant access to the CMK, decryption fails and the driver returns the encrypted BinData blob.

    Tip

    To learn how to use a KMIP-compliant KMS for automatic encryption, see Use Automatic with KMIP.

    For a Local Key Provider, retrieve the CMK from your filesystem and use it to decrypt the . If the local key specified in the database configuration was not used to encrypt the , decryption fails and the driver returns the encrypted BinData blob.

    Warning

    Do Not Use the Local Key Provider in Production

    The Local Key Provider is an insecure method of storage and is not recommended for production. Instead, you should store your s in a remote :wikipedia:` <Key_management#Key_management_system>` (KMS).

    To learn how to use a remote KMS in your implementation, see the <csfle-tutorial-automatic-encryption> guide.

  5. Decrypt the BinData value using the decrypted

    and appropriate algorithm.

Applications with access to the MongoDB server that do not also have access to the required CMK and s 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 , see -Specific MongoClient Options.

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

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.