Editing Amazon CloudHSM key store settings - Amazon Key Management Service
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).

Editing Amazon CloudHSM key store settings

You can change the settings of an existing Amazon CloudHSM key store. The custom key store must be disconnected its Amazon CloudHSM cluster.

To edit Amazon CloudHSM key store settings:

  1. Disconnect the custom key store from its Amazon CloudHSM cluster. While the custom key store is disconnected, you cannot create Amazon KMS keys (KMS keys) in the custom key store and you cannot use the KMS keys it contains for cryptographic operations.

  2. Edit one or more of the Amazon CloudHSM key store settings.

  3. Reconnect the custom key store to its Amazon CloudHSM cluster.

You can edit the following settings in a custom key store:

The friendly name of the custom key store.

Enter a new friendly name. The new name must be unique among all custom key stores in your Amazon Web Services 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.

The cluster ID of the associated Amazon CloudHSM cluster.

Edit this value to substitute a related Amazon CloudHSM cluster for the original one. You can use this feature to repair a custom key store if its Amazon CloudHSM cluster becomes corrupted or is deleted.

Specify an Amazon CloudHSM cluster that shares a backup history with the original cluster and fulfills the requirements for association with a custom key store, including two active HSMs in different Availability Zones. Clusters that share a backup history have the same cluster certificate. To view the cluster certificate of a cluster, use the DescribeClusters operation. You cannot use the edit feature to associate the custom key store with an unrelated Amazon CloudHSM cluster.

The current password of the kmsuser crypto user (CU).

Tells Amazon KMS the current password of the kmsuser CU in the Amazon CloudHSM cluster. This action does not change the password of the kmsuser CU in the Amazon CloudHSM cluster.

If you change the password of the kmsuser CU in the Amazon CloudHSM cluster, use this feature to tell Amazon KMS the new kmsuser password. Otherwise, Amazon KMS cannot log into the cluster and all attempts to connect the custom key store to the cluster fail.

Edit an Amazon CloudHSM key store (console)

When you edit an Amazon CloudHSM key store, you can change any or of the configurable values.

  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 Amazon CloudHSM key store you want to edit.

    If the value in the Connection state column is not Disconnected, you must disconnect the custom key store before you can edit it. (From the Key store actions menu, choose Disconnect.)

    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.

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

  6. Do one or more of the following actions.

    • Type a new friendly name for the custom key store.

    • Type the cluster ID of a related Amazon CloudHSM cluster.

    • Type the current password of the kmsuser crypto user in the associated Amazon CloudHSM cluster.

  7. Choose Save.

    When the procedure is successful, a message describes the settings that you edited. When 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.

  8. Reconnect the custom key store.

    To use the Amazon CloudHSM key store, you must reconnect it after editing. You can leave the Amazon CloudHSM key store disconnected. But while it is disconnected, you cannot create KMS keys in the Amazon CloudHSM key store or use the KMS keys in the Amazon CloudHSM key store in cryptographic operations.

Edit an Amazon CloudHSM key store (API)

To change the properties of an Amazon CloudHSM key store, use the UpdateCustomKeyStore operation. You can change multiple properties of a custom key store in the same command. If the operation is successful, Amazon KMS returns an HTTP 200 response and a JSON object with no properties. To verify that the changes are effective, use the DescribeCustomKeyStores operation.

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

Begin by using DisconnectCustomKeyStore to disconnect the custom key store from its Amazon CloudHSM cluster. Replace the example custom key store ID, cks-1234567890abcdef0, with an actual ID.

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

The first example uses UpdateCustomKeyStore to change the friendly name of the Amazon CloudHSM key store to DevelopmentKeys. The command uses the CustomKeyStoreId parameter to identify the Amazon CloudHSM key store and the CustomKeyStoreName to specify the new name for the custom key store.

$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --new-custom-key-store-name DevelopmentKeys

The following example changes the cluster that is associated with an Amazon CloudHSM key store to another backup of the same cluster. The command uses the CustomKeyStoreId parameter to identify the Amazon CloudHSM key store and the CloudHsmClusterId parameter to specify the new cluster ID.

$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --cloud-hsm-cluster-id cluster-1a23b4cdefg

The following example tells Amazon KMS that the current kmsuser password is ExamplePassword. The command uses the CustomKeyStoreId parameter to identify the Amazon CloudHSM key store and the KeyStorePassword parameter to specify the current password.

$ aws kms update-custom-key-store --custom-key-store-id cks-1234567890abcdef0 --key-store-password ExamplePassword

The final command reconnects the Amazon CloudHSM key store to its Amazon CloudHSM cluster. You can leave the custom key store in the disconnected state, but you must connect it before you can create new KMS keys or use existing KMS keys for cryptographic operations. Replace the example custom key store ID with an actual ID.

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