Navigation

Manage Data Encryption Keys

New in version 4.2.

Client-side field level encryption uses data encryption keys for encryption and decryption. The mongo shell getKeyVault() method returns a key vault object for creating, modifying, and deleting data encryption keys.

This page documents client-side field level encryption using the mongo shell, and does not refer to any official MongoDB 4.2+ compatible driver. See the relevant documentation for driver-specific data encryption key management methods and syntax.

The following procedure uses the mongo shell to create a data encryption key for use with client-side field level encryption and decryption. For guidance on data encryption key management using a 4.2+ compatible driver, see the driver documentation instead.

Use the tabs below to select the KMS appropriate for your deployment:

1

Configuring client-side field level encryption for the AWS KMS requires an AWS Access Key ID and its associated Secret Access Key. The AWS Access Key must correspond to an IAM user with all List and Read permissions for the KMS service.

To mitigate the risk of these credentials leaking into logs, the following procedure passes the values into the mongo shell using environment variables.

First, ensure that you have configured the following environment variables according to your platform's documentation:

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

Next, create a mongo shell session using the --eval, --shell, and --nodb options:

mongo --eval " var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID' var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY' " \
--shell --nodb

This example opens the mongo shell without a connection to a MongoDB database. The --eval option sets the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY variables in the mongo shell to the value of the corresponding environment variables. The specified variables are also supported by the AWS CLI.

2

In the mongo shell, create a new ClientSideFieldLevelEncryptionOptions variable for storing the client-side field level encryption configuration document:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"aws" : {
"accessKeyId" : AWS_ACCESS_KEY_ID,
"secretAccessKey" : AWS_SECRET_ACCESS_KEY
}
}
}
3

In the mongo shell, use the Mongo() constructor to establish a database connection to the target cluster. Specify the ClientSideFieldLevelEncryptionOptions document as the second parameter to the Mongo() constructor to configure the connection for client-side field level encryption:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

Replace the replaceMe.example.net URI with the connection string for the target cluster.

Use the csfleDatabaseConnection object to access client-side field level encryption shell methods.

For complete documentation on establishing database connections configured for client-side field level encryption, see the Mongo() constructor reference.

4

Use the getKeyVault() method on the csfleDatabaseConnection database connection object to create the keyVault object:

keyVault = csfleDatabaseConnection.getKeyVault();
Important

Client-side field level encryption depends on server-enforced uniqueness of key alternate names. getKeyVault() creates a unique index on keyAltNames if one does not exist. Do not drop the unique index created by getKeyVault().

5

Use the KeyVault.createKey() method on the keyVault object to create a new data encryption key in the key vault:

keyVault.createKey(
"aws",
"arn:aws:kms:region:account:key/keystring",
[ "keyAlternateName" ]
)

Where:

  • The first parameter must be "aws" to specify the configured Amazon Web Services KMS.
  • The second parameter must be the full Amazon Resource Name (ARN) of the Customer Master Key (CMK). MongoDB uses the specified CMK to encrypt the data encryption key.
  • The third parameter may be an array of one or more keyAltNames for the data encryption key. Each key alternate name must be unique. getKeyVault() creates a unique index on keyAltNames to enforce uniqueness on the field if one does not already exist. Key alternate names facilitate data encryption key findability.

If successful, createKey() returns the UUID of the new data encryption key. The UUID is a BSON Binary (BinData) object with subtype 4 that uniquely identifies the data encryption key. The UUID string is the hexadecimal representation of the underlying binary data.

If you are providing the data encryption key to an official 4.2+ compatible driver in order to configure automatic client-side field level encryption, you must use the base64 representation of the UUID string.

You can run the following operation in the mongo shell to convert a UUID hexadecimal string to its base64 representation:

UUID("b4b41b33-5c97-412e-a02b-743498346079").base64()

Supply the UUID of your own data encryption key to this command, as returned from createKey() above, or as described in Retrieve an Existing Data Encryption Key.

The following procedure uses the mongo shell to manage the alternate names of a data encryption key. For guidance on data encryption key management using a 4.2+ compatible driver, see the driver documentation instead.

If you are still within your configured mongo shell session from the Create a Data Encryption Key steps above, you can skip directly to step 5.

Use the tabs below to select the KMS appropriate for your deployment:

1

Configuring client-side field level encryption for the AWS KMS requires an AWS Access Key ID and its associated Secret Access Key. The AWS Access Key must correspond to an IAM user with all List and Read permissions for the KMS service.

To mitigate the risk of these credentials leaking into logs, the following procedure passes the values into the mongo shell using environment variables.

First, ensure that you have configured the following environment variables according to your platform's documentation:

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

Next, create a mongo shell session using the --eval, --shell, and --nodb options:

mongo --eval " var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID' var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY' " \
--shell --nodb

This example opens the mongo shell without a connection to a MongoDB database. The --eval option sets the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY variables in the mongo shell to the value of the corresponding environment variables. The specified variables are also supported by the AWS CLI.

2

In the mongo shell, create a new ClientSideFieldLevelEncryptionOptions variable for storing the client-side field level encryption configuration document:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"aws" : {
"accessKeyId" : AWS_ACCESS_KEY_ID,
"secretAccessKey" : AWS_SECRET_ACCESS_KEY
}
}
}
3

In the mongo shell, use the Mongo() constructor to establish a database connection to the target cluster. Specify the ClientSideFieldLevelEncryptionOptions document as the second parameter to the Mongo() constructor to configure the connection for client-side field level encryption:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

Replace the replaceMe.example.net URI with the connection string for the target cluster.

Use the csfleDatabaseConnection object to access client-side field level encryption shell methods.

For complete documentation on establishing database connections configured for client-side field level encryption, see the Mongo() constructor reference.

4

Use the getKeyVault() method on the csfleDatabaseConnection database connection object to create the keyVault object:

keyVault = csfleDatabaseConnection.getKeyVault();
Important

Client-side field level encryption depends on server-enforced uniqueness of key alternate names. getKeyVault() creates a unique index on keyAltNames if one does not exist. Do not drop the unique index created by getKeyVault().

5

Use the steps below to either add or remove an existing Key Alternate Name.

Add Key Alternate Name
Important

Client-side field level encryption depends on server-enforced uniqueness of key alternate names. Validate that a unique index exists on keyAltNames prior to adding a new key alternate name. If the unique index was dropped, you must re-create it prior to adding any key alternate names.

Use the KeyVault.addKeyAlternateName() to add a new alternate name to a data encryption key:

keyVault.addKeyAlternateName(
UUID("<Replace Me With The UUID Of The Key To Modify"),
"NewKeyAltNameForMyFirstCSFLEDataKey"
)

Where:

  • The first parameter must be the UUID of the data encryption key to modify.
  • The second parameter must be a unique string. getKeyVault() creates a unique index on keyAltNames to enforce uniqueness of key alternate names.

KeyVault.addKeyAlternateName() returns the data encryption key document prior to modification. Use KeyVault.getKey() to retrieve the modified data encryption key.

Remove Key Alternate Name

Use the KeyVault.removeKeyAlternateName() to remove a key alternate name from a data encryption key:

keyVault.removeKeyAlternateName(
UUID("<Replace Me With The UUID Of The Key To Modify"),
"NewKeyAltNameForMyFirstCSFLEDataKey"
)

Where:

  • The first parameter must be the UUID of the data encryption key to modify.
  • The second parameter must be a string key alternate name.

KeyVault.removeKeyAlternateName() returns the data encryption key prior to modification. Use KeyVault.getKey() to retrieve the modified data encryption key.

Warning

Deleting a data encryption key renders all fields encrypted using that key as permanently unreadable.

The following procedure uses the mongo shell to remove a data encryption key from the key vault. For guidance on data encryption key management using a 4.2+ compatible driver, see the driver documentation instead.

If you are still within your configured mongo shell session from the Create a Data Encryption Key steps above, you can skip directly to step 5.

Use the tabs below to select the KMS appropriate for your deployment:

1

Configuring client-side field level encryption for the AWS KMS requires an AWS Access Key ID and its associated Secret Access Key. The AWS Access Key must correspond to an IAM user with all List and Read permissions for the KMS service.

To mitigate the risk of these credentials leaking into logs, the following procedure passes the values into the mongo shell using environment variables.

First, ensure that you have configured the following environment variables according to your platform's documentation:

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

Next, create a mongo shell session using the --eval, --shell, and --nodb options:

mongo --eval " var AWS_ACCESS_KEY_ID = '$AWS_ACCESS_KEY_ID' var AWS_SECRET_ACCESS_KEY = '$AWS_SECRET_ACCESS_KEY' " \
--shell --nodb

This example opens the mongo shell without a connection to a MongoDB database. The --eval option sets the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY variables in the mongo shell to the value of the corresponding environment variables. The specified variables are also supported by the AWS CLI.

2

In the mongo shell, create a new ClientSideFieldLevelEncryptionOptions variable for storing the client-side field level encryption configuration document:

var ClientSideFieldLevelEncryptionOptions = {
"keyVaultNamespace" : "encryption.__dataKeys",
"kmsProviders" : {
"aws" : {
"accessKeyId" : AWS_ACCESS_KEY_ID,
"secretAccessKey" : AWS_SECRET_ACCESS_KEY
}
}
}
3

In the mongo shell, use the Mongo() constructor to establish a database connection to the target cluster. Specify the ClientSideFieldLevelEncryptionOptions document as the second parameter to the Mongo() constructor to configure the connection for client-side field level encryption:

csfleDatabaseConnection = Mongo(
"mongodb://replaceMe.example.net:27017/?replicaSet=myMongoCluster",
ClientSideFieldLevelEncryptionOptions
)

Replace the replaceMe.example.net URI with the connection string for the target cluster.

Use the csfleDatabaseConnection object to access client-side field level encryption shell methods.

For complete documentation on establishing database connections configured for client-side field level encryption, see the Mongo() constructor reference.

4

Use the getKeyVault() method on the csfleDatabaseConnection database connection object to create the keyVault object:

keyVault = csfleDatabaseConnection.getKeyVault();
Important

Client-side field level encryption depends on server-enforced uniqueness of key alternate names. getKeyVault() creates a unique index on keyAltNames if one does not exist. Do not drop the unique index created by getKeyVault().

5

Use the KeyVault.deleteKey() method on the keyVault object to delete a data key from the key vault:

keyVault.deleteKey(UUID("<Replace Me With The UUID Of The Key To Delete"))

To retrieve an existing data encryption key document from the key vault, either:

If providing the data encryption key to an official 4.2+ compatible driver in order to configure automatic client-side field level encryption, you must use the base64 representation of the UUID string.

You can run the following operation in the mongo shell to convert a UUID hexadecimal string to its base64 representation:

UUID("b4b41b33-5c97-412e-a02b-743498346079").base64()

Supply the UUID of your own data encryption key to this command.

Give Feedback