If you set the Origin parameter to EXTERNAL when you create a customer master key (CMK) for a dedicated Key Management Service (KMS) instance of the Standard edition, Dedicated KMS does not generate symmetric key material in your hardware security module (HSM) cluster. You must import external symmetric key material for the CMK. This topic describes how to import external symmetric key material.

Background information

You can call the DescribeKey operation to view the source of the symmetric key material of an existing CMK. If the value of the Origin parameter is EXTERNAL, the symmetric key material is imported from an external source. In this case, the CMK is considered an external CMK.

If you set the Origin parameter to EXTERNAL, take note of the following points when you import external symmetric key material:
  • Make sure that the source of randomness from which the symmetric key material is generated meets the requirements.
  • The symmetric key material is imported to your HSM cluster. You cannot delete the symmetric key material by calling the DeleteKeyMaterial operation. However, you can call the ScheduleKeyDeletion operation to schedule a CMK deletion task and specify a waiting period for the detection. When the CMK is deleted, the symmetric key material is also deleted.
  • A CMK can have only one piece of symmetric key material. After you import symmetric key material for a CMK, the CMK is bound to the symmetric key material. You can no longer import other symmetric key material for the CMK.
  • The symmetric key material must be a 128-, 192-, or 256-bit symmetric key.

Step 1: Create an external CMK

  1. Log on to the KMS console.
  2. In the top navigation bar, select the region where your dedicated KMS instance of the Standard edition resides.
  3. In the left-side navigation pane, click Dedicated KMS.
  4. Find the dedicated KMS instance that you want to manage and click Manage in the Actions column.
  5. On the User master key tab, click Create Key.
  6. In the Create Key dialog box, configure the Key Spec parameter.
    Dedicated KMS supports the following key types:Aliyun_AES_128, Aliyun_AES_192, and Aliyun_AES_256.
  7. Configure the Alias Name and Description parameters.
  8. Click Advanced and set the Key Material Source parameter to External.
  9. Select I understand the implications of using the external key materials key and click OK.

Step 2: Obtain the parameters that are used to import symmetric key material

The parameters include a public key and an import token. The public key is used to encrypt the symmetric key material.
  1. On the User master key tab, click the ID of the required CMK to go to the key management page.
  2. In the Key Material section, click Obtain Parameters Used to Import Key Material.
  3. In the Obtain Parameters Used to Import Key Material dialog box, configure the Wrapping Key Type parameter and the Wrapping Algorithm parameter and click Next.
    Note

    If you set the Wrapping Key Type parameter to RSA_2048, you can set the Wrapping Algorithm parameter to RSAES_PKCS1_V1_5 or RSAES_OAEP_SHA_256. The default value is RSAES_PKCS1_V1_5. In this example, the default value is used.

  4. Click Download to the right of Public Key Format to download the public key. Click Download to the right of Import Token to download the import token. Then, click Close.

Step 3: Encrypt symmetric key material

The following section describes how to use OpenSSL to encrypt symmetric key material. The encryption algorithm must be the same as the algorithm that you specify when you obtain the parameters that are used to import the symmetric key material. The public key is encoded in Base64. Before you can use the public key, you must decode the public key.

  1. Create symmetric key material. In this example, OpenSSL is used to generate a 32-byte random number. The number is used as the symmetric key material.
  2. Use the specified encryption algorithm to encrypt the symmetric key material. In this example, the RSAES_PKCS1_V1_5 algorithm is used.
  3. Encode the encrypted symmetric key material in Base64 and save the encoded key material to a text file. 
    openssl rand -out KeyMaterial.bin 32
openssl rsautl -encrypt -in KeyMaterial.bin -pkcs -inkey PublicKey.bin  -keyform DER  -pubin -out EncryptedKeyMaterial.bin
openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt

Step 4: Import the symmetric key material

Each import token is bound to a public key that is used to encrypt symmetric key material. A CMK is specified when an import token is generated. An import token can be used to import symmetric key material only for the CMK that is specified. The validity period of an import token is 24 hours. The token can be repeatedly used within this period. After the token expires, you must obtain a new import token and a new public key.

  1. On the User master key tab, find the CMK for which you want to import symmetric key material and click its ID to go to the key management page.
  2. In the Key Material section, click Import Wrapped Key Material.
  3. In the Import Wrapped Key Material dialog box, configure the Wrapped Key Material and Import Token parameters, and click OK.

Result

After the symmetric key material is imported, the status of the CMK changes from Pending Import to Enabled.