Creating a Custom Key Store

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

Tip

You do not have to connect your custom 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 status, and then disconnect it.

Assemble the Prerequisites

Each AWS KMS custom key store is backed by an AWS CloudHSM cluster. To create a custom
key store,
you must specify an active AWS 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 AWS KMS
can use to create and manage keys on your behalf.

The AWS CloudHSM cluster that you select is permanently associated with the custom
key
store. After you create the custom 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 custom key store.

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

The cluster must be active.

You must create the cluster, initialize it, install the AWS CloudHSM client software
for your platform, and then activate the cluster. For detailed instructions, see
the
Getting Started section of the AWS CloudHSM User Guide.

The cluster must be in the same account and
Region as the AWS KMS custom key store. You cannot associate a custom key
store in one region with a cluster in a different region. To create a multi-region
key infrastructure, you must create key stores and clusters in each region.

The cluster cannot be associated with another
custom key store in the account. Each custom key store must be associated with a
different AWS 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 AWS CloudHSM console
or the DescribeClusters operation.

The cluster must be configured with private subnets in at least two Availability Zones in the Region. Because AWS 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.

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 AWS 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 AWS CloudHSM cluster to AWS KMS. AWS KMS needs the trust anchor certificate
to connect
the custom key store to the cluster.

Every active AWS 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 AWS KMS

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

Important

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

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 a Custom Key Store (Console)

When you create a custom key store in
the AWS 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.

To change the AWS Region, use the Region selector in the upper-right corner of the
page.

In the navigation pane, choose Custom key stores.

Choose Create key store.

Enter a friendly name for the custom key store. The name must be unique in the
account.

Select an AWS CloudHSM cluster for the custom key
store. Or, to create a new AWS CloudHSM cluster, choose the Create an AWS CloudHSM
cluster link.

The cluster must fulfill the requirements for
association with a custom key store. The menu displays custom key stores in your account
and region that are not already associated with a custom key store.

Choose Upload file, and then upload the trust anchor
certificate for the AWS CloudHSM cluster that you chose. This is the
customerCA.crt file that you created when you initialized the
cluster.

When the procedure is successful, the new custom key store appears in the list of
custom
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 custom key stores are not automatically
connected. Before you can create customer master keys (CMKs) in the custom key store,
you
must connect the custom key store to its
associated AWS CloudHSM cluster.

Create a Custom Key Store (API)

The CreateCustomKeyStore
operation creates a new custom key store
that is associated with an AWS CloudHSM cluster in the account and Region. These examples
use the
AWS Command Line Interface (AWS 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.