Syntax Examples Parameters Related topics

extractMaskedObject

The extractMaskedObject command in key_mgmt_util extracts a key from an HSM and saves it to a file as a masked object. Masked objects are cloned objects that can only be used after inserting them back into the original cluster by using the insertMaskedObject command. You can only insert a masked object into the same cluster from which it was generated, or a clone of that cluster. This includes any cloned versions of the cluster generated by copying a backup across regions and using that backup to create a new cluster.

Masked objects are an efficient way to offload and synchronize keys, including nonextractable keys (that is, keys that have a OBJ_ATTR_EXTRACTABLE value of 0). This way, keys can be securely synced across related clusters in different regions without the need to update the AWS CloudHSM configure file.

Important

Upon insertion, masked objects are decrypted and given a key handle that is different from the key handle of the original key. A masked object includes all metadata associated with the original key, including attributes, ownership and sharing information, and quorum settings. If you need to sync keys across clusters in an application, use syncKey in the cloudhsm_mgmt_util instead.

Before you run any key_mgmt_util command, you must start key_mgmt_util and log in to the HSM. The extractMaskedObject command can be used either by the CU who owns the key or any CO.

Syntax


extractMaskedObject -h

extractMaskedObject -o <object-handle>
                    -out <object-file>

Examples

This example shows how to use extractMaskedObject to extract a key from an HSM as a masked object.

Example : Extract a masked object

This command extracts a masked object out of an HSM from a key with handle 524295 and saves it as a file called maskedObj. When the command succeeds, extractMaskedObject returns a success message.


Command: extractMaskedObject -o 524295 -out maskedObj

Object was masked and written to file "maskedObj"

        Cfm3ExtractMaskedObject returned: 0x00 : HSM Return: SUCCESS

Parameters

This command takes the following parameters.

-h

Displays command line help for the command.

Required: Yes

-o

Specifies the handle of the key to extract as a masked object.

Required: Yes

-out

Specifies the name of the file to which the masked object will be saved.

Required: Yes