How to import symmetric keys into HSM - Key Management Service

Use imSymKey to import a plaintext symmetric key into a Hardware Security Module (HSM).

imSymKey only handles plaintext key files. For encrypted key files, use unWrapKey instead. To import public or private keys, see importPubKey and importPrivateKey.

How it works

HSM does not allow direct plaintext key imports. When you run imSymKey, it uses a wrapping key — an AES key already stored in HSM — to encrypt your key file, then immediately unwraps and imports the encrypted key into HSM via unWrapKey. The plaintext key never enters HSM unprotected.

To back up or migrate symmetric keys between clusters, use imSymKey together with exSymKey.

Prerequisites

Before you begin, make sure that you have:

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

Syntax

Parameters must be entered in the order shown.

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>]

Parameters

Parameter	Required	Description
`-f`	Yes	Path to the plaintext key file to import.
`-w`	Yes	Key handle of the AES wrapping key in HSM. This key encrypts the import file before it enters HSM.
`-t`	Yes	Type of the key being imported: `21` for Triple DES (3DES), `31` for AES.
`-l`	Yes	Label for the imported key.
`-id`	No	ID for the imported key.
`-sess`	No	Marks the imported key as a session key. Session keys exist only for the duration of the current session.
`-wk`	No	Path to the AES key file used to decrypt the import file. Defaults to the wrapping key specified by `-w`.
`-attest`	No	Runs an integrity check on the firmware response.
`-min_srv`	No	Minimum number of HSM servers the key must synchronize to within the time specified by `-timeout`. If synchronization does not complete in time, the key is not created.
`-timeout`	No	Time in seconds to wait for the key to synchronize to the minimum number of servers specified by `-min_srv`. Only applies when `-min_srv` is set. Default: no timeout (waits indefinitely).
`-u`	No	User IDs authorized to share the imported key. Separate multiple user IDs with commas.

Examples

Import an AES symmetric key

This example generates a 256-bit AES key and imports it into HSM.

Step 1. Generate a random 256-bit AES key and save it to aes256.key.

openssl rand -out aes256.key 32

Step 2. Import the key into HSM. The -w 6 argument specifies the key handle of the AES wrapping key, and -t 31 specifies AES as the key type.

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

Successful output looks like this. Note the key handle (19) assigned to the imported key — use it to reference the key in subsequent operations.

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

What's next

Export a symmetric key: exSymKey
Import an encrypted key: unWrapKey
Import a public key: importPubKey
Import a private key: importPrivateKey