How do I resolve the error I receive when I use AWS CloudFormation to create an AWS KMS key?

Short description

AWS KMS performs safety checks when you apply a key policy to your key. One safety check confirms that the principal in the key policy has the required permissions to perform the CreateKey and PutKeyPolicy API operations. This check makes sure that the AWS KMS key remains manageable.

Important: Make sure that the key policy that you create allows an appropriate AWS Identity and Access Management (IAM) principal to administer the AWS KMS key.

Resolution

Note: When you create an AWS CloudFormation stack, an IAM user or role is used to perform the CreateStack API operation. This user is also used to create resources specified in the AWS CloudFormation template.

Create an AWS KMS key

Complete the following steps:

1. Use AWS CloudFormation to create an AWS KMS key.
2. Choose an appropriate IAM user or role that you can use to manage your key in future.
3. Use the BypassPolicyLockoutSafetyCheck resource parameter after you include a valid administrative principal in the Allow statements with the kms:PutKeyPolicy action.

In the following example, the AWS CloudFormation stack is created by the IAM user arn:aws:iam::123456789012:user/Alice. The KeyAdmin role is designated as the key administrator. The IAM role KeyAdmin is allowed to modify the key policy when the key is created with a key policy in the following format:

{
    "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:role/KeyAdmin"
                    },
                    "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:role/KeyUser"
                    },
                    "Action": [
                        "kms:Encrypt",
                        "kms:Decrypt",
                        "kms:ReEncrypt*",
                        "kms:GenerateDataKey*",
                        "kms:DescribeKey"
                    ],
                    "Resource": "*"
                }
            ]
        }
    }
}

Important: If a valid principal isn't specified in your policy, then the BypassPolicyLockoutSafetyCheck might result in an unmanageable key. Make sure that you use a valid principal in your policies.

Set the principal key administrator

To set the principal key administrator from your federated identity provider, use the role session Amazon Resource Name (ARN). You can also use a specific administrative user's assume role session from your external identity provider as the principal for key management.

Example:

"Principal": { "AWS": "arn:aws:sts::123456789012:assumed-role/FederatedAccess/FederatedUsername" }

In the preceding example, the name of the IAM role is FederatedAccess, and the name of the federated user is FederatedUsername. This allows multiple users to use the same role while only trusted users can modify the key policy.

When you use the AWS CloudFormation service role to create the stack, you can set the principal as the service role ARN to avoid the error.

Example:

"Principal": { "AWS": "arn:aws:iam::123456789012:role/ServiceRoleName" }

In the preceding example, the name of the AWS CloudFormation service role is ServiceRoleName.

To set the AWS account root user as the principal key administrator, run the following command:

"Principal": { "AWS": "arn:aws:iam::123456789012:root" }

Note: If the principal key administrator is set to the root ARN, then make sure you have the correct permissions. The IAM user, role, or service role that creates the AWS CloudFormation stack must have the IAM permissions to perform the CreateKey and PutKeyPolicy API operations.

Important: When you set the principal key administrator to the root ARN, any principal in the account with sufficient IAM permissions can modify the key, not just the root user.

After you have a principal with the kms:PutKeyPolicy permission in the key policy, you can use AWS CloudFormation to create your AWS KMS key. Use the BypassPolicyLockoutSafetyCheck property in your AWS CloudFormation template.

Example:

myKMSKey:
  Type: 'AWS::KMS::Key'
  Properties:
    Description: This key is managed by the KeyAdmin role
    BypassPolicyLockoutSafetyCheck: true
    KeyPolicy:
      Version: 2012-10-17
      Id: key-policy-1
      Statement:
        - Sid: Allow administration of the key
          Effect: Allow
          Principal:
            AWS: 'arn:aws:iam::123456789012:role/KeyAdmin'
          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:role/KeyUser'
          Action:
            - 'kms:DescribeKey'
            - 'kms:Encrypt'
            - 'kms:Decrypt'
            - 'kms:ReEncrypt*'
            - 'kms:GenerateDataKey'
            - 'kms:GenerateDataKeyWithoutPlaintext'
          Resource: '*'
    EnableKeyRotation: true
    PendingWindowInDays: 30

Related information

AWS Key Management Service

KMS key access and permissions