How to import encryption keys in HSM - Key Management Service

This topic explains how to import encryption keys into HSM using the unWrapKey command.

Feature description

The unWrapKey command allows for the importation of an encrypted symmetric key or private key from a file into the HSM, utilizing the encrypted key exported by the wrapKey command.
Utilizing unWrapKey and wrapKey, key backup and migration tasks can be performed.

Important

Ensure you start the key_mgmt_tool and log on to the HSM as a CU before executing this command.

Syntax

Enter the parameters as per the following syntax. For parameter details, see Parameters.

unWrapKey -f <key-file-name> 
          -w <wrapping-key-handle> 
          [-sess]
          [-min_srv <minimum-number-of-HSMs>]          
          [-timeout <number-of-seconds>]
          [-tag_size <tag size>]
          [-iv_file <IV file>]
          [-attest]
          [-m <wrapping-mechanism>]
          [-t <hash-type>]
          [-nex]
          [-noheader]
          [-l <key-label>]
          [-id <key-id>]
          [-kt <key-type>]
          [-kc <key-class]
          [-i <unwrapping-IV>]

Important

Parameters must be entered in the order specified by the syntax.

Example

The following example demonstrates importing an AES encrypted key file. The key is decrypted using an AES key with handle 6, and the output indicates that the handle of the imported key is 22.

Command:   unWrapKey -f aes-encrypted.key -w 6 -m 4

       	Cfm2UnWrapKey5 returned: 0x00 : HSM Return: SUCCESS

       	Key Unwrapped.  Key Handle: 22

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

Parameters

Parameter name	Description	Required	Valid values
-f	Defines the path and name of the encrypted key file.	Yes	No Special Requirements
-w	Specifies the handle of the decryption key.	Yes	No Special Requirements
-m	Indicates the decryption mechanism.	Yes	4: AES_KEY_WRAP_PAD_PKCS5 5: NIST_AES_WRAP_NO_PAD 6: NIST_AES_WRAP_PAD 7: RSA_AES 8: RSA_OAEP 9: NIST_TDEA_WRAP 10: AES_GCM 11: CLOUDHSM_AES_GCM
tag_size	Specifies the block size. Note Applicable only for AES_GCM and CLOUDHSM_AES_GCM decryption mechanisms.	No	No Special Requirements
iv_file	Defines the length of the AES initialization vector. Note Applicable only for AES_GCM decryption mechanism.	No	No Special Requirements
-sess	Designates the key as the current session key.	No	No Special Requirements
-attest	Conducts an integrity check on the firmware response.	No	No Special Requirements
-min_srv	Determines the minimum number of synchronized servers required for the key within the specified time (refer to timeout). If the key fails to synchronize to the designated number of servers within the specified time, it will not be created.	No	No Special Requirements
-timeout	Sets the duration (in seconds) for the key to synchronize to the specified number of servers (refer to min_srv). This parameter is relevant only when used in conjunction with the min_srv parameter. Default: No timeout. The command will wait indefinitely until the key synchronizes to the minimum required servers.	No	No Special Requirements
-t	Specifies the hash algorithm value.		2: SHA1 3: SHA-256 4: SHA-384 5:SHA-512 6: SHA224 (valid for RSA_AES and RSA_OAEP)
-nex	Marks the key as non-exportable.	No	No Special Requirements
-noheader	Omits the header for specific key properties.	No	No Special Requirements
-l	Assigns a label to the imported key. Note Only applicable when used with the -noheader parameter.	No	No Special Requirements
-id	Specifies the ID for the imported key. Note Only applicable when used with the -noheader parameter.		No Special Requirements
-kc	Defines the category of the imported key. Note Only applicable when used with the -noheader parameter.	No	3: Private key 4: Symmetric key
-kt	Indicates the type of the imported key. Note Only applicable when used with the -noheader parameter.	No	0: RSA 1: DSA 3: ECC 16: GENERIC_SECRET 21: DES3 31: AES
-i	Determines the initialization vector (IV) for the imported key. Note Only applicable when used with the -noheader parameter and for CLOUDHSM_AES_KEY_WRAP and NIST_AES_WRAP mechanisms.	No	No Special Requirements