(ae68723)

HMAC Device Interface Functions More...

#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_hmac_autogen.h"

Go to the source code of this file.

Data Structures
struct	dif_hmac_transaction
	Configuration for a single HMAC Transaction. More...

struct	dif_hmac_digest
	A typed representation of the HMAC digest. More...

Typedefs
typedef enum dif_hmac_mode	dif_hmac_mode_t
	Supported HMAC modes of operation.

typedef enum dif_hmac_endianness	dif_hmac_endianness_t
	Supported byte endienness options.

typedef enum dif_hmac_key_length	dif_hmac_key_length_t
	HMAC key length in bits.

typedef enum dif_sha2_digest_size	dif_sha2_digest_size_t
	SHA-2 digest size.

typedef struct dif_hmac_transaction	dif_hmac_transaction_t
	Configuration for a single HMAC Transaction.

typedef struct dif_hmac_digest	dif_hmac_digest_t
	A typed representation of the HMAC digest.

Enumerations
enum	dif_hmac_mode { kDifHmacModeHmac = 0, kDifHmacModeSha256 }
	Supported HMAC modes of operation. More...

enum	dif_hmac_endianness { kDifHmacEndiannessBig = 0, kDifHmacEndiannessLittle }
	Supported byte endienness options. More...

enum	dif_hmac_key_length { kDifHMACKey128 = 1, kDifHMACKey256 = (1 << 1), kDifHMACKey384 = (1 << 2), kDifHMACKey512 = (1 << 3), kDifHMACKey1024 = (1 << 4) }
	HMAC key length in bits.

enum	dif_sha2_digest_size { kDifSHA256 = (1 << 1), kDifSHA384 = (1 << 2), kDifSHA512 = (1 << 3) }
	SHA-2 digest size.

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_hmac_mode_hmac_start (const dif_hmac_t hmac, const uint8_t key, const dif_hmac_transaction_t config)
	Resets the HMAC engine and readies it to receive a new message to process an HMAC digest. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_hmac_mode_sha256_start (const dif_hmac_t *hmac, const dif_hmac_transaction_t config)
	Resets the HMAC engine and readies it to receive a new message to process a SHA256 digest. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_hmac_fifo_push (const dif_hmac_t hmac, const void data, size_t len, size_t *bytes_sent)
	Attempts to send `len` bytes from the buffer pointed to by `data` to the device described by `hmac`. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_hmac_fifo_count_entries (const dif_hmac_t hmac, uint32_t num_entries)
	Retrieves the number of entries in the HMAC FIFO. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_hmac_get_message_length (const dif_hmac_t hmac, uint64_t msg_len)
	Retrieves the number of bits in the loaded HMAC device. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_hmac_process (const dif_hmac_t *hmac)
	Attempts to run HMAC or SHA256 depending on the mode `hmac` was initialized in. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_hmac_finish (const dif_hmac_t hmac, bool disable_after_done, dif_hmac_digest_t digest)
	Attempts to finish a transaction started with `dif_hmac_mode_*_start`, and reads the final digest in the buffer referenced by `digest`. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_hmac_wipe_secret (const dif_hmac_t hmac, uint32_t entropy, dif_hmac_digest_t digest)
	Randomizes internal secret registers on the HMAC device. More...

Detailed Description

HMAC Device Interface Functions

Definition in file dif_hmac.h.

Data Structure Documentation

◆ dif_hmac_transaction

struct dif_hmac_transaction

Configuration for a single HMAC Transaction.

Definition at line 69 of file dif_hmac.h.

Data Fields
dif_hmac_endianness_t	digest_endianness	Byte endianness for reads from the digest.
dif_sha2_digest_size_t	digest_size	SHA-2 digest size.
dif_hmac_key_length_t	key_length	HMAC key length.
dif_hmac_endianness_t	message_endianness	Byte endianness for writes to the FIFO.

◆ dif_hmac_digest

struct dif_hmac_digest

A typed representation of the HMAC digest.

Definition at line 83 of file dif_hmac.h.

Data Fields
uint32_t	digest[8]

Enumeration Type Documentation

◆ dif_hmac_endianness

enum dif_hmac_endianness

Supported byte endienness options.

Enumerator
kDifHmacEndiannessBig	Big endian byte ordering.
kDifHmacEndiannessLittle	Little endian byte ordering.

Definition at line 39 of file dif_hmac.h.

◆ dif_hmac_mode

enum dif_hmac_mode

Supported HMAC modes of operation.

Enumerator
kDifHmacModeHmac	The HMAC mode.
kDifHmacModeSha256	The SHA256-only mode.

Definition at line 29 of file dif_hmac.h.

Function Documentation

◆ dif_hmac_fifo_count_entries()

OT_WARN_UNUSED_RESULT dif_result_t dif_hmac_fifo_count_entries	(	const dif_hmac_t *	hmac,
		uint32_t *	num_entries
	)

Retrieves the number of entries in the HMAC FIFO.

These entries may be semi-arbitrary in length; this function should not be used to calculate message length.

Parameters

	hmac	The HMAC device to get the FIFO depth for.
[out]	num_entries	The number of entries in the FIFO.

Returns: The result of the operation.

Definition at line 211 of file dif_hmac.c.

◆ dif_hmac_fifo_push()

OT_WARN_UNUSED_RESULT dif_result_t dif_hmac_fifo_push	(	const dif_hmac_t *	hmac,
		const void *	data,
		size_t	len,
		size_t *	bytes_sent
	)

Attempts to send len bytes from the buffer pointed to by data to the device described by hmac.

This function will send to the message FIFO until the FIFO fills up or len bytes have been sent.

In the event that the FIFO fills up before len bytes have been sent this function will return a kDifHmacFifoFull error. In this case it is valid to call this function again by advancing data by len - |*bytes_sent| bytes. It may be desirable to wait for space to free up on the FIFO before issuing subsequent calls to this function, but it is not strictly necessary. The number of entries in the FIFO can be queried with dif_hmac_fifo_count_entries().

data must point to an allocated buffer of at least length len.

Parameters

	hmac	The HMAC device to send to.
	data	A contiguous buffer to copy from.
	len	The length of the buffer to copy from.
[out]	bytes_sent	The number of bytes sent to the FIFO (optional).

Returns: The result of the operation.

Definition at line 171 of file dif_hmac.c.

◆ dif_hmac_finish()

OT_WARN_UNUSED_RESULT dif_result_t dif_hmac_finish	(	const dif_hmac_t *	hmac,
		bool	disable_after_done,
		dif_hmac_digest_t *	digest
	)

Attempts to finish a transaction started with dif_hmac_mode_*_start, and reads the final digest in the buffer referenced by digest.

This queries the INTR_STATE register to check if the HMAC is finished, and will acknowledge a hmac_done interrupt. If that register is not pending, then this function assumes HMAC is still processing and will return kDifHmacErrorDigestProcessing.

digest must reference an allocated, contiguous, 32-byte buffer. This buffer shall also be 4-byte aligned. This is all consistent with the platform requirements for size and alignment requirements of dif_hmac_digest_t.

Parameters

	hmac	The HMAC device to read the digest from.
	disable_after_done	If true, the HMAC and SHA256 datapaths will be disabled after the digest is read, clearing the digest registers.
[out]	digest	A contiguous 32-byte, 4-byte aligned buffer for the digest.

Returns: The result of the operation.

Definition at line 259 of file dif_hmac.c.

◆ dif_hmac_get_message_length()

OT_WARN_UNUSED_RESULT dif_result_t dif_hmac_get_message_length	(	const dif_hmac_t *	hmac,
		uint64_t *	msg_len
	)

Retrieves the number of bits in the loaded HMAC device.

dif_hmac_fifo_count_entries() should be called before this function to ensure the FIFO is empty, as any bits in the FIFO are not counted in msg_len.

Parameters

	hmac	The HMAC device to get the message length for.
[out]	msg_len	The number of bits in the HMAC message.

Returns: The result of the operation.

Definition at line 222 of file dif_hmac.c.

◆ dif_hmac_mode_hmac_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_hmac_mode_hmac_start	(	const dif_hmac_t *	hmac,
		const uint8_t *	key,
		const dif_hmac_transaction_t	config
	)

Resets the HMAC engine and readies it to receive a new message to process an HMAC digest.

This function causes the HMAC engine to start its operation. After a successful call to this function, |dif_hmac_fifo_push()| can be called to write the message for HMAC processing.

This function should be called with a valid key that references a 32-byte, contiguous, readable region where the key may be copied from. Passing a NULL key reference will skip loading of the key. This is only expected to be used to test scenarios where the key is not loaded.

Parameters

hmac	The HMAC device to start HMAC operation for.
key	The 256-bit HMAC key.
config	The per-transaction configuration.

Returns: The result of the operation.

Definition at line 96 of file dif_hmac.c.

◆ dif_hmac_mode_sha256_start()

OT_WARN_UNUSED_RESULT dif_result_t dif_hmac_mode_sha256_start	(	const dif_hmac_t *	hmac,
		const dif_hmac_transaction_t	config
	)

Resets the HMAC engine and readies it to receive a new message to process a SHA256 digest.

This function causes the HMAC engine to start its operation. After a successful call to this function, |dif_hmac_fifo_push()| can be called to write the message for SHA256 processing.

Parameters

hmac	The HMAC device to start SHA256 operation for.
config	The per-transaction configuration.

Returns: The result of the operation.

Definition at line 139 of file dif_hmac.c.

◆ dif_hmac_process()

OT_WARN_UNUSED_RESULT dif_result_t dif_hmac_process ( const dif_hmac_t * hmac )

Attempts to run HMAC or SHA256 depending on the mode hmac was initialized in.

Calls to this function always succeed and return without blocking. The caller can use dif_hmac_check_state() to check for errors and for the DIF_HMAC_DONE status before reading the digest with dif_hmac_digest_read().

Parameters

hmac	The HMAC device to initiate the run on.

Returns: The result of the operation.

Definition at line 237 of file dif_hmac.c.

◆ dif_hmac_wipe_secret()

OT_WARN_UNUSED_RESULT dif_result_t dif_hmac_wipe_secret	(	const dif_hmac_t *	hmac,
		uint32_t	entropy,
		dif_hmac_digest_t *	digest
	)

Randomizes internal secret registers on the HMAC device.

This includes the key, hash value, and internal state machine. The value of entropy will be used to "randomize" the internal state of the HMAC device. See the HMAC IP documentation for more information: hw/ip/hmac/doc.

Parameters

	hmac	The HMAC device to clobber state on.
	entropy	A source of randomness to write to the HMAC internal state.
[out]	digest	The resulting digest from the wipe operation.

Returns: The result of the operation.

Definition at line 314 of file dif_hmac.c.

(ae68723)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_hmac_transaction

◆ dif_hmac_digest

Enumeration Type Documentation

◆ dif_hmac_endianness

◆ dif_hmac_mode

Function Documentation

◆ dif_hmac_fifo_count_entries()

◆ dif_hmac_fifo_push()

◆ dif_hmac_finish()

◆ dif_hmac_get_message_length()

◆ dif_hmac_mode_hmac_start()

◆ dif_hmac_mode_sha256_start()

◆ dif_hmac_process()

◆ dif_hmac_wipe_secret()