How to import a private key in HSM - Key Management Service

Import an asymmetric private key from a file into a Hardware Security Module (HSM) using the importPrivateKey command in key_mgmt_tool.

Because HSM requires all keys to be encrypted before import, the private key is encrypted with AES outside the HSM and then decrypted inside the HSM after transfer. Use importPrivateKey together with exportPrivateKey to back up or transfer private keys between HSMs.

Prerequisites

Before you begin, ensure that you have:

Started key_mgmt_tool
Logged in to HSM as a Crypto User (CU)
An AES wrapping key already present in the HSM (note its key handle; use findKey to look it up, or use genSymKey to create one)

Syntax

importPrivateKey -l <label>
                 -f <key-file>
                 -w <wrapping-key-handle>
                 [-sess]
                 [-id <key-id>]
                 [-m_value <0...8>]
                 [min_srv <minimum-number-of-servers>]
                 [-timeout <number-of-seconds>]
                 [-u <user-ids>]
                 [-wk <wrapping-key-file>]
                 [-attest]

Important

Enter parameters in the order shown in the syntax.

Parameters

Parameter	Description	Required	Default
`-f`	File containing the private key to import.	Yes	—
`-w`	Key handle of the AES wrapping key used to encrypt the private key before import. To find the handle of an existing AES key, use `findKey`. To create a new AES wrapping key, use `genSymKey`.	Yes	—
`-l`	Label for the imported key.	Yes	—
`-id`	ID to assign to the imported key.	No	No ID assigned
`-sess`	Marks the imported key as a session key. Session keys exist only for the duration of the session and are not persisted to the cluster.	No	The key is stored as a persistent (token) key in the cluster
`-nex`	Marks the imported key as non-exportable.	No	The key is exportable
`-u`	User IDs that can use the imported key, separated by commas.	No	Only the current CU can use the key
`-m_value`	Maximum number of users who can utilize the imported key.	No	`0`; valid range: `0`–`8`
`-attest`	Runs a firmware attestation check to verify the integrity of the HSM response.	No	Attestation check is not run
`-min_srv`	Minimum number of HSM nodes the key must synchronize to within the timeout period. If synchronization does not reach this threshold before the timeout expires, the key is not created.	No	—
`-timeout`	Synchronization timeout in seconds. Used only with `-min_srv`.	No	No timeout; the command waits indefinitely
`-wk`	Path to an external wrapping key file. When specified, `-w` is used to wrap the key during export but the key in `-wk` is used to unwrap during import.	No	Uses the wrapping key specified by `-w` for both wrap and unwrap

Example

The following command imports the private key from keypair.pem, assigns it the label rsa2048-imported, and uses AES key handle 6 as the wrapping key.

importPrivateKey -f keypair.pem -l rsa2048-imported -w 6

A successful import produces output similar to the following. The private key handle assigned in the HSM is shown on the Private Key Imported line. The Cluster Status section lists every node in your cluster — each node should report HSM Return: SUCCESS.

BER encoded key length is 1218

        Cfm3ImportWrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate2 returned: 0x00 : HSM Return: SUCCESS

        Cfm3ImportUnWrapKey: 0x00 : HSM Return: SUCCESS

        Private Key Imported.  Key Handle: 17

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

Related commands

exportPrivateKey — export a private key from HSM for backup or transfer
genSymKey — generate an AES symmetric key to use as a wrapping key
findKey — find the key handle of an existing key in HSM