Header file for the Nanocrypto HMAC API. More...

Functions
MOC_EXTERN MSTATUS	HMAC_MD5 (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte key, sbyte4 keyLen, const ubyte text, sbyte4 textLen, const ubyte *textOpt, sbyte4 textOptLen, ubyte result[MD5_DIGESTSIZE])
	Calculate (in a single call) the HMAC-MD5. More...

MOC_EXTERN MSTATUS	HMAC_MD5_quick (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte pKey, sbyte4 keyLen, const ubyte pText, sbyte4 textLen, ubyte *pResult)
	Calculate HMAC-MD5 (with a single function call). More...

MOC_EXTERN MSTATUS	HMAC_SHA1 (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte key, sbyte4 keyLen, const ubyte text, sbyte4 textLen, const ubyte *textOpt, sbyte4 textOptLen, ubyte result[SHA_HASH_RESULT_SIZE])
	Calculate (in a single call) the HMAC-SHA1. More...

MOC_EXTERN MSTATUS	HMAC_SHA1_quick (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte pKey, sbyte4 keyLen, const ubyte pText, sbyte4 textLen, ubyte *pResult)
	Calculate HMAC-SHA1 (with a single function call). More...

MOC_EXTERN MSTATUS	HMAC_SHA1Ex (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte key, sbyte4 keyLen, const ubyte texts[], sbyte4 textLens[], sbyte4 numTexts, ubyte result[SHA_HASH_RESULT_SIZE])
	Calculate (in a single call) the HMAC-SHA1 of multiple input buffers. More...

MOC_EXTERN MSTATUS	HMAC_SHA256 (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte key, sbyte4 keyLen, const ubyte text, sbyte4 textLen, const ubyte *textOpt, sbyte4 textOptLen, ubyte result[SHA256_RESULT_SIZE])
	Calculate (in a single call) the HMAC-SHA256. More...

MOC_EXTERN MSTATUS	HMAC_SHA512 (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte key, sbyte4 keyLen, const ubyte text, sbyte4 textLen, const ubyte *textOpt, sbyte4 textOptLen, ubyte result[SHA512_RESULT_SIZE])
	Calculate (in a single call) the HMAC-SHA512. More...

MOC_EXTERN MSTATUS	HmacCreate (MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX *pctx, const BulkHashAlgo pBHAlgo)
	Create HMAC context. More...

MOC_EXTERN MSTATUS	HmacDelete (MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX **pctx)
	Delete (free) HMAC context. More...

MOC_EXTERN MSTATUS	HmacFinal (MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX ctx, ubyte result)
	Get final HMAC value. More...

MOC_EXTERN MSTATUS	HmacKey (MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX ctx, const ubyte key, ubyte4 keyLen)
	Insert and process HMAC context's key. More...

MOC_EXTERN MSTATUS	HmacQuick (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte pKey, sbyte4 keyLen, const ubyte pText, sbyte4 textLen, ubyte pResult, const BulkHashAlgo pBHAlgo)
	Calculate HMAC (with a single function call). More...

MOC_EXTERN MSTATUS	HmacQuicker (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte pKey, sbyte4 keyLen, const ubyte pText, sbyte4 textLen, ubyte pResult, const BulkHashAlgo pBHAlgo, HMAC_CTX *ctx)
	Calculate HMAC using an existing context (with a single function call). More...

MOC_EXTERN MSTATUS	HmacQuickerEx (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte pKey, sbyte4 keyLen, const ubyte pText, sbyte4 textLen, const ubyte pOptText, ubyte4 optTextLen, ubyte pResult, const BulkHashAlgo pBHAlgo, HMAC_CTX ctx)
	Calculate HMAC using an existing context (with a single function call) for a message with extended data. More...

MOC_EXTERN MSTATUS	HmacQuickerInline (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte pKey, sbyte4 keyLen, const ubyte pText, sbyte4 textLen, ubyte pResult, const BulkHashAlgo pBHAlgo, BulkCtx context)
	Calculate HMAC using an existing hash context (with a single function call). More...

MOC_EXTERN MSTATUS	HmacQuickerInlineEx (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte key, sbyte4 keyLen, const ubyte text, sbyte4 textLen, const ubyte textOpt, sbyte4 textOptLen, ubyte pResult, const BulkHashAlgo *pBHAlgo, BulkCtx context)
	Calculate HMAC with extended data using an existing hash context (with a single function call). More...

MOC_EXTERN MSTATUS	HmacQuickEx (MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte pKey, sbyte4 keyLen, const ubyte pText, sbyte4 textLen, const ubyte pOptText, ubyte4 optTextLen, ubyte pResult, const BulkHashAlgo *pBHAlgo)
	Calculate HMAC (with a single function call) for a message with extended data. More...

MOC_EXTERN MSTATUS	HmacReset (MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX *ctx)
	Reset HMAC context. More...

MOC_EXTERN MSTATUS	HmacUpdate (MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX ctx, const ubyte data, ubyte4 dataLen)
	Update intermediate HMAC value. More...

Detailed Description

Header file for the Nanocrypto HMAC API.

Function Documentation

◆ HMAC_MD5()

MOC_EXTERN MSTATUS HMAC_MD5	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	key,
		sbyte4	keyLen,
		const ubyte *	text,
		sbyte4	textLen,
		const ubyte *	textOpt,
		sbyte4	textOptLen,
		ubyte	result[MD5_DIGESTSIZE]
	)

This function calculates (in a single call) the HMAC-MD5, and returns it through the result parameter.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-MD5

To enable this function, the following flag must not be defined:

__HMAC_MD5_HARDWARE_HASH__

Warning: Before calling this function, be sure that the buffer used for the result parameter is at least MD5_DIGESTSIZE bytes; otherwise, buffer overflow may occur.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing. But... what does the user specify? In the 5.3.1 docs, we just said that this was "Reserved for future use." Ditto this for all hmac.{c,h} functions.
key	Pointer to key for the HMAC-MD5 operation.
keyLen	Number of bytes in the key (`key`).
text	Pointer to input text for the MD5 operation.
textLen	Number of bytes of input text (`text`).
textOpt	Pointer to optional input text for the MD5 operation; can be NULL.
textOptLen	Number of bytes of optional input text; set to 0 if you set `textOpt` to NULL.
result	On return, buffer containing calculated MD5. (The calling function must allocate at least MD5_DIGESTSIZE bytes for the `result`; otherwise buffer overflow may occur.)

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HMAC_MD5_quick()

MOC_EXTERN MSTATUS HMAC_MD5_quick	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pKey,
		sbyte4	keyLen,
		const ubyte *	pText,
		sbyte4	textLen,
		ubyte *	pResult
	)

This function completely calculates an HMAC-MD5, with no need to call multiple, "separate steps" methods. The resultant HMAC value is returned through the result parameter.

Warning: Before calling this function, be sure that the buffer pointed to by the result parameter is large enough: at least equal to MD5_DIGESTSIZE. Otherwise, buffer overflow will occur.

Note: This function is the most efficient method to calculate the HMAC for a single message, saving both memory and time. However, if you need to calculate the HMAC-MD5 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().; To append optional (extended) input data, use the HmacQuickEx() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-MD5

To enable this function, the following flag must not be defined:

__HMAC_MD5_HARDWARE_HASH__

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pKey	Pointer to HMAC key to insert.
keyLen	Number of bytes in HMAC key (`pKey`).
pText	Pointer to input data.
textLen	Number of bytes of input data (`pText`).
pResult	On return, pointer to resultant HMAC-MD5 value.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HMAC_SHA1()

MOC_EXTERN MSTATUS HMAC_SHA1	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	key,
		sbyte4	keyLen,
		const ubyte *	text,
		sbyte4	textLen,
		const ubyte *	textOpt,
		sbyte4	textOptLen,
		ubyte	result[SHA_HASH_RESULT_SIZE]
	)

This function calculates (in a single call) the HMAC-SHA1, and returns it through the result parameter.

Note: This function is the most efficient method to calculate the HMAC-SHA1 for a single message, saving both memory and time. However, if you need to calculate the HMAC-SHA1 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA* >

To enable this function, the following flag must not be defined:

__HMAC_SHA1_HARDWARE_HASH__

Warning: Before calling this function, be sure that the buffer used for the result parameter is at least SHA_HASH_RESULT_SIZE bytes; otherwise, buffer overflow may occur.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
key	Pointer to key for the HMAC-SHA1 operation.
keyLen	Number of bytes in the key (`key`).
text	Pointer to input text for the HMAC-SHA1 operation.
textLen	Number of bytes of input text (`text`).
textOpt	Pointer to optional input text for the HMAC-SHA1 operation; can be NULL.
textOptLen	Number of bytes of optional input text; set to 0 if you set `textOpt` to NULL.
result	On return, buffer containing calculated HMAC-SHA1. (The calling function must allocate at least SHA_HASH_RESULT_SIZE bytes for the `result`; otherwise buffer overflow may occur.)

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HMAC_SHA1_quick()

MOC_EXTERN MSTATUS HMAC_SHA1_quick	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pKey,
		sbyte4	keyLen,
		const ubyte *	pText,
		sbyte4	textLen,
		ubyte *	pResult
	)

This function completely calculates an HMAC-SHA1, with no need to call multiple, "separate steps" methods. The resultant HMAC value is returned through the result parameter.

Warning: Before calling this function, be sure that the buffer pointed to by the result parameter is large enough: at least equal to the output size of the underlying hash function (for example, 20 bytes for SHA1). Otherwise, buffer overflow will occur.

Note: This function is the most efficient method to calculate the HMAC for a single message, saving both memory and time. However, if you need to calculate the HMAC-MD5 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().; To append optional (extended) input data, use the HmacQuickEx() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA*

To enable this function, the following flag must not be defined:

__HMAC_MD5_HARDWARE_HASH__

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pKey	Pointer to HMAC key to insert.
keyLen	Number of bytes in HMAC key (`pKey`).
pText	Pointer to input data.
textLen	Number of bytes of input data (`pText`).
pResult	On return, pointer to resultant HMAC-SHA1 value.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HMAC_SHA1Ex()

MOC_EXTERN MSTATUS HMAC_SHA1Ex	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	key,
		sbyte4	keyLen,
		const ubyte *	texts[],
		sbyte4	textLens[],
		sbyte4	numTexts,
		ubyte	result[SHA_HASH_RESULT_SIZE]
	)

This function calculates (in a single call) the HMAC-SHA1, and returns it through the result parameter.

Note: This function is the most efficient method to calculate the HMAC-SHA1 for a single message, saving both memory and time. However, if you need to calculate the HMAC-SHA1 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA* >

To enable this function, the following flag must not be defined:

__HMAC_SHA1_HARDWARE_HASH__

Warning: Before calling this function, be sure that the buffer used for the result parameter is at least SHA_HASH_RESULT_SIZE bytes; otherwise, buffer overflow may occur.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
key	Pointer to key for the HMAC-SHA1 operation.
keyLen	Number of bytes in the key (`key`).
texts	Array of input texts for the HMAC-SHA1 operation.
textLens	Array of the number of bytes of each input text (`text`).
numTexts	Number of input texts.
result	On return, buffer containing calculated HMAC-SHA1. (The calling function must allocate at least SHA_HASH_RESULT_SIZE bytes for the `result`; otherwise buffer overflow may occur.)

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HMAC_SHA256()

MOC_EXTERN MSTATUS HMAC_SHA256	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	key,
		sbyte4	keyLen,
		const ubyte *	text,
		sbyte4	textLen,
		const ubyte *	textOpt,
		sbyte4	textOptLen,
		ubyte	result[SHA256_RESULT_SIZE]
	)

This function calculates (in a single call) the HMAC-SHA256, and returns it through the result parameter.

Note: This function is the most efficient method to calculate the HMAC-SHA256 for a single message, saving both memory and time. However, if you need to calculate the HMAC-SHA256 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA* >

To enable this function, the following flag not must be defined:

__DISABLE_MOCANA_SHA256__

Warning: Before calling this function, be sure that the buffer used for the result parameter is at least SHA256_RESULT_SIZE bytes; otherwise, buffer overflow may occur.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
key	Pointer to key for the HMAC-SHA256 operation.
keyLen	Number of bytes in the key (`key`).
text	Pointer to input text for the HMAC-SHA256 operation.
textLen	Number of bytes of input text (`text`).
textOpt	Pointer to optional input text for the HMAC-SHA256 operation; can be NULL.
textOptLen	Number of bytes of optional input text; set to 0 if you set `textOpt` to NULL.
result	On return, buffer containing calculated HMAC-SHA256. (The calling function must allocate at least SHA256_RESULT_SIZE bytes for the `result`; otherwise buffer overflow may occur.)

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HMAC_SHA512()

MOC_EXTERN MSTATUS HMAC_SHA512	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	key,
		sbyte4	keyLen,
		const ubyte *	text,
		sbyte4	textLen,
		const ubyte *	textOpt,
		sbyte4	textOptLen,
		ubyte	result[SHA512_RESULT_SIZE]
	)

This function calculates (in a single call) the HMAC-SHA512, and returns it through the result parameter.

Note: This function is the most efficient method to calculate the HMAC-SHA512 for a single message, saving both memory and time. However, if you need to calculate the HMAC-SHA512 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA* >

To enable this function, the following flag not must be defined:

__DISABLE_MOCANA_SHA512__

Warning: Before calling this function, be sure that the buffer used for the result parameter is at least SHA512_RESULT_SIZE bytes; otherwise, buffer overflow may occur.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
key	Pointer to key for the HMAC-SHA512 operation.
keyLen	Number of bytes in the key (`key`).
text	Pointer to input text for the HMAC-SHA512 operation.
textLen	Number of bytes of input text (`text`).
textOpt	Pointer to optional input text for the HMAC-SHA512 operation; can be NULL.
textOptLen	Number of bytes of optional input text; set to 0 if you set `textOpt` to NULL.
result	On return, buffer containing calculated HMAC-SHA512. (The calling function must allocate at least SHA512_RESULT_SIZE bytes for the `result`; otherwise buffer overflow may occur.)

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacCreate()

MOC_EXTERN MSTATUS HmacCreate	(	MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX **	pctx,
		const BulkHashAlgo *	pBHAlgo
	)

This function creates an HMAC context and initializes data structure fields (function pointers) related to the hash function to be used within HMAC operations.

To avoid memory leaks, your application code must call the HmacDelete() function after HMAC-related operations (because the HMAC context is dynamically allocated by this function during context creation).

Note: If you need an HMAC value for only a single message, it is more efficient to call the HmacQuick() function.

Warning: Be sure to check this function's return status. An unsuccessful return causes subsequent HMAC single-step operations to fail.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pctx	On return, pointer to resultant HMAC context.
pBHAlgo	On return, pointer to collection of hash routines to be used within HMAC.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacDelete()

MOC_EXTERN MSTATUS HmacDelete ( MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX ** pctx )

This function deletes (frees) an HMAC context. Your application should call this function as soon as it is done using an HMAC context created by HmacCreate().

Note: If you need an HMAC value for only a single message, it is more efficient to call the HmacQuick() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pctx	Pointer to HMAC context to delete.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacFinal()

MOC_EXTERN MSTATUS HmacFinal	(	MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX *	ctx,
		ubyte *	result
	)

This function calculates a final HMAC value, and returns it through the result parameter.

Warning: Before calling this function, be sure that the buffer pointed to by the result parameter is large enough: at least equal to the output size of the underlying hash function (for example, 20 bytes for SHA1). Otherwise, buffer overflow will occur.

Note: If you need an HMAC value for only a single message, it is more efficient to call the HmacQuick() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
ctx	Pointer to HMAC context.
result	On return, pointer to resultant HMAC value. (The calling function must allocate sufficient memory for the result: at least equal to the output size of the underlying hash function — for example, 20 bytes for SHA1. Otherwise buffer overflow will occur.)

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacKey()

MOC_EXTERN MSTATUS HmacKey	(	MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX *	ctx,
		const ubyte *	key,
		ubyte4	keyLen
	)

This function inserts and processes an HMAC context's key. After calling this function, your application should call HmacUpdate().

Note: If you need an HMAC value for only a single message, it is more efficient to call the HmacQuick() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
ctx	Pointer to HMAC context.
key	Pointer to HMAC key to insert.
keyLen	Number of bytes in HMAC key (`key`).

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacQuick()

MOC_EXTERN MSTATUS HmacQuick	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pKey,
		sbyte4	keyLen,
		const ubyte *	pText,
		sbyte4	textLen,
		ubyte *	pResult,
		const BulkHashAlgo *	pBHAlgo
	)

This function completely calculates an HMAC, with no need to call multiple, "separate steps" methods. Before calling this function, allocate and assign the desired algorithm values to the pBHAlgo parameter. (Using values for SHA1 is the equivalent to calling the HMAC_SHA1() function.) The resultant HMAC value is returned through the pResult parameter.

Warning: Before calling this function, be sure that the buffer pointed to by the result parameter is large enough: at least equal to the output size of the underlying hash function (for example, 20 bytes for SHA1). Otherwise, buffer overflow will occur.

Note: This function is the most efficient method to calculate the HMAC for a single message without using a pre-existing context, saving both memory and time. However, if you need to calculate the HMAC-MD5 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().; To append optional (extended) input data, use the HmacQuickEx() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-MD5, HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pKey	Pointer to HMAC key to insert.
keyLen	Number of bytes in HMAC key (`pKey`).
pText	Pointer to input data.
textLen	Number of bytes of input data (`pText`).
pResult	On return, pointer to resultant HMAC value. (The calling function must allocate sufficient memory for the result: at least equal to the output size of the underlying hash function — for example, 20 bytes for SHA1. Otherwise buffer overflow will occur.)
pBHAlgo	Pointer to collection of hash routines used within HMAC. (Refer to crypto.h for the structure definition.)

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacQuicker()

MOC_EXTERN MSTATUS HmacQuicker	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pKey,
		sbyte4	keyLen,
		const ubyte *	pText,
		sbyte4	textLen,
		ubyte *	pResult,
		const BulkHashAlgo *	pBHAlgo,
		HMAC_CTX *	ctx
	)

This function completely calculates an HMAC, with no need to call multiple, "separate steps" methods. Before calling this function, allocate and assign the desired algorithm values to the pBHAlgo parameter. (Using values for SHA1 is the equivalent to calling the HMAC_SHA1() function.) The resultant HMAC value is returned through the pResult parameter.

Warning: Before calling this function, be sure that the buffer pointed to by the result parameter is large enough: at least equal to the output size of the underlying hash function (for example, 20 bytes for SHA1). Otherwise, buffer overflow will occur.

Note: This function is the most efficient method to calculate the HMAC for a single message, saving both memory and time. However, if you need to calculate the HMAC-MD5 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().; To append optional (extended) input data, use the HmacQuickEx() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-MD5, HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pKey	Pointer to HMAC key to insert.
keyLen	Number of bytes in HMAC key (`pKey`).
pText	Pointer to input data.
textLen	Number of bytes of input data (`pText`).
pResult	On return, pointer to resultant HMAC value. (The calling function must allocate sufficient memory for the result: at least equal to the output size of the underlying hash function — for example, 20 bytes for SHA1. Otherwise buffer overflow will occur.)
pBHAlgo	Pointer to collection of hash routines used within HMAC. (Refer to crypto.h for the structure definition.)
ctx	Pointer to an existing HMAC context to use.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacQuickerEx()

MOC_EXTERN MSTATUS HmacQuickerEx	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pKey,
		sbyte4	keyLen,
		const ubyte *	pText,
		sbyte4	textLen,
		const ubyte *	pOptText,
		ubyte4	optTextLen,
		ubyte *	pResult,
		const BulkHashAlgo *	pBHAlgo,
		HMAC_CTX *	ctx
	)

This function completely calculates an HMAC for a message with extended data, with no need to call multiple, "separate steps" methods. Before calling this function, allocate and assign the desired algorithm values to the pBHAlgo parameter. (Using values for SHA1 is the equivalent to calling the HMAC_SHA1() function.) The resultant HMAC value is returned through the pResult parameter.

Warning: Before calling this function, be sure that the buffer pointed to by the result parameter is large enough: at least equal to the output size of the underlying hash function (for example, 20 bytes for SHA1). Otherwise, buffer overflow will occur.

Note: This function is the most efficient method to calculate the HMAC for a single message with extended data, saving both memory and time. However, if you need to calculate the HMAC-MD5 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-MD5, HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pKey	Pointer to HMAC key to insert.
keyLen	Number of bytes in HMAC key (`pKey`).
pText	Pointer to input data.
textLen	Number of bytes of input data (`pText`).
pOptText	Pointer to optional (extended) input data to append after (`pText`); may be NULL to indicate none (which makes this function equivalent to the HmacQuick() function).
optTextLen	Number of bytes of optional input data (`pOptText`); may be zero to indicate none.
pResult	On return, pointer to resultant HMAC value. (The calling function must allocate sufficient memory for the result: at least equal to the output size of the underlying hash function — for example, 20 bytes for SHA1. Otherwise buffer overflow will occur.)
pBHAlgo	Pointer to collection of hash routines used within HMAC. (Refer to crypto.h for the structure definition.)
ctx	Pointer to an existing HMAC context to use.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacQuickerInline()

MOC_EXTERN MSTATUS HmacQuickerInline	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pKey,
		sbyte4	keyLen,
		const ubyte *	pText,
		sbyte4	textLen,
		ubyte *	pResult,
		const BulkHashAlgo *	pBHAlgo,
		BulkCtx	context
	)

This function is unique in that it does not call any other Hmac* functions, but instead performs the entire computation inline calling only to the underlying hash function.

This function completely calculates an HMAC, with no need to call multiple, "separate steps" methods. Before calling this function, allocate and assign the desired algorithm values to the pBHAlgo parameter. (Using values for SHA1 is the equivalent to calling the HMAC_SHA1() function.) The resultant HMAC value is returned through the pResult parameter.

Warning: Before calling this function, be sure that the buffer pointed to by the result parameter is large enough: at least equal to the output size of the underlying hash function (for example, 20 bytes for SHA1). Otherwise, buffer overflow will occur.

Note: This function is the most efficient method to calculate the HMAC for a single message, saving both memory and time. However, if you need to calculate the HMAC-MD5 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().; To append optional (extended) input data, use the HmacQuickEx() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-MD5, HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pKey	Pointer to HMAC key to insert.
keyLen	Number of bytes in HMAC key (`pKey`).
pText	Pointer to input data.
textLen	Number of bytes of input data (`pText`).
pResult	On return, pointer to resultant HMAC value. (The calling function must allocate sufficient memory for the result: at least equal to the output size of the underlying hash function — for example, 20 bytes for SHA1. Otherwise buffer overflow will occur.)
pBHAlgo	Pointer to collection of hash routines used within HMAC. (Refer to crypto.h for the structure definition.)
context	Pointer to an existing hash context to use.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacQuickerInlineEx()

MOC_EXTERN MSTATUS HmacQuickerInlineEx	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	key,
		sbyte4	keyLen,
		const ubyte *	text,
		sbyte4	textLen,
		const ubyte *	textOpt,
		sbyte4	textOptLen,
		ubyte *	pResult,
		const BulkHashAlgo *	pBHAlgo,
		BulkCtx	context
	)

This function is unique in that it does not call any other Hmac* functions, but instead performs the entire computation inline calling only to the underlying hash function.

This function completely calculates an HMAC, with no need to call multiple, "separate steps" methods. Before calling this function, allocate and assign the desired algorithm values to the pBHAlgo parameter. (Using values for SHA1 is the equivalent to calling the HMAC_SHA1() function.) The resultant HMAC value is returned through the pResult parameter.

Warning: Before calling this function, be sure that the buffer pointed to by the result parameter is large enough: at least equal to the output size of the underlying hash function (for example, 20 bytes for SHA1). Otherwise, buffer overflow will occur.

Note: This function is the most efficient method to calculate the HMAC for a single message, saving both memory and time. However, if you need to calculate the HMAC-MD5 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().; To append optional (extended) input data, use the HmacQuickEx() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-MD5, HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pKey	Pointer to HMAC key to insert.
keyLen	Number of bytes in HMAC key (`pKey`).
pText	Pointer to input data.
textLen	Number of bytes of input data (`pText`).
pOptText	Pointer to optional (extended) input data to append after (`pText`); may be NULL to indicate none (which makes this function equivalent to the HmacQuick() function).
optTextLen	Number of bytes of optional input data (`pOptText`); may be zero to indicate none.
pResult	On return, pointer to resultant HMAC value. (The calling function must allocate sufficient memory for the result: at least equal to the output size of the underlying hash function — for example, 20 bytes for SHA1. Otherwise buffer overflow will occur.)
pBHAlgo	Pointer to collection of hash routines used within HMAC. (Refer to crypto.h for the structure definition.)
context	Pointer to an existing hash context to use.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacQuickEx()

MOC_EXTERN MSTATUS HmacQuickEx	(	MOC_HASH(hwAccelDescr hwAccelCtx) const ubyte *	pKey,
		sbyte4	keyLen,
		const ubyte *	pText,
		sbyte4	textLen,
		const ubyte *	pOptText,
		ubyte4	optTextLen,
		ubyte *	pResult,
		const BulkHashAlgo *	pBHAlgo
	)

This function completely calculates an HMAC for a message with extended data, with no need to call multiple, "separate steps" methods. Before calling this function, allocate and assign the desired algorithm values to the pBHAlgo parameter. (Using values for SHA1 is the equivalent to calling the HMAC_SHA1() function.) The resultant HMAC value is returned through the pResult parameter.

Warning: Before calling this function, be sure that the buffer pointed to by the result parameter is large enough: at least equal to the output size of the underlying hash function (for example, 20 bytes for SHA1). Otherwise, buffer overflow will occur.

Note: This function is the most efficient method to calculate the HMAC for a single message, saving both memory and time. However, if you need to calculate the HMAC-MD5 for two or more messages, you must use the "separate steps" methods, HmacCreate(), HmacKey(), HmacReset(), HmacUpdate(), HmacFinal(), and HmacDelete().

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-MD5, HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
pKey	Pointer to HMAC key to insert.
keyLen	Number of bytes in HMAC key (`pKey`).
pText	Pointer to input data.
textLen	Number of bytes of input data (`pText`).
pOptText	Pointer to optional (extended) input data to append after (`pText`); may be NULL to indicate none (which makes this function equivalent to the HmacQuick() function).
optTextLen	Number of bytes of optional input data (`pOptText`); may be zero to indicate none.
pResult	On return, pointer to resultant HMAC value. (The calling function must allocate sufficient memory for the result: at least equal to the output size of the underlying hash function — for example, 20 bytes for SHA1. Otherwise buffer overflow will occur.)
pBHAlgo	Pointer to collection of hash routines used within HMAC. (Refer to crypto.h for the structure definition.)

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacReset()

MOC_EXTERN MSTATUS HmacReset ( MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX * ctx )

This function resets an HMAC context.

Note: If you need an HMAC value for only a single message, it is more efficient to call the HmacQuick() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
ctx	Pointer to HMAC context.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

◆ HmacUpdate()

MOC_EXTERN MSTATUS HmacUpdate	(	MOC_HASH(hwAccelDescr hwAccelCtx) HMAC_CTX *	ctx,
		const ubyte *	data,
		ubyte4	dataLen
	)

This function updates the intermediate HMAC value in an HMAC context. Applications can repeatedly call this function to calculate an HMAC for different data items.

Note: If you need an HMAC value for only a single message, it is more efficient to call the HmacQuick() function.

FIPS Approved
Suite B Algorithm
Flowchart	HMAC-SHA*

There are no flag dependencies to enable this function.

hmac.h

Parameters

hwAccelCtx	If a hardware acceleration flag is defined, this macro expands to an additional parameter, "hwAccelDescr hwAccelCtx". Otherwise, this macro resolves to nothing.
ctx	Pointer to HMAC context.
text	Pointer to input data.
textLen	Number of bytes of input data (`text`).

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

hmac.h

Functions

Detailed Description

Function Documentation

◆ HMAC_MD5()

◆ HMAC_MD5_quick()

◆ HMAC_SHA1()

◆ HMAC_SHA1_quick()

◆ HMAC_SHA1Ex()

◆ HMAC_SHA256()

◆ HMAC_SHA512()

◆ HmacCreate()

◆ HmacDelete()

◆ HmacFinal()

◆ HmacKey()

◆ HmacQuick()

◆ HmacQuicker()

◆ HmacQuickerEx()

◆ HmacQuickerInline()

◆ HmacQuickerInlineEx()

◆ HmacQuickEx()

◆ HmacReset()

◆ HmacUpdate()