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.

Operation Process

Scenario	Procedure
Using existing key materials	Creating a key whose material source is external: Create an empty key whose material source is external. Importing key material (existing key material): Import key material and token to the created empty key.
Downloading key materials by calling APIs	Creating a key whose material source is external: Create an empty key whose material source is external. Downloading wrapping key and importing a token (by calling the API): Download the wrapping key and import the token by calling the API. Using wrapping key to encrypt key material: Use HSM or OpenSSL to encrypt wrapping key into key material. Importing key material (existing key material): Import key material and token to the created empty key.
Downloading key materials on the KMS console	Creating a key whose material source is external: Create an empty key whose material source is external. 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. Using wrapping key to encrypt key material: Use HSM or OpenSSL to encrypt wrapping key into key material. Importing Key Material (Continue Importing Key Material): Import the key material to the created empty key.

Step 1: Creating a Key Using External Materials

Log in to the management console.
Click in the upper left corner of the management console and select a region or project.
Click on the left and choose Security > Key Management Service.
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 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.

Downloading the Wrapping Key By Calling APIs

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
}
```
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
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

Log in to the management console.
Click in the upper left corner of the management console and select a region or project.
Click on the left and choose Security > Key Management Service.
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.

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.

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)

Symmetric Keys

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.

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

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 Keys

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.

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

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

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

Importing Existing Key Materials

Log in to the management console.
Click in the upper left corner of the management console and select a region or project.
Click on the left and choose Security > Key Management Service.
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.

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.

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

Figure 4 Importing 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.

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

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

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 Materials

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

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

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

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.