Docs 菜单
Docs 主页
/
MongoDB Manual
/
安全性
/
加密
/
正在使用的加密
/
客户端字段级加密 (Client-Side Field Level Encryption)
/
参考

安装和配置 CSFLE 库

在此页面上

  • 开始之前
  • 步骤

MongoDB可以使用两个库之一进行客户端字段级加密(CSFLE)。 推荐的库是自动加密共享库。

开始之前

要将 CSFLE 与自动加密结合使用，必须首先选择希望MongoDB用于加密字段的库。

  • crypt_shared ，推荐的 CSFLE 库。

  • mongocryptd ，包含在MongoDB Enterprise Server 安装中。

两者都需要 libmongocrypt 库。有关更多信息，请参阅 为 CSFLE 安装 libmongocrypt。

自动加密共享库

自动加密共享库是一个动态库，使您的客户端应用程序能够执行自动加密。 动态库是应用程序在运行时而不是编译时访问的一设立功能。 自动加密共享库执行以下任务：

  • 读取加密模式以确定要加密或解密的字段

  • 防止应用程序对加密字段执行不支持的操作

自动加密共享库不 执行任何以下操作：

  • 进行数据加密或解密

  • 访问加密密钥材料

  • 在网络上侦听数据

自动加密共享库是 mongocryptd 的首选替代方案，并且不要求您生成另一个进程以执行自动加密。

注意

虽然我们建议使用自动加密共享库，但仍支持 mongocryptd。

要了解有关自动加密的更多信息，请参阅功能。

mongocryptd

mongocryptd 随MongoDB Enterprise Server 一起安装。

当您创建启用了 CSFLE 的 MongoDB 客户端时，默认情况下会自动启动mongocryptd进程。

mongocryptd 进程：

  • 使用指定的自动加密规则对读写操作中的字段进行标记，以便加密。

  • 防止在加密字段上执行不支持的操作。

  • 分析为数据库连接指定的加密模式。自动加密规则使用严格的 JSON Schema 语法子集。如果规则包含无效的自动加密语法或任何 document validation 语法，mongocryptd 将返回错误。

mongocryptd 仅执行上述功能，不执行以下任何操作：

  • mongocryptd 不进行加密或解密

  • mongocryptd 不访问任何加密密钥材料

  • mongocryptd 不监听网络

为了执行字段加密和自动解密，驱动程序使用 Apache 许可的 libmongocrypt 库。

官方MongoDB驱动程序需要访问权限客户端托管上的 mongocryptd进程。这些客户端默认在系统 PATH 中搜索mongocryptd进程。

步骤

1

下载自动加密共享库

从 MongoDB 下载中心下载自动加密共享库，方法是先选择版本和平台，然后选择库：

  1. 在 Version下拉列表中，选择标记为“当前”的版本。

  2. 在 Platform 下拉列表中，选择您的平台。

  3. 在 Package 下拉菜单中，选择 crypt_shared。

  4. 单击 Download（连接）。

提示

要查看可用版本和软件包的扩展列表，请参阅MongoDB Enterprise 下载。

2

配置自动加密共享库

您可以通过以下参数，配置驱动程序搜索自动加密共享库的方式：

名称
说明

cryptSharedLibPath

指定自动加密共享库包crypt_shared的绝对路径。

默认：undefined。

cryptSharedLibRequired

指定驾驶员是否必须使用自动加密共享库。 如果为 true，则当自动加密共享库不可用时，驾驶员会引发错误。如果为 false，则驾驶员将执行以下操作序列：

  1. 尝试使用自动加密共享库。

  2. 如果自动加密共享库不可用，则驱动程序尝试生成并连接到 mongocryptd。

默认：false。

要查看说明如何配置这些参数的示例，请参阅快速入门。

1

安装 mongocryptd

对于支持的Linux操作系统：要安装MongoDB Server包，请按照在Linux上安装教程并安装 mongodb-enterprise 服务器包。 或者，指定mongodb-enterprise-cryptd以仅安装mongocryptd二进制文件。 包管理器将二进制文件安装到系统 PATH 中的某个位置。

对于 OSX：要安装MongoDB Server包，请按照MacOS 上的安装教程进行操作。 包管理器将二进制文件安装到系统 PATH 中的某个位置。

对于Windows ：要安装MongoDB Server包，请按照在Windows上安装教程进行操作。 安装后，您必须将mongocryptd包添加到系统路径中。 按照 Windows 安装记录的最佳实践将mongocryptd二进制文件添加到系统 PATH。

要从官方 tarball/ZIP 存档安装：要从官方存档安装，请遵循适用于您的操作系统的最佳实践，将mongocryptd二进制文件添加到系统路径。

2

配置 mongocryptd

如果驱动程序有权访问 mongocryptd 进程，则默认情况下会生成该进程。

重要

引导时启动

如果可能的话，在启动时启动 mongocryptd，而不是按需启动。

通过以下参数配置驱动程序启动 mongocryptd 的方式：

名称
说明

端口

The port from which mongocryptd listens for messages.
Default: 27020

idleShutdownTimeoutSecs

Number of idle seconds the mongocryptd process waits before exiting.
Default: 60

mongocryptdURI

The URI on which to run the mongocryptd process.
Default: "mongodb://localhost:27020"

mongocryptdBypassSpawn

When true, prevents the driver from automatically spawning mongocryptd.
Default: false

mongocryptdSpawnPath

The full path to mongocryptd.
Default: Defaults to empty string and spawns from the system path.

如果 mongocryptd 进程已在驱动程序指定的端口上运行，则驱动程序可能会记录警告，并在不生成新进程的情况下继续运行。驱动程序指定的任何设置仅在现有进程退出并且新的加密客户端尝试连接时才适用。

例子

要查看如何配置 mongocryptd 进程的示例，请单击与应用程序中使用的驱动程序对应的标签页：

以下代码片段设置 mongocryptd 的监听端口配置：

var extraOptions = new Dictionary<string, object>()
{
    { "mongocryptdSpawnArgs", new [] { "--port=30000" } },
};
autoEncryptionOptions.With(extraOptions: extraOptions);

以下代码片段设置 mongocryptd 的默认超时配置：

var extraOptions = new Dictionary<string, object>()
{
    { "idleShutdownTimeoutSecs", 60 },
};
autoEncryptionOptions.With(extraOptions: extraOptions);

以下代码片段设置 mongocryptd 的监听端口配置：

extraOptions := map[string]interface{}{
    "mongocryptdSpawnArgs": []string{
        "--port=30000",
    },
}

以下代码片段设置 mongocryptd 的默认超时配置：

extraOptions := map[string]interface{}{
    "mongocryptdSpawnArgs": []string{
        "--idleShutdownTimeoutSecs=75",
    },
}

以下代码片段设置 mongocryptd 的监听端口配置：

List<String> spawnArgs = new ArrayList<String>();
spawnArgs.add("--port=30000");
Map<String, Object> extraOpts = new HashMap<String, Object>();
extraOpts.put("mongocryptdSpawnArgs", spawnArgs);
AutoEncryptionSettings autoEncryptionSettings = AutoEncryptionSettings.builder()
    ...
    .extraOptions(extraOpts);

以下代码片段设置 mongocryptd 的默认超时配置：

List<String> spawnArgs = new ArrayList<String>();
spawnArgs.add("--idleShutdownTimeoutSecs")
    .add("60");
Map<String, Object> extraOpts = new HashMap<String, Object>();
extraOpts.put("mongocryptdSpawnArgs", spawnArgs);
AutoEncryptionSettings autoEncryptionSettings = AutoEncryptionSettings.builder()
    ...
    .extraOptions(extraOpts);

以下代码片段设置 mongocryptd 的监听端口配置：

autoEncryption: {
  ...
  extraOptions: {
    mongocryptdSpawnArgs: ["--port", "30000"],
    mongocryptdURI: 'mongodb://localhost:30000',
  }

注意

在 NodeJS 驱动程序中，mongocryptdURI 必须与侦听端口匹配。

以下代码片段设置 mongocryptd 的默认超时配置：

autoEncryption: {
  ...
  extraOptions: {
    mongocryptdSpawnArgs: ["--idleShutdownTimeoutSecs", "75"]
  }

以下代码片段设置 mongocryptd 的监听端口配置：

auto_encryption_opts = AutoEncryptionOpts(mongocryptd_spawn_args=['--port=30000'])

以下代码片段设置 mongocryptd 的默认超时配置：

auto_encryption_opts = AutoEncryptionOpts(mongocryptd_spawn_args=['--idleShutdownTimeoutSecs=75'])

后退

密码学

来年

使用 libmongocrypt

在此页面上