HMAC keys in AWS KMS - AWS Key Management Service

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.

Tip

Best practices recommend that you limit the time during which any signing mechanism, including an HMAC, is effective. This deters an attack where the actor uses a signed message to establish validity repeatedly or long after the message is superseded. HMAC tags do not include a timestamp, but you can include a timestamp in the token or message to help you detect when its time to refresh the HMAC.

Supported cryptographic operations

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