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

Key Management Service (KMS) provides a key rotation feature, allowing you to periodically rotate keys to enhance the security of your keys and business data. This topic describes how key rotation works and how to configure it.

Why rotate keys

Reduce the amount of data encrypted by a single key version to lower the risk of cryptanalysis attacks.
This refers to the total number of bytes encrypted by a single key version. By periodically rotating keys, you reduce the cryptanalysis attack surface for each key version, making your overall encryption scheme more secure.
Be prepared to respond to security incidents.
This prepares your system to respond to security incidents. By incorporating key rotation into your system design and implementation, you make it a routine security management task.
Shorten the time window for a key to be compromised.
If you re-encrypt data with new keys after each rotation, the rotation period becomes the time window in which a key can be compromised. This means an attacker must break the key before the next rotation to access the data. This practice is highly effective in protecting data from cryptanalysis attacks.
Meet compliance requirements.
Periodic key rotation helps organizations meet various compliance requirements. Standards that require key rotation include but are not limited to:
- Payment Card Industry Data Security Standard (PCI DSS).
- Cryptography-related industry standards issued by the China State Cryptography Administration, such as GM/T 0051-2016 Cryptographic Device Management - Symmetric Key Management Technical Specification.
- Cryptography-related standards issued by 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 key versions. The versions of a key are cryptographically unrelated. KMS rotates a key by creating a new key version and always uses the latest key version for cryptographic operations. You cannot specify a key version to use.

Important

Key rotation creates a new key version but does not change the key ID, key ARN, alias, or other properties of the key.
KMS deletes a key version only when the key to which it belongs is deleted.
Key rotation does not affect cloud service or SDK calls.

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

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

Note

You can call the DescribeKey operation. In the response, the LastRotationDate field specifies the last rotation time, and the NextRotationDate field specifies the scheduled time for the next rotation.
If a key is configured for periodic automatic rotation and you perform a manual immediate rotation between scheduled rotations, the time of the manual rotation becomes the last rotation time used to calculate the next rotation time.

Usage notes

Key type and key material source

Key type	Key material source	Periodic automatic rotation	Manual immediate rotation
Software key (symmetric)	Key Management Service	Supported	Supported
Software key (symmetric)	External (Import Key Material)	Not supported	Supported
Software key (asymmetric)	Key Management Service, External (Import Key Material)	Not supported
Hardware key (symmetric and asymmetric)	Key Management Service
Hardware key (symmetric and asymmetric)	External (Import Key Material)

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

Configure rotation for default keys

Billing

KMS provides default keys at no cost for server-side encryption by cloud services. However, key rotation for default keys is a value-added service.

Fee: USD 9 per year per region. After you purchase the service, all default keys, including service keys and customer master keys (CMKs), in the specified region are eligible for rotation.

Rotation method and schedule

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

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

Note

The value-added service for key rotation is an annual subscription. To ensure that the next rotation is performed as scheduled, make sure that your subscription is active.

Enable periodic automatic rotation

Purchase the value-added service for key rotation.
1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.
2. On the Default Keys tab, click Buy Key Rotation and configure the parameters.
  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: Purchase only one set per region.
3. Read the Service Agreement carefully, click Buy Now, and then click Purchase Rotation Service to complete the purchase.
Enable key rotation.
- Service key
  No configuration is required. KMS enables rotation automatically.
- Customer master key (CMK)
  Using the console
  1. On the Default Keys tab of the Keys page, click the ID of the CMK.
  2. At the bottom of 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 an API
  - Enable rotation when you create a key.
    Call the CreateKey operation and set the EnableAutomaticRotation and RotationInterval parameters.
  - Enable rotation after you create a key.
    Call the UpdateRotationPolicy operation and set the EnableAutomaticRotation and RotationInterval parameters.

Using rotating keys

The default key can be used only for server-side encryption in cloud products. After rotation is enabled, cloud products automatically manage the key, and no manual operations are required. For more information, see Overview of integrating cloud products with KMS.

View rotation details

Using the console

On the Default Keys tab of the Keys page, find the service key or customer master key (CMK) that you want to view.
Click the key ID. On the details page, view the Rotation Status, Rotation Period, and Key Version.

Using the API

Call the DescribeKey operation and check the returned AutomaticRotation and RotationInterval parameters.
Call the ListKeyVersions operation and check the returned KeyVersions parameter.

Set key rotation for a KMS instance

Quota consumption

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

Rotation methods and dates

Periodic automatic rotation and manual immediate rotation are supported.

Periodic automatic rotation: A new key version is periodically generated based on a custom rotation period of 7 to 365 days.
Manual immediate rotation: A new key version is generated immediately.

Enable rotation

Enable periodic automatic rotation
Using the console
- Enable rotation when you create a key. For more information, see Manage keys.
  1. On the Customer Master Keys tab of the Keys page, select a KMS instance ID, and then click Create Key.
  2. In the Create Key panel, configure the parameters, enable Automatic Rotation, and set the Rotation Period. Then, click OK.
- If you did not enable rotation when you created the key, enable it afterward.
  1. On the Customer Master Keys tab of the Keys page, select a KMS instance ID, and then click the ID of the target key.
  2. In the Key Version section of 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.
Using an API
- Enable rotation when you create a key.
  Call the CreateKey operation and set the EnableAutomaticRotation and RotationInterval parameters.
- If you did not enable rotation when you created the key, enable it afterward.
  Call the UpdateRotationPolicy operation and set the EnableAutomaticRotation and RotationInterval parameters.
Manual immediate rotation
- Keys with key material generated by KMS.
  Using the console
  1. On the Customer Master Keys tab of the Keys page, select a KMS instance ID, and then click the ID of the target key.
  2. In the Key Version section of the key details page, click Configure Rotation. In the Configure Rotation Policy dialog box, select Rotate Now, and then click OK.
  Using an API
  Call the CreateKeyVersion operation.
- Bring Your Own Keys (BYOKs) with imported key material.
  1. Import new key material
    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.
    2. On the Keys tab, select a KMS instance ID, and then click Details in the Actions column for the target key.
    3. On the Key Material and Version tab, click Import New Key Material in the upper-left corner. Import the key material. For more information, see Import symmetric key material.
    4. After the new key material is imported, a new key version is generated. You can view the new key version in the key version list. The status is "Pending Rotation".
      Important
      You cannot import a new version before the current new version is rotated.
  2. Perform 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 you use keys for server-side encryption of cloud products, the cloud products automatically manage the keys after you enable rotation. No manual operations are required. When you use keys to encrypt data in your self-built applications, call the following API operations for cryptographic operations. By default, the operations use the latest key version after rotation.

When you use an Alibaba Cloud SDK

Alibaba Cloud SDKs call OpenAPI operations. Call the following operations for encryption and decryption.

Generate a data key: GenerateDataKey. KMS uses the primary version of the specified key to encrypt the data key.
Encrypt data: Encrypt. KMS uses the primary version of the specified key to encrypt the plaintext.
Decrypt data: Decrypt. KMS uses the key version that corresponds to the input ciphertext to decrypt the data.

When you use a KMS instance SDK (not recommended)

This SDK is not recommended for new users. KMS instance SDKs call instance API operations. Call the following operations for encryption and decryption.

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

Important

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

View rotation details

Using the console

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

Using an 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.