[ aws . kms ]

create-custom-key-store

Description

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.

Synopsis

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

Options

--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 <https://docs.aws.amazon.com/kms/latest/developerguide/key-store-concepts.html#concept-kmsuser>`__ 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 | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those 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. This may not be specified along with --cli-input-yaml.

--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. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. 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.

Examples

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.

Output

CustomKeyStoreId -> (string)

A unique identifier for the new custom key store.