iqr_mac.h File Reference

ISARA Radiate Security Solution Suite's Message Authentication Code object API. More...

Macros
#define	IQR_POLY1305_KEY_SIZE   32
#define	IQR_POLY1305_TAG_SIZE   16

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 *buf, size_t buf_size)
IQR_API iqr_retval	iqr_MACEnd (iqr_MAC *mac, uint8_t *tag, size_t tag_size)
IQR_API iqr_retval	iqr_MACGetKeySize (const iqr_MAC *mac, size_t *key_size)
IQR_API iqr_retval	iqr_MACGetTagSize (const iqr_MAC *mac, size_t *tag_size)

Macro Definition Documentation

IQR_POLY1305_KEY_SIZE

#define IQR_POLY1305_KEY_SIZE   32

The size of a Poly1305 key in bytes. Larger keys are truncated.

IQR_POLY1305_TAG_SIZE

#define IQR_POLY1305_TAG_SIZE   16

The size of a Poly1305 tag in bytes.

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 size of key in bytes. This must be at least the size returned by iqr_MACGetKeySize().

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.

*mac must be set to NULL before calling iqr_MACCreateHMAC().

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.

*mac must be set to NULL before calling iqr_MACCreatePoly1305().

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.

All internal iqr_MAC buffers are cleared and deallocated during the call to iqr_MACDestroy().

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.

All internal buffers are cleared and deallocated during the call to iqr_MACEnd().

Parameters

[in]	mac	A MAC object.
[out]	tag	Buffer for storing the MAC tag.
[in]	tag_size	The size of tag in bytes. This value must be at least the size returned by iqr_MACGetTagSize().

Returns

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

iqr_MACGetKeySize()

IQR_API iqr_retval iqr_MACGetKeySize	(	const iqr_MAC *	mac,
		size_t *	key_size
	)

Get the size of the key required by this MAC.

This function will return the minimum size of a key for the given MAC object. For HMAC, longer keys can be supplied, and the extra key data will be processed along with the first key_size bytes. For Poly1305, this will always return IQR_POLY1305_KEY_SIZE, and only the first IQR_POLY1305_KEY_SIZE bytes will be used.

Parameters

[in]	mac	A MAC object.
[out]	key_size	The size of the key required by this MAC in bytes.

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. For Poly1305, this will always return IQR_POLY1305_TAG_SIZE.

Parameters

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

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().

All internal buffers are cleared and deallocated during the call to iqr_MACMessage().

Parameters

[in]	mac	A MAC object.
[in]	key	A buffer containing the key data.
[in]	key_size	The size of key in bytes. This must be at least the size returned by iqr_MACGetKeySize().
[in]	msg	The message data, or NULL.
[in]	msg_size	The size of msg in bytes, or 0.
[out]	tag	The resulting message authentication code.
[in]	tag_size	The size of tag in bytes. This value must be exactly the size returned by iqr_MACGetTagSize().

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 *	buf,
		size_t	buf_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]	buf	Buffer containing message data, or NULL.
[in]	buf_size	The size of buf in bytes, or 0.

Returns

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

Detailed Description

ISARA Radiate Security Solution Suite's Message Authentication Code object API.

Copyright

Copyright 2016-2018, 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.