AWS KMS Custom Key Store: A Deep Dive in AWS Resources & Best Practices to Adopt
Organizations handling sensitive data face increasing pressure to maintain strict control over their encryption keys while meeting compliance requirements. A 2023 Thales Data Threat Report found that 67% of organizations experienced a data breach or failed audit in the past year, with many citing inadequate key management practices as a contributing factor. For enterprises requiring the highest levels of security, AWS KMS Custom Key Stores provide a unique solution that combines the convenience of AWS Key Management Service with the control of hardware security modules (HSMs) under your direct management.
Traditional cloud encryption models require trusting the cloud provider with your encryption keys, but regulated industries like finance, healthcare, and government often need to maintain direct control over key material. Custom Key Stores address this requirement by allowing organizations to store their KMS key material in AWS CloudHSM clusters or external key managers, providing cryptographic assurance that AWS never has access to your plaintext keys. This approach enables compliance with strict regulations while maintaining the operational benefits of cloud services.
In this blog post we will learn about what AWS KMS Custom Key Store is, how you can configure and work with it using Terraform, and learn about the best practices for this service.
What is AWS KMS Custom Key Store?
AWS KMS Custom Key Store is a specialized feature that allows you to create and manage AWS KMS keys using key material stored in your own hardware security modules (HSMs) or external key managers. Unlike standard KMS keys where AWS manages the key material within their infrastructure, Custom Key Stores give you complete control over the cryptographic material while still leveraging KMS APIs for encryption operations.
The service acts as a bridge between AWS KMS and your external key storage systems, enabling you to use familiar AWS APIs while maintaining custody of your encryption keys. This architecture provides the operational simplicity of managed encryption services while meeting the most stringent security and compliance requirements that mandate customer-controlled key material.
AWS CloudHSM Integration
Custom Key Stores integrate seamlessly with AWS CloudHSM, providing FIPS 140-2 Level 3 validated hardware security modules. When you create a CloudHSM custom key store, AWS KMS communicates with your CloudHSM cluster through secure, authenticated connections. The HSM cluster must be configured with specific users and authentication credentials that KMS uses to perform cryptographic operations.
CloudHSM clusters require at least two HSMs across different Availability Zones for high availability. The cluster operates independently from AWS KMS, with your organization retaining full control over the HSM lifecycle, including initialization, user management, and key material generation. This separation ensures that even AWS support personnel cannot access your key material, providing cryptographic assurance of data sovereignty.
The integration process involves creating a dedicated CloudHSM user account for KMS operations, configuring network connectivity between KMS and your HSM cluster, and establishing trust relationships through certificate-based authentication. Once configured, KMS can create, rotate, and use encryption keys stored within your HSM cluster while maintaining the familiar KMS API interface for application integration.
External Key Store Architecture
External Key Stores extend the Custom Key Store concept beyond AWS infrastructure by integrating with external key managers from vendors like Thales, Entrust, or other FIPS-validated HSM providers. This option provides maximum flexibility for organizations with existing key management infrastructure or specific vendor requirements.
External key managers connect to AWS KMS through the External Key Store Proxy (XKS), which acts as a translation layer between KMS APIs and your external key management system. The XKS proxy handles authentication, request routing, and cryptographic operations while maintaining secure communication channels between AWS and your external infrastructure.
Organizations can host XKS proxies in their own data centers, on-premises environments, or third-party hosting facilities, providing complete geographic and administrative control over key storage. This architecture enables hybrid cloud scenarios where sensitive workloads remain on-premises while leveraging AWS services for less sensitive operations, all unified under a single key management framework.
Strategic Security and Compliance Advantages
Custom Key Stores address critical security and compliance challenges that traditional cloud encryption models cannot solve. Organizations subject to regulations like FIPS 140-2 Level 3, Common Criteria EAL 4+, or specific government security standards often require demonstrated control over cryptographic key material that extends beyond logical access controls.
The architecture provides several strategic advantages for enterprise security programs. First, it enables zero-trust cryptographic operations where no single entity, including AWS, can access plaintext key material. Second, it supports regulatory compliance frameworks that require physical control over cryptographic modules. Third, it allows organizations to maintain consistent key management practices across hybrid and multi-cloud environments.
Cryptographic Assurance and Attestation
Custom Key Stores provide cryptographic proof that AWS cannot access your key material through hardware-based attestation mechanisms. CloudHSM clusters generate cryptographic attestations that prove key material never leaves the HSM boundary, while external key stores provide similar assurances through vendor-specific attestation capabilities.
This attestation capability is crucial for compliance audits and regulatory reviews, as it provides mathematical proof of key custody rather than relying solely on policy attestations. Organizations can present these cryptographic proofs to auditors, regulators, or customers as evidence of proper key management practices.
The attestation mechanisms also support continuous compliance monitoring, where organizations can programmatically verify the integrity of their key management infrastructure and detect any unauthorized access attempts or configuration changes that might compromise security.
Multi-Jurisdictional Compliance
Organizations operating in multiple jurisdictions face complex regulatory requirements around data residency, key escrow, and cryptographic sovereignty. Custom Key Stores enable compliance with diverse regulations by allowing organizations to maintain key material within specific geographic boundaries or under particular legal frameworks.
For example, European organizations subject to GDPR can maintain encryption keys within EU boundaries using external key stores, while still leveraging AWS services for data processing. Similarly, organizations in regulated industries can comply with sector-specific requirements like HIPAA, SOX, or PCI-DSS while maintaining operational efficiency through cloud services.
The flexibility to choose key storage locations and custody models also supports data sovereignty requirements imposed by various national governments, enabling organizations to demonstrate compliance with local data protection laws while maintaining global operational capabilities.
Risk Mitigation and Business Continuity
Custom Key Stores provide additional layers of risk mitigation beyond standard cloud encryption models. By maintaining control over key material, organizations can implement independent backup and recovery procedures, establish alternate key access paths, and maintain cryptographic operations even during cloud service disruptions.
The distributed nature of CloudHSM clusters across multiple Availability Zones ensures high availability for key operations, while external key stores can implement geo-distributed architectures that span multiple regions or continents. This redundancy protects against both technical failures and geographic disasters that might affect single-region deployments.
Organizations can also implement key escrow or split-knowledge procedures where multiple parties must collaborate to access critical key material, providing additional protection against insider threats or coercion scenarios.
Key Features and Capabilities
Hardware Security Module Integration
Custom Key Stores provide direct integration with FIPS 140-2 Level 3 validated hardware security modules, ensuring that key material never exists in plaintext outside the HSM boundary. This integration supports both AWS CloudHSM and external HSM providers, giving organizations flexibility in choosing their preferred hardware platform while maintaining consistent API interfaces.
Cryptographic Key Lifecycle Management
The service manages the complete lifecycle of cryptographic keys within your controlled environment, including generation, rotation, archival, and destruction. Organizations can implement custom key rotation policies, maintain detailed audit logs of key operations, and establish governance workflows that align with their security policies.
Cross-Service Encryption Support
Custom Key Store keys integrate with all AWS services that support KMS encryption, including Amazon S3, EBS, RDS, and Lambda. This comprehensive integration ensures that organizations can maintain consistent encryption policies across their entire AWS infrastructure while retaining control over key material.
API Compatibility and Migration Support
Custom Key Store keys maintain full compatibility with existing KMS APIs, enabling seamless migration from standard KMS keys without requiring application changes. This compatibility ensures that existing encryption workflows continue to function while providing enhanced security and compliance capabilities.
Integration Ecosystem
Custom Key Stores integrate extensively with AWS security and compliance services, creating a comprehensive data protection ecosystem. The service works seamlessly with AWS CloudTrail for audit logging, AWS Config for configuration management, and AWS Security Hub for centralized security monitoring.
At the time of writing there are 150+ AWS services that integrate with KMS Custom Key Store in some capacity. Services like Amazon S3, Amazon EBS, Amazon RDS, AWS Lambda, and Amazon ECS can all use Custom Key Store keys for encryption, providing consistent protection across your entire AWS infrastructure.
AWS CloudHSM Integration: Custom Key Stores integrate natively with CloudHSM clusters, providing high-performance cryptographic operations within AWS infrastructure. This integration supports automatic failover, load balancing, and monitoring of HSM resources.
External Key Manager Support: The service supports integration with external key management systems from vendors like Thales, Entrust, and other certified HSM providers. This capability enables organizations to leverage existing investments in key management infrastructure while extending protection to cloud workloads.
Multi-Account and Cross-Region Operations: Custom Key Stores support resource sharing across AWS accounts and regions, enabling enterprise-scale key management architectures. Organizations can centralize key management while distributing cryptographic operations across multiple business units or geographic regions.
The integration ecosystem extends beyond AWS services to include third-party security tools, compliance platforms, and enterprise key management solutions. This comprehensive integration support ensures that Custom Key Stores can fit into existing security architectures while providing enhanced protection for cloud-based workloads.
Pricing and Scale Considerations
Custom Key Stores operate on a usage-based pricing model that combines KMS key charges with additional fees for custom key store operations. The pricing structure includes monthly charges for each custom key store ($1.00 per month), plus standard KMS key charges ($1.00 per month per key), and per-request charges for cryptographic operations ($0.03 per 10,000 requests).
CloudHSM custom key stores incur additional charges for the underlying CloudHSM clusters, which cost $1.60 per hour per HSM instance. Organizations typically deploy at least two HSMs for high availability, resulting in monthly costs of approximately $2,300 for a minimal deployment. External key stores avoid CloudHSM charges but may incur costs for external key manager licensing and infrastructure.
Scale Characteristics
Custom Key Stores support enterprise-scale operations with performance characteristics that meet demanding production requirements. CloudHSM clusters can perform up to 5,000 RSA-2048 operations per second per HSM, with linear scaling across multiple HSMs. External key stores performance depends on the capabilities of the external key manager and network connectivity.
The service supports unlimited numbers of custom key stores within an AWS account, with each store capable of managing thousands of encryption keys. Organizations can implement multiple custom key stores to separate different security domains, compliance requirements, or business units while maintaining centralized management capabilities.
Custom Key Stores provide built-in high availability through multi-AZ deployments and automatic failover capabilities. The service monitors HSM health and automatically routes requests to available HSMs, ensuring continuous operation even during hardware failures or maintenance events.
Enterprise Considerations
Enterprise deployments typically require additional considerations around governance, monitoring, and disaster recovery. Custom Key Stores support enterprise features including CloudTrail integration for audit logging, CloudWatch metrics for operational monitoring, and AWS Config rules for compliance validation.
Organizations can implement custom key store architectures that span multiple AWS regions, providing geographic redundancy and supporting global operations. Cross-region replication capabilities ensure that key material remains available during regional service disruptions while maintaining compliance with data residency requirements.
The service integrates with enterprise identity management systems through AWS IAM, enabling organizations to implement role-based access controls and automated provisioning workflows. This integration supports both human users and service accounts, providing flexible access management that aligns with enterprise security policies.
Custom Key Stores provide superior security and compliance capabilities compared to standard KMS keys, but at significantly higher operational costs and complexity. However, for infrastructure running on AWS this is the only option that provides hardware-backed key custody while maintaining AWS service integration.
Organizations must carefully evaluate the cost-benefit tradeoff between enhanced security and operational complexity. Many enterprises implement hybrid approaches where only the most sensitive workloads use Custom Key Store keys, while less critical data uses standard KMS keys, optimizing both security and cost across their infrastructure.
Managing Custom Key Store using Terraform
Terraform provides comprehensive support for managing Custom Key Stores, though the complexity varies significantly based on the chosen architecture. CloudHSM-based custom key stores require careful coordination between HSM cluster provisioning, network configuration, and KMS resource creation.
CloudHSM Custom Key Store Deployment
Creating a CloudHSM custom key store requires establishing the underlying CloudHSM cluster and configuring the necessary network and security components before creating the KMS custom key store resource.
# CloudHSM cluster for custom key store
resource "aws_cloudhsm_v2_cluster" "kms_cluster" {
hsm_type = "hsm1.medium"
subnet_ids = [aws_subnet.hsm_subnet_1.id, aws_subnet.hsm_subnet_2.id]
tags = {
Name = "kms-custom-store-cluster"
Environment = "production"
Purpose = "kms-custom-key-store"
}
}
# CloudHSM instances for high availability
resource "aws_cloudhsm_v2_hsm" "kms_hsm_1" {
cluster_id = aws_cloudhsm_v2_cluster.kms_cluster.cluster_id
subnet_id = aws_subnet.hsm_subnet_1.id
availability_zone = "us-west-2a"
}
resource "aws_cloudhsm_v2_hsm" "kms_hsm_2" {
cluster_id = aws_cloudhsm_v2_cluster.kms_cluster.cluster_id
subnet_id = aws_subnet.hsm_subnet_2.id
availability_zone = "us-west-2b"
}
# Custom key store configuration
resource "aws_kms_custom_key_store" "primary" {
custom_key_store_name = "primary-key-store"
cloud_hsm_cluster_id = aws_cloudhsm_v2_cluster.kms_cluster.cluster_id
trust_anchor_certificate = file("${path.module}/trust-anchor.pem")
key_store_password = var.key_store_password
tags = {
Name = "primary-custom-key-store"
Environment = "production"
Compliance = "fips-140-2-level-3"
}
depends_on = [
aws_cloudhsm_v2_hsm.kms_hsm_1,
aws_cloudhsm_v2_hsm.kms_hsm_2
]
}
This configuration creates a CloudHSM cluster with two HSMs across different Availability Zones for high availability. The trust_anchor_certificate
parameter requires the root certificate from your CloudHSM cluster, which must be extracted after cluster initialization. The key_store_password
should be stored securely using Terraform's variable mechanisms or external secret management systems.
The depends_on
clause ensures that both HSMs are fully provisioned before creating the custom key store. This dependency management is crucial because the custom key store creation will fail if the CloudHSM cluster is not properly initialized and configured.
External Key Store Configuration
External key stores provide greater flexibility but require careful configuration of the external key manager and XKS proxy components.
# External key store configuration
resource "aws_kms_custom_key_store" "external" {
custom_key_store_name = "external-key-store"
custom_key_store_type = "EXTERNAL_KEY_STORE"
xks_proxy_uri_endpoint = "<https://xks-proxy.example.com>"
xks_proxy_uri_path = "/kms/xks/v1"
xks_proxy_vpc_endpoint_service_name = aws_vpc_endpoint_service.xks_proxy.service_name
xks_proxy_authentication_credential = jsonencode({
access_key_id = var.xks_proxy_access_key
secret_access_key = var.xks_proxy_secret_key
})
xks_proxy_connectivity = "VPC_ENDPOINT_SERVICE"
tags = {
Name = "external-key-store"
Environment = "production"
KeyManager = "thales-luna"
}
}
# VPC endpoint service for XKS proxy
resource "aws_vpc_endpoint_service" "xks_proxy" {
acceptance_required = false
auto_accept = true
network_load_balancer_arns = [aws_lb.xks_proxy.arn]
allowed_principals = [
"arn:aws:iam::${data.aws_caller_identity.current.account_id}:root"
]
tags = {
Name = "xks-proxy-endpoint-service"
Purpose = "kms-external-key-store"
}
}
External key store configurations require establishing secure connectivity between AWS KMS and your external key manager. The XKS proxy must be deployed with proper TLS certificates, authentication credentials, and network access controls. The xks_proxy_authentication_credential
should contain the credentials that KMS uses to authenticate with your XKS proxy.
The VPC endpoint service configuration enables private connectivity between AWS KMS and your XKS proxy, ensuring that key management traffic does not traverse the public
Managing KMS Custom Key Store using Terraform
AWS KMS Custom Key Store configurations can be complex, particularly when integrating with external HSMs or managing key material outside of AWS. This section demonstrates practical Terraform configurations for setting up and managing custom key stores with proper security controls.
CloudHSM-based Custom Key Store
When implementing a custom key store backed by AWS CloudHSM, you need to ensure proper cluster configuration and secure key material management.
# CloudHSM cluster for custom key store
resource "aws_cloudhsm_v2_cluster" "kms_cluster" {
hsm_type = "hsm1.medium"
subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]
tags = {
Name = "kms-custom-key-store-cluster"
Environment = "production"
Purpose = "custom-key-store"
}
}
# HSM instances for the cluster
resource "aws_cloudhsm_v2_hsm" "kms_hsm_1" {
cluster_id = aws_cloudhsm_v2_cluster.kms_cluster.cluster_id
availability_zone = data.aws_availability_zones.available.names[0]
tags = {
Name = "kms-hsm-1"
}
}
resource "aws_cloudhsm_v2_hsm" "kms_hsm_2" {
cluster_id = aws_cloudhsm_v2_cluster.kms_cluster.cluster_id
availability_zone = data.aws_availability_zones.available.names[1]
tags = {
Name = "kms-hsm-2"
}
}
# Custom key store backed by CloudHSM
resource "aws_kms_custom_key_store" "cloudhsm_store" {
custom_key_store_name = "production-cloudhsm-store"
cloud_hsm_cluster_id = aws_cloudhsm_v2_cluster.kms_cluster.cluster_id
trust_anchor_certificate = file("${path.module}/certificates/trust-anchor.pem")
key_store_password = var.key_store_password
# Ensure HSMs are active before creating the key store
depends_on = [
aws_cloudhsm_v2_hsm.kms_hsm_1,
aws_cloudhsm_v2_hsm.kms_hsm_2
]
tags = {
Environment = "production"
Purpose = "custom-encryption"
Compliance = "required"
}
}
# KMS key using the custom key store
resource "aws_kms_key" "custom_store_key" {
description = "KMS key using custom CloudHSM key store"
custom_key_store_id = aws_kms_custom_key_store.cloudhsm_store.id
key_usage = "ENCRYPT_DECRYPT"
key_spec = "SYMMETRIC_DEFAULT"
# Enable key rotation for custom key store keys
enable_key_rotation = true
# Key policy for custom key store
policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Sid = "Enable IAM User Permissions"
Effect = "Allow"
Principal = {
AWS = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:root"
}
Action = "kms:*"
Resource = "*"
},
{
Sid = "Allow use of the key for application encryption"
Effect = "Allow"
Principal = {
AWS = [
aws_iam_role.application_role.arn,
aws_iam_role.backup_role.arn
]
}
Action = [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
]
Resource = "*"
}
]
})
tags = {
Name = "custom-store-encryption-key"
Environment = "production"
KeyStore = "cloudhsm"
}
}
# Key alias for easier reference
resource "aws_kms_alias" "custom_store_key_alias" {
name = "alias/custom-cloudhsm-key"
target_key_id = aws_kms_key.custom_store_key.key_id
}
This configuration establishes a CloudHSM cluster with multiple HSM instances for high availability, then creates a custom key store backed by that cluster. The key store password and trust anchor certificate are managed securely through variables and external files.
External Key Store Configuration
For organizations requiring external key material storage, you can configure a custom key store that uses your own key management infrastructure.
# External key store configuration
resource "aws_kms_custom_key_store" "external_store" {
custom_key_store_name = "external-hsm-store"
custom_key_store_type = "EXTERNAL_KEY_STORE"
# External key store proxy configuration
xks_proxy_uri_endpoint = var.xks_proxy_endpoint
xks_proxy_uri_path = "/kms/xks/v1"
xks_proxy_vpc_endpoint_service_name = aws_vpc_endpoint_service.xks_proxy.service_name
xks_proxy_authentication_credential = var.xks_proxy_auth_credential
xks_proxy_connectivity = "VPC_ENDPOINT_SERVICE"
tags = {
Environment = "production"
KeyStore = "external"
Compliance = "strict"
}
}
# VPC endpoint service for external key store proxy
resource "aws_vpc_endpoint_service" "xks_proxy" {
acceptance_required = false
network_load_balancer_arns = [aws_lb.xks_proxy_nlb.arn]
tags = {
Name = "xks-proxy-endpoint-service"
}
}
# Network load balancer for XKS proxy
resource "aws_lb" "xks_proxy_nlb" {
name = "xks-proxy-nlb"
internal = true
load_balancer_type = "network"
subnets = [aws_subnet.private_a.id, aws_subnet.private_b.id]
enable_deletion_protection = true
tags = {
Name = "xks-proxy-nlb"
}
}
# Target group for XKS proxy servers
resource "aws_lb_target_group" "xks_proxy" {
name = "xks-proxy-tg"
port = 443
protocol = "TLS"
vpc_id = aws_vpc.main.id
health_check {
enabled = true
healthy_threshold = 2
interval = 30
matcher = "200"
path = "/health"
port = "traffic-port"
protocol = "HTTPS"
timeout = 5
unhealthy_threshold = 2
}
tags = {
Name = "xks-proxy-targets"
}
}
# KMS key using external key store
resource "aws_kms_key" "external_store_key" {
description = "KMS key using external key store"
custom_key_store_id = aws_kms_custom_key_store.external_store.id
key_usage = "ENCRYPT_DECRYPT"
key_spec = "SYMMETRIC_DEFAULT"
# External key ID from your HSM
xks_key_id = var.external_key_id
policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Sid = "Enable IAM User Permissions"
Effect = "Allow"
Principal = {
AWS = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:root"
}
Action = "kms:*"
Resource = "*"
},
{
Sid = "Allow external key store operations"
Effect = "Allow"
Principal = {
AWS = aws_iam_role.external_key_manager.arn
}
Action = [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey",
"kms:CreateGrant",
"kms:ListGrants",
"kms:RevokeGrant"
]
Resource = "*"
}
]
})
tags = {
Name = "external-store-key"
Environment = "production"
KeyStore = "external"
}
}
This configuration sets up an external key store that connects to your own key management infrastructure through a VPC endpoint service. The XKS proxy configuration enables secure communication between AWS KMS and your external HSM.
Parameter Explanations
CloudHSM Custom Key Store Parameters:
custom_key_store_name
: Human-readable name for the key storecloud_hsm_cluster_id
: ID of the CloudHSM cluster backing the key storetrust_anchor_certificate
: Certificate establishing trust with the HSM clusterkey_store_password
: Password for accessing the key store (stored securely in variables)
External Key Store Parameters:
custom_key_store_type
: Set to "EXTERNAL_KEY_STORE" for external configurationsxks_proxy_uri_endpoint
: Endpoint URL for your external key store proxyxks_proxy_uri_path
: URI path for XKS proxy API callsxks_proxy_vpc_endpoint_service_name
: VPC endpoint service for secure connectivityxks_proxy_authentication_credential
: Authentication credential for proxy accessxks_proxy_connectivity
: Connectivity type (VPC_ENDPOINT_SERVICE or PUBLIC_ENDPOINT)
Key Configuration Parameters:
xks_key_id
: Identifier for the key in your external HSMcustom_key_store_id
: Reference to the custom key store resourceenable_key_rotation
: Whether to enable automatic key rotation
Dependencies and Security Considerations
Custom key stores require careful orchestration of dependencies and security controls:
# IAM role for custom key store operations
resource "aws_iam_role" "custom_key_store_admin" {
name = "CustomKeyStoreAdminRole"
assume_role_policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Action = "sts:AssumeRole"
Effect = "Allow"
Principal = {
Service = "kms.amazonaws.com"
}
}
]
})
}
# Policy for custom key store administration
resource "aws_iam_role_policy" "custom_key_store_admin" {
name = "CustomKeyStoreAdminPolicy"
role = aws_iam_role.custom_key_store_admin.id
policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Action = [
"cloudhsm:DescribeClusters",
"cloudhsm:DescribeBackups",
"cloudhsm:ListTags"
]
Resource = "*"
},
{
Effect = "Allow"
Action = [
"kms:ConnectCustomKeyStore",
"kms:DisconnectCustomKeyStore",
"kms:DescribeCustomKeyStores"
]
Resource = "*"
}
]
})
}
# CloudWatch log group for custom key store monitoring
resource "aws_cloudwatch_log_group" "custom_key_store_logs" {
name = "/aws/kms/custom-key-store"
retention_in_days = 90
tags = {
Environment = "production"
Purpose = "custom-key-store-monitoring"
}
}
# CloudWatch alarms for custom key store health
resource "aws_cloudwatch_metric_alarm" "custom_key_store_connection" {
alarm_name = "custom-key-store-connection-failure"
comparison_operator = "GreaterThanThreshold"
evaluation_periods = "2"
metric_name = "CustomKeyStoreConnectionFailures"
namespace = "AWS/KMS"
period = "300"
statistic = "Sum"
threshold = "0"
alarm_description = "This metric monitors custom key store connection failures"
alarm_actions = [aws_sns_topic.kms_alerts.arn]
dimensions = {
CustomKeyStoreId = aws_kms_custom_key_store.cloudhsm_store.id
}
}
# SNS topic for KMS alerts
resource "aws_sns_topic" "kms_alerts" {
name = "kms-custom-key-store-alerts"
tags = {
Purpose = "kms-monitoring"
}
}
The dependencies ensure that the CloudHSM cluster is fully operational before creating the custom key store, and the monitoring configuration provides visibility into key store health and performance.
Best practices for KMS Custom Key Store
Managing KMS Custom Key Store requires careful consideration of security, compliance, and operational requirements. Here are the key best practices to follow when implementing and maintaining custom key stores.
Implement Proper CloudHSM Cluster Setup
Why it matters: A misconfigured CloudHSM cluster can lead to custom key store creation failures, service unavailability, or security vulnerabilities.
Implementation: Design your CloudHSM cluster with redundancy and high availability from the start. Deploy HSM instances across multiple Availability Zones within a region to ensure fault tolerance.
# Verify CloudHSM cluster readiness before creating custom key store
aws cloudhsmv2 describe-clusters --cluster-ids cluster-1234567890abcdef0
# Ensure all HSM instances are ACTIVE
aws cloudhsmv2 describe-clusters --cluster-ids cluster-1234567890abcdef0 \\
--query 'Clusters[0].Hsms[*].{HsmId:HsmId,State:State,SubnetId:SubnetId}'
Monitor cluster health continuously and maintain at least two HSM instances per cluster. This prevents single points of failure and ensures your custom key store remains available during HSM maintenance or unexpected failures. Configure automated backups of your HSM configuration and implement proper disaster recovery procedures.
Secure Network Configuration and Access Controls
Why it matters: Custom key stores require secure network connectivity to CloudHSM clusters, and improper network configuration can expose encryption keys to unauthorized access.
Implementation: Use dedicated VPC subnets for your CloudHSM cluster and implement strict security group rules that only allow necessary traffic.
resource "aws_security_group" "cloudhsm_sg" {
name_prefix = "cloudhsm-"
vpc_id = var.vpc_id
ingress {
from_port = 2223
to_port = 2225
protocol = "tcp"
cidr_blocks = [var.vpc_cidr]
}
egress {
from_port = 443
to_port = 443
protocol = "tcp"
cidr_blocks = ["0.0.0.0/0"]
}
tags = {
Name = "cloudhsm-security-group"
Environment = var.environment
}
}
Implement VPC endpoints for KMS to ensure that traffic between your applications and KMS remains within the AWS network. This reduces exposure to internet-based attacks and improves performance. Configure CloudTrail logging to monitor all API calls to your custom key store and CloudHSM cluster.
Establish Robust Key Management Lifecycle
Why it matters: Improper key lifecycle management can lead to data inaccessibility, compliance violations, and operational disruptions.
Implementation: Develop comprehensive procedures for key creation, rotation, backup, and deletion. Document the entire key lifecycle and ensure all team members understand their responsibilities.
# Create a custom key store with proper naming and description
aws kms create-custom-key-store \\
--custom-key-store-name "production-custom-key-store" \\
--cloud-hsm-cluster-id cluster-1234567890abcdef0 \\
--key-store-password MySecurePassword123! \\
--trust-anchor-certificate file://customerCA.crt
# Verify custom key store connection
aws kms describe-custom-key-stores \\
--custom-key-store-id cks-1234567890abcdef0 \\
--query 'CustomKeyStores[0].ConnectionState'
Implement automated key rotation schedules and maintain detailed records of all key operations. Establish clear procedures for key recovery and ensure that backup keys are stored securely in geographically separate locations. Regular testing of key recovery procedures is essential to ensure business continuity.
Implement Comprehensive Monitoring and Alerting
Why it matters: Custom key stores require continuous monitoring to detect connection issues, performance degradation, or security incidents before they impact business operations.
Implementation: Set up CloudWatch alarms for key metrics and configure automated responses to common issues.
# Create CloudWatch alarm for custom key store connection failures
aws cloudwatch put-metric-alarm \\
--alarm-name "CustomKeyStore-ConnectionFailure" \\
--alarm-description "Alert when custom key store connection fails" \\
--metric-name "NumberOfRequestsSucceeded" \\
--namespace "AWS/KMS" \\
--statistic "Sum" \\
--period 300 \\
--threshold 1 \\
--comparison-operator "LessThanThreshold" \\
--evaluation-periods 2 \\
--alarm-actions "arn:aws:sns:region:account:topic-name"
Monitor CloudHSM cluster health metrics including CPU utilization, memory usage, and network connectivity. Set up alerts for unusual patterns in key usage, failed authentication attempts, or configuration changes. Implement log aggregation to centralize monitoring data and enable rapid incident response.
Ensure Compliance and Audit Readiness
Why it matters: Many organizations use custom key stores to meet specific compliance requirements, and proper documentation and audit trails are essential for regulatory adherence.
Implementation: Maintain comprehensive documentation of your custom key store configuration, including security policies, access controls, and operational procedures.
resource "aws_kms_custom_key_store" "compliance_store" {
custom_key_store_name = "compliance-key-store"
cloud_hsm_cluster_id = aws_cloudhsmv2_cluster.main.cluster_id
key_store_password = var.key_store_password
trust_anchor_certificate = file("${path.module}/certificates/ca.crt")
tags = {
Compliance = "SOC2-Type2"
DataClass = "Confidential"
Owner = "SecurityTeam"
Environment = "Production"
BackupPolicy = "Daily"
}
}
Enable comprehensive logging for all key operations and regularly review audit logs. Implement proper tagging strategies to track key usage and ownership. Establish regular compliance assessments and maintain evidence of security controls. Document incident response procedures specific to custom key store operations.
Optimize Performance and Cost Management
Why it matters: Custom key stores can introduce latency and costs that need to be managed effectively to maintain system performance and budget control.
Implementation: Monitor key usage patterns and optimize the number of HSM instances based on actual demand. Implement caching strategies where appropriate to reduce the frequency of HSM operations.
# Monitor custom key store performance metrics
aws cloudwatch get-metric-statistics \\
--namespace "AWS/KMS" \\
--metric-name "NumberOfRequestsSucceeded" \\
--dimensions Name=CustomKeyStoreId,Value=cks-1234567890abcdef0 \\
--start-time 2023-01-01T00:00:00Z \\
--end-time 2023-01-02T00:00:00Z \\
--period 3600 \\
--statistics Sum
Regularly review CloudHSM cluster sizing and adjust the number of HSM instances based on performance requirements and cost optimization goals. Implement proper resource tagging to track costs associated with custom key stores. Consider using AWS Cost Explorer to analyze spending patterns and identify optimization opportunities.
Plan for Disaster Recovery and Business Continuity
Why it matters: Loss of access to custom key stores can render encrypted data inaccessible, causing significant business disruption.
Implementation: Develop and regularly test comprehensive disaster recovery procedures that include custom key store restoration and key material recovery.
Maintain current backups of all key material and ensure that backup procedures include both the CloudHSM cluster configuration and the custom key store settings. Document recovery time objectives (RTO) and recovery point objectives (RPO) for different failure scenarios. Establish clear escalation procedures and ensure that multiple team members are trained on recovery operations.
Implement cross-region backup strategies where compliance requirements allow, and maintain detailed runbooks for various failure scenarios. Regular disaster recovery testing should include full restoration procedures to validate the effectiveness of your backup and recovery strategies.
Enterprise Value and Strategic Impact
KMS Custom Key Store addresses critical security and compliance requirements for organizations that need maximum control over their encryption keys. According to industry reports, over 60% of enterprises require hardware-based key management to meet regulatory compliance standards, particularly in financial services, healthcare, and government sectors.
Enhanced Security Posture
Custom Key Stores provide an additional layer of security beyond standard KMS keys by ensuring your encryption keys never leave your dedicated HSM environment. This hardware-based approach meets the highest security standards, including FIPS 140-2 Level 3 certification requirements. Organizations can maintain complete ownership of their key material while leveraging AWS's cryptographic services.
Regulatory Compliance Benefits
For businesses operating under strict regulatory frameworks like SOX, HIPAA, or PCI DSS, Custom Key Stores help demonstrate compliance with key management requirements. The ability to generate and store keys within your own HSM provides auditable proof of key custody and control, often required for regulatory assessments.
Operational Excellence
Custom Key Stores integrate seamlessly with existing AWS services, allowing organizations to use familiar KMS APIs while maintaining enhanced key security. This reduces operational complexity compared to implementing entirely separate key management solutions.
Key Features and Capabilities
Hardware Security Module Integration
Custom Key Stores connect directly to AWS CloudHSM clusters, providing FIPS 140-2 Level 3 validated hardware security. This integration ensures cryptographic keys are generated, stored, and used within tamper-resistant hardware environments. The HSM clusters operate within your AWS VPC, maintaining network isolation and security.
Bring Your Own Key Material
Organizations can import their own key material or have keys generated within the HSM cluster. This capability supports existing key lifecycle processes and enables migration of encryption keys from on-premises environments to AWS while maintaining key ownership and control.
Multi-Region Support
Custom Key Stores can be configured to span multiple AWS regions, supporting disaster recovery and business continuity requirements. Cross-region key replication ensures encrypted data remains accessible even during regional outages or disasters.
Audit and Compliance Logging
All cryptographic operations performed with Custom Key Store keys are logged through AWS CloudTrail, providing comprehensive audit trails. This logging includes key usage, administrative actions, and access patterns, supporting forensic analysis and compliance reporting requirements.
Integration Ecosystem
AWS KMS Custom Key Store integrates with over 150+ AWS services that support encryption, providing enterprise-grade key management across your entire AWS infrastructure. Services like Amazon S3, Amazon EBS, Amazon RDS, and Amazon Redshift can all utilize Custom Key Store keys for encryption at rest.
Storage Services Integration:
Custom Key Stores work seamlessly with S3 buckets to provide server-side encryption using customer-managed keys stored in dedicated HSMs. This ensures that sensitive data stored in S3 is protected with keys that never leave your controlled environment.
Database Encryption:
Integration with RDS instances and DynamoDB tables enables transparent data encryption using Custom Key Store keys. Database administrators can implement encryption without application changes while maintaining strict key control requirements.
Compute and Container Security:EC2 instances and EKS clusters can leverage Custom Key Store keys for encrypting volumes, secrets, and application data. This extends hardware-based key security to compute workloads and containerized applications.
Pricing and Scale Considerations
Custom Key Store pricing follows a multi-component model based on the underlying CloudHSM infrastructure and KMS usage. CloudHSM clusters require a minimum of two HSM instances for high availability, with each instance costing approximately $1.45 per hour. Additionally, standard KMS API request charges apply for cryptographic operations.
Scale Characteristics
Custom Key Stores support thousands of customer managed keys (CMKs) within a single store, with each key capable of handling millions of cryptographic operations per second when properly distributed across HSM instances. The underlying CloudHSM cluster can scale horizontally by adding additional HSM instances to handle increased throughput requirements.
Enterprise Considerations
Large enterprises often require multiple Custom Key Stores across different regions and business units. Consider implementing a centralized key management strategy that accounts for cross-regional data protection requirements and disaster recovery scenarios. Organizations should also plan for HSM capacity management as cryptographic workloads grow.
Custom Key Stores require significantly higher investment compared to standard KMS keys but provide unmatched security and compliance benefits. For organizations with strict regulatory requirements or handling highly sensitive data, the additional cost is often justified by risk reduction and compliance advantages.
Managing KMS Custom Key Store using Terraform
Custom Key Store configuration requires careful coordination between CloudHSM cluster setup and KMS integration, making Infrastructure as Code approaches valuable for maintaining consistent deployments.
Basic Custom Key Store Setup
This configuration establishes a Custom Key Store connected to an existing CloudHSM cluster for secure key material storage.
# CloudHSM cluster for Custom Key Store
resource "aws_cloudhsm_v2_cluster" "kms_cluster" {
hsm_type = "hsm1.medium"
subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]
tags = {
Name = "kms-custom-key-store-cluster"
Environment = "production"
Compliance = "fips-140-2-level-3"
}
}
# Custom Key Store configuration
resource "aws_kms_custom_key_store" "enterprise_store" {
custom_key_store_name = "enterprise-key-store"
cloud_hsm_cluster_id = aws_cloudhsm_v2_cluster.kms_cluster.cluster_id
trust_anchor_certificate = file("${path.module}/certificates/trust-anchor.pem")
key_store_password = var.hsm_cluster_password
tags = {
Name = "enterprise-custom-key-store"
Environment = "production"
Purpose = "regulatory-compliance"
Team = "security-operations"
}
depends_on = [aws_cloudhsm_v2_hsm.cluster_hsms]
}
# Customer managed key in Custom Key Store
resource "aws_kms_key" "custom_store_key" {
description = "Enterprise encryption key in Custom Key Store"
custom_key_store_id = aws_kms_custom_key_store.enterprise_store.id
key_usage = "ENCRYPT_DECRYPT"
customer_master_key_spec = "SYMMETRIC_DEFAULT"
policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Sid = "Enable root account permissions"
Effect = "Allow"
Principal = {
AWS = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:root"
}
Action = "kms:*"
Resource = "*"
}
]
})
tags = {
Name = "enterprise-encryption-key"
Environment = "production"
KeyStore = "custom"
}
}
This configuration creates a Custom Key Store backed by a CloudHSM cluster with a customer managed key. The cloud_hsm_cluster_id
links the Custom Key Store to the HSM cluster, while trust_anchor_certificate
establishes the trust relationship. The depends_on
ensures proper sequencing of resource creation.
Multi-Region Custom Key Store with Cross-Region Replication
This advanced configuration implements a Custom Key Store with cross-region support for disaster recovery and compliance requirements.
# Primary region Custom Key Store
resource "aws_kms_custom_key_store" "primary_store" {
custom_key_store_name = "primary-enterprise-store"
cloud_hsm_cluster_id = aws_cloudhsm_v2_cluster.primary_cluster.cluster_id
trust_anchor_certificate = file("${path.module}/certificates/primary-trust-anchor.pem")
key_store_password = var.primary_hsm_password
tags = {
Name = "primary-custom-key-store"
Environment = "production"
Region = "primary"
DR = "source"
}
}
# Replica Custom Key Store in DR region
resource "aws_kms_custom_key_store" "replica_store" {
provider = aws.dr_region
custom_key_store_name = "replica-enterprise-store"
cloud_hsm_cluster_id = aws_cloudhsm_v2_cluster.replica_cluster.cluster_id
trust_anchor_certificate = file("${path.module}/certificates/replica-trust-anchor.pem")
key_store_password = var.replica_hsm_password
tags = {
Name = "replica-custom-key-store"
Environment = "production"
Region = "dr"
DR = "target"
}
}
# Multi-region key with automatic failover
resource "aws_kms_replica_key" "cross_region_key" {
provider = aws.dr_region
description = "Cross-region replica for Custom Key Store key"
primary_key_arn = aws_kms_key.primary_custom_key.arn
deletion_window_in_days = 7
tags = {
Name = "cross-region-replica-key"
Environment = "production"
Purpose = "disaster-recovery"
}
}
This setup creates Custom Key Stores in multiple regions with replica keys for disaster recovery. The provider
meta-argument ensures resources are created in different regions, while replica keys maintain cross-region encryption capabilities. Each Custom Key Store maintains its own HSM cluster and trust relationship.
Best practices for KMS Custom Key Store
Implementing Custom Key Store requires careful attention to security, compliance, and operational procedures to maximize the benefits of hardware-based key management.
Implement Comprehensive HSM Cluster High Availability
Why it matters: Custom Key Stores depend on underlying CloudHSM clusters for key operations. HSM failures can render encrypted data inaccessible, making high availability critical for business continuity.
Implementation: Deploy HSM instances across multiple Availability Zones with automated backup and recovery procedures.
# Check HSM cluster health and capacity
aws cloudhsmv2 describe-clusters \\
--filters clusterIds=cluster-abc123def456 \\
--query 'Clusters[0].{State:State,HsmCount:Hsms[].HsmId}'
# Monitor HSM utilization
aws logs filter-log-events \\
--log-group-name /aws/cloudhsm/cluster-abc123def456 \\
--filter-pattern "[timestamp, request_id, ERROR]"
Configure CloudWatch alarms for HSM instance failures and implement automated recovery procedures. Maintain at least three HSM instances in production environments to handle instance failures and maintenance windows without service disruption.
Establish Robust Key Lifecycle Management
Why it matters: Custom Key Store keys require careful lifecycle management including rotation, backup, and recovery procedures. Poor key management can lead to data loss or compliance violations.
Implementation: Implement automated key rotation and comprehensive backup strategies for key material and HSM cluster configurations.
# Automated key rotation for Custom Key Store keys
resource "aws_kms_key" "custom_store_key_with_rotation" {
custom_key_store_id = aws_kms_custom_key_store.enterprise_store.id
description = "Auto-rotating Custom Key Store key"
enable_key_rotation = true
rotation_period_in_days = 365
multi_region = false
tags = {
Name = "auto-rotating-custom-key"
RotationPolicy = "annual"
BackupRequired = "true"
}
}
Develop procedures for key material export and import to support disaster recovery scenarios. Document key usage patterns and implement monitoring for unauthorized key access attempts.
Configure Comprehensive Audit and Monitoring
Why it matters: Custom Key Stores handle sensitive encryption operations that must be auditable for compliance and security purposes. Lack of proper monitoring can prevent detection of security incidents.
Implementation: Enable comprehensive logging and establish monitoring for all Custom Key Store operations.
# Query Custom Key Store operations in CloudTrail
aws logs start-query \\
--log-group-name CloudTrail/KMSEvents \\
--start-time 1625097600 \\
--end-time 1625184000 \\
--query-string 'fields @timestamp, eventName, sourceIPAddress, errorMessage | filter eventSource = "kms.amazonaws.com" and resources.0.type = "AWS::KMS::CustomKeyStore"'
# Monitor Custom Key Store connection status
aws kms describe-custom-key-stores \\
--custom-key-store-id cks-abc123def456 \\
--query 'CustomKeyStores[0].ConnectionState'
Set up alerts for Custom Key Store disconnections, failed cryptographic operations, and unusual access patterns. Implement regular security assessments and compliance audits of key usage and access controls.
Terraform and Overmind for KMS Custom Key Store
Overmind Integration
KMS Custom Key Store is used in enterprise environments where encryption key security is paramount. Managing changes to Custom Key Stores requires understanding dependencies across HSM clusters, customer managed keys, and encrypted resources throughout your AWS environment.
When you run overmind terraform plan
with Custom Key Store modifications, Overmind automatically identifies all resources that depend on your Custom Key Store infrastructure, including:
- CloudHSM Clusters that provide the underlying hardware security module infrastructure for key storage
- Customer Managed Keys created within the Custom Key Store for specific encryption operations
- Encrypted Resources across multiple AWS services that use Custom Key Store keys for data protection
- IAM Roles and Policies that control access to Custom Key Store operations and key usage
This dependency mapping extends beyond direct relationships to include indirect dependencies that might not be immediately obvious, such as applications using encrypted EBS volumes or databases with transparent data encryption relying on Custom Key Store keys.
Risk Assessment
Overmind's risk analysis for Custom Key Store changes focuses on several critical areas:
High-Risk Scenarios:
- Custom Key Store Disconnection: Disconnecting a Custom Key Store renders all associated keys temporarily unavailable, potentially causing widespread service disruptions across encrypted resources
- HSM Cluster Modifications: Changes to the underlying CloudHSM cluster configuration can affect Custom Key Store connectivity and key availability
- Trust Anchor Certificate Updates: Modifying trust relationships can break Custom Key Store connectivity until properly configured
Medium-Risk Scenarios:
- Key Policy Modifications: Changes to key policies for Custom Key Store keys can inadvertently remove access for critical applications or services
- Custom Key Store Settings Updates: Modifying Custom Key Store properties may require temporary disconnection and reconnection cycles
Low-Risk Scenarios:
- Tag Updates: Modifying tags on Custom Key Store resources typically has no functional impact on key operations
- Description Changes: Updates to Custom Key Store descriptions are metadata-only changes with minimal operational risk
Use Cases
Financial Services Regulatory Compliance
Large financial institutions use Custom Key Stores to meet strict regulatory requirements for encryption key management in payment processing and customer data protection systems. The hardware-based key storage provides auditable proof of key custody required for SOX compliance and PCI DSS certification. Banks often implement multiple Custom Key Stores across different business units to maintain separation of duties and support regulatory examination requirements.
Healthcare Data Protection with HIPAA Compliance
Healthcare organizations leverage Custom Key Stores to encrypt electronic health records (EHR) and medical imaging data while maintaining complete control over encryption keys. The FIPS 140-2 Level 3 certification of CloudHSM meets HIPAA technical safeguards requirements for protecting patient health information. Custom Key Stores enable healthcare providers to demonstrate reasonable and appropriate security measures as required by HIPAA regulations.
Government and Defense Sensitive Data Handling
Government agencies and defense contractors use Custom Key Stores to protect classified and sensitive data according to NIST and FIPS standards. The hardware-based key management supports requirements for controlled unclassified information (CUI) and sensitive compartmented information (SCI) handling. Custom Key Stores provide the cryptographic key isolation necessary for multi-level security environments and cross-domain solutions.
Limitations
CloudHSM Dependency and Complexity
Custom Key Stores require underlying CloudHSM clusters, which add significant complexity and cost compared to standard KMS keys. Organizations must manage HSM cluster lifecycle, capacity planning, and high availability configurations. The minimum requirement of two HSM instances for production deployments creates substantial baseline costs that may not be justified for smaller workloads.
Regional and Cross-Account Constraints
Custom Key Stores are region-specific resources that cannot be directly shared across regions or AWS accounts. Implementing cross-region or multi-account encryption strategies requires careful