Assemble the prerequisites Create an Amazon CloudHSM key store (console)Create an Amazon CloudHSM key store (API)

Creating an Amazon CloudHSM key store

You can create one or several Amazon CloudHSM key stores in your account. Each Amazon CloudHSM key store is associated with one Amazon CloudHSM cluster in the same Amazon Web Services account and Region. Before you create your Amazon CloudHSM key store, you need to assemble the prerequisites. Then, before you can use your Amazon CloudHSM key store, you must connect it to its Amazon CloudHSM cluster.

Note

If you try to create an Amazon CloudHSM key store with all of the same property values as an existing disconnected Amazon CloudHSM key store, Amazon KMS does not create a new Amazon CloudHSM key store, and it does not throw an exception or display an error. Instead, Amazon KMS recognizes the duplicate as the likely consequence of a retry, and it returns the ID of the existing Amazon CloudHSM key store.

Tip

You do not have to connect your Amazon CloudHSM key store immediately. You can leave it in a disconnected state until you are ready to use it. However, to verify that it is configured properly, you might want to connect it, view its connection state, and then disconnect it.

Topics

Assemble the prerequisites
Create an Amazon CloudHSM key store (console)
Create an Amazon CloudHSM key store (API)

Assemble the prerequisites

Each Amazon CloudHSM key store is backed by an Amazon CloudHSM cluster. To create an Amazon CloudHSM key store, you must specify an active Amazon CloudHSM cluster that is not already associated with another key store. You also need to create a dedicated crypto user (CU) in the cluster's HSMs that Amazon KMS can use to create and manage keys on your behalf.

Before you create an Amazon CloudHSM key store, do the following:

Select an Amazon CloudHSM cluster

Every Amazon CloudHSM key store is associated with exactly one Amazon CloudHSM cluster. When you create a Amazon KMS keys in your Amazon CloudHSM key store, Amazon KMS creates the KMS key metadata, such as an ID and Amazon Resource Name (ARN) in Amazon KMS. It then creates the key material in the HSMs of the associated cluster. You can create a new Amazon CloudHSM cluster or use an existing one. Amazon KMS does not require exclusive access to the cluster.

The Amazon CloudHSM cluster that you select is permanently associated with the Amazon CloudHSM key store. After you create the Amazon CloudHSM key store, you can change the cluster ID of the associated cluster, but the cluster that you specify must share a backup history with the original cluster. To use an unrelated cluster, you need to create a new Amazon CloudHSM key store.

The Amazon CloudHSM cluster that you select must have the following characteristics:

The cluster must be active.

You must create the cluster, initialize it, install the Amazon CloudHSM client software for your platform, and then activate the cluster. For detailed instructions, see Getting started with Amazon CloudHSM in the Amazon CloudHSM User Guide.
The cluster must be in the same account and Region as the Amazon CloudHSM key store. You cannot associate an Amazon CloudHSM key store in one Region with a cluster in a different Region. To create a key infrastructure in multiple Regions, you must create Amazon CloudHSM key stores and clusters in each Region.
The cluster cannot be associated with another custom key store in the same account and Region. Each Amazon CloudHSM key store in the account and Region must be associated with a different Amazon CloudHSM cluster. You cannot specify a cluster that is already associated with a custom key store or a cluster that shares a backup history with an associated cluster. Clusters that share a backup history have the same cluster certificate. To view the cluster certificate of a cluster, use the Amazon CloudHSM console or the DescribeClusters operation.

If you back up an Amazon CloudHSM cluster to a different Region, it is considered to be different cluster, and you can associate the backup with a custom key store in its Region. However, KMS keys in the two custom key stores are not interoperable, even if they have the same backing key. Amazon KMS binds metadata to the ciphertext so it can be decrypted only by the KMS key that encrypted it.
The cluster must be configured with private subnets in at least two Availability Zones in the Region. Because Amazon CloudHSM is not supported in all Availability Zones, we recommend that you create private subnets in all Availability Zones in the region. You cannot reconfigure the subnets for an existing cluster, but you can create a cluster from a backup with different subnets in the cluster configuration.

Important
After you create your Amazon CloudHSM key store, do not delete any of the private subnets configured for its Amazon CloudHSM cluster. If Amazon KMS cannot find all of the subnets in the cluster configuration, attempts to connect to the custom key store fail with a SUBNET_NOT_FOUND connection error state. For details, see How to fix a connection failure.
The security group for the cluster (cloudhsm-cluster-<cluster-id>-sg) must include inbound rules and outbound rules that allow TCP traffic on ports 2223-2225. The Source in the inbound rules and the Destination in the outbound rules must match the security group ID. These rules are set by default when you create the cluster. Do not delete or change them.
The cluster must contain at least two active HSMs in different Availability Zones. To verify the number of HSMs, use the Amazon CloudHSM console or the DescribeClusters operation. If necessary, you can add an HSM.

Find the trust anchor certificate

When you create a custom key store, you must upload the trust anchor certificate for the Amazon CloudHSM cluster to Amazon KMS. Amazon KMS needs the trust anchor certificate to connect the Amazon CloudHSM key store to its associated Amazon CloudHSM cluster.

Every active Amazon CloudHSM cluster has a trust anchor certificate. When you initialize the cluster, you generate this certificate, save it in the customerCA.crt file, and copy it to hosts that connect to the cluster.

Create the kmsuser crypto user for Amazon KMS

To administer your Amazon CloudHSM key store, Amazon KMS logs into the kmsuser crypto user (CU) account in the selected cluster. Before you create your Amazon CloudHSM key store, you must create the kmsuser CU. Then when you create your Amazon CloudHSM key store, you provide the password for kmsuser to Amazon KMS. Whenever you connect the Amazon CloudHSM key store to its associated Amazon CloudHSM cluster, Amazon KMS logs in as the kmsuser and rotates the kmsuser password

Important

Do not specify the 2FA option when you create the kmsuser CU. If you do, Amazon KMS cannot log in and your Amazon CloudHSM key store cannot be connected to this Amazon CloudHSM cluster. Once you specify 2FA, you cannot undo it. Instead, you must delete the CU and recreate it.

To create the kmsuser CU, use the following procedure.

Start cloudhsm_mgmt_util as described in the Getting started with CloudHSM Management Utility (CMU) topic of the Amazon CloudHSM User Guide.
Use the createUser command in cloudhsm_mgmt_util to create a CU named kmsuser. The password must consist of 7-32 alphanumeric characters. It is case-sensitive and cannot contain any special characters.

For example, the following example command creates a kmsuser CU with a password of kmsPswd.
```
aws-cloudhsm> createUser CU kmsuser kmsPswd
```

Create an Amazon CloudHSM key store (console)

When you create an Amazon CloudHSM key store in the Amazon Web Services Management Console, you can add and create the prerequisites as part of your workflow. However, the process is quicker when you have assembled them in advance.

Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.
To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.
In the navigation pane, choose Custom key stores, Amazon CloudHSM key stores.
Choose Create a key store.
Enter a friendly name for the custom key store. The name must be unique among all custom key stores in your account.

Important
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
Select an Amazon CloudHSM cluster for the Amazon CloudHSM key store. Or, to create a new Amazon CloudHSM cluster, choose the Create an Amazon CloudHSM cluster link.

The menu displays the Amazon CloudHSM clusters in your account and region that are not already associated with an Amazon CloudHSM key store. The cluster must fulfill the requirements for association with a custom key store.
Choose Choose file, and then upload the trust anchor certificate for the Amazon CloudHSM cluster that you chose. This is the customerCA.crt file that you created when you initialized the cluster.
Enter the password of the kmsuser crypto user (CU) that you created in the selected cluster.
Choose Create.

When the procedure is successful, the new Amazon CloudHSM key store appears in the list of Amazon CloudHSM key stores in the account and Region. If it is unsuccessful, an error message appears that describes the problem and provides help on how to fix it. If you need more help, see Troubleshooting a custom key store.

Next: New Amazon CloudHSM key stores are not automatically connected. Before you can create Amazon KMS keys in the Amazon CloudHSM key store, you must connect the custom key store to its associated Amazon CloudHSM cluster.

Create an Amazon CloudHSM key store (API)

You can use the CreateCustomKeyStore operation to create a new Amazon CloudHSM key store that is associated with an Amazon CloudHSM cluster in the account and Region. These examples use the Amazon Command Line Interface (Amazon CLI), but you can use any supported programming language.

The CreateCustomKeyStore operation requires the following parameter values.

CustomKeyStoreName – A friendly name for the custom key store that is unique in the account.

Important
Do not include confidential or sensitive information in this field. This field may be displayed in plaintext in CloudTrail logs and other output.
CloudHsmClusterId – The cluster ID of an Amazon CloudHSM cluster that fulfills the requirements for an Amazon CloudHSM key store.
KeyStorePassword – The password of kmsuser CU account in the specified cluster.
TrustAnchorCertificate – The content of the customerCA.crt file that you created when you initialized the cluster.

The following example uses a fictitious cluster ID. Before running the command, replace it with a valid cluster ID.


$ aws kms create-custom-key-store
        --custom-key-store-name ExampleCloudHSMKeyStore \
        --cloud-hsm-cluster-id cluster-1a23b4cdefg \
        --key-store-password kmsPswd \
        --trust-anchor-certificate <certificate-goes-here>

If you are using the Amazon CLI, you can specify the trust anchor certificate file, instead of its contents. In the following example, the customerCA.crt file is in the root directory.


$ aws kms create-custom-key-store
        --custom-key-store-name ExampleCloudHSMKeyStore \
        --cloud-hsm-cluster-id cluster-1a23b4cdefg \
        --key-store-password kmsPswd \
        --trust-anchor-certificate file://customerCA.crt

When the operation is successful, CreateCustomKeyStore returns the custom key store ID, as shown in the following example response.


{
    "CustomKeyStoreId": cks-1234567890abcdef0
}

If the operation fails, correct the error indicated by the exception, and try again. For additional help, see Troubleshooting a custom key store.

Next: To use the Amazon CloudHSM key store, connect it to its Amazon CloudHSM cluster.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Managing a CloudHSM custom key store

Viewing an Amazon CloudHSM key store