Navigation

    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

    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:

    1

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

    mongosh --nodb
    2

    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.

    3

    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.

    4

    Create the keyVault object using the getKeyVault() shell method:

    keyVault = csfleDatabaseConnection.getKeyVault();
    5

    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 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.
    Tip
    See also:
    Give Feedback