Key Synchronization in AWS CloudHSM - AWS CloudHSM

Key Synchronization in AWS CloudHSM

This topic describes key synchronization settings in AWS CloudHSM, common issues customers face working with keys on a cluster, and offers recommendations for making keys more durable.


Token keys

Persistent keys that you create during key generate, import or unwrap operations. CloudHSM synchronizes token keys across a cluster.

Session keys

Ephemeral keys that exist only on one HSM in the cluster. CloudHSM does not synchronize session keys across a cluster.

Client-side key synchronization

You can make keys more durable by specifying the number of HSMs required for key creation operations to succeed.

Server-side key synchronization

Periodically clones keys to every HSM in the cluster. Requires no management.

Understanding Key Synchronization

AWS CloudHSM uses key synchronization to clone token keys across all the HSMs in a cluster. You create token keys as persistent keys during key generation, import, or unwrap operations. To distribute these keys across the cluster, CloudHSM offers both client-side and server-side key synchronization.

The goal with key synchronization—both server side and client side—is to distribute new keys across the cluster as quickly as possible after you create them. This is important because the subsequent calls you make to use new keys can get routed to any available HSM in the cluster. If the call you make routes to a HSM without the key, then the call fails. You can mitigate these type failures by specifying that your applications retry subsequent calls made after key creation operations. The time required to synchronize can vary, depending on the workload of your cluster and other intangibles. Use CloudWatch metrics to determine the timing your application should employ in this type situation. For more information, see CloudWatch Metrics.

Key synchronization is mostly an automatic process, but you can use the client-side synchronization settings to make keys more durable. You specify the number of nodes on which key creation must succeed for the overall operation to be deemed a success. Client-side synchronization always makes a best-effort attempt to clone keys to every node in the cluster no matter what setting you choose. Your setting enforces key creation on the number of nodes you specify. If you specify a value and the system cannot replicate the key to that number of nodes, then the system automatically cleans up any unwanted key material and you can try again.


If you don’t set client-side synchronization settings (or if you use the default value of 1), your keys are vulnerable to loss. If your current HSM should fail before the server-side service has cloned that key to another HSM, you lose the key material. For recommendations, see Working with Client-side Synchronization.

Working with Client-side Synchronization

To maximize key durability, consider specifying at least two HSMs for client-side synchronization. Remember that no matter how many nodes you specify, the workload on your cluster remains the same. Client-side synchronization always makes a best-effort attempt to clone keys to every node in the cluster.


  • Minimum: Two HSMs per cluster

  • Maximum: One fewer than the total number of HSMs in your cluster

If client-side synchronization fails, the client service cleans up any unwanted keys that may have been created and are now unwanted. This clean up is a best-effort response that may not always work. If cleanup fails, you may have to delete unwanted key material. For more information, see Key Synchronization Failures.

Setting Up the Configuration File for Client-side Synchronization

To specify client-side synchronization settings, you must edit cloudhsm_client.cfg.

To edit the client configuration file

  1. Open cloudhsm_client.cfg.




  2. In the client node of the file, add create_object_minimum_nodes and specify a value for the minimum number of HSMs on which AWS CloudHSM must successfully create keys for key creation operations to succeed.

    "create_object_minimum_nodes" : 2

    The key_mgmt_util (KMU) command-line tool has an additional setting for client-side synchronization. For more information, see KMU and Client-side Synchronization

Configuration Reference

These are the client-side synchronization properties, shown in an excerpt of the cloudhsm_client.cfg:

{ "client": { "create_object_minimum_nodes" : 2, ... }, ... }

Specifies the minimum number of nodes required to deem key generation, key import, or key unwrap operations a success. If set, the default is 1. This means that for every key create operation, the client-side service attempts to create keys on every node in the cluster, but to return a success, only needs to create a single key on one node in the cluster.

KMU and Client-side Synchronization

If you create keys with the key_mgmt_util (KMU) command-line tool, you use an optional command line parameter (-min_srv) to limit the number of HSMs on which to clone keys. If you specify the command-line parameter and a value in the configuration file, AWS CloudHSM honors the LARGER of the two values.

For more information, see the following topics:

Synchronizing Keys Across Cloned Clusters

Client-side and server-side synchronization are only for synchronizing keys within the same cluster. If you copy a backup of a cluster to another region, you can use the syncKey command of the cloudhsm_mgmt_util (CMU) for synchronizing keys between clusters. You might use cloned clusters for cross-region redundancy or to simplify your disaster recovery process. For more information, see syncKey.