AWS CloudHSM
User Guide

setAttribute

The setAttribute command in key_mgmt_util converts a key that is valid only in the current session to a persistent key that exists until you delete it. It does this by changing the value of the token attribute of the key (OBJ_ATTR_TOKEN) from false (0) to true (1). You can only change the attributes of keys that you own.

You can also use the setAttribute command in cloudhsm_mgmt_util to change the label, wrap, unwrap, encrypt, and decrypt attributes.

Before you run any key_mgmt_util command, you must start key_mgmt_util and login to the HSM as a crypto user (CU).

Syntax

setAttribute -h setAttribute -o <object handle> -a 1

Example

This example shows how to convert a session key to a persistent key.

The first command uses the -sess parameter of genSymKey to create a 192-bit AES key that is valid only in the current session. The output shows that the key handle of the new session key is 262154.

Command: genSymKey -t 31 -s 24 -l tmpAES -sess Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS Symmetric Key Created. Key Handle: 262154 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS

This command uses findKey to find the session keys in the current session. The output verifies that key 262154 is a session key.

Command: findKey -sess 1 Total number of keys present 1 number of keys matched from start index 0::0 262154 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

This command uses setAttribute to convert key 262154 from a session key to a persistent key. To do so, it changes the value of the token attribute (OBJ_ATTR_TOKEN) of the key from 0 (false) to 1 (true). For help interpreting the key attributes, see the Key Attribute Reference.

The command uses the -o parameter to specify the key handle (262154) and the -a parameter to specify the constant that represents the token attribute (1). When you run the command, it prompts you for a value for the token attribute. The only valid value is 1 (true); the value for a persistent key.

Command: setAttribute -o 262154 -a 1 This attribute is defined as a boolean value. Enter the boolean attribute value (0 or 1):1 Cfm3SetAttribute returned: 0x00 : HSM Return: SUCCESS Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

To confirm that key 262154 is now persistent, this command uses findKey to search for session keys (-sess 1) and persistent keys (-sess 0). This time, the command does not find any session keys, but it returns 262154 in the list of persistent keys.

Command: findKey -sess 1 Total number of keys present 0 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS Command: findKey -sess 0 Total number of keys present 5 number of keys matched from start index 0::4 6, 7, 524296, 9, 262154 Cluster Error Status Node id 1 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

Parameters

-h

Displays help for the command.

Required: Yes

-o

Specifies the key handle of the target key. You can specify only one key in each command. To get the key handle of a key, use findKey.

Required: Yes

-a

Specifies the constant that represents the attribute that you want to change. The only valid value is 1, which represents the token attribute, OBJ_ATTR_TOKEN.

To get the attributes and their integer values, use listAttributes.

Required: Yes

Related Topics