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

This topic explains the process of generating a symmetric key using the genSymKey command on HSM.

Feature description

The genSymKey command allows for the creation of a symmetric key on HSM. Upon successful execution, it provides a key handle from HSM, which serves as the key's identifier.

Important

Ensure you have initiated key_mgmt_tool and logged on to HSM with a CU identity before executing this command.

Syntax

Enter the parameters as outlined in the syntax below. For detailed parameter descriptions, see Parameters.

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

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

Example

Below is an example of generating a 256-bit AES key with the label 'aes256'.

Command:  genSymKey -t 31 -s 32 -l aes256

       	Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

       	Symmetric Key Created.  Key Handle: 16

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

Parameters

Parameter Name	Description	Required	Valid Values
-t	Determines the type of symmetric key to generate.	Yes	16: GENERIC_SECRET. The Generic secret key is a byte array without adherence to a specific standard. 18: RC4. Not valid on HSMs operating in FIPS mode. 21: Triple DES (3DES). 31: AES
-s	Sets the key size in bits.	Yes	AES: 128, 192, or 256 bits 3DES: 192 bits Generic key: Up to 28672 bits
-l	Assigns a label to the key.	Yes	No specific requirements
-id	Specifies an ID for the generated key.	No	No specific requirements
-sess	Marks the key as a session key.	No	No specific requirements
-nex	Designates the key as non-exportable.	No	No specific requirements
-u	Lists user IDs authorized to access the key, separated by commas for multiple users.	No	No specific requirements
-m_value	Defines the maximum number of users permitted to utilize the generated key.	No	No specific requirements
-attest	Conducts a verification of the firmware response's integrity.	No	No specific requirements
-min_srv	Indicates the minimum number of servers that must synchronize with the key within the specified timeout period. If synchronization to the required number of servers is not achieved within the timeout, the key will not be created.	No	No specific requirements
-timeout	Specifies the duration, in seconds, for the key to synchronize to the required number of servers (refer to -min_srv). This parameter is applicable only when the -min_srv parameter is also used. Default behavior: There is no timeout; the command waits indefinitely until the key is synchronized with the minimum number of servers.	No	No specific requirements