Encryption Key Management¶

On this page

Encryption Components
Supported Key Management Services
- Reasons to Use a Remote KMS
Manage a ‘s Alternate Name
Learn More

In this guide, you can learn how to manage your encryption keys with a: () in your ()-enabled

application.

Encryption Components¶

MongoDB uses the following components to perform :

s (DEKs)
s
s (CMKs)
(KMS)

Your is the key you use to encrypt the fields in your MongoDB documents. Your is stored in a document in a MongoDB collection called the .

Your is the key you use to encrypt your s. MongoDB automatically encrypts s using the specified

during creation.

The is the most sensitive key in . If your: is compromised, all of your encrypted data can be

decrypted.

Use a to store your .

To learn more about the relationship between keys, see Keys and Key Vaults.

Important

Use a Remote Key Management Service Provider

Ensure you store your () on a remote KMS.

To learn more about why you should use a remote , see Reasons to Use a Remote KMS.

To view a list of all supported providers, see the KMS Providers page.

Supported Key Management Services¶

supports the following () providers:

KMS
Azure Key Vault
Google Cloud Platform KMS
Any KMIP Compliant
Local Key Provider (for testing only)

To learn more about these providers, including diagrams that show how your application uses them to perform , see KMS Providers.

Reasons to Use a Remote KMS¶

Using a remote to manage your () has the following advantages over using your local filesystem to host the :

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 providers, your: remotely encrypts and decrypts your , ensuring

your is never exposed to your -enabled application:

KMS
Azure Key Vault
Google Cloud Platform KMS

Manage a ‘s Alternate Name¶

You can assign a () 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 with an Alternate Name¶

Important

Prerequisite

Prior to adding a new key alternate name, you must create a unique index on the keyAltNames field. 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 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

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.

Important

Cannot Use Alternate Name for Deterministically Encrypted Field

You cannot reference a 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:

copy

{
  "<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:

copy

{
  "name": "Jon Doe",
  "salary": 45000,
  "fieldWithAltName": "my-alt-name"
}

The salary field is encrypted by the the that has the alternate name my-alt-name.

Dynamically Assign Keys at Runtime¶

You can use alternate key names to dynamically set the for a field at runtime. Use this functionality to encrypt individual documents with different s using the same encryption schema.

For example, consider the following documents:

copy

{
    "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 -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 s specific to the individual document. The keys are assigned dynamically at runtime.

Delete a¶

You can delete a from your using standard CRUD delete operations.

Tip

MongoDB Shell Specific Feature

The MongoDB shell allows you to delete a by UUID using the keyVault.deleteKey() method as follows:

copy

keyVault = db.getKeyVault()
keyVault.deleteKey(UUID("<UUID String>"))

To learn more about s see s.

Learn More¶

For tutorials detailing how to set up a -enabled application with each of the supported providers, see the following pages:

To view additional examples of encryption schemas, see Encryption Schemas.

← Keys and Key Vaults Fields and Encryption Types →