Configuring the ESA with AWS Key Management System (KMS)

Steps to connect to AWS KMS.

Verifying the Prerequisites

Ensure that the following prerequisites are met before configuring the ESA with the AWS Key Store.

Authorization

The Amazon Web Services Key Management Service (AWS KMS) allows you to enable the creation of the data encryption key (DEK). Additionally, you can also encrypt and decrypt the data, and generate random bytes of data using the Key Management Gateway (KMGW) in the ESA.

To use the AWS KMS as a key store, the following permissions are required by the AWS user or role:

Table: Permissions for accessing AWS KMS user or role

ActionsPermissionsDescription
Decryptkms:DecryptEnable decryption using a key.
Encryptkms:EncryptEnable encryption using a key.
TagResourcekms:TagResourceEnable the possibility to tag a resource.
GenerateRandomkms:GenerateRandomGrant permission to generate random bytes.
DescribeKeykms:DescribeKeyGrant permission to view information about a key.
CreateKeykms:CreateKeyGrant permission to create a new key.
List MasterKeystag:GetResourcesList all the masterkeys.

Authentication

Authentication methods depend on if using AWS or On Premise.

On AWS

If the ESA EC2 instance is running on the AWS and an IAM role is setup, then the IAM role gets linked to the ESA EC2 instance. Further, the SDK automatically gets the credentials to perform authenticated calls to the AWS.

On Premise

If the ESA is running on any other environment, then ensure to set up the environment by generating the long-term credentials on the AWS. The following environment variables are used to set the long-term credentials:

Table: List of Environments Variables to set the long-term credentials

Environment VariablesValuesDescription
AWS_REGION*us-east-1The AWS region to use.
AWS_ACCESS_KEY_ID*AKI…AWS Access key ID, which is the long-term credential.
AWS_SECRET_ACCESS_KEY*wJalrXUt…CYEXAMPLEKEYAWS Secret access key, which is the long-term credentials

Note: Ensure that the environments marked with * are set when they are not running on the EC2 instance.

Configuring Connection with AWS KMS with the AWS Customer Managed Keys

The Key Store with the AWS customer managed keys is configured by using one of the following methods:

  • Setting the environment variables.
  • Using the roles that are set in the AWS KMS environment.

Configuring the AWS Key Store using the Environment Variables

To configure connection with AWS KMS using the environment variables:

  1. On the ESA Web UI, navigate to Key Management > Key Stores.

    The Key Stores screen appears.

  2. Click New Key Store.

    The Create New Key Store screen appears.

  3. In the Key Store Information section, enter the following details.

    • Name: Type a unique name for AWS KMS. For example, type AWS_KMS. The name that you type will update the Key Store installation path field.
    • Type: Select AWS KMS.

  4. In the Key Store files and environment variables > Key Store environment variables section, click Add environment variable.
    The Add Key Store environment variable dialog box appears.

  5. Enter the following details, and then click Save:

    • Environment variable name: Specify the environment variable name for the AWS KMS. For example, specify the following entries:
      • AWS_ACCESS_KEY_ID
      • AWS_SECRET_ACCESS_KEY
      • AWS_REGION
    • Environment variable value: Specify the value for the corresponding environment variable.
      If you want to mask the value of the variable in the UI, then click the Sensitive toggle to the on position. This ensures that the variable value is hidden while typing and is replaced with asterisks of a fixed-length in the list of environment variables.

  6. Click Save.
    The Key Store saved successfully message appears.

  7. Click Test to test the Key Store connection.
    The Test Key Store Connection dialog box appears.

  8. Click OK to close the Test Key Store Connection dialog box.

  9. Click Set As Active to activate the Key Store.
    The AWS Key Store is set as active.

Note: You should verify that the master key is generated by the AWS Key Store.

Configuring the AWS Key Store using the Authorized IAM Role

Before you begin: Ensure that an ESA instance is created in the AWS.

To configure the AWS Key Store by using the authorized IAM role:

  1. In the AWS screen, navigate to AWS > EC2.

  2. Select the required instance.

  3. Navigate to Actions > Security > Modify IAM.

  4. Select the role with the AWS KMS permissions.

    The IAM role is modified for the instance.

  5. On the ESA Web UI, navigate to Key Management > Key Stores.

    The Key Stores screen appears.

  6. Click New Key Store.

    The Create New Key Store screen appears.

  7. In the Key Store Information section, enter the following details.

    • Name: Type a unique name for AWS KMS. For example, type AWS_KMS.
    • Type: Select AWS KMS.

  8. Click Save.
    The Key Store saved successfully message appears.

  9. Click Test to test the Key Store connection.
    The Test Key Store Connection dialog box appears.

  10. Click OK to close the Test Key Store Connection dialog box.

  11. Click Set As Active to activate the Key Store.
    The AWS Key Store is set as active.

Note: You should verify that the master key is generated by the AWS Key Store.

Keys in AWS KMS

The AWS KMS keys are tagged with the following two tags:

  • Owner: Protegrity
  • Service: KMGW

These tags are used to search or filter keys which are created by the KMGW.


Last modified : October 31, 2025