Import key material into an HSM-Key Management Service(KMS)-阿里云帮助中心

Import your own symmetric or asymmetric key material into a hardware security module (HSM). The procedure differs by key material type, and importing a private key additionally requires a wrapping key.

Before you begin

Applicable HSM types

You can import your own key material into the following HSM types:

General-purpose HSM (FIPS)

Prerequisites

Start the HSM client agent (hsm_proxy). For more information, see Step 2: Start the HSM client (hsm_proxy).

Tools

Before performing any operations, log in as a crypto user (CU):

$/opt/hsm/bin/key_mgmt_tool
Command: loginHSM -u CU -s <yourCuUserName> -p <yourCuUserPassword>

Replace /opt/hsm/bin/key_mgmt_tool with the actual path, and replace <yourCuUserName> and <yourCuUserPassword> with your CU credentials.

Every genSymKey, imSymKey, importPrivateKey, and importPubKey command in this topic runs inside this command-line tool. The OpenSSL commands run in your shell.

Import symmetric key material

The following procedure imports AES-256 symmetric key material into an HSM. Symmetric key material is imported under a wrapping key, so the procedure has three steps: prepare the key material, generate the wrapping key, and import the key material.

Prepare the symmetric key material.
Note
If you already have the key material, skip this step. The file must contain only the key material and no extra content, such as a line feed.
In this example, OpenSSL generates 32 bytes (256 bits) of key material for an AES-256 key:
```
openssl rand 32 >aes256key_to_import.key
```

Generate a wrapping key.

In this example, the -sess option generates a temporary session key as the wrapping key.

genSymKey -t 31 -s 32 -sess -l import-wrapping-key

The following table describes the genSymKey parameters.

Parameter	Description
`-t`	The key type. Valid values: 21 (3DES) and 31 (AES).
`-s`	The key length, in bytes. For an AES key, valid values are 16, 24, or 32. For a 3DES key, the value must be 24.
`-sess`	Creates a temporary session key that is not persistently stored.
`-l`	The key label.

Expected output:

Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
  Symmetric Key Created.  Key Handle: 37
  Cluster Status:
  Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Import the symmetric key material.

imSymKey -f aes256key_to_import.key -t 31 -l aes256-key-imported -w 37

The following table describes the imSymKey parameters.

Parameter	Description
`-f`	The name of the key material file.
`-t`	The key type of the key material. Valid values: 16 (GENERIC_SECRET), 21 (3DES or DES), and 31 (AES).
`-l`	The key label.
`-w`	The identifier of the wrapping key. This is the Key Handle value in the output of the `genSymKey` command that you run to generate the wrapping key. The HSM assigns the Key Handle value randomly, so replace it with the actual value.

Expected output:

Cfm3ImportWrapKey returned: 0x00 : HSM Return: SUCCESS
  Cfm3CreateUnwrapTemplate2 returned: 0x00 : HSM Return: SUCCESS
  Cfm3ImportUnWrapKey returned: 0x00 : HSM Return: SUCCESS
  Symmetric Key Imported.  Key Handle: 35 
  Cluster Status:
  Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Import asymmetric key material

The following procedures import an ECC secp256k1 key pair into an HSM. You can import either the private key or the public key of the asymmetric key material, and the part you import determines the commands you run:

Private key — Generate a wrapping key, and then run importPrivateKey. See Import the private key.
Public key only — Run importPubKey. You do not need to generate a wrapping key. See Import only the public key.
Both paths use the key material files prepared in Prepare the asymmetric key material.

Prepare the asymmetric key material

Note

If you already have the key material, skip this step.

In this example, OpenSSL generates ECC secp256k1 asymmetric key material:

openssl ecparam -name secp256k1 -genkey -noout -out secp256k1_key.pem
openssl ec -in secp256k1_key.pem -pubout -out secp256k1_key_pub.pem

The following samples show the structure of the generated files. The key content is redacted and is shown for illustration only. Do not copy these samples as key material.

Private key file (secp256k1_key.pem):

Public key file (secp256k1_key_pub.pem):

Import the private key

Generate a wrapping key.

genSymKey -t 31 -s 32 -sess -l import-wrapping-key

The following table describes the genSymKey parameters.

Parameter	Description
`-t`	The key type. Valid values: 21 (3DES) and 31 (AES).
`-s`	The key length, in bytes. For an AES key, valid values are 16, 24, or 32. For a 3DES key, the value must be 24.
`-sess`	Creates a temporary session key that is not persistently stored.
`-l`	The key label.

Expected output:

Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
  Symmetric Key Created.  Key Handle: 37
  Cluster Status:
  Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Import the private key of the asymmetric key material.

importPrivateKey -f secp256k1_key.pem -l secp256k1_key-imported -w 37

The following table describes the importPrivateKey parameters.

Parameter	Description
`-f`	The name of the private key file.
`-l`	The key label.
`-w`	The identifier of the wrapping key. This is the Key Handle value in the output of the `genSymKey` command that you run to generate the wrapping key. The HSM assigns the Key Handle value randomly, so replace it with the actual value.

Expected output:

BER encoded key length is 135
  Cfm3ImportWrapKey returned: 0x00 : HSM Return: SUCCESS
  Cfm3CreateUnwrapTemplate2 returned: 0x00 : HSM Return: SUCCESS
  Cfm3ImportUnWrapKey: 0x00 : HSM Return: SUCCESS
  Private Key Imported.  Key Handle: 36 
  Cluster Status:
  Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Import only the public key

Importing a public key does not use a wrapping key, so run importPubKey without the -w parameter:

importPubKey -f secp256k1_key_pub.pem -l secp256k1_key_pub

The following table describes the importPubKey parameters.

Parameter	Description
`-f`	The name of the public key file.
`-l`	The key label.

Expected output:

Cfm3CreatePublicKey returned: 0x00 : HSM Return: SUCCESS