/ /

In-Use Encryption

Overview

You can use the Node.js driver to encrypt specific document fields by using a set of features called in-use encryption. In-use encryption allows your application to encrypt data before sending it to MongoDB and query documents with encrypted fields.

Warning

MongoDB 8.2 Known Issue

Version 8.2.0 of mongocryptd might not run on Windows. This bug affects In-Use Encryption with the driver if you specify the --logpath NUL argument when starting mongocryptd.

To learn more about this issue and how to resolve it, see Known Issues in the MongoDB 8.2 Release Notes.

In-use encryption prevents unauthorized users from viewing plaintext data as it is sent to MongoDB or while it is in an encrypted database. To enable in-use encryption in an application and authorize it to decrypt data, you must create encryption keys that only your application can access. Only applications that have access to your encryption keys can access the decrypted, plaintext data. If an attacker gains access to the database, they can only see the encrypted ciphertext data because they lack access to the encryption keys.

You might use in-use encryption to encrypt fields in your MongoDB documents that contain the following types of sensitive data:

Credit card numbers
Addresses
Health information
Financial information
Any other sensitive or personally identifiable information (PII)

MongoDB offers the following features to enable in-use encryption:

Queryable Encryption
Client-side Field Level Encryption

Queryable Encryption

Queryable Encryption is the next-generation in-use encryption feature, first introduced as a preview feature in MongoDB Server version 6.0 and as a generally available (GA) feature in MongoDB Server version 7.0. Queryable Encryption supports searching encrypted fields for equality and encrypts each value uniquely.

Important

Preview Feature Incompatible with MongoDB Server 7.0

The implementation of Queryable Encryption in MongoDB Server 6.0 is incompatible with the GA version introduced in MongoDB Server 7.0. The Queryable Encryption preview feature is no longer supported.

To learn more about Queryable Encryption, see Queryable Encryption in the MongoDB Server manual.

Client-side Field Level Encryption

Client-side Field Level Encryption (CSFLE) was introduced in MongoDB Server version 4.2 and supports searching encrypted fields for equality. CSFLE differs from Queryable Encryption in that you can select either a deterministic or random encryption algorithm to encrypt fields. You can only query encrypted fields that use a deterministic encryption algorithm when using CSFLE. When you use a random encryption algorithm to encrypt fields in CSFLE, they can be decrypted, but you cannot perform equality queries on those fields. When you use Queryable Encryption, you cannot specify the encryption algorithm, but you can query all encrypted fields.

When you deterministically encrypt a value, the same input value produces the same output value. While deterministic encryption allows you to perform queries on those encrypted fields, encrypted data with low cardinality is susceptible to code breaking by frequency analysis.

Tip

To learn more about these concepts, see the following Wikipedia entries:

To learn more about CSFLE, see CSFLE in the Server manual.

Aggregation Pipeline Support

Starting in MongoDB Server 8.1, you can use the $lookup aggregation stage with clients configured for in-use encryption. This feature requires mongodb-client-encryption package version 6.3.0 or later.

The $lookup stage allows you to join related data across encrypted collections without having to fetch and combine documents manually in your application code. Both the source collection and the from collection must be configured for in-use encryption. The fields specified in localField and foreignField must not be encrypted fields.

The following example shows a $lookup operation on an encrypted collection:

const pipeline = [
  {
    $lookup: {
      from: "encryptedCollection",
      localField: "userId",
      foreignField: "_id",
      as: "userDetails"
    }
  }
];
const results = await collection.aggregate(pipeline).toArray();

Back

Kerberos (GSSAPI)

TLS Security Protocol