Syntax Example Parameters Related topics

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 log in 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