# AWS KMS Terraform module Terraform module which creates AWS KMS resources. [![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md) ## Usage See [`examples`](https://github.com/terraform-aws-modules/terraform-aws-kms/tree/master/examples) directory for working examples to reference: ### Autoscaling Service Linked Role 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" 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): ```hcl 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. ```hcl 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" } } ``` ## Known limitations (Terraform/OpenTofu, not this module) A few requests come up again and again and cannot be implemented by this module, or by any module: Terraform requires `lifecycle` arguments to be literal values inside the resource block. [hashicorp/terraform#18367](https://github.com/hashicorp/terraform/issues/18367) has been open since 2018, [#22544](https://github.com/hashicorp/terraform/issues/22544) since 2019, and [opentofu/opentofu#1329](https://github.com/opentofu/opentofu/issues/1329) is the same request for OpenTofu. - **terraform destroy scheduled deletion of a KMS key** - Native option: raise `deletion_window_in_days` to 30, which this module already exposes, so a scheduled deletion can be cancelled. [Compliance.tf](https://compliance.tf/?utm_source=github&utm_medium=readme&utm_campaign=known-limitations) serves this module with these rules applied at download time, on top of whatever your organization already has enabled there. Inputs and outputs do not change; the `source` line does. Drop the `version` argument and pin the release you use by adding `&version=` and that release number to the URL. To get started, register a free compliance.tf account and configure an access token: source = "https://registry.compliance.tf/terraform-aws-modules/kms/aws?add_rules=lifecycle_prevent_destroy_encryption" The full workaround for each item above, and the exact diff each rule makes, are in the [compliance.tf docs for this module](https://compliance.tf/docs/workarounds/terraform-aws-kms/?utm_source=github&utm_medium=readme&utm_campaign=known-limitations). To preview a diff without an account, open this module in the [Rules Playground](https://registry.compliance.tf/playground?module=terraform-aws-modules/kms/aws&rules=lifecycle_prevent_destroy_encryption). Disclosure: written by this module's maintainer, who also builds [compliance.tf](https://compliance.tf/?utm_source=github&utm_medium=readme&utm_campaign=known-limitations). ## Examples Examples codified under the [`examples`](https://github.com/terraform-aws-modules/terraform-aws-kms/tree/master/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](https://github.com/terraform-aws-modules/terraform-aws-kms/tree/master/examples/complete) ## Requirements | Name | Version | | ---- | ------- | | [terraform](#requirement\_terraform) | >= 1.5.7 | | [aws](#requirement\_aws) | >= 6.28 | ## Providers | Name | Version | | ---- | ------- | | [aws](#provider\_aws) | >= 6.28 | ## Modules No modules. ## Resources | Name | Type | | ---- | ---- | | [aws_kms_alias.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_alias) | resource | | [aws_kms_external_key.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_external_key) | resource | | [aws_kms_grant.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_grant) | resource | | [aws_kms_key.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_key) | resource | | [aws_kms_replica_external_key.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_replica_external_key) | resource | | [aws_kms_replica_key.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_replica_key) | resource | | [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source | | [aws_iam_policy_document.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source | | [aws_partition.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/partition) | data source | ## Inputs | Name | Description | Type | Default | Required | | ---- | ----------- | ---- | ------- | :------: | | [aliases](#input\_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](#input\_aliases\_use\_name\_prefix) | Determines whether the alias name is used as a prefix | `bool` | `false` | no | | [bypass\_policy\_lockout\_safety\_check](#input\_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](#input\_computed\_aliases) | A map of aliases to create. Values provided via the `name` key of the map can be computed from upstream resources |

map(object({
    name = string
  }))

| `{}` | no | | [create](#input\_create) | Determines whether resources will be created (affects all resources) | `bool` | `true` | no | | [create\_external](#input\_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](#input\_create\_replica) | Determines whether a replica standard CMK will be created (AWS provided material) | `bool` | `false` | no | | [create\_replica\_external](#input\_create\_replica\_external) | Determines whether a replica external CMK will be created (externally provided material) | `bool` | `false` | no | | [custom\_key\_store\_id](#input\_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](#input\_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](#input\_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](#input\_description) | The description of the key as viewed in AWS console | `string` | `null` | no | | [enable\_default\_policy](#input\_enable\_default\_policy) | Specifies whether to enable the default key policy. Defaults to `true` | `bool` | `true` | no | | [enable\_key\_rotation](#input\_enable\_key\_rotation) | Specifies whether key rotation is enabled. Defaults to `true` | `bool` | `true` | no | | [enable\_route53\_dnssec](#input\_enable\_route53\_dnssec) | Determines whether the KMS policy used for Route53 DNSSEC signing is enabled | `bool` | `false` | no | | [grants](#input\_grants) | A map of grant definitions to create |

map(object({
    constraints = optional(list(object({
      encryption_context_equals = optional(map(string))
      encryption_context_subset = optional(map(string))
    })))
    grant_creation_tokens = optional(list(string))
    grantee_principal     = string
    name                  = optional(string) # Will fall back to use map key
    operations            = list(string)
    retire_on_delete      = optional(bool)
    retiring_principal    = optional(string)
  }))

| `null` | no | | [is\_enabled](#input\_is\_enabled) | Specifies whether the key is enabled. Defaults to `true` | `bool` | `null` | no | | [key\_administrators](#input\_key\_administrators) | A list of IAM ARNs for [key administrators](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html#key-policy-default-allow-administrators) | `list(string)` | `[]` | no | | [key\_asymmetric\_public\_encryption\_users](#input\_key\_asymmetric\_public\_encryption\_users) | A list of IAM ARNs for [key asymmetric public encryption users](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html#key-policy-users-crypto) | `list(string)` | `[]` | no | | [key\_asymmetric\_sign\_verify\_users](#input\_key\_asymmetric\_sign\_verify\_users) | A list of IAM ARNs for [key asymmetric sign and verify users](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html#key-policy-users-crypto) | `list(string)` | `[]` | no | | [key\_hmac\_users](#input\_key\_hmac\_users) | A list of IAM ARNs for [key HMAC users](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html#key-policy-users-crypto) | `list(string)` | `[]` | no | | [key\_material\_base64](#input\_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](#input\_key\_owners) | A list of IAM ARNs for those who will have full key permissions (`kms:*`) | `list(string)` | `[]` | no | | [key\_service\_roles\_for\_autoscaling](#input\_key\_service\_roles\_for\_autoscaling) | A list of IAM ARNs for [AWSServiceRoleForAutoScaling roles](https://docs.aws.amazon.com/autoscaling/ec2/userguide/key-policy-requirements-EBS-encryption.html#policy-example-cmk-access) | `list(string)` | `[]` | no | | [key\_service\_users](#input\_key\_service\_users) | A list of IAM ARNs for [key service users](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html#key-policy-service-integration) | `list(string)` | `[]` | no | | [key\_spec](#input\_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\_224, HMAC\_256, HMAC\_384, HMAC\_512, ECC\_NIST\_P256, ECC\_NIST\_P384, ECC\_NIST\_P521, ECC\_SECG\_P256K1, ML\_DSA\_44, ML\_DSA\_65, ML\_DSA\_87, or SM2 (China Regions only). Defaults to SYMMETRIC\_DEFAULT | `string` | `null` | no | | [key\_statements](#input\_key\_statements) | A map of IAM policy [statements](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document#statement) for custom permission usage |

list(object({
    sid           = optional(string)
    actions       = optional(list(string))
    not_actions   = optional(list(string))
    effect        = optional(string)
    resources     = optional(list(string))
    not_resources = optional(list(string))
    principals = optional(list(object({
      type        = string
      identifiers = list(string)
    })))
    not_principals = optional(list(object({
      type        = string
      identifiers = list(string)
    })))
    condition = optional(list(object({
      test     = string
      values   = list(string)
      variable = string
    })))
  }))

list(object({
    account_ids     = optional(list(string))
    hosted_zone_arn = optional(string)
  }))

| `null` | no | | [source\_policy\_documents](#input\_source\_policy\_documents) | List of IAM policy documents that are merged together into the exported document. Statements must have unique `sid`s | `list(string)` | `[]` | no | | [tags](#input\_tags) | A map of tags to add to all resources | `map(string)` | `{}` | no | | [valid\_to](#input\_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](#output\_aliases) | A map of aliases created and their attributes | | [external\_key\_expiration\_model](#output\_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](#output\_external\_key\_state) | The state of the CMK | | [external\_key\_usage](#output\_external\_key\_usage) | The cryptographic operations for which you can use the CMK | | [grants](#output\_grants) | A map of grants created and their attributes | | [key\_arn](#output\_key\_arn) | The Amazon Resource Name (ARN) of the key | | [key\_id](#output\_key\_id) | The globally unique identifier for the key | | [key\_policy](#output\_key\_policy) | The IAM resource policy set on the key | | [key\_region](#output\_key\_region) | The region for the key | ## License Apache-2.0 Licensed. See [LICENSE](https://github.com/terraform-aws-modules/terraform-aws-kms/blob/master/LICENSE).

Controls