AWS::KMS::Key - AWS CloudFormation
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS::KMS::Key

AWS::KMS::Key 资源指定 AWS Key Management Service (AWS KMS) 中的对称客户主密钥 (CMK)。您可以使用对称 CMK 加密和解密少量数据,但它们更经常用于生成对称数据密钥和非对称数据密钥对。您还可以使用对称 CMK 对存储在与 AWS KMS 集成的 AWS 服务中的数据进行加密。有关更多信息,请参阅 AWS Key Management Service 开发人员指南 中的什么是 AWS Key Management Service?

注意

AWS KMS 目前不支持使用 CloudFormation 模板创建非对称 CMK。

语法

要在 AWS CloudFormation 模板中声明此实体,请使用以下语法:

JSON

{ "Type" : "AWS::KMS::Key", "Properties" : { "Description" : String, "Enabled" : Boolean, "EnableKeyRotation" : Boolean, "KeyPolicy" : Json, "KeyUsage" : String, "PendingWindowInDays" : Integer, "Tags" : [ Tag, ... ] } }

YAML

Type: AWS::KMS::Key Properties: Description: String Enabled: Boolean EnableKeyRotation: Boolean KeyPolicy: Json KeyUsage: String PendingWindowInDays: Integer Tags: - Tag

属性

Description

CMK 的描述。使用帮助您将此 CMK 与账户中的其他 CMK 区别开来的描述,例如其预期用途。

必需:否

类型:字符串

最低0

最高8192

Update requires: No interruption

Enabled

指定是否启用客户主密钥 (CMK)。无法在加密操作中使用禁用的 CMK。

Enabledtrue 时,CMK 的密钥状态Enabled。当 Enabledfalse 时,CMK 的密钥状态为 Disabled。默认值为 true

CMK 的实际密钥状态可能受在 CloudFormation 外部执行的操作的影响,例如运行 EnableKeyDisableKeyScheduleKeyDeletion 操作。

有关 CMK 的密钥状态的信息,请参阅 AWS Key Management Service 开发人员指南 中的密钥状态如何影响客户主密钥的使用

必需:否

类型:布尔值

Update requires: No interruption

EnableKeyRotation

为指定的客户主密钥 (CMK) 启用密钥材料的自动轮换。默认情况下,不启用自动密钥轮换。

当您启用自动轮换时,AWS KMS 会在启用(或重新启用)日期 365 天后为 CMK 创建新的密钥材料,并在今后每隔 365 天创建一次。AWS KMS 将保留所有密钥材料,直到您删除该 CMK。

有关自动密钥轮换的详细信息,请参阅 AWS Key Management Service 开发人员指南 中的轮换客户主密钥

必需:否

类型:布尔值

Update requires: No interruption

KeyPolicy

授权使用 CMK 的密钥策略。该密钥策略必须遵守以下规则。

  • 该密钥策略必须允许调用方在 CMK 上进行后续 PutKeyPolicy 请求。这降低了 CMK 变得不可管理的风险。有关更多信息,请参阅 AWS Key Management Service 开发人员指南 默认密钥策略部分中的方案。

  • 密钥策略中的每条语句必须包含一个或多个委托人。密钥策略中的委托人必须存在并对 AWS KMS 可见。在创建新的 AWS 委托人(例如,IAM 用户或角色)时,您可能需要在将新委托人包含到密钥策略中之前强制实施延迟,因为新的委托人可能不会立即对 AWS KMS 可见。有关更多信息,请参阅 AWS Identity and Access Management 用户指南 中的我做的更改并不总是立即可见

  • 密钥策略大小限制为 32 KB(32768 个字节)。

如果您不确定要使用哪个策略,请考虑默认密钥策略。这是 AWS KMS 应用于通过在未指定密钥策略的情况下使用 CreateKey API 创建的 CMK 的关键策略。它为拥有密钥的 AWS 账户提供对密钥执行所有操作的权限。它还允许您编写 IAM 策略来授予对密钥的访问权。有关详细信息,请参阅 AWS Key Management Service 开发人员指南 中的默认密钥策略

必需:是

类型:Json

最低1

最高131072

模式[\u0009\u000A\u000D\u0020-\u00FF]+

Update requires: No interruption

KeyUsage

确定可以使用 CMK 的加密操作。默认值 ENCRYPT_DECRYPT 是对称 CMK 的唯一有效值。在创建 CMK 后,您无法更改 KeyUsage 值。

允许的值:ENCRYPT_DECRYPT

必需:否

类型:字符串

Update requires: Replacement

PendingWindowInDays

指定 AWS KMS 删除已从 CloudFormation 堆栈中移除的 CMK 之前的等待期的天数。请输入 7 到 30 天之间的值。默认值为 30 天。

在从 CloudFormation 堆栈中删除客户主密钥 (CMK) 时,AWS KMS 将安排删除 CMK 并启动强制等待期。PendingWindowInDays 属性将确定等待期的长度。在等待期内,CMK 的密钥状态为 Pending Deletion,这会阻止在加密操作中使用 CMK。在等待期到期后,AWS KMS 将永久删除 CMK。

在从堆栈中删除 CMK 之后,您不能使用 CloudFormation 模板取消对 CMK 的删除,无论等待期如何。如果您在模板中指定 CMK,即使是同名的 CMK,CloudFormation 也会创建一个新的 CMK。要取消删除 CMK,请使用 AWS KMS 控制台或 CancelKeyDeletion 操作。

有关 PendingDeletion 密钥状态的信息,请参阅 AWS Key Management Service 开发人员指南 中的密钥状态如何影响客户主密钥的使用。有关删除 CMK 的更多信息,请参阅 AWS Key Management Service API 参考 中的 ScheduleKeyDeletion 操作以及 AWS Key Management Service 开发人员指南 中的删除客户主密钥

最小值:7

最大值:30

必需:否

类型:整数

Update requires: No interruption

Tags

要应用于此资源的键值对的数组。

有关更多信息,请参阅标签

必需:否

类型Tag 的列表

Update requires: No interruption

返回值

Ref

在将此资源的逻辑 ID 传递给内部 Ref 函数时,Ref 返回密钥 ID,例如 1234abcd-12ab-34cd-56ef-1234567890ab

For more information about using the Ref function, see Ref.

Fn::GetAtt

Fn::GetAtt 内部函数返回此类型的一个指定属性的值。以下为可用属性和示例返回值。

有关使用 Fn::GetAtt 内部函数的更多信息,请参阅 Fn::GetAtt

Arn

AWS KMS 客户主密钥 (CMK) 的 Amazon 资源名称 (ARN),例如 arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

要获得有关查找 CMK 的 ARN 的帮助,请参阅 AWS Key Management Service 开发人员指南 中的查找密钥 ID 和 ARN

示例

创建对称 CMK

以下示例创建一个对称的 CMK。CMK 的密钥策略允许 Alice 管理此密钥,并允许 Bob 查看 CMK 并在加密操作中使用它。它还允许 AWS 账户(根)对密钥进行完全访问。这可防止您在从账户中同时删除 AliceBob 的情况下丢失对密钥的控制。

JSON

"myKey" : { "Type" : "AWS::KMS::Key", "Properties" : { "Description" : "An example symmetric CMK", "KeyPolicy" : { "Version": "2012-10-17", "Id": "key-default-1", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::111122223333:root"}, "Action": "kms:*", "Resource": "*" }, { "Sid": "Allow administration of the key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/Alice" }, "Action": [ "kms:Create*", "kms:Describe*", "kms:Enable*", "kms:List*", "kms:Put*", "kms:Update*", "kms:Revoke*", "kms:Disable*", "kms:Get*", "kms:Delete*", "kms:ScheduleKeyDeletion", "kms:CancelKeyDeletion" ], "Resource": "*" }, { "Sid": "Allow use of the key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/Bob" }, "Action": [ "kms:DescribeKey", "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey", "kms:GenerateDataKeyWithoutPlaintext" ], "Resource": "*" } ] } } }

YAML

myKey: Type: AWS::KMS::Key Properties: Description: An example symmetric CMK KeyPolicy: Version: '2012-10-17' Id: key-default-1 Statement: - Sid: Enable IAM User Permissions Effect: Allow Principal: AWS: arn:aws:iam::111122223333:root Action: kms:* Resource: '*' - Sid: Allow administration of the key Effect: Allow Principal: AWS: arn:aws:iam::123456789012:user/Alice Action: - kms:Create* - kms:Describe* - kms:Enable* - kms:List* - kms:Put* - kms:Update* - kms:Revoke* - kms:Disable* - kms:Get* - kms:Delete* - kms:ScheduleKeyDeletion - kms:CancelKeyDeletion Resource: '*' - Sid: Allow use of the key Effect: Allow Principal: AWS: arn:aws:iam::123456789012:user/Bob Action: - kms:DescribeKey - kms:Encrypt - kms:Decrypt - kms:ReEncrypt* - kms:GenerateDataKey - kms:GenerateDataKeyWithoutPlaintext Resource: '*'

使用资源标签创建对称 CMK

以下示例创建具有一个资源标签的对称 CMK。

JSON

{ "Resources" : { "myKey" : { "Type" : "AWS::KMS::Key", "Properties" : { "KeyPolicy" : { "Version": "2012-10-17", "Id": "key-default-1", "Statement": [ { "Sid": "Enable IAM User Permissions", "Effect": "Allow", "Principal": { "AWS": { "Fn::Join" : ["" , ["arn:aws:iam::", {"Ref" : "AWS::AccountId"} ,":root" ]] } }, "Action": "kms:*", "Resource": "*" } ] }, "Tags" : [ { "Key" : {"Ref" : "Key"}, "Value" : {"Ref" : "Value"} } ] } } }, "Parameters" : { "Key" : { "Type" : "String" }, "Value" : { "Type" : "String" } } }

YAML

Resources: myKey: Type: AWS::KMS::Key Properties: KeyPolicy: Version: '2012-10-17' Id: key-default-1 Statement: - Sid: Enable IAM User Permissions Effect: Allow Principal: AWS: Fn::Join: - '' - - 'arn:aws:iam::' - Ref: AWS::AccountId - :root Action: kms:* Resource: '*' Tags: - Key: Ref: Key Value: Ref: Value Parameters: Key: Type: String Value: Type: String

另请参阅

  • AWS Key Management Service 开发人员指南 中的创建密钥

  • AWS Key Management Service API 参考 中的 CreateKey

  • AWS Key Management Service 开发人员指南 中的客户主密钥