AWS KMS

Overview

The EQTY Governance Platform uses AWS Key Management Service (KMS) for managing cryptographic keys for DID (Decentralized Identifier) signing operations.

AWS KMS provides:

• Managed Key Storage – Secure, FIPS 140-2 validated hardware security modules
• Automatic Key Rotation – Optional automatic annual key rotation
• Audit Trail – CloudTrail integration for all key usage

Platform behavior:

• Automatically creates and manages KMS keys with the configured alias prefix
• Stores key IDs in the database
• Uses asymmetric keys (ECC_SECG_P256K1) for signing operations

This guide covers:

• Setting up an IAM user with KMS permissions (CLI or AWS Console)
• Configuring the Helm chart for AWS KMS
• Verifying the configuration

Prerequisites

• AWS account with permissions to use KMS and create IAM users/policies
• AWS CLI installed and configured (for CLI method)
• AWS region selected for key storage (e.g. us-east-1)

Helm Configuration

Add the following to the values.yaml and secrets.yaml files. Placeholders will be filled in throughout the steps below.

values.yaml:

auth-service:
  config:
    keyManagement:
      provider: "aws_kms"
      aws_kms:
        region: "<aws-region>" # Chosen before step 1
        aliasPrefix: "alias/eqtylab/did"
        deletionWindowDays: 7

secrets.yaml:

global:
  secrets:
    create: true
    keyManagement:
      provider: "aws_kms"
      aws_kms:
        secretName: "platform-aws-kms"
        values:
          accessKeyId: "<access-key-id>" # Filled in after step 4
          secretAccessKey: "<secret-access-key>" # Filled in after step 4
          sessionToken: ""

Quick Start (CLI Method - Recommended)

Choose an AWS region for key storage (e.g. us-east-1, eu-west-1). Update values.yaml with the chosen region.

values.yaml -> auth-service.config.keyManagement.aws_kms:

region: "<chosen-region>"

1. Create IAM Policy

Create a policy document file named kms-policy.json with the following content:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowKMSKeyCreation",
      "Effect": "Allow",
      "Action": ["kms:CreateKey", "kms:TagResource"],
      "Resource": "*"
    },
    {
      "Sid": "AllowAliasCreationWithPrefix",
      "Effect": "Allow",
      "Action": ["kms:CreateAlias"],
      "Resource": "*",
      "Condition": {
        "StringLike": {
          "kms:RequestAlias": "alias/eqtylab/did/*"
        }
      }
    },
    {
      "Sid": "AllowOperationsOnPrefixedKeys",
      "Effect": "Allow",
      "Action": [
        "kms:DescribeKey",
        "kms:GetPublicKey",
        "kms:Sign",
        "kms:Verify",
        "kms:ScheduleKeyDeletion",
        "kms:DeleteAlias",
        "kms:UpdateAlias"
      ],
      "Resource": "*",
      "Condition": {
        "ForAnyValue:StringLike": {
          "kms:ResourceAliases": "alias/eqtylab/did/*"
        }
      }
    },
    {
      "Sid": "AllowListOperations",
      "Effect": "Allow",
      "Action": ["kms:ListAliases", "kms:ListKeys"],
      "Resource": "*"
    }
  ]
}

Note on permissions: AWS only supports restricting kms:CreateAlias by alias name, not by target key. This means the policy grants the ability to assign an alias/eqtylab/did/* alias to any key in the account — not just keys created by the platform. Sign and verify operations are still scoped to aliased keys, limiting the impact. Enabling CloudTrail on KMS is recommended to audit alias assignments.

Create the IAM policy:

aws iam create-policy \
  --policy-name governance-kms-access \
  --policy-document file://kms-policy.json \
  --description "Allows EQTY Governance Platform to manage KMS keys for DID signing"

Save the policy ARN from the output — it will look like arn:aws:iam::123456789012:policy/governance-kms-access.

2. Create IAM User

aws iam create-user --user-name governance-platform-kms

3. Attach Policy to User

To find the AWS account ID:

aws sts get-caller-identity --query Account --output text

Attach the policy. Replace ACCOUNT_ID with the value from above:

aws iam attach-user-policy \
  --user-name governance-platform-kms \
  --policy-arn arn:aws:iam::ACCOUNT_ID:policy/governance-kms-access

4. Create Access Key

aws iam create-access-key --user-name governance-platform-kms

Save both the AccessKeyId and SecretAccessKey from the output. The secret access key is only shown once and cannot be retrieved later.

The output will look like:

{
  "AccessKey": {
    "UserName": "governance-platform-kms",
    "AccessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "Status": "Active"
  }
}

Update secrets.yaml with the credentials.

secrets.yaml -> global.secrets.keyManagement.aws_kms.values:

accessKeyId: "<access-key-id>"
secretAccessKey: "<secret-access-key>"

Alternative: Web UI Setup

Click to expand AWS Console instructions

Using the AWS Console

1. Create IAM Policy

• Navigate to IAM console
• Go to Policies > Create policy
• Switch to JSON editor
• Paste the KMS policy JSON from step 1 above
• Name: “governance-kms-access”
• Create the policy

2. Create IAM User

• Navigate to IAM > Users
• Click “Create user”
• Username: “governance-platform-kms”
• Click “Next”

3. Attach Policy

• Select “Attach policies directly”
• Search for “governance-kms-access”
• Select the policy
• Click “Next” and “Create user”

4. Create Access Key

• Click on the created user
• Navigate to “Security credentials” tab
• Click “Create access key”
• Select “Application running outside AWS”
• Click “Next” and “Create access key”
• Save the Access Key ID and Secret Access Key

Update secrets.yaml with the credentials.

secrets.yaml -> global.secrets.keyManagement.aws_kms.values:

accessKeyId: "<access-key-id>"
secretAccessKey: "<secret-access-key>"

Verification

Test that the IAM user can access KMS. Set the credentials from step 4:

export AWS_ACCESS_KEY_ID="<access-key-id>"
export AWS_SECRET_ACCESS_KEY="<secret-access-key>"

List KMS keys (should succeed):

aws kms list-keys --region <chosen-region>

List KMS aliases (should succeed):

aws kms list-aliases --region <chosen-region>

Clean up the temporary credentials:

unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

If the commands succeed without errors, the configuration is correct. The platform will automatically create KMS keys as needed when DIDs are generated.

Key Management

The EQTY platform will automatically:

• Create new KMS keys as needed for DID signing
• Use the format: alias/eqtylab/did/<did-identifier>
• Store key IDs in the platform database
• Set appropriate key policies for signing and verification
• Cache keys according to the configured TTL

Note: Manual key creation is not supported. The platform manages all key lifecycle operations automatically.

Security Best Practices

• Audit Logging: Enable CloudTrail to log all KMS operations for compliance and security monitoring
• Access Key Rotation: Regularly rotate IAM access keys and update Kubernetes secrets
• Secure Storage: Store IAM credentials in Kubernetes secrets with appropriate RBAC restrictions
• Key Deletion: Be cautious when deleting keys — the platform stores key IDs in the database and expects keys to persist

Cost Considerations

AWS KMS pricing (as of 2025):

• Key Storage: $1/month per key
• API Requests: $0.03 per 10,000 requests
• The platform creates one key per DID, so costs scale with the number of DIDs

Consider budgeting and setting up billing alerts.

Official Documentation

• AWS KMS CLI Reference
• AWS KMS Developer Guide
• KMS Best Practices
• Asymmetric Keys in KMS
• Helm Chart Examples