doc-exports/docs/kms/umn/kms_01_0089.html

Importing Key Materials

If you want to use your own key materials instead of the KMS-generated materials, you can use the console to import your key materials to KMS. CMKs 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.

Procedure

1. Log in to the management console.
2. Click in the upper left corner of the management console and select a region or project.
3. Click . Choose Security > Key Management Service. The Key Management Service page is displayed.
4. Click Import Key. The Import Key dialog box is displayed.
5. Configure key parameters.
   Figure 1 Creating an empty key
   
   • Alias is the alias of the key to be created.
     

     • You can enter digits, letters, underscores (_), hyphens (-), colons (:), and slashes (/).
     • You can enter up to 255 characters.
   • (Optional) Description is the description of the custom key.
     

     You can enter up to 255 characters.

6. (Optional) Add tags to the custom key as needed, and enter the tag key and tag value.
   

   • If a custom key has been created without any tag, you can add a tag to the custom key later if needed. Click the alias of the custom key, choose the Tags tab, and click Add Tag.
   • The same tag (including tag key and tag value) can be used for different custom keys. However, under the same custom key, one tag key can have only one tag value.
   • A maximum of 20 tags can be added for one custom key.
   • If you want to delete a tag from the tag list when adding multiple tags, you can click Delete in the row where the tag to be added is located to delete the tag.

7. Click security and durability to understand the security and durability of the imported key.
8. Select I understand the security and durability of using an imported key, and create a custom key whose key material is empty.
9. Click Next to go to the Download the Import Items step. Select a key wrapping algorithm based on Table 1.
   Figure 2 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.

   

   If you stop a key material import process and want to try again, click Import Key Material in the row of the required custom key, and import key material in the displayed dialog box.

10. Obtain the wrapping key and import token. If you already have a key material, skip this step.
    1. Obtain the wrapping key and import token.
       • Method 1: Click Download and Continue to download the wrapping key file, as shown in Figure 3.
         Figure 3 Downloaded 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 import wizard automatically transfers the import token. If you close the wizard before completing the import, the token will automatically become invalid. To retry import, open the import wizard again.

       • Method 2: Obtain the wrapping key and import token by calling APIs.
         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.
    2. Use the wrapping key to encrypt the key material.
       

       After performing this step, you will obtain either of the following files:

       Symmetric key scenario: EncryptedKeyMaterial.bin (key material)

       Asymmetric key scenario: 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. Generate a key material (256-bit symmetric key) and save it as PlaintextKeyMaterial.bin.
          • If the AES256 symmetric key algorithm is used, run the following command on the client where the OpenSSL tool has been installed:

            openssl rand -out PlaintextKeyMaterial.bin 32

          • If the RSA and ECC asymmetric key algorithms are used, run the following command on the client where the OpenSSL tool has been installed:
            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 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

       3. (Optional) 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. Perform the following operations:
            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.

11. The Import Key Material page is displayed.

    Table 3 Parameters for importing key materials (for symmetric keys)

    Parameter	Description
    Key ID	Random ID of a CMK generated during the CMK creation
    Key material	Import a key material. For example, use the EncryptedKeyMaterial.bin file in 10.b.ii.

    Table 4 Parameters for importing key materials (for asymmetric keys)

    Parameter	Description
    Key ID	Random ID of a CMK generated during the CMK creation
    Temporary key material	Import a temporary key material. For example, select the EncryptedKeyMaterial.bin file in 10.b.ii.
    Private key ciphertext	Select private key ciphertext. For example, select the out_rsa_private_key.der file in 10.b.iii.

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

    Table 5 Parameters for importing a key token

    Parameter	Description
    Key ID	Random ID of a CMK generated during the CMK creation
    Key import token	Select the import token obtained via API in 12.b.
    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.

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

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

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

Parent topic: Creating CMKs Using Imported Key Materials