HSU
[UMAC]

Structures and Helper functions to use the Hardware Security Unit. More...

Collaboration diagram for HSU:

Defines
#define	HSU_SUPPORT(m) (hsu_status & HSU_##m##_BIT)
	True if HSU support feature `m`, false otherwise.
#define	HSU_LOCK()
	Macro unused.
#define	HSU_UNLOCK()
	Macro unused.
#define	HSU_MODE(m) (hsu_mode(HSU_MODE_##m))
	HSU mode value for control register.
#define	HSU_SHA_MAX_LEN 512
	Maximum length in bytes for all input vectors.
Enumerations
enum	hsu_modes { HSU_MODE_TKIP_MIC = 0, HSU_MODE_AES_128_CMAC = 1, HSU_MODE_IP_CHK = 2, HSU_MODE_SHA_1 = 3, HSU_MODE_SHA_256 = 4, HSU_MODE_SHA_224 = 5, HSU_MODE_HMAC_SHA1 = 6, HSU_MODE_HMAC_SHA256 = 7, HSU_MODE_HMAC_SHA224 = 8, HSU_MODE_SHA_512 = 9, HSU_MODE_SHA_384 = 10, HSU_MODE_HMAC_SHA512 = 11, HSU_MODE_HMAC_SHA384 = 12 }
	Operation modes supported by HSU.
Functions
__INLINE uint32_t	hsu_mode (int mode)
void	hsu_init (void)
	Checks if HSU is available.
uint64_t	hsu_aes_cmac (uint32_t *key, int nb_elem, uint32_t addr[], int len[])
	Computes AES-CMAC on several vectors using HSU.
static bool	hsu_michael (uint32_t ctrl, struct mic_calc *mic_calc, uint32_t data, uint32_t data_len)
	Computes Michael MIC on the provided buffer using HSU.
bool	hsu_michael_init (struct mic_calc mic_calc, uint32_t mic_key, uint32_t *aad)
	Initializes TKIP MIC computation using HSU.
bool	hsu_michael_calc (struct mic_calc *mic_calc, uint32_t data, uint32_t data_len)
	Continues TKIP MIC computation using HSU.
bool	hsu_michael_end (struct mic_calc *mic_calc)
	Ends TKIP MIC computation using HSU.
bool	hsu_ip_checksum (uint32_t addr, uint16_t len, uint16_t *checksum)
	Computes the IP checksum on the buffer provided.
static bool	hsu_sha_x (uint32_t hsu_sha_mode, int nb_elem, const uint8_t addr[], const size_t len, int sha_size, uint32_t *sha)
	Generic function for SHA-X computation.
bool	hsu_sha1 (int nb_elem, const uint8_t addr[], const size_t len, uint32_t *sha)
	Computes the SHA1 on the buffers provided.
bool	hsu_sha224 (int nb_elem, const uint8_t addr[], const size_t len, uint32_t *sha)
	Computes the SHA224 on the buffers provided.
bool	hsu_sha256 (int nb_elem, const uint8_t addr[], const size_t len, uint32_t *sha)
	Computes the SHA256 on the buffers provided.
bool	hsu_sha384 (int nb_elem, const uint8_t addr[], const size_t len, uint32_t *sha)
	Computes the SHA384 on the buffers provided.
bool	hsu_sha512 (int nb_elem, const uint8_t addr[], const size_t len, uint32_t *sha)
	Computes the SHA512 on the buffers provided.
bool	hsu_hmac_sha_x (uint32_t hsu_hmac_mode, const uint8_t key[], const size_t key_len, int nb_elem, const uint8_t addr[], const size_t len, int mac_size, uint32_t *mac)
	Generic function for HMAC-SHA-X computation.
bool	hsu_hmac_sha1 (const uint8_t key[], const size_t key_len, int nb_elem, const uint8_t addr[], const size_t len, uint32_t *mac)
	Computes the HMAC-SHA1 on the buffers provided.
bool	hsu_hmac_sha224 (const uint8_t key[], const size_t key_len, int nb_elem, const uint8_t addr[], const size_t len, uint32_t *mac)
	Computes the HMAC-SHA224 on the buffers provided.
bool	hsu_hmac_sha256 (const uint8_t key[], const size_t key_len, int nb_elem, const uint8_t addr[], const size_t len, uint32_t *mac)
	Computes the HMAC-SHA256 on the buffers provided.
bool	hsu_hmac_sha384 (const uint8_t key[], const size_t key_len, int nb_elem, const uint8_t addr[], const size_t len, uint32_t *mac)
	Computes the HMAC-SHA384 on the buffers provided.
bool	hsu_hmac_sha512 (const uint8_t key[], const size_t key_len, int nb_elem, const uint8_t addr[], const size_t len, uint32_t *mac)
	Computes the HMAC-SHA512 on the buffers provided.
Variables
static uint32_t	hsu_status = 0
	List features supported by HSU.
static uint8_t	hsu_sha_buf [HSU_SHA_MAX_LEN]
	Intermediate buffer to concatenate input vectors.

Detailed Description

Structures and Helper functions to use the Hardware Security Unit.

Function Documentation

uint64_t hsu_aes_cmac	(	uint32_t *	key,
		int	nb_elem,
		uint32_t	addr[],
		int	len[]
	)

Computes AES-CMAC on several vectors using HSU.

All vectors MUST be located in SHARED MEMORY.

Parameters:

`[in]`	key	Key (16 bytes)
`[in]`	nb_elem	Number of element in `addr` and `len` tables.
`[in]`	addr	Table of input vector addresses (HW address)
`[in]`	len	Table of input vector length (in bytes)

Returns:: AES_CMAC value of all vectors concatenated.

bool hsu_hmac_sha1	(	const uint8_t	key[],
		const size_t	key_len,
		int	nb_elem,
		const uint8_t *	addr[],
		const size_t *	len,
		uint32_t *	mac
	)

Computes the HMAC-SHA1 on the buffers provided.

For this function key and data buffers doesn't have to be located in Shared memory but the total size of buffers must be lower than HSU_SHA_MAX_LEN.

Parameters:

`[in]`	key	Key to use to compute the MAC. CPU address is expected.
`[in]`	key_len	Length, in bytes, of key buffer.
`[in]`	nb_elem	Number of buffer in `addr`.
`[in]`	addr	The address of the data buffer on which the MAC is computed CPU address is expected.
`[in]`	len	Length, in bytes, of each element of `addr`.
`[out]`	mac	The computed MAC. MUST be, at least, 20 bytes long

Returns:: true if the MAC was correctly computed, false otherwise

bool hsu_hmac_sha224	(	const uint8_t	key[],
		const size_t	key_len,
		int	nb_elem,
		const uint8_t *	addr[],
		const size_t *	len,
		uint32_t *	mac
	)

Computes the HMAC-SHA224 on the buffers provided.

For this function key and data buffers doesn't have to be located in Shared memory but the total size of buffers must be lower than HSU_SHA_MAX_LEN.

Parameters:

`[in]`	key	Key to use to compute the MAC. CPU address is expected.
`[in]`	key_len	Length, in bytes, of key buffer.
`[in]`	nb_elem	Number of buffer in `addr`.
`[in]`	addr	The address of the data buffer on which the MAC is computed CPU address is expected.
`[in]`	len	Length, in bytes, of each element of `addr`.
`[out]`	mac	The computed MAC. MUST be, at least, 28 bytes long

Returns:: true if the MAC was correctly computed, false otherwise

bool hsu_hmac_sha256	(	const uint8_t	key[],
		const size_t	key_len,
		int	nb_elem,
		const uint8_t *	addr[],
		const size_t *	len,
		uint32_t *	mac
	)

Computes the HMAC-SHA256 on the buffers provided.

For this function key and data buffers doesn't have to be located in Shared memory but the total size of buffers must be lower than HSU_SHA_MAX_LEN.

Parameters:

`[in]`	key	Key to use to compute the MAC. CPU address is expected.
`[in]`	key_len	Length, in bytes, of key buffer.
`[in]`	nb_elem	Number of buffer in `addr`.
`[in]`	addr	The address of the data buffer on which the MAC is computed CPU address is expected.
`[in]`	len	Length, in bytes, of each element of `addr`.
`[out]`	mac	The computed MAC. MUST be, at least, 32 bytes long

Returns:: true if the MAC was correctly computed, false otherwise

bool hsu_hmac_sha384	(	const uint8_t	key[],
		const size_t	key_len,
		int	nb_elem,
		const uint8_t *	addr[],
		const size_t *	len,
		uint32_t *	mac
	)

Computes the HMAC-SHA384 on the buffers provided.

For this function key and data buffers doesn't have to be located in Shared memory but the total size of buffers must be lower than HSU_SHA_MAX_LEN.

Parameters:

`[in]`	key	Key to use to compute the MAC. CPU address is expected.
`[in]`	key_len	Length, in bytes, of key buffer.
`[in]`	nb_elem	Number of buffer in `addr`.
`[in]`	addr	The address of the data buffer on which the MAC is computed CPU address is expected.
`[in]`	len	Length, in bytes, of each element of `addr`.
`[out]`	mac	The computed MAC. MUST be, at least, 48 bytes long

Returns:: true if the MAC was correctly computed, false otherwise

bool hsu_hmac_sha512	(	const uint8_t	key[],
		const size_t	key_len,
		int	nb_elem,
		const uint8_t *	addr[],
		const size_t *	len,
		uint32_t *	mac
	)

Computes the HMAC-SHA512 on the buffers provided.

For this function key and data buffers doesn't have to be located in Shared memory but the total size of buffers must be lower than HSU_SHA_MAX_LEN.

Parameters:

`[in]`	key	Key to use to compute the MAC. CPU address is expected.
`[in]`	key_len	Length, in bytes, of key buffer.
`[in]`	nb_elem	Number of buffer in `addr`.
`[in]`	addr	The address of the data buffer on which the MAC is computed CPU address is expected.
`[in]`	len	Length, in bytes, of each element of `addr`.
`[out]`	mac	The computed MAC. MUST be, at least, 64 bytes long

Returns:: true if the MAC was correctly computed, false otherwise

bool hsu_hmac_sha_x	(	uint32_t	hsu_hmac_mode,
		const uint8_t	key[],
		const size_t	key_len,
		int	nb_elem,
		const uint8_t *	addr[],
		const size_t *	len,
		int	mac_size,
		uint32_t *	mac
	)

Generic function for HMAC-SHA-X computation.

Concatenate input vectors in the temporary buffer hsu_sha_buf and then use HSU to compute the requested MAC. Caller must ensure that HSU supports the requested mode and that the ouput buffer is big enough.

Parameters:

`[in]`	hsu_hmac_mode	Mode to configure for HSU
`[in]`	key	Key to use to compute the MAC.
`[in]`	key_len	Length, in bytes, of key buffer.
`[in]`	nb_elem	Number of buffer in `addr`.
`[in]`	addr	TAble of input vectors.
`[in]`	len	Length, in bytes, of each element of `addr`.
`[in]`	mac_size	Size, in 32bits words, of the output MAC.
`[out]`	mac	The computed MAC.

Returns:: true if the MAC was correctly computed, false otherwise

Definition at line 424 of file hsu.c.

References CPU2HW, HSU_LOCK, hsu_sha_buf, HSU_SHA_MAX_LEN, HSU_UNLOCK, and TRACE_LMAC.

void hsu_init ( void )

Checks if HSU is available.

It updates internal variable hsu_status. If HSU is not available and NX_HSU is defined to 1 then hsu functions will immediately return and software implementation will be used instead. If HSU is not available and NX_HSU is set to 2, then an error is generated.

bool hsu_ip_checksum	(	uint32_t	addr,
		uint16_t	len,
		uint16_t *	checksum
	)

Computes the IP checksum on the buffer provided.

Parameters:

`[in]`	addr	The address of the data buffer on which the checksum is computed
`[in]`	len	Length on which the checksum is computed
`[out]`	checksum	The computed checksum

Returns:: true if the checksum was correctly computed, false otherwise

static bool hsu_michael	(	uint32_t	ctrl,
		struct mic_calc *	mic_calc,
		uint32_t	data,
		uint32_t	data_len
	)			`[static]`

Computes Michael MIC on the provided buffer using HSU.

Use HSU to compute Michael MIC. Temporary MIC and remaining byts are restore from mic_calc. After computation MIC and remaining bytes are saved in mic_calc.

Parameters:

`[in]`	ctrl	Value of HSU control registr to use.
`[in,out]`	mic_calc	Pointer to Mic structure
`[in]`	data	HW address of the data buffer. Must be in SHARED RAM
`[in]`	data_len	Length, in bytes, of the data buffer

Returns:: true if computation has been done by HSU, false otherwise

Definition at line 195 of file hsu.c.

References ASSERT_WARN, HSU_LOCK, HSU_SUPPORT, HSU_UNLOCK, HW2CPU, mic_calc::last_m_i, mic_calc::mic_key_least, mic_calc::mic_key_most, and TST_SHRAM_PTR.

bool hsu_michael_calc	(	struct mic_calc *	mic_calc,
		uint32_t	data,
		uint32_t	data_len
	)

Continues TKIP MIC computation using HSU.

Continue MIC computation with the provided data.

Parameters:

`[in,out]`	mic_calc	Pointer to Mic structure
`[in]`	data	Address of the data buffer (HW address) It must be located in SHARED RAM.
`[in]`	data_len	Length, in bytes, of the data buffer

Returns:: true if computation has been done by HSU, false otherwise

bool hsu_michael_end ( struct mic_calc * mic_calc )

Ends TKIP MIC computation using HSU.

Ends TKIP computation by adding padding data

Parameters:

[in,out] mic_calc Pointer to Mic structure that will be initialize

Returns:: true if computation has been done by HSU, false otherwise

bool hsu_michael_init	(	struct mic_calc *	mic_calc,
		uint32_t *	mic_key,
		uint32_t *	aad
	)

Initializes TKIP MIC computation using HSU.

Parameters:

`[out]`	mic_calc	Pointer to Mic structure that will be initialize
`[in]`	mic_key	Key to use for MIC computation
`[in]`	aad	Additional Authentication Data vector (CPU address, 16 bytes long) It must be located in SHARED RAM.

Returns:: true if computation has been done by HSU, false otherwise

__INLINE uint32_t hsu_mode ( int mode )

Parameters:

[in] mode HSU mode (hsu_modes)

Returns:: control register value for requested mode

Definition at line 87 of file hsu.c.

References hsu_status.

bool hsu_sha1	(	int	nb_elem,
		const uint8_t *	addr[],
		const size_t *	len,
		uint32_t *	sha
	)

Computes the SHA1 on the buffers provided.