Database Manual / Security / Encryption / In-Use Encryption

Compatibility兼容性

Queryable Encryption equality and range queries are fully supported in production. Prefix, suffix, and substring queries are only available in public preview in MongoDB 8.2. Do not enable these query types in production. GA functionality of prefix, suffix and substring query types will be incompatible with the preview feature.可查询的加密相等性和范围查询在生产环境中得到了完全支持。前缀、后缀和子字符串查询仅在MongoDB 8.2的公共预览中可用。不要在生产环境中启用这些查询类型。前缀、后缀和子字符串查询类型的GA功能将与预览功能不兼容。

This page describes the MongoDB Server editions and driver versions compatible with Queryable Encryption and Client-Side Field Level Encryption to help you determine whether your deployment supports each in-use encryption feature.此页面描述了与可查询加密和客户端字段级加密兼容的MongoDB服务器版本和驱动程序版本，以帮助您确定部署是否支持每种正在使用的加密功能。

➤ Use the Select your language drop-down menu to select your driver and see its compatibility with Queryable Encryption and Client-Side Field Level Encryption.使用“选择语言”下拉菜单选择驱动程序，并查看其与可查询加密和客户端字段级加密的兼容性。

Queryable Encryption Compatibility可查询的加密兼容性

The following sections describe the compatibility requirements for using Queryable Encryption with MongoDB Server and your selected driver.以下部分描述了使用MongoDB服务器和所选驱动程序的可查询加密的兼容性要求。

MongoDB CompatibilityMongoDB兼容性

You can use Queryable Encryption on a MongoDB Server 7.0 or later replica set or sharded cluster, but not a standalone instance. The following table shows which MongoDB Server products support which Queryable Encryption mechanisms:

Product NameMinimum VersionSupports Queryable Encryption with Automatic EncryptionSupports Queryable Encryption with Explicit Encryption
MongoDB Atlas [1]7.0YesYes
MongoDB Enterprise Advanced7.0YesYes
MongoDB Community Edition7.0NoYes
[1] Queryable Encryption is compatible with MongoDB Atlas but not MongoDB Search.

Driver Compatibility

C

To use Queryable Encryption with the C driver, install the following components:

  • Driver version 1.24.0 or later
  • libmongocrypt version 1.8.0 or later
C++11

To use Queryable Encryption with the C++ driver, install the following components:

  • Driver version 3.8.0 or later
  • libmongocrypt version 1.8.0 or later
C#

To use Queryable Encryption with the .NET/C# driver, install driver version 2.20.0 or later.

If you're using driver version 3.0 or later, you must also complete the following steps:

  • Install the MongoDB.Driver.Encryption package from NuGet. This package enables automatic encryption.
  • If your application runs on Linux, install libmongocrypt manually. Then, set the LIBMONGOCRYPT_PATH environment variable to the absolute path of the libmongocrypt file.
  • If your application runs on 64-bit Linux, and you're using driver version 3.4.3 or earlier, add the following lines of XML to your .csproj file. Change the value of the <MongoDriverEncryptionVersion> element to match the version of the MongoDB.Driver.Encryption package that you have installed.
<PropertyGroup>
    <!-- replace the version here with your package version -->
    <MongoDriverEncryptionVersion>3.4.2</MongoDriverEncryptionVersion>
    <MongoDriverEncryptionPath>$(NuGetPackageRoot)mongodb.driver.encryption\$(MongoDriverEncryptionVersion)</MongoDriverEncryptionPath>
</PropertyGroup>
<PropertyGroup>
    <!-- Suppresses the duplicate file error -->
    <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>
<!-- Ensures the correct library after build or publish -->
<Target Name="EnsureCorrectMongoEncryption" AfterTargets="Build;Publish" Condition="'$(RuntimeIdentifier)' != ''">
    <!-- Determine paths based on current operation -->
    <PropertyGroup>
        <_TargetDir Condition="Exists('$(PublishDir)')">$(PublishDir)</_TargetDir>
        <_TargetDir Condition="'$(_TargetDir)' == ''">$(OutputPath)</_TargetDir>
    </PropertyGroup>
    <!-- Copy the correct library based on runtime identifier (RID) -->
    <ItemGroup>
        <_CorrectMongoLib Include="$(MongoDriverEncryptionPath)/runtimes/linux/native/x64/libmongocrypt.so"
                          Condition="'$(RuntimeIdentifier)' == 'linux-x64'" />
        <_CorrectMongoLib Include="$(MongoDriverEncryptionPath)/runtimes/linux/native/arm64/libmongocrypt.so"
                          Condition="'$(RuntimeIdentifier)' == 'linux-arm64'" />
        <_CorrectMongoLib Include="$(MongoDriverEncryptionPath)/runtimes/linux/native/alpine/libmongocrypt.so"
                          Condition="'$(RuntimeIdentifier)' == 'linux-musl-arm64'" />
    </ItemGroup>
    <!-- Copy with overwrite -->
    <Copy SourceFiles="@(_CorrectMongoLib)"
          DestinationFolder="$(_TargetDir)"
          Condition="'@(_CorrectMongoLib)' != ''"
          OverwriteReadOnlyFiles="true" />
    <Message Text="Fixed MongoDB encryption library for $(RuntimeIdentifier)"
             Condition="'@(_CorrectMongoLib)' != ''" />
</Target>
Go

To use Queryable Encryption with the Go driver, install the following components:

  • Driver version 1.12 or later
  • libmongocrypt version 1.8.0 or later
Java(Async)

To use Queryable Encryption with the Java Reactive Streams driver, install the following components:

  • Driver version 4.10.0 or later
  • mongodb-crypt version 1.8.0 or later
Java(Sync)

To use Queryable Encryption with the Java Sync driver, install the following components:

  • Driver version 4.10.0 or later
  • mongodb-crypt version 1.8.0 or later
Node.js

To use Queryable Encryption with the Node.js driver, install the following components:

If you're using version 6.0 or later of the Node.js driver, you must also use version 6.0 or later of mongodb-client-encryption.

PHP

To use Queryable Encryption with the PHP driver, install driver version 1.16 or later.

Python

To use Queryable Encryption with PyMongo, install the following components:

  • Driver version 4.4 or later
  • pymongocrypt version 1.6 or later
Ruby

To use Queryable Encryption with the Ruby driver, install the following components:

Rust

To use Queryable Encryption with the Rust driver, install the following components:

  • Driver version 2.4.0 or later驱动程序版本2.4.0或更高版本
  • libmongocrypt version 1.8.0 or later
scala

To use Queryable Encryption with the Scala driver, install the following components:

  • Driver version 4.10.0 or later驱动程序版本4.10.0或更高版本
  • mongodb-crypt version 1.8.0 or later

Important

Automatic Encryption Support自动加密支持

To use Queryable Encryption with automatic encryption, you must install a query analysis component. To learn more, see Install and Configure a Query Analysis Component.要使用带自动加密的可查询加密，您必须安装查询分析组件。要了解更多信息，请参阅安装和配置查询分析组件。

MongoDB Support Limitations

Enabling Queryable Encryption on a collection redacts fields from some diagnostic commands and omits some operations from the query log. This limits the data available to MongoDB support engineers, especially when analyzing query performance. To measure the impact of operations against encrypted collections, use a third party application performance monitoring tool to collect metrics.

Client-Side Field Level Encryption Compatibility

The following sections describe the compatibility requirements for using Client-Side Field Level Encryption (CSFLE) with MongoDB Server and your selected driver.

MongoDB Compatibility

You can use Client-Side Field Level Encryption on a replica set or sharded cluster, but not a standalone instance. The following table shows which MongoDB Server products support which Client-Side Field Level Encryption mechanisms:

Product NameMinimum VersionSupports CSFLE with Automatic EncryptionSupports CSFLE with Explicit Encryption
MongoDB AtlasAll supported MongoDB versionsYesYes
MongoDB Enterprise Advanced4.2YesYes
MongoDB Community Edition4.2NoYes

Driver Compatibility

C

To use Client-Side Field Level Encryption and the Key Rotation API with the C driver, install driver version 1.17.5 or later.

C++11

To use Client-Side Field Level Encryption and the Key Rotation API with the C++ driver, install driver version 3.6.0 or later.

C#

To use Client-Side Field Level Encryption with the .NET/C# driver, install driver version 2.10.0 or later. To use the Key Rotation API, install driver version 2.17.1 or later.

If you're using driver version 3.0 or later, you must also complete the following steps:

  • Install the MongoDB.Driver.Encryption package from NuGet. This package enables automatic encryption.
  • If your application runs on Linux, install libmongocrypt manually. Then, set the LIBMONGOCRYPT_PATH environment variable to the absolute path of the libmongocrypt file.
  • If your application runs on 64-bit Linux, and you're using driver version 3.4.3 or earlier, add the following lines of XML to your .csproj file. Change the value of the <MongoDriverEncryptionVersion> element to match the version of the MongoDB.Driver.Encryption package that you have installed.
<PropertyGroup>
    <!-- replace the version here with your package version -->
    <MongoDriverEncryptionVersion>3.4.2</MongoDriverEncryptionVersion>
    <MongoDriverEncryptionPath>$(NuGetPackageRoot)mongodb.driver.encryption\$(MongoDriverEncryptionVersion)</MongoDriverEncryptionPath>
</PropertyGroup>
<PropertyGroup>
    <!-- Suppresses the duplicate file error -->
    <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>
<!-- Ensures the correct library after build or publish -->
<Target Name="EnsureCorrectMongoEncryption" AfterTargets="Build;Publish" Condition="'$(RuntimeIdentifier)' != ''">
    <!-- Determine paths based on current operation -->
    <PropertyGroup>
        <_TargetDir Condition="Exists('$(PublishDir)')">$(PublishDir)</_TargetDir>
        <_TargetDir Condition="'$(_TargetDir)' == ''">$(OutputPath)</_TargetDir>
    </PropertyGroup>
    <!-- Copy the correct library based on runtime identifier (RID) -->
    <ItemGroup>
        <_CorrectMongoLib Include="$(MongoDriverEncryptionPath)/runtimes/linux/native/x64/libmongocrypt.so"
                          Condition="'$(RuntimeIdentifier)' == 'linux-x64'" />
        <_CorrectMongoLib Include="$(MongoDriverEncryptionPath)/runtimes/linux/native/arm64/libmongocrypt.so"
                          Condition="'$(RuntimeIdentifier)' == 'linux-arm64'" />
        <_CorrectMongoLib Include="$(MongoDriverEncryptionPath)/runtimes/linux/native/alpine/libmongocrypt.so"
                          Condition="'$(RuntimeIdentifier)' == 'linux-musl-arm64'" />
    </ItemGroup>
    <!-- Copy with overwrite -->
    <Copy SourceFiles="@(_CorrectMongoLib)"
          DestinationFolder="$(_TargetDir)"
          Condition="'@(_CorrectMongoLib)' != ''"
          OverwriteReadOnlyFiles="true" />
    <Message Text="Fixed MongoDB encryption library for $(RuntimeIdentifier)"
             Condition="'@(_CorrectMongoLib)' != ''" />
</Target>
Go

To use Client-Side Field Level Encryption with the Go driver, install driver version 1.2 or later. To use the Key Rotation API, install libmongocrypt version 1.5.2 or later.

Java(Async)

To use Client-Side Field Level Encryption with the Java Reactive Streams driver, install driver version 1.12.0 or later. To use the Key Rotation API, install mongodb-crypt version 1.7.3 or later.

Java(Sync)

To use Client-Side Field Level Encryption with the Java Sync or Java Reactive Streams driver, install driver version 3.10.0 or later. To use the Key Rotation API, install mongodb-crypt version 1.7.3 or later.

Node.js

To use Client-Side Field Level Encryption with the Node.js driver, install driver version 3.4.0 or later. To use the Key Rotation API, install mongodb-client-encryption version 2.2.0 - 2.x.

If you're using version 6.0 or later of the Node.js driver, you must also use version 6.0 or later of mongodb-client-encryption.

PHP

To use Client-Side Field Level Encryption and the Key Rotation API with the PHP driver, install driver version 1.6.0 or later.

Python

To use Client-Side Field Level Encryption with PyMongo, install driver version 3.10.0 or later. To use the Key Rotation API, install pymongocrypt version 1.3.1 or later.

Ruby

To use Client-Side Field Level Encryption and the Key Rotation API with the Ruby driver, install driver version 2.12.1 or later.

Rust

To use Client-Side Field Level Encryption with the Rust driver, install driver version 2.4.0 or later. To use the Key Rotation API, install libmongocrypt version 1.8.0 or later.

scala

To use Client-Side Field Level Encryption and the Key Rotation API with the Scala driver, install driver version 2.7.0 or later.

To learn more about the Key Rotation API, see Rotate and Rewrap Encryption Keys.要了解有关键旋转API的更多信息，请参阅旋转和重新缠绕加密键。

Important

Automatic Encryption Support自动加密支持

To use Client-Side Field Level Encryption with automatic encryption, you must install a query analysis component. To learn more, see Install and Configure a CSFLE Query Analysis Component.要将客户端字段级加密与自动加密一起使用，您必须安装查询分析组件。要了解更多信息，请参阅安装和配置CSFLE查询分析组件。