# kms

Creates a KMS Customer Managed Key with aliases, grants, and optional cross-account sharing.

Provisions a KMS CMK with automatic annual key rotation enabled by default, a configurable key policy (defaulting to account root with optional cross-account principals), named aliases, and fine-grained grants. Supports multi-region primary keys for cross-region replication scenarios.

## Usage

```hcl
module "kms" {
  source  = "hcassc.jfrog.io/iac-terraform-modules-virtual/security/kms/aws"
  version = "0.1.0"

  description = "S3 encryption key"
  aliases     = ["s3/data-lake"]

  cross_account_principals = [
    "arn:aws:iam::111122223333:root",
  ]
}
```

<!-- BEGIN_TF_DOCS — DO NOT EDIT BELOW THIS LINE -->
## Requirements

| Name | Version |
| ---- | ------- |
| <a name="requirement_terraform"></a> [terraform](#requirement_terraform) | ~> 1.5 |
| <a name="requirement_aws"></a> [aws](#requirement_aws) | ~> 6.50 |

## Providers

| Name | Version |
| ---- | ------- |
| <a name="provider_aws"></a> [aws](#provider_aws) | 6.50.0 |

## Resources

| Name | Type |
| ---- | ---- |
| [aws_kms_alias.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_alias) | 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 |

## Inputs

| Name | Description | Type | Default | Required |
| ---- | ----------- | ---- | ------- | :------: |
| <a name="input_aliases"></a> [aliases](#input_aliases) | List of alias names (without alias/ prefix) | `list(string)` | `[]` | no |
| <a name="input_cross_account_principals"></a> [cross_account_principals](#input_cross_account_principals) | List of external account principals allowed to use the key | `list(string)` | `[]` | no |
| <a name="input_customer_master_key_spec"></a> [customer_master_key_spec](#input_customer_master_key_spec) | Key spec — SYMMETRIC_DEFAULT, RSA_2048, RSA_4096, ECC_NIST_P256, etc. | `string` | `"SYMMETRIC_DEFAULT"` | no |
| <a name="input_deletion_window_in_days"></a> [deletion_window_in_days](#input_deletion_window_in_days) | Days before key deletion after destruction (7–30) | `number` | `30` | no |
| <a name="input_description"></a> [description](#input_description) | Description for the KMS key | `string` | `"Managed by Terraform"` | no |
| <a name="input_enable_key_rotation"></a> [enable_key_rotation](#input_enable_key_rotation) | Enable automatic annual key rotation | `bool` | `true` | no |
| <a name="input_grants"></a> [grants](#input_grants) | Map of KMS grants to create | <pre>map(object({<br/>    grantee_principal  = string<br/>    operations         = list(string)<br/>    retiring_principal = optional(string, null)<br/>    constraints = optional(object({<br/>      encryption_context_equals = optional(map(string), null)<br/>      encryption_context_subset = optional(map(string), null)<br/>    }), null)<br/>  }))</pre> | `{}` | no |
| <a name="input_key_usage"></a> [key_usage](#input_key_usage) | Key usage — ENCRYPT_DECRYPT or SIGN_VERIFY | `string` | `"ENCRYPT_DECRYPT"` | no |
| <a name="input_multi_region"></a> [multi_region](#input_multi_region) | Create a multi-region primary key | `bool` | `false` | no |
| <a name="input_policy"></a> [policy](#input_policy) | JSON key policy document (optional — uses AWS default if null) | `string` | `null` | no |
| <a name="input_tags"></a> [tags](#input_tags) | Resource tags to apply to all resources | `map(string)` | `{}` | no |

## Outputs

| Name | Description |
| ---- | ----------- |
| <a name="output_alias_arns"></a> [alias_arns](#output_alias_arns) | Map of alias name to alias ARN |
| <a name="output_arn"></a> [arn](#output_arn) | KMS key ARN |
| <a name="output_grant_ids"></a> [grant_ids](#output_grant_ids) | Map of grant name to grant token |
| <a name="output_id"></a> [id](#output_id) | KMS key ID |
| <a name="output_key_id"></a> [key_id](#output_key_id) | KMS key ID (alias for id) |
<!-- END_TF_DOCS — DO NOT EDIT ABOVE THIS LINE -->