add key_spec and upgrade readme

Author: magreenbaum

README.md

@@ -202,6 +202,7 @@ No modules.
 | <a name="input_key_owners"></a> [key\_owners](#input\_key\_owners) | A list of IAM ARNs for those who will have full key permissions (`kms:*`) | `list(string)` | `[]` | no |
 | <a name="input_key_service_roles_for_autoscaling"></a> [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 |
 | <a name="input_key_service_users"></a> [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 |
+| <a name="input_key_spec"></a> [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 |
 | <a name="input_key_statements"></a> [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 | <pre>list(object({<br/>    sid           = optional(string)<br/>    actions       = optional(list(string))<br/>    not_actions   = optional(list(string))<br/>    effect        = optional(string)<br/>    resources     = optional(list(string))<br/>    not_resources = optional(list(string))<br/>    principals = optional(list(object({<br/>      type        = string<br/>      identifiers = list(string)<br/>    })))<br/>    not_principals = optional(list(object({<br/>      type        = string<br/>      identifiers = list(string)<br/>    })))<br/>    condition = optional(list(object({<br/>      test     = string<br/>      values   = list(string)<br/>      variable = string<br/>    })))<br/>  }))</pre> | `null` | no |
 | <a name="input_key_symmetric_encryption_users"></a> [key\_symmetric\_encryption\_users](#input\_key\_symmetric\_encryption\_users) | A list of IAM ARNs for [key symmetric encryption users](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-default.html#key-policy-users-crypto) | `list(string)` | `[]` | no |
 | <a name="input_key_usage"></a> [key\_usage](#input\_key\_usage) | Specifies the intended use of the key. Valid values: `ENCRYPT_DECRYPT` or `SIGN_VERIFY`. Defaults to `ENCRYPT_DECRYPT` | `string` | `null` | no |

UPGRADE-4.0.md

@@ -0,0 +1,162 @@
+# Upgrade from v3.x to v4.x
+
+If you have any questions regarding this upgrade process, please consult the [`examples/`](https://github.com/terraform-aws-modules/terraform-aws-kms/tree/master/examples) projects:
+
+If you find a bug, please open an issue with supporting configuration to reproduce.
+
+## List of backwards incompatible changes
+
+- Support for Terraform `<1.5.7` has been dropped; `1.5.7` is now the minimum supported version
+- Terraform AWS provider minimum version is now `v6.0.0` in order to support the `region` argument in resources
+- Variable `key_statements.conditions` is now `key_statements.condition`
+- Variable `grants.constraints` has changed to type list
+
+## Additional changes
+
+### Added
+
+- `region` to support creating resources in a different region than the provider region
+
+### Modified
+
+- `key_statements.conditions` changed to `key_statements.condition`
+- `grants.constrants` changed to type list
+
+### Variable and output changes
+
+1. Removed variables:
+
+  - None
+
+2. Renamed variables:
+
+  - `key_statements.conditions` -> `key_statements.condition`
+
+3. Added variables:
+
+  - `region`
+
+4. Removed outputs:
+
+  - None
+
+5. Renamed outputs:
+
+  - None
+
+6. Added outputs:
+
+  - `key_region` added to support output for setting the `region` variable
+
+## Upgrade Migrations
+
+The following examples demonstrate some of the changes that users can elect to make to avoid any potential disruptions when upgrading.
+
+### Before 3.x Example
+
+```hcl
+module "kms" {
+  source  = "terraform-aws-modules/rds/aws"
+  version = "~> 3.0"
+
+  # Only the affected attributes are shown
+  key_statements = [
+    {
+      sid = "CloudWatchLogs"
+      actions = [
+        "kms:Encrypt*",
+        "kms:Decrypt*",
+        "kms:ReEncrypt*",
+        "kms:GenerateDataKey*",
+        "kms:Describe*"
+      ]
+      resources = ["*"]
+
+      principals = [
+        {
+          type        = "Service"
+          identifiers = ["logs.${data.aws_region.current.name}.amazonaws.com"]
+        }
+      ]
+
+      conditions = [
+        {
+          test     = "ArnLike"
+          variable = "kms:EncryptionContext:aws:logs:arn"
+          values = [
+            "arn:aws:logs:${local.region}:${data.aws_caller_identity.current.account_id}:log-group:*",
+          ]
+        }
+      ]
+    }
+  ]
+
+  # Grants
+  grants = {
+    lambda = {
+      grantee_principal = aws_iam_role.lambda.arn
+      operations        = ["Encrypt", "Decrypt", "GenerateDataKey"]
+      constraints = {
+        encryption_context_equals = {
+          Department = "Finance"
+        }
+      }
+    }
+  }
+
+  tags = local.tags
+}
+```
+
+### After 4.x Example
+
+```hcl
+module "kms" {
+  source  = "terraform-aws-modules/rds/aws"
+  version = "~> 4.0"
+
+  key_statements = [
+    {
+      sid = "CloudWatchLogs"
+      actions = [
+        "kms:Encrypt*",
+        "kms:Decrypt*",
+        "kms:ReEncrypt*",
+        "kms:GenerateDataKey*",
+        "kms:Describe*"
+      ]
+      resources = ["*"]
+
+      principals = [
+        {
+          type        = "Service"
+          identifiers = ["logs.${local.region}.amazonaws.com"]
+        }
+      ]
+
+      condition = [
+        {
+          test     = "ArnLike"
+          variable = "kms:EncryptionContext:aws:logs:arn"
+          values = [
+            "arn:aws:logs:${local.region}:${local.account_id}:log-group:*",
+          ]
+        }
+      ]
+    }
+  ]
+
+  # Grants
+  grants = {
+    lambda = {
+      grantee_principal = aws_iam_role.lambda.arn
+      operations        = ["Encrypt", "Decrypt", "GenerateDataKey"]
+      constraints = [{
+        encryption_context_equals = {
+          Department = "Finance"
+        }
+      }]
+    }
+  }
+}
+```

main.tf

@@ -49,6 +49,8 @@ resource "aws_kms_external_key" "this" {
   description                        = var.description
   enabled                            = var.is_enabled
   key_material_base64                = var.key_material_base64
+  key_spec                           = var.key_spec
+  key_usage                          = var.key_usage
   multi_region                       = var.multi_region
   policy                             = coalesce(var.policy, data.aws_iam_policy_document.this[0].json)
   valid_to                           = var.valid_to

variables.tf

@@ -184,6 +184,12 @@ variable "key_statements" {
   default = null
 }
 
+variable "key_spec" {
+  description = "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"
+  type        = string
+  default     = null
+}
+
 variable "source_policy_documents" {
   description = "List of IAM policy documents that are merged together into the exported document. Statements must have unique `sid`s"
   type        = list(string)

wrappers/main.tf

@@ -28,6 +28,7 @@ module "wrapper" {
   key_owners                             = try(each.value.key_owners, var.defaults.key_owners, [])
   key_service_roles_for_autoscaling      = try(each.value.key_service_roles_for_autoscaling, var.defaults.key_service_roles_for_autoscaling, [])
   key_service_users                      = try(each.value.key_service_users, var.defaults.key_service_users, [])
+  key_spec                               = try(each.value.key_spec, var.defaults.key_spec, null)
   key_statements                         = try(each.value.key_statements, var.defaults.key_statements, null)
   key_symmetric_encryption_users         = try(each.value.key_symmetric_encryption_users, var.defaults.key_symmetric_encryption_users, [])
   key_usage                              = try(each.value.key_usage, var.defaults.key_usage, null)