hmac.h File Reference

(6a7232711d)

Message authentication codes for the OpenTitan cryptography library. More...

#include "datatypes.h"
#include "hash.h"

Go to the source code of this file.

Data Structures
struct	otcrypto_hmac_context
	Generic hmac context. More...

Typedefs
typedef struct otcrypto_hmac_context	otcrypto_hmac_context_t
	Generic hmac context. More...

Functions
OT_WARN_UNUSED_RESULT 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...
OT_WARN_UNUSED_RESULT otcrypto_status_t	otcrypto_hmac_init (otcrypto_hmac_context_t *ctx, const otcrypto_blinded_key_t *key)
	Performs the INIT operation for HMAC. More...
OT_WARN_UNUSED_RESULT 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...
OT_WARN_UNUSED_RESULT otcrypto_status_t	otcrypto_hmac_final (otcrypto_hmac_context_t *const ctx, otcrypto_word32_buf_t tag)
	Performs the FINAL operation for HMAC. More...

Detailed Description

Message authentication codes for the OpenTitan cryptography library.

Supports message authentication based on either HMAC or KMAC.

Definition in file hmac.h.

---

Data Structure Documentation

otcrypto_hmac_context

struct otcrypto_hmac_context

Generic hmac context.

Representation is internal to the hmac implementation; initialize with otcrypto_hmac_init.

Definition at line 28 of file hmac.h.

Data Fields
uint32_t	data[kOtcryptoHashCtxStructWords]

Typedef Documentation

otcrypto_hmac_context_t

typedef struct otcrypto_hmac_context otcrypto_hmac_context_t

Generic hmac context.

Representation is internal to the hmac implementation; initialize with otcrypto_hmac_init.

Function Documentation

otcrypto_hmac()

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

Parameters

	key	Pointer to the blinded key struct with key shares.
	input_message	Input message to be hashed.
[out]	tag	Output authentication tag.

Returns

The result of the HMAC operation.

Definition at line 174 of file hmac.c.

otcrypto_hmac_final()

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

Parameters

	ctx	Pointer to the generic HMAC context struct.
[out]	tag	Output authentication tag.

Returns

Result of the HMAC final operation.

Definition at line 255 of file hmac.c.

otcrypto_hmac_init()

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

Parameters

[out]	ctx	Pointer to the generic HMAC context struct.
	key	Pointer to the blinded HMAC key struct.
	hash_mode	Hash function to use.

Returns

Result of the HMAC init operation.

Definition at line 207 of file hmac.c.

otcrypto_hmac_update()

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

Parameters

ctx	Pointer to the generic HMAC context struct.
input_message	Input message to be hashed.

Returns

Result of the HMAC update operation.

Definition at line 236 of file hmac.c.