Importing Key Materials

Constraints

• The HMAC key algorithm does not support the import of key materials.

Operation Process

Step 1: Creating a Key Whose Material Source Is External

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 on the left. Choose Security & Compliance > Data Encryption Workshop.
4. 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 5.

Step 2: Downloading Wrapping Key and Importing Token

Downloading the Wrapping Key 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.

Downloading the Wrapping Key on the KMS Console

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 on the left. Choose Security & Compliance > Data Encryption Workshop.
4. On the Custom Keys tab page, locate the key created by Step 1: Creating a Key Whose Material Source Is External and click Import Key Material in the Operation column.
5. 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	Setting
   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.

6. Click Download and Continue 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 Material.

Step 3: Using wrapping key to Encrypt Key Materials

Symmetric Key

• 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

Asymmetric Key

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

• If the key material is downloaded by calling the API or the key material already exists, run the Importing Existing Key Materials.
• To download the key material using the KMS console, run the Importing Key Material.

Importing Existing Key Materials

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 on the left. Choose Security & Compliance > Data Encryption Workshop.
4. On the Custom Keys tab page, locate the key created by Step 1: Creating a Key Whose Material Source Is External and click Import Key Material in the Operation column.
5. 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	Setting
   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.

6. Click Use Existing Key Material. In the Import Key Material area, enter Key Material.
   Figure 4 Import key materials
   

   Table 5 Key material description

   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.

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

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

Importing Key Material

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

   Table 7 Key material description

   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 the Key imported successfully message 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 list of CMKs. The default status of an imported CMK is Enabled.