Rotating Amazon KMS keys - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Rotating Amazon KMS keys

Cryptographic best practices discourage extensive reuse of encryption keys. To create new cryptographic material for your KMS keys, you can create new KMS keys, and then change your applications or aliases to use the new KMS keys. Or, you can enable automatic key rotation for an existing KMS key.

When you enable automatic key rotation for a customer managed key, Amazon KMS generates new cryptographic material for the KMS key every year. Amazon KMS also saves the KMS key's older cryptographic material in perpetuity so it can be used to decrypt data that the KMS key encrypted. Amazon KMS does not delete any rotated key material until you delete the KMS key.

Key rotation changes only the KMS key's key material, which is the cryptographic material that is used in encryption operations. The KMS key is the same logical resource, regardless of whether or how many times its key material changes. The properties of the KMS key do not change, as shown in the following image.

Automatic key rotation has the following benefits:

  • The properties of the KMS key, including its key ID, key ARN, region, policies, and permissions, do not change when the key is rotated.

  • You do not need to change applications or aliases that refer to the key ID or key ARN of the KMS key.

  • After you enable key rotation, Amazon KMS rotates the KMS key automatically every year. You don't need to remember or schedule the update.

However, automatic key rotation has no effect on the data that the KMS key protects. It does not rotate the data keys that the KMS key generated or re-encrypt any data protected by the KMS key, and it will not mitigate the effect of a compromised data key.

You might decide to create a new KMS key and use it in place of the original KMS key. This has the same effect as rotating the key material in an existing KMS key, so it's often thought of as manually rotating the key. Manual rotation is a good choice when you want to control the key rotation schedule. It also provides a way to rotate KMS keys that are not eligible for automatic key rotation, including asymmetric KMS keys, KMS keys in custom key stores, and KMS keys with imported key material.

Key rotation and pricing

Rotating customer managed keys might result in extra monthly charges. For details, see Amazon Key Management Service Pricing. For more detailed information about key material and rotation, see Amazon Key Management Service Cryptographic Details.

How automatic key rotation works

Key rotation in Amazon KMS is a cryptographic best practice that is designed to be transparent and easy to use. Amazon KMS supports optional automatic key rotation only for customer managed keys.

  • Managing key material. Amazon KMS retains all key material for a KMS key, even if key rotation is disabled. Key material is deleted only when the KMS key is deleted. When you use a KMS key to encrypt, Amazon KMS uses the current key material. When you use the KMS key to decrypt, Amazon KMS uses the key material that was used to encrypt.

  • Enable and disable key rotation. Automatic key rotation is disabled by default on customer managed keys. When you enable (or re-enable) automatic key rotation, Amazon KMS automatically rotates the KMS key 365 days after the enable date and every 365 days thereafter.

  • Disabled KMS keys. While a KMS key is disabled, Amazon KMS does not rotate it. However, the key rotation status does not change, and you cannot change it while the KMS key is disabled. When the KMS key is re-enabled, if the key material is more than 365 days old, Amazon KMS rotates it immediately and every 365 days thereafter. If the key material is less than 365 days old, Amazon KMS resumes the original key rotation schedule.

  • KMS keys pending deletion. While a KMS key is pending deletion, Amazon KMS does not rotate it. The key rotation status is set to false and you cannot change it while deletion is pending. If deletion is canceled, the previous key rotation status is restored. If the key material is more than 365 days old, Amazon KMS rotates it immediately and every 365 days thereafter. If the key material is less than 365 days old, Amazon KMS resumes the original key rotation schedule.

  • Amazon managed keys. You cannot manage key rotation for Amazon managed keys. Amazon KMS automatically rotates Amazon managed keys every three years (1095 days).

  • Amazon owned keys. You cannot manage key rotation for Amazon owned keys. The key rotation strategy for an Amazon owned key is determined by the Amazon service that creates and manages the key. For details, see the Encryption at Rest topic in the user guide or developer guide for the service.

  • Amazon services. You can enable automatic key rotation on the customer managed keys that you use for server-side encryption in Amazon services. The annual rotation is transparent and compatible with Amazon services.

  • Multi-Region keys. You can enable and disable automatic key rotation for multi-Region keys. You set the property only on the primary key. When Amazon KMS synchronizes the keys, it copies the property setting from the primary key to its replica keys. When the key material of the primary key is rotated, Amazon KMS automatically copies that key material to all of its replica keys. For details, see Rotating multi-Region keys.

  • Monitoring key rotation. When Amazon KMS automatically rotates the key material for an Amazon managed key or customer managed key, it writes a KMS CMK Rotation event to Amazon CloudWatch Events and a RotateKey event to your Amazon CloudTrail log. You can use these records to verify that the KMS key was rotated.

  • Unsupported KMS key types. Automatic key rotation is not supported on the following types of KMS keys, but you can rotate these KMS keys manually.

  • Eventual consistency. Automatic key rotation is subject to the same eventual consistency effects as other Amazon KMS management operations. There might be a slight delay before the new key material is available throughout Amazon KMS. However, rotating key material does not cause any interruption or delay in cryptographic operations. The current key material is used in cryptographic operations until the new key material is available throughout Amazon KMS. When key material for a multi-Region key is automatically rotated, Amazon KMS uses the current key material until the new key material is available in all Regions with a related multi-Region key.

How to enable and disable automatic key rotation

You can use the Amazon KMS console or the Amazon KMS API to enable and disable automatic key rotation, and view the rotation status of any customer managed key

When you enable automatic key rotation, Amazon KMS rotates the KMS key 365 days after the enable date and every 365 days thereafter.

Enabling and disabling key rotation (console)

  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys. (You cannot enable or disable rotation of Amazon managed keys. They are automatically rotated every three years.)

  4. Choose the alias or key ID of a KMS key.

  5. Choose the Key rotation tab.

    The Key rotation tab only appears on the detail page of symmetric KMS keys with key material that Amazon KMS generated (the Origin is AWS_KMS). You cannot automatically rotate asymmetric KMS keys, KMS keys with imported key material, or KMS keys in custom key stores. However, you can rotate them manually.

  6. Select or clear the Automatically rotate this KMS key every year check box.

    Note

    If a KMS key is disabled or pending deletion, the Automatically rotate this KMS key every year check box is cleared, and you cannot change it. The key rotation status is restored when you enable the KMS key or cancel deletion. For details, see How automatic key rotation works and Key states of Amazon KMS keys.

  7. Choose Save.

Enabling and disabling key rotation (Amazon KMS API)

You can use the Amazon Key Management Service (Amazon KMS) API to enable and disable automatic key rotation, and view the current rotation status of any customer managed key These examples use the Amazon Command Line Interface (Amazon CLI), but you can use any supported programming language.

The EnableKeyRotation operation enables automatic key rotation for the specified KMS key. The DisableKeyRotation operation disables it. To identify the KMS key in these operations, use its key ID or key ARN. By default, key rotation is disabled for customer managed keys.

The following example enables key rotation on the specified symmetric KMS key and uses the GetKeyRotationStatus operation to see the result. Then, it disables key rotation and, again, uses GetKeyRotationStatus to see the change.

$ aws kms enable-key-rotation --key-id 1234abcd-12ab-34cd-56ef-1234567890ab $ aws kms get-key-rotation-status --key-id 1234abcd-12ab-34cd-56ef-1234567890ab { "KeyRotationEnabled": true } $ aws kms disable-key-rotation --key-id 1234abcd-12ab-34cd-56ef-1234567890ab $ aws kms get-key-rotation-status --key-id 1234abcd-12ab-34cd-56ef-1234567890ab { "KeyRotationEnabled": false }

Rotating keys manually

You might want to create a new KMS key and use it in place of a current KMS key instead of enabling automatic key rotation. When the new KMS key has different cryptographic material than the current KMS key, using the new KMS key has the same effect as changing the key material in an existing KMS key. The process of replacing one KMS key with another is known as manual key rotation.

You might prefer to rotate keys manually so you can control the rotation frequency. It's also a good solution for KMS keys that are not eligible for automatic key rotation, such as asymmetric KMS keys, KMS keys in custom key stores and KMS keys with imported key material.

Note

When you begin using the new KMS key, be sure to keep the original KMS key enabled so that Amazon KMS can decrypt data that the original KMS key encrypted.

Because the new KMS key is a different resource from the current KMS key, it has a different key ID and ARN. When you change KMS keys, you need to update references to the KMS key ID or ARN in your applications. Aliases, which associate a friendly name with a KMS key, make this process easier. Use an alias to refer to a KMS key in your applications. Then, when you want to change the KMS key that the application uses, change the target KMS key of the alias. For details, see Using aliases in your applications.

To update the target KMS key of an alias, use UpdateAlias operation in the Amazon KMS API. For example, this command updates the TestKey alias to point to a new KMS key. Because the operation does not return any output, the example uses the ListAliases operation to show that the alias is now associated with a different KMS key and the LastUpdatedDate field is updated.

$ aws kms list-aliases { "Aliases": [ { "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/TestKey", "AliasName": "alias/TestKey", "TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "CreationDate": 1521097200.123, "LastUpdatedDate": 1521097200.123 }, ] } $ aws kms update-alias --alias-name alias/TestKey --target-key-id 0987dcba-09fe-87dc-65ba-ab0987654321 $ aws kms list-aliases { "Aliases": [ { "AliasArn": "arn:aws:kms:us-west-2:111122223333:alias/TestKey", "AliasName": "alias/TestKey", "TargetKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321", "CreationDate": 1521097200.123, "LastUpdatedDate": 1604958290.722 }, ] }