User type Syntax Example Arguments Related topics

setAttribute

The setAttribute command in cloudhsm_mgmt_util changes the value of the label, encrypt, decrypt, wrap, and unwrap attributes of a key in the HSMs. You can also use the setAttribute command in key_mgmt_util to convert a session key to a persistent key. You can only change the attributes of keys that you own.

Before you run any CMU command, you must start CMU and log in to the HSM. Be sure that you log in with a user type that can run the commands you plan to use.

If you add or delete HSMs, update the configuration files for CMU. Otherwise, the changes that you make might not be effective for all HSMs in the cluster.

User type

The following users can run this command.

Crypto users (CU)

Syntax

Because this command does not have named parameters, you must enter the arguments in the order specified in the syntax diagram.


setAttribute <key handle> <attribute id>

Example

This example shows how to disable the decrypt functionality of a symmetric key. You can use a command like this one to configure a wrapping key, which should be able to wrap and unwrap other keys but not encrypt or decrypt data.

The first step is to create the wrapping key. This command uses genSymKey in key_mgmt_util to generate a 256-bit AES symmetric key. The output shows that the new key has key handle 14.


$  genSymKey -t 31 -s 32 -l aes256

Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Created.  Key Handle: 14

        Cluster Error Status
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

Next, we want to confirm the current value of the decrypt attribute. To get the attribute ID of the decrypt attribute, use listAttributes. The output shows that the constant that represents the OBJ_ATTR_DECRYPT attribute is 261. For help interpreting the key attributes, see the Key Attribute Reference.


aws-cloudhsm> listAttributes

Following are the possible attribute values for getAttribute:

      OBJ_ATTR_CLASS                  = 0
      OBJ_ATTR_TOKEN                  = 1
      OBJ_ATTR_PRIVATE                = 2
      OBJ_ATTR_LABEL                  = 3
      OBJ_ATTR_TRUSTED                = 134
      OBJ_ATTR_KEY_TYPE               = 256
      OBJ_ATTR_ID                     = 258
      OBJ_ATTR_SENSITIVE              = 259
      OBJ_ATTR_ENCRYPT                = 260
      OBJ_ATTR_DECRYPT                = 261
      OBJ_ATTR_WRAP                   = 262
      OBJ_ATTR_UNWRAP                 = 263
      OBJ_ATTR_SIGN                   = 264
      OBJ_ATTR_VERIFY                 = 266
      OBJ_ATTR_DERIVE                 = 268
      OBJ_ATTR_LOCAL                  = 355
      OBJ_ATTR_MODULUS                = 288
      OBJ_ATTR_MODULUS_BITS           = 289
      OBJ_ATTR_PUBLIC_EXPONENT        = 290
      OBJ_ATTR_VALUE_LEN              = 353
      OBJ_ATTR_EXTRACTABLE            = 354
      OBJ_ATTR_NEVER_EXTRACTABLE      = 356
      OBJ_ATTR_ALWAYS_SENSITIVE       = 357
      OBJ_ATTR_DESTROYABLE            = 370
      OBJ_ATTR_KCV                    = 371
      OBJ_ATTR_WRAP_WITH_TRUSTED      = 528
      OBJ_ATTR_WRAP_TEMPLATE          = 1073742353
      OBJ_ATTR_UNWRAP_TEMPLATE        = 1073742354
      OBJ_ATTR_ALL                    = 512

To get the current value of the decrypt attribute for key 14, the next command uses getAttribute in cloudhsm_mgmt_util.

The output shows that the value of the decrypt attribute is true (1) on both HSMs in the cluster.


aws-cloudhsm> getAttribute 14 261
      
Attribute Value on server 0(10.0.0.1):
OBJ_ATTR_DECRYPT
0x00000001

Attribute Value on server 1(10.0.0.2):
OBJ_ATTR_DECRYPT
0x00000001

This command uses setAttribute to change the value of the decrypt attribute (attribute 261) of key 14 to 0. This disables the decrypt functionality on the key.

The output shows that the command succeeded on both HSMs in the cluster.


aws-cloudhsm> setAttribute 14 261 0
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. AWS does NOT synchronize these changes automatically with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************

Do you want to continue(y/n)? y
setAttribute success on server 0(10.0.0.1)
setAttribute success on server 1(10.0.0.2)

The final command repeats the getAttribute command. Again, it gets the decrypt attribute (attribute 261) of key 14.

This time, the output shows that the value of the decrypt attribute is false (0) on both HSMs in the cluster.


aws-cloudhsm>getAttribute 14 261
Attribute Value on server 0(10.0.3.6):
OBJ_ATTR_DECRYPT
0x00000000

Attribute Value on server 1(10.0.1.7):
OBJ_ATTR_DECRYPT
0x00000000

Arguments


setAttribute <key handle> <attribute id>

<key-handle>

Specifies the key handle of a key that you own. You can specify only one key in each command. To get the key handle of a key, use findKey in key_mgmt_util. To find the users of a key, use getKeyInfo.

Required: Yes

<attribute id>

Specifies the constant that represents the attribute that you want to change. You can specify only one attribute in each command. To get the attributes and their integer values, use listAttributes. For help interpreting the key attributes, see the Key Attribute Reference.

Valid values:

3 – OBJ_ATTR_LABEL.
134 – OBJ_ATTR_TRUSTED.
260 – OBJ_ATTR_ENCRYPT.
261 – OBJ_ATTR_DECRYPT.
262 – OBJ_ATTR_WRAP.
263 – OBJ_ATTR_UNWRAP.
264 – OBJ_ATTR_SIGN.
266 – OBJ_ATTR_VERIFY.
268 – OBJ_ATTR_DERIVE.
370 – OBJ_ATTR_DESTROYABLE.
528 – OBJ_ATTR_WRAP_WITH_TRUSTED.
1073742353 – OBJ_ATTR_WRAP_TEMPLATE.
1073742354 – OBJ_ATTR_UNWRAP_TEMPLATE.

Required: Yes