Database Manual / Security / Encryption / In-Use Encryption / Keys and Key Vaults

KMS Providers

Overview概述

Learn about the Key Management System (KMS) providers In-Use Encryption supports.

Reasons to Use a Remote Key Management System

Using a remote Key Management System to manage your Customer Master Key has the following advantages over using your local filesystem to host it:

  • Secure storage of the key with access auditing
  • Reduced risk of access permission issues
  • Availability and distribution of the key to remote clients
  • Automated key backup and recovery
  • Centralized encryption key lifecycle management

Additionally, for the following KMS providers, your KMS remotely encrypts and decrypts your Data Encryption Key, ensuring your Customer Master Key is never exposed to your Queryable Encryption or CSFLE enabled application:

  • Amazon Web Services KMS
  • Azure Key Vault
  • Google Cloud KMS

Key Management System Tasks

In In-Use Encryption, your Key Management System:

  • Creates and encrypts the Customer Master Key
  • Encrypts the Data Encryption Keys created by your application
  • Decrypts Data Encryption Keys

To learn more about Customer Master Keys and Data Encryption Keys, see Encryption Keys and Key Vaults.

Create and Store your Customer Master Key

To create a Customer Master Key, configure your Key Management System to generate your Customer Master Key as follows:

Diagram

To view a tutorial that demonstrates how to create and store a CMK in your preferred KMS, see the Queryable Encryption Automatic Encryption Tutorial or CSFLE Automatic Encryption Tutorial.

Create and Encrypt a Data Encryption Key

To create a Data Encryption Key:

  • Instantiate a ClientEncryption instance in your Queryable Encryption or CSFLE enabled application:

    • Provide a kmsProviders object that specifies the credentials your application uses to authenticate with your KMS provider.

  • Create a Data Encryption Key with the CreateDataKey method of the ClientEncryption object in your application.

    • Provide a dataKeyOpts object that specifies with which key your KMS should encrypt your new Data Encryption Key.

To view a tutorial demonstrating how to create and encrypt a Data Encryption Key, see the following resources:

To view the structure of kmsProviders and dataKeyOpts objects for all supported KMS providers, see Supported Key Management Services.

Supported Key Management Services

The following sections of this page present the following information for all Key Management System providers:

  • Architecture of In-Use Encryption enabled client
  • Structure of kmsProviders objects
  • Structure of dataKeyOpts objects

Both Queryable Encryption and CSFLE support the following Key Management System providers:

Amazon Web Services KMS

This section provides information related to using AWS Key Management Service in your Queryable Encryption or CSFLE enabled application.

To view a tutorial demonstrating how to use AWS KMS in your application, see Overview: Enable Queryable Encryption or Use Automatic Client-Side Field Level Encryption with AWS.

Architecture

The following diagram describes the architecture of a Queryable Encryption enabled application using AWS KMS.

Diagram KMS

Note

Client Can't Access Customer Master Key

When using the preceding Key Management System, 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 AWS KMS:

Field字段Required for IAM UserRequired for IAM RoleDescription描述
Access Key IDYesYesIdentifies the account user.
Secret Access KeyYesYesContains the authentication credentials of the account user.
Session TokenNoYesContains a token obtained from AWS Security Token Service (STS).

dataKeyOpts Object

The following table presents the structure of a dataKeyOpts object for AWS KMS:

Field字段RequiredDescription描述
keyYesAmazon Resource Number (ARN) of the master key.
regionNoAWS region of your master key, e.g. "us-west-2"; required only if not specified in your ARN.
endpointNoCustom hostname for the AWS endpoint if configured for your account.

Azure Key Vault

This section provides information related to using Azure Key Vault in your Queryable Encryption or CSFLE enabled application.

To view a tutorial demonstrating how to use Azure Key Vault in your application, see Overview: Enable Queryable Encryption or Use Automatic Client-Side Field Level Encryption with Azure.

Architecture

The following diagram describes the architecture of a Queryable Encryption enabled application using Azure Key Vault.

Diagram KMS

Note

Client Can't Access Customer Master Key

When using the preceding Key Management System, 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 Azure Key Vault:

Field字段RequiredDescription描述
azure.tenantIdYesIdentifies the organization of the account.
azure.clientIdYesIdentifies the clientId to authenticate your registered application.
azure.clientSecretYesUsed to authenticate your registered application.
azure.identityPlatformEndpointNoSpecifies a hostname and port number for the authentication server. Defaults to login.microsoftonline.com and is only needed for non-commercial Azure instances such as a government or China account.

dataKeyOpts Object

The following table presents the structure of a dataKeyOpts object for Azure Key Vault:

Field字段RequiredDescription描述
keyNameYesName of the master key
keyVersionNo, but strongly recommendedVersion of the master key
keyVaultEndpointYesURL of the key vault. E.g. myVaultName.vault.azure.net

Warning

If you do not include a keyVersion field, Azure Key Vault attempts to decrypt Data Encryption Keys using the latest Customer Master Key. If you rotate the CMK but do not rewrap the Data Encryption Keys with the new master key, attempting to decrypt an existing DEK fails, since the DEK is encrypted with the previous version of the CMK.

Google Cloud Platform KMS

This section provides information related to using Google Cloud Key Management in your Queryable Encryption or CSFLE enabled application.

To view a tutorial demonstrating how to use GCP KMS in your application, see Overview: Enable Queryable Encryption or Use Automatic Client-Side Field Level Encryption with GCP.

Architecture

The following diagram describes the architecture of a Queryable Encryption enabled application using GCP KMS.

Diagram KMS

Note

Client Can't Access Customer Master Key

When using the preceding Key Management System, 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:

Field字段RequiredDescription描述
emailYesIdentifies your service account email address.
privateKeyYes
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
endpointNoSpecifies a hostname and port number for the authentication server. Defaults to oauth2.googleapis.com.

dataKeyOpts Object

The following table presents the structure of a dataKeyOpts object for GCP KMS:

Field字段RequiredDescription描述
projectIdYesIdentifier for your project in which you created the key.
locationYesRegion specified for your key.
keyRingYesIdentifier for the group of keys your key belongs to.
keyNameYesIdentifier for the symmetric master key.
keyVersionNoSpecifies the version of the named key. If not specified, the default version of the key is used.
endpointNoSpecifies the host and optional port of the Cloud KMS. The default is cloudkms.googleapis.com.

KMIP

This section provides information related to using a KMIP compliant Key Management System in your Queryable Encryption or CSFLE enabled application.

To learn how to set up KMIP with HashiCorp Vault, see the How to Set Up HashiCorp Vault KMIP Secrets Engine with MongoDB CSFLE or Queryable Encryption blog post.

Architecture

The following diagram describes the architecture of a Queryable Encryption enabled application using a KMIP-compliant key provider.

Diagram

Important

Client Accesses Customer Master Key

When your Queryable Encryption enabled application uses a KMIP-compliant key provider without specifying the delegated option, your application directly accesses your Customer Master Key. To avoid directly accessing your CMK, you can set the delegated option to true in your dataKeyOpts object.

kmsProviders Object

The following table presents the structure of a kmsProviders object for a KMIP compliant Key Management System:

Note

Authenticate through TLS/SSL

Your Queryable Encryption enabled application authenticates through TLS/SSL when using KMIP.

Field字段RequiredDescription描述
endpointYesSpecifies a hostname and port number for the authentication server.

dataKeyOpts Object

The following table presents the structure of a dataKeyOpts object for a KMIP compliant Key Management System:

Field字段RequiredDescription描述
keyIdNo

The keyId field of a 96 byte Secret Data managed object stored in your KMIP-compliant key provider.

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.

endpointYesThe URI of your KMIP-compliant key provider.
delegatedNo

Set this option to true to delegate the encryption and decryption of your DEK to your KMIP-compliant key provider. Delegating these to the KMIP-compliant key provider ensures that you never have direct access to the CMK.

If you do not set the delegated option to true, your application directly accesses and transports your Customer Master Key from the KMIP provider.

IMPORTANT: The delegated option is not available in the Ruby or Go drivers.

Local Key Provider

This section provides information related to using a Local Key Provider in your Queryable Encryption or CSFLE enabled application.

Warning

Secure your Local Key File in Production在生产环境中保护本地键文件

We recommend storing your Customer Master Keys in a remote Key Management System (KMS). To learn how to use a remote KMS in your Queryable Encryption implementation, see the Queryable Encryption Tutorials guide.

If you choose to use a local key provider in production, exercise great caution and do not store it on the file system. Consider injecting the key into your client application using a sidecar process, or use another approach that keeps the key secure.如果您选择在生产中使用本地键提供程序，请务必谨慎，不要将其存储在文件系统上。考虑使用sidecar进程将键注入客户端应用程序，或使用另一种确保键安全的方法。

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

Architecture建筑

When you use a Local Key Provider for testing, your application retrieves your Customer Master Key from the computer it runs on. To use a Local Key Provider in production, use an approach that doesn't store the key on the file system. For example, you can inject the key into the client process via a sidecar.当您使用本地键提供程序进行测试时，应用程序会从其运行的计算机中检索客户主键。要在生产中使用本地键提供方，请使用不将键存储在文件系统上的方法。例如，您可以通过sidecar将键注入客户端进程。

The following diagram describes the architecture of a Queryable Encryption-enabled application using a Local Key Provider.下图描述了使用本地键提供程序的启用可查询加密的应用程序的体系结构。

Local Key Provider architecture diagram.

kmsProviders Object对象

The following table presents the structure of a kmsProviders object for a Local Key Provider:下表显示了本地键提供程序的kmsProviders对象的结构：

Field字段RequiredDescription描述
keyYesThe master key used to encrypt/decrypt data keys. The master key is passed as a base64 encoded string.用于加密/解密数据键的主键。主键以base64编码字符串的形式传递。

dataKeyOpts ObjectdataKeyOpts对象

When you use a Local Key Provider, you specify your Customer Master Key through your kmsProviders object.当您使用本地键提供程序时，您可以通过kmsProviders对象指定客户主键。