Create a KMS key in an Amazon CloudHSM key store
After you have created an Amazon CloudHSM key store, you can create Amazon KMS keys in your key store. They must be symmetric encryption KMS keys with key material that Amazon KMS generates. You cannot create asymmetric KMS keys, HMAC KMS keys or KMS keys with imported key material in a custom key store. Also, you cannot use symmetric encryption KMS keys in a custom key store to generate asymmetric data key pairs.
To create a KMS key in an Amazon CloudHSM key store, the Amazon CloudHSM key store must be connected to the associated Amazon CloudHSM cluster and the cluster must contain at least two active HSMs in different Availability Zones. To find the connection state and number of HSMs, view the Amazon CloudHSM key stores page in the Amazon Web Services Management Console. When using the API operations, use the DescribeCustomKeyStores operation to verify that the Amazon CloudHSM key store is connected. To verify the number of active HSMs in the cluster and their Availability Zones, use the Amazon CloudHSM DescribeClusters operation.
When you create a KMS key in your Amazon CloudHSM key store, Amazon KMS creates the KMS key in Amazon KMS. But, it creates the key material for the KMS key in the associated Amazon CloudHSM cluster. Specifically, Amazon KMS signs into the cluster as the kmsuser CU that you created. Then it creates a persistent, non-extractable, 256-bit Advanced Encryption Standard (AES) symmetric key in the cluster. Amazon KMS sets the value of the key label attribute, which is visible only in the cluster, to Amazon Resource Name (ARN) of the KMS key.
When the command succeeds, the key state of the new
KMS key is Enabled
and its origin is AWS_CLOUDHSM
. You cannot change
the origin of any KMS key after you create it. When you view a KMS key in an Amazon CloudHSM key store
in the Amazon KMS console or by using the DescribeKey operation, you can see typical properties, like its key ID, key state,
and creation date. But you can also see the custom key store ID and (optionally) the Amazon CloudHSM
cluster ID.
If your attempt to create a KMS key in your Amazon CloudHSM key store fails, use the error message
to help you determine the cause. It might indicate that the Amazon CloudHSM key store is not connected
(CustomKeyStoreInvalidStateException
) or the associated Amazon CloudHSM cluster doesn't
have the two active HSMs that are required for this operation
(CloudHsmClusterInvalidConfigurationException
). For help see Troubleshooting a custom key store.
For an example of the Amazon CloudTrail log of the operation that creates a KMS key in an Amazon CloudHSM key store, see CreateKey.
Create a new KMS key in your CloudHSM key store
You can create a symmetric encryption KMS key in your Amazon CloudHSM key store in the Amazon KMS console or by using the CreateKey operation.
Use the following procedure to create a symmetric encryption KMS key in an Amazon CloudHSM key store.
Note
Do not include confidential or sensitive information in the alias, description, or tags. These fields may appear in plain text in CloudTrail logs and other output.
-
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
. -
To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.
-
In the navigation pane, choose Customer managed keys.
-
Choose Create key.
-
Choose Symmetric.
-
In Key usage, the Encrypt and decrypt option is selected for you. Do not change it.
-
Choose Advanced options.
-
For Key material origin, choose Amazon CloudHSM key store.
You cannot create a multi-Region key in an Amazon CloudHSM key store.
-
Choose Next.
-
Select an Amazon CloudHSM key store for your new KMS key. To create a new Amazon CloudHSM key store, choose Create custom key store.
The Amazon CloudHSM key store that you select must have a status of Connected. Its associated Amazon CloudHSM cluster must be active and contain at least two active HSMs in different Availability Zones.
For help with connecting an Amazon CloudHSM key store, see Disconnect an Amazon CloudHSM key store. For help with adding HSMs, see Adding an HSM in the Amazon CloudHSM User Guide.
-
Choose Next.
-
Type an alias and an optional description for the KMS key.
-
(Optional). On the Add Tags page, add tags that identify or categorize your KMS key.
When you add tags to your Amazon resources, Amazon generates a cost allocation report with usage and costs aggregated by tags. Tags can also be used to control access to a KMS key. For information about tagging KMS keys, see Tags in Amazon KMS and ABAC for Amazon KMS.
-
Choose Next.
-
In the Key Administrators section, select the IAM users and roles who can manage the KMS key. For more information, see Allows key administrators to administer the KMS key.
Note
IAM policies can give other IAM users and roles permission to use the KMS key.
IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see Security best practices in IAM
in the IAM User Guide. -
(Optional) To prevent these key administrators from deleting this KMS key, clear the box at the bottom of the page for Allow key administrators to delete this key.
-
Choose Next.
-
In the This account section, select the IAM users and roles in this Amazon Web Services account that can use the KMS key in cryptographic operations. For more information, see Allows key users to use the KMS key.
Note
IAM policies can give other IAM users and roles permission to use the KMS key.
IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see Security best practices in IAM
in the IAM User Guide. -
(Optional) You can allow other Amazon Web Services accounts to use this KMS key for cryptographic operations. To do so, in the Other Amazon Web Services accounts section at the bottom of the page, choose Add another Amazon Web Services account and enter the Amazon Web Services account ID of an external account. To add multiple external accounts, repeat this step.
Note
Administrators of the other Amazon Web Services accounts must also allow access to the KMS key by creating IAM policies for their users. For more information, see Allowing users in other accounts to use a KMS key.
-
Choose Next.
-
Review the key settings that you chose. You can still go back and change all settings.
-
When you're done, choose Finish to create the key.
When the procedure succeeds, the display shows the new KMS key in the Amazon CloudHSM key store that you chose. When you choose the name or alias of the new KMS key, the Cryptographic configuration tab on its detail page displays the origin of the KMS key (Amazon CloudHSM), the name, ID, and type of the custom key store, and the ID of the Amazon CloudHSM cluster. If the procedure fails, an error message appears that describes the failure.
Tip
To make it easier to identify KMS keys in a custom key store, on the Customer managed keys page, add the Custom key store ID column to the display. Click the gear icon in the upper-right and select Custom key store ID. For details, see Customize your console view.
To create a new Amazon KMS key (KMS key) in your Amazon CloudHSM
key store, use the CreateKey operation.
Use the CustomKeyStoreId
parameter to identify your custom key store and
specify an Origin
value of AWS_CLOUDHSM
.
You might also want to use the Policy
parameter to specify a key policy.
You can change the key policy (PutKeyPolicy) and add optional elements, such as a description and tags at any time.
The examples in this section use the Amazon Command Line Interface
(Amazon CLI)
The following example begins with a call to the DescribeCustomKeyStores
operation to verify that the Amazon CloudHSM key store is connected to its associated Amazon CloudHSM cluster.
By default, this operation returns all custom keys stores in your account and Region. To
describe only a particular Amazon CloudHSM key store, use its CustomKeyStoreId
or
CustomKeyStoreName
parameter (but not both).
Before running this command, replace the example custom key store ID with a valid ID.
Note
Do not include confidential or sensitive information in the Description
or Tags
fields. These fields may appear in plain text in CloudTrail logs and other output.
$
aws kms describe-custom-key-stores --custom-key-store-id
cks-1234567890abcdef0
{ "CustomKeyStores": [ "CustomKeyStoreId": "cks-1234567890abcdef0", "CustomKeyStoreName": "ExampleKeyStore", "CustomKeyStoreType": "Amazon CloudHSM key store", "CloudHsmClusterId": "cluster-1a23b4cdefg", "TrustAnchorCertificate": "
<certificate string appears here>
", "CreationDate": "1.499288695918E9", "ConnectionState": "CONNECTED" ], }
The next example command uses the DescribeClusters operation to verify that the Amazon CloudHSM cluster that is associated
with the ExampleKeyStore
(cluster-1a23b4cdefg) has at least two active
HSMs. If the cluster has fewer than two HSMs, the CreateKey
operation
fails.
$
aws cloudhsmv2 describe-clusters
{ "Clusters": [ { "SubnetMapping": { ... }, "CreateTimestamp": 1507133412.351, "ClusterId": "cluster-1a23b4cdefg", "SecurityGroup": "sg-865af2fb", "HsmType": "hsm1.medium", "VpcId": "vpc-1a2b3c4d", "BackupPolicy": "DEFAULT", "Certificates": { "ClusterCertificate": "-----BEGIN CERTIFICATE-----\...\n-----END CERTIFICATE-----\n" }, "Hsms": [ { "AvailabilityZone": "us-west-2a", "EniIp": "10.0.1.11", "ClusterId": "cluster-1a23b4cdefg", "EniId": "eni-ea8647e1", "StateMessage": "HSM created.", "SubnetId": "subnet-a6b10bd1", "HsmId": "hsm-abcdefghijk", "State": "ACTIVE" }, { "AvailabilityZone": "us-west-2b", "EniIp": "10.0.0.2", "ClusterId": "cluster-1a23b4cdefg", "EniId": "eni-ea8647e1", "StateMessage": "HSM created.", "SubnetId": "subnet-b6b10bd2", "HsmId": "hsm-zyxwvutsrqp", "State": "ACTIVE" }, ], "State": "ACTIVE" } ] }
This example command uses the CreateKey operation to create a KMS key in an Amazon CloudHSM key store. To create a
KMS key in an Amazon CloudHSM key store, you must provide the custom key store ID of the Amazon CloudHSM key
store and specify an Origin
value of AWS_CLOUDHSM
.
The response includes the IDs of the custom key store and the Amazon CloudHSM cluster.
Before running this command, replace the example custom key store ID with a valid ID.
$
aws kms create-key --origin AWS_CLOUDHSM --custom-key-store-id
cks-1234567890abcdef0
{ "KeyMetadata": { "AWSAccountId": "111122223333", "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "CreationDate": 1.499288695918E9, "Description": "Example key", "Enabled": true, "MultiRegion": false, "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "KeyManager": "CUSTOMER", "KeyState": "Enabled", "KeyUsage": "ENCRYPT_DECRYPT", "Origin": "AWS_CLOUDHSM" "CloudHsmClusterId": "cluster-1a23b4cdefg", "CustomKeyStoreId": "cks-1234567890abcdef0" "KeySpec": "SYMMETRIC_DEFAULT", "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT", "EncryptionAlgorithms": [ "SYMMETRIC_DEFAULT" ] } }