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

Short description

When you try to create and define a key, you might get the following error message:

"The new key policy will not allow you to update the key policy in the future."

The principal that you specified in the key policy must have the required permissions to perform the CreateKey and PutKeyPolicy API operations.

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 CloudFormation stack, CloudFormation assumes an IAM role to perform the CreateStack API operation. CloudFormation also uses the role to create the resources that you specified in the CloudFormation template.

Create an AWS KMS key

Complete the following steps:

1. Open the CloudFormation console.
2. Use the AWS::KMS::Key resource to create the AWS KMS key.
3. Choose an IAM user or role that you can use to manage your key.
4. Include an administrative principal in the Allow statements with the kms:PutKeyPolicy action.
5. Use the BypassPolicyLockoutSafetyCheck resource parameter.

In the following example, the KeyAdmin role can modify the key policy when the policy is 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 access for Key Administrators",
                    "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 policy statement:

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

Note: Replace FederatedAccess with your IAM role and FederatedUsername with your username.

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

Example policy statement:

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

Note: Replace ServiceRoleName with your service role.

To set the AWS account root user as the principal key administrator, include the following statement in your policy:

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

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

When there's principal with the kms:PutKeyPolicy permission in the key policy, you can use CloudFormation to create your AWS KMS key. Set the BypassPolicyLockoutSafetyCheck property to true in your CloudFormation template.

Example template:

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 access for Key Administrators
          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