Key Management Service:Import key material into a symmetric key

Features

A key is a basic resource in KMS, consisting of a key ID, basic metadata (such as key status), and key material. When you create a key, you can choose to let KMS generate the key material, or choose an external key material origin. If you choose an external key material origin, you need to import the external key material into the key. This feature is commonly referred to as Bring Your Own Key (BYOK). For the support of different KMS key management types for importing key material, see the following table. For more information about key management types, see Key management types and key specifications.

Usage notes

• Make sure you use a random number generator that meets the requirements to generate key material.

• After you import key material into a key for the first time, the key is bound to that key material and no longer supports importing other key material.

• You can import the same key material into a KMS key multiple times as needed, but you cannot import different key material into the same KMS key.

• If the key material of a key expires or is deleted, you can import the same key material again to make the key usable again. Imported key material cannot be exported. Store your key material securely.

Applicable scope

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

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

Before importing key material, create a symmetric key with an external key material origin.

After creation, the key status is Pending Import.

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

The parameters for importing key material include a wrapping public key and an import token. The wrapping public key is used to encrypt the key material and protect your key material during the import process. The import token is used to import the key material.

1. Find the target key and click Details in the Actions column. In the Key Material section, click Obtain Parameters for Import.

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

   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)

3. Download the wrapping public key and import token, and store them securely.

   • Public Key Format:

     • DER Format: The downloaded file is named WrappingPublicKey**.bin by default.

     • PEM Format: The downloaded file is named WrappingPublicKey**.pem by default.

   • Import Token: The downloaded file is named ImportToken***.txt by default.

     Important

     • An import token is valid for 24 hours and can be reused within this 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 as a pair. You cannot use a wrapping public key from one download with an import token from another.

Step 3: Encrypt the key material using the wrapping public key

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

1. Use OpenSSL to generate a 32-byte random number as key material. Skip this step if you already have key material.

   Note

   If you are creating an HMAC key, refer to HMAC key material length for the required number of bytes, replace the byte count, and then generate the key material.

   openssl rand -out KeyMaterial.bin 32

2. Encrypt the key material based on the specified encryption algorithm.

   Note

   The encryption algorithm in the example uses RSAES_OAEP_SHA_256.

   The example uses DER format for the public key. If you selected PEM format when downloading the public key file, replace -keyform DER with -keyform PEM in the example.

   Replace PublicKey.bin with the name of the public key file downloaded in Step 2: Download a wrapping public key and an import token.

   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

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

   EncryptedKeyMaterial_base64.txt is the key material file that can be imported into KMS.

Step 4: Import the key material

On the key details page, click Import Key Material. In the Import Wrapped Key Material dialog box, complete the settings and click OK.

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

Appendix

FAQ

• Can I delete key material?

  Yes.

  After imported key material expires or is deleted, the key becomes unusable. You need to import the same key material again to use the key normally.

  • Delete key material directly

    • Console: On the key details page, in the Key Material section, click Delete Key Material.

    • API: Call the DeleteKeyMaterial operation to delete the key material. This operation does not delete your key.

  • Automatic deletion by KMS after expiration

    Set an expiration time when importing key material. KMS will delete the expired key material after the specified time.

• How do I re-import the same key material?

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

  1. Delete the expired key material.

     On the key details page, click the Key Material tab and click Delete Key Material.

  2. Download a new wrapping public key and import token. For more information, see Step 2: Download a wrapping public key and an import token.

     The key wrapping process does not affect the content of the key material. Therefore, you can use a different wrapping public key and wrapping algorithm to import the same key material.

  3. Encrypt the key material using the wrapping public key. For more information, see .

     The key material must be the same as the previously expired key material.

  4. Import the encrypted key material using the import token. For more information, see Step 4: Import the key material.

• How do I check whether the key material was imported from an external source or generated by KMS?

  • Method 1: Check in the KMS console.

    • Default key: On the Keys page, click the Default Keys tab, find the target key, and click Details in the Actions column. On the details page, check Key Material Origin.

    • Software-protected key, Hardware-protected key: On the Keys page, click the Customer Master Keys tab, select the Instance ID, find the target key, and click Details in the Actions column. On the details page, check Key Material Origin.

  • Method 2: Call the DescribeKey operation.

    If the Origin value is EXTERNAL, the key material was imported from an external source. If the Origin value is Aliyun_KMS, the key material was generated by KMS.

• How do I rotate a key that uses imported key material?

  • Software-protected symmetric keys with imported external key material support only immediate manual rotation and do not support automatic periodic rotation. For more information, see BYOK key rotation.

  • Software-protected asymmetric keys with imported external key material do not support rotation.

  • Hardware-protected keys (both symmetric and asymmetric) with imported external key material do not support rotation.

Related documentation

• Understanding KMS keys

• Key management types and key specifications

• Import key material for an asymmetric key