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.

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. This example uses 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    
}