CAAM HASH driver

Overview

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

Macros
#define	CAAM_SHA_BLOCK_SIZE   128
	CAAM HASH Context size. More...
#define	CAAM_HASH_BLOCK_SIZE   CAAM_SHA_BLOCK_SIZE
	CAAM hash block size.
#define	CAAM_HASH_CTX_SIZE   58
	CAAM HASH Context size. More...

Typedefs
typedef uint32_t	caam_hash_ctx_t [CAAM_HASH_CTX_SIZE]
	Storage type used to save hash context. More...

Enumerations
enum	caam_hash_algo_t {   kCAAM_XcbcMac = 0,   kCAAM_Cmac,   kCAAM_Sha1,   kCAAM_Sha224,   kCAAM_Sha256,   kCAAM_Sha384,   kCAAM_Sha512 }
	Supported cryptographic block cipher functions for HASH creation. More...

Functions
status_t	CAAM_HASH_Init (CAAM_Type *base, caam_handle_t *handle, caam_hash_ctx_t *ctx, caam_hash_algo_t algo, const uint8_t *key, size_t keySize)
	Initialize HASH context. More...
status_t	CAAM_HASH_Update (caam_hash_ctx_t *ctx, const uint8_t *input, size_t inputSize)
	Add data to current HASH. More...
status_t	CAAM_HASH_Finish (caam_hash_ctx_t *ctx, uint8_t *output, size_t *outputSize)
	Finalize hashing. More...
status_t	CAAM_HASH (CAAM_Type *base, caam_handle_t *handle, caam_hash_algo_t algo, const uint8_t *input, size_t inputSize, const uint8_t *key, size_t keySize, uint8_t *output, size_t *outputSize)
	Create HASH on given data. More...

Macro Definition Documentation

#define CAAM_SHA_BLOCK_SIZE   128

up to SHA-512 block size

#define CAAM_HASH_CTX_SIZE   58

Typedef Documentation

typedef uint32_t caam_hash_ctx_t[CAAM_HASH_CTX_SIZE]

Enumeration Type Documentation

enum caam_hash_algo_t

Enumerator
kCAAM_XcbcMac	XCBC-MAC (AES engine)
kCAAM_Cmac	CMAC (AES engine)
kCAAM_Sha1	SHA_1 (MDHA engine)
kCAAM_Sha224	SHA_224 (MDHA engine)
kCAAM_Sha256	SHA_256 (MDHA engine)
kCAAM_Sha384	SHA_384 (MDHA engine)
kCAAM_Sha512	SHA_512 (MDHA engine)

Function Documentation

status_t CAAM_HASH_Init	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		caam_hash_ctx_t *	ctx,
		caam_hash_algo_t	algo,
		const uint8_t *	key,
		size_t	keySize
	)

This function initializes the HASH. Key shall be supplied if the underlaying algoritm is AES XCBC-MAC or CMAC. Key shall be NULL if the underlaying algoritm is SHA.

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

This functions is used to initialize the context for both blocking and non-blocking CAAM_HASH API. For blocking CAAM HASH API, the HASH context contains all information required for context switch, such as running hash or MAC. For non-blocking CAAM HASH API, the HASH context is used to hold SGT. Therefore, the HASH context cannot be shared between blocking and non-blocking HASH API. With one HASH context, either use only blocking HASH API or only non-blocking HASH API.

Parameters

	base	CAAM peripheral base address
	handle	Handle used for this request.
[out]	ctx	Output hash context
	algo	Underlaying algorithm to use for hash computation.
	key	Input key (NULL if underlaying algorithm is SHA)
	keySize	Size of input key in bytes

Returns

Status of initialization

status_t CAAM_HASH_Update	(	caam_hash_ctx_t *	ctx,
		const uint8_t *	input,
		size_t	inputSize
	)

Add data to current HASH. This can be called repeatedly with an arbitrary amount of data to be hashed. The functions blocks. If it returns kStatus_Success, the running hash or mac has been updated (CAAM has processed the input data), so the memory at input pointer can be released back to system. The context is updated with the running hash or mac and with all necessary information to support possible context switch.

Parameters

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

Returns

Status of the hash update operation

status_t CAAM_HASH_Finish	(	caam_hash_ctx_t *	ctx,
		uint8_t *	output,
		size_t *	outputSize
	)

Outputs the final hash (computed by CAAM_HASH_Update()) and erases the context.

Parameters

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

Returns

Status of the hash finish operation

status_t CAAM_HASH	(	CAAM_Type *	base,
		caam_handle_t *	handle,
		caam_hash_algo_t	algo,
		const uint8_t *	input,
		size_t	inputSize,
		const uint8_t *	key,
		size_t	keySize,
		uint8_t *	output,
		size_t *	outputSize
	)

Perform the full keyed XCBC-MAC/CMAC or SHA in one function call.

Key shall be supplied if the underlaying algoritm is AES XCBC-MAC or CMAC. Key shall be NULL if the underlaying algoritm is SHA.

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

The function is blocking.

Parameters

	base	CAAM peripheral base address
	handle	Handle used for this request.
	algo	Underlaying algorithm to use for hash computation.
	input	Input data
	inputSize	Size of input data in bytes
	key	Input key (NULL if underlaying algorithm is SHA)
	keySize	Size of input key in bytes
[out]	output	Output hash data
[out]	outputSize	Output parameter storing the size of the output hash in bytes

Returns

Status of the one call hash operation.