Rotating AWS KMS keys

To create new cryptographic material for your customer managed keys, you can create new KMS keys, and then change your applications or aliases to use the new KMS keys. Or, you can rotate the key material associated with an existing KMS key by enabling automatic key rotation or performing on-demand rotation.

By default, when you enable automatic key rotation for a KMS key, AWS KMS generates new cryptographic material for the KMS key every year. You can also specify a custom rotation-period to define the number of days after you enable automatic key rotation that AWS KMS will rotate your key material, and the number of days between each automatic rotation thereafter. If you need to immediately initiate key material rotation, you can perform on-demand rotation, regardless of whether or not automatic key rotation is enabled. On-demand rotations do not change existing automatic rotation schedules.

AWS KMS saves all previous versions of the cryptographic material in perpetuity so you can decrypt any data encrypted with that KMS key. AWS KMS does not delete any rotated key material until you delete the KMS key. You can track the rotation of key material for your KMS keys in Amazon CloudWatch, AWS CloudTrail, and the AWS Key Management Service console. You can also use GetKeyRotationStatus operation to verify whether automatic rotation is enabled for a KMS key and identify any in progress on-demand rotations. You can use ListKeyRotations operation to view the details of completed rotations.

When you use a rotated KMS key to encrypt data, AWS KMS uses the current key material. When you use the rotated KMS key to decrypt ciphertext, AWS KMS uses the version of the key material that was used to encrypt it. You cannot select a particular version of the key material for decrypt operations, AWS KMS automatically chooses the correct version. Because AWS KMS transparently decrypts with the appropriate key material, you can safely use a rotated KMS key in applications and AWS services without code changes.

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.

AWS KMS supports automatic and on-demand key rotation only for symmetric encryption KMS keys with key material that AWS KMS creates. Automatic rotation is optional for customer managed KMS keys. AWS KMS always rotates the key material for AWS managed KMS keys every year. Rotation of AWS owned KMS keys is managed by the AWS service that owns the key.

Note

The rotation period for AWS managed keys changed in May 2022. For details, see AWS managed keys.

Key rotation changes only the key material, which is the cryptographic secret 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.

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 rotate KMS keys that are not eligible for automatic key rotation, including asymmetric KMS keys, HMAC KMS keys, KMS keys in custom key stores, and KMS keys with imported key material.

Key rotation and pricing

AWS KMS charges a monthly fee for first and second rotation of key material maintained for your KMS key. This price increase is capped at the second rotation, and any subsequent rotations will not be billed. For details, see AWS Key Management Service Pricing.

Note

You can use the AWS Cost Explorer Service to view a breakdown of your key storage charges. For example, you can filter your view to see the total charges for keys billed as current and rotated KMS keys by specifying $REGION-KMS-Keys for the Usage Type and grouping the data by API Operation.

You might still see instances of the legacy Unknown API operation for historical dates.

Key rotation and quotas

Each KMS key counts as one key when calculating key resource quotas, regardless of the number of rotated key material versions.

For detailed information about key material and rotation, see AWS Key Management Service Cryptographic Details.

Why rotate KMS keys?

Cryptographic best practices discourage extensive reuse of keys that encrypt data directly, such as the data keys that AWS KMS generates. When 256-bit data keys encrypt millions of messages they can become exhausted and begin to produce ciphertext with subtle patterns that clever actors can exploit to discover the bits in the key. To avoid this key exhaustion, it's best to use data keys once, or just a few times, which effectively rotates the key material.

However, KMS keys are most often used as wrapping keys, also known as key-encryption keys. Instead of encrypting data, wrapping keys encrypt the data keys that encrypt your data. As such, they are used far less often than data keys, and are almost never reused enough to risk key exhaustion.

Despite this very low exhaustion risk, you might be required to rotate your KMS keys due to business or contract rules or government regulations. When you are compelled to rotate KMS keys, we recommend that you use automatic key rotation where it is supported, and manual key rotation when automatic key rotation is not supported.

You might consider performing on-demand rotations to demonstrate key material rotation capabilities or to validate automation scripts. We recommend using on-demand rotations for unplanned rotations, and using automatic key rotation with with a custom rotation period whenever possible.

How key rotation works

Key rotation in AWS KMS is a designed to be transparent and easy to use. AWS KMS supports optional automatic and on-demand key rotation only for customer managed keys.

Automatic key rotation

AWS KMS rotates the KMS key automatically on the next rotation date defined by your rotation period. You don't need to remember or schedule the update.

On-demand rotation

Immediately initiate rotation of the key material associated with your KMS key, regardless of whether or not automatic key rotation is enabled.

Managing key material

AWS KMS retains all key material for a KMS key, even if key rotation is disabled. AWS KMS deletes key material only when you delete the KMS key.

Using key material

When you use a rotated KMS key to encrypt data, AWS KMS uses the current key material. When you use the rotated KMS key to decrypt ciphertext, AWS KMS uses the same version of the key material that was used to encrypt it. You cannot select a particular version of the key material for decrypt operations, AWS KMS automatically chooses the correct version.

Rotation period

Rotation period defines the number of days after you enable automatic key rotation that AWS KMS will rotate your key material, and the number of days between each automatic key rotation thereafter. If you do not specify a value for RotationPeriodInDays when you enable automatic key rotation, the default value is 365 days.

You can use the kms:RotationPeriodInDays condition key to further constrain the values that principals can specify in the RotationPeriodInDays parameter.

Rotation date

AWS KMS automatically rotates the KMS key on the rotation date defined by your rotation period. The default rotation period is 365 days.

Customer managed keys

Because automatic key rotation is optional on customer managed keys and can be enabled and disabled at any time, the rotation date depends on the date that rotation was most recently enabled. The date can change if you modify the rotation period for a key that you previously enabled automatic key rotation on. The rotation date can change many times over the life of the key.

For example, if you create a customer managed key on January 1, 2022, and enable automatic key rotation with the default rotation period of 365 days on March 15, 2022, AWS KMS rotates the key material on March 15, 2023, March 15, 2024, and every 365 days thereafter.

The following examples assume that automatic key rotation was enabled with the default rotation period of 365 days. These examples demonstrate special cases that might impact a key's rotation period.

• Disable key rotation — If you disable automatic key rotation at any point, the KMS key continues to use the version of the key material it was using when rotation was disabled. If you enable automatic key rotation again, AWS KMS rotates the key material based on the new rotation-enable date.

• Disabled KMS keys — While a KMS key is disabled, AWS 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 past its last scheduled rotation date , AWS KMS rotates it immediately. If the key material has not missed its last scheduled rotation date, AWS KMS resumes the original key rotation schedule.

• KMS keys pending deletion — While a KMS key is pending deletion, AWS 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 past its last scheduled rotation date, AWS KMS rotates it immediately. If the key material has not missed its last scheduled rotation date, AWS KMS resumes the original key rotation schedule.

AWS managed keys

AWS KMS automatically rotates AWS managed keys every year (approximately 365 days). You cannot enable or disable key rotation for AWS managed keys.

The key material for an AWS managed key is first rotated one year after its creation date, and every year (approximately 365 days from the last rotation) thereafter.

Note

In May 2022, AWS KMS changed the rotation schedule for AWS managed keys from every three years (approximately 1,095 days) to every year (approximately 365 days).

New AWS managed keys are automatically rotated one year after they are created, and approximately every year thereafter.

Existing AWS managed keys are automatically rotated one year after their most recent rotation, and every year thereafter.

AWS owned keys

You cannot enable or disable key rotation for AWS owned keys. The key rotation strategy for an AWS owned key is determined by the AWS 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.

Supported KMS key types

Automatic key rotation is supported only on symmetric encryption KMS keys with key material that AWS KMS generates (Origin = AWS_KMS).

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

• Asymmetric KMS keys

• HMAC KMS keys

• KMS keys in custom key stores

• KMS keys with imported key material

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 AWS 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, AWS KMS automatically copies that key material to all of its replica keys. For details, see Rotating multi-Region keys.

AWS services

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

Monitoring key rotation

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

You can use the AWS Key Management Service console to view the number of remaining on-demand rotations and a list of all completed key material rotations for a KMS key.

You can use ListKeyRotations operation to view the details of completed rotations.

Eventual consistency

Key rotation is subject to the same eventual consistency effects as other AWS KMS management operations. There might be a slight delay before the new key material is available throughout AWS 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 AWS KMS. When key material for a multi-Region key is automatically rotated, AWS 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

By default, when you enable automatic key rotation for a KMS key, AWS KMS generates new cryptographic material for the KMS key every year. You can also specify a custom rotation-period to define the number of days after you enable automatic key rotation that AWS KMS will rotate your key material, and the number of days between each automatic rotation thereafter.

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.

• Rotating key material does not affect the use of the KMS key in any AWS service.

• After you enable key rotation, AWS KMS rotates the KMS key automatically on the next rotation date defined by your rotation period. You don't need to remember or schedule the update.

Authorized users can use the AWS KMS console and the AWS KMS API to enable and disable automatic key rotation and view the key rotation status.

Topics

• Enabling and disabling automatic key rotation (console)
• Enabling and disabling automatic key rotation (AWS KMS API)

Enabling and disabling automatic key rotation (console)

1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms.

2. To change the AWS 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 AWS managed keys. They are automatically rotated every year.)

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

5. Choose the Key rotation tab.

   The Key rotation tab appears only on the detail page of symmetric encryption KMS keys with key material that AWS KMS generated (the Origin is AWS_KMS), including multi-Region symmetric encryption KMS keys.

   You cannot automatically rotate asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in custom key stores. However, you can rotate them manually.

6. In the Automatic key rotation section, choose Edit.

7. For Key rotation, select Enable.

   Note

   If a KMS key is disabled or pending deletion, AWS KMS does not rotate the key material and you cannot update the automatic key rotation status or rotation period. Enable the KMS key or cancel deletion to update the automatic key rotation configuration. For details, see How key rotation works and Key states of AWS KMS keys.

8. (Optional) Type a rotation period between 90 and 2560 days. The default value is 365 days. If you do not specify a custom rotation period, AWS KMS will rotate the key material every year.

   You can use the kms:RotationPeriodInDays condition key to limit the values that principals can specify for the rotation period.

9. Choose Save.

Enabling and disabling automatic key rotation (AWS KMS API)

You can use the AWS Key Management Service (AWS KMS) API to enable and disable automatic key rotation, and view the current rotation status of any customer managed key. These examples use the AWS Command Line Interface (AWS 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.

You can use the kms:RotationPeriodInDays condition key to limit the values that principals can specify for the RotationPeriodInDays parameter of an EnableKeyRotation request.

The following example enables key rotation with a rotation period of 180 days on the specified symmetric encryption 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 \
    --rotation-period-in-days 180

$ aws kms get-key-rotation-status --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyRotationEnabled": true,
    "RotationPeriodInDays": 180,
    "NextRotationDate": "2024-02-14T18:14:33.587000+00:00"
}

$ 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
{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyRotationEnabled": false
}
            

How to perform on-demand key rotation

You can perform on-demand rotation of the key material in customer managed KMS keys, regardless of whether or not automatic key rotation is enabled. Disabling automatic rotation (DisableKeyRotation) does not impact your ability to perform on-demand rotations, nor does it cancel any in progress on-demand rotations. On-demand rotations do not change existing automatic rotation schedules. For example, consider a KMS key that has automatic key rotation enabled with a rotation period of 730 days. If the key is scheduled to automatically rotate on April 14, 2024, and you perform an on-demand rotation on April 10, 2024, the key will automatically rotate, as scheduled, on April 14, 2024 and every 730 days thereafter.

You can perform on-demand key rotation a maximum of 10 times per KMS key. You can use the AWS KMS console to view the number of remaining on-demand rotations available for a KMS key.

On-demand key rotation is supported only on symmetric encryption KMS keys. You cannot perform on-demand rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in a custom key store. To perform on-demand rotation of a set of related multi-Region keys, invoke the on-demand rotation on the primary key.

Authorized users can use the AWS KMS console and the AWS KMS API to initiate on-demand key rotation and view the key rotation status.

Topics

• Initiating on-demand key rotation (console)
• Initiating on-demand key rotation (AWS KMS API)

Initiating on-demand key rotation (console)

1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms.

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

3. In the navigation pane, choose Customer managed keys. (You cannot perform on-demand rotation of AWS managed keys. They are automatically rotated every year.)

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

5. Choose the Key rotation tab.

   The Key rotation tab appears only on the detail page of symmetric encryption KMS keys with key material that AWS KMS generated (the Origin is AWS_KMS), including multi-Region symmetric encryption KMS keys.

   You cannot perform on-demand rotation of asymmetric KMS keys, HMAC KMS keys, KMS keys with imported key material, or KMS keys in custom key stores. However, you can rotate them manually.

6. In the On-demand key rotation section, choose Rotate key.

7. Read and consider the warning and the information about the number of remaining on-demand rotations for the key. If you decide that you do not want to proceed with the on-demand rotation, choose Cancel.

8. Choose Rotate key to confirm on-demand rotation.

   Note

   On-demand rotation is subject to the same eventual consistency effects as other AWS KMS management operations. There might be a slight delay before the new key material is available throughout AWS KMS. The banner at the top of the console notifies you when the on-demand rotation is complete.

Initiating on-demand key rotation (AWS KMS API)

You can use the AWS Key Management Service (AWS KMS) API to initiate on-demand key rotation, and view the current rotation status of any customer managed key. These examples use the AWS Command Line Interface (AWS CLI), but you can use any supported programming language.

The RotateKeyOnDemand operation immediately initiates on-demand key rotation for the specified KMS key. To identify the KMS key in these operations, use its key ID or key ARN.

The following example initiates on-demand key rotation on the specified symmetric encryption KMS key and uses the GetKeyRotationStatus operation to verify that the on-demand rotation is in progress. The OnDemandRotationStartDate in the kms:GetKeyRotationStatus response identifies the date and time that an in progress on-demand rotation was initiated.

$ aws kms rotate-key-on-demand --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"    
}

$ aws kms get-key-rotation-status --key-id 1234abcd-12ab-34cd-56ef-1234567890ab
{
    "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
    "KeyRotationEnabled": true,
    "NextRotationDate": "2024-03-14T18:14:33.587000+00:00",
    "OnDemandRotationStartDate": "2024-02-24T18:44:48.587000+00:00"
    "RotationPeriodInDays": 365    
}

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.

Manual rotation is a good choice when you want to rotate KMS keys that are not eligible for automatic key rotation, such as asymmetric KMS keys, HMAC 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 AWS KMS can decrypt data that the original KMS key encrypted.

When you rotate KMS keys manually, you also need to update references to the KMS key ID or key ARN in your applications. Aliases, which associate a friendly name with a KMS key, can 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, instead of editing your application code, change the target KMS key of the alias. For details, see Using aliases in your applications.

Note

Aliases that point to the latest version of a manually rotated KMS key are a good solution for the DescribeKey, Encrypt, GenerateDataKey, GenerateDataKeyPair, GenerateMac, and Sign operations. Aliases are not permitted in operations that manage KMS keys, such as DisableKey or ScheduleKeyDeletion.

When calling the Decrypt operation on manually rotated symmetric encryption KMS keys, omit the KeyId parameter from the command. AWS KMS automatically uses the KMS key that encrypted the ciphertext.

The KeyId parameter is required when calling Decrypt or Verify with an asymmetric KMS key, or calling VerifyMac with an HMAC KMS key. These requests fail when the value of the KeyId parameter is an alias that no longer points to the KMS key that performed the cryptographic operation, such as when a key is manually rotated. To avoid this error, you must track and specify the correct KMS key for each operation.

To change the target KMS key of an alias, use UpdateAlias operation in the AWS KMS API. For example, this command updates the alias/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. The ListAliases commands use the query parameter in the AWS CLI to get only the alias/TestKey alias.

$ aws kms list-aliases --query 'Aliases[?AliasName==`alias/TestKey`]'
{
    "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 --query 'Aliases[?AliasName==`alias/TestKey`]'
{
    "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
        },
    ]
}