Encryption Key Management
On this page
In this guide, you can learn how to manage your encryption keys with a Key Management System (KMS) in your Client-Side Field Level Encryption (CSFLE)-enabled application.
Encryption Components
MongoDB uses the following components to perform Client-Side Field Level Encryption:
- Data Encryption Keys (DEKs)
- Key Vault collections
- Customer Master Keys (CMKs)
- Key Management System (KMS)
Your Data Encryption Key is the key you use to encrypt the fields in your MongoDB documents. Your DEK is stored in a document in a MongoDB collection called the Key Vault collection.
Your Customer Master Key is the key you use to encrypt your Data Encryption Keys. MongoDB automatically encrypts Data Encryption Keys using the specified CMK during Data Encryption Key creation.
The CMK is the most sensitive key in CSFLE. If your CMK is compromised, all of your encrypted data can be decrypted.
Use a Key Management System to store your Customer Master Key.
To learn more about the relationship between keys, see Keys and Key Vaults.
Ensure you store your Customer Master Key (CMK) on a remote KMS.
To learn more about why you should use a remote KMS, see Reasons to Use a Remote KMS.
To view a list of all supported KMS providers, see the KMS Providers page.
Supported Key Management Services
Client-Side Field Level Encryption supports the following Key Management System (KMS) providers:
- Amazon Web Services KMS
- Azure Key Vault
- Google Cloud Platform KMS
- Any KMIP Compliant Key Management System
- Local Key Provider (for testing only)
To learn more about these providers, including diagrams that show how your application uses them to perform Client-Side Field Level Encryption, see KMS Providers.
Reasons to Use a Remote KMS
Using a remote KMS to manage your Customer Master Key (CMK) has the following advantages over using your local filesystem to host the CMK:
- 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 CSFLE-enabled application:
- Amazon Web Services KMS
- Azure Key Vault
- Google Cloud Platform KMS
Manage a Data Encryption Key's Alternate Name
You can assign a Data Encryption Key (DEK) alternate names to make the key easier to reference. Assigning alternate names allows you to perform the following actions:
- Reference a DEK by different means than the
_id
field. - Dynamically assign DEKs at runtime.
Create a Data Encryption Key with an Alternate Name
Prior to adding a new key alternate name, you must create a unique
index on the keyAltNames
field. Client-Side Field Level Encryption depends on
server-enforced uniqueness of key alternate names.
To learn how to create a unique index, see Unique Indexes.
The following example creates a DEK with an alternate name. Select the tab that corresponds to your driver language:
To learn more about dataKeyOpts
and kmsProviders
objects, see
KMS Providers.
Use Key Alternate Names in an Automatic Encryption Schema
Encryption schemas contain user-specified rules that identify which fields must be encrypted and how to encrypt those fields. In your encryption rules, you can specify alternate key names name for the Data Encryption Key which encrypts your field.
You must refer to a key alternate name with a JSON pointer. A JSON
pointer is a string prefixed with a "/"
character that can be used
to access a particular field value in the same or another document. Use
JSON pointers to reference a field in your query or update document
which contains the value of your key alternate name.
You cannot reference a DEK by it's alternate name when
encrypting a field with the deterministic encryption algorithm. To encrypt your field
deterministically, you must specify the _id
of the key you would
like to use to encrypt your field.
Reference Key Alternate Name in an Encryption Schema
Consider the following encryption schema which encrypts the salary
field:
{ "<database>.<collection>": { "bsonType": "object", "properties": { "salary": { "encrypt": { "bsonType": "int", "keyId": "/fieldWithAltName", "algorithm": "AEAD_AES_256_CBC_HMAC_SHA_512-Random" } } } } }
The schema's keyId
field contains a JSON pointer to reference the
fieldWithAltName
field within the documents being encrypted.
The following document's fieldWithAltName
value is my-alt-name
:
{ "name": "Jon Doe", "salary": 45000, "fieldWithAltName": "my-alt-name" }
The salary
field is encrypted by the the Data Encryption Key that has the
alternate name my-alt-name
.
Dynamically Assign Keys at Runtime
You can use alternate key names to dynamically set the Data Encryption Key for a field at runtime. Use this functionality to encrypt individual documents with different Data Encryption Keys using the same encryption schema.
For example, consider the following documents:
{ "name": "Jon Doe", "salary": 45000, "fieldWithAltName": "my-alt-name" }, { "name": "Jane Smith", "salary": 70000, "fieldWithAltName": "my-other-alt-name" }
You insert the preceding documents using a CSFLE-enabled client configured with the encryption schema from the previous example.
In the encryption schema, the salary.encrypt.keyId
field contains a
JSON pointer to the fieldWithAltName
field of the inserted document.
As a result, the salary
fields in the two example documents are
uniquely encrypted using Data Encryption Keys specific to the individual
document. The keys are assigned dynamically at runtime.
Delete a Data Encryption Key
You can delete a DEK from your Key Vault collection using standard CRUD delete operations.
The MongoDB shell allows you to delete a DEK by UUID
using
the keyVault.deleteKey()
method as follows:
keyVault = db.getKeyVault() keyVault.deleteKey(UUID("<UUID String>"))
To learn more about Key Vault collections see Key Vault Collections.
Learn More
For tutorials detailing how to set up a CSFLE-enabled application with each of the supported KMS providers, see the following pages:
- Use Automatic Client-Side Field Level Encryption with AWS
- Use Automatic Client-Side Field Level Encryption with Azure
- Use Automatic Client-Side Field Level Encryption with GCP
- Use Automatic Client-Side Field Level Encryption with KMIP
To view additional examples of encryption schemas, see Encryption Schemas.