Import key material into an HSM - Cloud Hardware Security Module (HSM)

Cloud Hardware Security Module allows you to import your own key material into a hardware security module (HSM). This topic describes how to import symmetric and asymmetric key material into an HSM.

Applicable HSM types

General virtual security modules (GVSMs) that are validated by Federal Information Processing Standards (FIPS)

Prerequisites

The hsm_proxy HSM client proxy is started. For more information, see Getting started with Cloud Hardware Security Module.

Tools

The key_mgmt_tool CLI is required. For more information, see key_mgmt_tool.

Before you perform the operations that are described in this topic, make sure that you are logged on to a crypto user (CU) by using key_mgmt_tool. The following sample code shows the required command.

Note

Replace /opt/hsm/bin/key_mgmt_tool with the actual path.
Replace <yourCuUserName> and <yourCuUserPassword> with the actual username and password of the CU.

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

Import symmetric key material

In the following example, AES-256 symmetric key material is imported.

Create symmetric key material.
Note
If you already have key material, skip this step. Your file can contain only key material and cannot contain additional information such as line feeds.
In this example, OpenSSL is used to generate 32-byte symmetric key material.
```
openssl rand 32 >aes256key_to_import.key
```

Run the genSymKey command to generate a wrapping key.

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

Parameter	Description
-t	The type of the key. Valid values: 21: Triple Data Encryption Standard (3DES) 31: Advanced Encryption Standard (AES)
-s	The length of the key. Unit: bytes. For AES keys, valid values are 16, 24, and 32. For 3DES keys, set the value to 24.
-sess	Specifies that the key is a session key. A session key is intended for temporary use rather than for prolonged storage.
-l	The key tag.

Expected output:

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

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 file name of the key material.
-t	The key type of the key material. Valid values: 16: GENERIC_SECRET 21: 3DES or Data Encryption Standard (DES) 31: AES
-l	The key tag.
-w	The identifier of the wrapping key. The identifier is the value of Key Handle in the output of the `genSymKey` command that you run to generate a wrapping key. Note The value of Key Handle is randomly assigned by your HSM. You must modify the value based on your business requirements.

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

In the following example, an elliptic curve cryptography (ECC) secp256k1 private key and an ECC secp256k1 public key are created.

Create asymmetric key material. If you already have key material, skip this step.
In this example, OpenSSL is used 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
```
Private key file example (secp256k1_key.pem):
Public key file example (secp256k1_key_pub.pem):

Run the genSymKey command to create a wrapping key.

Note

You can import the public key or private key of the asymmetric key material based on your business requirements. 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 type of the key. Valid values: 21: Triple Data Encryption Standard (3DES) 31: Advanced Encryption Standard (AES)
-s	The length of the key. Unit: bytes. For AES keys, valid values are 16, 24, and 32. For 3DES keys, set the value to 24.
-sess	Specifies that the key is a session key. A session key is intended for temporary use rather than for prolonged storage.
-l	The key tag.

Expected output:

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

Run the importPrivateKey command to import the private key of the asymmetric key material.

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

Parameter	Description
-f	The file name of the private key.
-l	The key tag.
-w	The identifier of the wrapping key. The identifier is the value of Key Handle in the output of the `genSymKey` command that you run to generate a wrapping key. Note The value of Key Handle is randomly assigned by your HSM. You must modify the value based on your business requirements.

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

Run the importPubKey command to import the public key of the asymmetric key material.
```
Command:  importPubKey -f secp256k1_key_pub.pem -l secp256k1_key_pub
```
Parameter
Description
-f
The file name of the public key.
-l
The key tag.
Expected output:
```
	Cfm3CreatePublicKey returned: 0x00 : HSM Return: SUCCESS
```

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