Client-Side Field Level Encryption¶
When working with a MongoDB Enterprise
or MongoDB Atlas cluster, you can use mongosh
to configure
Client-Side Field Level Encryption and connect with encryption
support. Client-side field level encryption uses data encryption keys
for supporting encryption and decryption of field values, and stores
this encryption key material in a Key Management Service (KMS).
mongosh
supports the following KMS providers for use with
client-side field level encryption:
- Amazon Web Services KMS
- Azure Key Vault
- Google Cloud Platform KMS
- Locally Managed Keyfile
Create a Data Encryption Key¶
The following procedure uses mongosh
to create a data encryption key
for use with client-side field level encryption and decryption.
Use the tabs below to select the KMS appropriate for your deployment:
Create the Encryption Configuration.¶
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.
In mongosh
, create a new
ClientSideFieldLevelEncryptionOptions variable for storing the
client-side field level encryption configuration, which contains these
credentials:
var ClientSideFieldLevelEncryptionOptions = { "keyVaultNamespace" : "encryption.__dataKeys", "kmsProviders" : { "aws" : { "accessKeyId" : "YOUR_AWS_ACCESS_KEY_ID", "secretAccessKey" : "YOUR_AWS_SECRET_ACCESS_KEY" } } }
Fill in the values for YOUR_AWS_ACCESS_KEY_ID
and
YOUR_AWS_SECRET_ACCESS_KEY
as appropriate.
Connect with Encryption Support.¶
In mongosh
, 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.
Create the Key Vault Object.¶
Create the keyVault
object using the getKeyVault()
shell method:
keyVault = csfleDatabaseConnection.getKeyVault();
Create the Encryption Key.¶
Create the data encryption key using the
createKey()
shell method:
keyVault.createKey( "aws", { region: "regionname", key: "awsarn" }, [ "keyAlternateName" ] )
Where:
- The first parameter must be
"aws"
to specify the configured Amazon Web Services KMS. The second parameter must be a document containing the following:
- the AWS region you are connecting to, such as
us-west-2
- the Amazon Resource Name (ARN) to the AWS customer master key (CMK).
- the AWS region you are connecting to, such as
- 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 onkeyAltNames
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. To retrieve the new 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.