Help Center/ Data Encryption Workshop/ User Guide/ Key Management Service/ Creating a Key/ Importing a Key
Updated on 2025-09-15 GMT+08:00
View PDF
Share

Importing a Key

If you want to use your own key materials instead of the KMS-generated materials, you can import your key materials to KMS on the console. Keys created using imported materials and KMS-generated materials are managed together by KMS.

This section describes how to import key materials on the KMS console.

Constraints

  • Key materials cannot be imported for HMAC digest keys and cannot be deleted for asymmetric keys.
  • When a replica key is being created, the key materials of the CMK are synchronized. After the key materials are expired, import the key materials again in each region.

Important Notes

Pay attention to the following when you import key materials:

  • Security

    You need to ensure that random sources meet your security requirements when using them to generate key materials. When using the import key materials function, you need to be responsible for the security of your key materials. Save the original backup of the key material so that the backup key material can be imported to the KMS in time when the key material is deleted accidentally.

  • Availability and durability

    Before importing the key material into KMS, you need to ensure the availability and durability of the key material.

  • Association

    When a key material is imported to a custom key, the custom key is permanently associated with the key material. Other key materials cannot be imported into the custom key.

  • Uniqueness

    If you use the custom key created using the imported key material to encrypt data, the encrypted data can be decrypted only by the custom key that has been used to encrypt the data, because the metadata and key material of the custom key must be consistent.

Operation Process

Scenario

Procedure

Using existing key materials
  1. Creating a key whose material source is external: Create an empty key whose material source is external.
  2. Importing key material (existing key material): Import key material and token to the created empty key.

Downloading key materials by calling APIs
  1. Creating a key whose material source is external: Create an empty key whose material source is external.
  2. Downloading wrapping key and importing a token (by calling the API): Download the wrapping key and import the token by calling the API.
  3. Using wrapping key to encrypt key material: Use HSM or OpenSSL to encrypt wrapping key into key material.
  4. Importing key material (existing key material): Import key material and token to the created empty key.

Downloading key materials on the KMS console
  1. Creating a key whose material source is external: Create an empty key whose material source is external.
  2. Downloading wrapping key and importing the token (from the KMS console): Download wrapping key from the KMS console. The import token is automatically guided by the console.
    NOTICE:

    After downloading wrapping key, do not close or exit the Import Key Material dialog box. After the key material is encrypted, you need to perform the Import Key Material (Continue to Import Key Material) in this dialog box.

  3. Using wrapping key to encrypt key material: Use HSM or OpenSSL to encrypt wrapping key into key material.
  4. Importing Key Material (Continue Importing Key Material): Import the key material to the created empty key.

Step 1: Creating a Key Using External Materials

  1. Log in to the DEW console.
  2. Click in the upper left corner and select a region or project.
  3. Click Create Key in the upper right corner of the page to create an empty key whose Source is External. For details about more parameters, see Step 4.

Step 2: Downloading the Wrapping Key and Importing Token

The key management function provides two download modes:
  • Download the wrapping key and import token by calling the API.
  • Download the wrapping key from the KMS console. The import token is automatically passed by the console. Therefore, do not close or exit the Import Key Material dialog box after the key material is downloaded. Otherwise, the imported token will automatically become invalid.
  1. Call the get-parameters-for-import API to obtain the wrapping key and import token.

    • public_key: content of the wrapping key (Base-64 encoding) returned after the API call
    • import_token: content of the import token (Base-64 encoding) returned after the API call
    The following example describes how to obtain the wrapping key and import token of a CMK (ID: 43f1ffd7-18fb-4568-9575-602e009b7ee8; algorithm: RSAES_OAEP_SHA_256).
    • Example request 
      {      
    "key_id": "43f1ffd7-18fb-4568-9575-602e009b7ee8",
    "wrapping_algorithm":"RSAES_OAEP_SHA_256"
}
    • Example response 
      {
    "key_id": "43f1ffd7-18fb-4568-9575-602e009b7ee8",    
    "public_key":"public key base64 encoded data",
    "import_token":"import token base64 encoded data",
    "expiration_time":1501578672
}

  2. Save the wrapping key and convert its format. Only the key material encrypted using the converted wrapping key can be imported to the management console.

    1. Copy the content of the wrapping key public_key, paste it to a .txt file, and save the file as PublicKey.b64.
    2. Use OpenSSL to run the following command to perform Base-64 coding on the content of the PublicKey.b64 file to generate binary data, and save the converted file as PublicKey.bin:

      openssl enc -d -base64 -A -in PublicKey.b64 -out PublicKey.bin

  3. Save the import token, copy the content of the import_token token, paste it to a .txt file, and save the file as ImportToken.b64.
  1. Log in to the DEW console.
  2. Click in the upper left corner and select a region or project.
  3. In the Custom Keys tab, locate the key created by Step 1: Creating a Key Using External Materials and click Import Key Material in the Operation column.
  4. In the Download the Import Items area, select a key wrapping algorithm based on Key wrapping algorithm.

    Figure 1 Obtaining the wrapping key and import token


    Table 1 Key wrapping algorithms

    Algorithm

    Description

    Configuration

    RSAES_OAEP_SHA_256

    RSA algorithm that uses OAEP and has the SHA-256 hash function

    Select an algorithm based on your HSM functions.

    If the HSMs support the RSAES_OAEP_SHA_256 algorithm, use RSAES_OAEP_SHA_256 to encrypt key materials.

  5. Click Download Key Material to download the wrapping key file, as shown in Figure 2.

    Figure 2 Downloading a file
    • wrappingKey_KeyID is the wrapping key. It is encoded in binary format and used to encrypt the wrapping key of the key material.
    • Import token: You do not need to download it. The import wizard automatically transfers the import token. If you close the wizard before completing the import, the token will automatically become invalid.

    The wrapping key expires in 24 hours. If the wrapping key is invalid, download it again.

    The console automatically passes the import token. Therefore, do not close or exit the Import Key Material dialog box after the key material is downloaded. Otherwise, the imported token will automatically become invalid.

    After downloading wrapping key, use it to encrypt the key material. Then, import the key material in the Import Key Material dialog box. For details, see Importing Key Materials.

Step 3: Using Wrapping Key to Encrypt Key Materials

Symmetric and asymmetric key encryption modes generate different key materials.
  • Symmetric key: The key material is EncryptedKeyMaterial.bin.
  • Asymmetric key: EncryptedKeyMaterial.bin (temporary key material) and out_rsa_private_key.der (private key ciphertext)
  • Method 1: Use the downloaded wrapping key to encrypt key materials on your HSM. For details, see the operation guide of your HSM.
  • Method 2: Use OpenSSL to generate a key material and use the downloaded wrapping key to encrypt the key material.

    If you need to run the openssl pkeyutl command, ensure your OpenSSL version is 1.0.2 or later.

    1. To generate a key material for a 256-bit symmetric key, on the agent where OpenSSL has been installed, run the following command to generate the key material and save it as PlaintextKeyMaterial.bin:
      • AES256 symmetric key

        openssl rand -out PlaintextKeyMaterial.bin 32

    2. Use the downloaded wrapping key to encrypt the key material and save the encrypted key material as EncryptedKeyMaterial.bin.

      If the wrapping key was downloaded from the console, replace PublicKey.bin in the following command with the wrapping key name wrappingKey_keyID.

      Table 2 Encrypting the generated key material using the downloaded wrapping key

      Wrapping Key Algorithm

      Key Material Encryption

      RSAES_OAEP_SHA_256

      openssl pkeyutl -in PlaintextKeyMaterial.bin -inkey PublicKey.bin -out EncryptedKeyMaterial.bin -keyform der -pubin -encrypt -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256
  • Method 1: Use the downloaded wrapping key to encrypt key materials on your HSM. For details, see the operation guide of your HSM.
  • Method 2: Use OpenSSL to generate a key material and use the downloaded wrapping key to encrypt the key material.

    If you need to run the openssl pkeyutl command, ensure your OpenSSL version is 1.0.2 or later.

    1. To generate a key material for a 256-bit symmetric key, on the agent where OpenSSL has been installed, run the following command to generate the key material and save it as PlaintextKeyMaterial.bin:
      • RSA and ECC asymmetric keys
        1. Generate a hexadecimal AES256 key.

          openssl rand -out 0xPlaintextKeyMaterial.bin -hex 32

        2. Convert the hexadecimal AES256 key to the binary format.

          cat 0xPlaintextKeyMaterial.bin | xxd -r -ps > PlaintextKeyMaterial.bin

    2. Use the downloaded wrapping key to encrypt the key material and save the encrypted key material as EncryptedKeyMaterial.bin.

      If the wrapping key was downloaded from the console, replace PublicKey.bin in the following command with the wrapping key name wrappingKey_keyID.

      Table 3 Encrypting the generated key material using the downloaded wrapping key

      Wrapping Key Algorithm

      Key Material Encryption

      RSAES_OAEP_SHA_256

      openssl pkeyutl -in PlaintextKeyMaterial.bin -inkey PublicKey.bin -out EncryptedKeyMaterial.bin -keyform der -pubin -encrypt -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256
    3. To import an asymmetric key, generate an asymmetric private key, use the temporary key material (EncryptedKeyMaterial.bin) to encrypt the private key, and import the encrypted file as the private key ciphertext.
      • Take the RSA4096 algorithm as an example.
        1. Generate a private key.

          openssl genrsa -out pkcs1_rsa_private_key.pem 4096

        2. Convert the format to PKCS8.

          openssl pkcs8 -topk8 -inform PEM -in pkcs1_rsa_private_key.pem -outform pem -nocrypt -out rsa_private_key.pem

        3. Convert the PKCS8 format to the DER format.

          openssl pkcs8 -topk8 -inform PEM -outform DER -in rsa_private_key.pem -out rsa_private_key.der -nocrypt

        4. Use a temporary key material to encrypt the private key.

          openssl enc -id-aes256-wrap-pad -K $(cat 0xPlaintextKeyMaterial.bin) -iv A65959A6 -in rsa_private_key.der -out out_rsa_private_key.der

          By default, the -id-aes256-wrap-pad algorithm is not enabled in OpenSSL. To wrap a key, upgrade OpenSSL to the latest version and patch it first. For details, see FAQs.

Step 4: Importing Key Materials

The import method varies depending on the key material download method.

  1. Log in to the DEW console.
  2. Click in the upper left corner and select a region or project.
  3. In the Custom Keys tab, locate the key created by Step 1: Creating a Key Using External Materials and click Import Key Material in the Operation column.
  4. In the Download the Import Items area, select a key wrapping algorithm based on Key wrapping algorithm.

    Figure 3 Obtaining the wrapping key and import token


    Table 4 Key wrapping algorithms

    Algorithm

    Description

    Configuration

    RSAES_OAEP_SHA_256

    RSA algorithm that uses OAEP and has the SHA-256 hash function

    Select an algorithm based on your HSM functions.

    If the HSMs support the RSAES_OAEP_SHA_256 algorithm, use RSAES_OAEP_SHA_256 to encrypt key materials.

  5. Click Use Existing Key Material. In the Import Key Material area, enter Key Material.

    Figure 4 Importing key materials


    Table 5 Key materials

    Scenario

    Description

    Symmetric key

    Use the key material encrypted by wrapping key.

    For example, the EncryptedKeyMaterial.bin file in Step 3: Using Wrapping Key to Encrypt Key Materials.

    Asymmetric key

    Use the temporary key material and private key ciphertext encrypted by wrapping key.

    For example, the temporary key material EncryptedKeyMaterial.bin and private key ciphertext out_rsa_private_key.der in Step 3: Using Wrapping Key to Encrypt Key Materials.

  6. Click Next. In the Import Key Token area, set parameters based on Table 6.

    Figure 5 Importing a key token
    Table 6 Parameters for importing a key token

    Parameter

    Description

    Key ID

    Random ID of a CMK generated during the CMK creation

    Key import token

    Enter the import token obtained in Downloading the Wrapping Key By Calling APIs.

    Key material expiration mode
    • Key material will never expire: You use this option to specify that key materials will not expire after import.
    • Key material will expire: You use this option to specify the expiration time of the key materials. By default, key materials expire in 24 hours after import.

      After the key material expires, the system automatically deletes the key material within 24 hours. Once the key material is deleted, the key cannot be used and its status changes to Pending import.

  7. Click OK. When message "Key imported successfully" is displayed in the upper right corner, the materials are imported.

    Key materials can be imported when they match the corresponding key ID and token.

    Your imported materials are displayed in the key list. The default status of an imported key is Enabled.

  1. In the Import Key Material dialog box (Step 5) on the management console, add the Key Material file in the Import Key Material configuration item.

    Figure 6 Importing key materials


    Table 7 Key materials

    Scenario

    Description

    Symmetric key

    Use the key material encrypted by wrapping key.

    For example, the EncryptedKeyMaterial.bin file in Step 3: Using Wrapping Key to Encrypt Key Materials.

    Asymmetric key

    Use the temporary key material and private key ciphertext encrypted by wrapping key.

    For example, the temporary key material EncryptedKeyMaterial.bin and private key ciphertext out_rsa_private_key.der in Step 3: Using Wrapping Key to Encrypt Key Materials.

  2. Click Next to go to the Import Key Token step. Configure the parameters as described in Table 8.

    Figure 7 Importing a key token
    Table 8 Parameters for importing a key token

    Parameter

    Description

    Key ID

    Random ID of a CMK generated during the CMK creation

    Key material expiration mode
    • Key material will never expire: You use this option to specify that key materials will not expire after import.
    • Key material will expire: You use this option to specify the expiration time of the key materials. By default, key materials expire in 24 hours after import.

      After the key material expires, the system automatically deletes the key material within 24 hours. Once the key material is deleted, the key cannot be used and its status changes to Pending import.

  3. Click OK. When message "Key imported successfully" is displayed in the upper right corner, the materials are imported.

    Key material can be successfully imported when it matches the corresponding key ID.

    Your imported materials are displayed in the key list. The default status of an imported key is Enabled.

Deleting Key Materials

After the imported key materials are expired or deleted, the key using the materials becomes unavailable and its status changes to Pending import. In this case, you need to import the same key materials again. Only by then can the custom key decrypts all data encrypted before the key material is deleted.

Key materials cannot be deleted for asymmetric keys.

To delete key materials, use either of the following methods:

  • Method 1: KMS deletes expired key materials.

    When you import key materials, specify the expiration time. KMS will delete the key materials after they expire.

  • Method 2: Delete key materials on the console.
    1. Locate the target key material and choose More > Delete Key Material.
    2. In the displayed dialog box, enter DELETE, and click OK. When Key material deleted successfully is displayed in the upper right corner, the key materials are deleted.

Importing the Same Key Materials Again

When key materials are expired or deleted, you need to import the same materials again to continue using the key.

  1. Download the wrapping public key and import token again. For details, see Step 2: Downloading the Wrapping Key and Importing Token.

    Key wrapping will not affect key materials. Therefore, you can use different wrapping public keys and algorithms to import the same key materials.

  2. Use the wrapping public key to encrypt the key materials. For details, see Step 3: Using Wrapping Key to Encrypt Key Materials.

    The key materials must be those used before expiration.

  3. Use the import token to import the encrypted key materials. For details, see Step 4: Importing Key Materials.
Parent Topic: Creating a Key