AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource and Property Types Reference » AWS Key Management Service 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.

Syntax

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

JSON

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

YAML

Type: AWS::KMS::Key
Properties: 
  Description: String
  Enabled: Boolean
  EnableKeyRotation: Boolean
  KeyPolicy: JSON object
  KeyUsage: String
  PendingWindowInDays: Integer
  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

KeyUsage

The intended use of the key. You can use CMKs only for symmetric encryption and decryption.

Valid values: ENCRYPT_DECRYPT

Required: No

Type: String

Update requires: Replacement

PendingWindowInDays

The waiting period, specified in number of days. After the waiting period ends, AWS KMS deletes the customer master key (CMK).

Valid Range: Minimum value of 7. Maximum value of 30.

Required: No

Type: Integer

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: Resource Tag

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

"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

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

{
  "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: !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