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

CSFLE KMS 提供商

在此页面上

  • Overview
  • 密钥管理系统任务
  • 创建并存储您的客户主密钥
  • 创建和加密数据加密密钥
  • 支持的密钥管理服务
  • Amazon Web Services KMS
  • Azure Key Vault
  • Google Cloud Platform KMS
  • KMIP
  • 本地密钥提供程序

Overview

了解客户端字段级加密 (CSFLE) 支持的密钥管理系统 (KMS) 提供程序。

密钥管理系统任务

在 CSFLE 中，密钥管理系统执行以下任务：

  • 创建和存储客户主密钥

  • 创建并加密您的数据加密密钥

要了解有关客户主密钥和数据加密密钥的更多信息，请参阅密钥和密钥保管库。

创建并存储您的客户主密钥

要创建客户主密钥，您必须配置密钥管理系统以生成客户主密钥，如下所示：

示意图

要查看说明如何在所需的 KMS 中创建和存储 CMK 的教程，请参阅教程。

创建和加密数据加密密钥

创建数据加密密钥时，您必须执行以下操作：

  • 在启用了 CSFLE 的应用程序中实例化一个 ClientEncryption 实例：

    • 提供一个 kmsProviders 对象，以指定启用了 CSFLE 的应用程序在 KMS 提供程序中进行身份验证时使用的凭证。

  • 使用启用了 CSFLE 的应用程序中 ClientEncryption 对象的 CreateDataKey 方法创建数据加密密钥。

    • 提供一个 dataKeyOpts 对象，指定您的 KMS 应使用哪个密钥来加密该新数据加密密钥。

要查看说明如何创建和加密数据加密密钥的教程，请参阅以下资源：

要查看所有支持的KMS提供商的kmsProviders和dataKeyOpts对象的结构，请参阅支持的密钥管理服务。

支持的密钥管理服务

本页的以下部分为所有密钥管理系统提供程序提供以下信息：

  • 启用了 CSFLE 的客户端的架构

  • kmsProviders 对象的结构

  • dataKeyOpts 对象的结构

CSFLE 支持以下密钥管理系统提供程序：

Amazon Web Services KMS

本节提供与使用 相关的信息 在启用了 CSFLEAmazon Web ServicesKMS 的应用程序中。

要查看如何在启用 CSFLE 的应用程序中使用 AWS KMS 的演示教程，请参阅通过 AWS 使用自动客户端字段级加密。

架构

下图描述了使用 AWS KMS 的启用了 CSFLE 的应用程序的架构。

KMS 图表

注意

客户端无法访问客户主密钥

在使用上述密钥管理系统时，启用了 CSFLE 的应用程序无权访问客户主密钥。

kmsProviders 对象

下表显示了 AWS KMS 的 kmsProviders 对象的结构：

字段
对 IAM 用户是必需的
IAM 角色必填项
说明
访问密钥 ID
是
是
标识该账户用户。
秘密访问密钥
是
是
包含账户用户的身份验证凭据。
Session Token
No
是
包含从 AWS Security Token Service (STS) 获取的令牌。

dataKeyOpts 对象

下表显示了 AWS KMS 的 dataKeyOpts 对象的结构：

字段
必需
说明
key
是
区域
No
主密钥的 AWS 地区，例如 "us-west-2"；仅当您的 ARN 中未指定时才为必填项。
端点
No
您的帐户的 AWS 端点的自定义主机名（如果配置）。

Azure Key Vault

本节接受有关在启用 CSFLE 的应用程序中使用 Azure Key Vault 的信息。

要查看说明如何在启用了 CSFLE 的应用程序中使用 Azure Key Vault 的教程，请参阅在 Azure 中使用自动客户端字段级加密。

架构

下图描述了使用 Azure Key Vault. 的启用了 CSFLE 的应用程序的架构。

KMS 图表

注意

客户端无法访问客户主密钥

在使用上述密钥管理系统时，启用了 CSFLE 的应用程序无权访问客户主密钥。

kmsProviders 对象

下表显示了 Azure Key Vault 的 kmsProviders 对象的结构：

字段
必需
说明
azure.tenantId
是
标识帐户的组织。
azure.clientId
是
指定 clientId 以对注册的应用程序进行身份验证。
azure.clientSecret
是
用于对注册的应用程序进行身份验证。
azure.identityPlatformEndpoint
No
指定身份验证服务器的主机名和端口号。默认为 login.microsoftonline.com，仅非商业 Azure 实例需要使用该字段，例如政府或中国帐户。

dataKeyOpts 对象

下表显示了 Azure Key Vault 的 dataKeyOpts 对象的结构：

字段
必需
说明
keyName
是
主密钥名称
keyVersion
否，但强烈建议
主密钥版本
keyVaultEndpoint
是
密钥库的 URL。例如 myVaultName.vault.azure.net

警告

如果不包含 keyVersion 字段，则 Azure Key Vault 尝试使用最新的客户主密钥对数据加密密钥进行解密。如果您轮换 CMK，但未使用新的主密钥重新包装数据加密密钥，尝试解密现有的 DEK 将失败，因为 DEK 是使用以前版本的 CMK 加密的。

Google Cloud Platform KMS

本节提供有关在启用了 CSFLE 的应用程序中使用 Google Cloud Key Management 的信息。

要查看说明如何在启用了 CSFLE 的应用程序中使用 GCP KMS 的教程，请参阅在 GCP 中使用自动客户端字段级加密。

架构

下图描述了使用 GCP KMS 且启用了 CSFLE 的应用程序的架构。

KMS 图表

注意

客户端无法访问客户主密钥

在使用上述密钥管理系统时，启用了 CSFLE 的应用程序无权访问客户主密钥。

kmsProviders 对象

下表显示了 GCP KMS 的kmsProviders对象的结构：

字段
必需
说明
电子邮件
是
标识您的服务帐户电子邮件地址。
privateKey
是
Identifies your service account private key in either base64 string or Binary subtype 0 format without the prefix and suffix markers.

Suppose your service account private key value is as follows:
-----BEGIN PRIVATE KEY-----\nyour-private-key\n-----END PRIVATE KEY-----\n
The value you would specify for this field is:
your-private-key
If you have a user-key.json credential file, you can extract the string by executing the following command in a bash or similar shell. The following command requires that you install OpenSSL:
cat user-key.json | jq -r .private_key | openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER | base64 -w 0
端点
No
指定身份验证服务器的主机名和端口号。默认为 oauth2.googleapis.com。

dataKeyOpts 对象

下表显示了 GCP KMS 的dataKeyOpts对象的结构：

字段
必需
说明
projectId
是
在其中创建密钥的项目的标识符。
位置
是
为密钥指定的区域。
keyRing
是
您的密钥所属的密钥群组的标识符。
keyName
是
对称主密钥的标识符。
keyVersion
No
指定命名密钥的版本。 如果未指定，则使用默认的密钥版本。
端点
No
指定 Cloud KMS 的主机和可选端口。默认为 cloudkms.googleapis.com。

KMIP

本节提供有关在启用了 CSFLE 的应用程序中使用 KMIP 兼容密钥管理系统的信息。

要查看如何在启用 CSFLE 的应用程序中使用符合 KMIP 的密钥管理系统的演示教程，请参阅通过 KMIP 使用自动客户端字段级加密。

架构

下图描述了使用 KMIP 兼容密钥提供程序且启用了 CSFLE 的应用程序的架构。

示意图

重要

客户端访问客户主密钥

当启用 CSFLE 的应用程序使用符合 KMIP 的密钥提供者时，该应用程序将直接访问您的客户主密钥。

kmsProviders 对象

下表显示 KMIP 兼容密钥提供程序的 kmsProviders 对象的结构：

注意

通过 TLS/SSL 进行身份验证

使用 KMIP 时，启用 CSFLE 的应用程序通过 TLS/SSL 进行身份验证。

字段
必需
说明
端点
是
指定身份验证服务器的主机名和端口号。

dataKeyOpts 对象

下表显示了符合 KMIP 的密钥管理系统的dataKeyOpts对象的结构：

字段
必需
说明
keyId
No

keyId96字节 密钥数据托管对象 的 字段 存储在符合 KMIP 的密钥提供程序中。

如果您在发送到 KMIP 兼容密钥提供程序的 masterKey 文档中未指定 keyId 字段，则驱动程序在 KMIP 兼容密钥提供程序中创建新的 96 字节密钥数据管理对象以作为主密钥。

端点
是
KMIP 兼容密钥提供程序的 URI。

本地密钥提供程序

本节提供有关在启用了 CSFLE 的应用程序中使用本地密钥提供程序（文件系统）的信息。

警告

不要在生产环境中使用本地密钥提供程序

本地密钥提供程序是一种不安全的存储方法，建议不要用于生产环境。相反，应将客户主密钥存储在远程密钥管理系统 (KMS) 中。

要了解如何在 CSFLE 实施中使用远程 KMS，请参阅教程指南。

要查看如何使用本地密钥提供者测试客户端字段级加密的教程，请参阅快速入门。

架构

当您在启用 CSFLE 的应用程序中使用本地密钥提供者时，您的应用程序将从运行应用程序的计算机的文件系统中检索您的客户主密钥。

下图描述使用本地密钥提供程序且启用了 CSFLE 的应用程序的架构。

本地密钥提供程序架构图。

kmsProviders 对象

下表显示了本地密钥提供者的 kmsProviders 对象的结构：

字段
必需
说明
key
是
用于加密/解密数据密钥的主密钥。主密钥以 base64 编码字符串的形式传递。

dataKeyOpts 对象

在使用本地密钥提供程序时，您可以通过 kmsProviders 对象指定客户主密钥。

后退

MongoClientOptions

来年

组件