Create a KMS key in external key stores
After you have created and connected your external key store, you can
create AWS KMS keys in your key store. They must be symmetric encryption KMS keys with an origin value of
External key store (EXTERNAL_KEY_STORE
). 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.
A KMS key in an external key store might have poorer latency, durability and availability than a standard KMS key because it depends on components located outside of AWS. Before creating or using a KMS key in an external key store, verify that you require a key with external key store properties.
Note
Some external key managers provide a simpler method for creating KMS keys in an external key store. For details, see your external key manager documentation.
To create a KMS key in your external key store, you specify the following:
-
The ID of your external key store.
-
A key material origin of External key store (
EXTERNAL_KEY_STORE
). -
The ID of an existing external key in the external key manager associated with your external key store. This external key serves as key material for the KMS key. You cannot change the external key ID after you create the KMS key.
AWS KMS provides the external key ID to your external key store proxy in requests for encryption and decryption operations. AWS KMS cannot directly access your external key manager or any of its cryptographic keys.
In addition to the external key, a KMS key in an external key store also has AWS KMS key material. All data encrypted under the KMS key is first encrypted in AWS KMS using the key's AWS KMS key material and then by your external key manager using your external key. This double encryption process ensures that ciphertext protected by a KMS key in an external key store is at least as strong as ciphertext protected only by AWS KMS. For details, see How external key stores work.
When the CreateKey
operation succeeds, the key
state of the new KMS key is Enabled
. When you view a KMS key in an external key store you can see
typical properties, like its key ID, key spec, key usage, key state, and
creation date. But you can also see the ID and connection state of the external key store and the ID of the external
key.
If your attempt to create a KMS key in your external key store fails, use the error
message to identify the cause. It might indicate that the external key store is not
connected (CustomKeyStoreInvalidStateException
), that your external key store
proxy cannot find an external key with the specified external key ID
(XksKeyNotFoundException
), or that the external key is already associated
with a KMS key in the same external key store
XksKeyAlreadyInUseException
.
For an example of the AWS CloudTrail log of the operation that creates a KMS key in an external key store, see CreateKey.
Topics
Requirements for a KMS key in an external key store
To create a KMS key in an external key store, the following properties are required of the external key store, the KMS key, and the external key that serves as the external cryptographic key material for the KMS key.
External key store requirements
-
Must be connected to its external key store proxy.
To view the connection state of your external key store, see View external key stores. To connect your external key store, see Connect and disconnect external key stores.
KMS key requirements
You cannot change these properties after you create the KMS key.
-
Key spec: SYMMETRIC_DEFAULT
-
Key usage: ENCRYPT_DECRYPT
-
Key material origin: EXTERNAL_KEY_STORE
-
Multi-Region: FALSE
External key requirements
-
256-bit AES cryptographic key (256 random bits). The
KeySpec
of the external key must beAES_256
. -
Enabled and available for use. The
Status
of the external key must beENABLED
. -
Configured for encryption and decryption. The
KeyUsage
of the external key must includeENCRYPT
andDECRYPT
. -
Used only with this KMS key. Each
KMS key
in an external key store must be associated with a different external key.AWS KMS also recommends that the external key be used exclusively for the external key store. This restriction makes it easier to identify and resolve problems with the key.
-
Accessible by the external key store proxy for the external key store.
If the external key store proxy can't find the key using the specified external key ID, the
CreateKey
operation fails. -
Can handle the anticipated traffic that your use of AWS services generates. AWS KMS recommends that external keys be prepared to handle up to 1800 requests per second.
Create a new KMS key in your external key store
You can create a new KMS key in your external key store in the AWS KMS console or by using the CreateKey operation.
There are two ways to create a KMS key in an external key store.
-
Method 1 (recommended): Choose an external key store, then create a KMS key in that external key store.
-
Method 2: Create a KMS key, then indicate that it's in an external key store.
If you use Method 1, where you choose your external key store before you create your key, AWS KMS chooses all required KMS key properties for you and fills in the ID of your external key store. This method avoids errors you might make when creating your KMS key.
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.
Method 1 (recommended): Start in your external key store
To use this method, choose your external key store, then create a KMS key. The AWS KMS console chooses all required properties for you and fills in the ID of your external key store. This method avoids many errors you might make when creating your KMS key.
-
Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms
. -
To change the AWS Region, use the Region selector in the upper-right corner of the page.
In the navigation pane, choose Custom key stores, External key stores.
-
Choose the name of your external key store.
-
In the top right corner, choose Create a KMS key in this key store.
If the external key store is not connected, you will be prompted to connect it. If the connection attempt fails, you need to resolve the problem and connect the external key store before you can create a new KMS key in it.
If the external key store is connected, you are redirected to the Customer managed keys page for creating a key. The required Key configuration values are already chosen for you. Also, the custom key store ID of your external key store is filled in, although you can change it.
-
Enter the key ID of an external key in your external key manager. This external key must fulfill the requirements for use with a KMS key. You cannot change this value after the key is created.
If the external key has multiple IDs, enter the key ID that the external key store proxy uses to identify the external key.
-
Confirm that you intend to create a KMS key in the specified external key store.
-
Choose Next.
The remainder of this procedure is the same as creating a standard KMS key.
-
Type an alias (required) and a description (optional) 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 AWS resources, AWS 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 AWS KMS and ABAC for AWS 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 Allow key administrators to delete this key check box.
Deleting a KMS key is a destructive and irreversible operation that can render ciphertext unrecoverable. You cannot recreate a symmetric KMS key in an external key store, even if you have the external key material. However, deleting a KMS key has no effect on its associated external key. For information about deleting a KMS key from an external key store, see Special considerations for deleting keys.
-
Choose Next.
-
In the This account section, select the IAM users and roles in this AWS 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 AWS accounts to use this KMS key for cryptographic operations. To do so, in the Other AWS accounts section at the bottom of the page, choose Add another AWS account and enter the AWS account ID of an external account. To add multiple external accounts, repeat this step.
Note
Administrators of the other AWS 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.
Method 2: Start in Customer managed keys
This procedure is the same as the procedure to create a symmetric encryption key with AWS KMS key material. But, in this procedure, you specify the custom key store ID of the external key store and the key ID of the external key. You must also specify the required property values for a KMS key in an external key store, such as the key spec and key usage.
-
Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms
. -
To change the AWS 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 External key store.
-
Confirm that you intend to create a KMS key in the specified external key store.
-
Choose Next.
-
Choose the row that represents the external key store for your new KMS key.
You cannot choose a disconnected external key store. To connect a key store that is disconnected, choose the key store name, and then, from Key store actions, choose, Connect. For details, see Using the AWS KMS console.
-
Enter the key ID of an external key in your external key manager. This external key must fulfill the requirements for use with a KMS key. You cannot change this value after the key is created.
If the external key has multiple IDs, enter the key ID that the external key store proxy uses to identify the external key.
-
Choose Next.
The remainder of this procedure is the same as creating a standard KMS key.
-
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 AWS resources, AWS 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 AWS KMS and ABAC for AWS 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.
-
(Optional) To prevent these key administrators from deleting this KMS key, clear Allow key administrators to delete this key check box.
Deleting a KMS key is a destructive and irreversible operation that can render ciphertext unrecoverable. You cannot recreate a symmetric KMS key in an external key store, even if you have the external key material. However, deleting a KMS key has no effect on its associated external key. For information about deleting a KMS key from an external key store, see Delete an AWS KMS keys.
-
Choose Next.
-
In the This account section, select the IAM users and roles in this AWS 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.
-
(Optional) You can allow other AWS accounts to use this KMS key for cryptographic operations. To do so, in the Other AWS accounts section at the bottom of the page, choose Add another AWS account and enter the AWS account ID of an external account. To add multiple external accounts, repeat this step.
Note
Administrators of the other AWS 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 external 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 (External key store), the name, ID, and type of the custom key store, and the ID, key usage, and status of the external key. If the procedure fails, an error message appears that describes the failure. For , see Troubleshooting external key stores.
Tip
To make it easier to identify KMS keys in a custom key store, on the Customer managed keys page, add the Origin and Custom key store ID column to the display. To change the table fields, choose the gear icon in the upper right corner of the page. For details, see Customize your console view.
To create a new KMS key in an external key store, use the CreateKey operation. The following parameters are required:
-
The
Origin
value must beEXTERNAL_KEY_STORE
. -
The
CustomKeyStoreId
parameter identifies your external key store. The ConnectionState of the specified external key store must beCONNECTED
. To find theCustomKeyStoreId
andConnectionState
, use theDescribeCustomKeyStores
operation. -
The
XksKeyId
parameter identifies the external key. This external key must fulfills the requirements for association with a KMS key.
You can also use any of the optional parameters of the CreateKey
operation, such as using the Policy
or Tags parameters.
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.
The examples in this section use the AWS Command Line Interface
(AWS CLI)
This example command uses the CreateKey operation to create a KMS key in an external key store. The response includes the properties of the KMS keys, the ID of the external key store, and the ID, usage, and status of the external key.
Before running this command, replace the example custom key store ID with a valid ID.
$
aws kms create-key --origin EXTERNAL_KEY_STORE --custom-key-store-id
cks-1234567890abcdef0
--xks-key-idbb8562717f809024
{ "KeyMetadata": { "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "AWSAccountId": "111122223333", "CreationDate": "2022-12-02T07:48:55-07:00", "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT", "CustomKeyStoreId": "cks-1234567890abcdef0", "Description": "", "Enabled": true, "EncryptionAlgorithms": [ "SYMMETRIC_DEFAULT" ], "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "KeyManager": "CUSTOMER", "KeySpec": "SYMMETRIC_DEFAULT", "KeyState": "Enabled", "KeyUsage": "ENCRYPT_DECRYPT", "MultiRegion": false, "Origin": "EXTERNAL_KEY_STORE", "XksKeyConfiguration": { "Id": "bb8562717f809024" } } }