# Rotate AWS KMS keys
To create new cryptographic material for your [customer managed keys](concepts.md#customer-mgn-key), 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](#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.
You can [track the rotation](#monitor-key-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](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html) operation to verify whether automatic rotation is enabled for a KMS key and identify any in progress on-demand rotations. You can use [ListKeyRotations](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyRotations.html) operation to view the details of completed rotations.
Key rotation changes only the *current key material*, which is the cryptographic secret that is used in encryption operations. When you use the rotated KMS key to decrypt ciphertext, AWS KMS uses the key material that was used to encrypt it. You cannot select a particular key material for decrypt operations, AWS KMS automatically chooses the correct key material. 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.
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.
![\[Key rotation process showing key material change while Key ID remains constant.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/key-rotation-auto.png)
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](rotate-keys-manually.md). Manual rotation is a good choice when you want to rotate KMS keys that are not eligible for automatic or on-demand key rotation, including [asymmetric KMS keys](symmetric-asymmetric.md), [HMAC KMS keys](hmac.md) and KMS keys in [custom key stores](key-store-overview.md#custom-key-store-overview).
**Note**
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. Key rotation will not mitigate the effect of a compromised data key.
**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](https://aws.amazon.com/kms/pricing/).
**Note**
You can use the [AWS Cost Explorer Service](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-what-is.html) 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](https://docs.aws.amazon.com/kms/latest/cryptographic-details/).
**Topics**
+ [
## Why rotate KMS keys?
](#rotating-kms-keys)
+ [
## How key rotation works
](#rotate-keys-how-it-works)
+ [
# Enable automatic key rotation
](rotating-keys-enable.md)
+ [
# Disable automatic key rotation
](rotating-keys-disable.md)
+ [
# Perform on-demand key rotation
](rotating-keys-on-demand.md)
+ [
# List rotations and key materials
](list-rotations.md)
+ [
# Rotate keys manually
](rotate-keys-manually.md)
+ [
# Change the primary key in a set of multi-Region keys
](multi-region-update.md)
## Why rotate KMS keys?
Cryptographic best practices discourage extensive reuse of keys that encrypt data directly, such as the [data keys](data-keys.md) 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. It's best to use data keys once, or just a few times, to mitigate this key exhaustion.
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, use on-demand rotation if automatic rotation is not supported, and manual key rotation when neither automatic nor on-demand key rotation is 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 a custom [rotation period](#rotation-period) whenever possible.
## How key rotation works
AWS KMS key rotation is designed to be transparent and easy to use. AWS KMS supports optional automatic and on-demand key rotation only for [customer managed keys](concepts.md#customer-mgn-key).
**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.
Automatic key rotation is supported only on symmetric encryption KMS keys with key material that AWS KMS generates (`AWS_KMS` origin).
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.
**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.
On-demand key rotation is supported on symmetric encryption KMS keys with key material that AWS KMS generates (`AWS_KMS` origin) and symmetric encryption KMS keys with imported key material (`EXTERNAL` origin).
**Manual rotation**
Neither automatic nor on-demand key rotation is supported for the following types of KMS keys, but you can [rotate these KMS keys manually](rotate-keys-manually.md).
+ [Asymmetric KMS keys](symmetric-asymmetric.md)
+ [HMAC KMS keys](hmac.md)
+ KMS keys in [custom key stores](key-store-overview.md#custom-key-store-overview)
**Managing key material**
AWS KMS retains all key material for a KMS key with `AWS_KMS` origin, even if key rotation is disabled. AWS KMS deletes key material only when you delete the KMS key.
You manage the key materials for symmetric encryption keys with `EXTERNAL` origin. You can delete any key material using the [DeleteImportedKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteImportedKeyMaterial.html) operation or set an expiration time when importing the material. The KMS key becomes unusable as soon as any of its materials expires or is deleted.
**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](conditions-kms.md#conditions-kms-rotation-period-in-days) condition key to further constrain the values that principals can specify in the `RotationPeriodInDays` parameter.
**Rotation date**
Rotation date reflects the date when the current key material for a KMS key was updated either as a result of automatic (scheduled) rotation or an on-demand key rotation.
**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](concepts.md#customer-mgn-key) 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](rotating-keys-disable.md) 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](concepts.md#aws-managed-key).
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.
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).
**AWS owned keys**
You cannot enable or disable key rotation for AWS owned keys. The [key rotation](#rotate-keys) 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.
**Rotating multi-Region keys**
The rotation behavior differs depending on whether the key material is generated by AWS KMS (`AWS_KMS` origin) or imported (`EXTERNAL` origin).
**Multi-Region keys with `AWS_KMS` origin**
You can enable and disable automatic rotation and perform on-demand rotation of the key material in symmetric encryption [multi-Region keys](multi-region-keys-overview.md) with `AWS_KMS` origin. Key rotation is a [shared property](multi-region-keys-overview.md#mrk-sync-properties) of multi-Region keys.
You enable and disable automatic key rotation only on the primary key. You initiate on-demand rotation only on the primary key.
+ When AWS KMS synchronizes the multi-Region keys, it copies the key rotation property setting from the primary key to all of its related replica keys.
+ When AWS KMS rotates the key material, it creates new key material for the primary key and then copies the new key material across Region boundaries to all related replica keys. The key material never leaves AWS KMS unencrypted. This step is carefully controlled to ensure that key material is fully synchronized before any key is used in a cryptographic operation.
+ AWS KMS does not encrypt any data with the new key material until that key material is available in the primary key and every one of its replica keys.
+ When you replicate a primary key that has been rotated, the new replica key has the current key material and all previous versions of the key material for its related multi-Region keys.
This pattern ensures that related multi-Region keys are fully interoperable. Any multi-Region key can decrypt any ciphertext encrypted by a related multi-Region key, even if the ciphertext was encrypted before the key was created.
**Multi-Region keys with `EXTERNAL` origin**
You can perform on-demand rotation of the key material in symmetric encryption [multi-Region keys](multi-region-keys-overview.md) with `EXTERNAL` origin. Key rotation is a [shared property](multi-region-keys-overview.md#mrk-sync-properties) of multi-Region keys.
You initiate on-demand rotation only on the primary key after importing the new key material into the primary key and each replica key.
+ When you import new key material into the primary key, AWS KMS copies the the key material identifier and the key material description from the primary key to all related replica keys. It does not copy the key material.
+ You must import the same key material into each replica key individually. After the key material has been imported into all related multi-Region keys, you can initiate on-demand rotation on the primary key. This ensures that AWS KMS does not encrypt any data with the new key material until that key material is available in the primary key and every one of its replica keys.
+ Each key material in the primary key or any replica key can expire or be deleted independently of other key material in the same key or any other related multi-region key.
**AWS services**
You can enable automatic key rotation on the [customer managed keys](concepts.md#customer-mgn-key) 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](concepts.md#aws-managed-key) or [customer managed key](concepts.md#customer-mgn-key), it writes a `KMS CMK Rotation` event to Amazon EventBridge and a [RotateKey event](ct-rotatekey.md) 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyRotations.html) 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.
# Enable 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](rotate-keys.md#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](concepts.md#key-id-key-id), [key ARN](concepts.md#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.
You can enable automatic key rotation in the AWS KMS console or by using the [EnableKeyRotation](https://docs.aws.amazon.com/kms/latest/APIReference/API_EnableKeyRotation.html) operation. To enable automatic key rotation, you need `kms:EnableKeyRotation` permissions. For more information about AWS KMS permissions, see the [Permissions reference](kms-api-permissions-reference.md).
## Using the AWS KMS 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](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**. (You cannot enable or disable rotation of AWS managed keys. They are automatically rotated every year.)
1. Choose the alias or key ID of a KMS key.
1. 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\$1KMS**), including [multi-Region](rotate-keys.md#multi-region-rotate) symmetric encryption KMS keys.
You cannot automatically rotate asymmetric KMS keys, HMAC KMS keys, KMS keys with [imported key material](importing-keys.md), or KMS keys in [custom key stores](key-store-overview.md#custom-key-store-overview). However, you can [rotate them manually](rotate-keys-manually.md).
1. In the **Automatic key rotation** section, choose **Edit**.
1. 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](rotate-keys.md#rotate-keys-how-it-works) and [Key states of AWS KMS keys](key-state.md).
1. (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](conditions-kms.md#conditions-kms-rotation-period-in-days) condition key to limit the values that principals can specify for the rotation period.
1. Choose **Save**.
## Using the AWS KMS API
You can use the [AWS Key Management Service (AWS KMS) API](https://docs.aws.amazon.com/kms/latest/APIReference/) to enable automatic key rotation and view the current rotation status of any customer managed key. These examples use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
The [EnableKeyRotation](https://docs.aws.amazon.com/kms/latest/APIReference/API_EnableKeyRotation.html) operation enables automatic key rotation for the specified KMS key. To identify the KMS key in this operation, use its [key ID](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN). By default, key rotation is disabled for customer managed keys.
You can use the [ kms:RotationPeriodInDays](conditions-kms.md#conditions-kms-rotation-period-in-days) 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html) operation to see the result.
```
$ 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"
}
```
# Disable automatic key rotation
After enabling automatic key rotation on a customer managed key, you can choose to disable it at any time.
If you disable automatic key rotation, 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.
Disabling automatic rotation does not impact your ability to [perform on-demand rotations](rotating-keys-on-demand.md), nor does it cancel any in progress on-demand rotations.
You can disable automatic key rotation in the AWS KMS console or by using the [DisableKeyRotation](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKeyRotation.html) operation. To disable automatic key rotation, you need `kms:DisableKeyRotation` permissions. For more information about AWS KMS permissions, see the [Permissions reference](kms-api-permissions-reference.md).
## Using the AWS KMS 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](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**. (You cannot enable or disable rotation of AWS managed keys. They are automatically rotated every year.)
1. Choose the alias or key ID of a KMS key.
1. 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\$1KMS**), including [multi-Region](rotate-keys.md#multi-region-rotate) symmetric encryption KMS keys.
You cannot automatically rotate asymmetric KMS keys, HMAC KMS keys, KMS keys with [imported key material](importing-keys.md), or KMS keys in [custom key stores](key-store-overview.md#custom-key-store-overview). However, you can [rotate them manually](rotate-keys-manually.md).
1. In the **Automatic key rotation** section, choose **Edit**.
1. For **Key rotation**, select **Disable**.
**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](rotate-keys.md#rotate-keys-how-it-works) and [Key states of AWS KMS keys](key-state.md).
1. Choose **Save**.
## Using the AWS KMS API
You can use the [AWS Key Management Service (AWS KMS) API](https://docs.aws.amazon.com/kms/latest/APIReference/) to disable automatic key rotation and view the current rotation status of any customer managed key. This example uses the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
The [DisableKeyRotation](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKeyRotation.html) operation disables automatic key rotation. To identify the KMS key in this operation, use its [key ID](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN). By default, key rotation is disabled for customer managed keys.
The following example disables automatic key rotation on the specified symmetric encryption KMS key and uses the [GetKeyRotationStatus](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html) operation to see the result.
```
$ 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
}
```
# 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKeyRotation.html)) 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 25 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](symm-asymm-choose-key-spec.md#symmetric-cmks). You cannot perform on-demand rotation of [asymmetric KMS keys](symmetric-asymmetric.md), [HMAC KMS keys](hmac.md), or KMS keys in a [custom key store](key-store-overview.md#custom-key-store-overview). To perform on-demand rotation of a set of related [multi-Region keys](rotate-keys.md#multi-region-rotate), invoke the on-demand rotation on the primary key.
Authorized users with `kms:RotateKeyOnDemand` and `kms:GetKeyRotationStatus` permissions can use the AWS KMS console and the AWS KMS API to initiate on-demand key rotation and view the key rotation status. Use [ListKeyRotations](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyRotations.html) to view completed rotations for a KMS key.
**Topics**
+ [
## Initiating on-demand key rotation (console)
](#rotate-on-demand-console)
+ [
## Initiating on-demand key rotation (AWS KMS API)
](#rotate-on-demand-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](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**. (You cannot perform on-demand rotation of AWS managed keys. They are automatically rotated every year.)
1. Choose the alias or key ID of a KMS key.
1. Choose the **Key material and rotations** tab.
The **Key material and rotations** tab appears only on the detail page of symmetric encryption KMS keys that support automatic or on-demand rotation. This includes KMS keys with key material that AWS KMS generated (**AWS\$1KMS** origin) and KMS keys with imported key material (**EXTERNAL** origin)
You cannot perform on-demand rotation of asymmetric KMS keys, HMAC KMS keys, or KMS keys in [custom key stores](key-store-overview.md#custom-key-store-overview). However, you can [rotate them manually](rotate-keys-manually.md).
1. Choose **Rotate now**. For symmetric encryption keys with imported key material, the **Rotate now** option is available only if you have previously [imported new key material](importing-keys-import-key-material.md#import-new-key-material) and it is in **Pending rotation** state.
**Note**
For multi-Region keys, only the primary Region key can be rotated.
1. Read and consider the warning and the information about the number of remaining on-demand rotations for the key. You will also see information such as the ID, description, and expiration time of the key material that will become current after rotation. If you decide that you do not want to proceed with the on-demand rotation, choose **Cancel**.
1. 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](https://docs.aws.amazon.com/kms/latest/APIReference/) 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)](https://aws.amazon.com/cli/), but you can use any supported programming language.
The [RotateKeyOnDemand](https://docs.aws.amazon.com/kms/latest/APIReference/API_RotateKeyOnDemand.html) operation immediately initiates on-demand key rotation for the specified KMS key. To identify the KMS key in these operations, use its [key ID](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN).
The following example initiates on-demand key rotation on the specified symmetric encryption KMS key and uses the [GetKeyRotationStatus](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyRotationStatus.html) 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. In this example, the KMS key also has automatic rotation enabled with a period of 365 days.
```
$ 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
}
```
If the KMS key does not support automatic rotation or does not have automatic rotation enabled, the `kms:GetKeyRotationStatus` response would have fewer fields as shown in the following example:
```
$ 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": false,
"OnDemandRotationStartDate": "2024-02-24T18:44:48.587000+00:00"
}
```
# List rotations and key materials
KMS keys that support automatic or on-demand key rotation can have multiple key materials associated with them. These keys have an initial key material and one additional key material for each automatic or on-demand rotation.
Authorized users with `kms:ListKeyRotations` permission can use the AWS KMS console and the [ListKeyRotations](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyRotations.html) API to list all key materials associated with a KMS key, including those from completed automatic and on-demand rotations.
**Topics**
+ [
## List rotations and key materials (console)
](#list-rotations-console)
+ [
## List rotations and key materials (AWS KMS API)
](#list-rotations-api)
## List rotations and key materials (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](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose the alias or key ID of a KMS key.
1. Choose the **Key material and rotations** tab.
+ The **Key material and rotations** tab appears only on the detail page of symmetric encryption KMS keys that support automatic or on-demand rotation. This includes KMS keys with key material that AWS KMS generated (`AWS_KMS` origin) and KMS keys with imported key material (`EXTERNAL` origin).
+ The **Key materials** table in the **Key material and rotations** tab lists all the key materials associated with the KMS key. For each key material, the corresponding entry displays its unique identifier assigned by AWS KMS, the rotation date, and key material state. The rotation date identifies when the key material became current after an automatic or on-demand key rotation. There is no rotation date associated with the first or `Pending rotation` key material. The key material state determines how AWS KMS uses the key material. Current key material is used for both encryption and decryption. Non-current key material is only used for decryption. A key material state of `Pending rotation` indicates the key material is staged for rotation. This key material is not used for any cryptographic operation until an on-demand key rotation makes it the current key material. Additional information displayed for the key material depends on type of KMS key.
+ For symmetric encryption KMS keys with `AWS_KMS` origin, each row also displays the rotation type — `On-demand` or `Automatic`.
+ Symmetric encryption KMS keys with imported key material (`EXTERNAL` origin) only support `On-demand` rotation, so there is no rotation type column. Instead, each row displays an import state, a user-specified description, expiration information, and an **Actions** menu. The import state is either **Imported** indicating the key material is available inside AWS KMS or **Pending import** indicating the key material is not available inside AWS KMS. The **Actions** menu can be used to delete imported key material or reimport key material. The **Delete key material** action is disabled if the import state of the key material is **Pending import**. The **Reimport key material** action is always available. You do not need to wait for a key material to expire or be deleted before reimporting it.
## List rotations and key materials (AWS KMS API)
You can use the [AWS Key Management Service (AWS KMS) API](https://docs.aws.amazon.com/kms/latest/APIReference/) 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)](https://aws.amazon.com/cli/), but you can use any supported programming language.
The [ListKeyRotations](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListKeyRotations.html) operation lists all rotations and key materials for the specified KMS key. To identify the KMS key in these operations, use its [key ID](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN).
This operation supports an optional `IncludeKeyMaterial` parameter. The default value of this parameter is `ROTATIONS_ONLY`. If you omit this parameter, AWS KMS returns information on the key materials created by automatic or on-demand key rotation. When you specify a value of `ALL_KEY_MATERIAL`, AWS KMS adds the first key material and any imported key material pending rotation to the response. This parameter can only be used with KMS keys that support automatic or on-demand key rotation.
```
$ aws kms list-key-rotations --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--inlcude-key-material ALL_KEY_MATERIAL
{
"Rotations": [
{
"KeyId": 1234abcd-12ab-34cd-56ef-1234567890ab,
"KeyMaterialId": 123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0,
"KeyMaterialDescription": "KeyMaterialA",
"ImportState": "PENDING_IMPORT",
"KeyMaterialState": "NON_CURRENT"
},
{
"KeyId": 1234abcd-12ab-34cd-56ef-1234567890ab,
"KeyMaterialId": 96083e4fb6dbc41d77578a213a6b6669c044dd4c143e96755396d2bf11fd6068,
"ImportState": "IMPORTED",
"KeyMaterialState": "CURRENT",
"ExpirationModel": "KEY_MATERIAL_DOES_NOT_EXPIRE",
"RotationDate": "2025-05-01T15:50:51.045000-07:00",
"RotationType": "ON_DEMAND"
}
],
"Truncated": false
}
```
# Rotate keys manually
You might want to create a new KMS key and use it in place of a current KMS key instead of using automatic or on-demand 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*.
![\[Diagram showing manual key rotation process with application, old key, and new key.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/key-rotation-manual.png)
Manual rotation is a good choice when you want to rotate KMS keys that are not eligible for automatic or on-demand key rotation, such as asymmetric KMS keys, HMAC KMS keys, and KMS keys in [custom key stores](key-store-overview.md#custom-key-store-overview).
**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](kms-alias.md), 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 [Learn how to use aliases in your applications](alias-using.md).
**Note**
Aliases that point to the latest version of a manually rotated KMS key are a good solution for [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html), [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) and cryptographic operations like [DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html), [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html), [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html), [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html), [GenerateMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateMac.html), [VerifyMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html), [Sign](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html) and [Verify](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html). Aliases are not permitted in operations that manage KMS keys, such as [DisableKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DisableKey.html) or [ScheduleKeyDeletion](https://docs.aws.amazon.com/kms/latest/APIReference/API_ScheduleKeyDeletion.html).
When calling the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_Verify.html) with an asymmetric KMS key, or calling [VerifyMac](https://docs.aws.amazon.com/kms/latest/APIReference/API_VerifyMac.html) 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateAlias.html) 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_ListAliases.html) 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-filter.html#cli-usage-filter-client-side-specific-values) 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
},
]
}
```
# Change the primary key in a set of multi-Region keys
Every set of related multi-Region keys must have a primary key. But you can change the primary key. This action, known as *updating the primary Region*, converts the current primary key to a replica key and converts one of the related replica keys to the primary key. You might do this if you need to delete the current primary key while maintaining the replica keys, or to locate the primary key in the same Region as your key administrators.
You can select any related replica key to be the new primary key. Both the primary key and the replica key must be in the `Enabled` [key state](key-state.md) when the operation starts.
**The `Updating` key state**
Even after the `UpdatePrimaryRegion` operation completes, the process of updating the primary Region might still be in progress for a few more seconds. During this time, the old and new primary keys have a transient key state of [Updating](#update-primary-keystate). While the key state is `Updating`, you can use the keys in cryptographic operations, but you cannot replicate the new primary key or perform certain management operations, such as enabling or disabling these keys. Operations such as [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) might display both the old and new primary keys as replicas. The `Enabled` key state is restored when the update is complete.
For information about the effect of the `Updating` key state, see [Key states of AWS KMS keys](key-state.md).
**How it works**
Suppose you have a primary key in US East (N. Virginia) (us-east-1) and a replica key in Europe (Ireland) (eu-west-1). You can use the update feature to change the primary key in US East (N. Virginia) (us-east-1) to a replica key and change the replica key in Europe (Ireland) (eu-west-1) to the primary key.
![\[Updating the primary key\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/multi-region-keys-update-sm.png)
When the update process completes, the multi-Region key in the Europe (Ireland) (eu-west-1) Region is a multi-Region primary key and the key in the US East (N. Virginia) (us-east-1) Region is its replica key. If there are other related replica keys, they become replicas of the new primary key. The next time that AWS KMS synchronizes the shared properties of the multi-Region keys, it will get the [shared properties](multi-region-keys-overview.md#mrk-sync-properties) from the new primary key and copy them to its replica keys, including the former primary key.
The update operation has no effect on the [key ARN](concepts.md#key-id-key-ARN) of any multi-Region key. It also has no effect on shared properties, such as the key material, or on independent properties, such as the key policy. However, you might want to [update the key policy](key-policy-modifying.md) of the new primary key. For example, you might want to add [kms:ReplicateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReplicateKey.html) permission for trusted principals to the new primary key and remove it from the new replica key.
## Update the primary Region
You can convert a replica key to a primary key, which changes the former primary key into a replica. To update the primary Region, you need [kms:UpdatePrimaryRegion](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdatePrimaryRegion.html) permission in both Regions.
You can update the primary Region in the AWS KMS console or by using the [UpdatePrimaryRegion](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdatePrimaryRegion.html) operation.
### Using the AWS KMS console
You can update the primary key in the AWS KMS console. Start on the key details page for the current primary key.
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](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Select the key ID or alias of the [multi-Region primary key](multi-region-keys-overview.md#mrk-primary-key). This opens the key details page for the primary key.
To identify a multi-Region primary key, use the tool icon in the upper right corner to add the **Regionality** column to the table.
1. Choose the **Regionality** tab.
1. In the **Primary key** section, choose **Change primary Region**.
1. Choose the Region of the new primary key. You can choose only one Region from the menu.
The **Change primary Regions** menu includes only Regions that have a related multi-Region key. You might not have [permission to update the primary Region](multi-region-keys-auth.md#mrk-auth-update) in all of the Regions on the menu.
1. Choose **Change primary Region**.
### Using the AWS KMS API
To change the primary key in a set of related multi-Region keys, use the [UpdatePrimaryRegion](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdatePrimaryRegion.html) operation.
Use the `KeyId` parameter to identify the current primary key. Use the `PrimaryRegion` parameter to indicate the AWS Region of the new primary key. If the primary key doesn't already have a replica in the new primary Region, the operation fails.
The following example changes the primary key from the multi-Region key in the `us-west-2` Region to its replica in the `eu-west-1` Region. The `KeyId` parameter identifies the current primary key in the `us-west-2` Region. The `PrimaryRegion` parameter specifies the AWS Region of the new primary key, `eu-west-1`.
```
$ aws kms update-primary-region \
--key-id arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab \
--primary-region eu-west-1
```
When successful, this operation doesn't return any output; just the HTTP status code. To see the effect, call the [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) operation on either of the multi-Region keys. You might want to wait until the key state returns to `Enabled`. While the key state is [Updating](#update-primary-keystate), the values for the key might still be in flux.
For example, the following `DescribeKey` call gets the details about the multi-Region key in the `eu-west-1` Region. The output shows that the multi-Region key in the `eu-west-1` Region is now the primary key. The related multi-Region key (same key ID) in the `us-west-2` Region is now a replica key.
```
$ aws kms describe-key \
--key-id arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab \
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab",
"Arn": "arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"CreationDate": 1609193147.831,
"Enabled": true,
"Description": "multi-region-key",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"Origin": "AWS_KMS",
"KeyManager": "CUSTOMER",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"MultiRegion": true,
"MultiRegionConfiguration": {
"MultiRegionKeyType": "PRIMARY",
"PrimaryKey": {
"Arn": "arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "eu-west-1"
},
"ReplicaKeys": [
{
"Arn": "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "us-west-2"
}
]
}
}
}
```