How to import encryption keys in HSM - Key Management Service

Import an encrypted symmetric key or private key from a file into the Hardware Security Module (HSM). Use unWrapKey together with wrapKey to back up and migrate keys between HSMs.

Prerequisites

Before you begin, ensure that you have:

Started key_mgmt_tool
Logged in to the HSM as a Crypto User (CU)

Syntax

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

Enter parameters in the order shown above.

Example

This example imports an AES-encrypted key file. The key is decrypted using the AES key with handle 6 and mechanism 4 (AES_KEY_WRAP_PAD_PKCS5). The imported key is assigned handle 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	Required	Description
`-f`	Yes	Path and filename of the encrypted key file.
`-w`	Yes	Handle of the decryption key.
`-m`	Yes	Unwrapping mechanism. See Unwrapping mechanisms.
`-sess`	No	Marks the imported key as a session key (valid only for the current session).
`-attest`	No	Performs an integrity check on the firmware response.
`-min_srv`	No	Minimum number of HSMs the key must synchronize to within the time set by `-timeout`. If synchronization does not complete in time, the key is not imported.
`-timeout`	No	Time limit in seconds for the key to synchronize to the number of servers set by `-min_srv`. Only valid when used with `-min_srv`. Default: no timeout (waits indefinitely).
`-tag_size`	No	Block size. Applies only to AES_GCM and CLOUDHSM_AES_GCM mechanisms.
`-iv_file`	No	Length of the AES initialization vector (IV). Applies only to the AES_GCM mechanism.
`-t`	No	Hash algorithm. See Hash algorithms.
`-nex`	No	Marks the imported key as non-exportable.
`-noheader`	No	Omits the header for specific key properties. When specified, the following parameters are applicable: `-l`, `-kc`, `-kt`, `-id`, `-i`.
`-l`	No	Label for the imported key. Only applicable when `-noheader` is specified.
`-id`	No	ID for the imported key. Only applicable when `-noheader` is specified.
`-kc`	No	Class of the imported key. Only applicable when `-noheader` is specified. Valid values: `3` (private key), `4` (symmetric key).
`-kt`	No	Type of the imported key. Only applicable when `-noheader` is specified. Valid values: `0` (RSA), `1` (DSA), `3` (ECC), `16` (GENERIC_SECRET), `21` (DES3), `31` (AES).
`-i`	No	Initialization vector (IV) for the unwrapping operation. Only applicable when `-noheader` is specified and the mechanism is CLOUDHSM_AES_KEY_WRAP or NIST_AES_WRAP.

Unwrapping mechanisms

Value	Mechanism
`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

Hash algorithms

Value	Algorithm
`2`	SHA1
`3`	SHA-256
`4`	SHA-384
`5`	SHA-512
`6`	SHA224 (valid for RSA_AES and RSA_OAEP only)

What's next

wrapKey — Export and encrypt a key from the HSM before migration or backup