Key Management Service:Import key material into a symmetric key

Background information

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.

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.

• If the key material of a key expires or is deleted, you can reimport the same key material for the key to make the key usable again. After the key material is imported, you cannot export the key material. Therefore, we recommend that you store the key material in a secure location.

Prerequisites

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

Default key of the CMK type

1. Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Keys.

2. Click the Default Key tab. Then, find the default key of the CMK type 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. Note Read and select I understand the implications of using the external key materials.

Hardware-protected key

1. Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Keys.

2. 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.

3. 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	The key material origin. Select External. Note Read and select I understand the implications of using the external key materials.

Step 2: Download a public key and an import token

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

1. 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.

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

   Public key type	Encryption algorithm
   RSA_2048	RSAES_OAEP_SHA_256 (recommended) RSAES_PKCS1_V1_5 Important 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.

3. Download a public key and an import token and store them in a secure location.

   • Public Key Format

     • If you select DER Format, the name of the public key file is in the publickey_key-******.bin format.

     • If you select PEM Format, the name of the public key file is in the publickey_key-******.pem format.

   • Import Token: The name of the import token file is in the token_key-******.txt format.

     Important

     The import token is valid for 24 hours and can be repeatedly used within this period. After 24 hours, you must download a new import token and public key.

Step 3: Encrypt key material

Use the public key that is downloaded in Step 2: Download a public key and an import token to encrypt your 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.

1. Use OpenSSL to generate a random 32-byte number as your key material. If you have key material, skip this step.

   openssl rand -out KeyMaterial.bin 32

2. 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 you downloaded in Step 2: Download a public key and an import token.

3. Encode the encrypted key material in Base64 and save the 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. In the Import Wrapped Key Material dialog box, configure the parameters and click OK.

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

FAQ

References

• Overview

• KMS types and specifications

• Import key material into an asymmetric key