How can I manually rotate customer managed keys in AWS KMS?

Resolution

Use manual key rotation to create a new AWS KMS key to replace the current key.

To rotate your current AWS KMS key to a new key, complete the following steps:

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

1. Create an alias named application-current, and then attach it to the existing AWS KMS key:

   acbc32cf8f6f:~ $$ aws kms create-alias --alias-name alias/application-current --target-key-id 0987dcba-09fe-87dc-65ba-ab0987654321acbc32cf8f6f:~ $$ aws kms list-aliases --output text | grep application
   ALIASES    arn:aws:kms:eu-west-1:123456789012:alias/application-current    alias/application-current    0987dcba-09fe-87dc-65ba-ab0987654321

2. Create a new alias named application-20180606 that includes the rotation date as part of its name for the AWS KMS key to be rotated. In the following example, the rotation date is 2018-06-06. The AWS KMS key has two aliases:

   acbc32cf8f6f:~ $$ aws kms create-alias --alias-name alias/application-20180606 --target-key-id 0987dcba-09fe-87dc-65ba-ab0987654321acbc32cf8f6f:~ $$ aws kms list-aliases --output text | grep application
   ALIASES    arn:aws:kms:eu-west-1:123456789012:alias/application-20180606    alias/application-20180606    0987dcba-09fe-87dc-65ba-ab0987654321
   ALIASES    arn:aws:kms:eu-west-1:123456789012:alias/application-current     alias/application-current     0987dcba-09fe-87dc-65ba-ab0987654321

3. Create a new AWS KMS key similar to the following:

   acbc32cf8f6f:~ $$ aws kms create-key{
       "KeyMetadata": {
           "Origin": "AWS_KMS",
           "KeyId": "9bf76697-5b41-4caf-9fe1-e23bbe20f858",
           "Description": "",
           "KeyManager": "CUSTOMER",
           "Enabled": true,
           "KeyUsage": "ENCRYPT_DECRYPT",
           "KeyState": "Enabled",
           "CreationDate": 1528289057.531,
           "Arn": "arn:aws:kms:eu-west-1:123456789012:key/9bf76697-5b41-4caf-9fe1-e23bbe20f858",
           "AWSAccountId": "123456789012"
       }
   }

4. Associate the application-current alias to the new AWS KMS key. Replace NEW_KMS_KEY_ID with your newly created key ID from step 3:

   $$ aws kms update-alias --alias-name alias/application-current --target-key-id NEW_KMS_KEY_ID

5. You have both the new and the current AWS KMS keys. Use the application-current key to encrypt data. When AWS KMS decrypts the data, the AWS KMS key is automatically resolved:

   acbc32cf8f6f:~ $$ aws kms list-aliases --output text | grep applicationALIASES    arn:aws:kms:eu-west-1:123456789012:alias/application-20180606    alias/application-20180606    0987dcba-09fe-87dc-65ba-ab0987654321
   ALIASES    arn:aws:kms:eu-west-1:123456789012:alias/application-current     alias/application-current     9bf76697-5b41-4caf-9fe1-e23bbe20f858

   Keep the current AWS KMS key as a backup to track when key rotation occurred or to roll back changes.
   Note: Users with an existing key must copy that policy to the application-current key.

6. Open the AWS KMS console and choose Customer managed keys.

7. In Alias, choose the current key.

8. In Key Policy, choose Switch to policy view.

9. Copy the current policy, and then choose Customer managed keys.

10. In Alias, choose application-current.

11. In Key Policy, choose Edit. Delete the application-current policy and paste the current policy. Then, choose Save Changes.

Related information

How do I import my keys into AWS Key Management Service?