Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

CSFLE KMS Providers

On this page

  • Overview
  • Key Management System Tasks
  • Create and Store your Customer Master Key
  • Create and Encrypt a Data Encryption Key
  • Supported Key Management Services
  • Amazon Web Services KMS
  • Azure Key Vault
  • Google Cloud Platform KMS
  • KMIP
  • Local Key Provider

Learn about the Key Management System (KMS) providers Client-Side Field Level Encryption (CSFLE) supports.

In CSFLE, your Key Management System performs the following tasks:

  • Creates and stores your Customer Master Key

  • Create and Encrypt your Data Encryption Keys

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

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

Diagram

To view a tutorial demonstrating how to create and store your CMK in your preferred KMS, see Tutorials.

When you create a Data Encryption Key, you must perform the following actions:

  • Instantiate a ClientEncryption instance in your CSFLE-enabled application:

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

  • Create a Data Encryption Key with the CreateDataKey method of the ClientEncryption object in your CSFLE-enabled 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.

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

  • Architecture of CSFLE-enabled client

  • Structure of kmsProviders objects

  • Structure of dataKeyOpts objects

CSFLE supports the following Key Management System providers:

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

To view a tutorial demonstrating how to use AWS KMS in your CSFLE-enabled application, see Use Automatic Client-Side Field Level Encryption with AWS.

The following diagram describes the architecture of a CSFLE-enabled application using AWS KMS.

Diagram KMS

Note

Client Can't Access Customer Master Key

When using the preceding Key Management System, your CSFLE-enabled application does not have access to your Customer Master Key.

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

Field
Required for IAM User
Required for IAM Role
Description
Access Key ID
Yes
Yes
Identifies the account user.
Secret Access Key
Yes
Yes
Contains the authentication credentials of the account user.
Session Token
No
Yes
Contains a token obtained from AWS Security Token Service (STS).

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

Field
Required
Description
key
Yes
Amazon Resource Number (ARN) of the master key.
region
No
AWS region of your master key, e.g. "us-west-2"; required only if not specified in your ARN.
endpoint
No
Custom hostname for the AWS endpoint if configured for your account.

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

To view a tutorial demonstrating how to use Azure Key Vault in your CSFLE-enabled application, see Use Automatic Client-Side Field Level Encryption with Azure.

The following diagram describes the architecture of a CSFLE-enabled application using Azure Key Vault.

Diagram KMS

Note

Client Can't Access Customer Master Key

When using the preceding Key Management System, your CSFLE-enabled application does not have access to your Customer Master Key.

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

Field
Required
Description
azure.tenantId
Yes
Identifies the organization of the account.
azure.clientId
Yes
Identifies the clientId to authenticate your registered application.
azure.clientSecret
Yes
Used to authenticate your registered application.
azure.identityPlatformEndpoint
No
Specifies 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.

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

Field
Required
Description
keyName
Yes
Name of the master key
keyVersion
No, but strongly recommended
Version of the master key
keyVaultEndpoint
Yes
URL 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.

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

To view a tutorial demonstrating how to use GCP KMS in your CSFLE-enabled application, see Use Automatic Client-Side Field Level Encryption with GCP.

The following diagram describes the architecture of a CSFLE-enabled application using GCP KMS.

Diagram KMS

Note

Client Can't Access Customer Master Key

When using the preceding Key Management System, your CSFLE-enabled application does not have access to your Customer Master Key.

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

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.

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
endpoint
No
Specifies a hostname and port number for the authentication server. Defaults to oauth2.googleapis.com.

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

Field
Required
Description
projectId
Yes
Identifier for your project in which you created the key.
location
Yes
Region specified for your key.
keyRing
Yes
Identifier for the group of keys your key belongs to.
keyName
Yes
Identifier for the symmetric master key.
keyVersion
No
Specifies the version of the named key. If not specified, the default version of the key is used.
endpoint
No
Specifies the host and optional port of the Cloud KMS. The default is cloudkms.googleapis.com.

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

To view a tutorial demonstrating how to use a KMIP compliant Key Management System in your CSFLE-enabled application, see Use Automatic Client-Side Field Level Encryption with KMIP.

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

Diagram

Important

Client Accesses Customer Master Key

When your CSFLE-enabled application uses a KMIP-compliant key provider, your application directly accesses your Customer Master Key.

The following table presents the structure of a kmsProviders object for a KMIP-compliant key provider:

Note

Authenticate through TLS/SSL

Your CSFLE-enabled application authenticates through TLS/SSL when using KMIP.

Field
Required
Description
endpoint
Yes
Specifies a hostname and port number for the authentication server.

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

Field
Required
Description
keyId
No

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.

endpoint
Yes
The URI of your KMIP-compliant key provider.

This section provides information related to using a Local Key Provider (your filesystem) in your CSFLE-enabled application.

Warning

Do Not Use the Local Key Provider in Production

The Local Key Provider is an insecure method of storage and is not recommended for production. Instead, you should store your Customer Master Keys in a remote Key Management System (KMS).

To learn how to use a remote KMS in your CSFLE implementation, see the Tutorials guide.

To view a tutorial demonstrating how to use a Local Key Provider for testing Client-Side Field Level Encryption, see Quick Start.

When you use a Local Key Provider in your CSFLE-enabled application, your application retrieves your Customer Master Key from the filesystem of the computer on which your application is running.

The following diagram describes the architecture of a CSFLE-enabled application using a Local Key Provider.

Local Key Provider architecture diagram.

The following table presents the structure of a kmsProviders object for a Local Key Provider:

Field
Required
Description
key
Yes
The master key used to encrypt/decrypt data keys. The master key is passed as a base64 encoded string.

When you use a Local Key Provider, you specify your Customer Master Key through your kmsProviders object.

←  CSFLE-Specific MongoClient OptionsCSFLE Encryption Components →