A terraform aws kms key is a declarative configuration that creates and manages an AWS Key Management Service (KMS) key using HashiCorp Terraform. It enables automated, version-controlled encryption key provisioning within AWS infrastructure.
Terraform AWS KMS key resources define cryptographic keys used to encrypt and decrypt data at rest in AWS services such as Amazon S3, EBS volumes, and RDS databases. The key is provisioned through a Terraform configuration file, which describes the desired state rather than executing imperative commands.
When applied, Terraform provisions the KMS key in the specified AWS region and account. This key can then be referenced by other resources-such as encrypted EBS volumes or S3 buckets-to enforce data protection policies. The entire lifecycle is managed via Terraform's plan/apply mechanism.
Terraform AWS KMS key uses the AWS provider plugin to interact with the AWS API. When you run terraform apply, Terraform sends a request to AWS to create a KMS key based on the parameters defined in your configuration.
The key is created with attributes such as key specification (symmetric or asymmetric), key usage (encrypt/decrypt, sign/verify), and key policy. The key policy defines who can use the key and under what conditions. These policies are written in JSON format and embedded directly in the Terraform configuration.
After creation, the KMS key remains in AWS until explicitly deleted via Terraform. Deletion requires setting deletion_window_in_days to a value between 7 and 30 days. During this window, the key can be restored, preventing accidental data loss.
Each aws_kms_key resource includes essential parameters:
description: A human-readable label for the key.key_usage: Specifies whether the key is used for encryption/decryption or signing/verifying.origin: Determines the source of the key material. Set to aws:kms for AWS-generated keys or external for imported keys.policy: A JSON string defining access permissions for users, roles, and services.tags: Metadata for cost allocation and organizational tagging.For example, a basic KMS key configuration might look like this:
resource "aws_kms_key" "encrypted_data" {
description = "Key for encrypting application secrets"
key_usage = "ENCRYPT_DECRYPT"
origin = "aws:kms"
enable_key_rotation = true
tags = {
Environment = "production"
Owner = "devops"
}
}This configuration creates a symmetric key in the default AWS region, enables automatic rotation every year, and applies standard cost-tracking tags.
There are two primary types of KMS keys based on their purpose and configuration:
| Type | Use Case | Configuration Note |
|---|---|---|
| Symmetric Key | Data encryption at rest (e.g., S3, EBS) | Uses key_usage = "ENCRYPT_DECRYPT"; faster and simpler |
| Asymmetric Key | Digital signatures, key exchange, TLS certificates | Uses key_usage = "SIGN_VERIFY"; supports RSA or ECC algorithms |
Another common setup involves cross-account key sharing. A central security team can create a KMS key in a dedicated account and grant permission to other accounts via the key policy. This centralizes control while allowing distributed teams to use the same key for consistent encryption standards.
Many users assume that creating a KMS key automatically grants access to it. This is false. Without proper key policy or IAM role assignments, even the root user cannot use the key. The key policy must explicitly allow actions like kms:Encrypt, kms:Decrypt, and kms:DescribeKey.
Another mistake is omitting key rotation. While AWS KMS supports automatic key rotation for customer-managed keys, it must be enabled manually. Disabling rotation increases risk if the key is compromised. According to AWS documentation, "rotating keys reduces the impact of long-term exposure."
A less obvious issue is key policy complexity. Overly permissive policies-like granting Allow to Principal: *-can expose data to unauthorized access. Always follow the principle of least privilege. For example, restrict access to specific IAM roles or service principals.
Consider a web application running on EC2 instances with a PostgreSQL database. Backups are stored in an S3 bucket. To protect backup data, a KMS key is created specifically for encryption.
Here's a complete configuration:
resource "aws_kms_key" "db_backup_encryption" {
description = "Encrypts database backups stored in S3"
key_usage = "ENCRYPT_DECRYPT"
enable_key_rotation = true
deletion_window_in_days = 30
policy = jsonencode({
Version = "2012-10-17"
Statement = [{
Effect = "Allow"
Principal = {
Service = "s3.amazonaws.com"
}
Action = [
"kms:Encrypt",
"kms:Decrypt",
"kms:GenerateDataKey"
]
Resource = "*"
}]
})
tags = {
Project = "web-app"
Tier = "backup"
}
}
resource "aws_s3_bucket" "backups" {
bucket = "app-backups-prod"
acl = "private"
server_side_encryption_configuration {
rule {
apply_server_side_encryption_by_default {
sse_algorithm = "aws:kms"
kms_master_key_id = aws_kms_key.db_backup_encryption.key_id
}
}
}
}This setup helps all objects uploaded to the S3 bucket are encrypted using the KMS key. The key policy allows S3 to use the key for encryption and decryption, but no other service or user can access it unless explicitly granted.
When the team runs terraform apply, Terraform creates the KMS key and configures the S3 bucket to use it. The key is rotated annually, and deletion is delayed by 30 days-providing both security and operational safety.
According to AWS's official documentation, "KMS keys are designed to be highly available and durable," but they are not inherently secure. Security depends on correct configuration and access control.
The National Institute of Standards and Technology (NIST) SP 800-57 Part 1 Revision 5 recommends rotating cryptographic keys regularly. For KMS keys, AWS provides automatic rotation for customer-created keys, but it must be enabled explicitly.
Always store the KMS key ID and ARN in a Terraform output variable for reference. Avoid hardcoding key IDs in other configurations. Use data "aws_kms_key" "lookup" to retrieve existing keys when needed.
Finally, test your configuration in a staging environment before applying it to production. Use terraform plan to preview changes and validate that the key policy and access settings match expectations.
Using terraform aws kms key correctly helps encryption is not an afterthought but a core part of infrastructure design. It enables compliance with regulations like HIPAA, GDPR, and PCI-DSS by providing auditable, reproducible encryption setups.