Master Key and Data Encryption Key Management

beta

Client-Side Field Level Encryption is available as a beta. The contentsof this page may change during the beta period.

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 automaticallyencrypts data encryption keys using the specified CMK duringdata encryption key creation.

Deleting the CMK renders all data encryption keys encrypted with thatCMK as permanently unreadable, which in turn renders all valuesencrypted with those data encryption keys as permanently unreadable.

Client-side field level encryption supports the following KMS providers:

Amazon Web Services KMS

Warning

The 4.2.0 and 4.2.1 mongo shell does not support theAWS KMS service due to an unexpected change in the KMS responseobject. Previously functional applications using themongo shell to perform client-side field levelencryption using AWS KMS may now return errors during encryptionoperations. Official MongoDB 4.2-compatible drivers withclient-side field level encryption support are unaffected.

SERVER-44721 documents the issue and isscheduled for the future 4.2.2 release.

MongoDB client-side encryption supports using theAmazon Web Services Key Management Service for encryptingand decrypting data encryption keys. Specifically, MongoDB securelytransmits the data encryption key to AWS KMS for encrypting ordecrypting using the specified Customer Master Key (CMK). The CMK neverleaves the AWS KMS.

The mongo shell supports two methods for configuringaccess to an AWS KMS:

or

Configuring access to an AWS KMS requires at minimum an AWS access keyand its corresponding secret key. The IAM user associated to the accesskey must have at least one policy with the following actions:

Implement Seperation of Least Privilege for KMS Access

Consider configuring IAM user roles such that MongoDB has only theaccess to the actions and resources required to function.

For example, the following policy JSON scopes the required actions toa single CMK:

  1. {
  2.     "Version": "2012-10-17",
  3.     "Statement": [
  4.         {
  5.             "Sid": "VisualEditor0",
  6.             "Effect": "Allow",
  7.             "Action": [
  8.                 "kms:Decrypt",
  9.                 "kms:Encrypt"
  10.             ],
  11.             "Resource": "arn:aws:kms:region:account:key/12a345b6-cd7e-8f9g-0h1i-jk23l45mn6o7"
  12.         }
  13.     ]
  14. }

For complete documentation on data encryption key management using AWS KMS, seeManage Data Encryption Keys.

Locally Managed Key

The mongo shell supports specifying a locally managed keyas 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 alocally managed key, seeManage Data Encryption Keys.

Encryption Key Vault

The key vault is a collection that stores data encryption keys for usewith client-side field level encryption. data encryption keys areencrypted using a Customer Master Key (CMK) managed through a supportedKey Management System (KMS).

The mongo shell provides helper methods for dataencryption key management:

Retrieving data encryption keys- KeyVault.getKey()- KeyVault.getKeys()- KeyVault.getKeyByAltName()
Creating or Modifying data encryption keys- KeyVault.createKey()- KeyVault.addKeyAlternateName()- KeyVault.removeKeyAlternateName()
Removing data encryption keysImportantRemoving a data encryption key renders all fields encryptedusing that data encryption key as permanently unreadable.- KeyVault.deleteKey()

Applications with read access to the key vault collectioncan retrieve data encryption keys by querying the collection. However,only applications with access to the CMK used to encrypt a dataencryption key can use that key for encryption or decryption.

By default MongoDB stores the key vault collection on the connectedcluster. MongoDB also supports specifying a remote cluster as the keyvault. Applications must have access to both the remote key vaultcluster and the connection cluster to perform client-side field levelencryption operations.

data encryption keys have the following structure:

  1. {
  2.   "_id" : UUID("<string>"),
  3.   "keyMaterial" : BinData(0,"<encrypted binary data string>"),
  4.       "creationDate" : ISODate("2019-08-20T15:45:02.575Z"),
  5.       "updateDate" : ISODate("2019-08-20T15:45:02.575Z"),
  6.       "status" : <int>,
  7.       "version" : NumberLong(0),
  8.       "masterKey" : {
  9.         "provider" : "<string>",
  10.         "key" : "<string>",
  11.         "region" : "<string>",
  12.         "endpoint" : "<string>"
  13.       },
  14.       "keyAltNames" : [
  15.     "<string>"
  16.   ]
  17. }

Client-side field level encryption depends on uniqueness ofkeyAltNames values. The mongo shellKeyVault.createKey() method creates a unique index on keyAltNames if one does not exist.Applications can use the listIndexes command against thekey vault collection to check if the unique index exists. If the uniqueindex does not exist, applications must create it prior to performingdata encryption key management.

For complete documentation on data encryption key management, seeManage Data Encryption Keys.