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