AWS Key Management Service (KMS) serves as the foundational layer for cryptographic operations within the Amazon Web Services ecosystem. It is a managed service designed for creating, controlling, and utilizing encryption keys. In modern cloud infrastructure, the transition from manual key management to Infrastructure as Code (IaC) is not merely a convenience but a critical requirement for security, auditability, and consistency. Terraform has emerged as the standard tool for this transition, allowing engineers to define the lifecycle of KMS keys, aliases, and policies with declarative precision. This guide explores the technical depth required to implement, secure, and update KMS resources using Terraform, addressing both the standard provisioning workflows and the complex edge cases involving policy modifications and multi-region replication.
Prerequisites and Project Structure
Before implementing KMS resources via Terraform, specific environmental conditions must be met. The operational environment requires a configured AWS Command Line Interface (AWS CLI) with appropriate permissions to create and manage cryptographic material. Additionally, Terraform must be installed and initialized with the AWS provider. A fundamental understanding of encryption concepts is necessary, particularly regarding symmetric versus asymmetric keys, key rotation, and the distinction between key policies and identity-based policies.
A robust project structure separates concerns between variable definitions, resource declarations, and output values. A standard directory layout facilitates maintainability and collaboration. The structure typically includes the following files:
main.tf: Contains the primary resource definitions, including the AWS provider block and the core KMS resources.variables.tf: Defines input variables such as region, project name, and environment tags.outputs.tf: Exports the attributes of the created resources for consumption by other modules.terraform.tfvars: Stores the specific values for the variables, ensuring secrets or environment-specific data are not hardcoded in the source files.
Basic KMS Configuration and Provisioning
The core of any KMS Terraform implementation is the aws_kms_key resource. This resource allows for the creation of symmetric and asymmetric customer-managed keys. When provisioning a basic symmetric key, several attributes control the key's behavior and security posture.
The following code block demonstrates a standard configuration for a primary KMS key. It establishes the provider, defines the key with a description, sets a deletion window, enables automatic rotation, and applies an inline key policy.
```hcl
main.tf
provider "aws" {
region = var.aws_region
}
KMS Key
resource "awskmskey" "main" {
description = "KMS key for ${var.projectname}"
deletionwindowindays = 7
enablekeyrotation = true
policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Sid = "Enable IAM User Permissions"
Effect = "Allow"
Principal = {
AWS = "arn:aws:iam::${data.awscalleridentity.current.account_id}:root"
}
Action = "kms:"
Resource = ""
}
]
})
tags = {
Environment = var.environment
}
}
KMS Alias
resource "awskmsalias" "main" {
name = "alias/${var.projectname}"
targetkeyid = awskmskey.main.keyid
}
Data source for current account
data "awscalleridentity" "current" {}
```
In this configuration, the deletion_window_in_days attribute is critical. It specifies the number of days after which the key is permanently deleted if a deletion request is initiated. The default is 30 days, but this can be adjusted. The enable_key_rotation attribute, when set to true, enables automatic annual rotation of the key material.
The aws_kms_alias resource creates a friendly name for the key. Using an alias is recommended over hardcoding the key ID because aliases remain stable even when the key material is rotated or the key is deleted and re-created. The target_key_id references the unique identifier of the key resource.
The key policy embedded in the jsonencode function follows the AWS Identity and Access Management (IAM) policy language. The statement with Sid "Enable IAM User Permissions" grants the root account permission to use KMS API operations (kms:*) on the key resource. This is a common starting point that allows the account administrator to manage the key and use Identity and Access Management (IAM) policies to control access for specific users and roles within the account.
Multi-Region Key Configuration
For applications that require high availability and disaster recovery across multiple AWS Regions, multi-region keys provide a mechanism to replicate key metadata to a secondary region. This eliminates the need to manually manage separate keys in each region and ensures that keys are available in the recovery region even if the primary region becomes unavailable.
Configuring multi-region keys in Terraform requires defining a primary key and a secondary key, with the secondary key referencing the primary key's Amazon Resource Name (ARN).
```hcl
Primary Region Key
resource "awskmskey" "primary" {
description = "Multi-region primary key for ${var.projectname}"
deletionwindowindays = 7
enablekeyrotation = true
multi_region = true
tags = {
Environment = var.environment
}
}
Secondary Region Key
resource "awskmskey" "secondary" {
provider = aws.secondaryregion
description = "Multi-region replica key for ${var.projectname}"
deletionwindowindays = 7
multiregion = true
primarykeyarn = awskmskey.primary.arn
}
```
In this example, the multi_region attribute is set to true for both the primary and secondary keys. The primary_key_arn argument in the secondary key definition points to the ARN of the primary key. It is essential to note that while key metadata is replicated, the key material itself is not automatically replicated in the traditional sense of data replication; rather, the ability to use the key in the secondary region is established through the link. Users must handle key rotation manually for multi-region keys if automatic rotation is not enabled, or ensure that the rotation policy is correctly configured to propagate.
Updating Existing KMS Key Policies
One of the most challenging aspects of managing KMS keys with Terraform is updating an existing key policy, particularly when the key was not created by Terraform or when the policy needs to be modified without replacing the key. Terraform does not directly support updating an existing KMS key policy through its standard resources in a seamless manner for imported keys. However, there are effective approaches to achieve this.
Approach 1: Data Sources and Local Variables
The first method involves using data sources to fetch the existing key and its current policy, modifying the policy in a local variable, and then applying the new policy using the aws_kms_key_policy resource.
```hcl
Data source to get information about the existing key
data "awskmskey" "existingkey" {
keyid = "your-key-id-or-arn"
}
Data source to fetch the current policy
data "awskmskeypolicy" "existingpolicy" {
keyid = data.awskmskey.existingkey.id
}
Local variable to modify the policy
locals {
updatedpolicy = jsonencode({
Version = "2012-10-17"
Statement = concat(
jsondecode(data.awskmskeypolicy.existing_policy.policy).Statement,
[
{
Sid = "NewStatement"
Effect = "Allow"
Principal = {
AWS = "arn:aws:iam::123456789012:user/NewUser"
}
Action = ["kms:Encrypt", "kms:Decrypt"]
Resource = "*"
}
]
)
})
}
Apply the updated policy
resource "awskmskeypolicy" "updatedpolicy" {
keyid = data.awskmskey.existingkey.id
policy = local.updated_policy
}
```
This approach leverages the aws_kms_key_policy resource, which allows for the management of the policy attached to a specific key. By using jsondecode and jsonencode, the existing policy statements are preserved, and new statements are appended. This is particularly useful for adding new principals or actions without disrupting existing permissions.
Approach 2: Importing the Key and Using the Resource Argument
If more control is needed or the previous method does not fit the use case, the aws_kms_key resource can be used with the policy argument. This requires importing the existing key into the Terraform state.
hcl
resource "aws_kms_key" "existing_key" {
description = "Existing KMS key"
policy = jsonencode({
Version = "2012-10-17"
Statement = [
# Your existing policy statements here
{
Sid = "NewStatement"
Effect = "Allow"
Principal = {
AWS = "arn:aws:iam::123456789012:user/NewUser"
}
Action = ["kms:Encrypt", "kms:Decrypt"]
Resource = "*"
}
]
})
}
After defining the resource in the Terraform configuration, the key must be imported using the Terraform CLI:
bash
terraform import aws_kms_key.existing_key your-key-id-or-arn
Once imported, subsequent terraform apply commands will manage the key and its policy according to the defined configuration. This method is powerful but requires careful handling of the state to avoid unintended changes to other key attributes.
Approach 3: Using null_resource for AWS CLI Commands
As a last resort, a null_resource with local-exec can be used to run AWS CLI commands to update the policy. This approach is less idiomatic for Terraform but provides ultimate flexibility when dealing with complex policy logic that is difficult to express in HCL.
Restricting Default Access via Key Policy
Security best practices dictate that default access to KMS keys should be restricted. The default KMS key policy often contains a statement that allows the root account to use all KMS operations. While this is convenient for initial setup, it poses a security risk if the root account credentials are compromised.
The default policy statement is as follows:
json
{
"Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:root"
},
"Action": "kms:*",
"Resource": "*"
}
This statement allows the caller's account to use IAM policies to control key access. However, the Effect and Principal elements do not refer to the AWS root user account specifically in a granular way; they refer to the root account, which implies broad permissions. To restrict this, the key policy should be modified to explicitly grant permissions to specific IAM roles or users, rather than the root account.
For example, if there are existing IAM roles named TERRAFORM, ADMIN, and ANALYST, the key policy can be updated to grant specific permissions to these roles instead of the root account. This approach enhances security by ensuring that only authorized identities have access to the key.
Common Mistakes and Pitfalls
Managing KMS keys with Terraform involves several potential pitfalls that can lead to security breaches or operational disruptions. Understanding these mistakes is crucial for robust implementation.
- Locking Yourself Out: If the root account access is removed from the key policy and no remaining principal can update the policy, the key becomes unmanageable. The only way to recover in this scenario is to contact AWS support. Therefore, it is essential to maintain a principal with sufficient permissions to modify the key policy.
- Forgetting Grants: Some AWS services, such as Elastic Block Store (EBS) and Relational Database Service (RDS), use grants instead of direct key policies. Ensure that the roles interacting with these services have the
kms:CreateGrantpermission. Failing to do so can result in access denials when attempting to use the key through these services. - Deleting Keys Too Quickly: The minimum deletion window is 7 days. For production keys, it is recommended to use the maximum of 30 days. Additionally, it is best practice to disable the key first and wait for a period before scheduling deletion. This allows for a grace period during which any dependent services can be identified and updated.
Using Terraform Modules for KMS
For complex environments, using a pre-built Terraform module can simplify the management of KMS resources. The terraform-aws-modules/kms module provides a structured way to create KMS keys with various configurations.
Reference usage for EC2 AutoScaling service linked role to launch encrypted EBS volumes:
```hcl
module "kms" {
source = "terraform-aws-modules/kms/aws"
description = "EC2 AutoScaling key usage"
keyusage = "ENCRYPTDECRYPT"
# Policy
keyadministrators = ["arn:aws:iam::012345678901:role/admin"]
keyservicerolesfor_autoscaling = ["arn:aws:iam::012345678901:role/aws-service-role/autoscaling.amazonaws.com/AWSServiceRoleForAutoScaling"]
# Aliases
aliases = ["mycompany/ebs"]
tags = {
Terraform = "true"
Environment = "dev"
}
}
```
Reference usage for external CMK (externally provided encryption material):
```hcl
module "kms" {
source = "terraform-aws-modules/kms/aws"
description = "External key example"
keymaterialbase64 = "Wblj06fduthWggmsT0cLVoIMOkeLbc2kVfMud77i/JY="
valid_to = "2085-04-12T23:20:50.52Z"
# Policy
keyowners = ["arn:aws:iam::012345678901:role/owner"]
keyadministrators = ["arn:aws:iam::012345678901:role/admin"]
keyusers = ["arn:aws:iam::012345678901:role/user"]
keyservice_users = ["arn:aws:iam::012345678901:role/ec2-role"]
# Aliases
aliases = ["mycompany/external"]
aliasesusename_prefix = true
# Grants
grants = {
lambda = {
granteeprincipal = "arn:aws:iam::012345678901:role/lambda-function"
operations = ["Encrypt", "Decrypt", "GenerateDataKey"]
constraints = {
encryptioncontext_equals = {
Department = "Finance"
}
}
}
}
tags = {
Terraform = "true"
Environment = "dev"
}
}
```
This module allows for granular control over key usage, aliases, and grants. The grants block defines specific permissions for principals, such as Lambda functions, with constraints based on encryption context. This level of detail is crucial for securing workloads that rely on conditional access.
Outputs and Integration
To facilitate integration with other Terraform configurations, it is essential to export key information as outputs. This allows other modules to reference the KMS key ID, ARN, or alias ARN.
```hcl
output "kmskeyid" {
description = "The KMS key ID"
value = awskmskey.main.key_id
}
output "kmskeyarn" {
description = "The KMS key ARN"
value = awskmskey.main.arn
}
output "kmsaliasarn" {
description = "The KMS alias ARN"
value = awskmsalias.main.arn
}
```
These outputs can be consumed by other Terraform modules, ensuring that encryption is consistently applied across different services. For example, an S3 bucket module can use the kms_key_id output to enable server-side encryption with customer-managed keys (SSE-KMS).
Conclusion
KMS keys are the backbone of encryption on AWS. Customer-managed keys give organizations control over who can access their encrypted data, provide audit trails through CloudTrail, and enable automatic key rotation. Creating separate keys for different services enhances security isolation and simplifies key management. It is imperative to always include root account access in key policies to prevent lockout scenarios, while simultaneously restricting access to specific IAM roles where possible. Never set the deletion window below 30 days for production keys to allow for ample recovery time. Encryption is only as strong as your key management practices, and Terraform makes these practices auditable, repeatable, and scalable. By leveraging data sources, modules, and careful policy design, engineers can build a robust cryptographic infrastructure that meets the highest security standards.