/ /

Master Key and Data Encryption Key Management

Docs Home

/ /

Client-Side Field Level Encryption

Master Key and Data Encryption Key Management

Docs Home

MongoDB Manual

Security

Client-Side Field Level Encryption

Master Key and Data Encryption Key Management

Manage Data Encryption Keys

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB.

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.

Create a Data Encryption Key

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:

Launch the `mongo` Shell.

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.

Create the Encryption Configuration.

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
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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().

Create the Data Encryption Key.

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.

Launch the `mongo` Shell.

Configuring client-side field level encryption for Azure Key Vault requires a valid Tenant ID, Client ID, and Client Secret.

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:

AZURE_TENANT_ID
AZURE_CLIENT_ID
AZURE_CLIENT_SECRET

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

mongo --eval "
    var AZURE_TENANT_ID = '$AZURE_TENANT_ID'
    var AZURE_CLIENT_ID = '$AZURE_CLIENT_ID'
    var AZURE_CLIENT_SECRET = '$AZURE_CLIENT_SECRET'
  " \
  --shell --nodb

This example opens the mongo shell without a connection to a MongoDB database. The --eval option sets the AZURE_TENANT_ID, and AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET variables in the mongo shell to the value of the corresponding environment variables.

Create the Encryption Configuration.

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" : {
    "azure" : {
      "tenantId" : AZURE_TENANT_ID,
      "clientId" : AZURE_CLIENT_ID,
      "clientSecret" : AZURE_CLIENT_SECRET
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Create the Data Encryption Key.

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

keyVault.createKey(
  "azure",
  { keyName: "keyvaultname", keyVaultEndpoint: "endpointname" },
  [ "keyAlternateName" ]
)

Where:

The first parameter must be "azure" to specify the configured Azure Key Vault.
The second parameter must be a document containing:
- the name of your Azure Key Vault
- the DNS name of the Azure Key Vault to use (e.g. my-key-vault.vault.azure.net)
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.

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.

Launch the `mongo` Shell.

Configuring client-side field level encryption for the GCP KMS requires your GCP Email and its associated Private Key.

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:

GCP_EMAIL
GCP_PRIVATEKEY

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

mongo --eval "
    var GCP_EMAIL = '$GCP_EMAIL'
    var GCP_PRIVATEKEY = '$GCP_PRIVATEKEY'
  " \
  --shell --nodb

This example opens the mongo shell without a connection to a MongoDB database. The --eval option sets the GCP_EMAIL and GCP_PRIVATEKEY variables in the mongo shell to the value of the corresponding environment variables.

Create the Encryption Configuration.

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" : {
    "gcp" : {
      "email" : GCP_EMAIL,
      "privateKey" : GCP_PRIVATEKEY
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Create the Data Encryption Key.

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

keyVault.createKey(
  "gcp",
  {
    projectId: "projectid",
    location: "locationname",
    keyRing: "keyringname",
    keyName: "keyname"
  },
  [ "keyAlternateName" ]
)

Where:

The first parameter must be "gcp" to specify the configured Google Cloud KMS.
The second parameter must be a document containing
- projectid is the name of your GCP project, such as my-project
- locationname is the location of the KMS keyring, such as global
- keyringname is the name of the KMS keyring, such as my-keyring
- keyname is the name of your 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.

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.

Generate an Encryption Key.

Configuring client-side field level encryption for a locally-managed key requires specifying a base64-encoded 96-byte string with no line breaks.

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

The following operation generates a key that meets the stated requirements and adds it to the user's ~/.profile. If the key DEV_LOCAL_KEY already exists, skip this operation.

echo "export DEV_LOCAL_KEY=\"$(head -c 96 /dev/urandom | base64 | tr -d '\n')\"" >> ~/.profile

The host operating system may require logging out and back in to refresh the loaded environment variables. Alternatively, you can use the command source ~/.profile to manually refresh the shell.

Note

Your specific host operating system or shell may have different procedures for setting persistent environment variables. Defer to the documentation for your host OS or shell for a more specific procedure as appropriate.

Launch the `mongo` Shell.

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

mongo --eval "var LOCAL_KEY = '$DEV_LOCAL_KEY' " \
  --shell --nodb

The example automatically opens a mongo shell without a connection to a MongoDB database. The --eval option sets the LOCAL_KEY variable in the mongo shell to the value of the corresponding environment variable.

Create the Encryption Configuration.

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" : {
    "local" : {
      "key" : BinData(0, LOCAL_KEY)
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Create the Data Encryption Key.

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

keyVault.createKey(
  "local",
  [ "keyAlternateName" ]
)

Where:

The first parameter must be local to specify the configured locally managed key.
The second 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.

Note

Prior to MongoDB 4.2.3, creating a local key required specifying an empty string "" as the second parameter and the optional array of keyAltNames as the third parameter.

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.

Manage a Data Encryption Key's Alternate Name

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:

Launch the `mongo` Shell.

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

Create the Encryption Configuration.

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
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Manage the Data Encryption Key's Alternate Name.

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.

Launch the `mongo` Shell.

Configuring client-side field level encryption for Azure Key Vault requires a valid Tenant ID, Client ID, and Client Secret.

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:

AZURE_TENANT_ID
AZURE_CLIENT_ID
AZURE_CLIENT_SECRET

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

mongo --eval "
    var AZURE_TENANT_ID = '$AZURE_TENANT_ID'
    var AZURE_CLIENT_ID = '$AZURE_CLIENT_ID'
    var AZURE_CLIENT_SECRET = '$AZURE_CLIENT_SECRET'
  " \
  --shell --nodb

Create the Encryption Configuration.

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" : {
    "azure" : {
      "tenantId" : AZURE_TENANT_ID,
      "clientId" : AZURE_CLIENT_ID,
      "clientSecret" : AZURE_CLIENT_SECRET
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Manage the Data Encryption Key's Alternate Name.

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

Add Key Alternate Name

Important

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.

Launch the `mongo` Shell.

Configuring client-side field level encryption for the GCP KMS requires your GCP Email and its associated Private Key.

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:

GCP_EMAIL
GCP_PRIVATEKEY

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

mongo --eval "
    var GCP_EMAIL = '$GCP_EMAIL'
    var GCP_PRIVATEKEY = '$GCP_PRIVATEKEY'
  " \
  --shell --nodb

Create the Encryption Configuration.

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" : {
    "gcp" : {
      "email" : GCP_EMAIL,
      "privateKey" : GCP_PRIVATEKEY
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Manage the Data Encryption Key's Alternate Name.

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

Add Key Alternate Name

Important

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.

Generate an Encryption Key.

Configuring client-side field level encryption for a locally-managed key requires specifying a base64-encoded 96-byte string with no line breaks.

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

The following operation generates a key that meets the stated requirements and adds it to the user's ~/.profile. If the key DEV_LOCAL_KEY already exists, skip this operation.

echo "export DEV_LOCAL_KEY=\"$(head -c 96 /dev/urandom | base64 | tr -d '\n')\"" >> ~/.profile

The host operating system may require logging out and back in to refresh the loaded environment variables. Alternatively, you can use the command source ~/.profile to manually refresh the shell.

Note

Launch the `mongo` Shell.

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

mongo --eval "var LOCAL_KEY = '$DEV_LOCAL_KEY' " \
  --shell --nodb

Create the Encryption Configuration.

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" : {
    "local" : {
      "key" : BinData(0, LOCAL_KEY)
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Manage the Data Encryption Key's Alternate Name.

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

Add Key Alternate Name

Important

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.

Remove a 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:

Launch the `mongo` Shell.

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

Create the Encryption Configuration.

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
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Delete the Data Encryption Key Using its `UUID`.

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"))

Launch the `mongo` Shell.

Configuring client-side field level encryption for Azure Key Vault requires a valid Tenant ID, Client ID, and Client Secret.

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:

AZURE_TENANT_ID
AZURE_CLIENT_ID
AZURE_CLIENT_SECRET

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

mongo --eval "
    var AZURE_TENANT_ID = '$AZURE_TENANT_ID'
    var AZURE_CLIENT_ID = '$AZURE_CLIENT_ID'
    var AZURE_CLIENT_SECRET = '$AZURE_CLIENT_SECRET'
  " \
  --shell --nodb

Create the Encryption Configuration.

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" : {
    "azure" : {
      "tenantId" : AZURE_TENANT_ID,
      "clientId" : AZURE_CLIENT_ID,
      "clientSecret" : AZURE_CLIENT_SECRET
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Delete the Data Encryption Key Using its `UUID`.

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"))

Launch the `mongo` Shell.

Configuring client-side field level encryption for the GCP KMS requires your GCP Email and its associated Private Key.

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:

GCP_EMAIL
GCP_PRIVATEKEY

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

mongo --eval "
    var GCP_EMAIL = '$GCP_EMAIL'
    var GCP_PRIVATEKEY = '$GCP_PRIVATEKEY'
  " \
  --shell --nodb

Create the Encryption Configuration.

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" : {
    "gcp" : {
      "email" : GCP_EMAIL,
      "privateKey" : GCP_PRIVATEKEY
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Delete the Data Encryption Key Using its `UUID`.

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"))

Generate an Encryption Key.

Configuring client-side field level encryption for a locally-managed key requires specifying a base64-encoded 96-byte string with no line breaks.

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

The following operation generates a key that meets the stated requirements and adds it to the user's ~/.profile. If the key DEV_LOCAL_KEY already exists, skip this operation.

echo "export DEV_LOCAL_KEY=\"$(head -c 96 /dev/urandom | base64 | tr -d '\n')\"" >> ~/.profile

The host operating system may require logging out and back in to refresh the loaded environment variables. Alternatively, you can use the command source ~/.profile to manually refresh the shell.

Note

Launch the `mongo` Shell.

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

mongo --eval "var LOCAL_KEY = '$DEV_LOCAL_KEY' " \
  --shell --nodb

Create the Encryption Configuration.

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" : {
    "local" : {
      "key" : BinData(0, LOCAL_KEY)
    }
  }
}

Connect with Encryption Support.

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.

Create the Key Vault Object.

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

keyVault = csfleDatabaseConnection.getKeyVault();

Important

Delete the Data Encryption Key Using its `UUID`.

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"))

Retrieve an Existing Data Encryption Key

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

Use getKey() to retrieve the created key by its UUID, or
Use getKeyByAltName() to retrieve the key by its alternate name, if specified. For more information on working with alternate names, see Manage a Data Encryption Key's Alternate Name.

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.

Back

Master Key and Data Encryption Key Management

Limitations

Create a Data Encryption Key

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Create the Data Encryption Key.

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Create the Data Encryption Key.

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Create the Data Encryption Key.

Generate an Encryption Key.

Note

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Create the Data Encryption Key.

Note

Manage a Data Encryption Key's Alternate Name

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Manage the Data Encryption Key's Alternate Name.

Important

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Manage the Data Encryption Key's Alternate Name.

Important

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Manage the Data Encryption Key's Alternate Name.

Important

Generate an Encryption Key.

Note

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Manage the Data Encryption Key's Alternate Name.

Important

Remove a Data Encryption Key

Warning

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Delete the Data Encryption Key Using its UUID.

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Delete the Data Encryption Key Using its UUID.

Launch the mongo Shell.

Create the Encryption Configuration.

Connect with Encryption Support.

Create the Key Vault Object.

Important

Delete the Data Encryption Key Using its UUID.

Generate an Encryption Key.

Launch the `mongo` Shell.

Launch the `mongo` Shell.

Launch the `mongo` Shell.

Launch the `mongo` Shell.

Launch the `mongo` Shell.

Launch the `mongo` Shell.

Launch the `mongo` Shell.

Launch the `mongo` Shell.

Launch the `mongo` Shell.

Delete the Data Encryption Key Using its `UUID`.

Launch the `mongo` Shell.

Delete the Data Encryption Key Using its `UUID`.

Launch the `mongo` Shell.

Delete the Data Encryption Key Using its `UUID`.

Launch the `mongo` Shell.

Delete the Data Encryption Key Using its `UUID`.