Menu
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS::KMS::Key

The AWS::KMS::Key resource creates a customer master key (CMK) in AWS Key Management Service (AWS KMS). Users (customers) can use the master key to encrypt their data stored in AWS services that are integrated with AWS KMS or within their applications. For more information, see What is the AWS Key Management Service? in the AWS Key Management Service Developer Guide.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

Copy
{ "Type" : "AWS::KMS::Key", "Properties" : { "Description" : String, "Enabled" : Boolean, "EnableKeyRotation" : Boolean, "KeyPolicy" : JSON object "Tags" : [ Resource Tag, ... ], } }

YAML

Copy
Type: "AWS::KMS::Key" Properties: Description: String Enabled: Boolean EnableKeyRotation: Boolean KeyPolicy: JSON object Tags: - Resource Tag

Properties

Description

A description of the key. Use a description that helps your users decide whether the key is appropriate for a particular task.

Required: No

Type: String

Update requires: No interruption

Enabled

Indicates whether the key is available for use. AWS CloudFormation sets this value to true by default.

Required: No

Type: Boolean

Update requires: No interruption

EnableKeyRotation

Indicates whether AWS KMS rotates the key. AWS CloudFormation sets this value to false by default.

Required: No

Type: Boolean

Update requires: No interruption

KeyPolicy

An AWS KMS key policy to attach to the key. Use a policy to specify who has permission to use the key and which actions they can perform. For more information, see Key Policies in the AWS Key Management Service Developer Guide.

Required: Yes

Type: JSON object

Update requires: No interruption

Tags

Specifies an arbitrary set of tags (key–value pairs) to associate with this key. Use tags to manage your resources.

Required: No

Type: AWS CloudFormation Resource Tags

Update requires: No interruption

Return Values

Ref

When you provide the logical ID of this resource to the Ref intrinsic function, it returns the key ID, such as 123ab456-a4c2-44cb-95fd-b781f32fbb37.

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

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

Arn

The ARN of the AWS KMS key, such as arn:aws:kms:us-west-2:123456789012:key/12a34567-8c90-1defg-af84-0bf06c1747f3.

For more information about using Fn::GetAtt, see Fn::GetAtt.

Examples

The following example creates a custom CMK, which permits the IAM user Alice to administer the key and allows Bob to use the key for encrypting and decrypting data.

JSON

Copy
"myKey" : { "Type" : "AWS::KMS::Key", "Properties" : { "Description" : "A sample key", "KeyPolicy" : { "Version": "2012-10-17", "Id": "key-default-1", "Statement": [ { "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:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" } ] } } }

YAML

Copy
myKey: Type: "AWS::KMS::Key" Properties: Description: "A sample key" KeyPolicy: Version: "2012-10-17" Id: "key-default-1" Statement: - 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:Encrypt" - "kms:Decrypt" - "kms:ReEncrypt*" - "kms:GenerateDataKey*" - "kms:DescribeKey" Resource: "*"

The following example creates a custom CMK with a single tag.

JSON

Copy
{ "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

Copy
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: !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