# Create a KMS key
You can create AWS KMS keys in the AWS Management Console, or by using the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation or the [AWS::KMS::Key AWS CloudFormation resource](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kms-key.html). During this process, you set the key policy for the KMS key, which you can change at any time. You also select the following values that define the type of KMS key that you create. You cannot change these properties after the KMS key is created.
**KMS key type**
*Key type* is a property that determines what type of cryptographic key is created. AWS KMS offers three key types to protect data:
+ Advanced Encryption Standard (AES) symmetric keys
256-bit keys that are used under the Galois Counter Mode (GCM) mode of AES to provide authenticated encryption/decryption of data under 4KB in size. This is the most common type of key and is used to protect other data encryption keys used in your applications and by AWS services that encrypt your data on your behalf.
+ RSA, elliptic curve, or SM2 (China Regions only) asymmetric keys
These keys are available in various sizes and support many algorithms. They can be used for encryption and decryption, sign and verify, or derive shared secrets operations depending on the algorithm choice.
+ Symmetric keys for performing hash-based message authentication codes (HMAC) operations
These keys are 256-bit keys used for sign and verify operations.
KMS keys cannot be exported from the service in plaintext. They are generated by and can only be used within the hardware security modules (HSMs) used by the service. This is the foundational security property of AWS KMS to ensure that keys are not compromised.
**Key usage**
*Key usage* is a property that determines the cryptographic operations the key supports. KMS keys can have a key usage of `ENCRYPT_DECRYPT`, `SIGN_VERIFY`, `GENERATE_VERIFY_MAC`, or `KEY_AGREEMENT`. Each KMS key can have only one key usage. This follows key usage best practices according to [National Institute of Standards and Technology (NIST) Special Publication 800-57 Recommendations for Key Management](https://csrc.nist.gov/pubs/sp/800/57/pt1/r5/final), Section 5.2, Key usage. Using a KMS key for more than one type of operation makes the product of both operations more vulnerable to attack.
**Key spec**
*Key spec* is a property that represents the cryptographic configuration of a key. The meaning of the key spec differs with the key type.
For KMS keys, the *key spec* determines whether the KMS key is symmetric or asymmetric. It also determines the type of its key material, and the algorithms it supports.
The default key spec, [SYMMETRIC\$1DEFAULT](symm-asymm-choose-key-spec.md#symmetric-cmks), represents a 256-bit symmetric encryption key. For a detailed description of all supported key specs, see [Key spec reference](symm-asymm-choose-key-spec.md).
**Key material origin**
*Key material origin* is a KMS key property that identifies the source of the key material in the KMS key. You choose the key material origin when you create the KMS key, and you cannot change it. The source of the key material affects the security, durability, availability, latency, and throughput characteristics of the KMS key.
Each KMS key includes a reference to its key material in its metadata. The key material origin of symmetric encryption KMS keys can vary. You can use key material that AWS KMS generates, key material that is generated in a [custom key store](key-store-overview.md#custom-key-store-overview), or [import your own key material](importing-keys.md).
By default, each KMS key has unique key material. However, you can create a set of [multi-Region keys](multi-region-keys-overview.md) with the same key material.
KMS keys can have one of the following key material origin values: `AWS_KMS`, `EXTERNAL` ([imported key material](importing-keys.md)), `AWS_CLOUDHSM` ([KMS key in a AWS CloudHSM key store](keystore-cloudhsm.md)), or `EXTERNAL_KEY_STORE` ([KMS key in an external key store](keystore-external.md)).
**Topics**
+ [
## Permissions for creating KMS keys
](#create-key-permissions)
+ [
## Choosing what type of KMS key to create
](#symm-asymm-choose)
+ [
# Create a symmetric encryption KMS key
](create-symmetric-cmk.md)
+ [
# Create an asymmetric KMS key
](asymm-create-key.md)
+ [
# Create an HMAC KMS key
](hmac-create-key.md)
+ [
# Create multi-Region primary keys
](create-primary-keys.md)
+ [
# Create multi-Region replica keys
](multi-region-keys-replicate.md)
+ [
# Create a KMS key with imported key material
](importing-keys-conceptual.md)
+ [
# Create a KMS key in an AWS CloudHSM key store
](create-cmk-keystore.md)
+ [
# Create a KMS key in external key stores
](create-xks-keys.md)
## Permissions for creating KMS keys
To create a KMS key in the console or by using the APIs, you must have the following permission in an IAM policy. Whenever possible, use [condition keys](policy-conditions.md) to limit the permissions. For example, you can use the [kms:KeySpec](conditions-kms.md#conditions-kms-key-spec) condition key in an IAM policy to allow principals to create only symmetric encryption keys.
For an example of an IAM policy for principals who create keys, see [Allow a user to create KMS keys](customer-managed-policies.md#iam-policy-example-create-key).
**Note**
Be cautious when giving principals permission to manage tags and aliases. Changing a tag or alias can allow or deny permission to the customer managed key. For details, see [ABAC for AWS KMS](abac.md).
+ [kms:CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) is required.
+ [kms:CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) is required to create a KMS key in the console where an alias is required for every new KMS key.
+ [kms:TagResource](https://docs.aws.amazon.com/kms/latest/APIReference/API_TagResource.html) is required to add tags while creating the KMS key.
+ [iam:CreateServiceLinkedRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceLinkedRole.html) is required to create multi-Region primary keys. For details, see [Control access to multi-Region keys](multi-region-keys-auth.md).
The [kms:PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html) permission is not required to create the KMS key. The `kms:CreateKey` permission includes permission to set the initial key policy. But you must add this permission to the key policy while creating the KMS key to ensure that you can control access to the KMS key. The alternative is using the [BypassLockoutSafetyCheck](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html#KMS-CreateKey-request-BypassPolicyLockoutSafetyCheck) parameter, which is not recommended.
KMS keys belong to the AWS account in which they were created. The IAM user who creates a KMS key is not considered to be the key owner and they don't automatically have permission to use or manage the KMS key that they created. Like any other principal, the key creator needs to get permission through a key policy, IAM policy, or grant. However, principals who have the `kms:CreateKey` permission can set the initial key policy and give themselves permission to use or manage the key.
## Choosing what type of KMS key to create
The type of KMS key that you create depends largely on how you plan to *use* the KMS key, your security requirements, and your authorization requirements. The key type and key usage of a KMS key determine what cryptographic operations the key can perform. Each KMS key has only one key usage. Using a KMS key for more than one type of operation makes the product of all operations more vulnerable to attack.
To allow principals to create KMS keys only for a particular key usage, use the [kms:KeyUsage](conditions-kms.md#conditions-kms-key-usage) condition key. You can also use the `kms:KeyUsage` condition key to allow principals to call API operations for a KMS key based on its key usage. For example, you can allow permission to disable a KMS key only if its key usage is SIGN\$1VERIFY.
Use the following guidance to determine which type of KMS key you need based on your use case.
**Encrypt and decrypt data**
Use a [symmetric KMS key](symm-asymm-choose-key-spec.md#symmetric-cmks) for most use cases that require encrypting and decrypting data. The symmetric encryption algorithm that AWS KMS uses is fast, efficient, and assures the confidentiality and authenticity of data. It supports authenticated encryption with additional authenticated data (AAD), defined as an [encryption context](encrypt_context.md). This type of KMS key requires both the sender and recipient of encrypted data to have valid AWS credentials to call AWS KMS.
If your use case requires encryption outside of AWS by users who cannot call AWS KMS, [asymmetric KMS keys](symmetric-asymmetric.md) are a good choice. You can distribute the public key of the asymmetric KMS key to allow these users to encrypt data. And your applications that need to decrypt that data can use the private key of the asymmetric KMS key within AWS KMS.
**Sign messages and verify signatures**
To sign messages and verify signatures, you must use an [asymmetric KMS key](symmetric-asymmetric.md). You can use a KMS key with a [key spec](symm-asymm-choose-key-spec.md) that represents an RSA key pair, an elliptic curve (ECC) key pair, an ML-DSA key pair, or an SM2 key pair (China Regions only). The key spec you choose is determined by the signing algorithm that you want to use. The ECDSA signing algorithms that ECC key pairs support are recommended over the RSA signing algorithms. Use an ML-DSA key pair when migrating from RSA or ECC keys to post-quantum keys. However, you might need to use a particular key spec and signing algorithm to support users who verify signatures outside of AWS.
**Encrypt with asymmetric key pairs**
To encrypt data with an asymmetric key pair, you must use an [asymmetric KMS key](symmetric-asymmetric.md) with an [RSA key spec](symm-asymm-choose-key-spec.md#key-spec-rsa-encryption) or an [SM2 key spec](symm-asymm-choose-key-spec.md#key-spec-sm) (China Regions only). To encrypt data in AWS KMS with the public key of a KMS key pair, use the [Encrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) operation. You can also [download the public key](download-public-key.md) and share it with the parties that need to encrypt data outside of AWS KMS.
When you download the public key of an asymmetric KMS key, you can use it outside of AWS KMS. But it is no longer subject to the security controls that protect the KMS key in AWS KMS. For example, you cannot use AWS KMS key policies or grants to control use of the public key. Nor can you control whether the key is used only for encryption and decryption using the encryption algorithms that AWS KMS supports. For more details, see [Special Considerations for Downloading Public Keys](offline-public-key.md#download-public-key-considerations).
To decrypt data that was encrypted with the public key outside of AWS KMS, call the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation. The `Decrypt` operation fails if the data was encrypted under a public key from a KMS key with a key usage of `SIGN_VERIFY`. It will also fail if it was encrypted by using an algorithm that AWS KMS does not support for the key spec you selected. For more information on key specs and supported algorithms, see [Key spec reference](symm-asymm-choose-key-spec.md).
To avoid these errors, anyone using a public key outside of AWS KMS must store the key configuration. The AWS KMS console and the [GetPublicKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetPublicKey.html) response provide the information that you must include when you share the public key.
**Derive shared secrets**
To derive shared secrets, use a KMS key with [NIST-standard elliptic curve](symm-asymm-choose-key-spec.md#key-spec-ecc) or [SM2](symm-asymm-choose-key-spec.md#key-spec-sm) (China Regions only) key material. AWS KMS uses the [Elliptic Curve Cryptography Cofactor Diffie-Hellman Primitive](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf#page=60) (ECDH) to establish a key agreement between two peers by deriving a shared secret from their elliptic curve public-private key pairs. You can use the raw shared secret that the [ DeriveSharedSecret](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeriveSharedSecret.html) operation returns to derive a symmetric key that can encrypt and decrypt data that is sent between two parties, or generate and verify HMACs. AWS KMS recommends that you follow [NIST recommendations for key derivation](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Cr2.pdf) when using the raw shared secret to derive a symmetric key.
**Generate and verify HMAC codes**
To generate and verify hash-based message authentication codes, use an HMAC KMS key. When you create an HMAC key in AWS KMS, AWS KMS creates and protects your key material and ensures that you use the correct MAC algorithms for your key. HMAC codes can also be used as pseudo-random numbers, and in certain scenarios for symmetric signing and tokenizing.
HMAC KMS keys are symmetric keys. When creating an HMAC KMS key in the AWS KMS console, choose the `Symmetric` key type.
**Use with AWS services**
To create a KMS key for use with an [AWS service that is integrated with AWS KMS](service-integration.md), consult the documentation for the service. AWS services that encrypt your data require a [symmetric encryption KMS key](symm-asymm-choose-key-spec.md#symmetric-cmks).
In addition to these considerations, cryptographic operations on KMS keys with different key specs have different prices and different request quotas. For information about AWS KMS pricing, see [AWS Key Management Service Pricing](https://aws.amazon.com/kms/pricing/). For information about request quotas, see [Request quotas](requests-per-second.md).
# Create a symmetric encryption KMS key
This topic explains how to create the basic KMS key, a [symmetric encryption KMS key](symm-asymm-choose-key-spec.md#symmetric-cmks) for a single Region with key material from AWS KMS. You can use this KMS key to protect your resources in an AWS service.
You can create symmetric encryption KMS keys in the AWS KMS console, by using the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) API, or by using the [AWS::KMS::Key CloudFormation template](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kms-key.html).
The default key spec, [SYMMETRIC\$1DEFAULT](symm-asymm-choose-key-spec.md#symmetric-cmks), is the key spec for symmetric encryption KMS keys. When you select the **Symmetric** key type and the **Encrypt and decrypt** key usage in the AWS KMS console, it selects the `SYMMETRIC_DEFAULT` key spec. In the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation, if you don't specify a `KeySpec` value, SYMMETRIC\$1DEFAULT is selected. If you don't have a reason to use a different key spec, SYMMETRIC\$1DEFAULT is a good choice.
For information about quotas that apply to KMS keys, see [Quotas](limits.md).
## Using the AWS KMS console
You can use the AWS Management Console to create AWS KMS keys (KMS keys).
**Important**
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.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose **Create key**.
1. To create a symmetric encryption KMS key, for **Key type** choose **Symmetric**.
1. In **Key usage**, the **Encrypt and decrypt** option is selected for you.
1. Choose **Next**.
1. Type an alias for the KMS key. The alias name cannot begin with **aws/**. The **aws/** prefix is reserved by Amazon Web Services to represent AWS managed keys in your account.
**Note**
Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see [ABAC for AWS KMS](abac.md) and [Use aliases to control access to KMS keys](alias-authorization.md).
An alias is a display name that you can use to identify the KMS key. We recommend that you choose an alias that indicates the type of data you plan to protect or the application you plan to use with the KMS key.
Aliases are required when you create a KMS key in the AWS Management Console. They are optional when you use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation.
1. (Optional) Type a description for the KMS key.
You can add a description now or update it any time unless the [key state](key-state.md) is `Pending Deletion` or `Pending Replica Deletion`. To add, change, or delete the description of an existing customer managed key, edit the description on the details page for the KMS key in the AWS Management Console or use the [UpdateKeyDescription](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateKeyDescription.html) operation.
1. (Optional) Type a tag key and an optional tag value. To add more than one tag to the KMS key, choose **Add tag**.
**Note**
Tagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see [ABAC for AWS KMS](abac.md) and [Use tags to control access to KMS keys](tag-authorization.md).
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](tagging-keys.md) and [ABAC for AWS KMS](abac.md).
1. Choose **Next**.
1. Select the IAM users and roles that can administer the KMS key.
**Notes**
This key policy gives the AWS account full control of this KMS key. It allows account administrators to use IAM policies to give other principals permission to manage the KMS key. For details, see [Default key policy](key-policy-default.md).
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
The AWS KMS console adds key administrators to the key policy under the statement identifier `"Allow access for Key Administrators"`. Modifying this statement identifier might impact how the console displays updates that you make to the statement.
1. (Optional) To prevent the selected IAM users and roles from deleting this KMS key, in the **Key deletion** section at the bottom of the page, clear the **Allow key administrators to delete this key** check box.
1. Choose **Next**.
1. Select the IAM users and roles that can use the key in [cryptographic operations](kms-cryptography.md#cryptographic-operations)
**Notes**
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
The AWS KMS console adds key users to the key policy under the statement identifiers `"Allow use of the key"` and `"Allow attachment of persistent resources"`. Modifying these statement identifiers might impact how the console displays updates that you make to the statement.
1. (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 identification number of an external account. To add multiple external accounts, repeat this step.
**Note**
To allow principals in the external accounts to use the KMS key, Administrators of the external account must create IAM policies that provide these permissions. For more information, see [Allowing users in other accounts to use a KMS key](key-policy-modifying-external-accounts.md).
1. Choose **Next**.
1. Review the key policy statements for the key. To make changes to the key policy, select **Edit**.
1. Choose **Next**.
1. Review the key settings that you chose. You can still go back and change all settings.
1. Choose **Finish** to create the KMS key.
## Using the AWS KMS API
You can use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation to create AWS KMS keys of all types. These examples use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/). For examples in multiple programming languages, see [Use `CreateKey` with an AWS SDK or CLI](example_kms_CreateKey_section.md).
**Important**
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 following operation creates a symmetric encryption key in a single Region backed by key material generated by AWS KMS. This operation has no required parameters. However, you might also want to use the `Policy` parameter to specify a key policy. You can change the key policy ([PutKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html)) and add optional elements, such as a [description](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) and [tags](https://docs.aws.amazon.com/kms/latest/APIReference/API_TagResource.html) at any time. You can also create [asymmetric keys](asymm-create-key.md#create-asymmetric-keys-api), [multi-Region keys](create-primary-keys.md), keys with [imported key material](importing-keys-create-cmk.md#importing-keys-create-cmk-api), and keys in [custom key stores](create-cmk-keystore.md#create-cmk-keystore-api). To create data keys for client-side encryption, use the [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) operation.
The `CreateKey` operation doesn't let you specify an alias, but you can use the [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) operation to create an alias for your new KMS key.
The following is an example of a call to the `CreateKey` operation with no parameters. This command uses all of the default values. It creates a symmetric encryption KMS key with key material generated by AWS KMS.
```
$ aws kms create-key
{
"KeyMetadata": {
"Origin": "AWS_KMS",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Description": "",
"KeyManager": "CUSTOMER",
"Enabled": true,
"KeySpec": "SYMMETRIC_DEFAULT",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"KeyUsage": "ENCRYPT_DECRYPT",
"KeyState": "Enabled",
"CreationDate": 1502910355.475,
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"MultiRegion": false
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
}
}
```
If you do not specify a key policy for your new KMS key, the [default key policy](key-policy-default.md) that `CreateKey` applies differs from the default key policy that the console applies when you use it to create a new KMS key.
For example, this call to the [GetKeyPolicy](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyPolicy.html) operation returns the key policy that `CreateKey` applies. It gives the AWS account access to the KMS key and allows it to create AWS Identity and Access Management (IAM) policies for the KMS key. For detailed information about IAM policies and key policies for KMS keys, see [KMS key access and permissions](control-access.md)
```
$ aws kms get-key-policy --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --policy-name default --output text
```
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id" : "key-default-1",
"Statement" : [ {
"Sid" : "EnableIAMUserPermissions",
"Effect" : "Allow",
"Principal" : {
"AWS" : "arn:aws:iam::111122223333:root"
},
"Action" : "kms:*",
"Resource" : "*"
} ]
}
```
------
# Create an asymmetric KMS key
You can create [asymmetric KMS keys](symmetric-asymmetric.md) in the AWS KMS console, by using the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) API, or by using the [AWS::KMS::Key CloudFormation template](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kms-key.html). An asymmetric KMS key represents a public and private key pair that can be used for encryption, signing, or deriving shared secrets. The private key remains within AWS KMS. To download the public key for use outside of AWS KMS, see [Download public key](download-public-key.md).
When you create an asymmetric KMS key, you must select a key spec. Often the key spec that you select is determined by regulatory, security, or business requirements. It might also be influenced by the size of messages that you need to encrypt or sign. In general, longer encryption keys are more resistant to brute-force attacks. For a detailed description of all supported key specs, see [Key spec reference](symm-asymm-choose-key-spec.md).
AWS services that integrate with AWS KMS do not support asymmetric KMS keys. If you want to create a KMS key that encrypts data that you store or manage in an AWS service, [create a symmetric encryption KMS key](create-symmetric-cmk.md).
For information about the permissions required to create KMS keys, see [Permissions for creating KMS keys](create-keys.md#create-key-permissions).
## Using the AWS KMS console
You can use the AWS Management Console to create asymmetric AWS KMS keys (KMS keys). Each asymmetric KMS key represents a public and private key pair.
**Important**
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.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose **Create key**.
1. To create an asymmetric KMS key, in **Key type,** choose **Asymmetric**.
1. To create an asymmetric KMS key for public key encryption, in **Key usage**, choose **Encrypt and decrypt**.
To create an asymmetric KMS key for signing messages and verifying signatures, in **Key usage**, choose **Sign and verify**.
To create an asymmetric KMS key for deriving shared secrets, in **Key usage**, choose **Key agreement**.
For help choosing a key usage value, see [Choosing what type of KMS key to create](create-keys.md#symm-asymm-choose).
1. Select a specification (**Key spec**) for your asymmetric KMS key.
1. Choose **Next**.
1. Type an [alias](kms-alias.md) for the KMS key. The alias name cannot begin with **aws/**. The **aws/** prefix is reserved by Amazon Web Services to represent AWS managed keys in your account.
An *alias* is a friendly name that you can use to identify the KMS key in the console and in some AWS KMS APIs. We recommend that you choose an alias that indicates the type of data you plan to protect or the application you plan to use with the KMS key.
Aliases are required when you create a KMS key in the AWS Management Console. You cannot specify an alias when you use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation, but you can use the console or the [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) operation to create an alias for an existing KMS key. For details, see [Aliases in AWS KMS](kms-alias.md).
1. (Optional) Type a description for the KMS key.
Enter a description that explains the type of data you plan to protect or the application you plan to use with the KMS key.
You can add a description now or update it any time unless the [key state](key-state.md) is `Pending Deletion` or `Pending Replica Deletion`. To add, change, or delete the description of an existing customer managed key, edit the description on the details page for the KMS key in the AWS Management Console or use the [UpdateKeyDescription](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateKeyDescription.html) operation.
1. (Optional) Type a tag key and an optional tag value. To add more than one tag to the KMS key, choose **Add tag**.
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](tagging-keys.md) and [ABAC for AWS KMS](abac.md).
1. Choose **Next**.
1. Select the IAM users and roles that can administer the KMS key.
**Notes**
This key policy gives the AWS account full control of this KMS key. It allows account administrators to use IAM policies to give other principals permission to manage the KMS key. For details, see [Default key policy](key-policy-default.md).
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
The AWS KMS console adds key administrators to the key policy under the statement identifier `"Allow access for Key Administrators"`. Modifying this statement identifier might impact how the console displays updates that you make to the statement.
1. (Optional) To prevent the selected IAM users and roles from deleting this KMS key, in the **Key deletion** section at the bottom of the page, clear the **Allow key administrators to delete this key** check box.
1. Choose **Next**.
1. Select the IAM users and roles that can use the KMS key for [cryptographic operations](kms-cryptography.md#cryptographic-operations).
**Notes**
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
The AWS KMS console adds key users to the key policy under the statement identifiers `"Allow use of the key"` and `"Allow attachment of persistent resources"`. Modifying these statement identifiers might impact how the console displays updates that you make to the statement.
1. (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 identification number of an external account. To add multiple external accounts, repeat this step.
**Note**
To allow principals in the external accounts to use the KMS key, administrators of the external account must create IAM policies that provide these permissions. For more information, see [Allowing users in other accounts to use a KMS key](key-policy-modifying-external-accounts.md).
1. Choose **Next**.
1. Review the key policy statements for the key. To make changes to the key policy, select **Edit**.
1. Choose **Next**.
1. Review the key settings that you chose. You can still go back and change all settings.
1. Choose **Finish** to create the KMS key.
## Using the AWS KMS API
You can use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation to create an asymmetric AWS KMS key. These examples use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
When you create an asymmetric KMS key, you must specify the `KeySpec` parameter, which determines the type of keys you create. Also, you must specify a `KeyUsage` value of ENCRYPT\$1DECRYPT, SIGN\$1VERIFY, or KEY\$1AGREEMENT. You cannot change these properties after the KMS key is created.
The `CreateKey` operation doesn't let you specify an alias, but you can use the [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) operation to create an alias for your new KMS key.
**Important**
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.
**Create an asymmetric KMS key pair for public encryption**
The following example uses the `CreateKey` operation to create an asymmetric KMS key of 4096-bit RSA keys designed for public key encryption.
```
$ aws kms create-key --key-spec RSA_4096 --key-usage ENCRYPT_DECRYPT
{
"KeyMetadata": {
"KeyState": "Enabled",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"Description": "",
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": 1569973196.214,
"MultiRegion": false,
"KeySpec": "RSA_4096",
"CustomerMasterKeySpec": "RSA_4096",
"KeyUsage": "ENCRYPT_DECRYPT",
"EncryptionAlgorithms": [
"RSAES_OAEP_SHA_1",
"RSAES_OAEP_SHA_256"
],
"AWSAccountId": "111122223333",
"Origin": "AWS_KMS",
"Enabled": true
}
}
```
**Create an asymmetric KMS key pair for signing and verification**
The following example command creates an asymmetric KMS key that represents a pair of ECC keys used for signing and verification. You cannot create an elliptic curve key pair for encryption and decryption.
```
$ aws kms create-key --key-spec ECC_NIST_P521 --key-usage SIGN_VERIFY
{
"KeyMetadata": {
"KeyState": "Enabled",
"KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
"CreationDate": 1570824817.837,
"Origin": "AWS_KMS",
"SigningAlgorithms": [
"ECDSA_SHA_512"
],
"Arn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
"AWSAccountId": "111122223333",
"KeySpec": "ECC_NIST_P521",
"CustomerMasterKeySpec": "ECC_NIST_P521",
"KeyManager": "CUSTOMER",
"Description": "",
"Enabled": true,
"MultiRegion": false,
"KeyUsage": "SIGN_VERIFY"
}
}
```
**Create an asymmetric KMS key pair for deriving shared secrets**
The following example command creates an asymmetric KMS key that represents a pair of ECDH keys used for deriving shared secrets. You cannot create an elliptic curve key pair for encryption and decryption.
```
$ aws kms create-key --key-spec ECC_NIST_P256 --key-usage KEY_AGREEMENT
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
"Arn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
"CreationDate": "2023-12-27T19:10:15.063000+00:00",
"Enabled": true,
"Description": "",
"KeyUsage": "KEY_AGREEMENT",
"KeyState": "Enabled",
"Origin": "AWS_KMS",
"KeyManager": "CUSTOMER",
"CustomerMasterKeySpec": "ECC_NIST_P256",
"KeySpec": "ECC_NIST_P256",
"KeyAgreementAlgorithms": [
"ECDH"
],
"MultiRegion": false
}
}
```
# Create an HMAC KMS key
You can create HMAC KMS keys in the AWS KMS console, by using the [https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) API, or by using the [AWS::KMS::Key CloudFormation template](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kms-key.html).
When you create an HMAC KMS key, you must select a key spec. AWS KMS supports multiple [key specs for HMAC KMS keys](symm-asymm-choose-key-spec.md#hmac-key-specs). The key spec that you select might be determined by regulatory, security, or business requirements. In general, longer keys are more resistant to brute-force attacks.
For information about the permissions required to create KMS keys, see [Permissions for creating KMS keys](create-keys.md#create-key-permissions).
## Using the AWS KMS console
You can use the AWS Management Console to create HMAC KMS keys. HMAC KMS keys are symmetric keys with a key usage of **Generate and verify MAC**. You can also create multi-Region HMAC keys.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose **Create key**.
1. For **Key type**, choose **Symmetric**.
HMAC KMS keys are symmetric. You use the same key to generate and verify HMAC tags.
1. For **Key usage**, choose **Generate and verify MAC**.
Generate and verify MAC is the only valid key usage for HMAC KMS keys.
**Note**
**Key usage** is displayed for symmetric keys only when HMAC KMS keys are supported in your selected Region.
1. Select a specification (**Key spec**) for your HMAC KMS key.
The key spec that you select can be determined by regulatory, security, or business requirements. In general, longer keys are more secure.
1. To create a [multi-Region](multi-region-keys-overview.md) *primary* HMAC key, in **Advanced options**, choose **Multi-Region key**. The [shared properties](multi-region-keys-overview.md#mrk-sync-properties) that you define for this KMS key, such as its key type and key usage, will be shared with its replica keys.
You cannot use this procedure to create a replica key. To create a multi-Region *replica* HMAC key, follow the [instructions for creating a replica key](multi-region-keys-replicate.md).
1. Choose **Next**.
1. Enter an [alias](kms-alias.md) for the KMS key. The alias name cannot begin with **aws/**. The **aws/** prefix is reserved by Amazon Web Services to represent AWS managed keys in your account.
We recommend that you use an alias that identifies the KMS key as an HMAC key, such as `HMAC/test-key`. This will make it easier for you to identify your HMAC keys in the AWS KMS console where you can sort and filter keys by tags and aliases, but not by key spec or key usage.
Aliases are required when you create a KMS key in the AWS Management Console. You cannot specify an alias when you use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation, but you can use the console or the [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) operation to create an alias for an existing KMS key. For details, see [Aliases in AWS KMS](kms-alias.md).
1. (Optional) Enter a description for the KMS key.
Enter a description that explains the type of data you plan to protect or the application you plan to use with the KMS key.
You can add a description now or update it any time unless the [key state](key-state.md) is `Pending Deletion` or `Pending Replica Deletion`. To add, change, or delete the description of an existing customer managed key, edit the description on the details page for the KMS key in the AWS Management Console in the AWS Management Console or use the [UpdateKeyDescription](https://docs.aws.amazon.com/kms/latest/APIReference/API_UpdateKeyDescription.html) operation.
1. (Optional) Enter a tag key and an optional tag value. To add more than one tag to the KMS key, choose **Add tag**.
Consider adding a tag that identifies the key as an HMAC key, such as `Type=HMAC`. This will make it easier for you to identify your HMAC keys in the AWS KMS console where you can sort and filter keys by tags and aliases, but not by key spec or key usage.
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](tagging-keys.md) and [ABAC for AWS KMS](abac.md).
1. Choose **Next**.
1. Select the IAM users and roles that can administer the KMS key.
**Notes**
This key policy gives the AWS account full control of this KMS key. It allows account administrators to use IAM policies to give other principals permission to manage the KMS key. For details, see [Default key policy](key-policy-default.md).
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
The AWS KMS console adds key administrators to the key policy under the statement identifier `"Allow access for Key Administrators"`. Modifying this statement identifier might impact how the console displays updates that you make to the statement.
1. (Optional) To prevent the selected IAM users and roles from deleting this KMS key, in the **Key deletion** section at the bottom of the page, clear the **Allow key administrators to delete this key** check box.
1. Choose **Next**.
1. Select the IAM users and roles that can use the KMS key for [cryptographic operations](kms-cryptography.md#cryptographic-operations).
**Notes**
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
The AWS KMS console adds key users to the key policy under the statement identifiers `"Allow use of the key"` and `"Allow attachment of persistent resources"`. Modifying these statement identifiers might impact how the console displays updates that you make to the statement.
1. (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 identification number of an external account. To add multiple external accounts, repeat this step.
**Note**
To allow principals in the external accounts to use the KMS key, Administrators of the external account must create IAM policies that provide these permissions. For more information, see [Allowing users in other accounts to use a KMS key](key-policy-modifying-external-accounts.md).
1. Choose **Next**.
1. Review the key policy statements for the key. To make changes to the key policy, select **Edit**.
1. Choose **Next**.
1. Review the key settings that you chose. You can still go back and change all settings.
1. Choose **Finish** to create the HMAC KMS key.
## Using the AWS KMS API
You can use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation to create an HMAC KMS key. These examples use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
When you create an HMAC KMS key, you must specify the `KeySpec` parameter, which determines the type of the KMS key. Also, you must specify a `KeyUsage` value of GENERATE\$1VERIFY\$1MAC, even though it's the only valid key usage value for HMAC keys. To create a [multi-Region](multi-region-keys-overview.md) HMAC KMS key, add the `MultiRegion` parameter with a value of `true`. You cannot change these properties after the KMS key is created.
The `CreateKey` operation doesn't let you specify an alias, but you can use the [CreateAlias](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateAlias.html) operation to create an alias for your new KMS key. We recommend that you use an alias that identifies the KMS key as an HMAC key, such as `HMAC/test-key`. This will make it easier for you to identify your HMAC keys in the AWS KMS console where you can sort and filter keys by alias, but not by key spec or key usage.
If you try to create an HMAC KMS key in an AWS Region in which HMAC keys are not supported, the `CreateKey` operation returns an `UnsupportedOperationException`
The following example uses the `CreateKey` operation to create a 512-bit HMAC KMS key.
```
$ aws kms create-key --key-spec HMAC_512 --key-usage GENERATE_VERIFY_MAC
{
"KeyMetadata": {
"KeyState": "Enabled",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"Description": "",
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": 1669973196.214,
"MultiRegion": false,
"KeySpec": "HMAC_512",
"CustomerMasterKeySpec": "HMAC_512",
"KeyUsage": "GENERATE_VERIFY_MAC",
"MacAlgorithms": [
"HMAC_SHA_512"
],
"AWSAccountId": "111122223333",
"Origin": "AWS_KMS",
"Enabled": true
}
}
```
# Create multi-Region primary keys
You can create a [multi-Region primary key](multi-region-keys-overview.md#mrk-primary-key) in the AWS KMS console or by using the AWS KMS API. You can create the primary key in any AWS Region where AWS KMS supports multi-Region keys.
To create a multi-Region primary key, the principal needs the [same permissions](create-keys.md#create-key-permissions) that they need to create any KMS key, including the [kms:CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) permission in an IAM policy. The principal also needs the [iam:CreateServiceLinkedRole](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceLinkedRole.html) permission. You can use the [kms:MultiRegionKeyType](conditions-kms.md#conditions-kms-multiregion-key-type) condition key to allow or deny permission to create multi-Region primary keys.
**Note**
When creating your multi-Region primary key, carefully consider the IAM users and roles that you select to administer and use the key. IAM policies can give other IAM users and roles permission to manage 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
## Using the AWS KMS console
To create a multi-Region primary key in the AWS KMS console, use the same process that you would use to create any KMS key.. You select a multi-Region key in **Advanced options**. For complete instructions, see [Create a KMS key](create-keys.md).
**Important**
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.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose **Create key**.
1. Select a [symmetric or asymmetric](symmetric-asymmetric.md) key type. Symmetric keys are the default.
You can create multi-Region symmetric and asymmetric keys, including multi-Region HMAC KMS keys, which are symmetric.
1. Select your key usage. **Encrypt and decrypt** is the default.
For help, see [Create a KMS key](create-keys.md), [Create an asymmetric KMS key](asymm-create-key.md), or [Create an HMAC KMS key](hmac-create-key.md).
1. Expand **Advanced options**.
1. Under **Key material origin**, to have AWS KMS generate the key material that your primary and replica keys will share, choose **KMS**. If you are [importing key material](importing-keys-create-cmk.md) into the primary and replica keys, choose **External (Import key material)**.
1. Under **Regionality**, choose **Multi-Region key**.
You can't change this setting after you create the KMS key.
1. Type an [alias](kms-alias.md) for the primary key.
Aliases are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same alias or different aliases. AWS KMS does not synchronize the aliases of multi-Region keys.
**Note**
Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see [ABAC for AWS KMS](abac.md) and [Use aliases to control access to KMS keys](alias-authorization.md).
1. (Optional) Type a description of the primary key.
Descriptions are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same description or different descriptions. AWS KMS does not synchronize the key descriptions of multi-Region keys.
1. (Optional) Type a tag key and an optional tag value. To assign more than one tag to the primary key, choose **Add tag**.
Tags are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same tags or different tags. AWS KMS does not synchronize the tags of multi-Region keys. You can change the tags on KMS keys at any time.
**Note**
Tagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see [ABAC for AWS KMS](abac.md) and [Use tags to control access to KMS keys](tag-authorization.md).
1. Select the IAM users and roles that can administer the primary key.
**Notes**
This step starts the process of creating a [key policy](key-policies.md) for the primary key. Key policies are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same key policy or different key policies. AWS KMS does not synchronize the key policies of multi-Region keys. You can change the key policy of a KMS key at any time.
When creating a multi-Region primary key, consider using the [default key policy](key-policy-default.md) generated by the console. If you modify this policy, the console won't provide steps to select key administrators and users when creating replica keys, nor will it add the corresponding policy statements. As a result, you'll need to add these manually.
The AWS KMS console adds key administrators to the key policy under the statement identifier `"Allow access for Key Administrators"`. Modifying this statement identifier might impact how the console displays updates that you make to the statement.
1. (Optional) To prevent the selected IAM users and roles from deleting this KMS key, in the **Key deletion** section at the bottom of the page, clear the **Allow key administrators to delete this key** check box.
1. Choose **Next**.
1. Select the IAM users and roles that can use the KMS key for [cryptographic operations](kms-cryptography.md#cryptographic-operations).
**Notes**
The AWS KMS console adds key users to the key policy under the statement identifiers `"Allow use of the key"` and `"Allow attachment of persistent resources"`. Modifying these statement identifiers might impact how the console displays updates that you make to the statement.
1. (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 identification number of an external account. To add multiple external accounts, repeat this step.
**Note**
To allow principals in the external accounts to use the KMS key, Administrators of the external account must create IAM policies that provide these permissions. For more information, see [Allowing users in other accounts to use a KMS key](key-policy-modifying-external-accounts.md).
1. Choose **Next**.
1. Review the key policy statements for the key. To make changes to the key policy, select **Edit**.
1. Choose **Next**.
1. Review the key settings that you chose. You can still go back and change all settings.
1. Choose **Finish** to create the multi-Region primary key.
## Using the AWS KMS API
To create a multi-Region primary key, use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation. Use the `MultiRegion` parameter with a value of `True`.
For example, the following command creates a multi-Region primary key in the caller's AWS Region (us-east-1). It accepts default values for all other properties, including the key policy. The default values for multi-Region primary keys are the same as the default values for all other KMS keys, including the [default key policy](key-policy-default.md). This procedure creates a symmetric encryption key, the default KMS key.
The response includes the `MultiRegion` element and the `MultiRegionConfiguration` element with typical sub-elements and values for a multi-Region primary key with no replica keys. The [key ID](concepts.md#key-id-key-id) of a multi-Region key always begins with `mrk-`.
**Important**
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 create-key --multi-region
{
"KeyMetadata": {
"Origin": "AWS_KMS",
"KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab",
"Description": "",
"KeyManager": "CUSTOMER",
"Enabled": true,
"KeySpec": "SYMMETRIC_DEFAULT",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"KeyUsage": "ENCRYPT_DECRYPT",
"KeyState": "Enabled",
"CreationDate": 1606329032.475,
"Arn": "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"AWSAccountId": "111122223333",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"MultiRegion": true,
"MultiRegionConfiguration": {
"MultiRegionKeyType": "PRIMARY",
"PrimaryKey": {
"Arn": "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "us-east-1"
},
"ReplicaKeys": [ ]
}
}
}
```
# Create multi-Region replica keys
You can create a [multi-Region replica key](multi-region-keys-overview.md#mrk-primary-key) in the AWS KMS console, by using the [ReplicateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReplicateKey.html) operation, or by using a [AWS::KMS::ReplicaKey CloudFormation template](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kms-replicakey.html). You cannot use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation to create a replica key.
You can use these procedures to replicate any multi-Region primary key, including a [symmetric encryption KMS key](symm-asymm-choose-key-spec.md#symmetric-cmks), an [asymmetric KMS key](symmetric-asymmetric.md), or an [HMAC KMS key](hmac.md).
When this operation completes, the new replica key has a transient [key state](key-state.md) of `Creating`. This key state changes to `Enabled` (or `PendingImport` if you create a multi-Region key with [imported key material](importing-keys.md)) after a few seconds when the process of creating the new replica key is complete. While the key state is `Creating`, you can manage key, but you cannot yet use it in cryptographic operations. If you are creating and using the replica key programmatically, retry on `KMSInvalidStateException` or call [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) to check its `KeyState` value before using it.
If you mistakenly delete a replica key, you can use this procedure to recreate it. If you replicate the same primary key in the same Region, the new replica key you create will have the same [shared properties](multi-region-keys-overview.md#mrk-sync-properties) as the original replica key.
**Important**
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.
To use a AWS CloudFormation template to create a replica key, see [AWS::KMS::ReplicaKey](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-kms-replicakey.html) in the *AWS CloudFormation User Guide*.
## Step 1: Choose replica Regions
You typically choose to replicate a multi-Region key into an AWS Region based on your business model and regulatory requirements. For example, you might replicate a key into Regions where you keep your resources. Or, to comply with a disaster recovery requirement, you might replicate a key into geographically distant Regions.
The following are the AWS KMS requirements for replica Regions. If the Region that you choose doesn't comply with these requirements, attempts to replicate a key fail.
+ **One related multi-Region key per Region** — You can't create a replica key in the same Region as its primary key, or in the same Region as another replica of the primary key.
If you try to replicate a primary key in a Region that already has a replica of that primary key, the attempt fails. If the current replica key in the Region is in the [`PendingDeletion` key state](key-state.md), you can [cancel the replica key deletion](deleting-keys-scheduling-key-deletion.md) or wait until the replica key is deleted.
+ **Multiple unrelated multi-Region keys in the same Region** — You can have multiple unrelated multi-Region keys in the same Region. For example, you can have two multi-Region primary keys in the `us-east-1` Region. Each of the primary keys can have a replica key in `us-west-2` Region.
+ **Regions in the same partition** — The replica key Region must be in the same [AWS partition](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) as the primary key Region.
+ **Region must be enabled** — If a Region is [disabled by default](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html#rande-manage-enable), you cannot create any resources in that Region until it is enabled for your AWS account.
## Step 2: Create replica keys
**Note**
When creating replica keys, carefully consider the IAM users and roles that you select to administer and use the replica key. IAM policies can give other IAM users and roles permission to manage 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
### Using the AWS KMS console
In the AWS KMS console, you can create one or many replicas of a multi-Region primary key in the same operation.
This procedure is similar to creating a standard single-Region KMS key in the console. However, because a replica key is based on the primary key, you do not select values for [shared properties](multi-region-keys-overview.md#mrk-sync-properties), such as the key spec (symmetric or asymmetric), key usage, or key origin.
You do specify properties that are not shared, including an alias, tags, a description, and a key policy. As a convenience, the console displays the current property values of the primary key, but you can change them. Even if you keep the primary key values, AWS KMS does not keep these values synchronized.
**Important**
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.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Select the key ID or alias of a [multi-Region primary key](multi-region-keys-overview.md#mrk-primary-key). This opens the key details page for the KMS key.
To identify a multi-Region primary key, use the tool icon in the upper right corner to add the **Regionality** column to the table.
1. Choose the **Regionality** tab.
1. In the **Related multi-Region keys** section, choose **Create new replica keys**.
The **Related multi-Region keys** section displays the Region of the primary key and its replica keys. You can use this display to help you choose the Region for your new replica key.
1. Choose one or more AWS Regions. This procedure creates a replica key in each of the Regions you select.
The menu includes only Regions in the same AWS partition as the primary key. Regions that already have a related multi-Region key are displayed, but not selectable. You might not have permission to replicate a key into all of the Regions on the menu.
When you are finished choosing Regions, close the menu. The Regions you chose are displayed. To cancel replication into a Region, choose the **X** beside the Region name.
1. Type an [alias](kms-alias.md) for the replica key.
The console displays one of the current aliases of the primary key, but you can change it. You can give your multi-Region primary key and its replicas the same alias or different aliases. Aliases are not a [shared property](multi-region-keys-overview.md#mrk-sync-properties) of multi-Region keys. AWS KMS does not synchronize the aliases of multi-Region keys.
Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see [ABAC for AWS KMS](abac.md) and [Use aliases to control access to KMS keys](alias-authorization.md).
1. (Optional) Type a description of the replica key.
The console displays the current description of the primary key, but you can change it. Descriptions are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same description or different descriptions. AWS KMS does not synchronize the key descriptions of multi-Region keys.
1. (Optional) Type a tag key and an optional tag value. To assign more than one tag to the replica key, choose **Add tag**.
The console displays the tags currently attached to the primary key, but you can change them. Tags are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same tags or different tags. AWS KMS does not synchronize the tags of multi-Region keys.
Tagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see [ABAC for AWS KMS](abac.md) and [Use tags to control access to KMS keys](tag-authorization.md).
1. Select the IAM users and roles that can administer the replica key.
**Notes**
If you modified the default key policy when creating your multi-Region primary key, the console won't prompt you to select key administrators or key users (steps 11-15) during replica key creation. In this case, you'll need to manually add the necessary permissions for key administrators and users to the key policy by selecting **Edit** in the **Edit key policy** step (Step 17).
This step begins the process of creating a [key policy](key-policies.md) for the replica key. The console displays the current key policy of the primary key, but you can change it. Key policies are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same key policy or different key policies. AWS KMS does not synchronize key policies. You can change the key policy of any KMS key at any time.
The AWS KMS console adds key administrators to the key policy under the statement identifier `"Allow access for Key Administrators"`. Modifying this statement identifier might impact how the console displays updates that you make to the statement.
1. (Optional) To prevent the selected IAM users and roles from deleting this KMS key, in the **Key deletion** section at the bottom of the page, clear the **Allow key administrators to delete this key** check box.
1. Choose **Next**.
1. Select the IAM users and roles that can use the KMS key for [cryptographic operations](kms-cryptography.md#cryptographic-operations).
**Note**
The AWS KMS console adds key users to the key policy under the statement identifiers `"Allow use of the key"` and `"Allow attachment of persistent resources"`. Modifying these statement identifiers might impact how the console displays updates that you make to the statement.
1. (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 identification number of an external account. To add multiple external accounts, repeat this step.
**Note**
To allow principals in the external accounts to use the KMS key, Administrators of the external account must create IAM policies that provide these permissions. For more information, see [Allowing users in other accounts to use a KMS key](key-policy-modifying-external-accounts.md).
1. Choose **Next**.
1. Review the key policy statements for the key. To make changes to the key policy, select **Edit**.
1. Choose **Next**.
1. Review the key settings that you chose. You can still go back and change all settings.
1. Choose **Finish** to create the multi-Region replica key.
### Using the AWS KMS API
To create a multi-Region replica key, use the [ReplicateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReplicateKey.html) operation. You cannot use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation to create a replica key. This operation creates one replica key at a time. The Region that you specify must comply with the [Region requirements](#replica-region) for replica keys.
When you use the `ReplicateKey` operation, you don't specify values for any [shared properties](multi-region-keys-overview.md#mrk-sync-properties) of multi-Region keys. Shared property values are copied from the primary key and kept synchronized. However, you can specify values for properties that are not shared. Otherwise, AWS KMS applies the standard default values for KMS keys, not the values of the primary key.
**Note**
If you don't specify values for the `Description`, `KeyPolicy`, or `Tags` parameters, AWS KMS creates the replica key with an empty string description, the [default key policy](key-policy-default.md), and no tags.
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.
For example, the following command creates a multi-Region replica key in the Asia Pacific (Sydney) Region (ap-southeast-2). This replica key is modeled on the primary key in the US East (N. Virginia) Region (us-east-1), which is identified by the value of the `KeyId` parameter. This example accepts default values for all other properties, including the key policy.
The response describes the new replica key. It includes fields for shared properties, such as the `KeyId`, `KeySpec`, `KeyUsage`, and key material origin (`Origin`). It also includes properties that are independent of the primary key, such as the `Description`, key policy (`ReplicaKeyPolicy`), and tags (`ReplicaTags`).
The response also includes the key ARN and region of the primary key and all of its replica keys, including the one that was just created in the ap-southeast-2 Region. In this example, the `ReplicaKey` element shows that this primary key was already replicated in the Europe (Ireland) Region (eu-west-1).
```
$ aws kms replicate-key \
--key-id arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab \
--replica-region ap-southeast-2
{
"ReplicaKeyMetadata": {
"MultiRegion": true,
"MultiRegionConfiguration": {
"MultiRegionKeyType": "REPLICA",
"PrimaryKey": {
"Arn": "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "us-east-1"
},
"ReplicaKeys": [
{
"Arn": "arn:aws:kms:ap-southeast-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "ap-southeast-2"
},
{
"Arn": "arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"Region": "eu-west-1"
}
]
},
"AWSAccountId": "111122223333",
"Arn": "arn:aws:kms:ap-southeast-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
"CreationDate": 1607472987.918,
"Description": "",
"Enabled": true,
"KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"Origin": "AWS_KMS",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
]
},
"ReplicaKeyPolicy": "{\n \"Version\" : \"2012-10-17\",\n \"Id\" : \"key-default-1\",...,
"ReplicaTags": []
}
```
# Create a KMS key with imported key material
Imported key material lets you protect your AWS resources under cryptographic keys that you generate. The following overview explains how to import your key material into AWS KMS. For more details about each step in the process, see the corresponding topics.
1. [Create a KMS key with no key material](importing-keys-create-cmk.md) – The origin must be `EXTERNAL`. A key origin of `EXTERNAL` indicates that the key is designed for imported key material and prevents AWS KMS from generating key material for the KMS key. In a later step you will import your own key material into this KMS key.
The key material that you import must be compatible with the key spec of the associated AWS KMS key. For more information about compatibility, see [Requirements for imported key material](#importing-keys-material-requirements).
1. [Download the wrapping public key and import token](importing-keys-get-public-key-and-token.md) – After completing step 1, download a wrapping public key and an import token. These items protect your key material while it's imported to AWS KMS.
In this step, you choose the type ("key spec") of the RSA wrapping key and the wrapping algorithm that you'll use to encrypt your data in transit to AWS KMS. You can choose a different wrapping key spec and wrapping key algorithm each time you import or reimport the same key material.
1. [Encrypt the key material](importing-keys-encrypt-key-material.md) – Use the wrapping public key that you downloaded in step 2 to encrypt the key material that you created on your own system.
1. [Import the key material](importing-keys-import-key-material.md) – Upload the encrypted key material that you created in step 3 and the import token that you downloaded in step 2.
At this stage, you can [set an optional expiration time](importing-keys-import-key-material.md#importing-keys-expiration). When imported key material expires, AWS KMS deletes it, and the KMS key becomes unusable. To continue to use the KMS key, you must reimport the **same** key material.
When the import operation completes successfully, the key state of the KMS key changes from `PendingImport` to `Enabled`. You can now use the KMS key in cryptographic operations.
AWS KMS records an entry in your AWS CloudTrail log when you [create the KMS key](ct-createkey.md), [download the wrapping public key and import token](ct-getparametersforimport.md), and [import the key material](ct-importkeymaterial.md). AWS KMS also records an entry when you delete imported key material or when AWS KMS [deletes expired key material](ct-deleteexpiredkeymaterial.md).
## Permissions for importing key material
To create and manage KMS keys with imported key material, the user needs permission for the operations in this process. You can provide the `kms:GetParametersForImport`, `kms:ImportKeyMaterial`, and `kms:DeleteImportedKeyMaterial` permissions in the key policy when you create the KMS key. In the AWS KMS console, these permissions are added automatically for key administrators when you create a key with an **External** key material origin.
To create KMS keys with imported key material, the principal needs the following permissions.
+ [kms:CreateKey](customer-managed-policies.md#iam-policy-example-create-key) (IAM policy)
+ To limit this permission to KMS keys with imported key material, use the [kms:KeyOrigin](conditions-kms.md#conditions-kms-key-origin) policy condition with a value of `EXTERNAL`.
```
{
"Sid": "CreateKMSKeysWithoutKeyMaterial",
"Effect": "Allow",
"Resource": "*",
"Action": "kms:CreateKey",
"Condition": {
"StringEquals": {
"kms:KeyOrigin": "EXTERNAL"
}
}
}
```
+ [kms:GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) (Key policy or IAM policy)
+ To limit this permission to requests that use a particular wrapping algorithm and wrapping key spec, use the [kms:WrappingAlgorithm](conditions-kms.md#conditions-kms-wrapping-algorithm) and [kms:WrappingKeySpec](conditions-kms.md#conditions-kms-wrapping-key-spec) policy conditions.
+ [kms:ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) (Key policy or IAM policy)
+ To allow or prohibit key material that expires and control the expiration date, use the [kms:ExpirationModel](conditions-kms.md#conditions-kms-expiration-model) and [kms:ValidTo](conditions-kms.md#conditions-kms-valid-to) policy conditions.
To reimport imported key material, the principal needs the [kms:GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) and [kms:ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) permissions.
To delete imported key material, the principal needs [kms:DeleteImportedKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_DeleteImportedKeyMaterial.html) permission.
For example, to give the example `KMSAdminRole` permission to manage all aspects of a KMS key with imported key material, include a key policy statement like the following one in the key policy of the KMS key.
```
{
"Sid": "Manage KMS keys with imported key material",
"Effect": "Allow",
"Resource": "*",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/KMSAdminRole"
},
"Action": [
"kms:GetParametersForImport",
"kms:ImportKeyMaterial",
"kms:DeleteImportedKeyMaterial"
]
}
```
## Requirements for imported key material
The key material that you import must be compatible with the [key spec](create-keys.md#key-spec) of the associated KMS key. For asymmetric key pairs, import only the private key of the pair. AWS KMS derives the public key from the private key.
AWS KMS supports the following key specs for KMS keys with imported key material.
+ **Symmetric encryption keys**
+ **Key spec:**
+ SYMMETRIC\$1DEFAULT.
+ **Requirements:**
+ 256-bits (32 bytes) of binary data.
+ In China Regions, it must be a 128-bits (16 bytes) of binary data.
+ **HMAC keys**
+ **Key specs:**
+ HMAC\$1224
+ HMAC\$1256
+ HMAC\$1384
+ HMAC\$1512
+ **Requirements:**
+ HMAC key material must conform to [RFC 2104](https://datatracker.ietf.org/doc/html/rfc2104).
+ The key length must be at least the same length specified by the key spec. The maximum key length is 1024-bits.
+ If your key material exceeds 1024 bits, you can hash the key material and import the hash output. The hashing algorithm must match the key spec of the HMAC KMS key you're creating.
+ **Example:**
+ To import 2048 bits of key material into an HMAC\$1256 key, first compute the SHA-256 hash of the 2048-bit key material, then import the resulting 256-bit hash output into the KMS key.
+ **Valid key lengths:**
+ HMAC\$1224: 224–1024 bits
+ HMAC\$1256: 256–1024 bits
+ HMAC\$1384: 384–1024 bits
+ HMAC\$1512: 512–1024 bits
+ **RSA asymmetric private key**
+ **Key specs:**
+ RSA\$12048
+ RSA\$13072
+ RSA\$14096
+ **Requirements:**
+ The RSA asymmetric private key that you import must be part of a key pair that conforms to [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447/).
+ **Modulus:** 2048 bits, 3072 bits or 4096 bits
+ **Number of primes:** 2 (multi-prime RSA keys are not supported)
+ Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) \$18 format that complies with [RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208).
+ **Elliptic curve asymmetric private key**
+ **Key specs:**
+ ECC\$1NIST\$1P256 (secp256r1)
+ ECC\$1NIST\$1P384 (secp384r1)
+ ECC\$1NIST\$1P521 (secp521r1)
+ ECC\$1SECG\$1P256K1 (secp256k1)
+ ECC\$1NIST\$1EDWARDS25519 (ed25519)
+ **Requirements:**
+ The ECC asymmetric private key that you import must be part of a key pair that conforms to [RFC 5915](https://datatracker.ietf.org/doc/html/rfc5915/).
+ **Curve:** NIST P-256, NIST P-384, NIST P-521, Secp256k1, NIST Ed25519.
+ **Parameters:** Named curves only (ECC keys with explicit parameters are rejected).
+ **Public point coordinates:** May be compressed, uncompressed, or projective.
+ Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) \$18 format that complies with [RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208).
+ **ML-DSA key**
+ **Key specs:**
+ ML\$1DSA\$144
+ ML\$1DSA\$165
+ ML\$1DSA\$187
**Important**
Importing ML-DSA keys is not supported.
+ **SM2 asymmetric private key** (China Regions only)
+ **Requirements:**
+ The SM2 asymmetric private key that you import must be part of a key pair that conforms to GM/T 0003.
+ **Curve:** SM2.
+ **Parameters:** Named curve only (SM2 keys with explicit parameters are rejected).
+ **Public point coordinates:** May be compressed, uncompressed, or projective.
+ Asymmetric key material must be BER-encoded or DER-encoded in Public-Key Cryptography Standards (PKCS) \$18 format that complies with [RFC 5208](https://datatracker.ietf.org/doc/html/rfc5208).
# Step 1: Create an AWS KMS key without key material
By default, AWS KMS creates key material for you when you create a KMS key. To import your own key material instead, start by creating a KMS key with no key material. Then import the key material. To create a KMS key with no key material, use AWS KMS console or the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation.
To create a key with no key material, specify an [origin](create-keys.md#key-origin) of `EXTERNAL`. The origin property of a KMS key is immutable. Once you create it, you cannot convert a KMS key designed for imported key material into a KMS key with key material from AWS KMS or any other source.
The [key state](key-state.md) of a KMS key with an `EXTERNAL` origin and no key material is `PendingImport`. A KMS key can remain in `PendingImport` state indefinitely. However, you cannot use a KMS key in `PendingImport` state in cryptographic operations. When you import key material, the key state of the KMS key changes to `Enabled`, and you can use it in cryptographic operations.
AWS KMS records an event in your AWS CloudTrail log when you [create the KMS key](ct-createkey.md), [download the public key and import token](ct-getparametersforimport.md), and [import the key material](ct-importkeymaterial.md). AWS KMS also records a CloudTrail event when you [delete imported key material](ct-deleteimportedkeymaterial.md) or when AWS KMS [deletes expired key material](ct-deleteexpiredkeymaterial.md).
**Topics**
+ [
## Creating a KMS key with no key material (console)
](#importing-keys-create-cmk-console)
+ [
## Creating a KMS key with no key material (AWS KMS API)
](#importing-keys-create-cmk-api)
## Creating a KMS key with no key material (console)
You only need to create a KMS key for the imported key material once. You can import and reimport the same key material into the existing KMS key as often as you need to, but you cannot import different key material into a KMS key. For details, see [Step 2: Download the wrapping public key and import token](importing-keys-get-public-key-and-token.md).
To find existing KMS keys with imported key material in your **Customer managed keys** table, use the gear icon in the upper right corner to show the **Origin** column in the list of KMS keys. Imported keys have an **Origin** value of **External (Import Key material)**.
To create a KMS key with imported key material, begin by following the [instructions for creating a KMS key of your preferred key type](create-keys.md), with the following exception.
After choosing the key usage, do the following:
1. Expand **Advanced options**.
1. For **Key material origin**, choose **External (Import key material)**.
1. Choose the check box next to **I understand the security and durability implications of using an imported key** to indicate that you understand the implications of using imported key material. To read about these implications, see [Protecting imported key material](import-keys-protect.md).
1. Optional: To create a [multi-Region KMS key](multi-region-keys-overview.md) with imported key material, under **Regionality** select **Multi-Region key**.
1. Return to the basic instructions. The remaining steps of the basic procedure are the same for all KMS keys of that type.
When you choose **Finish**, you have created a KMS key with no key material and a status ([key state](key-state.md)) of **Pending import**.
However. instead of returning to the **Customer managed keys** table, the console displays a page where you can download the public key and import token that you need to import your key material. You can continue with the download step now, or choose **Cancel** to stop at this point. You can return to this download step at any time.
Next: [Step 2: Download the wrapping public key and import token](importing-keys-get-public-key-and-token.md).
## Creating a KMS key with no key material (AWS KMS API)
To use the [AWS KMS API](https://docs.aws.amazon.com/kms/latest/APIReference/) to create a symmetric encryption KMS key with no key material, send a [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) request with the `Origin` parameter set to `EXTERNAL`. The following example shows how to do this with the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/).
```
$ aws kms create-key --origin EXTERNAL
```
When the command is successful, you see output similar to the following. The AWS KMS key's `Origin` is `EXTERNAL` and its `KeyState` is `PendingImport`.
**Tip**
If the command does not succeed, you might see a `KMSInvalidStateException` or a `NotFoundException`. You can retry the request.
```
{
"KeyMetadata": {
"Origin": "EXTERNAL",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Description": "",
"Enabled": false,
"MultiRegion": false,
"KeyUsage": "ENCRYPT_DECRYPT",
"KeyState": "PendingImport",
"CreationDate": 1568289600.0,
"Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"AWSAccountId": "111122223333",
"KeyManager": "CUSTOMER",
"KeySpec": "SYMMETRIC_DEFAULT",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
]
}
}
```
Copy the `KeyId` value from your command output to use in later steps, and then proceed to [Step 2: Download the wrapping public key and import token](importing-keys-get-public-key-and-token.md).
**Note**
This command creates a symmetric encryption KMS key with a `KeySpec` of `SYMMETRIC_DEFAULT` and `KeyUsage` of `ENCRYPT_DECRYPT`. You can use the optional parameters `--key-spec` and `--key-usage` to create an asymmetric or HMAC KMS key. For more information, see the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation.
# Step 2: Download the wrapping public key and import token
After you [create a AWS KMS key with no key material](importing-keys-create-cmk.md), download a wrapping public key and an import token for that KMS key by using the AWS KMS console or the [GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) API. The wrapping public key and import token are an indivisible set that must be used together.
You will use the wrapping public key to [encrypt your key material](importing-keys-encrypt-key-material.md) for transport. Before downloading an RSA wrapping key pair, you select the length (key spec) of the RSA wrapping key pair and the wrapping algorithm that you will use to encrypt your imported key material for transport in [step 3](importing-keys-encrypt-key-material.md). AWS KMS also supports the SM2 wrapping key spec (China Regions only).
Each wrapping public key and import token set is valid for 24 hours. If you don't use them to import key material within 24 hours of downloading them, you must download a new set. You can download new wrapping public key and import token sets at any time. This lets you change your RSA wrapping key length ("key spec") or replace a lost set.
You can also download a wrapping public key and import token set to [reimport the same key material](importing-keys-import-key-material.md#reimport-key-material) into a KMS key. You might do this to set or change the expiration time for the key material, or to restore expired or deleted key material. You must download and re-encrypt your key material every time you import it to AWS KMS.
**Use of the wrapping public key**
The download includes a public key that is unique to your AWS account, also called a *wrapping public key*.
Before you import key material, you encrypt the key material with the public wrapping key, and then upload the encrypted key material to AWS KMS. When AWS KMS receives your encrypted key material, it decrypts the key material with the corresponding private key, then reencrypts the key material under an AES symmetric key, all within an AWS KMS hardware security module (HSM).
**Use of the import token**
The download includes an import token with metadata that ensures that your key material is imported correctly. When you upload your encrypted key material to AWS KMS, you must upload the same import token that you downloaded in this step.
## Select a wrapping public key spec
To protect your key material during import, you encrypt it using wrapping public key that you download from AWS KMS, and a supported [wrapping algorithm](#select-wrapping-algorithm). You select a key spec before you download your wrapping public key and import token. All wrapping key pairs are generated in AWS KMS hardware security modules (HSMs). The private key never leaves the HSM in plain text.
**RSA wrapping key specs**
The *key spec* of the wrapping public key determines the length of the keys in the RSA key pair that protects your key material during its transport to AWS KMS. In general, we recommend using the longest wrapping public key that is practical. We offer several wrapping public key specs to support a variety of HSMs and key managers.
AWS KMS supports the following key specs for the RSA wrapping keys used to import key material of all types, except as noted.
+ RSA\$14096 (recommended)
+ RSA\$13072
+ RSA\$12048
**Note**
The following combination is NOT supported: ECC\$1NIST\$1P521 key material, the RSA\$12048 public wrapping key spec, and an RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithm.
You cannot directly wrap ECC\$1NIST\$1P521 key material with a RSA\$12048 public wrapping key. Use a larger wrapping key or an RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1\$1 wrapping algorithm.
**SM2 wrapping key spec (China Regions only)**
AWS KMS supports the following key spec for the SM2 wrapping keys used to import asymmetric key material.
+ SM2
## Select a wrapping algorithm
To protect your key material during import, you encrypt it using the downloaded wrapping public key and a supported wrapping algorithm.
AWS KMS supports several standard RSA wrapping algorithms and a two-step hybrid wrapping algorithm. In general, we recommend using the most secure wrapping algorithm that is compatible with your imported key material and [wrapping key spec](#select-wrapping-key-spec). Typically, you choose an algorithm that is supported by the hardware security module (HSM) or key management system that protects your key material.
The following table shows the wrapping algorithms that are supported for each type of key material and KMS key. The algorithms are listed in preference order.
| Key material | Supported wrapping algorithm and spec |
| --- | --- |
| Symmetric encryption key 256-bit AES key 128-bit SM4 key (China Regions only) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) |
| Asymmetric RSA private key | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) |
| Asymmetric elliptic curve (ECC) private key You cannot use the RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithms with the RSA\$12048 wrapping key spec to wrap ECC\$1NIST\$1P521 key material. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) |
| Asymmetric SM2 private key (China Regions only) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) |
| HMAC key | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kms/latest/developerguide/importing-keys-get-public-key-and-token.html) |
**Note**
The `RSA_AES_KEY_WRAP_SHA_256` and `RSA_AES_KEY_WRAP_SHA_1` wrapping algorithms are not supported in China Regions.
+ `RSA_AES_KEY_WRAP_SHA_256` – A two-step hybrid wrapping algorithm that combines encrypting your key material with an AES symmetric key that you generate, and then encrypting the AES symmetric key with the downloaded RSA public wrapping key and the RSAES\$1OAEP\$1SHA\$1256 wrapping algorithm.
An `RSA_AES_KEY_WRAP_SHA_*` wrapping algorithm is required for wrapping RSA private key material, except in China Regions, where you must use the `SM2PKE` wrapping algorithm.
+ `RSA_AES_KEY_WRAP_SHA_1` – A two-step hybrid wrapping algorithm that combines encrypting your key material with an AES symmetric key that you generate, and then encrypting the AES symmetric key with the downloaded RSA wrapping public key and the RSAES\$1OAEP\$1SHA\$11 wrapping algorithm.
An `RSA_AES_KEY_WRAP_SHA_*` wrapping algorithm is required for wrapping RSA private key material, except in China Regions, where you must use the `SM2PKE` wrapping algorithm.
+ `RSAES_OAEP_SHA_256` – The RSA encryption algorithm with Optimal Asymmetric Encryption Padding (OAEP) with the SHA-256 hash function.
+ `RSAES_OAEP_SHA_1` – The RSA encryption algorithm with Optimal Asymmetric Encryption Padding (OAEP) with the SHA-1 hash function.
+ `RSAES_PKCS1_V1_5` (Deprecated; as of October 10, 2023, AWS KMS does not support the RSAES\$1PKCS1\$1V1\$15 wrapping algorithm) – The RSA encryption algorithm with the padding format defined in PKCS \$11 Version 1.5.
+ `SM2PKE` (China Regions only) – An elliptic curve based encryption algorithm defined by OSCCA in GM/T 0003.4-2012.
**Topics**
+ [
## Select a wrapping public key spec
](#select-wrapping-key-spec)
+ [
## Select a wrapping algorithm
](#select-wrapping-algorithm)
+ [
## Downloading the wrapping public key and import token (console)
](#importing-keys-get-public-key-and-token-console)
+ [
## Downloading the wrapping public key and import token (AWS KMS API)
](#importing-keys-get-public-key-and-token-api)
## Downloading the wrapping public key and import token (console)
You can use the AWS KMS console to download the wrapping public key and import token.
1. If you just completed the steps to [create a KMS key with no key material](importing-keys-create-cmk.md#importing-keys-create-cmk-console) and you are on the **Download wrapping key and import token** page, skip to [Step 10](#id-wrap-step).
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
**Tip**
You can import key material only into an KMS key with an **Origin** of **External (Import key material)**. This indicates that the KMS key was created with no key material. To add the **Origin** column to your table, in the upper-right corner of the page, choose the settings icon (![\[Gear or cog icon representing settings or configuration options.\]](http://docs.aws.amazon.com/kms/latest/developerguide/images/console-icon-settings-new.png)). Turn on **Origin**, and then choose **Confirm**.
1. Choose the alias or key ID of the KMS key that is pending import.
1. Choose the **Cryptographic configuration** tab and view its values. The tabs are below the **General configuration** section.
You can only import key material into KMS keys an **Origin** of **External (Import Key material)**. For information about creating KMS keys with imported key material, see, [Importing key material for AWS KMS keys](importing-keys.md).
1. Choose the appropriate tab based on your key type.
+ For asymmetric and HMAC keys, choose the **Key material** tab.
+ For symmetric encryption keys, choose the **Key material and rotations** tab.
1. Choose the import action.
+ For asymmetric and HMAC keys, choose **Import key material**.
+ For symmetric encryption keys, choose one of the following:
+ **Import initial key material** (if no key material has been imported yet)
+ **Import new key material** (to add new material for rotation)
+ **Reimport key material** (available from the **Actions** menu in the key materials table)
**Note**
For multi-Region keys, you must first import the new key material into the primary Region key. Then, import the same key material into each replica Region key.
For primary multi-Region keys, the **Key materials** table includes a **Replica import state** column that displays the import status across all replica regions (for example, "0 of 3 imported"). Choose the replica import state value to open a modal that shows the import status for each replica region. The modal provides **Import key material** links for replica regions where the new key material has not been imported.
1. For **Select wrapping key spec**, choose the configuration for your KMS key. After you create this key, you can't change the key spec.
1. For **Select wrapping algorithm**, choose the option that you will use to encrypt your key material. For more information about the options, see [Select a Wrapping Algorithm](#select-wrapping-algorithm).
1. Choose **Download wrapping public key and import token**, and then save the file.
If you have a **Next** option, to continue the process now, choose **Next**. To continue later, choose **Cancel**.
1. Decompress the `.zip` file that you saved in the previous step (`Import_Parameters__`).
The folder contains the following files:
+ A wrapping public key in a file named `WrappingPublicKey.bin`.
+ An import token in a file named `ImportToken.bin`.
+ A text file named README.txt. This file contains information about the wrapping public key, the wrapping algorithm to use to encrypt your key material, and the date and time when the wrapping public key and import token expire.
1. To continue the process, see [encrypt your key material](importing-keys-encrypt-key-material.md).
## Downloading the wrapping public key and import token (AWS KMS API)
To download the public key and import token, use the [GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) API. Specify the KMS key that will be associated with the imported key material. This KMS key must have an [Origin](create-keys.md#key-origin) value of `EXTERNAL`.
**Note**
You can't import key material for ML-DSA KMS keys.
This example specifies the `RSA_AES_KEY_WRAP_SHA_256` wrapping algorithm, the RSA\$13072 wrapping public key spec, and an example key ID. Replace these example values with valid values for your download. For the key ID, you can use a [key ID](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN), but you cannot use an [alias name](concepts.md#key-id-alias-name) or [alias ARN](concepts.md#key-id-alias-ARN) in this operation.
```
$ aws kms get-parameters-for-import \
--key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--wrapping-algorithm RSA_AES_KEY_WRAP_SHA_256 \
--wrapping-key-spec RSA_3072
```
When the command is successful, you see output similar to the following:
```
{
"ParametersValidTo": 1568290320.0,
"PublicKey": "public key (base64 encoded)",
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"ImportToken": "import token (base64 encoded)"
}
```
To prepare the data for the next step, base64 decode the public key and import token and save the decoded values in files.
To base64 decode the public key and import token:
1. Copy the base64 encoded public key (represented by *public key (base64 encoded)* in the example output), paste it into a new file, and then save the file. Give the file a descriptive name, such as `PublicKey.b64`.
1. Use [OpenSSL](https://openssl.org/) to base64 decode the file's contents and save the decoded data to a new file. The following example decodes the data in the file that you saved in the previous step (`PublicKey.b64`) and saves the output to a new file named `WrappingPublicKey.bin`.
```
$ openssl enc -d -base64 -A -in PublicKey.b64 -out WrappingPublicKey.bin
```
1. Copy the base64 encoded import token (represented by *import token (base64 encoded)* in the example output), paste it into a new file, and then save the file. Give the file a descriptive name, for example `importtoken.b64`.
1. Use [OpenSSL](https://openssl.org/) to base64 decode the file's contents and save the decoded data to a new file. The following example decodes the data in the file that you saved in the previous step (`ImportToken.b64`) and saves the output to a new file named `ImportToken.bin`.
```
$ openssl enc -d -base64 -A -in importtoken.b64 -out ImportToken.bin
```
Proceed to [Step 3: Encrypt the key material](importing-keys-encrypt-key-material.md).
# Step 3: Encrypt the key material
After you [download the public key and import token](importing-keys-get-public-key-and-token.md), encrypt your key material using the public key that you downloaded and the wrapping algorithm that you specified. If you need to replace the public key or import token, or change the wrapping algorithm, you must download a new public key and import token. For information about the public keys and wrapping algorithms that AWS KMS supports, see [Select a wrapping public key spec](importing-keys-get-public-key-and-token.md#select-wrapping-key-spec) and [Select a wrapping algorithm](importing-keys-get-public-key-and-token.md#select-wrapping-algorithm).
The key material must be in binary format. For detailed information, see [Requirements for imported key material](importing-keys-conceptual.md#importing-keys-material-requirements).
**Note**
For asymmetric key pairs, encrypt and import only the private key. AWS KMS derives the public key from the private key.
The following combination is NOT supported: ECC\$1NIST\$1P521 key material, the RSA\$12048 public wrapping key spec, and an RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithm.
You cannot directly wrap ECC\$1NIST\$1P521 key material with a RSA\$12048 public wrapping key. Use a larger wrapping key or an RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1\$1 wrapping algorithm.
The RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1256 and RSA\$1AES\$1KEY\$1WRAP\$1SHA\$11 wrapping algorithms are not supported in China Regions.
Typically, you encrypt your key material when you export it from your hardware security module (HSM) or key management system. For information about how to export key material in binary format, see the documentation for your HSM or key management system. You can also refer to the following section that provides a proof of concept demonstration using OpenSSL.
When you encrypt your key material, use the same wrapping algorithm that you specified when you [downloaded the public key and import token](importing-keys-get-public-key-and-token.md). To find the wrapping algorithm that you specified, see the CloudTrail log event for the associated [GetParametersForImport](https://docs.aws.amazon.com/kms/latest/APIReference/API_GetParametersForImport.html) request.
## Generate key material for testing
The following OpenSSL commands generate key material of each supported type for testing. These examples are provided only for testing and proof-of-concept demonstrations. For production systems, use a more secure method to generate your key material, such as a hardware security module or key management system.
To convert the private keys of asymmetric key pairs into DER-encoded format, pipe the key material generation command to the following `openssl pkcs8` command. The `topk8` parameter directs OpenSSL to take a private key as input and return a PKCS\$18 formatted key. (The default behavior is the opposite.)
```
openssl pkcs8 -topk8 -outform der -nocrypt
```
The following commands generate test key material for each of the supported key types.
+ Symmetric encryption key (32 bytes)
This command generates a 256-bit symmetric key (32-byte random string) and saves it in the `PlaintextKeyMaterial.bin` file. You do not need to encode this key material.
```
openssl rand -out PlaintextKeyMaterial.bin 32
```
In China Regions only, you must generate a 128-bit symmetric key (16-byte random string).
```
openssl rand -out PlaintextKeyMaterial.bin 16
```
+ HMAC keys
This command generates a random byte string of the specified size. You do not need to encode this key material.
The length of your HMAC key must match the length defined by the key spec of the KMS key. For example, if the KMS key is HMAC\$1384, you must import a 384-bit (48-byte) key.
```
openssl rand -out HMAC_224_PlaintextKey.bin 28
openssl rand -out HMAC_256_PlaintextKey.bin 32
openssl rand -out HMAC_384_PlaintextKey.bin 48
openssl rand -out HMAC_512_PlaintextKey.bin 64
```
+ RSA private keys
```
openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:2048 | openssl pkcs8 -topk8 -outform der -nocrypt > RSA_2048_PrivateKey.der
openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:3072 | openssl pkcs8 -topk8 -outform der -nocrypt > RSA_3072_PrivateKey.der
openssl genpkey -algorithm rsa -pkeyopt rsa_keygen_bits:4096 | openssl pkcs8 -topk8 -outform der -nocrypt > RSA_4096_PrivateKey.der
```
+ ECC private keys
```
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-256 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_NIST_P256_PrivateKey.der
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-384 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_NIST_P384_PrivateKey.der
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:P-521 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_NIST_P521_PrivateKey.der
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:secp256k1 | openssl pkcs8 -topk8 -outform der -nocrypt > ECC_SECG_P256K1_PrivateKey.der
```
+ SM2 private keys (China Regions only)
```
openssl genpkey -algorithm ec -pkeyopt ec_paramgen_curve:sm2 | openssl pkcs8 -topk8 -outform der -nocrypt > SM2_PrivateKey.der
```
## Examples of encrypting key material with OpenSSL
The following examples show how to use [OpenSSL](https://openssl.org/) to encrypt your key material with the public key that you downloaded. To encrypt your key material using an SM2 public key (China Regions only), use the [`SM2OfflineOperationHelper` class](offline-operations.md#key-spec-sm-offline-helper). For more information on the key material types that each wrapping algorithm supports, see [Select a wrapping algorithm](importing-keys-get-public-key-and-token.md#select-wrapping-algorithm).
**Important**
These examples are a proof of concept demonstration only. For production systems, use a more secure method (such as a commercial HSM or key management system) to generate and store your key material.
The following combination is NOT supported: ECC\$1NIST\$1P521 key material, the RSA\$12048 public wrapping key spec, and an RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithm.
You cannot directly wrap ECC\$1NIST\$1P521 key material with a RSA\$12048 public wrapping key. Use a larger wrapping key or an RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1\$1 wrapping algorithm.
------
#### [ RSAES\$1OAEP\$1SHA\$11 ]
AWS KMS supports the RSAES\$1OAEP\$1SHA\$11 for symmetric encryption keys (SYMMETRIC\$1DEFAULT), elliptic curve (ECC) private keys, SM2 private keys, and HMAC keys.
RSAES\$1OAEP\$1SHA\$11 is not supported for RSA private keys. Also, you cannot use an RSA\$12048 public wrapping key with any RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithm to wrap an ECC\$1NIST\$1P521 (secp521r1) private key. You must use a larger public wrapping key or an RSA\$1AES\$1KEY\$1WRAP wrapping algorithm.
The following example encrypts your key material with the [public key that you downloaded](importing-keys-get-public-key-and-token.md) and the RSAES\$1OAEP\$1SHA\$11 wrapping algorithm, and saves it in the `EncryptedKeyMaterial.bin` file.
In this example:
+ *`WrappingPublicKey.bin`* is the file that contains the downloaded wrapping public key.
+ *`PlaintextKeyMaterial.bin`* is the file that contains the key material that you are encrypting, such as `PlaintextKeyMaterial.bin`, `HMAC_384_PlaintextKey.bin` or `ECC_NIST_P521_PrivateKey.der`.
```
$ openssl pkeyutl \
-encrypt \
-in PlaintextKeyMaterial.bin \
-out EncryptedKeyMaterial.bin \
-inkey WrappingPublicKey.bin \
-keyform DER \
-pubin \
-pkeyopt rsa_padding_mode:oaep \
-pkeyopt rsa_oaep_md:sha1
```
------
#### [ RSAES\$1OAEP\$1SHA\$1256 ]
AWS KMS supports the RSAES\$1OAEP\$1SHA\$1256 for symmetric encryption keys (SYMMETRIC\$1DEFAULT), elliptic curve (ECC) private keys, SM2 private keys, and HMAC keys.
RSAES\$1OAEP\$1SHA\$1256 is not supported for RSA private keys. Also, you cannot use an RSA\$12048 public wrapping key with any RSAES\$1OAEP\$1SHA\$1\$1 wrapping algorithm to wrap an ECC\$1NIST\$1P521 (secp521r1) private key. You must use a larger public key or an RSA\$1AES\$1KEY\$1WRAP wrapping algorithm.
The following example encrypts key material with the [public key that you downloaded](importing-keys-get-public-key-and-token.md) and the RSAES\$1OAEP\$1SHA\$1256 wrapping algorithm, and saves it in the `EncryptedKeyMaterial.bin` file.
In this example:
+ *`WrappingPublicKey.bin`* is the file that contains the downloaded public wrapping key. If you downloaded the public key from the console, this file is named `wrappingKey_KMS key_key_ID_timestamp` (for example, `wrappingKey_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909`).
+ *`PlaintextKeyMaterial.bin`* is the file that contains the key material that you are encrypting, such as `PlaintextKeyMaterial.bin`, `HMAC_384_PlaintextKey.bin`, or `ECC_NIST_P521_PrivateKey.der`.
```
$ openssl pkeyutl \
-encrypt \
-in PlaintextKeyMaterial.bin \
-out EncryptedKeyMaterial.bin \
-inkey WrappingPublicKey.bin \
-keyform DER \
-pubin \
-pkeyopt rsa_padding_mode:oaep \
-pkeyopt rsa_oaep_md:sha256 \
-pkeyopt rsa_mgf1_md:sha256
```
------
#### [ RSA\$1AES\$1KEY\$1WRAP\$1SHA\$11 ]
The RSA\$1AES\$1KEY\$1WRAP\$1SHA\$11 wrapping algorithm involves two encryption operations.
1. Encrypt your key material with an AES symmetric key that you generate and an AES symmetric encryption algorithm.
1. Encrypt the AES symmetric key that you used with the public key that you downloaded and the RSAES\$1OAEP\$1SHA\$11 wrapping algorithm.
The RSA\$1AES\$1KEY\$1WRAP\$1SHA\$11 wrapping algorithm requires OpenSSL version 3.*x* or later.
1.
**Generate a 256-bit AES symmetric encryption key**
This command generates an AES symmetric encryption key consisting of 256 random bits, and saves it in the `aes-key.bin` file
```
# Generate a 32-byte AES symmetric encryption key
$ openssl rand -out aes-key.bin 32
```
1.
**Encrypt your key material with the AES symmetric encryption key**
This command encrypts your key material with the AES symmetric encryption key and saves the encrypted key material in the `key-material-wrapped.bin` file.
In this example command:
+ *`PlaintextKeyMaterial.bin`* is the file that contains the key material that you are importing, such as `PlaintextKeyMaterial.bin`, `HMAC_384_PlaintextKey.bin`, `RSA_3072_PrivateKey.der`, or `ECC_NIST_P521_PrivateKey.der`.
+ *`aes-key.bin`* is the file that contains 256-bit AES symmetric encryption key that you generated in the previous command.
```
# Encrypt your key material with the AES symmetric encryption key
$ openssl enc -id-aes256-wrap-pad \
-K "$(xxd -p < aes-key.bin | tr -d '\n')" \
-iv A65959A6 \
-in PlaintextKeyMaterial.bin \
-out key-material-wrapped.bin
```
1.
**Encrypt your AES symmetric encryption key with the public key**
This command encrypts your AES symmetric encryption key with the public key that you downloaded and the RSAES\$1OAEP\$1SHA\$11 wrapping algorithm, DER-encodes it, and save it in the `aes-key-wrapped.bin` file.
In this example command:
+ *`WrappingPublicKey.bin`* is the file that contains the downloaded public wrapping key. If you downloaded the public key from the console, this file is named `wrappingKey_KMS key_key_ID_timestamp` (for example, `wrappingKey_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909`
+ *`aes-key.bin`* is the file that contains 256-bit AES symmetric encryption key that you generated in the first command in this example sequence.
```
# Encrypt your AES symmetric encryption key with the downloaded public key
$ openssl pkeyutl \
-encrypt \
-in aes-key.bin \
-out aes-key-wrapped.bin \
-inkey WrappingPublicKey.bin \
-keyform DER \
-pubin \
-pkeyopt rsa_padding_mode:oaep \
-pkeyopt rsa_oaep_md:sha1 \
-pkeyopt rsa_mgf1_md:sha1
```
1.
**Generate the file to import**
Concatenate the file with the encrypted key material and the file with the encrypted AES key. Save them in the `EncryptedKeyMaterial.bin` file, which is the file that you'll import in the [Step 4: Import the key material](importing-keys-import-key-material.md).
In this example command:
+ *`key-material-wrapped.bin`* is the file that contains your encrypted key material.
+ *`aes-key-wrapped.bin`* is the file that contains the encrypted AES encryption key.
```
# Combine the encrypted AES key and encrypted key material in a file
$ cat aes-key-wrapped.bin key-material-wrapped.bin > EncryptedKeyMaterial.bin
```
------
#### [ RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1256 ]
The RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1256 wrapping algorithm involves two encryption operations.
1. Encrypt your key material with an AES symmetric key that you generate and an AES symmetric encryption algorithm.
1. Encrypt the AES symmetric key that you used with the public key that you downloaded and the RSAES\$1OAEP\$1SHA\$1256 wrapping algorithm.
The RSA\$1AES\$1KEY\$1WRAP\$1SHA\$1256 wrapping algorithm requires OpenSSL version 3.*x* or later.
1.
**Generate a 256-bit AES symmetric encryption key**
This command generates an AES symmetric encryption key consisting of 256 random bits, and saves it in the `aes-key.bin` file
```
# Generate a 32-byte AES symmetric encryption key
$ openssl rand -out aes-key.bin 32
```
1.
**Encrypt your key material with the AES symmetric encryption key**
This command encrypts your key material with the AES symmetric encryption key and saves the encrypted key material in the `key-material-wrapped.bin` file.
In this example command:
+ *`PlaintextKeyMaterial.bin`* is the file that contains the key material that you are importing, such as `PlaintextKeyMaterial.bin`, `HMAC_384_PlaintextKey.bin`, `RSA_3072_PrivateKey.der`, or `ECC_NIST_P521_PrivateKey.der`.
+ *`aes-key.bin`* is the file that contains 256-bit AES symmetric encryption key that you generated in the previous command.
```
# Encrypt your key material with the AES symmetric encryption key
$ openssl enc -id-aes256-wrap-pad \
-K "$(xxd -p < aes-key.bin | tr -d '\n')" \
-iv A65959A6 \
-in PlaintextKeyMaterial.bin \
-out key-material-wrapped.bin
```
1.
**Encrypt your AES symmetric encryption key with the public key**
This command encrypts your AES symmetric encryption key with the public key that you downloaded and the RSAES\$1OAEP\$1SHA\$1256 wrapping algorithm, DER-encodes it, and save it in the `aes-key-wrapped.bin` file.
In this example command:
+ *`WrappingPublicKey.bin`* is the file that contains the downloaded public wrapping key. If you downloaded the public key from the console, this file is named `wrappingKey_KMS key_key_ID_timestamp` (for example, `wrappingKey_f44c4e20-f83c-48f4-adc6-a1ef38829760_0809092909`
+ *`aes-key.bin`* is the file that contains 256-bit AES symmetric encryption key that you generated in the first command in this example sequence.
```
# Encrypt your AES symmetric encryption key with the downloaded public key
$ openssl pkeyutl \
-encrypt \
-in aes-key.bin \
-out aes-key-wrapped.bin \
-inkey WrappingPublicKey.bin \
-keyform DER \
-pubin \
-pkeyopt rsa_padding_mode:oaep \
-pkeyopt rsa_oaep_md:sha256 \
-pkeyopt rsa_mgf1_md:sha256
```
1.
**Generate the file to import**
Concatenate the file with the encrypted key material and the file with the encrypted AES key. Save them in the `EncryptedKeyMaterial.bin` file, which is the file that you'll import in the [Step 4: Import the key material](importing-keys-import-key-material.md).
In this example command:
+ *`key-material-wrapped.bin`* is the file that contains your encrypted key material.
+ *`aes-key-wrapped.bin`* is the file that contains the encrypted AES encryption key.
```
# Combine the encrypted AES key and encrypted key material in a file
$ cat aes-key-wrapped.bin key-material-wrapped.bin > EncryptedKeyMaterial.bin
```
------
Proceed to [Step 4: Import the key material](importing-keys-import-key-material.md).
# Step 4: Import the key material
After you [encrypt your key material](importing-keys-encrypt-key-material.md), you can import the key material to use with an AWS KMS key. To import key material, you upload the encrypted key material from [Step 3: Encrypt the key material](importing-keys-encrypt-key-material.md) and the import token that you downloaded at [Step 2: Download the wrapping public key and import token](importing-keys-get-public-key-and-token.md). You must import key material into the same KMS key that you specified when you [downloaded the public key and import token](importing-keys-get-public-key-and-token.md). When key material is successfully imported, the [key state](key-state.md) of the KMS key changes to `Enabled`, and you can use the KMS key in cryptographic operations.
When you import key material, you can [set an optional expiration time](#importing-keys-expiration) for the key material. When the key material expires, AWS KMS deletes the key material and the KMS key becomes unusable. After you import your key material, you cannot set, change, or cancel the expiration date for the current import. To change these values, you must [reimport](#reimport-key-material) the same key material.
For all KMS keys with `EXTERNAL` origin, the first key material imported into it becomes current and permanently associated with it. Symmetric encryption keys with `EXTERNAL` origin support on-demand rotation. You can associate multiple key materials with imported keys that support on-demand rotation. The process for importing new key material differs for single-Region and multi-Region keys as described in the section [Import new key material](#import-new-key-material). You must set the `importType` parameter to `NEW_KEY_MATERIAL` with the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) action to associate new key material with a KMS key. The default value of the optional `ImportType` parameter is `EXISTING_KEY_MATERIAL`. When you omit the `ImportType` parameter or specify it as `EXISTING_KEY_MATERIAL`, you must import a key material that is previously associated with the KMS key.
For asymmetric, or HMAC KMS keys with `EXTERNAL` origin, only one key material can ever be associated with the key. AWS KMS will reject [ ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) API requests with the `ImportType` parameter.
When all key materials permanently associated with a KMS key are imported, the KMS key is available for use in cryptographic operations. If any one of these key materials is deleted or allowed to expire, the KMS key state changes to `PendingImport` and the key is unusable for cryptographic operations.
To import key material, you can use the [AWS KMS console](#importing-keys-import-key-material-console) or the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) API. You can use the API directly by making HTTP requests, or by using an [AWS SDKs](https://aws.amazon.com/tools/#sdk), [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/) or [AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/).
When you import the key material, an [ImportKeyMaterial entry](ct-importkeymaterial.md) is added to your AWS CloudTrail log to record the `ImportKeyMaterial` operation. The CloudTrail entry is the same whether you use the AWS KMS console or the AWS KMS API.
## Setting an expiration time (optional)
When you import the key material for your KMS key, you can set an optional expiration date and time for the key material of up to 365 days from the import date. When imported key material expires, AWS KMS deletes it. This action changes the [key state](key-state.md#key-state-table) of the KMS key to `PendingImport`, which prevents it from being used in any cryptographic operation. To use the KMS key, you must [reimport a copy of the original key material](#reimport-key-material).
Ensuring that imported key material expires frequently can help you to satisfy regulatory requirements, but it introduces an additional a risk to data encrypted under the KMS key. Until you reimport a copy of the original key material, a KMS key with expired key material is unusable, and any data encrypted under the KMS key is inaccessible. If you fail to reimport the key material for any reason, including losing your copy of the original key material, the KMS key is permanently unusable, and data encrypted under the KMS key is unrecoverable.
To mitigate this risk, make sure that your copy of the imported key material is accessible, and design a system to delete and reimport the key material before it expires and interrupts your AWS workload. We recommend that you [set an alarm](imported-key-material-expiration-alarm.md) for the expiration of your imported key material that gives you plenty of time to reimport the key material before it expires. You can also use your CloudTrail logs to audit operations that [import (and reimport) key material](ct-importkeymaterial.md) and [delete imported key material](ct-deleteimportedkeymaterial.md), and the AWS KMS operation to [delete expired key material](ct-deleteexpiredkeymaterial.md).
AWS KMS cannot restore, recover, or reproduce the deleted key material. Instead of setting an expiration time, you can programmatically [delete](importing-keys-delete-key-material.md) and [reimport](#reimport-key-material) the imported key material periodically, but the requirements for retaining a copy of the original key material are the same.
You determine whether and when imported key material expires when you import the key material. However you can turn expiration on and off, or set a new expiration time by reimporting the key material. Use the `ExpirationModel` parameter of [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) to turn expiration on (`KEY_MATERIAL_EXPIRES`) and off (`KEY_MATERIAL_DOES_NOT_EXPIRE`) and the `ValidTo` parameter to set the expiration time. The maximum time is 365 days from the import data; there is no minimum, but the time must be in the future.
## Set key material description
Symmetric encryption keys with `EXTERNAL` origin can have multiple key materials associated with them. You can specify an optional key material description when importing key material into such keys. The description can be used to keep track of where the corresponding key material is durably maintained outside AWS KMS.
For multi-Region keys, you can set or change the key material description only on the primary Region key. AWS KMS automatically propagates the key material description to replica Region keys.
## Import new key material
To perform on-demand rotation on a symmetric encryption KMS key with imported key material, you'll first need to import new key material, not previously associated with the key.
+ **Single Region keys**
+ Use the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) operation with the `ImportType` parameter set to `NEW_KEY_MATERIAL` to accomplish this task. This key material is not permanently associated with the key until you perform the [RotateKeyOnDemand](https://docs.aws.amazon.com/kms/latest/APIReference/API_RotateKeyOnDemand.html) operation or rotate the key in the AWS Management Console. Until then, this key material is in `PENDING_ROTATION` state. A KMS key can have at most one key material in `PENDING_ROTATION` state at any time. A key material in `PENDING_ROTATION` state can be deleted without impacting the key's usability in cryptographic operations.
+ **Multi-Region keys**
+ To import key material into a multi-Region key, you must first import the new key material to the primary Region key. You cannot directly import new key materials to replica Region keys. After importing new key material to the primary Region key, you can import the same key materials into the replica Region keys.
+ Use the [https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) operation with the `ImportType` parameter set to **NEW\$1KEY\$1MATERIAL** for the primary Region key to accomplish this task. For the replica Region key, use the **EXISTING\$1KEY\$1MATERIAL** parameter for `ImportType` for the `ImportKeyMaterial` operation.
+ The key material for symmetric-encryption multi-Region keys must be imported into all the replica Region keys and primary Region keys before the key material state changes to `PENDING_ROTATION` state. Until then, the state of the new key material is `PENDING_MULTI_REGION_IMPORT_AND_ROTATION`. A KMS key can have at most one key material in `PENDING_ROTATION` or `PENDING_MULTI_REGION_IMPORT_AND_ROTATION`state at any time (see the `KeyMaterialState` description in [RotationsListEntry](https://docs.aws.amazon.com/kms/latest/APIReference/API_RotationsListEntry.html)). A key material in `PENDING_MULTI_REGION_IMPORT_AND_ROTATION` or `PENDING_ROTATION` state is not permanently associated with the key and can be deleted without impacting the key's usability in cryptographic operations.
## Reimport key material
If you manage a KMS key with imported key material, you might need to reimport the key material. You might reimport key material to replace expiring or deleted key material, or to change the expiration model or expiration date of the key material.
You can reimport key material at any time, on any schedule that meets your security requirements. You do not have to wait until the key material is at or close to its expiration time.
The procedure to reimport key material is the same procedure that you use to import the key material the first time, with the following exceptions.
+ Use an existing KMS key, instead of creating a new KMS key. You can skip [Step 1](importing-keys-create-cmk.md) of the import procedure.
+ When you reimport key material, you can change the expiration model and expiration date. For symmetric encryption keys, you can also change the key material description.
For multi-Region keys, you can set or change the key material description only on the primary Region key. AWS KMS automatically propagates the key material description to replica Region keys.
Each time you import key material to a KMS key, you need to [download and use a new wrapping key and import token](importing-keys-get-public-key-and-token.md) for the KMS key. The wrapping procedure does not affect the content of the key material, so you can use different wrapping public keys and different wrapping algorithms to import the same key material.
## Import key material (console)
You can use the AWS Management Console to import key material.
1. If you are on the **Upload your wrapped key material** page, skip to [Step 10](#id-key-materials-step).
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose the key ID or alias of the KMS key for which you downloaded the public key and import token.
1. Choose the **Cryptographic configuration** tab and view its values. The tabs are on the detail page for a KMS key below the **General configuration** section.
You can only import key material into KMS keys with an **Origin** of **External (Import key material)**. For information about creating KMS keys with imported key material, see [Importing key material for AWS KMS keys](importing-keys.md).
1. Choose the appropriate tab based on your key type.
+ For asymmetric and HMAC keys, choose the **Key material** tab.
+ For symmetric encryption keys, choose the **Key material and rotations** tab.
1. Choose the import action.
+ For asymmetric and HMAC keys, choose **Import key material**.
+ For symmetric encryption keys, choose one of the following:
+ **Import initial key material** (if no key material has been imported yet)
+ **Import new key material** (to add new material for rotation)
+ **Reimport key material** (available from the **Actions** menu in the key materials table)
**Note**
For Multi-Region keys, you must first import the new key material into the primary Region key. Then, import the same key material into each replica Region key.
For primary multi-Region keys, the **Key materials** table includes a **Replica import state** column that displays the import status across all replica regions (for example, "0 of 3 imported"). Choose the replica import state value to open a modal that shows the import status for each replica region. The modal provides **Import key material** links for replica regions where the new key material has not been imported.
1. If you downloaded the key material, import token, and encrypted the key material, choose **Next**.
**Note**
For Multi-Region keys, you must first import the new key material into the primary Region key. Then you can import the same key material into the replica Region keys.
1. In the **Encrypted key material and import token** section, do the following.
1. Under **Wrapped key material**, choose **Choose file**. Then upload the file that contains your wrapped (encrypted) key material.
1. Under **Import token**, choose **Choose file**. Upload the file that contains the import token that you [downloaded](importing-keys-get-public-key-and-token.md#importing-keys-get-public-key-and-token-console).
1. In the **Expiration option** section, you determine whether the key material expires. To set an expiration date and time, choose **Key material expires**, and use the calendar to select a date and time. You can specify a date up to 365 days from the current date and time.
1. For symmetric encryption keys, you can optionally specify a description for the key material being imported.
1. Choose **Import key material**.
## Import key material (AWS KMS API)
To import key material, use the [ImportKeyMaterial](https://docs.aws.amazon.com/kms/latest/APIReference/API_ImportKeyMaterial.html) operation. The following example uses the [AWS CLI](https://aws.amazon.com/cli/), but you can use any supported programming language.
To use this example:
1. Replace `1234abcd-12ab-34cd-56ef-1234567890ab` with a key ID of the KMS key that you specified when you downloaded the public key and import token. To identify the KMS key, use its [key ID](concepts.md#key-id-key-id) or [key ARN](concepts.md#key-id-key-ARN). You cannot use an [alias name](concepts.md#key-id-alias-name) or [alias ARN](concepts.md#key-id-alias-ARN) for this operation.
1. Replace `EncryptedKeyMaterial.bin` with the name of the file that contains the encrypted key material.
1. Replace `ImportToken.bin` with the name of the file that contains the import token.
1. If you want the imported key material to expire, set the value of the `expiration-model` parameter to its default value, `KEY_MATERIAL_EXPIRES`, or omit the `expiration-model` parameter. Then, replace the value of the `valid-to` parameter with the date and time that you want the key material to expire. The date and time can be up to 365 days from the time of the request.
```
$ aws kms import-key-material --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--encrypted-key-material fileb://EncryptedKeyMaterial.bin \
--import-token fileb://ImportToken.bin \
--expiration-model KEY_MATERIAL_EXPIRES \
--valid-to 2023-06-17T12:00:00-08:00
```
If you do not want the imported key material to expire, set the value of the `expiration-model` parameter to `KEY_MATERIAL_DOES_NOT_EXPIRE` and omit the `valid-to` parameter from the command.
```
$ aws kms import-key-material --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--encrypted-key-material fileb://EncryptedKeyMaterial.bin \
--import-token fileb://ImportToken.bin \
--expiration-model KEY_MATERIAL_DOES_NOT_EXPIRE
```
1. If you want to import new key material, not previously associated with the KMS key, set the `ImportType` parameter to `NEW_KEY_MATERIAL`. This option can only be used with symmetric encryption keys. For these keys, you can also use the optional `KeyMaterialDescription` parameter to set a description for the imported key material in the following command line example:
```
$ aws kms import-key-material --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
--encrypted-key-material fileb://EncryptedKeyMaterial.bin \
--import-token fileb://ImportToken.bin \
--expiration-model KEY_MATERIAL_EXPIRES \
--valid-to 2023-06-17T12:00:00-08:00 \
--import-type NEW_KEY_MATERIAL \
--key-material-description "Q2 2025 Rotation"
```
1. For multi-Region keys, you can set or change the key material description only on the primary Region key. AWS KMS automatically propagates the key material description to replica Region keys.
**Tip**
If the command does not succeed, you might see a `KMSInvalidStateException` or a `NotFoundException`. You can retry the request.
# Create a KMS key in an AWS CloudHSM key store
After you have created an AWS CloudHSM key store, you can create AWS KMS keys in your key store. They must be [symmetric encryption KMS keys](symm-asymm-choose-key-spec.md#symmetric-cmks) with key material that AWS KMS generates. You cannot create [asymmetric KMS keys](symmetric-asymmetric.md), [HMAC KMS keys](hmac.md) or KMS keys with [imported key material](importing-keys.md) in a custom key store. Also, you cannot use symmetric encryption KMS keys in a custom key store to generate asymmetric data key pairs. KMS cannot communicate over IPv6 with AWS CloudHSM key stores.
To create a KMS key in an AWS CloudHSM key store, the AWS CloudHSM key store must be [connected to the associated AWS CloudHSM cluster](connect-keystore.md) 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 [AWS CloudHSM key stores page](view-keystore.md#view-keystore-console) in the AWS Management Console. When using the API operations, use the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation to verify that the AWS CloudHSM key store is connected. To verify the number of active HSMs in the cluster and their Availability Zones, use the AWS CloudHSM [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation.
When you create a KMS key in your AWS CloudHSM key store, AWS KMS creates the KMS key in AWS KMS. But, it creates the key material for the KMS key in the associated AWS CloudHSM cluster. Specifically, AWS KMS signs into the cluster as the [`kmsuser` CU that you created](create-keystore.md#before-keystore). Then it creates a persistent, non-extractable, 256-bit Advanced Encryption Standard (AES) symmetric key in the cluster. AWS KMS sets the value of the [key label attribute](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_cli-key-attributes.html), which is visible only in the cluster, to Amazon Resource Name (ARN) of the KMS key.
When the command succeeds, the [key state](key-state.md) 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 AWS CloudHSM key store in the AWS KMS console or by using the [DescribeKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) 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 AWS CloudHSM cluster ID.
If your attempt to create a KMS key in your AWS CloudHSM key store fails, use the error message to help you determine the cause. It might indicate that the AWS CloudHSM key store is not connected (`CustomKeyStoreInvalidStateException`) or the associated AWS CloudHSM cluster doesn't have the two active HSMs that are required for this operation (`CloudHsmClusterInvalidConfigurationException`). For help see [Troubleshooting a custom key store](fix-keystore.md).
For an example of the AWS CloudTrail log of the operation that creates a KMS key in an AWS CloudHSM key store, see [CreateKey](ct-createkey.md).
## Create a new KMS key in your CloudHSM key store
You can create a symmetric encryption KMS key in your AWS CloudHSM key store in the AWS KMS console or by using the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation.
### Using the AWS KMS console
Use the following procedure to create a symmetric encryption KMS key in an AWS 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.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose **Create key**.
1. Choose **Symmetric**.
1. In **Key usage**, the **Encrypt and decrypt** option is selected for you. Do not change it.
1. Choose **Advanced options**.
1. For **Key material origin**, choose **AWS CloudHSM key store**.
You cannot create a multi-Region key in an AWS CloudHSM key store.
1. Choose **Next**.
1. Select an AWS CloudHSM key store for your new KMS key. To create a new AWS CloudHSM key store, choose **Create custom key store**.
The AWS CloudHSM key store that you select must have a status of **Connected**. Its associated AWS CloudHSM cluster must be active and contain at least two active HSMs in different Availability Zones.
For help with connecting an AWS CloudHSM key store, see [Disconnect an AWS CloudHSM key store](connect-keystore.md). For help with adding HSMs, see [Adding an HSM](https://docs.aws.amazon.com/cloudhsm/latest/userguide/add-remove-hsm.html#add-hsm) in the *AWS CloudHSM User Guide*.
1. Choose **Next**.
1. Type an alias and an optional description for the KMS key.
1. (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](tagging-keys.md) and [ABAC for AWS KMS](abac.md).
1. Choose **Next**.
1. 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](key-policy-default.md#key-policy-default-allow-administrators).
**Notes**
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
The AWS KMS console adds key administrators to the key policy under the statement identifier `"Allow access for Key Administrators"`. Modifying this statement identifier might impact how the console displays updates that you make to the statement.
1. (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.**
1. Choose **Next**.
1. In the **This account** section, select the IAM users and roles in this AWS account that can use the KMS key in [cryptographic operations](kms-cryptography.md#cryptographic-operations). For more information, see [Allows key users to use the KMS key](key-policy-default.md#key-policy-default-allow-users).
**Notes**
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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
The AWS KMS console adds key users to the key policy under the statement identifiers `"Allow use of the key"` and `"Allow attachment of persistent resources"`. Modifying these statement identifiers might impact how the console displays updates that you make to the statement.
1. (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](key-policy-modifying-external-accounts.md).
1. Choose **Next**.
1. Review the key policy statements for the key. To make changes to the key policy, select **Edit**.
1. Choose **Next**.
1. Review the key settings that you chose. You can still go back and change all settings.
1. When you're done, choose **Finish** to create the key.
When the procedure succeeds, the display shows the new KMS key in the AWS 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 (**AWS CloudHSM**), the name, ID, and type of the custom key store, and the ID of the AWS 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](viewing-console-customize.md).
### Using the AWS KMS API
To create a new AWS KMS key (KMS key) in your AWS CloudHSM key store, use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_PutKeyPolicy.html)) and add optional elements, such as a [description](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeKey.html) and [tags](https://docs.aws.amazon.com/kms/latest/APIReference/API_TagResource.html) at any time.
The examples in this section use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language.
The following example begins with a call to the [DescribeCustomKeyStores](https://docs.aws.amazon.com/kms/latest/APIReference/API_DescribeCustomKeyStores.html) operation to verify that the AWS CloudHSM key store is connected to its associated AWS CloudHSM cluster. By default, this operation returns all custom keys stores in your account and Region. To describe only a particular AWS 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": "AWS CloudHSM key store",
"CloudHsmClusterId": "cluster-1a23b4cdefg",
"TrustAnchorCertificate": "",
"CreationDate": "1.499288695918E9",
"ConnectionState": "CONNECTED"
],
}
```
The next example command uses the [DescribeClusters](https://docs.aws.amazon.com/cloudhsm/latest/APIReference/API_DescribeClusters.html) operation to verify that the AWS 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](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation to create a KMS key in an AWS CloudHSM key store. To create a KMS key in an AWS CloudHSM key store, you must provide the custom key store ID of the AWS CloudHSM key store and specify an `Origin` value of `AWS_CLOUDHSM`.
The response includes the IDs of the custom key store and the AWS 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"
]
}
}
```
# Create a KMS key in external key stores
After you have [created](create-xks-keystore.md) and [connected](xks-connect-disconnect.md) your external key store, you can create AWS KMS keys in your key store. They must be [symmetric encryption KMS keys](symm-asymm-choose-key-spec.md#symmetric-cmks) with an origin value of **External key store** (`EXTERNAL_KEY_STORE`). You cannot create [asymmetric KMS keys](symmetric-asymmetric.md), [HMAC KMS keys](hmac.md) or KMS keys with [imported key material](importing-keys.md) 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](create-keys.md#key-origin) of External key store (`EXTERNAL_KEY_STORE`).
+ The ID of an existing [external key](keystore-external.md#concept-external-key) in the [external key manager](keystore-external.md#concept-ekm) 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](keystore-external.md#concept-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](keystore-external.md#xks-how-it-works).
When the `CreateKey` operation succeeds, the [key state](key-state.md) of the new KMS key is `Enabled`. When you [view a KMS key in an external key store](identify-key-types.md#view-xks-key) you can see typical properties, like its key ID, [key spec](create-keys.md#key-spec), [key usage](create-keys.md#key-usage), [key state](key-state.md), and creation date. But you can also see the ID and [connection state](xks-connect-disconnect.md#xks-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](ct-createkey.md).
**Topics**
+ [
## Requirements for a KMS key in an external key store
](#xks-key-requirements)
+ [
## Create a new KMS key in your external key store
](#create-key-xks)
## 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](xks-connect-disconnect.md#xks-connection-state) of your external key store, see [View external key stores](view-xks-keystore.md). To connect your external key store, see [Connect and disconnect external key stores](xks-connect-disconnect.md).
**KMS key requirements**
You cannot change these properties after you create the KMS key.
+ Key spec: SYMMETRIC\$1DEFAULT
+ Key usage: ENCRYPT\$1DECRYPT
+ Key material origin: EXTERNAL\$1KEY\$1STORE
+ Multi-Region: FALSE
**External key requirements**
+ 256-bit AES cryptographic key (256 random bits). The `KeySpec` of the external key must be `AES_256`.
+ Enabled and available for use. The `Status` of the external key must be `ENABLED`.
+ Configured for encryption and decryption. The `KeyUsage` of the external key must include `ENCRYPT` and `DECRYPT`.
+ 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](keystore-external.md#concept-xks-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](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation.
### Using the AWS KMS console
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.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Custom key stores**, **External key stores**.
1. Choose the name of your external key store.
1. 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.
1. Enter the key ID of an [external key](keystore-external.md#concept-external-key) in your [external key manager](keystore-external.md#concept-ekm). This external key must [fulfill the requirements](#xks-key-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.
1. Confirm that you intend to create a KMS key in the specified external key store.
1. Choose **Next**.
The remainder of this procedure is the same as [creating a standard KMS key](create-keys.md).
1. Type an alias (required) and a description (optional) for the KMS key.
1. (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](tagging-keys.md) and [ABAC for AWS KMS](abac.md).
1. Choose **Next**.
1. 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](key-policy-default.md#key-policy-default-allow-administrators).
**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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
1. (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](deleting-keys.md#special-considerations-delete).
1. Choose **Next**.
1. In the **This account** section, select the IAM users and roles in this AWS account that can use the KMS key in [cryptographic operations](kms-cryptography.md#cryptographic-operations). For more information, see [Allows key users to use the KMS key](key-policy-default.md#key-policy-default-allow-users).
**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](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
1. (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](key-policy-modifying-external-accounts.md).
1. Choose **Next**.
1. Review the key settings that you chose. You can still go back and change all settings.
1. 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](#xks-key-requirements) for a KMS key in an external key store, such as the key spec and key usage.
1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at [https://console.aws.amazon.com/kms](https://console.aws.amazon.com/kms).
1. To change the AWS Region, use the Region selector in the upper-right corner of the page.
1. In the navigation pane, choose **Customer managed keys**.
1. Choose **Create key**.
1. Choose **Symmetric**.
1. In **Key usage**, the **Encrypt and decrypt** option is selected for you. Do not change it.
1. Choose **Advanced options**.
1. For **Key material origin**, choose **External key store**.
1. Confirm that you intend to create a KMS key in the specified external key store.
1. Choose **Next**.
1. 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](about-xks-connecting.md#connect-xks-console).
1. Enter the key ID of an [external key](keystore-external.md#concept-external-key) in your [external key manager](keystore-external.md#concept-ekm). This external key must [fulfill the requirements](#xks-key-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.
1. Choose **Next**.
The remainder of this procedure is the same as [creating a standard KMS key](create-keys.md).
1. Type an alias and an optional description for the KMS key.
1. (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](tagging-keys.md) and [ABAC for AWS KMS](abac.md).
1. Choose **Next**.
1. 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](key-policy-default.md#key-policy-default-allow-administrators).
**Note**
IAM policies can give other IAM users and roles permission to use the KMS key.
1. (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 key](deleting-keys.md).
1. Choose **Next**.
1. In the **This account** section, select the IAM users and roles in this AWS account that can use the KMS key in [cryptographic operations](kms-cryptography.md#cryptographic-operations). For more information, see [Allows key users to use the KMS key](key-policy-default.md#key-policy-default-allow-users).
**Note**
IAM policies can give other IAM users and roles permission to use the KMS key.
1. (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](key-policy-modifying-external-accounts.md).
1. Choose **Next**.
1. Review the key settings that you chose. You can still go back and change all settings.
1. 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](xks-troubleshooting.md).
**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](viewing-console-customize.md).
### Using the AWS KMS API
To create a new KMS key in an external key store, use the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) operation. The following parameters are required:
+ The `Origin` value must be `EXTERNAL_KEY_STORE`.
+ The `CustomKeyStoreId` parameter identifies your external key store. The [`ConnectionState`](xks-connect-disconnect.md#xks-connection-state) of the specified external key store must be `CONNECTED`. To find the `CustomKeyStoreId` and `ConnectionState`, use the `DescribeCustomKeyStores` operation.
+ The `XksKeyId` parameter identifies the external key. This external key must [fulfills the requirements](#xks-key-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](https://docs.aws.amazon.com/kms/latest/APIReference/API_TagResource.html) 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)](https://aws.amazon.com/cli/), but you can use any supported programming language.
This example command uses the [CreateKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateKey.html) 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-id bb8562717f809024
{
"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"
}
}
}
```