Creating HMAC KMS keys - AWS Key Management Service

Creating HMAC KMS keys

You can create HMAC KMS keys in the AWS KMS console, by using the CreateKey API, or by using an AWS CloudFormation template.

AWS KMS supports multiple key specs for HMAC KMS keys. 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.

If you are creating a KMS key to encrypt data in an AWS service, use a symmetric encryption KMS key. AWS services that integrate with AWS KMS do not support asymmetric KMS keys or HMAC KMS keys. For help with creating a symmetric encryption KMS key, see Creating keys.

Note

HMAC KMS keys are not supported in all AWS Regions. For a list of Regions in which HMAC KMS keys are supported, see HMAC Regions.

Learn more

Creating HMAC KMS keys (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.

  2. To change the AWS Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. Choose Create key.

  5. For Key type, choose Symmetric.

    HMAC KMS keys are symmetric. You use the same key to generate and verify HMAC tags.

  6. 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. HMAC KMS keys are not supported in all AWS Regions. For a list of Regions in which HMAC KMS keys are supported, see HMAC Regions.

  7. 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.

  8. To create a multi-Region primary HMAC key, in Advanced options, choose Multi-Region key. The shared properties that you define for this KMS key, such as its key type and key usage, will be shared with its replica keys. For details, see Creating multi-Region 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.

  9. Choose Next.

  10. Enter 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.

    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 operation, but you can use the console or the CreateAlias operation to create an alias for an existing KMS key. For details, see Using aliases.

  11. (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 is Pending Deletion or Pending Replica Deletion. To add, change, or delete the description of an existing customer managed key, edit the description in the AWS Management Console or use the UpdateKeyDescription operation.

  12. (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 Tagging keys and ABAC for AWS KMS.

  13. Choose Next.

  14. Select the IAM users and roles that can administer the KMS key.

    Note

    IAM policies can give other IAM users and roles permission to manage the KMS key.

  15. (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.

  16. Choose Next.

  17. Select the IAM users and roles that can use the KMS key for cryptographic operations.

    Note

    The AWS account (root user) has full permissions by default. As a result, any IAM policies can also give users and roles permission to use the KMS key for cryptographic operations.

  18. (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.

  19. Choose Next.

  20. Review the key settings that you chose. You can still go back and change all settings.

  21. Choose Finish to create the HMAC KMS key.

Creating HMAC KMS keys (AWS KMS API)

You can use the CreateKey operation to create an HMAC KMS key. These examples use the AWS Command Line Interface (AWS 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 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 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. HMAC KMS keys are not supported in all AWS Regions. For a list of Regions in which HMAC KMS keys are supported, see HMAC Regions.

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 } }