Client-Side Field Level Encryption¶

Launch the mongosh Shell.¶

Create a mongosh session without connecting to a running database by using the --nodb option:

mongosh --nodb

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