AWS CloudHSM
User Guide

syncKey

You can use the syncKey command in cloudhsm_mgmt_util to manually synchronize keys across HSM instances within a cluster or across cloned clusters. In general, you will not need to use this command, as HSM instances within a cluster sync keys automatically. However, key synchronization across cloned clusters must be done manually. Cloned clusters are usually created in different AWS Regions in order to simplify the global scaling and disaster recovery processes.

You cannot use syncKey to synchronize keys across arbitrary clusters: one of the clusters must have been created from a backup of the other. Additionally, both clusters must have consistent CO and CU credentials in order for the operation to be successful. For more information, see HSM Users.

To use syncKey, you must first create an AWS CloudHSM configuration file that specifies one HSM from the source cluster and one from the destination cluster. This will allow cloudhsm_mgmt_util to connect to both HSM instances. Use this configuration file to start cloudhsm_mgmt_util. Then log in with the credentials of a CO or a CU who owns the keys you want to synchronize. For further instructions on how to create this configuration file, see the configuration file instructions below.

User Type

The following types of users can run this command.

  • Crypto officers (CO)

  • Crypto users (CU)

Note

COs can use syncKey on any keys, while CUs can only use this command on keys that they own. For more information, see .

Prerequisites

Before you begin, you must know the key handle of the key on the source HSM to be synchronized with the destination HSM. To find the key handle, use the listUsers command to list all identifiers for named users. Then, use the findAllKeys command to find all keys that belong to a particular user. In this example, we assume that the key handle to be synchronized is 261251.

You also need to know the server IDs assigned to the source and destination HSMs, which are shown in the trace output returned by cloudhsm_mgmt_util upon initiation. These are assigned in the same order that the HSMs appear in the configuration file. For this example, we assume that server 0 is the source HSM, and server 1 is the destination HSM.

Create a Configuration File for syncKey Across Cloned Clusters

Create a copy of your current config file (/opt/cloudhsm/etc/cloudhsm_mgmt_config.cfg). For this example, change the copy's name to clustersync.cfg.

Edit clustersync.cfg to include the Elastic Network Interface (ENI) IPs of the two HSMs to be synced. We recommend that you specify the source HSM first, followed by the destination HSM. To find the ENI IP of an HSM, use the describe-clusters CLI command.

Initialize cloudhsm_mgmt_util with the new config file by issuing the following command:

aws-cloudhsm> /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/clustersync.cfg

Check the status messages returned to ensure that the cloudhsm_mgmt_util is connected to both HSMs and determine which of the returned ENI IPs corresponds to each cluster. Then, enter server mode on the source HSM by issuing the server command. In this example, server 0 is the HSM instance from the source cluster, and server 1 is the HSM instance from the destination cluster.

Syntax

Note

To run syncKey, first enter server mode on the HSM, which contains the key to be synchronized.

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

User Type: Crypto user (CU)

syncKey <key handle> <destination hsm>

Example

Run the server command to log into the source HSM and enter server mode.

aws-cloudhsm> server 0

Now run the syncKey command.

aws-cloudhsm> syncKey 261251 1 syncKey success

Arguments

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

syncKey <key handle> <destination hsm>
<key handle>

Specifies the key handle of the key to sync. You can specify only one key in each command. To get the key handle of a key, use findAllKeys while logged in to an HSM server.

Required: Yes

<destination hsm>

Specifies the number of the server to which you are syncing a key.

Required: Yes

Related Topics