This topic describes how to configure automatic rotation of customer master keys (CMKs) in Key Management Service (KMS).

Key versions

A CMK may have multiple key versions. Each key version represents an independently generated key. Key versions of the same CMK do not have any cryptographic relation to each other. KMS automatically rotates CMKs 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 has only one primary key version at any point in time.
    • When you call an encryption API operation such as GenerateDataKey or Encrypt, KMS uses the primary key version of a specified CMK to encrypt the target plaintext.
    • You can call the DescribeKey operation to view the PrimaryKeyVersion attribute.
  • Non-primary key versions
    • A 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 and acted as the active encryption key in the past.
    • When a new primary key version is created, KMS does not delete or disable non-primary key versions because they will be used to decrypt data.
Note When you call an encryption API operation, the primary key version of a specified CMK is used. When you call a decryption API operation, the key version that was used to encrypt the ciphertext is used.
You can generate a key version in either of the following ways:
  • Create a CMK.

    You can call the CreateKey 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 regular basis to generate new key versions.

Automatic key rotation

Configure a key rotation policy

When you call the CreateKey operation to create a CMK, you can specify an automatic rotation policy for the CMK. You can call the UpdateRotationPolicy operation to update the current automatic rotation policy. When you call the API operations, 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 operation to view the configured automatic rotation policy. The following parameters are returned:
  • 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 the execution of automatic rotation although automatic rotation is enabled. For more information, see Impact 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 by using the following formula:
${NextRotationTime} = ${LastRotationTime} + ${RotationInterval}
where:
  • LastRotationTime: specifies the time when the last key version was created. You can call the DescribeKey operation and check the LastRotationDate parameter to obtain the time.
  • NextRotationTime: specifies the time when KMS will perform the next rotation task to create a new key version. You can call the DescribeKey operation and check the NextRotationDate parameter to obtain the time.
Notice When you update the RotationInterval parameter of an automatic rotation policy, the value of NextRotationTime may be a point in time in the past. This does not affect the execution of the automatic rotation policy. If this situation occurs, KMS executes the automatic rotation policy immediately.

Impact of CMK status on automatic rotation

A new key version can be created for a CMK only when this CMK is in the Enabled state (the value of KeyState). You must take note of the following points:
  • If a CMK is in the Disabled or Pending Deletion state, do not call the UpdateRotationPolicy operation to update its automatic rotation policy.
  • If a CMK enters the Disabled or Pending Deletion state after you enable automatic rotation for it, KMS suspends the execution of automatic rotation. In this case, if you call the DescribeKey operation, the returned value of the AutomaticRotation parameter is Suspended. When the CMK enters the Enabled state again, its automatic rotation policy becomes active again.

Limits

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

These two types of keys do not support version-based manual or automatic key rotation. A BYOK-based key does not have multiple versions in KMS. First, users have strong control over the persistence and lifecycle of BYOK-based keys. This makes management of the keys difficult and error-prone. For example, you must have on-premises key management facilities, data must be synchronized between on-premises and cloud facilities, and no grace period is provided for key material deletion on the cloud. The complexity of maintaining multiple versions of BYOK-based keys makes key management much more risky. Second, both primary and non-primary key versions may become unavailable at different points in time. For example, if key versions are deleted by KMS or imported again when they expire, it will be impossible to synchronize the CMKs and protected data or guarantee system integrity.