Client-Side Field Level Encryption: Use a KMS to Store the Master Key¶

Create an AWS IAM User¶

1. Create a new programmatic IAM user in the AWS management console by following the official AWS documentation on Adding a User. CSFLE-enabled clients authenticate with AWS KMS using the IAM user to encrypt and decrypt the remote master key. Take note of the following IAM credentials needed to authenticate with the KMS:

   • access key ID
   • secret access key
2. Grant the IAM user full List and Read permissions for the KMS service. See Amazon's official documentation on Adding permissions to a user to set these permissions.

Create the Master Key¶

The following diagram shows the steps required to create a new master key on a KMS provider.

1. To create a master key, log into your AWS management console and create a new symmetric master key in the KMS section. Choose a name and description that helps you identify it; these fields do not affect the functionality or configuration.
2. In the Usage Permissions step of the key generation process, add the full KMS List and Read permissions to the IAM user you created in the previous step. This authorizes the user to encrypt and decrypt the new master key.

Specify the AWS KMS Provider Credentials¶

Unlike the local key provider, the AWS KMS provider does not read the master key directly from the client application. Instead, it accepts the Access Key ID and Secret Access Key configurations that point to the master key. The IAM user must have the permissions set up in the previous step in order for the client to use the KMS to encrypt and decrypt data encryption keys. Follow the steps below to specify your credentials:

1. First, identify the following authentication credentials on AWS KMS:

   Field	Required	Description
   Access Key ID	Yes	Identifies the account user
   Secret Access Key	Yes	Contains the authentication credentials of the account user

2. Next, add your authentication credentials to your CSFLE-enabled client code:

var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>();
var awsAccessKey = Environment.GetEnvironmentVariable("FLE_AWS_ACCESS_KEY");
var awsSecretAccessKey = Environment.GetEnvironmentVariable("FLE_AWS_SECRET_ACCESS_KEY");
var awsKmsOptions = new Dictionary<string, object>
{
    { "accessKeyId", awsAccessKey },
    { "secretAccessKey", awsSecretAccessKey }
};
kmsProviders.Add("aws", awsKmsOptions);

Create a New Data Encryption Key¶

To encrypt your data, you need a data encryption key generated from your KMS-hosted master key. The following diagram shows the requests you need to make from the client application to create and store a new data encryption key:

1. First, specify the following information to access the master key:

   Field	Required	Description
   key	Yes	Amazon Resource Number (ARN) of the master key.
   region	No	AWS region of your master key, e.g. "us-west-2"; required only if not specified in your ARN.
   endpoint	No	Custom hostname for the AWS endpoint if configured for your account.

2. Once you have the required information, update and run the following code to generate the new data encryption key:

var keyVaultClient = new MongoClient(connectionString);
var clientEncryptionOptions = new ClientEncryptionOptions(
    keyVaultClient: keyVaultClient,
    keyVaultNamespace: keyVaultNamespace,
    kmsProviders: kmsProviders);
var clientEncryption = new ClientEncryption(clientEncryptionOptions);
var awsKeyARN = Environment.GetEnvironmentVariable("FLE_AWS_KEY_ARN"); // e.g. "arn:aws:kms:us-east-2:111122223333:alias/test-key"
var awsKeyRegion = Environment.GetEnvironmentVariable("FLE_AWS_KEY_REGION");
var awsEndpoint = Environment.GetEnvironmentVariable("FLE_AWS_ENDPOINT"); // Optional, AWS KMS URL.
var dataKeyOptions = new DataKeyOptions(
    masterKey: new BsonDocument
    {
        { "region", awsKeyRegion },
        { "key", awsKeyARN },
        { "endpoint", () => awsEndpoint, awsEndpoint != null }
    });
var dataKeyId = clientEncryption.CreateDataKey("aws", dataKeyOptions, CancellationToken.None);
Console.WriteLine($"AWS DataKeyId [UUID]: {dataKeyId}");
var dataKeyIdBase64 = Convert.ToBase64String(GuidConverter.ToBytes(dataKeyId, GuidRepresentation.Standard));
Console.WriteLine($"AWS DataKeyId [base64]: {dataKeyIdBase64}");

Update the Automatic Encryption JSON Schema¶

If you previously embedded the key ID of your data encryption key in your automatic encryption rules, update the JSON Schema with your new data encryption key ID.

Your client application is now ready to automatically encrypt your data using the master key on your KMS provider.