Note: You are viewing the documentation for an older major version of the AWS CLI (version 1).

AWS CLI version 2, the latest major version of AWS CLI, is now stable and recommended for general use. To view this page for the AWS CLI version 2, click here. For more information see the AWS CLI version 2 installation instructions and migration guide.

[ aws . kms ]



Creates a custom key store that is associated with an CloudHSM cluster that you own and manage.

This operation is part of the Custom Key Store feature feature in KMS, which combines the convenience and extensive integration of KMS with the isolation and control of a single-tenant key store.

Before you create the custom key store, you must assemble the required elements, including an CloudHSM cluster that fulfills the requirements for a custom key store. For details about the required elements, see Assemble the Prerequisites in the Key Management Service Developer Guide .

When the operation completes successfully, it returns the ID of the new custom key store. Before you can use your new custom key store, you need to use the ConnectCustomKeyStore operation to connect the new key store to its CloudHSM cluster. Even if you are not going to use your custom key store immediately, you might want to connect it to verify that all settings are correct and then disconnect it until you are ready to use it.

For help with failures, see Troubleshooting a Custom Key Store in the Key Management Service Developer Guide .

Cross-account use : No. You cannot perform this operation on a custom key store in a different Amazon Web Services account.

Required permissions : kms:CreateCustomKeyStore (IAM policy).

Related operations:

  • ConnectCustomKeyStore
  • DeleteCustomKeyStore
  • DescribeCustomKeyStores
  • DisconnectCustomKeyStore
  • UpdateCustomKeyStore

See also: AWS API Documentation

See 'aws help' for descriptions of global parameters.


--custom-key-store-name <value>
--cloud-hsm-cluster-id <value>
--trust-anchor-certificate <value>
--key-store-password <value>
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]


--custom-key-store-name (string)

Specifies a friendly name for the custom key store. The name must be unique in your Amazon Web Services account.

--cloud-hsm-cluster-id (string)

Identifies the CloudHSM cluster for the custom key store. Enter the cluster ID of any active CloudHSM cluster that is not already associated with a custom key store. To find the cluster ID, use the DescribeClusters operation.

--trust-anchor-certificate (string)

Enter the content of the trust anchor certificate for the cluster. This is the content of the customerCA.crt file that you created when you initialized the cluster .

--key-store-password (string)

Enter the password of the ` kmsuser crypto user (CU) account <>`__ in the specified CloudHSM cluster. KMS logs into the cluster as this user to manage key material on your behalf.

The password must be a string of 7 to 32 characters. Its value is case sensitive.

This parameter tells KMS the kmsuser account password; it does not change the password in the CloudHSM cluster.

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See 'aws help' for descriptions of global parameters.


To create a custom key store

The following create-custom-key-store example creates a custom key store with an existing custom key store.

  • This example uses the custom-key-store-name parameter to assign ExampleKeyStore as a friendly name for the key store.

  • It uses the cloud-hsm-cluster-id parameter to identify the cluster-1a23b4cdefg cluster.

  • It uses the key-store-password parameter to provide the password of the kmsuser user in the cluster-1a23b4cdefg cluster. This gives AWS KMS permission to use the cluster on your behalf.

  • It uses the trust-anchor-certificate parameter to specify the customerCA.crt file. In the AWS CLI, the file:// prefix is required.

    aws kms create-custom-key-store \
        --custom-key-store-name ExampleKeyStore \
        --cloud-hsm-cluster-id cluster-1a23b4cdefg \
        --key-store-password kmsPswd \
        --trust-anchor-certificate file://customerCA.crt

The output of this command includes the ID of the new custom key store. You can use this ID to identify the custom key store in other AWS KMS CLI commands.

    "CustomKeyStoreId": cks-1234567890abcdef0

For more information, see Creating a Custom Key Store in the AWS Key Management Service Developer Guide.


CustomKeyStoreId -> (string)

A unique identifier for the new custom key store.