Import key material into an HSM

Applicable HSM types

General virtual security modules (GVSMs)

Prerequisites

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

Tools

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

Import symmetric key material

The following example shows how to import AES-256 symmetric key material.

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

   Use OpenSSL to generate 32 bytes of symmetric key material.

   openssl rand 32 >aes256key_to_import.key

2. Run the genSymKey command to generate a wrapping key.

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

   Parameter	Description
   -t	The key type. Valid values: 21: 3DES 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

3. Run the imSymKey command to import the symmetric key material.

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

   Parameter	Description
   -f	The key material file.
   -t	The key type. Valid values: 16: GENERIC_SECRET 21: 3DES or DES 31: AES
   -l	The key label.
   -w	The identifier of the wrapping key. This is the Key Handle value from the output of the genSymKey command. Note The Key Handle value is randomly assigned by the HSM. You must replace it with the actual value from the command output.

   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 example shows how to import an ECC secp256k1 private key and public key.

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

   Use OpenSSL to generate 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

   Example private key file (secp256k1_key.pem):

   -----BEGIN EC PRIVATE KEY-----
   MHQCAQEExxxxyuf7UmNdSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSxxxxxAK
   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx6
   NpRcHyxpilxxxHolxxxxxroWwH2obVr,Ug==
   -----END EC PRIVATE KEY-----

   Example public key file (secp256k1_key_pub.pem):

   -----BEGIN PUBLIC KEY-----
   MFYwEAYHKoxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxo3ZiycE
   xCxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxVM, Ug==
   -----END PUBLIC KEY-----

2. Run the genSymKey command to generate a wrapping key.

   Note

   You can import either the public or the private key. If you import only the public key, you do not need to create a wrapping key.

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

   Parameter	Description
   -t	The key type. Valid values: 21: 3DES 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

3. Run the importPrivateKey command to import the private key.

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

   Parameter	Description
   -f	The private key file.
   -l	The key label.
   -w	The identifier of the wrapping key. This is the Key Handle value from the output of the genSymKey command. Note The Key Handle value is randomly assigned by the HSM. You must replace it with the actual value from the command output.

   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

4. Run the importPubKey command to import the public key.

   Command:  importPubKey -f secp256k1_key_pub.pem -l secp256k1_key_pub

   Parameter	Description
   -f	The public key file.
   -l	The key label.

   Expected output:

   	Cfm3CreatePublicKey returned: 0x00 : HSM Return: SUCCESS