Import key material into a symmetric key - Key Management Service

To manage and control your key material, you can create a key with an external origin in a Key Management Service (KMS) instance. Then, you can import your own key material. This topic describes how to import key material into a symmetric key.

Important

If your software key management instance or hardware key management instance does not support importing key material, or if an error occurs during the import, contact Alibaba Cloud technical support to upgrade the instance.

Function introduction

Keys are basic resources in KMS. A key consists of a key ID, basic metadata such as the key status, and key material. When you create a key, you can choose to have KMS generate the key material or use key material from an external source. If you choose an external source, you must import your external key material into the key. This feature is often called Bring Your Own Key (BYOK).

The following table describes the KMS key management types that support importing key material. For more information about key management types, see Key management types and key specifications.

: Indicates that importing the corresponding key material is supported.
: Indicates that importing the corresponding key material is not supported.

Key management type	Import symmetric key material	Import asymmetric key material
Default key	Customer master key: √ Service key: ×	Customer master key: × Service key: ×
Software-protected key	√	√
Hardware-protected key	√	×

Usage notes

Make sure that a compliant random number generator is used to generate the key material.
After you import key material into a key, the key is permanently bound to that key material. You cannot import different key material into the key.
You can import the same key material into a KMS key multiple times, but you cannot import different key material into the same KMS key.
If the key material for a key expires or is deleted, you can re-import the same key material to make the key available again. You cannot export key material after it is imported. Therefore, store your key material securely.

Prerequisites

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

Note

You do not need to purchase a KMS instance to import key material for a default customer master key.

Step 1: Create a symmetric key with an external key material origin

Before you import key material, you must create a symmetric key with an external key material origin.

Default key (customer master key)

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

On the Default Keys tab, click Enable in the Actions column for a customer master key. Then, on the Create Key tab, set the parameters and click OK.

Parameter	Description
Key Alias	An identifier for the key. It can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).
Description	A description of the key.
Advanced Settings	The origin of the key material. 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 navigation pane on the left, choose Resource > Keys.
On the Customer Master Keys tab, select a software key management instance from the Instance ID list and click Create Key.

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

Configuration item	Description
Key Type	Select Symmetric Key. Important If you are creating a key to encrypt a secret value, select Symmetric Key.
Key Specifications	Symmetric key specification: Aliyun_AES_256.
Key Usage	ENCRYPT/DECRYPT: The key is used for data encryption and decryption.
Key Alias	An alias for the key. It can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).
Tag Key, Tag Value	A tag for the key to help you categorize and manage keys. Each tag consists of a key-value pair that includes a tag key and a tag value. 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 (:), at signs (@), and spaces. A tag key cannot start with `aliyun` or `acs:`. You can configure up to 20 key-value pairs for each key.
Description	A description of the key.
Advanced Settings	Policy Settings: For more information, see Overview of key policies. Key Material Origin: Select External (Import Key Material). Note Read and select I understand the methods and implications of using external key material.

Hardware-protected key

Log on to the KMS console. In the top navigation bar, select a region. In the navigation pane on the left, choose Resource > Keys.
On the Customer Master Keys tab, select a hardware key management instance for the Instance ID and click Create Key.

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

Configuration item	Description
Key Type	Select Symmetric Key. Important If you are creating a key to encrypt a secret value, select Symmetric Key.
Key Specifications	Symmetric key specifications: Aliyun_AES_256, Aliyun_AES_192, Aliyun_AES_128.
Key Usage	The purpose of the key. Valid values: Encrypt/Decrypt: Data encryption and decryption. Sign/Verify: Generation and verification of digital signatures.
Key Alias	An alias for the key. It can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).
Tag Key, Tag Value	A tag for the key to help you categorize and manage keys. Each tag consists of a key-value pair that includes a tag key and a tag value. 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 (:), at signs (@), and spaces. A tag key cannot start with `aliyun` or `acs:`. You can configure up to 20 key-value pairs for each key.
Description	A description of the key.
Advanced Settings	Policy Settings: For more information, see Overview of key policies. Key Material Origin: Select External (Import Key Material). Note Read and select I understand the methods and implications of using external key material.

The key is created with a status of Pending Import.

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

The parameters required to import key material consist of a wrapping public key and an import token. The wrapping public key is used to encrypt the key material to protect it during the import process. The import token is required to perform the import operation.

Find the target key and click Details in the Actions column. Then, in the Key Material and Version section, click Import Initial Key Material.

In the Import Key Material panel, select a Public Key Type and an Encryption Algorithm.

Key management type	Wrapping public key type	Encryption algorithm
Default key (customer master key)	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: The National Institute of Standards and Technology (NIST) states in its guidelines Transitioning the Use of Cryptographic Algorithms and Key Lengths that this encryption algorithm should no longer be used for encrypting transport keys after December 31, 2023.

RSAES_OAEP_SHA_1: RSA encryption that uses the RSAES-OAEP scheme defined in RFC 3447/PKCS#1, with MGF1 and SHA-1.
RSAES_OAEP_SHA_256: RSA encryption that uses the RSAES-OAEP scheme defined in RFC 3447/PKCS#1, with MGF1 and SHA-256.

Download the wrapping public key and the import token, and store them securely.
- Wrapping Key Format:
  - pem: The default name of the downloaded file is publickey_******.pem.
  - der: The default name of the downloaded file is publickey_******.bin.
- Import Token: The default name of the downloaded file is token_******.txt.
  Important
  - The import token is valid for 24 hours and can be used multiple times within its validity period. After it expires, you must obtain a new import token and public key.
  - The wrapping public key and the import token must be used together. You cannot use a wrapping public key from one download with an import token from another download.

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

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

The following example shows how to use OpenSSL to generate key material and encrypt it with an RSA public key and the RSAES_OAEP_SHA_256 algorithm.

Use OpenSSL to generate a 32-byte random number as your key material. If you already have key material, skip this step.
```
openssl rand -out KeyMaterial.bin 32
```
Encrypt the key material with 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
- The example code uses the RSAES_OAEP_SHA_256 encryption algorithm.
- 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 with -keyform PEM in the sample code.
- Replace PublicKey.bin with the name of the public key file you downloaded in Step 2: Download a wrapping public key and an import token.
Base64-encode the encrypted key material and save it to a text file.
```
openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt
```
Note
The EncryptedKeyMaterial_base64.txt file contains the key material to be imported into KMS.

Step 4: Import the key material

In the Import Key Material panel, set the parameters and click OK.

Parameter	Description
Wrapped Key Material	Upload the key material file generated in Step 3: Use the wrapping public key to encrypt the key material.
Import Token	Upload the token file downloaded in Step 2: Download a wrapping public key and an import token.
Set Expiration Date	You can select Never Expire or specify a custom expiration time. Important If you set an expiration time for the key material, KMS deletes the expired key material at the specified time. You will not be able to use the key material. To resume using it, you can re-import the same key material for the key.

After the key material is imported, the key status changes from Pending Import to Enabling.

FAQ

Can I delete key material?

Deletion is supported.

Important

After imported key material expires or is deleted, its key becomes unusable. You must re-import the same key material to use the key again.

Manually delete key material
- In the console, on the key details page, click Delete Key Material in the Key Material and Version section.
- API operation: Call the DeleteKeyMaterial operation to delete the key material. This operation does not delete your key.
Configure key material to be automatically deleted upon expiration
When you import key material, you can set an expiration time. KMS deletes the key material after the specified time.

How do I re-import the same key material?

After key material expires or is deleted, you can re-import the same key material to continue using the key.

Delete the expired key material.
On the key details page, click the Key Material and Version tab and then click Delete Key Material.
Download a new wrapping public key and 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 the key material. Therefore, you can use a different wrapping public key and a different encryption algorithm to import 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 the key material.
Note
The key material must be the same as the one that was previously imported.
Use the import token to import the encrypted key material. For more information, see Step 4: Import the key material.

How do I determine if key material is imported or generated by KMS?

Method 1: Check in the Key Management Service console.
- Default key: On the Keys page, click the Default Keys tab. Locate the desired key and click Details in the Actions column. The Key Material Origin is displayed on the details page.
- Software-protected and hardware-protected keys: On the Keys page, click the Customer Master Keys tab. Select an Instance ID and find the target key. Then, click Details in the Actions column. On the details page, you can view the Key Material Origin.
Method 2: Call the DescribeKey operation.
If the value of Origin is EXTERNAL, the key material was imported. If the value of Origin is Aliyun_KMS, the key material was generated by KMS.

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

For software-protected symmetric keys that use imported key material, only immediate manual rotation is supported, not automatic periodic rotation. For more information, see Rotate a Bring-Your-Own-Key (BYOK) key.
Rotation is not supported for software-protected asymmetric keys that use imported key material.
Rotation is not supported for hardware-protected keys (both symmetric and asymmetric) that use imported key material.

Key Management Service:Import key material into a symmetric key

Function introduction

Usage notes

Prerequisites

Step 1: Create a symmetric key with an external key material origin

Default key (customer master key)

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 the key material

Step 4: Import the key material

FAQ

Can I delete key material?

How do I re-import the same key material?

How do I determine if key material is imported or generated by KMS?

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

References