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

For this function 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]` | nb_elem | Number of buffer in `addr`.
  `[in]` | addr | The address of the data buffer on which the hash is computed CPU address is expected.
  `[in]` | len | Length, in bytes, of each element of `addr`.
  `[out]` | sha | The computed hash. MUST be, at least, 20 bytes long

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

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

Computes the SHA224 on the buffers provided.

For this function 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]` | nb_elem | Number of buffer in `addr`.
  `[in]` | addr | The address of the data buffer on which the hash is computed CPU address is expected.
  `[in]` | len | Length, in bytes, of each element of `addr`.
  `[out]` | sha | The computed hash. MUST be, at least, 28 bytes long

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

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

Computes the SHA256 on the buffers provided.

For this function 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]` | nb_elem | Number of buffer in `addr`.
  `[in]` | addr | The address of the data buffer on which the hash is computed CPU address is expected.
  `[in]` | len | Length, in bytes, of each element of `addr`.
  `[out]` | sha | The computed hash. MUST be, at least, 32 bytes long

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

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

Computes the SHA384 on the buffers provided.

For this function 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]` | nb_elem | Number of buffer in `addr`.
  `[in]` | addr | The address of the data buffer on which the hash is computed CPU address is expected.
  `[in]` | len | Length, in bytes, of each element of `addr`.
  `[out]` | sha | The computed hash. MUST be, at least, 48 bytes long

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

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

Computes the SHA512 on the buffers provided.

For this function 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]` | nb_elem | Number of buffer in `addr`.
  `[in]` | addr | The address of the data buffer on which the hash is computed CPU address is expected.
  `[in]` | len | Length, in bytes, of each element of `addr`.
  `[out]` | sha | The computed hash. MUST be, at least, 64 bytes long

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

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 |
| ) |  |  | `[static]`

Generic function for SHA-X computation.

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

Parameters:

  `[in]` | hsu_sha_mode | Mode to configure for HSU
  `[in]` | nb_elem | Number of elements in `addr` table
  `[in]` | addr | Table of input vectors
  `[in]` | len | Table of length, in bytes, of each input vectors
  `[in]` | sha_size | Size, in 32bits words, of the computed hash
  `[out]` | sha | Output buffer. (Must be at least `sha_size` long)

Returns:
  true is `sha` buffer has been updated with the requested hash and false otherwise

Definition at line 322 of file hsu.c.

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