LTC HASH driver

Overview

This section describes the programming interface of the LTC HASH driver.

Data Structures
union	ltc_drv_hash_block
	16-byte block represented as byte array or four 32-bit words More...
struct	ltc_drv_hash_ctx
	Data structure with hash context. More...

Enumerations
enum	ltc_drv_hash_algo_state {   kLtcHashInit = 1u,   kLtcHashUpdate }
	Internal states of the HASH creation process. More...
enum	ltc_drv_hash_algo {   kLtcXcbcMac = kLTCMode_XCBC_MAC,   kLtcCMAC = kLTCMode_CMAC }
	Supported cryptographic block cipher functions for HASH creation. More...
enum	ltc_drv_hash_ctx_indexes {   kLtcHashCtxKeyStartIdx = 12,   kLtcHashCtxKeySize = 20,   kLtcHashCtxNumWords = 21 }
	Definitions of indexes into hash context array. More...

Functions
ltc_status_t	LTC_DRV_hash_init (uint32_t instance, ltc_drv_hash_ctx *ctx, ltc_drv_hash_algo algo, const uint8_t *key, uint32_t keySize)
	Initialize HASH context. More...
ltc_status_t	LTC_DRV_hash_update (ltc_drv_hash_ctx *ctx, const uint8_t *input, uint32_t inputSize)
	Add data to current HASH. More...
ltc_status_t	LTC_DRV_hash_finish (ltc_drv_hash_ctx *ctx, uint8_t *output, uint32_t *outputSize)
	Finalize hashing. More...
ltc_status_t	LTC_DRV_hash (uint32_t instance, ltc_drv_hash_algo algo, const uint8_t *input, uint32_t inputSize, const uint8_t *key, uint32_t keySize, uint8_t *output, uint32_t *outputSize)
	Create HASH on given data. More...

---

Data Structure Documentation

union ltc_drv_hash_block

Data Fields
uint8_t	b [16]
	byte array
uint32_t	w [4]
	array of 32-bit words

struct ltc_drv_hash_ctx

XCBC-MAC needs to store 48 bytes of context (MAC, K2 and K3) between message chunks processing.
CMAC needs less (32 bytes) of context (MAC and L) between message chunks processing.

In both modes, also the derived AES key must be restored from the context.

If state of the hash software process is kLtcCmacInit, the context is defined as follows
word[20] = key_size = word[kLtcCmacCtxKeySize]
word[12-19] = init key

If state of the hash software process is kLtcCmacUpdate, the context for kLtcXcbcMac hash is defined as follows
word[0-3] = mac
word[3-7] = k3
word[8-11] = k2
word[12-19] = k1
word[20] = key_size = word[kLtcCmacCtxKeySize]

If state of the hash software process is kLtcCmacUpdate, the context for kLtcCMAC hash is defined as follows
word[0-3] = mac
word[3-7] = L
word[12-19] = k1
word[20] = key_size = word[kLtcCmacCtxKeySize]

During hash updates we only process 16-byte blocks. If we have less data then keep them only in context. The 'blk' memory buffer is flushed to LTC during hash finish.

Data Fields
ltc_drv_hash_block	blk
	memory buffer. More...
uint32_t	blksz
	number of valid bytes in memory buffer
uint32_t	instance
	LTC module instance number.
ltc_drv_hash_algo	algo
	selected algorithm from the set of supported algorithms in ltc_drv_hash_algo
ltc_drv_hash_algo_state	state
	finite machine state of the hash software process
uint32_t	word [kLtcHashCtxNumWords]
	LTC module context that needs to be saved/restored between LTC jobs.

Field Documentation

ltc_drv_hash_block ltc_drv_hash_ctx::blk

only full 16-byte blocks are written to LTC during hash updates

Enumeration Type Documentation

enum ltc_drv_hash_algo_state

Enumerator
kLtcHashInit	Key in the HASH context is the input key.
kLtcHashUpdate	HASH context has algorithm specific context: MAC, K2 and K3 (XCBC-MAC) or MAC and L (CMAC). Key in the HASH context is the derived key.

enum ltc_drv_hash_algo

Enumerator
kLtcXcbcMac	XCBC-MAC (AES engine)
kLtcCMAC	CMAC (AES engine)

enum ltc_drv_hash_ctx_indexes

Enumerator
kLtcHashCtxKeyStartIdx	context word array index where key is stored
kLtcHashCtxKeySize	context word array index where key size is stored
kLtcHashCtxNumWords	number of context array 32-bit words

Function Documentation

ltc_status_t LTC_DRV_hash_init	(	uint32_t	instance,
		ltc_drv_hash_ctx *	ctx,
		ltc_drv_hash_algo	algo,
		const uint8_t *	key,
		uint32_t	keySize
	)

This function initialize the HASH with a given key, and selects a block cipher to use.

For XCBC-MAC, the key length must be 16. For CMAC, the key length can be the AES key lengths supported by AES engine.

Parameters

	instance	LTC module instance number.
[out]	ctx	Output hash context
	algo	Block cipher algorithm to use for HASH creation
	key	Input key
	keySize	Size of input key in bytes

Returns

0 on succes, or kFSLCryptErrInvalidKeyLength

ltc_status_t LTC_DRV_hash_update	(	ltc_drv_hash_ctx *	ctx,
		const uint8_t *	input,
		uint32_t	inputSize
	)

Add data to current HASH. This can be called repeatedly with an arbitrary amount of data to be hashed.

Parameters

[in,out]	ctx	HASH context
	input	Input data
	inputSize	Size of input data in bytes

Returns

Status of the hash update operation

ltc_status_t LTC_DRV_hash_finish	(	ltc_drv_hash_ctx *	ctx,
		uint8_t *	output,
		uint32_t *	outputSize
	)

Outputs the final hash and erases the context.

Parameters

[in,out]	ctx	Input hash context
[out]	output	Output hash data
[out]	outputSize	Output param storing the size of the output hash in bytes

Returns

Status of the hash finish operation

ltc_status_t LTC_DRV_hash	(	uint32_t	instance,
		ltc_drv_hash_algo	algo,
		const uint8_t *	input,
		uint32_t	inputSize,
		const uint8_t *	key,
		uint32_t	keySize,
		uint8_t *	output,
		uint32_t *	outputSize
	)

Peform the full keyed HASH in one function call.

Parameters

	instance	LTC module instance number.
	algo	Block cipher algorithm to use for CMAC creation
	input	Input data
	inputSize	Size of input data in bytes
	key	Input key
	keySize	Size of input key in bytes
[out]	output	Output hash data
[out]	outputSize	Output param storing the size of the output hash in bytes

Returns

Status of the one call hash operation.