Import key material into a symmetric key - Key Management Service

If you need to manage key material, you can create a key that has an external key material origin in your Key Management Service (KMS) instance, and then import your own key material. This topic describes how to import key material into a symmetric key.

Important

If your KMS instance of the hardware key management or software key management type does not allow you to import key material or an error is returned when you import key material, contact technical support.

Features

Keys are basic resources in KMS. A key consists of the key ID, metadata such as the key status, and key material. To create a key, you can use the key material that is generated by KMS or use external key material. If you use external key material to create a key, you must import the key material into the key. This feature is commonly known as the bring your own key (BYOK) feature.

The following table describes whether different types of keys support external key material. For more information about key types, see Key types and specifications.

: supports external key material.
: does not support external key material.

Key type	Import external key material into a symmetric key	Import external key material into an asymmetric key
Default key	Customer master key (CMK): √ Service key: ×	CMK: × Service key: ×
Software-protected key	✓	✓
Hardware-protected key	✓	✓

Usage notes

Make sure that a compliant random number generator is used to generate key material.
The first time you import key material into a key, the key is associated with the key material. You cannot import different key material into the key.
You can import the same key material into a key multiple times based on your business requirements.
If the key material of a key expires or is deleted, you can reimport the same key material for the key, This way, you can reuse the key. After you import key material, you cannot export the key material. We recommend that you store the key material in a secure location.

Prerequisites

A KMS instance is purchased and enabled. For more information, see Purchase and enable a KMS instance.

Note

When you import key material into a default key of the CMK type, you do not need to purchase a KMS instance.

Step 1: Create a symmetric key that has an external key material origin

Before you import key material, create a symmetric key that has an external key material origin.

Default key of the CMK type

Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

Click the Default Key tab, find the default key of the CMK type that you want to enable, and click Enable in the Actions column. In the Create Key panel, configure the parameters and click OK.

Parameter	Description
Key Alias	The alias of the key. The alias can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).
Description	The description of the key.
Advanced Settings	The key material origin. Select External (Import Key Material). Note Read and select I understand the implications of using the external key materials.

Software-protected key

Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.
On the Keys tab, select the ID of a KMS instance of the software key management type from the Instance ID drop-down list and click Create Key.

In the Create Key panel, configure the parameters and click OK.

Parameter	Description
Key Type	The type of the key. Select Symmetric Key. Important If you want to create a key to encrypt secrets, select Symmetric Key.
Key Specifications	Symmetric key specifications: Aliyun_AES_256
Key Usage	The usage of the key. Encrypt/Decrypt: encrypts or decrypts data.
Key Alias	The alias of the key. The alias can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).
Tag	The tag that you want to add to the key. You can use tags to classify and manage keys. A tag consists of a key-value pair. Note A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), and at signs (@). A tag key cannot start with aliyun or acs:. You can configure up to 20 key-value pairs for each key.
Description	The description of the key.
Advanced Settings	Policy Settings: For more information, see Overview. Key Material Source: Select External (Import Key Material). Note Read and select I understand the implications of using the external key materials.

Hardware-protected key

Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.
On the Keys tab, select the ID of a KMS instance of the hardware key management type from the Instance ID drop-down list and click Create Key.

In the Create Key panel, configure the parameters and click OK.

Parameter	Description
Key Type	The type of the key. Select Symmetric Key. Important If you want to create a key to encrypt secrets, select Symmetric Key.
Key Specifications	Symmetric key specifications: Aliyun_AES_256, Aliyun_AES_192, and Aliyun_AES_128
Key Usage	The usage of the key. Valid values: Encrypt/Decrypt: encrypts or decrypts data. Sign/Verify: signs data or verifies a digital signature.
Key Alias	The alias of the key. The alias can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).
Tag	The tag that you want to add to the key. You can use tags to classify and manage keys. A tag consists of a key-value pair. Note A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), and at signs (@). A tag key cannot start with aliyun or acs:. You can configure up to 20 key-value pairs for each key.
Description	The description of the key.
Advanced Settings	Policy Settings: For more information, see Overview. Key Material Source: Select External (Import Key Material). Note Read and select I understand the implications of using the external key materials.

After you create the key, the key enters the Pending Import status.

Step 2: Download a wrapping public key and an import token

To import key material into a key, you must obtain a wrapping public key and an import token. The wrapping public key is used to encrypt key material. The import token allows you to import key material.

Find the key into which you want to import key material and click Details in the Actions column. On the Key Material tab, click Obtain Parameters for Import.

In the Obtain Parameters to Import Key Material dialog box, configure Public Key Type and Encryption Algorithm and click Next.

Key type	Wrapping public key type	Encryption algorithm
Default key of the CMK type	RSA_2048	RSAES_OAEP_SHA_1 RSAES_OAEP_SHA_256 RSAES_PKCS1_V1_5 (not recommended)
Software-protected key	RSA_2048	RSAES_OAEP_SHA_256 RSAES_PKCS1_V1_5 (not recommended)
Hardware-protected key	RSA_2048	RSAES_OAEP_SHA_256 RSAES_PKCS1_V1_5 (not recommended)

Important

RSAES_PKCS1_V1_5: In accordance with Transitioning the Use of Cryptographic Algorithms and Key Lengths developed by the National Institute of Standards and Technology (NIST), the encryption algorithm cannot be used for key transportation after December 31, 2023.

RSAES_OAEP_SHA_1: the Rivest-Shamir-Adleman (RSA) encryption algorithm that uses MGF1 and SHA-1 in the RSAES-OAEP padding mode as defined in PKCS #1 in RFC 3447.
RSAES_OAEP_SHA_256: the RSA encryption algorithm that uses MGF1 and SHA-256 in the RSAES-OAEP padding mode as defined in PKCS #1 in RFC 3447.

Download a wrapping public key and an import token and store them in a secure location.
- Public Key Format
  - If you select PEM Format, the name of the public key file is in the publickey_******.pem format.
  - If you select DER Format, the name of the public key file is in the publickey_******.bin format.
- Import Token: The name of the import token file is in the token_******.txt format.
  Important
  - 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.
  - You must use the wrapping public key together with the import token. You cannot mix a wrapping public key and an import token from different downloads.

Step 3: Use the wrapping public key to encrypt key material

Use the wrapping public key that is downloaded in Step 2: Download a wrapping public key and an import token and the specified wrapping algorithm to encrypt key material.

In this example, OpenSSL is used to generate key material, and the key material is encrypted by using a Rivest-Shamir-Adleman (RSA) public key and the RSAES_OAEP_SHA_256 encryption algorithm.

Use OpenSSL to generate a random 32-byte number as your key material. If you already have key material, skip this step.
```
openssl rand -out KeyMaterial.bin 32
```
Encrypt the key material by using the specified encryption algorithm.
```
openssl pkeyutl -encrypt -in KeyMaterial.bin -inkey PublicKey.bin -keyform DER -pubin -out EncryptedKeyMaterial.bin -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256
```
Note
- In the sample code, the RSAES_OAEP_SHA_256 encryption algorithm is used.
- In the sample code, the public key file is in the DER format. If you select PEM Format when you download the public key file, you must replace -keyform DER in the sample code with -keyform PEM.
- Replace PublicKey.bin with the name of the public key file that is downloaded in Step 2: Download a wrapping public key and an import token.
Encode the encrypted key material in Base64 and save the encoded key material to a text file.
```
openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt
```
Note
In the sample code, the EncryptedKeyMaterial_base64.txt file contains the key material.

Step 4: Import key material

On the key details page, click Import Key Material on the Key Material tab. In the Import Wrapped Key Material dialog box, configure the parameters and click OK.

Parameter	Description
Wrapped Key Material	Upload the key material file that is generated in Step 3: Use the wrapping public key to encrypt key material.
Import Token	Upload the import token file that is downloaded in Step 2: Download a wrapping public key and an import token.
Key Material Expired On	You can select Never Expire or specify an expiration time. Important If you specify an expiration time for key material, KMS deletes the key material when the expiration time is reached, and you can no longer use the key material. If you want to reuse the key material, you can reimport the same key material into the key.

After you import the key material, the status of the key changes from Pending Import to Enabling.

FAQ

Can I delete key material?

Yes, you can delete key material.

Important

After imported key material expires or is deleted, the key that uses the key material becomes unavailable until you reimport the same key material.

Directly delete key material
- KMS console: On the details page of the key, click Delete Key Material on the Key Material tab.
- KMS API: Call the DeleteKeyMaterial operation to delete key material. This operation does not delete your key.
KMS deletes key material
Specify an expiration time for key material when you import the key material. KMS deletes the key material when the expiration time is reached.

How do I reimport the same key material?

After key material of a key expires or is deleted, you can reimport the same key material to continue using the key.

Delete the expired key material.
On the key details page, click the Key Material tab and then click Delete Key Material.
Re-download a wrapping public key and an import token. For more information, see Step 2: Download a wrapping public key and an import token.
Note
The key wrapping process does not affect the content of key material. You can use a different wrapping public key and a different wrapping algorithm to reimport the same key material.
Use the wrapping public key to encrypt the key material. For more information, see Step 3: Use the wrapping public key to encrypt key material.
Note
The key material must be the same as the expired key material.
Import the encrypted key material by using the import token. For more information, see Step 4: Import key material.

How do I view the key material origin of a key?

Method 1: Use the KMS console
- Default key: On the Keys page, click the Default Key tab, find the key that you want to manage, and then click Details in the Actions column. On the details page, view the value of Key Material Source.
- Software-protected keys and hardware-protected keys: On the Keys page, click the Keys tab, select the ID of the KMS instance from the Instance ID drop-down list, find the key that you want to manage, and then click Details in the Actions column. On the details page, view the value of Key Material Source.
Method 2: Call the DescribeKey operation
If the value of Origin is EXTERNAL, the key material is imported. If the value of Origin is Aliyun_KMS, KMS generated the key material.

How do I rotate a key that uses external key material?

KMS does not support automatic rotation for a key that uses external key material. If you want to rotate a key that uses external key material, you must create a different key and import different key material into the key.

Key Management Service:Import key material into a symmetric key

Features

Usage notes

Prerequisites

Step 1: Create a symmetric key that has an external key material origin

Default key of the CMK type

Software-protected key

Hardware-protected key

Step 2: Download a wrapping public key and an import token

Step 3: Use the wrapping public key to encrypt key material

Step 4: Import key material

FAQ

Can I delete key material?

How do I reimport the same key material?

How do I view the key material origin of a key?

How do I rotate a key that uses external key material?

References