How to Use Keys to Encrypt and Decrypt Data?

KMS provides a Representational State Transfer(REST) API that can be called via HTTPS requests. You can use the provided API for encryption and decryption. The following uses CMK for data encryption and decryption as an example to introduce the implementation process:

Encryption process (taking encryption certificate as an example):

1. Create a CMK on the KMS console or by calling the CreateKey API;

2. Call the Encrypt API of KMS to encrypt the plaintext certificate into the ciphertext certificate.

3. Deploy the ciphertext certificate on a server;

4. Call the Decrypt API of the KMS to decrypt the ciphertext certificate into a plaintext certificate when the server starts and needs to use the certificate.

How to Import an External Key?

After creating a key, go to the key details page to obtain the parameters for importing the CMK, including the encryption public key and the import token. Encrypt your key material with the obtained public key, and then upload your key material on the key details page as prompted.

The import token obtained from KMS is bound with the public key of the encryption key material, and a token can only be used to import the key material for the CMK specified when it was generated. The import token is valid for 24 hours and can be repeatedly used within the validity period. After 24 hours, you must download a new import token and a new public key.

How to Delete a Key?

KMS does not support immediate deletion, and only supports scheduled deletion. Specifically, you need to configure a scheduled deletion period (7 to 30 days). The system will automatically delete the key upon expiration. During the scheduled period, the key is managed in the system, but cannot be invoked for encryption and decryption.

After the scheduled deletion is configured and takes effect, keys will no longer incur fees. If you still need to use the key during the scheduled period, you can cancel the scheduled deletion to make the key available again.

Why Doesn't KMS Support Immediate Key Deletion?

A key cannot be recovered after deletion. Once a key is deleted, all data encrypted with the key cannot be decrypted. After you schedule a deletion, the key status changes to "Pending Deletion". The key will not be deleted immediately. Instead, the system will postpone the deletion of the key according to the scheduled deletion period. The system will delete the key only at the scheduled time point. Before this, you can cancel the scheduled deletion. In this way, KMS reduces the losses caused by user misoperations.

Keys in the "Pending Deletion" state are unavailable and cannot be used for encryption and decryption, and generating data keys.

If you no longer use a key, it is recommended that you disable the key first to ensure that it does not affect your business before deleting it by scheduling a key deletion. To avoid accidental deletion, you can enable the deletion protection function.

Does KMS Support the National Commercial Cryptographic Algorithms of China?

Yes. KMS supports SM2 and SM4 keys, suitable for data encryption and decryption, signature verification and other scenarios.

Cryptographic Algorithm Category	Cryptographic Algorithm Sub-category	Protection Level	Whether Encryption or Decryption Is Supported	Whether Signature Verification Is Supported
Symmetric key	AES_256	Software HSM	Support	Not supported
Asymmetric key	RSA_2048	Software HSM	Support	Support

Cryptographic Algorithm Category

Cryptographic Algorithm Sub-category

Protection Level

Whether Encryption or Decryption Is Supported

Whether Signature Verification Is Supported

Symmetric key

AES_256

Software

HSM

Support

Not supported

Asymmetric key

RSA_2048

Software

HSM

Support

What Is the Difference Between Software Protection Level and Hardware Protection Level?

A key at software protection level is protected by a software module, and its root key is encrypted by the public key into ciphertext and stored in software file system. The private key used to decrypt the ciphertext of the root key is symmetrically encrypted into ciphertext and stored in another position of the file system. The symmetric key is also stored in another position to enhance the security of the system root key;

A key at the hardware protection level is protected by special hardware. The hardware root key needs to store the internal key index of the cryptographic device, and confirm the root key by the index. All processes involving the root key are performed in the cryptographic device, including encryption and decryption.

What Is the Range of the Automatic Key Rotation Cycle?

For symmetric keys, you can set the automatic rotation cycle, ranging from 7 days to 730 days (two years).

Symmetric keys support automatic rotation. The system automatically generates a new key version based on the automatic rotation period, and sets the latest version to the primary version. The original key version is saved in KMS as a non-primary version. KMS will not delete or disable the non-primary versions, which will be used to decrypt data.

Does an Asymmetric Key Support Automatic Rotation?

Asymmetric keys do not support automatic rotation, but you can manually create a new version.

Because of the characteristics of use cases of the public key-private key pair, KMS does not support the automatic rotation of asymmetric CMKs. You can manually create a new key version in the specified CMK to generate a new public key-private key pair.

In addition, unlike symmetric CMKs, asymmetric CMKs do not have a primary key version. Therefore, you must specify the corresponding CMK ID or CMK alias and a key version if you need to call the APIs related to asymmetric cryptogrammic operations.

When Am I Required to Import an External Key?

Import an external key when you have your own key material and want to continue to use it to encrypt and decrypt data. For example, when you need to migrate local encrypted data to the cloud, and share the same key material for operations on and off the cloud. In this case, you can import the key material into KMS.

If you select the external source for key materials, you need to focus on the following for BYOK:

Ensure that you use a random source that meets the security requirements to generate key materials;

When importing the key, you must be responsible for the reliability of your own key materials;

Save the original backup of key materials to re-import the backup key materials into KMS in time if the key materials are accidentally deleted.

What Types of Keys Support External Key Materials?

Currently, AES_256 symmetric keys support importing external key materials.

You can create a key on the console. Select an AES_256 type symmetric key, select External as the key material source, check "I understand the methods and significance of using external key materials", and click OK.

After the key is successfully created, go to the key details page to import the key materials. Before importing key materials, you need to obtain the parameters of the imported materials, including the encryption public key and the import token. For details, see related sections in the User Guide.

Does an Imported Key Material Support Automatic Rotation?

No. Imported key materials do not support automatic rotation and do not have key versions.

When importing a key material, you can set the expiration time of the key material. The KMS automatically deletes the key material when it expires but the CMK and its metadata are retained.

You can manually delete an imported key material, but the CMK and its metadata will still be reserved.

How to Restore a Key if the Key Material Is Deleted by Mistake or Has Expired?

If a key material is deleted or expires, you can import the same key material again. The key will be available again after it is successfully imported. You need to back up the key material so that you can re-import it if the key material becomes invalid or is deleted by mistake.

The CMK is associated with the key material. When you import the key material into a CMK, the CMK is permanently associated with the key material, and other key materials cannot be imported into the CMK, even if the key material has expired or is deleted.

Can I Import Other Key Materials into the CMK after the Key Material of the CMK Is Deleted or Expires?

No. A CMK contains key metadata (key ID, key alias, description, key status, and creation date) and key materials used for encrypting and decrypting data.

After the key material is successfully imported into the CMK, the CMK is permanently associated with the key material. Other key materials can be imported into the CMK.

Can Different CMKs with the Same Key Material Encrypt and Decrypt Data of Each Other?

No. A CMK contains key metadata (key ID, key alias, description, key status, and creation date) and key materials used for encrypting and decrypting data.

A CMK is unique, and the data encrypted with a CMK can only be decrypted with the same CMK. Other CMKs with the same key material cannot decrypt the data encrypted by this CMK.

What Is the Purpose of a CMK Alias?

You can create aliases to help manage keys, and an alias corresponds to a unique CMK. When the KMS API is called, the key ID in the parameter can be replaced by an alias.

An alias is dependent on a CMK and its characteristics are as follows:

Multiple aliases can be bound to a CMK, and deleting an alias will not delete its associated CMK.

The alias cannot be modified. You can create a new alias for the CMK and delete the original alias to modify the CMK.

You can call the UpdateAlias API to change the CMK bound by the alias without affecting the CMK.

You cannot delete and add aliases for the default CMK.

What Is the Relationship Between a CMK and an Alias?

An alias is an optional identifier of a CMK and must be associated with the key. The alias of the same account in a region must be unique.

A CMK can be bound to multiple aliases, and an alias can only be bound to a CMK.

The default CMK alias cannot be deleted or changed.

Can I Change an Alias?

You cannot modify an alias directly. Instead, you can modify an alias by creating a new alias and deleting the original one.

When a new alias is created, other aliases will not be affected. Before deleting an existing alias, ensure that it is no longer used. Otherwise, data may fail to be encrypted.

You cannot delete or add the default CMK alias.

Will Deleting Aliases Affect the CMK?

An alias is an optional identifier of the CMK. After an alias is deleted, the associated CMK will not be deleted.

When calling the API, you can use the alias instead of the key ID. Therefore, if an alias is used as an API call parameter, the service call will fail if the alias is deleted. Please ensure that the alias scheduled for deletion is no longer in use.

Can I Set the Same Alias for the CMK in the Same Resource Pool?

No. The aliases of the same account in the same region must be unique. An alias can be bound to only one CMK in a region, but a CMK can have multiple aliases.

The same alias can be bound to CMKs in different resource pools.

What Is the Purpose of Configuring Automatic Rotation for CMKs?

KMS provides a key rotation function to enhance the security of keys by rotating keys between key versions and effectively secure business data.

Key rotation reduces the amount of data encrypted by each key version and mitigates the risks of cryptanalysis attacks;

Key rotation can reduce the time window during which keys can be cracked. After key rotation is enabled, the data that is encrypted by using an existing key can be encrypted by using a new key. The interval of key rotation is considered the time window during which a key can be cracked. An attacker can gain data access only if the attacker cracks a key in an interval between two rotation operations of the key. This greatly increases the security of data against cryptanalytic attacks. The key rotation period is the time window during which keys can be cracked. A smaller window indicates a greater difficulty for cracking.

Will It Affect the Decryption of Existing Data When a New Key Version Is Generated After Key Rotation?

No. After a new version is generated by key rotation, the new version will be used for encrypting data. The original version will not be deleted or disabled, and will be used to decrypt the original data.

Symmetric keys have primary versions and non-primary versions: The primary version is the Active Encryption Key of CMK. Each CMK has only one primary version at any point in time. When calling the encryption APIs such as GenerateDataKey and Encrypt, KMS encrypts the plaintext with the primary version of the specified CMK. The non-primary version is the Inactive Encryption Key of CMK. Each CMK can have zero to multiple non-primary versions. The non-primary version used to be the primary version and was used as the active encryption key. KMS will not delete or disable non-primary versions after a new primary version is generated by key rotation, and these non-primary versions are used to decrypt data.

Does an Asymmetric Key Support Automatic Rotation?

No. Because of the characteristics of use cases of the public key of asymmetric keys, KMS does not support the automatic rotation of asymmetric keys. You can manually create a new version and generate a pair of public key and private key.

Do I Need to Specify a Key Version When Using a Key for Data Encryption?

Whether it is necessary to specify a key version depends on the key type.

When calling a symmetric key to encrypt data, you are not required to specify the key version. By default, the system will use the latest primary version for data encryption.

When calling an asymmetric key to encrypt data, you need to specify the CMK and the key version.

Key Management Service