HMAC keys in AWS KMS

Hash-Based Message Authentication Code (HMAC) KMS keys are symmetric keys that you use to generate and verify HMACs within AWS KMS. The unique key material associated with each HMAC KMS key provides the secret key that HMAC algorithms require. You can use an HMAC KMS key with the GenerateMac and VerifyMac operations to verify the integrity and authenticity of data within AWS KMS.

HMAC algorithms combine a cryptographic hash function and a shared secret key. They take a message and a secret key, such as the key material in an HMAC KMS key, and return a unique, fixed-size code or tag. If even one character of the message changes, or if the secret key is not identical, the resulting tag is entirely different. By requiring a secret key, HMAC also provides authenticity; it is impossible to generate an identical HMAC tag without the secret key. HMACs are sometimes called symmetric signatures, because they work like digital signatures, but use a single key for both signing and verification.

HMAC KMS keys and the HMAC algorithms that AWS KMS uses conform to industry standards defined in RFC 2104. The AWS KMS GenerateMac operation generates standard HMAC tags. HMAC KMS keys are generated in AWS KMS hardware security modules that are certified under the FIPS 140-2 Cryptographic Module Validation Program (except in China (Beijing) and China (Ningxia) Regions) and never leave AWS KMS unencrypted. To use an HMAC KMS key, you must call AWS KMS.

You can use HMAC KMS keys to determine the authenticity of a message, such as a JSON Web Token (JWT), tokenized credit card information, or a submitted password. They can also be used as secure Key Derivation Functions (KDFs), especially in applications that require deterministic keys.

HMAC KMS keys provide an advantage over HMACs from application software because the key material is generated and used entirely within AWS KMS, subject to the access controls that you set on the key.

Authorized users can create, manage, and use the HMAC KMS keys in your AWS account. This includes enabling and disabling keys, setting and changing aliases and tags, and scheduling deletion of HMAC KMS keys. You can also control access to HMAC KMS keys using key policies, IAM policies, and grants. You can audit all operations that use or manage your HMAC KMS keys within AWS in AWS CloudTrail logs. You can create HMAC KMS keys with imported key material. You can also create HMAC multi-Region KMS keys that behave like copies of the same HMAC KMS key in multiple AWS Regions.

HMAC KMS keys support only the GenerateMac and VerifyMac cryptographic operations. You cannot use HMAC KMS keys to encrypt data or sign messages, or use any other type of KMS key in HMAC operations. When you use the GenerateMac operation, you supply a message of up to 4,096 bytes, an HMAC KMS key, and the MAC algorithm that is compatible with the HMAC key spec, and GenerateMac computes the HMAC tag. To verify an HMAC tag, you must supply the HMAC tag, and the same message, HMAC KMS key, and MAC algorithm that GenerateMac used to compute the original HMAC tag. The VerifyMac operation computes the HMAC tag and verifies that it is identical to the supplied HMAC tag. If the input and computed HMAC tags are not identical, verification fails.

HMAC KMS keys do not support automatic key rotation and you cannot create an HMAC KMS key in a custom key store.

If you are creating a KMS key to encrypt data in an AWS service, use a symmetric encryption key. You cannot use an HMAC KMS key.

Regions

HMAC KMS keys are supported in all AWS Regions that AWS KMS supports.

Learn more

Key specs for HMAC KMS keys

AWS KMS supports symmetric HMAC keys in varying lengths. The key spec that you select can depend on your security, regulatory, or business requirements. The length of the key determines the MAC algorithm that is used in GenerateMac and VerifyMac operations. In general, longer keys are more secure. Use the longest key that is practical for your use case.