 |
Software APIs
|
|
Software APIs
|
Message authentication codes for the OpenTitan cryptography library. More...
Go to the source code of this file.
Data Structures | |
| struct | otcrypto_hmac_context |
| Generic hmac context. More... | |
Typedefs | |
| typedef enum otcrypto_kmac_mode | otcrypto_kmac_mode_t |
| Enum to define KMAC mode. More... | |
| typedef struct otcrypto_hmac_context | otcrypto_hmac_context_t |
| Generic hmac context. More... | |
Enumerations | |
| enum | otcrypto_kmac_mode { kOtcryptoKmacModeKmac128 = 0x336, kOtcryptoKmacModeKmac256 = 0xec4 } |
| Enum to define KMAC mode. More... | |
Functions | |
| otcrypto_status_t | otcrypto_hmac (const otcrypto_blinded_key_t *key, otcrypto_const_byte_buf_t input_message, otcrypto_word32_buf_t tag) |
| Performs the HMAC function on the input data. More... | |
| otcrypto_status_t | otcrypto_kmac (const otcrypto_blinded_key_t *key, otcrypto_const_byte_buf_t input_message, otcrypto_kmac_mode_t kmac_mode, otcrypto_const_byte_buf_t customization_string, size_t required_output_len, otcrypto_word32_buf_t tag) |
| Performs the KMAC function on the input data. More... | |
| otcrypto_status_t | otcrypto_hmac_init (otcrypto_hmac_context_t *ctx, const otcrypto_blinded_key_t *key) |
| Performs the INIT operation for HMAC. More... | |
| otcrypto_status_t | otcrypto_hmac_update (otcrypto_hmac_context_t *const ctx, otcrypto_const_byte_buf_t input_message) |
| Performs the UPDATE operation for HMAC. More... | |
| otcrypto_status_t | otcrypto_hmac_final (otcrypto_hmac_context_t *const ctx, otcrypto_word32_buf_t tag) |
| Performs the FINAL operation for HMAC. More... | |
Message authentication codes for the OpenTitan cryptography library.
Supports message authentication based on either HMAC or KMAC.
Definition in file mac.h.
| struct otcrypto_hmac_context |
Generic hmac context.
Representation is internal to the hmac implementation; initialize with otcrypto_hmac_init.
| Data Fields | ||
|---|---|---|
| uint32_t | data[kOtcryptoHashCtxStructWords] | |
| typedef struct otcrypto_hmac_context otcrypto_hmac_context_t |
Generic hmac context.
Representation is internal to the hmac implementation; initialize with otcrypto_hmac_init.
| typedef enum otcrypto_kmac_mode otcrypto_kmac_mode_t |
Enum to define KMAC mode.
Values are hardened.
| enum otcrypto_kmac_mode |
| otcrypto_status_t otcrypto_hmac | ( | const otcrypto_blinded_key_t * | key, |
| otcrypto_const_byte_buf_t | input_message, | ||
| otcrypto_word32_buf_t | tag | ||
| ) |
Performs the HMAC function on the input data.
This function computes the HMAC function on the input_message using the key and returns a tag. The key should be at least as long as the digest for the chosen hash function. The hash function is determined by the key 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 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).
| key | Pointer to the blinded key struct with key shares. | |
| input_message | Input message to be hashed. | |
| [out] | tag | Output authentication tag. |
| otcrypto_status_t otcrypto_hmac_final | ( | otcrypto_hmac_context_t *const | ctx, |
| otcrypto_word32_buf_t | tag | ||
| ) |
Performs the FINAL operation for HMAC.
The final operation processes the remaining partial blocks, computes the final authentication code and copies it to the tag parameter.
otcrypto_hmac_update should be called before calling this function.
The caller should allocate space for the tag buffer, (the length should match the hash function digest size), and set the length of expected output in the len field of tag. If the user-set length and the output length does not match, an error message will be returned.
| ctx | Pointer to the generic HMAC context struct. | |
| [out] | tag | Output authentication tag. |
| otcrypto_status_t otcrypto_hmac_init | ( | otcrypto_hmac_context_t * | ctx, |
| const otcrypto_blinded_key_t * | key | ||
| ) |
Performs the INIT operation for HMAC.
Initializes the HMAC context. The key should be at least as long as the digest for the chosen hash function. The hash function is determined by the key mode. Only SHA-2 hash functions are are supported. Other modes (e.g. SHA-3) are not supported and will result in errors.
| [out] | ctx | Pointer to the generic HMAC context struct. |
| key | Pointer to the blinded HMAC key struct. | |
| hash_mode | Hash function to use. |
| otcrypto_status_t otcrypto_hmac_update | ( | otcrypto_hmac_context_t *const | ctx, |
| otcrypto_const_byte_buf_t | input_message | ||
| ) |
Performs the UPDATE operation for HMAC.
The update operation processes the input_message using the selected compression function. The intermediate state is stored in the HMAC context ctx. Any partial data is stored back in the context and combined with the subsequent bytes.
otcrypto_hmac_init should be called before calling this function.
| ctx | Pointer to the generic HMAC context struct. |
| input_message | Input message to be hashed. |
| otcrypto_status_t otcrypto_kmac | ( | const otcrypto_blinded_key_t * | key, |
| otcrypto_const_byte_buf_t | input_message, | ||
| otcrypto_kmac_mode_t | kmac_mode, | ||
| otcrypto_const_byte_buf_t | customization_string, | ||
| size_t | required_output_len, | ||
| otcrypto_word32_buf_t | tag | ||
| ) |
Performs the KMAC function on the input data.
This function computes the KMAC on the input_message using the key and returns a tag of required_output_len. The customization string is passed through customization_string parameter. If no customization is desired it can be be left empty (by settings its data to NULL and length to 0).
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 enough to hold required_output_len bytes, then the function will return an error.
| key | Pointer to the blinded key struct with key shares. | |
| input_message | Input message to be hashed. | |
| mac_mode | Required KMAC mode. | |
| customization_string | Customization string. | |
| required_output_len | Required output length, in bytes. | |
| [out] | tag | Output authentication tag. |