Required AWS KMS key policy for use with encrypted volumes
Amazon EC2 Auto Scaling uses service-linked roles to delegate permissions to other AWS services. Amazon EC2 Auto Scaling service-linked roles are predefined and include permissions that Amazon EC2 Auto Scaling requires to call other AWS services on your behalf. The predefined permissions also include access to your AWS managed keys. However, they do not include access to your customer managed keys, allowing you to maintain full control over these keys.
This topic describes how to set up the key policy that you need to launch Auto Scaling instances when you specify a customer managed key for Amazon EBS encryption.
Note
Amazon EC2 Auto Scaling does not need additional authorization to use the default AWS managed key to protect the encrypted volumes in your account.
Contents
Overview
The following AWS KMS keys can be used for Amazon EBS encryption when Amazon EC2 Auto Scaling launches instances:
-
AWS managed key – An encryption key in your account that Amazon EBS creates, owns, and manages. This is the default encryption key for a new account. The AWS managed key is used for encryption unless you specify a customer managed key.
-
Customer managed key – A custom encryption key that you create, own, and manage. For more information, see Creating keys in the AWS Key Management Service Developer Guide.
Note: The key must be symmetric. Amazon EBS does not support asymmetric customer managed keys.
You configure customer managed keys when creating encrypted snapshots or a launch template that specifies encrypted volumes, or enabling encryption by default.
Configure key policies
Your KMS keys must have a key policy that allows Amazon EC2 Auto Scaling to launch instances with Amazon EBS volumes encrypted with a customer managed key.
Use the examples on this page to configure a key policy to give Amazon EC2 Auto Scaling access to your customer managed key. You can modify the customer managed key's key policy either when the key is created or at a later time.
You must, at minimum, add two policy statements to your key policy for it to work with Amazon EC2 Auto Scaling.
-
The first statement allows the IAM identity specified in the
Principal
element to use the customer managed key directly. It includes permissions to perform the AWS KMSEncrypt
,Decrypt
,ReEncrypt*
,GenerateDataKey*
, andDescribeKey
operations on the key. -
The second statement allows the IAM identity specified in the
Principal
element to use theCreateGrant
operation to generate grants that delegate a subset of its own permissions to AWS services that are integrated with AWS KMS or another principal. This allows them to use the key to create encrypted resources on your behalf.
When you add the new policy statements to your key policy, do not change any existing statements in the policy.
For each of the following examples, arguments that must be replaced, such as a key
ID or the name of a service-linked role, are shown as user placeholder
text
. In most cases, you can replace the name of the
service-linked role with the name of an Amazon EC2 Auto Scaling service-linked role.
For more information, see the following resources:
-
To create a key with the AWS CLI, see create-key.
-
To update a key policy with the AWS CLI, see put-key-policy.
-
To find a key ID and Amazon Resource Name (ARN), see Finding the key ID and ARN in the AWS Key Management Service Developer Guide.
-
For information about Amazon EC2 Auto Scaling service-linked roles, see Service-linked roles for Amazon EC2 Auto Scaling.
-
For information about Amazon EBS encryption and KMS generally, Amazon EBS encryption in the Amazon EBS User Guide and the AWS Key Management Service Developer Guide.
Example 1: Key policy sections that allow access to the customer managed key
Add the following two policy statements to the key policy of the customer managed key, replacing the example ARN with the ARN of the appropriate service-linked role that is allowed access to the key. In this example, the policy sections give the service-linked role named AWSServiceRoleForAutoScaling permissions to use the customer managed key.
{ "Sid": "Allow service-linked role use of the customer managed key", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::
account-id
:role/aws-service-role/autoscaling.amazonaws.com/AWSServiceRoleForAutoScaling
" ] }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" }
{ "Sid": "Allow attachment of persistent resources", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::
account-id
:role/aws-service-role/autoscaling.amazonaws.com/AWSServiceRoleForAutoScaling
" ] }, "Action": [ "kms:CreateGrant" ], "Resource": "*", "Condition": { "Bool": { "kms:GrantIsForAWSResource": true } } }
Example 2: Key policy sections that allow cross-account access to the customer managed key
If you create a customer managed key in a different account than the Auto Scaling group, you must use a grant in combination with the key policy to allow cross-account access to the key.
There are two steps that must be completed in the following order:
-
First, add the following two policy statements to the customer managed key's key policy. Replace the example ARN with the ARN of the other account, making sure to replace
111122223333
with the actual account ID of the AWS account that you want to create the Auto Scaling group in. This allows you to give an IAM user or role in the specified account permission to create a grant for the key using the CLI command that follows. However, this does not by itself give any users access to the key.{ "Sid": "Allow external account
111122223333
use of the customer managed key", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333
:root" ] }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": "*" }{ "Sid": "Allow attachment of persistent resources in external account
111122223333
", "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333
:root" ] }, "Action": [ "kms:CreateGrant" ], "Resource": "*" } -
Then, from the account that you want to create the Auto Scaling group in, create a grant that delegates the relevant permissions to the appropriate service-linked role. The
Grantee Principal
element of the grant is the ARN of the appropriate service-linked role. Thekey-id
is the ARN of the key.The following is an example create-grant CLI command that gives the service-linked role named AWSServiceRoleForAutoScaling in account
111122223333
permissions to use the customer managed key in account444455556666
.aws kms create-grant \ --region
us-west-2
\ --key-idarn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
\ --grantee-principal arn:aws:iam::111122223333
:role/aws-service-role/autoscaling.amazonaws.com/AWSServiceRoleForAutoScaling
\ --operations "Encrypt" "Decrypt" "ReEncryptFrom" "ReEncryptTo" "GenerateDataKey" "GenerateDataKeyWithoutPlaintext" "DescribeKey" "CreateGrant"For this command to succeed, the user making the request must have permissions for the
CreateGrant
action.The following example IAM policy allows an IAM identity (user or role) in account
111122223333
to create a grant for the customer managed key in account444455556666
.{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCreationOfGrantForTheKMSKeyinExternalAccount
444455556666
", "Effect": "Allow", "Action": "kms:CreateGrant", "Resource": "arn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
" } ] }For more information about creating a grant for a KMS key in a different AWS account, see Grants in AWS KMS in the AWS Key Management Service Developer Guide.
Important
The service-linked role name specified as the grantee principal must be the name of an existing role. After creating the grant, to ensure that the grant allows Amazon EC2 Auto Scaling to use the specified KMS key, do not delete and recreate the service-linked role.
Edit key policies in the AWS KMS console
The examples in the previous sections show only how to add statements to a key policy, which is just one way of changing a key policy. The easiest way to change a key policy is to use the AWS KMS console's default view for key policies and make an IAM identity (user or role) one of the key users for the appropriate key policy. For more information, see Using the AWS Management Console default view in the AWS Key Management Service Developer Guide.
Important
Be cautious. The console's default view policy statements include permissions
to perform AWS KMS Revoke
operations on the customer managed key. If you give
an AWS account access to a customer managed key in your account, and you accidentally
revoke the grant that gave them this permission, external users can no longer
access their encrypted data or the key that was used to encrypt their data.