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:

kms_providers = {
    "aws": {
        "accessKeyId": "<IAM User Access Key ID>",
        "secretAccessKey": "<IAM User Secret Access Key>"
    }
}

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:

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

import pymongo
from pymongo import MongoClient
from pymongo.encryption_options import AutoEncryptionOpts
from bson.binary import STANDARD
from bson.codec_options import CodecOptions
connection_string = "mongodb://localhost:27017"
key_vault_namespace = "encryption.__keyVault"
fle_opts = AutoEncryptionOpts(
   kms_providers, # pass in the kms_providers from the previous step
   key_vault_namespace
)
client_encryption = pymongo.encryption.ClientEncryption(
   {
     "aws": {
       "accessKeyId": "<IAM User Access Key ID>",
       "secretAccessKey": "<IAM User Secret Access Key>"
     }
   },
   key_vault_namespace,
   client,
   CodecOptions(uuid_representation=STANDARD)
)
data_key_id = client_encryption.create_data_key("aws")

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.