How to generate a symmetric key on HSM - Key Management Service

Use the genSymKey command in key_mgmt_tool to generate a symmetric key on a hardware security module (HSM). You can specify the key type and size, assign an ID and a label, and share the key with other HSM users. You can also create non-exportable keys and session keys that expire when the session ends. When the command succeeds, it returns a key handle that identifies the key in subsequent operations.

Prerequisites

Before you begin, ensure that you have:

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

Syntax

genSymKey -t <key-type>
          -s <key-size>
          -l <label>
          [-id <key-ID>]
          [-min_srv <minimum-number-of-servers>]
          [-m_value <0..8>]
          [-nex]
          [-sess]
          [-timeout <number-of-seconds>]
          [-u <user-ids>]
          [-attest]

Important

Enter parameters in the order shown in the syntax above.

Parameters

Parameter	Required	Description
`-t`	Yes	The key type. Valid values: `16` (GENERIC_SECRET — a byte array with no specific standard), `18` (RC4 — not valid in FIPS mode), `21` (Triple DES / 3DES), `31` (AES)
`-s`	Yes	The key size in bits. Valid values: AES — `128`, `192`, or `256` bits; 3DES — `192` bits; GENERIC_SECRET — up to `28672` bits
`-l`	Yes	A label for the key. No format requirements.
`-id`	No	An ID for the key. No format requirements. Default: no ID assigned.
`-nex`	No	Makes the key non-exportable. The key cannot be exported from the HSM. Default: the key is exportable.
`-sess`	No	Creates a session key that exists only in the current session. The key is permanently lost when the session ends. Use this for short-lived keys such as wrapping keys. Default: the key is persistent.
`-u`	No	Shares the key with the specified CU user IDs. Provide a comma-separated list, for example `-u 5,6`. Do not include your own user ID. Default: only the current user can use the key.
`-m_value`	No	The maximum number of users permitted to utilize the generated key. Range: `0`–`8`. Default: `0`.
`-attest`	No	Verifies the integrity of the HSM firmware response. Default: attestation is not performed.
`-min_srv`	No	The minimum number of servers in the cluster that must synchronize the key within the timeout period. If synchronization does not reach this threshold before the timeout, the key is not created. Default: no minimum — the command returns as soon as the key is created on any one server.
`-timeout`	No	The maximum time in seconds to wait for cluster synchronization. Applies only when `-min_srv` is also specified. Default: no timeout — the command waits indefinitely until the key is synchronized with the minimum number of servers.

Examples

Generate a 256-bit AES key

genSymKey -t 31 -s 32 -l aes256

Output:

Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

Symmetric Key Created.  Key Handle: 16

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

The key handle (16) identifies this key in subsequent operations.