# Create an HMAC KMS key
You can create HMAC KMS keys in the Amazon KMS console, by using the [https://docs.amazonaws.cn/kms/latest/APIReference/API_CreateKey.html](https://docs.amazonaws.cn/kms/latest/APIReference/API_CreateKey.html) API, or by using the [AWS::KMS::Key Amazon CloudFormation template](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/aws-resource-kms-key.html).
When you create an HMAC KMS key, you must select a key spec. Amazon 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 Amazon KMS console
You can use the Amazon Web Services 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 Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at [https://console.amazonaws.cn/kms](https://console.amazonaws.cn/kms).
1. To change the Amazon Web Services 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 Amazon 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 Amazon 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 Amazon Web Services Management Console. You cannot specify an alias when you use the [CreateKey](https://docs.amazonaws.cn/kms/latest/APIReference/API_CreateKey.html) operation, but you can use the console or the [CreateAlias](https://docs.amazonaws.cn/kms/latest/APIReference/API_CreateAlias.html) operation to create an alias for an existing KMS key. For details, see [Aliases in Amazon 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 Amazon Web Services Management Console in the Amazon Web Services Management Console or use the [UpdateKeyDescription](https://docs.amazonaws.cn/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 Amazon 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 Amazon resources, Amazon generates a cost allocation report with usage and costs aggregated by tags. Tags can also be used to control access to a KMS key. For information about tagging KMS keys, see [Tags in Amazon KMS](tagging-keys.md) and [ABAC for Amazon 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 Amazon Web Services 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 Amazon 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 Amazon 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 Amazon Web Services accounts to use this KMS key for cryptographic operations. To do so, in the **Other Amazon Web Services accounts** section at the bottom of the page, choose **Add another Amazon Web Services account** and enter the Amazon Web Services account 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 Amazon KMS API
You can use the [CreateKey](https://docs.amazonaws.cn/kms/latest/APIReference/API_CreateKey.html) operation to create an HMAC KMS key. These examples use the [Amazon Command Line Interface (Amazon CLI)](http://www.amazonaws.cn/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\_VERIFY\_MAC, 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.amazonaws.cn/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 Amazon 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 Amazon Web Services 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
}
}
```