From acaed5901b917a112d577cdba80534d66cd8a4eb Mon Sep 17 00:00:00 2001 From: Ryan Torok Date: Mon, 5 Feb 2024 19:28:40 +0000 Subject: [PATCH] [crypto] improve API descriptions for HMAC and KMAC Signed-off-by: Ryan Torok --- sw/device/lib/crypto/include/mac.h | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/sw/device/lib/crypto/include/mac.h b/sw/device/lib/crypto/include/mac.h index 705c0d4353bf76..08a95bf2c83063 100644 --- a/sw/device/lib/crypto/include/mac.h +++ b/sw/device/lib/crypto/include/mac.h @@ -51,8 +51,15 @@ typedef struct otcrypto_hmac_context { * mode. Only SHA-2 hash functions are supported. Other modes (e.g. SHA-3) are * not supported and will result in errors. * - * The caller should allocate 32 bytes (8 32-bit words) of space for the `tag` - * buffer and set its `len` field to 8. + * The caller should allocate the following amount of space for the `tag` + * buffer, depending on which hash algorithm is used: + * + * SHA-256: 32 bytes + * SHA-384: 48 bytes + * SHA-512: 64 bytes + * + * The caller should also set the `len` field of `tag` to the equivalent number + * of 32-bit words (e.g. 8 for SHA-256). * * @param key Pointer to the blinded key struct with key shares. * @param input_message Input message to be hashed. @@ -71,6 +78,11 @@ otcrypto_status_t otcrypto_hmac(const otcrypto_blinded_key_t *key, * through `customization_string` parameter. If no customization is desired it * can be empty. * + * The caller should set the `key_length` field of `key.config` to the number + * of bytes in the key. Only the following key sizes (in bytes) are supported: + * [16, 24, 32, 48, 64]. If any other size is given, the function will return + * an error. + * * The caller should allocate enough space in the `tag` buffer to hold * `required_output_len` bytes, rounded up to the nearest word, and then set * the `len` field of `tag` to the word length. If the word length is not long