CSFLE KMS Providers
On this page
Overview
Learn about the Key Management System (KMS) providers Client-Side Field Level Encryption (CSFLE) supports.
Key Management System Tasks
In CSFLE, your Key Management System performs the following tasks:
To learn more about Customer Master Keys and Data Encryption Keys, see Keys and Key Vaults.
Create and Store your Customer Master Key
To create a Customer Master Key, you must configure your Key Management System to generate your Customer Master Key as follows:
![Diagram](/docs/v7.0/static/cd8b8aa4e4a3cd63639fd56ef014025b/2ce52/CSFLE_Master_Key_KMS.webp)
To view a tutorial demonstrating how to create and store your CMK in your preferred KMS, see Tutorials.
Create and Encrypt a Data Encryption Key
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 theClientEncryption
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.
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
objectsStructure of
dataKeyOpts
objects
CSFLE supports the following Key Management System providers:
Amazon Web Services KMS
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.
Architecture
The following diagram describes the architecture of a CSFLE-enabled application using AWS KMS.
![Diagram KMS](/docs/v7.0/static/5fb661a80bb16168a1f5c996ff1bbe02/15bb5/CSFLE_Data_Key_KMS.webp)
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.
kmsProviders Object
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). |
dataKeyOpts Object
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. |
Azure Key Vault
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.
Architecture
The following diagram describes the architecture of a CSFLE-enabled application using Azure Key Vault.
![Diagram KMS](/docs/v7.0/static/5fb661a80bb16168a1f5c996ff1bbe02/15bb5/CSFLE_Data_Key_KMS.webp)
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.
kmsProviders Object
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. |
dataKeyOpts Object
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.
Google Cloud Platform KMS
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.
Architecture
The following diagram describes the architecture of a CSFLE-enabled application using GCP KMS.
![Diagram KMS](/docs/v7.0/static/5fb661a80bb16168a1f5c996ff1bbe02/15bb5/CSFLE_Data_Key_KMS.webp)
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.
kmsProviders Object
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:
The value you would specify for this field is:
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:
| |||
endpoint | No | Specifies 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 | 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 . |
KMIP
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.
Architecture
The following diagram describes the architecture of a CSFLE-enabled application using a KMIP-compliant key provider.
![Diagram](/docs/v7.0/static/28791746684427e1cd1e8e1519085025/23cb4/CSFLE_Data_Key_KMIP.webp)
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.
kmsProviders Object
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. |
dataKeyOpts Object
The following table presents the structure of a dataKeyOpts
object
for a KMIP compliant Key Management System:
Field | Required | Description |
---|---|---|
keyId | No | The If you do not specify the |
endpoint | Yes | The URI of your KMIP-compliant key provider. |
Local 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.
Architecture
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.](/docs/v7.0/static/33fb1c01bdcd0a1fe27d298fdfc0a817/df5a9/CSFLE_Data_Key_Local.webp)
kmsProviders Object
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. |
dataKeyOpts Object
When you use a Local Key Provider, you specify your Customer Master Key
through your kmsProviders
object.