Disconnect an Amazon CloudHSM key store - Amazon Key Management Service
Disconnect your Amazon CloudHSM key store
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Disconnect an Amazon CloudHSM key store

When you disconnect an Amazon CloudHSM key store, Amazon KMS logs out of the Amazon CloudHSM client, disconnects from the associated Amazon CloudHSM cluster, and removes the network infrastructure that it created to support the connection.

While an Amazon CloudHSM key store is disconnected, you can manage the Amazon CloudHSM key store and its KMS keys, but you cannot create or use KMS keys in the Amazon CloudHSM key store. The connection state of the key store is DISCONNECTED and the key state of KMS keys in the custom key store is Unavailable, unless they are PendingDeletion. You can reconnect the Amazon CloudHSM key store at any time.

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 disconnect a custom key store, the KMS keys in the key store become unusable right away (subject to eventual consistency). However, resources encrypted with data keys protected by the KMS key are not affected until the KMS key is used again, such as to decrypt the data key. This issue affects Amazon Web Services services, many of which use data keys to protect your resources. For details, see How unusable KMS keys affect data keys.

Note

While a custom key store is disconnected, all attempts to create KMS keys in the custom key store or to use existing KMS keys in cryptographic operations will fail. This action can prevent users from storing and accessing sensitive data.

To better estimate the effect of disconnecting your custom key store, identify the KMS keys in the custom key store and determine their past use.

You might disconnect an Amazon CloudHSM key store for reasons such as the following:

  • To rotate of the kmsuser password. Amazon KMS changes the kmsuser password each time that it connects to the Amazon CloudHSM cluster. To force a password rotation, just disconnect and reconnect.

  • To audit the key material for the KMS keys in the Amazon CloudHSM cluster. When you disconnect the custom key store, Amazon KMS logs out of the kmsuser crypto user account in the Amazon CloudHSM client. This allows you to log into the cluster as the kmsuser CU and audit and manage the key material for the KMS key.

  • To immediately disable all KMS keys in the Amazon CloudHSM key store. You can disable and re-enable KMS keys in an Amazon CloudHSM key store by using the Amazon Web Services Management Console or the DisableKey operation. These operations complete quickly, but they act on one KMS key at a time. Disconnecting the Amazon CloudHSM key store immediately changes the key state of all KMS keys in the Amazon CloudHSM key store to Unavailable, which prevents them from being used in any cryptographic operation.

  • To repair a failed connection attempt. If an attempt to connect an Amazon CloudHSM key store fails (the connection state of the custom key store is FAILED), you must disconnect the Amazon CloudHSM key store before you try to connect it again.

Disconnect your Amazon CloudHSM key store

You can disconnect your Amazon CloudHSM key store in the Amazon KMS console or by using the DisconnectCustomKeyStore operation.

To disconnect a connected Amazon CloudHSM key store in the Amazon KMS console, begin by choosing the Amazon CloudHSM key store from the Custom Key Stores page.

  1. 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.

  2. To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Custom key stores, Amazon CloudHSM key stores.

  4. Choose the row of the external key store you want to disconnect.

  5. From the Key store actions menu, choose Disconnect.

When the operation completes, the connection state changes from Disconnecting to Disconnected. If the operation fails, 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.

To disconnect a connected Amazon CloudHSM key store, use the DisconnectCustomKeyStore operation. If the operation is successful, Amazon KMS returns an HTTP 200 response and a JSON object with no properties.

The examples in this section use the Amazon Command Line Interface (Amazon CLI), but you can use any supported programming language.

This example disconnects an Amazon CloudHSM key store. Before running this example, replace the example ID with a valid one.

$ aws kms disconnect-custom-key-store --custom-key-store-id cks-1234567890abcdef0

To verify that the Amazon CloudHSM key store is disconnected, 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 and CustomKeyStoreName parameter (but not both) to limit the response to particular custom key stores. The ConnectionState value of DISCONNECTED indicates that this example Amazon CloudHSM key store is not connected to its Amazon CloudHSM cluster.

$ aws kms describe-custom-key-stores --custom-key-store-id cks-1234567890abcdef0
{
   "CustomKeyStores": [
      "CloudHsmClusterId": "cluster-1a23b4cdefg",
      "ConnectionState": "DISCONNECTED",
      "CreationDate": "1.499288695918E9",
      "CustomKeyStoreId": "cks-1234567890abcdef0",
      "CustomKeyStoreName": "ExampleKeyStore",
      "CustomKeyStoreType": "AWS_CLOUDHSM",
      "TrustAnchorCertificate": "<certificate string appears here>"
   ],
}