insertMaskedObject - AWS CloudHSM

insertMaskedObject

The insertMaskedObject command in key_mgmt_util inserts a masked object from a file into a designated HSM. Masked objects are cloned objects that are extracted from an HSM by using the extractMaskedObject command. They can only be used after inserting them back into the original cluster. 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 original 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.

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

insertMaskedObject -h insertMaskedObject -f <filename> [-min_srv <minimum-number-of-servers>] [-timeout <number-of-seconds>]

Examples

This example shows how to use insertMaskedObject to insert a masked object file into an HSM.

Example : Insert a masked object

This command inserts a masked object into an HSM from a file named maskedObj. When the command succeeds, insertMaskedObject returns a key handle for the key decrypted from the masked object, and a success message.

Command: insertMaskedObject -f maskedObj Cfm3InsertMaskedObject returned: 0x00 : HSM Return: SUCCESS New Key Handle: 262433 Cluster Error Status Node id 2 and err state 0x00000000 : HSM Return: SUCCESS Node id 0 and err state 0x00000000 : HSM Return: SUCCESS Node id 1 and err state 0x00000000 : HSM Return: SUCCESS

Parameters

This command takes the following parameters.

-h

Displays command line help for the command.

Required: Yes

-f

Specifies the file name of the masked object to insert.

Required: Yes

-min_srv

Specifies the minimum number of servers on which the inserted masked object is synchronized before the value of the -timeout parameter expires. If the object is not synchronized to the specified number of servers in the time allotted, it is not inserted.

Default: 1

Required: No

-timeout

Specifies the number of seconds to wait for the key to sync across servers when the min-serv parameter is included. If no number is specified, the polling continues forever.

Default: No limit

Required: No

Related topics