Amazon KMS key policy and permissions for encrypting Amazon CloudFormation Hooks results at rest - Amazon CloudFormation
OverviewEncryption contextCustomer managed KMS key policyKMS permissions for SetTypeConfiguration APIKMS permissions for GetHookResult API
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon KMS key policy and permissions for encrypting Amazon CloudFormation Hooks results at rest

This topic describes how to set up the Amazon KMS key policy and permissions that you need when you specify a customer managed key for encrypting Hooks annotations data that's available from the GetHookResult API.

Note

Amazon CloudFormation Hooks doesn't need additional authorization to use the default Amazon owned key to encrypt annotations data in your account.

Overview

The following Amazon KMS keys can be used for encrypting Hook annotations data:

  • Amazon owned key – By default, CloudFormation uses an Amazon owned key to encrypt data. You can't view, manage, or use Amazon owned keys, or audit their use. However, you don't have to perform explicit configuration to protect the key that's used to encrypt your data. Amazon owned keys are provided free of charge (no monthly fees or usage fees). Unless you are required to audit or control the encryption key that protects your annotations data, an Amazon owned key is a good choice.

  • Customer managed key – CloudFormation supports the use of a symmetric customer managed key that you create, own, and manage to add a second layer of encryption over the existing Amazon owned key. Amazon KMS charges apply. For more information, see Creating keys in the Amazon Key Management Service Developer Guide. To manage your key, use the Amazon Key Management Service (Amazon KMS) in the Amazon KMS console, the Amazon CLI, or the Amazon KMS API. For more information, see the Amazon Key Management Service Developer Guide.

You can configure customer managed keys when creating and updating Hooks. When you provide your customer managed key, CloudFormation uses this key to encrypt the annotations data before storing it. When the annotations data is later accessed during the GetHookResult API operation, CloudFormation automatically decrypts it. For information about configuring your encryption key for Hooks, see Hook configuration schema syntax reference.

Important

Note that the KmsKeyId option to specify a customer managed key is currently only available when you use the Amazon CLI to configure your Hook.

Using encryption context to control access to your customer managed key

CloudFormation Hooks automatically includes encryption context with every annotation storage and retrieval operation. This allows you to set encryption context conditions in your key policy to ensure the key can only be used for specific Hooks:

  • kms:EncryptionContext:aws:cloudformation:hooks:service – Ensures the key is only used by the CloudFormation Hooks service.

  • kms:EncryptionContext:aws:cloudformation:account-id – Prevents cross-account key usage by matching your Amazon Web Services account ID.

  • kms:EncryptionContext:aws:cloudformation:arn – Restrict usage to specific Hooks using ARN patterns.

These conditions provide additional protection against confused deputy attacks by cryptographically binding the encrypted data to the specific Hook context.

Customer managed KMS key policy

When creating your customer managed key, you must define its key policy to allow the CloudFormation Hooks service to perform Amazon KMS operations. To use the following key policy, replace the placeholder values with your own information.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EnableIAMUserDescribeKey",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws-cn:iam::111122223333:role/ExampleRole"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "cloudformation.us-east-1.amazonaws.com"
        }
      }
    },
    {
      "Sid": "EnableIAMUserGenerateDataKey",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws-cn:iam::111122223333:role/ExampleRole"
      },
      "Action": "kms:GenerateDataKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "cloudformation.us-east-1.amazonaws.com",
          "kms:EncryptionContext:aws:cloudformation:hooks:service": "hooks.cloudformation.amazonaws.com",
          "kms:EncryptionContext:aws:cloudformation:account-id": "111122223333"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:cloudformation:arn": "arn:aws-cn:cloudformation:*:111122223333:hook/*"
        }
      }
    },
    {
      "Sid": "EnableIAMUserDecrypt",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws-cn:iam::111122223333:role/ExampleRole"
      },
      "Action": "kms:Decrypt",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "cloudformation.us-east-1.amazonaws.com"
        }
      }
    },
    {
      "Sid": "AllowHooksServiceDescribeKey",
      "Effect": "Allow",
      "Principal": {
        "Service": "hooks.cloudformation.amazonaws.com"
      },
      "Action": "kms:DescribeKey",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "111122223333"
        },
        "StringLike": {
          "aws:SourceArn": "arn:aws-cn:cloudformation:*:111122223333:hook/*"
        }
      }
    },
    {
      "Sid": "AllowHooksService",
      "Effect": "Allow",
      "Principal": {
        "Service": "hooks.cloudformation.amazonaws.com"
      },
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "111122223333",
          "kms:EncryptionContext:aws:cloudformation:hooks:service": "hooks.cloudformation.amazonaws.com",
          "kms:EncryptionContext:aws:cloudformation:account-id": "111122223333"
        },
        "StringLike": {
          "aws:SourceArn": "arn:aws-cn:cloudformation:*:111122223333:hook/*",
          "kms:EncryptionContext:aws:cloudformation:arn": "arn:aws-cn:cloudformation:*:111122223333:hook/*"
        }
      }
    }
  ]
}

This policy grants permissions to both IAM roles (first three statements) and the CloudFormation Hooks service (last two statements). The kms:ViaService condition key ensures the KMS key can only be used through CloudFormation, preventing direct KMS API calls. The key operations are:

  • kms:DescribeKey – Validates key properties and metadata. This operation is in separate statements because it cannot be used with encryption context conditions.

  • kms:GenerateDataKey – Generates data encryption keys for encrypting annotations before storage. This operation includes encryption context conditions for scoped access control.

  • kms:Decrypt – Decrypts previously encrypted annotations data. For IAM roles, this includes the kms:ViaService condition. For the service principal, this includes encryption context conditions.

The aws:SourceAccount and aws:SourceArn condition keys provide the primary protection against confused deputy attacks. The encryption context conditions provide additional validation layers. For more information, see Using aws:SourceArn or aws:SourceAccount condition keys in the Amazon Key Management Service Developer Guide.

Important

Hook execution roles do not need Amazon KMS permissions. The CloudFormation Hooks service principal performs all Amazon KMS operations.

KMS permissions for SetTypeConfiguration API

During the SetTypeConfiguration API call, CloudFormation validates user permissions to encrypt annotations data with the specified Amazon KMS key. Add the following IAM policy to the user or role that will configure encryption using the SetTypeConfiguration API. Replace arn:aws-cn:kms:us-east-1:123456789012:key/abc-123 with the ARN of your customer managed key.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudformation:SetTypeConfiguration",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "kms:DescribeKey",
      "Resource": "arn:aws-cn:kms:us-east-1:123456789012:key/abc-123"
    },
    {
      "Effect": "Allow",
      "Action": "kms:GenerateDataKey",
      "Resource": "arn:aws-cn:kms:us-east-1:123456789012:key/abc-123",
      "Condition": {
        "StringEquals": {
          "kms:EncryptionContext:aws:cloudformation:hooks:service": "hooks.cloudformation.amazonaws.com",
          "kms:EncryptionContext:aws:cloudformation:account-id": "123456789012"
        },
        "StringLike": {
          "kms:EncryptionContext:aws:cloudformation:arn": "arn:aws-cn:cloudformation:*:123456789012:hook/*"
        }
      }
    }
  ]
}

KMS permissions for GetHookResult API

To call GetHookResult for Hooks that use your customer managed key, users must have kms:Decrypt permission for that key. Add the following IAM policy to the user or role that will call GetHookResult. Replace arn:aws-cn:kms:us-east-1:123456789012:key/abc-123 with the ARN of your customer managed key.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudformation:GetHookResult",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws-cn:kms:us-east-1:123456789012:key/abc-123"
    }
  ]
}