iqr_mac.h File Reference

Typedefs
typedef struct iqr_MAC_struct	iqr_MAC

Functions
IQR_API iqr_retval	iqr_MACCreateHMAC (const iqr_Context *ctx, iqr_HashAlgorithmType hash_algo, iqr_MAC **mac)
IQR_API iqr_retval	iqr_MACCreatePoly1305 (const iqr_Context *ctx, iqr_MAC **mac)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_MACDestroy (iqr_MAC **mac)
IQR_API iqr_retval	iqr_MACMessage (iqr_MAC *mac, const uint8_t *key, size_t key_size, const uint8_t *msg, size_t msg_size, uint8_t *tag, size_t tag_size)
IQR_API iqr_retval	iqr_MACBegin (iqr_MAC *mac, const uint8_t *key, size_t key_size)
IQR_API iqr_retval	iqr_MACUpdate (iqr_MAC *mac, const uint8_t *data, size_t data_size)
IQR_API iqr_retval	iqr_MACEnd (iqr_MAC *mac, uint8_t *tag, size_t tag_size)
IQR_API iqr_retval	iqr_MACGetTagSize (const iqr_MAC *mac, size_t *tag_size)

Typedef Documentation

iqr_MAC

typedef struct iqr_MAC_struct iqr_MAC

The MAC object.

Function Documentation

iqr_MACBegin()

IQR_API iqr_retval iqr_MACBegin	(	iqr_MAC *	mac,
		const uint8_t *	key,
		size_t	key_size
	)

Initialize a MAC with the given key data.

Parameters

[in]	mac	A MAC object.
[in]	key	A buffer containing the key data.
[in]	key_size	The length of the key in bytes.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_MACCreateHMAC()

IQR_API iqr_retval iqr_MACCreateHMAC	(	const iqr_Context *	ctx,
		iqr_HashAlgorithmType	hash_algo,
		iqr_MAC **	mac
	)

Create an HMAC object.

You must call iqr_HashRegisterCallbacks() to set the Hash implementation for hash_algo before creating an HMAC object.

Parameters

[in]	ctx	A Context object.
[in]	hash_algo	The Hash object algorithm to use.
[out]	mac	A pointer that will be assigned an iqr_MAC object.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_MACCreatePoly1305()

IQR_API iqr_retval iqr_MACCreatePoly1305	(	const iqr_Context *	ctx,
		iqr_MAC **	mac
	)

Create a Poly1305 MAC object.

Parameters

[in]	ctx	A Context object.
[out]	mac	A pointer that will be assigned an iqr_MAC object.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_MACDestroy()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_MACDestroy

(

iqr_MAC **

mac

)

Clear and deallocate a MAC object.

mac will be set to NULL prior to returning.

Parameters

[in,out]

mac

A pointer to an iqr_MAC object.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_MACEnd()

IQR_API iqr_retval iqr_MACEnd	(	iqr_MAC *	mac,
		uint8_t *	tag,
		size_t	tag_size
	)

Finish a MAC and retrieve its tag.

This function can only be called after iqr_MACBegin(). Otherwise, IQR_EINVALGOSTATE will be returned.

Parameters

[in]	mac	A MAC object.
[out]	tag	Buffer for storing the MAC tag.
[in]	tag_size	The length of the tag buffer in bytes. This value must be equivalent in size to the tag returned by the MAC algorithm.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_MACGetTagSize()

IQR_API iqr_retval iqr_MACGetTagSize	(	const iqr_MAC *	mac,
		size_t *	tag_size
	)

Get the size of the tag returned by this MAC.

Parameters

[in]	mac	A MAC object.
[out]	tag_size	The size in bytes of the tag generated by this MAC.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_MACMessage()

IQR_API iqr_retval iqr_MACMessage	(	iqr_MAC *	mac,
		const uint8_t *	key,
		size_t	key_size,
		const uint8_t *	msg,
		size_t	msg_size,
		uint8_t *	tag,
		size_t	tag_size
	)

MAC a given message, returning the tag.

This function does a one-shot MAC of the given key and message data, returning the MAC in the tag buffer.

This is equivalent to calling iqr_MACBegin(), iqr_MACUpdate() with the message, then iqr_MACEnd().

Parameters

[in]	mac	A MAC object.
[in]	key	A buffer containing the key data.
[in]	key_size	The length of the key in bytes.
[in]	msg	The message data, or NULL.
[in]	msg_size	The length of the message data in bytes, or 0.
[out]	tag	The resulting message authentication code.
[in]	tag_size	The length of the tag buffer in bytes. This value must be equivalent in size to the tag returned by the MAC algorithm.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

iqr_MACUpdate()

IQR_API iqr_retval iqr_MACUpdate	(	iqr_MAC *	mac,
		const uint8_t *	data,
		size_t	data_size
	)

Update a MAC with the given message data.

This can be called multiple times after calling iqr_MACBegin() and before calling iqr_MACEnd(). Otherwise, IQR_EINVALGOSTATE will be returned.

Parameters

[in]	mac	A MAC object.
[in]	data	Buffer containing message data, or NULL.
[in]	data_size	The length of the data in bytes, or 0.

Returns

IQR_OK on success, or a value from iqr_retval.h when an error occurs.

Detailed Description

ISARA Toolkit's Message Authentication Code object API.

Copyright

Copyright 2016, ISARA Corporation, All Rights Reserved.

License

The code and other content set out herein is not in the public domain, is considered a trade secret and is confidential to ISARA Corporation. Use, reproduction or distribution, in whole or in part, of such code or other content is strictly prohibited except by express written permission of ISARA Corporation. Please contact ISARA Corporation at info@.nosp@m.isar.nosp@m.a.com for more information.