How to set up key rotation for KMS keys. - Key Management Service

Key Management Service (KMS) offers a key rotation feature that lets you periodically rotate keys. This enhances the security of your keys and business data. This topic describes how key rotation works and how to configure it.

Why rotate keys?

Reduces the amount of data encrypted by a single key. This lowers the risk of cryptanalysis attacks.
The security of a key is inversely related to the amount of data it encrypts. Data volume typically refers to the total bytes of data encrypted by a single key. Periodically rotating keys reduces the cryptanalysis attack surface for each key. This makes your overall encryption scheme more secure.
Prepares you to respond to security incidents.
By incorporating key rotation into your system design and implementation, you make it a routine security management task. This ensures your system is prepared to respond if a security incident occurs.
Shortens the time window for a key to be compromised.
If you regularly rotate keys and re-encrypt data with the new key, the rotation period becomes the time window in which an attacker can compromise the key. An attacker must break the key before the next rotation to access the data. This is a practical way to protect data from cryptanalysis attacks.
Helps you meet compliance requirements.
Periodic key rotation helps businesses comply with various standards. Standards that require key rotation include, but are not limited to:
- Payment Card Industry Data Security Standard (PCI DSS).
- Standards from the China State Cryptography Administration, such as GM/T 0051-2016 Cryptographic Device Management - Symmetric Key Management Technical Specification.
- Standards from the U.S. National Institute of Standards and Technology (NIST), such as NIST Special Publication 800-57 Recommendation for Key Management.

How key rotation works

A key can have multiple versions. These versions are cryptographically distinct from each other. KMS rotates a key by creating a new key version. KMS always uses the latest key version for cryptographic operations. You cannot specify a key version to use.

Note

Key rotation creates a new key version. The key ID, key ARN, and alias do not change.
KMS never deletes key versions. Key versions are deleted only when the parent key is deleted.

When you create a key, KMS generates the initial key version and sets it as the primary version. When the key is rotated, KMS creates a new key version and sets it as the new primary version. The following figure shows this process.

If you enable periodic automatic rotation, the Next rotation time is calculated using the following formula: Last rotation time + Rotation period.

Note

You can call the DescribeKey operation. The returned LastRotationDate field indicates the last rotation time. The NextRotationDate field indicates the scheduled time for the next rotation.
If a key is configured for periodic automatic rotation and you perform a manual rotation between scheduled rotations, the time of the manual rotation becomes the new Last rotation time. This new time is then used to calculate the Next rotation time.

Scope

Key type and source:

Key type	Key material source	Periodic automatic rotation	Manual immediate rotation
Software-protected key (symmetric)	Generated by KMS	Supported	Supported
Software-protected key (symmetric)	Imported from external source (BYOK)	Not supported	Supported
Software-protected key (asymmetric)	Generated by KMS, Imported from external source (BYOK)	Not supported
Hardware-protected key (symmetric and asymmetric)	Generated by KMS
Hardware-protected key (symmetric and asymmetric)	Imported from external source (BYOK)

Key status: The key must be in the Enabled state.
If a key is in the Disabled or Pending Deletion state, key rotation is paused. When the key is re-enabled, key rotation resumes.
Additional conditions for specific keys:
For default keys, you must purchase the rotation value-added service.

Set up rotation for default keys

Billing

Default keys are used for server-side encryption by Alibaba Cloud services and are free. However, key rotation for default keys is a value-added service.

Cost: USD 9 per year per region. After you purchase the service, all default keys in the specified region, including service keys and the default CMK, are eligible for rotation.

Rotation method and date

Only periodic automatic rotation is supported. Manual immediate rotation is not supported.

The rotation period is fixed at 365 days and cannot be changed. After you enable rotation, the first rotation occurs 365 days after the key version was created. Subsequent rotations occur every 365 days.

Note

The rotation value-added service is billed annually. Ensure that your subscription is active when the next rotation is scheduled. Otherwise, the rotation will fail.

Enable rotation (periodic automatic rotation)

Purchase the key rotation value-added service.
1. Log on to the KMS console. In the top navigation bar, select a region. In the navigation pane on the left, choose Resource > Keys.
2. On the Default Keys tab, click Buy Key Rotation and complete the configuration.
  1. Instance Type: Select Value-added Plan.
  2. Value-added Plan: Select Default Key Rotation.
  3. Region: Select the region where the default key is located.
  4. Purchase Quantity: You only need to purchase one per region.
3. Click Buy Now, read the Terms of Service carefully, and click Pay to complete the purchase.
Enable key rotation.
- Service keys
  No configuration is required. KMS automatically enables rotation.
- Default CMK
  Console
  1. On the Default Keys tab of Keys, click the ID of the key.
  2. On the details page, click the Key Version tab, and then click Configure Rotation.
  3. In the Configure Rotation dialog box, turn on the Rotation Status switch and click OK. On the key details page, the Rotation Status changes to Enabled, and the Rotation Period is displayed in Days.

Using rotating keys

Default keys can only be used for server-side encryption by Alibaba Cloud services. After rotation is enabled, Alibaba Cloud services manage rotation automatically. No manual operation is required. For more information, see Overview of KMS integration for encryption in cloud products.

View rotation details

Console

On the Default Keys tab of Keys, locate the service key or master key you want to view.
Click the key ID. On the details page, view the Rotation Status, Rotation Period, and Key Version.

Set up rotation for keys in a KMS instance

Quota consumption

Key rotation consumes the key quota of the KMS instance. Each version of a key consumes one key quota. For example, if a key has three versions (V1, V2, and V3), it consumes three key quotas. To increase the quota, see Upgrade a KMS instance.

Rotation method and date

KMS supports periodic automatic rotation and manual immediate rotation.

Periodic automatic rotation: Set a custom rotation period of 7 to 365 days to periodically generate new key versions.
Manual immediate rotation: Immediately generate a new key version.

Enable rotation

Enable periodic automatic rotation
Console
- Enable key rotation when you create a key. For more information, see Manage keys.
  1. On the Customer Master Keys tab of Keys, select an instance ID, and then click Create Key.
  2. In the Create Key panel, complete the configuration. Enable Automatic Rotation, set the Rotation Period, and then click OK.
- Enable key rotation after you create the key.
  1. On the Customer Master Keys tab of Keys, select an instance ID, and then click the ID of the target key.
  2. In the Key Version area on the key details page, click Configure Rotation. In the Configure Rotation Policy dialog box, enable periodic automatic rotation, set the rotation period, and then click OK.
API
- Enable key rotation when you create a key.
  Call the CreateKey operation. Set the EnableAutomaticRotation and RotationInterval parameters.
- Enable key rotation after you create the key.
  Call the UpdateRotationPolicy operation. Set the EnableAutomaticRotation and RotationInterval parameters.
Manual immediate rotation
- For keys with key material that is generated by KMS.
  Console
  1. On the Customer Master Keys tab of Keys, select an instance ID, and then click the ID of the target key.
  2. In the Key Version area on the key details page, click Configure Rotation. In the Configure Rotation Policy dialog box, select Rotate Now, and then click OK.
  API
  Call the CreateKeyVersion operation.
- For BYOK keys that use imported key material.
  1. Import new key material.
    1. Log on to the KMS console. In the top navigation bar, select a region. In the navigation pane on the left, choose Resource > Keys.
    2. On the Keys tab, select an instance ID, and then click Details in the Actions column of the target key.
    3. On the Key Material and Version tab, click Import New Key Material in the upper-left corner. Follow the instructions in Import symmetric key material to import the key material.
    4. After the new key material is imported, a new key version with a status of Pending Rotation is generated. You can view the new key version in the key version list.
      Important
      You cannot import another key version until the current new version is rotated.
  2. Perform the rotation.
    1. In the Actions column for the key version that was generated in Step 1, click Rotate.
    2. In the Rotate Now dialog box, confirm that the key material ID is correct, and then click OK.

Use rotated keys

When keys are used for server-side encryption by Alibaba Cloud services, the services automatically manage key rotation after you enable it. No manual operation is required. When you use keys for encryption in self-built applications, use the following API operations for cryptographic operations. By default, the operations use the latest version of the rotated key.

Using Alibaba Cloud SDK

Alibaba Cloud SDKs call OpenAPI. To perform encryption and decryption, call the following operations.

Generate data key: GenerateDataKey. Uses the primary version of the specified key to encrypt the data key.
Encrypt: Encrypt. Uses the primary version of the specified key to encrypt the plaintext.
Decrypt: Decrypt. Uses the key version that corresponds to the provided ciphertext to decrypt the data.

Using KMS instance SDK (not recommended)

We do not recommend that new users use this SDK. The KMS instance SDK calls instance APIs. To perform encryption and decryption, call the following operations.

Generate data key: AdvanceGenerateDataKey. KMS uses the primary version of the specified key to encrypt the data key.
Encrypt: AdvanceEncrypt. KMS uses the primary version of the specified key to encrypt the plaintext.
Decrypt: AdvanceDecrypt. KMS uses the key version that corresponds to the provided ciphertext to decrypt the data.

Important

If you have enabled automatic rotation for your key, do not use the older instance API operations Encrypt, Decrypt, or GenerateDataKey. These operations use the initial key version for encryption and decryption and do not use the new key versions that are generated after rotation.

View rotation details

Console

On the Customer Master Keys tab of Keys, select an instance ID, and then click the ID of the target key.
On the details page, you can view the Rotation Status, Rotation Period, and Key Version.

API

Call the DescribeKey operation. Check the AutomaticRotation and RotationInterval parameters in the response.
Call the ListKeyVersions operation. Check the KeyVersions parameter in the response.