Choosing an In-Use Encryption Approach
On this page
MongoDB provides two approaches to In-Use Encryption: Queryable Encryption and Client-Side Field Level Encryption (CSFLE). When using either approach, you can also choose between automatic and explicit encryption.
About Queryable Encryption and CSFLE
Both Queryable Encryption and Client-Side Field Level Encryption (CSFLE) enable a client application to encrypt data before transporting it over the network. Sensitive data is transparently encrypted and decrypted by the client and only communicated to and from the server in encrypted form.
To compare features in detail, see Queryable Encryption Features and CSFLE Features.
Considerations
When implementing an application that uses Queryable Encryption or CSFLE, review the security considerations in this section.
For the limitations of each approach, see Queryable Encryption limitations or CSFLE limitations.
For MongoDB server and driver version compatibility, see Compatibility.
Security Considerations
CSFLE and Queryable Encryption do not provide any guarantees against adversaries with access to your Customer Master Key and Data Encryption Keys.
CSFLE and Queryable Encryption do not provide any guarantees against adversaries with arbitrary write access to collections containing encrypted data.
MongoDB uses schema validation to enforce encryption of specific fields in a collection. Without a client-side schema, the client downloads the server-side schema for the collection to determine which fields to encrypt. To avoid this issue, use client-side schema validation.
Because CSFLE and Queryable Encryption do not provide a mechanism to verify the integrity of a schema, relying on a server-side schema means trusting that the server's schema has not been tampered with. If an adversary compromises the server, they can modify the schema so that a previously encrypted field is no longer labeled for encryption. This causes the client to send plaintext values for that field.
For an example of CSFLE configuration for client and server-side schemas, see CSFLE Server-Side Field Level Encryption Enforcement.
Using Queryable Encryption and CSFLE
You can use Queryable Encryption, Client-Side Field Level Encryption, or both in your application. However, you can't use both approaches in the same collection.
Consider using Queryable Encryption in the following scenarios:
You are developing a new application and want to use the latest cryptographic advancements from MongoDB.
You expect users to run ranged, prefix, suffix, or substring queries against encrypted data.
Your application can use a single key for a given field, rather than requiring separate keys on a per-user or per-tenant basis.
There are situations where CSFLE may be a preferable solution:
Your application already uses CSFLE.
You need to use different keys for the same field. This is commonly encountered when separating tenants or using user-specific keys.
You need to be flexible with your data schema and potentially add more encrypted fields. Adding encrypted fields for Queryable Encryption requires rebuilding metadata collections and indexes.
Querying Encrypted Fields
Queryable Encryption supports equality and range queries on encrypted fields. Support for prefix, suffix, and substring queries with Queryable Encryption is under development.
Client-Side Field Level Encryption supports equality queries on deterministically encrypted fields.
For more information about supported query operators, see Supported Query Operators for Queryable Encryption and Supported Query Operators for CSFLE. For the full list of MongoDB query operators, see Query and Projection Operators.
Encryption Algorithms
The new encryption algorithm for Queryable Encryption uses randomized encryption based on structured encryption, which produces different encrypted output values from the same input.
For detailed information on MongoDB's approach to Queryable Encryption, see the Overview of Queryable Encryption and Design and Analysis of a Stateless Document Database Encryption Scheme whitepapers.
The CSFLE encryption algorithm supports both randomized encryption and deterministic encryption. However, it only supports querying fields that are encrypted deterministically. With deterministic encryption, a given input value always encrypts to the same output value.
Private Querying
MongoDB encrypts queries for both Queryable Encryption and Client-Side Field Level Encryption so that the server has no information on cleartext document or query values. With Queryable Encryption, private querying goes a step further and redacts logs and metadata to scrub information around the query's existence. This ensures stronger privacy and confidentiality.
Choosing Between Automatic and Explicit Encryption
Using Automatic Encryption
We recommend automatic encryption in most situations, as it streamlines the process of writing your client application. With automatic encryption, MongoDB automatically encrypts and decrypts fields in read and write operations.
Using Explicit Encryption
Explicit encryption provides fine-grained control over security, at the cost of increased complexity when configuring collections and writing code for MongoDB Drivers. With explicit encryption, you specify how to encrypt fields in your document for each operation you perform on the database, and you include this logic throughout your application.
For details, see Explicit Encryption with Queryable Encryption or Explicit Encryption with CSFLE.