Connect an Amazon CloudHSM key store
New Amazon CloudHSM key stores are not connected. Before you can create and use Amazon KMS keys in your Amazon CloudHSM key store, you need to connect it to its associated Amazon CloudHSM cluster. You can connect and disconnect your Amazon CloudHSM key store at any time, and view its connection state.
You are not required to connect your Amazon CloudHSM key store. You can leave an Amazon CloudHSM key store in a disconnected state indefinitely and connect it only when you need to use it. However, you might want to test the connection periodically to verify that the settings are correct and it can be connected.
Note
Amazon CloudHSM key stores have a DISCONNECTED
connection state only when the key store has never been connected or you explicitly disconnect it. If your Amazon CloudHSM key store connection state
is CONNECTED
but you are having trouble using it, make sure that its
associated Amazon CloudHSM cluster is active and contains at least one active HSMs. For help with
connection failures, see Troubleshooting a custom key store.
When you connect an Amazon CloudHSM key store, Amazon KMS finds the associated Amazon CloudHSM cluster, connects to
it, logs into the Amazon CloudHSM client as the kmsuser
crypto user (CU), and then rotates the kmsuser
password. Amazon KMS remains
logged into the Amazon CloudHSM client as long as the Amazon CloudHSM key store is connected.
To establish the connection, Amazon KMS creates a security group named
kms-
in the virtual private
cloud (VPC) of the cluster. The security group has a single rule that allows inbound traffic
from the cluster security group. Amazon KMS also creates an elastic network interface (ENI)
in each Availability Zone of the private subnet for the cluster. Amazon KMS adds the ENIs to the
<custom key store ID>
kms-
security group and the security
group for the cluster. The description of each ENI is <cluster ID>
KMS managed ENI for cluster
.<cluster-ID>
The connection process can take an extended amount of time to complete; up to 20 minutes.
Before you connect the Amazon CloudHSM key store, verify that it meets the requirements.
-
Its associated Amazon CloudHSM cluster must contain at least one active HSM. To find the number of HSMs in the cluster, view the cluster in the Amazon CloudHSM console or use the DescribeClusters operation. If necessary, you can add an HSM.
-
The cluster must have a kmsuser crypto user (CU) account, but that CU cannot be logged into the cluster when you connect the Amazon CloudHSM key store. For help with logging out, see How to log out and reconnect.
-
The connection state of the Amazon CloudHSM key store cannot be
DISCONNECTING
orFAILED
. To view the connection state, use the Amazon KMS console or the DescribeCustomKeyStores response. If the connection state isFAILED
, disconnect the custom key store, fix the problem, and then connect it.
For help with connection failures, see How to fix a connection failure.
When your Amazon CloudHSM key store is connected, you can create KMS keys in it and use existing KMS keys in cryptographic operations.
Connect and reconnect to your Amazon CloudHSM key store
You can connect, or reconnect, your Amazon CloudHSM key store in the Amazon KMS console or by using the ConnectCustomKeyStore operation.
To connect an Amazon CloudHSM key store in the Amazon Web Services Management Console, begin by selecting the Amazon CloudHSM key store from the Custom key stores page. The connection process can take up to 20 minutes to complete.
-
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 the row of the Amazon CloudHSM key store you want to connect.
If the connection state of the Amazon CloudHSM key store is Failed, you must disconnect the custom key store before you connect it.
-
From the Key store actions menu, choose Connect.
Amazon KMS begins the process of connecting your custom key store. It finds the associated
Amazon CloudHSM cluster, builds the required network infrastructure, connects to it, logs into the
Amazon CloudHSM cluster as the kmsuser
CU, and rotates the kmsuser
password.
When the operation completes, the connection state changes to
Connected.
If the operation fails, an error message appears that describes the reason for the failure. Before you try to connect again, view the connection state of your Amazon CloudHSM key store. If it is Failed, you must disconnect the custom key store before you connect it again. If you need help, see Troubleshooting a custom key store.
To connect a disconnected Amazon CloudHSM key store, use the ConnectCustomKeyStore operation.
The associated Amazon CloudHSM cluster must contain at least one active HSM and the connection state
cannot be FAILED
.
The connection process takes an extended amount of time to complete; up to 20 minutes. Unless it fails quickly, the operation returns an HTTP 200 response and a JSON object with no properties. However, this initial response does not indicate that the connection was successful. To determine the connection state of the custom key store, see the DescribeCustomKeyStores response.
The examples in this section use the Amazon Command Line Interface
(Amazon CLI)
To identify the Amazon CloudHSM key store, use its custom key store ID. You can find the ID on the Custom key stores page in the console or by using the DescribeCustomKeyStores operation with no parameters. Before running this example, replace the example ID with a valid one.
$
aws kms connect-custom-key-store --custom-key-store-id
cks-1234567890abcdef0
To verify that the Amazon CloudHSM key store is connected, use the DescribeCustomKeyStores
operation. By default, this operation returns all custom keys stores in your account and
Region. But you can use either the CustomKeyStoreId
or
CustomKeyStoreName
parameter (but not both) to limit the response to
particular custom key stores. The ConnectionState
value of
CONNECTED
indicates that the custom key store is connected to its Amazon CloudHSM
cluster.
Note
The CustomKeyStoreType
field was added to the
DescribeCustomKeyStores
response to distinguish Amazon CloudHSM key stores from
external key stores.
$
aws kms describe-custom-key-stores --custom-key-store-id
cks-1234567890abcdef0
{ "CustomKeyStores": [ "CustomKeyStoreId": "cks-1234567890abcdef0", "CustomKeyStoreName": "ExampleCloudHSMKeyStore", "CloudHsmClusterId": "cluster-1a23b4cdefg", "CustomKeyStoreType": "AWS_CLOUDHSM", "TrustAnchorCertificate": "
<certificate string appears here>
", "CreationDate": "1.499288695918E9", "ConnectionState": "CONNECTED" ], }
If the ConnectionState
value is failed, the
ConnectionErrorCode
element indicates the reason for the failure. In this
case, Amazon KMS could not find an Amazon CloudHSM cluster in your account with the cluster ID
cluster-1a23b4cdefg
. If you deleted the cluster, you can restore it from a backup of the
original cluster and then edit the cluster ID for the
custom key store. For help responding to a connection error code, see How to fix a connection failure.
$
aws kms describe-custom-key-stores --custom-key-store-id
cks-1234567890abcdef0
{ "CustomKeyStores": [ "CustomKeyStoreId": "cks-1234567890abcdef0", "CustomKeyStoreName": "ExampleKeyStore", "CloudHsmClusterId": "cluster-1a23b4cdefg", "CustomKeyStoreType": "AWS_CLOUDHSM", "TrustAnchorCertificate": "
<certificate string appears here>
", "CreationDate": "1.499288695918E9", "ConnectionState": "FAILED" "ConnectionErrorCode": "CLUSTER_NOT_FOUND" ], }