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

Resolution

To manually 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

   Note: The new KMS key can't decrypt data encrypted with the old key. For data encrypted under symmetric encryption keys, AWS KMS extracts the AWS KMS key ID from the metadata. Then, AWS KMS uses that key to perform the decryption. Make sure that you don't specify a key ID in your decrypt request. If you use asymmetric AWS KMS keys, then you must manually specify the key ID in your decrypt requests. Make sure that you track the AWS KMS key that's used in encryption actions.

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

   To track when the key rotation occurred or to roll back changes, keep the current AWS KMS key as a backup.
   Note: If you have an existing key, then copy that policy to the application-current key.

6. Open the AWS KMS console, and then 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?