Client-Side Field Level Encryption: Use a KMS to Store the Master Key¶
On this page
- Introduction
- Prerequisites
- Reasons to Use a Remote KMS
- Set up a Remote Master Key
- Create an AWS IAM User
- Create the Master Key
- Specify the AWS KMS Provider Credentials
- Create a New Data Encryption Key
- Update the Automatic Encryption JSON Schema
- Register an Azure Application
- Create the Master Key
- Specify the Azure Credentials
- Create a New Data Encryption Key
- Update the Automatic Encryption JSON Schema
- Create a GCP Service Account
- Create the Master Key
- Specify your Google Cloud KMS Credentials
- Create a New Data Encryption Key
- Update the Automatic Encryption JSON Schema
- Further Reading
Introduction¶
This guide shows you how to migrate from using Client-Side Field Level Encryption (CSFLE) with a locally-managed master key to one that uses a remote Key Management Service (KMS) and is intended for full-stack developers.
Currently, MongoDB drivers support the following Key Management Providers:
Once you complete the steps in this guide, you should have:
- a master key hosted by one of the supported remote Key Management Services
- a working client application that encrypts and decrypts the data encryption key using the KMS master key
Prerequisites¶
This guide requires that you completed the following:
- created a CSFLE-enabled client using our CSFLE guide
- decrypted any data encrypted while using a local KMS master key
Reasons to Use a Remote KMS¶
Choosing a remote KMS for master key management has the following advantages over using your local filesystem to host the master key:
- 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, MongoDB trasmits the data encryption keys to the KMS for encryption and decryption, ensuring the Customer Master Key (CMK) is never exposed to the client.
Set up a Remote Master Key¶
Before you switch from a locally-managed master key to a remote KMS, you must decrypt all documents containing field-encrypted data if you want to keep it. Your existing data encryption keys can only be decrypted with the original locally-managed master key and not the CMK that the KMS generates.
Failure to decrypt all data at this stage may cause permanent and unrecoverable data loss.
The following steps explain the setup and updates necessary to move from a local key provider to a KMS. Select the tab that corresponds to your provider:
Further Reading¶
For more information on client-side field level encryption in MongoDB, check out the reference documentation in the MongoDB server manual: