AWS KMS is a fully managed encryption service that allows you to create, manage, and control cryptographic keys used to protect your data. It provides centralized key management with strong security controls, integrates seamlessly with other AWS services, and offers both AWS-managed and customer-managed encryption keys. KMS handles the complexity of key storage, rotation, and access control while providing detailed audit logs through CloudTrail. It supports symmetric and asymmetric keys, enables envelope encryption for large datasets, and helps meet compliance requirements by providing FIPS 140-2 validated hardware security modules.

You can read more about KMS here.

Required roles

rrelayer creates new KMS keys, tags them and reads them back this means it can handle as many KMS keys are you want. This is an important factor to know because of how deeply integrated KMS is into rrelayer you need to make sure you have the correct roles allowed for the AWS credentials.

required roles:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowKMSKeyCreation",
      "Effect": "Allow",
      "Action": [
        "kms:CreateKey",
        "kms:DescribeKey",
        "kms:ListKeys",
        "kms:ListAliases",
        "kms:TagResource",
        "kms:ListKeyPolicies",
        "kms:ListKeyRotations",
        "kms:ListResourceTags",
        "kms:ListRetirableGrants",
        "kms:GetKeyPolicy",
        "kms:GetPublicKey",
        "kms:DisableKey",
        "kms:EnableKey",
        "kms:CreateAlias",
        "kms:DeleteAlias",
        "kms:UpdateAlias"
      ],
      "Resource": "*"
    }
  ]
}

To enable KMS you need to add the region to the YAML under the aws_kms key:

name: first-rrelayer
description: "my first rrelayer"
api_config:
  port: 3000
  authentication_username: ${RRELAYER_AUTH_USERNAME}
  authentication_password: ${RRELAYER_AUTH_PASSWORD}
signing_provider: 
  aws_kms: 
    region: "eu-west-1"
    endpoint_url: "http://localhost:4566" # Optional: for LocalStack 

You then need to add the AWS variables to the .env

AWS_ACCESS_KEY_ID=YOUR_AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY

LocalStack Support

The optional endpoint_url field allows you to point AWS KMS requests to a custom endpoint, which is particularly useful for local development and testing with LocalStack.

signing_provider:
  aws_kms:
    region: "us-east-1"
    endpoint_url: "http://localhost:4566"

When using LocalStack:

• The region can be any valid AWS region name (LocalStack doesn't enforce region-specific behavior)
• Ensure LocalStack is running with both KMS and STS services enabled
• You still need to set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables