Syntax Examples Parameters Related topics

Get an AWS CloudHSM key attribute using KMU

Use the getAttribute command in the AWS CloudHSM key_mgmt_util to write one or all of the attribute values for an AWS CloudHSM key to a file. If the attribute you specify does not exist for the key type, such as the modulus of an AES key, getAttribute returns an error.

Key attributes are properties of a key. They include characteristics, like the key type, class, label, and ID, and values that represent actions that you can perform with the key, like encrypt, decrypt, wrap, sign, and verify.

You can use getAttribute only on keys that you own and key that are shared with you. You can run this command or the getAttribute command in cloudhsm_mgmt_util, which gets one attribute value of a key from all HSMs in a cluster, and writes it to stdout or to a file.

To get a list of attributes and the constants that represent them, use the listAttributes command. To change the attribute values of existing keys, use setAttribute in key_mgmt_util and setAttribute in cloudhsm_mgmt_util. For help interpreting the key attributes, see the AWS CloudHSM key attribute reference for KMU.

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


getAttribute -h 

getAttribute -o <key handle> 
             -a <attribute constant> 
             -out <file>

Examples

These examples show how to use getAttribute to get the attributes of keys in your HSMs.

Example : Get the key type

This example gets the type of the key, such an AES, 3DES, or generic key, or an RSA or elliptic curve key pair.

The first command runs listAttributes, which gets the key attributes and the constants that represent them. The output shows that the constant for key type is 256. For help interpreting the key attributes, see the AWS CloudHSM key attribute reference for KMU.


Command: listAttributes

Description
===========
The following are all of the possible attribute values for getAttributes.

      OBJ_ATTR_CLASS                  = 0
      OBJ_ATTR_TOKEN                  = 1
      OBJ_ATTR_PRIVATE                = 2
      OBJ_ATTR_LABEL                  = 3
      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_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_KCV                    = 371

The second command runs getAttribute. It requests the key type (attribute 256) for key handle 524296 and writes it to the attribute.txt file.


Command: getAttribute -o 524296 -a 256 -out attribute.txt
Attributes dumped into attribute.txt file

The final command gets the content of the key file. The output reveals that the key type is 0x15 or 21, which is a Triple DES (3DES) key. For definitions of the class and type values, see the Key Attribute Reference.


$  cat attribute.txt
OBJ_ATTR_KEY_TYPE
0x00000015

Example : Get all attributes of a key

This command gets all attributes of the key with key handle 6 and writes them to the attr_6 file. It uses an attribute value of 512, which represents all attributes.


Command: getAttribute -o 6 -a 512 -out attr_6
        
got all attributes of size 444 attr cnt 17
Attributes dumped into attribute.txt file

        Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS>

This command shows the content of a sample attribute file with all attribute values. Among the values, it reports that key is a 256-bit AES key with an ID of test_01 and a label of aes256.The key is extractable and persistent, that is, not a session-only key. For help interpreting the key attributes, see the AWS CloudHSM key attribute reference for KMU.


$  cat attribute.txt

OBJ_ATTR_CLASS
0x04
OBJ_ATTR_KEY_TYPE
0x15
OBJ_ATTR_TOKEN
0x01
OBJ_ATTR_PRIVATE
0x01
OBJ_ATTR_ENCRYPT
0x01
OBJ_ATTR_DECRYPT
0x01
OBJ_ATTR_WRAP
0x01
OBJ_ATTR_UNWRAP
0x01
OBJ_ATTR_SIGN
0x00
OBJ_ATTR_VERIFY
0x00
OBJ_ATTR_LOCAL
0x01
OBJ_ATTR_SENSITIVE
0x01
OBJ_ATTR_EXTRACTABLE
0x01
OBJ_ATTR_LABEL
aes256
OBJ_ATTR_ID
test_01
OBJ_ATTR_VALUE_LEN
0x00000020
OBJ_ATTR_KCV
0x1a4b31

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.

Also, you must own the specified key or it must be shared with you. To find the users of a key, use getKeyInfo.

Required: Yes

-a

Identifies the attribute. Enter a constant that represents an attribute, or 512, which represents all attributes. For example, to get the key type, type 256, which is the constant for the OBJ_ATTR_KEY_TYPE attribute.

To list the attributes and their constants, use listAttributes. For help interpreting the key attributes, see the AWS CloudHSM key attribute reference for KMU.

Required: Yes

-out

Writes the output to the specified file. Type a file path. You cannot write the output to stdout.

If the specified file exists, getAttribute overwrites the file without warning.

Required: Yes