AWS KMS Terraform module

Terraform module which creates AWS KMS resources.

Usage

See examples directory for working examples to reference:

Autoscaling Service Linked Role

Reference usage for EC2 AutoScaling service linked role to launch encrypted EBS volumes:

module "kms" {
  source = "terraform-aws-modules/kms/aws"

  description = "EC2 AutoScaling key usage"
  key_usage   = "ENCRYPT_DECRYPT"

  # Policy
  key_administrators                 = ["arn:aws:iam::012345678901:role/admin"]
  key_service_roles_for_autoscaling  = ["arn:aws:iam::012345678901:role/aws-service-role/autoscaling.amazonaws.com/AWSServiceRoleForAutoScaling"]

  # Aliases
  aliases = ["mycompany/ebs"]

  tags = {
    Terraform   = "true"
    Environment = "dev"
  }
}

External Key

Reference usage for external CMK (externally provided encryption material):

module "kms" {
  source = "terraform-aws-modules/kms/aws"

  description         = "External key example"
  key_material_base64 = "Wblj06fduthWggmsT0cLVoIMOkeLbc2kVfMud77i/JY="
  valid_to            = "2085-04-12T23:20:50.52Z"

  # Policy
  key_owners         = ["arn:aws:iam::012345678901:role/owner"]
  key_administrators = ["arn:aws:iam::012345678901:role/admin"]
  key_users          = ["arn:aws:iam::012345678901:role/user"]
  key_service_users  = ["arn:aws:iam::012345678901:role/ec2-role"]

  # Aliases
  aliases                 = ["mycompany/external"]
  aliases_use_name_prefix = true

  # Grants
  grants = {
    lambda = {
      grantee_principal = "arn:aws:iam::012345678901:role/lambda-function"
      operations        = ["Encrypt", "Decrypt", "GenerateDataKey"]
      constraints = {
        encryption_context_equals = {
          Department = "Finance"
        }
      }
    }
  }

  tags = {
    Terraform   = "true"
    Environment = "dev"
  }
}

Reference

Reference usage showing available configurations.

module "kms" {
  source = "terraform-aws-modules/kms/aws"

  description             = "Complete key example showing various configurations available"
  deletion_window_in_days = 7
  enable_key_rotation     = true
  is_enabled              = true
  key_usage               = "ENCRYPT_DECRYPT"
  multi_region            = false

  # Policy
  enable_default_policy                  = true
  key_owners                             = ["arn:aws:iam::012345678901:role/owner"]
  key_administrators                     = ["arn:aws:iam::012345678901:role/admin"]
  key_users                              = ["arn:aws:iam::012345678901:role/user"]
  key_service_users                      = ["arn:aws:iam::012345678901:role/ec2-role"]
  key_symmetric_encryption_users         = ["arn:aws:iam::012345678901:role/symmetric-user"]
  key_hmac_users                         = ["arn:aws:iam::012345678901:role/hmac-user"]
  key_asymmetric_public_encryption_users = ["arn:aws:iam::012345678901:role/asymmetric-public-user"]
  key_asymmetric_sign_verify_users       = ["arn:aws:iam::012345678901:role/sign-verify-user"]

  # Aliases
  aliases = ["one", "foo/bar"] # accepts static strings only
  computed_aliases = {
    ex = {
      # Sometimes you want to pass in an upstream attribute as the name and
      # that conflicts with using `for_each over a `toset()` since the value is not
      # known until after applying. Instead, we can use `computed_aliases` to work
      # around this limitation
      # Reference: https://github.com/hashicorp/terraform/issues/30937
      name = aws_iam_role.lambda.name
    }
  }
  aliases_use_name_prefix = true

  # Grants
  grants = {
    lambda = {
      grantee_principal = "arn:aws:iam::012345678901:role/lambda-function"
      operations        = ["Encrypt", "Decrypt", "GenerateDataKey"]
      constraints = {
        encryption_context_equals = {
          Department = "Finance"
        }
      }
    }
  }

  tags = {
    Terraform   = "true"
    Environment = "dev"
  }
}

Examples

Examples codified under the examples are intended to give users references for how to use the module(s) as well as testing/validating changes to the source code of the module. If contributing to the project, please be sure to make any appropriate updates to the relevant examples to allow maintainers to test your changes and to keep the examples up to date for users. Thank you!

• Complete

Requirements

Name	Version
terraform	>= 1.3
aws	>= 5.49

Providers

Name	Version
aws	>= 5.49

Modules

No modules.

Resources

Name	Type
aws_kms_alias.this	resource
aws_kms_external_key.this	resource
aws_kms_grant.this	resource
aws_kms_key.this	resource
aws_kms_replica_external_key.this	resource
aws_kms_replica_key.this	resource
aws_caller_identity.current	data source
aws_iam_policy_document.this	data source
aws_partition.current	data source

Inputs

Name	Description	Type	Default	Required
aliases	A list of aliases to create. Note - due to the use of toset(), values must be static strings and not computed values	list(string)	[]	no
aliases_use_name_prefix	Determines whether the alias name is used as a prefix	bool	false	no
bypass_policy_lockout_safety_check	A flag to indicate whether to bypass the key policy lockout safety check. Setting this value to true increases the risk that the KMS key becomes unmanageable	bool	null	no
computed_aliases	A map of aliases to create. Values provided via the name key of the map can be computed from upstream resources	any	{}	no
create	Determines whether resources will be created (affects all resources)	bool	true	no
create_external	Determines whether an external CMK (externally provided material) will be created or a standard CMK (AWS provided material)	bool	false	no
create_replica	Determines whether a replica standard CMK will be created (AWS provided material)	bool	false	no
create_replica_external	Determines whether a replica external CMK will be created (externally provided material)	bool	false	no
custom_key_store_id	ID of the KMS Custom Key Store where the key will be stored instead of KMS (eg CloudHSM).	string	null	no
customer_master_key_spec	Specifies whether the key contains a symmetric key or an asymmetric key pair and the encryption algorithms or signing algorithms that the key supports. Valid values: SYMMETRIC_DEFAULT, RSA_2048, RSA_3072, RSA_4096, HMAC_256, ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521, or ECC_SECG_P256K1. Defaults to SYMMETRIC_DEFAULT	string	null	no
deletion_window_in_days	The waiting period, specified in number of days. After the waiting period ends, AWS KMS deletes the KMS key. If you specify a value, it must be between 7 and 30, inclusive. If you do not specify a value, it defaults to 30	number	null	no
description	The description of the key as viewed in AWS console	string	null	no
enable_default_policy	Specifies whether to enable the default key policy. Defaults to true	bool	true	no
enable_key_rotation	Specifies whether key rotation is enabled. Defaults to true	bool	true	no
enable_route53_dnssec	Determines whether the KMS policy used for Route53 DNSSEC signing is enabled	bool	false	no
grants	A map of grant definitions to create	any	{}	no
is_enabled	Specifies whether the key is enabled. Defaults to true	bool	null	no
key_administrators	A list of IAM ARNs for key administrators	list(string)	[]	no
key_asymmetric_public_encryption_users	A list of IAM ARNs for key asymmetric public encryption users	list(string)	[]	no
key_asymmetric_sign_verify_users	A list of IAM ARNs for key asymmetric sign and verify users	list(string)	[]	no
key_hmac_users	A list of IAM ARNs for key HMAC users	list(string)	[]	no
key_material_base64	Base64 encoded 256-bit symmetric encryption key material to import. The CMK is permanently associated with this key material. External key only	string	null	no
key_owners	A list of IAM ARNs for those who will have full key permissions (kms:*)	list(string)	[]	no
key_service_roles_for_autoscaling	A list of IAM ARNs for AWSServiceRoleForAutoScaling roles	list(string)	[]	no
key_service_users	A list of IAM ARNs for key service users	list(string)	[]	no
key_statements	A map of IAM policy statements for custom permission usage	any	{}	no
key_symmetric_encryption_users	A list of IAM ARNs for key symmetric encryption users	list(string)	[]	no
key_usage	Specifies the intended use of the key. Valid values: ENCRYPT_DECRYPT or SIGN_VERIFY. Defaults to ENCRYPT_DECRYPT	string	null	no
key_users	A list of IAM ARNs for key users	list(string)	[]	no
multi_region	Indicates whether the KMS key is a multi-Region (true) or regional (false) key. Defaults to false	bool	false	no
override_policy_documents	List of IAM policy documents that are merged together into the exported document. In merging, statements with non-blank sids will override statements with the same sid	list(string)	[]	no
policy	A valid policy JSON document. Although this is a key policy, not an IAM policy, an aws_iam_policy_document, in the form that designates a principal, can be used	string	null	no
primary_external_key_arn	The primary external key arn of a multi-region replica external key	string	null	no
primary_key_arn	The primary key arn of a multi-region replica key	string	null	no
rotation_period_in_days	Custom period of time between each rotation date. Must be a number between 90 and 2560 (inclusive)	number	null	no
route53_dnssec_sources	A list of maps containing account_ids and Route53 hosted_zone_arn that will be allowed to sign DNSSEC records	list(any)	[]	no
source_policy_documents	List of IAM policy documents that are merged together into the exported document. Statements must have unique sids	list(string)	[]	no
tags	A map of tags to add to all resources	map(string)	{}	no
valid_to	Time at which the imported key material expires. When the key material expires, AWS KMS deletes the key material and the CMK becomes unusable. If not specified, key material does not expire	string	null	no

Outputs

Name	Description
aliases	A map of aliases created and their attributes
external_key_expiration_model	Whether the key material expires. Empty when pending key material import, otherwise KEY_MATERIAL_EXPIRES or KEY_MATERIAL_DOES_NOT_EXPIRE
external_key_state	The state of the CMK
external_key_usage	The cryptographic operations for which you can use the CMK
grants	A map of grants created and their attributes
key_arn	The Amazon Resource Name (ARN) of the key
key_id	The globally unique identifier for the key
key_policy	The IAM resource policy set on the key

License

Apache-2.0 Licensed. See LICENSE.