Rotating a customer master key (CMK) regularly limits the amount of data protected by any single version of the key material, reducing the risk of key compromise. In Key Management Service (KMS), automatic rotation replaces the key material on a schedule you define — without any changes to your application code or interruption to existing encryption and decryption operations.
Automatic key rotation is only available for CMKs with Origin = Aliyun_KMS. Service-managed keys and Bring Your Own Key (BYOK) keys do not support multiple key versions or rotation. For details, see Limitations.How automatic rotation works
A CMK can have multiple key versions. Each version is independently generated — versions of the same CMK share no cryptographic relationship with each other.
Key version types:
| Type | Description |
|---|---|
| Primary key version | The active encryption key. Each CMK has exactly one primary key version at any point in time. KMS uses the primary key version when you call GenerateDataKey or Encrypt. Query it via DescribeKey → PrimaryKeyVersion. |
| Non-primary key version | A previous primary key version that is now inactive. A CMK can have zero or more non-primary key versions. KMS retains all non-primary key versions — they are required to decrypt data encrypted when they were active. |
Encryption always uses the current primary key version. Decryption automatically selects whichever key version was used to encrypt the data.
How key versions are created:
At CMK creation — when you call
CreateKeywithOrigin = Aliyun_KMS, KMS generates an initial key version and sets it as the primary key version.By automatic rotation — once enabled, KMS creates a new key version on a regular schedule and promotes it to primary.
Effects on encryption and decryption
After rotation, KMS uses the new primary key version for all new encryption. For data encrypted by earlier key versions, you can only use that historical key version to decrypt the data — KMS automatically selects the correct historical key version for each decryption request. No application code changes are required.
To migrate ciphertext from a historical key version to the current primary version, call the ReEncrypt operation. ReEncrypt decrypts the ciphertext using the original key version, then re-encrypts the result using the current primary key version.
Configure automatic key rotation
Set up automatic key rotation at CMK creation, or update the schedule at any time.
At CMK creation, pass the rotation parameters to CreateKey:
| Parameter | Description |
|---|---|
EnableAutomaticRotation | Whether to enable automatic rotation |
RotationInterval | How often KMS creates a new key version |
After creation, call UpdateRotationPolicy with the same parameters to change the rotation schedule.
To view the current rotation configuration, call DescribeKey. The response includes:
| Field | Description | Values |
|---|---|---|
AutomaticRotation | Current rotation status | Enabled, Disabled, Suspended |
RotationInterval | Configured rotation interval | Duration value |
LastRotationDate | When the last key version was created | Timestamp |
NextRotationDate | When the next rotation is scheduled | Timestamp |
Rotation schedule formula:
NextRotationDate = LastRotationDate + RotationIntervalIf you update RotationInterval and the recalculated NextRotationDate falls in the past, KMS executes rotation immediately and then continues on the new schedule.
CMK status and rotation behavior
Rotation only runs on CMKs in the Enabled state (KeyState = Enabled).
Scenario: CMK enters `Disabled` or `Pending Deletion` state
KMS suspends automatic rotation. DescribeKey returns AutomaticRotation = Suspended. The rotation policy configuration is preserved and no new key versions are created.
Scenario: CMK returns to `Enabled` state
The automatic rotation policy becomes active again. KMS calculates the next rotation based on LastRotationDate + RotationInterval and resumes the schedule.
Scenario: Updating the rotation policy on a non-`Enabled` CMK
Do not call UpdateRotationPolicy on a CMK in the Disabled or Pending Deletion state.
Limitations
The following key types do not support multiple key versions or manual and automatic key rotation:
Service-managed keys — the default CMKs that KMS manages on behalf of specific Alibaba Cloud services. These keys belong to cloud service users and provide basic encryption for service data.
BYOK keys — keys you imported to KMS with
Origin = EXTERNAL. KMS does not generate key material or initiate rotation tasks for these keys.BYOK keys do not support multiple versions for two reasons:
You control the full lifecycle of the key material outside of KMS, including on-premises storage and synchronization with the cloud. Managing multiple versions of imported key material across environments introduces significant operational risk — for example, there is no grace period if key material is deleted from KMS.
If any version becomes unavailable — because it was deleted from KMS or re-imported material does not match the original — decryption of data encrypted by that version fails, which affects system integrity.
For more information, see Import key material.