KMS Providers

Create and Store your Customer Master Key创建并存储客户主键

To create a Customer Master Key, configure your Key Management Service provider to generate your Customer Master Key as follows:要创建客户主键，请按如下方式配置键管理服务提供商以生成客户主键：

To view a tutorial that demonstrates how to create and store a CMK in your preferred Key Management Service, see Tutorials.要查看演示如何在首选键管理服务中创建和存储CMK的教程，请参阅教程。

Create and Encrypt a Data Encryption Key创建和加密数据加密键

To create a Data Encryption Key:要创建数据加密键：

• Instantiate a ClientEncryption instance in your Queryable Encryption enabled application:在启用可查询加密的应用程序中实例化ClientEncryption实例：
  • Provide a kmsProviders object that specifies the credentials your Queryable Encryption enabled application uses to authenticate with your KMS.提供一个kmsProviders对象，该对象指定启用可查询加密的应用程序用于向KMS进行身份验证的凭据。
• Create a Data Encryption Key with the CreateDataKey method of the ClientEncryption object in your Queryable Encryption enabled application.在启用可查询加密的应用程序中，使用ClientEncryption对象的CreateDataKey方法创建数据加密键。
  • Provide a dataKeyOpts object that specifies with which key your KMS should encrypt your new Data Encryption Key.提供一个dataKeyOpts对象，该对象指定KMS应使用哪个键加密新的数据加密键。

To view a tutorial demonstrating how to create and encrypt a Data Encryption Key, see the following resources:要查看演示如何创建和加密数据加密键的教程，请参阅以下资源：

• Quick Start快速入门
• Tutorials教程

To view the structure of kmsProviders and dataKeyOpts objects for all supported KMS providers, see Supported Key Management Services.要查看所有支持的KMS提供程序的kmsProviders和dataKeyOpts对象的结构，请参阅支持的键管理服务。

Amazon Web Services KMS亚马逊网络服务KMS

This section provides information related to using AWS Key Management Service in your Queryable Encryption enabled application.本节提供了有关在启用可查询加密的应用程序中使用AWS键管理服务的信息。

To view a tutorial demonstrating how to use AWS KMS in your Queryable Encryption enabled application, see Use Automatic Queryable Encryption with AWS.要查看演示如何在启用可查询加密的应用程序中使用AWS KMS的教程，请参阅使用AWS的自动可查询加密。

Architecture体系结构

The following diagram describes the architecture of a Queryable Encryption enabled application using AWS KMS.下图描述了使用AWS KMS的可查询加密应用程序的体系结构。

Note

Client Can't Access Customer Master Key客户端无法访问客户主键

When using the preceding Key Management Service, your Queryable Encryption enabled application does not have access to your Customer Master Key.使用前面的键管理服务时，启用可查询加密的应用程序无法访问您的客户主键。

dataKeyOpts Object对象

The following table presents the structure of a dataKeyOpts object for AWS KMS:下表显示了AWS KMS的dataKeyOpts对象的结构：

Field字段	Required必需	Description描述
key	Yes	Amazon Resource Number (ARN) of the master key.主键的亚马逊资源号（ARN）。
region	No	AWS region of your master key, e.g. "us-west-2"; required only if not specified in your ARN.您的主键的AWS区域，例如“us-west-2”；仅当ARN中未指定时才需要。
endpoint	No	Custom hostname for the AWS endpoint if configured for your account.如果为您的帐户配置了AWS端点的自定义主机名。

Azure Key Vault键保管库

This section provides information related to using Azure Key Vault in your Queryable Encryption enabled application.本节提供了有关在启用可查询加密的应用程序中使用Azure键保管库的信息。

To view a tutorial demonstrating how to use Azure Key Vault in your Queryable Encryption enabled application, see Use Automatic Queryable Encryption with Azure.若要查看演示如何在启用可查询加密的应用程序中使用Azure键库的教程，请参阅使用Azure的自动可查询加密。

Architecture体系结构

The following diagram describes the architecture of a Queryable Encryption enabled application using Azure Key Vault.下图描述了使用Azure键保管库启用可查询加密的应用程序的体系结构。

Note

Client Can't Access Customer Master Key客户端无法访问客户主键

When using the preceding Key Management Service, your Queryable Encryption enabled application does not have access to your Customer Master Key.使用前面的键管理服务时，启用可查询加密的应用程序无法访问您的客户主键。

Google Cloud Platform KMS谷歌云平台KMS

This section provides information related to using Google Cloud Key Management in your Queryable Encryption enabled application.本节提供了有关在启用可查询加密的应用程序中使用谷歌云键管理的信息。

To view a tutorial demonstrating how to use GCP KMS in your Queryable Encryption enabled application, see Use Automatic Queryable Encryption with GCP.要查看演示如何在启用可查询加密的应用程序中使用GCP KMS的教程，请参阅使用GCP的自动可查询加密。

Architecture体系结构

The following diagram describes the architecture of a Queryable Encryption enabled application using GCP KMS.下图描述了使用GCP KMS的可查询加密应用程序的体系结构。

Note

Client Can't Access Customer Master Key客户端无法访问客户主键

When using the preceding Key Management Service, your Queryable Encryption enabled application does not have access to your Customer Master Key.使用前面的键管理服务时，启用可查询加密的应用程序无法访问您的客户主键。

kmsProviders Object对象

The following table presents the structure of a kmsProviders object for GCP KMS:下表显示了GCP KMS的kmsProviders对象的结构：

Field字段	Required必需	Description描述
email	Yes	Identifies your service account email address.标识您的服务帐户电子邮件地址。
privateKey	Yes	Identifies your service account private key in either base64 string or Binary subtype 0 format without the prefix and suffix markers.以base64字符串或二进制子类型0格式标识您的服务帐户私钥，不带前缀和后缀标记。 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. 如果您有一个user-key.json凭据文件，您可以通过在bash或类似的shell中执行以下命令来提取字符串。The following command requires that you install OpenSSL:以下命令要求您安装OpenSSL： cat user-key.json | jq -r .private_key | openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER | base64 -w 0
endpoint	No	Specifies a hostname and port number for the authentication server. Defaults to oauth2.googleapis.com.指定身份验证服务器的主机名和端口号。默认为oauth2googleapiscom。

KMIP

This section provides information related to using a KMIP compliant Key Management Service provider in your Queryable Encryption enabled application.本节提供了有关在启用可查询加密的应用程序中使用符合KMIP的键管理服务提供程序的信息。

Architecture体系结构

The following diagram describes the architecture of a Queryable Encryption enabled application using a KMIP-compliant key provider.下图描述了使用符合KMIP的键提供程序的可查询加密应用程序的体系结构。

Important

Client Accesses Customer Master Key客户端访问客户主键

When your Queryable Encryption enabled application uses a KMIP-compliant key provider, your application directly accesses your Customer Master Key.当启用可查询加密的应用程序使用符合KMIP的键提供程序时，您的应用程序将直接访问您的客户主键。

dataKeyOpts Object对象

The following table presents the structure of a dataKeyOpts object for a KMIP compliant Key Management Service:下表显示了符合KMIP的键管理服务的dataKeyOpts对象的结构：

Field字段	Required必需	Description描述
keyId	No	The keyId field of a 96 byte Secret Data managed object stored in your KMIP-compliant key provider.存储在符合KMIP的键提供程序中的96字节Secret Data托管对象的keyId字段。 If you do not specify the keyId field in the masterKey document you send to your KMIP-compliant key provider, the driver creates a new 96 Byte Secret Data managed object in your KMIP-compliant key provider to act as your master key. 如果您没有在发送给KMIP兼容键提供程序的masterKey文档中指定keyId字段，则驱动程序会在KMIP兼容的键提供程序中创建一个新的96字节秘密数据管理对象，用作您的主键。
endpoint	Yes	The URI of your KMIP-compliant key provider.符合KMIP的键提供程序的URI。

Local Key Provider本地键提供程序

This section provides information related to using a Local Key Provider (your filesystem) in your Queryable Encryption enabled application.本节提供了有关在启用可查询加密的应用程序中使用本地键提供程序（文件系统）的信息。

To view a tutorial demonstrating how to use a Local Key Provider for testing Queryable Encryption, see Quick Start.要查看演示如何使用本地键提供程序测试可查询加密的教程，请参阅快速入门。

Architecture体系结构

When you use a Local Key Provider, your application retrieves your Customer Master Key from the filesystem of the computer it runs on. The following diagram describes the architecture of a Queryable Encryption-enabled application using a Local Key Provider.使用本地键提供程序时，应用程序会从其运行的计算机的文件系统中检索客户主键。下图描述了使用本地键提供方启用可查询加密的应用程序的体系结构。