AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource Types Reference » AWS::KMS::Key

Filter View: All JSON YAML

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.

Topics

• Syntax
• Properties
• Return Values
• Example

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
  }
}

YAML

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

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

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.

Example

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: "*"