Viewing an Amazon CloudHSM key store - Amazon Key Management Service
View an Amazon CloudHSM key store (console)View an Amazon CloudHSM key store (API)
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).

Viewing an Amazon CloudHSM key store

You can view the Amazon CloudHSM key stores in each account and Region by using the Amazon KMS console or the DescribeCustomKeyStores operation.

See also:

View an Amazon CloudHSM key store (console)

When you view the Amazon CloudHSM key stores in the Amazon Web Services Management Console, you can see the following:

  • The custom key store name and ID

  • The ID of associated Amazon CloudHSM cluster

  • The number of HSMs in the cluster

  • The current connection state

A connection state (Status) value of Disconnected indicates that the custom key store is new and has never been connected, or it was intentionally disconnected from its Amazon CloudHSM cluster. However, if your attempts to use a KMS key in a connected custom key store fail, that might indicate a problem with the custom key store or its Amazon CloudHSM cluster. For help, see How to fix a failing KMS key.

To view the Amazon CloudHSM key stores in a given account and Region, use the following procedure.

  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.

To customize the display, click the gear icon that appears below the Create key store button.

View an Amazon CloudHSM key store (API)

To view your Amazon CloudHSM key stores, use the DescribeCustomKeyStores operation. By default, this operation returns all custom key stores in the account and Region. But you can use either the CustomKeyStoreId or CustomKeyStoreName parameter (but not both) to limit the output to a particular custom key store. For Amazon CloudHSM key stores, the output consists of the custom key store ID and name, the custom key store type, the ID of the associated Amazon CloudHSM cluster, and the connection state. If the connection state indicates an error, the output also includes an error code that describes the reason for the error.

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

For example, the following command returns all custom key stores in the account and Region. You can use the Limit and Marker parameters to page through the custom key stores in the output.

$ aws kms describe-custom-key-stores

The following example command uses the CustomKeyStoreName parameter to get only the custom key store with the ExampleCloudHSMKeyStore friendly name. You can use either the CustomKeyStoreName or CustomKeyStoreId parameter (but not both) in each command.

The following example output represents an Amazon CloudHSM key store that 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-name ExampleCloudHSMKeyStore
{
   "CustomKeyStores": [ 
      { 
         "CloudHsmClusterId": "cluster-1a23b4cdefg",
         "ConnectionState": "CONNECTED",
         "CreationDate": "1.499288695918E9",
         "CustomKeyStoreId": "cks-1234567890abcdef0",
         "CustomKeyStoreName": "ExampleCloudHSMKeyStore",
         "CustomKeyStoreType": "AWS_CLOUDHSM",
         "TrustAnchorCertificate": "<certificate appears here>"
      }
   ]
}

A ConnectionState of Disconnected indicates that a custom key store has never been connected or it was intentionally disconnected from its Amazon CloudHSM cluster. However, if attempts to use a KMS key in a connected Amazon CloudHSM key store fail, that might indicate a problem with the Amazon CloudHSM key store or its Amazon CloudHSM cluster. For help, see How to fix a failing KMS key.

If the ConnectionState of the custom key store is FAILED, the DescribeCustomKeyStores response includes a ConnectionErrorCode element that explains the reason for the error.

For example, in the following output, the INVALID_CREDENTIALS value indicates that the custom key store connection failed because the kmsuser password is invalid. For help with this and other connection error failures, see Troubleshooting a custom key store.

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