Master Key and Data Encryption Key Management
New in version 4.2.
Supported Key Management Services
Client-side field level encryption requires a Key Management Service (KMS) for accessing a Customer Master Key (CMK). MongoDB automatically encrypts data encryption keys using the specified CMK during data encryption key creation.
Deleting the CMK renders all data encryption keys encrypted with that CMK as permanently unreadable, which in turn renders all values encrypted with those data encryption keys as permanently unreadable.
Client-side field level encryption supports the following KMS providers:
Amazon Web Services KMS
Important
For AWS KMS support, use mongosh
, or the MongoDB
4.2.2 or later legacy mongo
shell. The 4.2.0 and
4.2.1 legacy mongo
shell do not support the AWS KMS
service due to an unexpected change in the KMS response object.
See SERVER-44721 for more information.
MongoDB client-side encryption supports using the Amazon Web Services Key Management Service for encrypting and decrypting data encryption keys. Specifically, MongoDB securely transmits the data encryption key to AWS KMS for encrypting or decrypting using the specified Customer Master Key (CMK). The CMK never leaves the AWS KMS.
mongosh
supports two methods for configuring
access to an AWS KMS:
Use the client-side field level encryption command-line options, or
Use the
Mongo()
constructor to create a database connection with the required AWS KMS configuration options.
Configuring access to an AWS KMS requires at minimum an AWS Access Key and its corresponding Secret Key. The IAM User associated to the Access Key must have at least one policy with the following actions:
kms:Encrypt
(reference)kms:Decrypt
(reference)
Note
Implement Principle of Least Privilege for KMS Access
Consider configuring IAM user roles such that MongoDB has only the access to the actions and resources required to function.
For example, the following policy JSON scopes the required actions to a single CMK:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:Encrypt" ], "Resource": "arn:aws:kms:region:account:key/12a345b6-cd7e-8f9g-0h1i-jk23l45mn6o7" } ] }
For complete documentation on data encryption key management using AWS KMS, see Manage Data Encryption Keys and select the "Amazon Web Services KMS" tab.
Azure Key Vault
MongoDB client-side encryption supports using the Azure Key Vault Key Management Service for encrypting and decrypting data encryption keys. Specifically, MongoDB securely transmits the data encryption key to Azure Key Vault for encrypting or decrypting using the specified Customer Master Key (CMK). The CMK never leaves the Azure Key Vault.
mongosh
supports specifying Azure Key Vault
as a KMS using the Mongo()
constructor using the
KMS configuration options.
Configuring access to Azure Key Vault requires at minimum an Azure Tenant ID, Client ID, and Client Secret. The Tenant ID must have the ability to perform the following actions:
wrap key
(reference)unwrap key
(reference)
Note
MongoDB does not support Azure's client certificate authentication (also known as TLS mutual authentication).
For complete documentation on data encryption key management using Azure Key Vault, see Manage Data Encryption Keys and select the "Azure Key Vault" tab.
Google Cloud Platform KMS
MongoDB client-side encryption supports using the Google Cloud KMS for encrypting and decrypting data encryption keys. Specifically, MongoDB securely transmits the data encryption key to Google Cloud KMS for encrypting or decrypting using the specified Customer Master Key (CMK). The CMK never leaves the Google Cloud KMS.
mongosh
supports specifying Google Cloud KMS
as a KMS using the Mongo()
constructor using the
KMS configuration options.
Configuring access to Google Cloud KMS requires at minimum a Google Cloud Email and associated Private Key. The Google Cloud Email account must have the following IAM permissions for the specified Private Key:
cloudkms.cryptoKeyVersions.useToEncrypt
cloudkms.cryptoKeyVersions.useToDecrypt
These IAM permissions are included in certain Google Cloud predefined roles or can be included in a Google Cloud custom role.
For complete documentation on data encryption key management using Google Cloud KMS, see Manage Data Encryption Keys and select the "Google Cloud KMS" tab.
Locally Managed Key
mongosh
supports specifying a locally managed key
as a KMS using the Mongo()
constructor. The local key must
be a 96-byte long string.
For complete documentation on data encryption key management using a locally managed key, see Manage Data Encryption Keys and select the "Local Keyfile" tab.
Encryption Key Vault
The key vault is a collection that stores data encryption keys for use with client-side field level encryption. Data encryption keys are encrypted using a Customer Master Key (CMK) managed through a supported Key Management System (KMS).
mongosh
provides helper methods for data
encryption key management:
Use Case | Helper Methods |
---|---|
Retrieving data encryption keys | |
Creating or Modifying data encryption keys | |
Removing data encryption keys | ImportantRemoving a data encryption key renders all fields encrypted using that data encryption key as permanently unreadable. |
Applications with read
access to the key vault collection
can retrieve data encryption keys by querying the collection. However,
only applications with access to the CMK used to encrypt a data
encryption key can use that key for encryption or decryption.
By default MongoDB stores the key vault collection on the connected cluster. MongoDB also supports specifying a remote cluster as the key vault. Applications must have access to both the remote key vault cluster and the connection cluster to perform client-side field level encryption operations.
Data encryption keys have the following structure:
{ "_id" : UUID("<string>"), "keyMaterial" : BinData(0,"<encrypted binary data string>"), "creationDate" : ISODate("2019-08-20T15:45:02.575Z"), "updateDate" : ISODate("2019-08-20T15:45:02.575Z"), "status" : <int>, "version" : NumberLong(0), "masterKey" : { "provider" : "<string>", "key" : "<string>", "region" : "<string>", "endpoint" : "<string>" }, "keyAltNames" : [ "<string>" ] }
Client-side field level encryption depends on uniqueness of
keyAltNames
values. The mongosh
KeyVault.createKey()
method creates a unique index on keyAltNames
if one does not exist.
Applications can use the listIndexes
command against the
key vault collection to check if the unique index exists. If the unique
index does not exist, applications must create it prior to performing
data encryption key management.
For complete documentation on data encryption key management, see Manage Data Encryption Keys.