How to import symmetric keys into HSM - Key Management Service

This topic explains how to use the imSymKey command to import symmetric keys into HSM.

Feature description

The imSymKey command enables the importation of key files stored in plaintext into HSM. For encrypted key files, refer to unWrapKey.
Utilizing exSymKey and imSymKey, you can facilitate the backup or migration of symmetric keys.
For importing symmetric keys, use the imSymKey command. To import public keys, see importPubKey, and for private keys, refer to importPrivateKey.
HSM prohibits the direct import of keys in plaintext. Initially, imSymKey encrypts the import file with AES, followed by invoking unWrapKey to facilitate the import of the encrypted file into HSM.

Important

Ensure you have started key_mgmt_tool and logged on to HSM as CU before executing this command.

Syntax

Enter the parameters as per the syntax provided below. For detailed parameter descriptions, see Parameters.

imSymKey -f <key-file>
         -w <wrapping-key-handle>  
         -t <key-type>
         -l <label>
         [-id <key-ID>]
         [-sess]
         [-wk <wrapping-key-file> ]
         [-attest]
         [-min_srv <minimum-number-of-servers>]
         [-timeout <number-of-seconds> ]
         [-u <user-ids>]

Important

Parameters must be entered in the sequence outlined in the syntax.

Example

Generate a random 256-bit AES symmetric key using OpenSSL and save it to the aes256.key file.
```
openssl rand -out aes256.key 32
```
The imSymKey command imports the AES key from the aes256.key file into HSM.

Command:  imSymKey -f aes256.key -w 6 -t 31 -l importedaes

       	Cfm3ImportWrapKey returned: 0x00 : HSM Return: SUCCESS

       	Cfm3CreateUnwrapTemplate2 returned: 0x00 : HSM Return: SUCCESS

       	Cfm3ImportUnWrapKey returned: 0x00 : HSM Return: SUCCESS

       	Symmetric Key Imported.  Key Handle: 19

       	Cluster Status:
       	Node id 0 status: 0x00000000 : HSM Return: SUCCESS

Parameters

Parameter Name	Description	Required	Valid Values
-f	Specifies the file name containing the import key.	Yes	No specific requirements
-w	Specifies the AES key handle used to encrypt the import key.	Yes	No specific requirements
-t	Indicates the type of the import key.	Yes	21: Triple DES (3DES). 31: AES
-l	Specifies the label for the import key.	Yes	No specific requirements
-id	Specifies the ID for the import key.	No	No specific requirements
-sess	Designates the import key as a session key.	No	No specific requirements
-wk	Specifies the file for decrypting the import key, including the path and file name of the AES key.	No	Defaults to the encryption key specified by -w
-attest	Conducts an integrity check on the firmware response.	No	No specific requirements
-min_srv	Sets the minimum number of servers required to be synchronized within the allocated time (refer to timeout). If the key fails to synchronize to the specified number of servers within the allocated time, it will not be created.	No	No specific requirements
-timeout	Defines the time (in seconds) for the key to synchronize to the specified number of servers (refer to min_srv). This parameter is applicable only when the min_srv parameter is also used. Default: No timeout, the command waits indefinitely until the key is synchronized to the minimum number of servers.	No	No specific requirements
-u	Lists the user IDs authorized to share the import key, separated by commas for multiple users.	No	No specific requirements