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:您可以在MongoDB Server 7.0或更高版本的副本集或分片集群上使用可查询加密，但不能在独立实例上使用。下表显示了哪些MongoDB服务器产品支持哪些可查询加密机制：

Product Name产品名称Minimum Version最低版本Supports Queryable Encryption with Automatic Encryption支持带自动加密的可查询加密Supports 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.可查询加密与MongoDB Atlas兼容，但与MongoDB搜索不兼容。

Driver Compatibility驱动程序兼容性

C

To use Queryable Encryption with the C driver, install the following components:要在C驱动程序中使用可查询加密，请安装以下组件：

  • Driver version 1.24.0 or later驱动程序版本1.24.0或更高版本
  • libmongocrypt version 1.8.0 or later
C++11

To use Queryable Encryption with the C++ driver, install the following components:要在C++驱动程序中使用可查询加密，请安装以下组件：

  • Driver version 3.8.0 or later驱动程序版本3.8.0或更高版本
  • 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.要将可查询加密与.NET/C#驱动程序一起使用，请安装驱动程序版本2.20.0或更高版本。

If you're using driver version 3.0 or later, you must also complete the following steps:如果您使用的是3.0或更高版本的驱动程序，还必须完成以下步骤：

  • Install the MongoDB.Driver.Encryption package from NuGet. This package enables automatic encryption.从NuGet安装MongoDB.Driver.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.如果应用程序在Linux上运行，请手动安装libmongocrypt。然后，将LIBMONGOCRYPT_PATH环境变量设置为libmongocrypt文件的绝对路径。
  • 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. 如果应用程序在64位Linux上运行，并且您使用的是3.4.3或更早版本的驱动程序，请将以下XML行添加到.csproj文件中。Change the value of the <MongoDriverEncryptionVersion> element to match the version of the MongoDB.Driver.Encryption package that you have installed.更改<MongoDriverEncryptionVersion>元素的值，以匹配您安装的MongoDBDriverEncryption包的版本。
<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:要使用Go驱动程序的可查询加密，请安装以下组件：

  • Driver version 1.12 or later驱动程序版本1.12或更高版本
  • libmongocrypt version 1.8.0 or later1.8.0或更高版本
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:要将Queryable Encryption与Java Sync驱动程序一起使用，请安装以下组件：

  • Driver version 4.10.0 or later驱动程序版本4.10.0或更高版本
  • mongodb-crypt version 1.8.0 or later1.8.0或更高版本
Node.js

To use Queryable Encryption with the Node.js driver, install the following components:要在Node.js驱动程序中使用Queryable Encryption，请安装以下组件：

  • Driver version 5.5.0 or later驱动程序版本5.5.0或更高版本
  • mongodb-client-encryption version 2.8.0 or later2.8.0或更高版本

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.如果您使用的是Node.js驱动程序的6.0或更高版本，则还必须使用mongodb-client-encryption的6.0或更新版本。

PHP

To use Queryable Encryption with the PHP driver, install driver version 1.16 or later.要在PHP驱动程序中使用可查询加密，请安装1.16或更高版本的驱动程序。

Python

To use Queryable Encryption with PyMongo, install the following components:要使用PyMongo的可查询加密，请安装以下组件：

  • Driver version 4.4 or later驱动程序版本4.4或更高版本
  • pymongocrypt version 1.6 or later1.6或更高版本
Ruby

To use Queryable Encryption with the Ruby driver, install the following components:要将Queryable Encryption与Ruby驱动程序一起使用，请安装以下组件：

  • Driver version 2.19 or later驱动程序版本2.19或更高版本
  • libmongocrypt-helper version 1.8.0 or later1.8.0或更高版本
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 later1.8.0或更高版本
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 later1.8.0或更高版本

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 LimitationsMongoDB支持限制

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. 这限制了MongoDB支持工程师可用的数据，特别是在分析查询性能时。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.以下部分描述了使用客户端字段级加密（CSFLE）与MongoDB服务器和所选驱动程序的兼容性要求。

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:您可以在副本集或分片集群上使用客户端字段级加密，但不能在独立实例上使用。下表显示了哪些MongoDB服务器产品支持哪些客户端字段级加密机制：

Product Name产品名称Minimum Version最低版本Supports CSFLE with Automatic Encryption支持具有自动加密功能的CSFLESupports CSFLE with Explicit Encryption支持具有显式加密的CSFLE
MongoDB AtlasAll supported MongoDB versions所有支持的MongoDB版本YesYes
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.要将客户端字段级加密和键旋转API与C驱动程序一起使用，请安装1.17.5或更高版本的驱动程序。

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.要将客户端字段级加密和键旋转API与C++驱动程序一起使用，请安装3.6.0或更高版本的驱动程序。

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.要将客户端字段级加密与.NET/C#驱动程序一起使用，请安装2.10.0或更高版本的驱动程序。若要使用键旋转API，请安装驱动程序版本2.17.1或更高版本。

If you're using driver version 3.0 or later, you must also complete the following steps:如果您使用的是3.0或更高版本的驱动程序，还必须完成以下步骤：

  • Install the MongoDB.Driver.Encryption package from NuGet. This package enables automatic encryption.从NuGet安装MongoDB.Driver.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.如果应用程序在Linux上运行，请手动安装libmongocrypt。然后，将LIBMONGOCRYPT_PATH环境变量设置为libmongocrypt文件的绝对路径。
  • 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.如果应用程序在64位Linux上运行，并且您使用的是3.4.3或更早版本的驱动程序，请将以下XML行添加到.csproj文件中。更改<MongoDriverEncryptionVersion>元素的值，以匹配您安装的MongoDB.Driver.Encryption包的版本。
<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.要使用Go驱动程序的客户端字段级加密，请安装驱动程序1.2或更高版本。要使用键旋转API，请安装libmongocrypt 1.5.2或更高版本。

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 Reactive Streams驱动程序一起使用，请安装1.12.0或更高版本的驱动程序。要使用键旋转API，请安装mongoodb-crypt 1.7.3或更高版本。

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.要将客户端字段级加密与Java Sync或Java Reactive Streams驱动程序一起使用，请安装3.10.0或更高版本的驱动程序。要使用键旋转API，请安装mongoodb-crypt 1.7.3或更高版本。

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.要在Node.js驱动程序中使用客户端字段级加密，请安装3.4.0或更高版本的驱动程序。要使用键旋转API，请安装mongodb-client-encryption版本2.2.0-2x。

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.如果您使用的是Node.js驱动程序的6.0或更高版本，则还必须使用mongodb-client-encryption的6.0或更新版本。

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.要将客户端字段级加密和键旋转API与PHP驱动程序一起使用，请安装驱动程序版本1.6.0或更高版本。

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.要在PyMongo中使用客户端字段级加密，请安装3.10.0或更高版本的驱动程序。要使用键轮换API，请安装pymongocrypt 1.3.1或更高版本。

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.要将客户端字段级加密和键旋转API与Ruby驱动程序一起使用，请安装2.12.1或更高版本的驱动程序。

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查询分析组件。