KMS Providers
On this page
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:
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 theClientEncryption
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
objectsStructure 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.
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 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 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.
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 | 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 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.
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 | 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 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.
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.
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 | 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 Queryable Encryption or CSFLE enabled application.
Warning
Do Not Use a Local Key File in Production
A local key file in your filesystem is insecure 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 Queryable Encryption implementation, see the Tutorials guide.
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.
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.
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.