This topic describes how to use automatic rotation of Customer Master Keys (CMKs) in KMS.

Key versions

CMKs support multiple key versions. Each key version represents an independently generated key. Multiple key versions of a CMK do not have any cryptographic relation to each other. KMS rotates CMKs automatically by generating new key versions.

There are two types of key versions:
  • Primary key versions
    • The primary key version of a CMK is an active encryption key. Each CMK only has a single primary key version at any time.
    • When you call API operations such as GenerateDataKey and Encrypt, KMS uses the primary key version of a specified CMK to encrypt the target plaintext.
    • You can call the DescribeKey API operation to view PrimaryKeyVersion attributes.
  • Non-primary key versions
    • The non-primary key version of a CMK is an inactive encryption key. Each CMK can have any number of non-primary key versions.
    • Each non-primary key version was a primary key version in the past and used to act as the active encryption key.
    • When a new primary key version is created, KMS does not delete or disable non-primary key versions, which can be used to decrypt data.
Note When you call the Encrypt API operation, the primary key version of a specified CMK is used. When you call the Decrypt API operation, the key version that was used to encrypt the ciphertext is selected.
You can generate a key version in either of the following ways:
  • Create a CMK

    You can call the CreateKey API operation to create a CMK. If you set the Origin parameter to Aliyun_KMS, KMS generates an initial key version and sets it as the primary key version.

  • Execute an automatic rotation policy

    After you configure an automatic rotation policy, KMS executes the policy on a periodic basis to generate new key versions.

Automatic key rotation

Configure a key rotation policy

When you call the CreateKey API operation to create a CMK, you can specify an automatic rotation policy for the CMK. You can call the UpdateRotationPolicy API operation to update the currently used automatic rotation policy. When you call the UpdateRotationPolicy API operation, you must configure the following parameters:
  • EnableAutomaticRotation: specifies whether to enable automatic rotation.
  • RotationInterval: specifies the period for automatic rotation.
You can call the DescribeKey API operation to view the automatic rotation policy information. The following policy-related parameters are displayed:
  • AutomaticRotation: indicates whether automatic rotation is enabled. Disabled indicates that automatic rotation is not enabled. Enabled indicates that automatic rotation is enabled. Suspended indicates that KMS suspends execution of automatic rotation although automatic rotation is enabled. For more information, see Effects of CMK status on automatic rotation.
  • RotationInterval: indicates the period for automatic rotation.

Execute an automatic rotation policy

When automatic rotation is enabled, KMS calculates the time of the next rotation using the following formula:
${NextRotationTime} = ${LastRotationTime} + ${RotationInterval}
The parameters are as follows:
  • LastRotationTime: specifies the time that the last key version was created. You can call the DescribeKey API operation and check the LastRotationDate parameter to query this value.
  • NextRotationTime: specifies the time that KMS will perform the next rotation task to create a new key version. You can call the DescribeKey API operation and check the NextRotationDate parameter to query this value.
Notice When you update the RotationInterval parameter of an automatic rotation policy, the calculated value of NextRotationTime may be a point in time in the past. This will not affect the execution of the automatic rotation policy. KMS will create a new key version as scheduled. If the calculated value of NextRotationTime is before the current time, KMS will execute the automatic rotation policy immediately.

Effects of CMK status on automatic rotation

A new key version can be created only when a CMK is in the Enabled state (the KeyState parameter is displayed as Enabled). You must take note of the following points:
  • If a CMK is in the Disabled or PendingDeletion state, do not call the UpdateRotationPolicy API operation to update its automatic rotation policy.
  • If a CMK enters the Disabled or PendingDeletion state after automatic rotation is enabled, KMS suspends execution of automatic rotation. When you call the DescribeKey API operation, the AutomaticRotation parameter will be displayed as Suspended. When the CMK enters the Enabled state, its automatic rotation policy becomes active again.

Limits

The following keys do not support multiple key versions:
  • Service managed keys: the default keys managed by KMS for specific cloud services. These keys belong to users of specific cloud services and are used to provide basic encryption protection for user data.
  • Bring Your Own Keys (BYOKs): the keys that you have imported to KMS. For more information, see Import key materials. The Origin value of these keys is External, so KMS does not generate key materials or initiate rotation tasks for these keys.

The preceding key types do not support version-based key rotation. KMS does not support multiple BYOK versions. First, users have strong control over BYOK persistence and lifecycle, which makes management difficult and error-prone. For example, you must have on-premise key management facilities, data must be synchronized between on-premise and cloud facilities, and no grace period is provided when you delete key materials. The complexity of maintaining multiple versions of BYOKs makes it much more risky. Second, both primary and non-primary key versions may become unavailable at different times. For example, if key versions are deleted by KMS or imported again when they expire, it would be impossible to synchronize the CMKs and protected data or guarantee system integrity.