iqr_hash.h File Reference

ISARA Radiate Security Solution Suite's Hash object API. More...

Data Structures
struct	iqr_HashCallbacks

Macros
#define	IQR_BLAKE2B_256_DIGEST_SIZE   32
	The size of a BLAKE2b-256 digest in bytes. More...
#define	IQR_BLAKE2B_512_DIGEST_SIZE   64
	The size of a BLAKE2b-512 digest in bytes. More...
#define	IQR_SHA2_256_DIGEST_SIZE   32
	The size of a SHA2-256 digest in bytes. More...
#define	IQR_SHA2_384_DIGEST_SIZE   48
	The size of a SHA2-384 digest in bytes. More...
#define	IQR_SHA2_512_DIGEST_SIZE   64
	The size of a SHA2-512 digest in bytes. More...
#define	IQR_SHA3_256_DIGEST_SIZE   32
	The size of a SHA3-256 digest in bytes. More...
#define	IQR_SHA3_512_DIGEST_SIZE   64
	The size of a SHA3-512 digest in bytes. More...

Typedefs
typedef struct iqr_Hash_struct	iqr_Hash

Enumerations
enum	iqr_HashAlgorithmType {   IQR_HASHALGO_BLAKE2B_256,   IQR_HASHALGO_BLAKE2B_512,   IQR_HASHALGO_SHA2_256,   IQR_HASHALGO_SHA2_384,   IQR_HASHALGO_SHA2_512,   IQR_HASHALGO_SHA3_256,   IQR_HASHALGO_SHA3_512 }

Functions
IQR_API iqr_retval	iqr_HashRegisterCallbacks (iqr_Context *ctx, iqr_HashAlgorithmType hash_algo, const iqr_HashCallbacks *cb)
IQR_API iqr_retval	iqr_HashCreate (const iqr_Context *ctx, iqr_HashAlgorithmType hash_algo, iqr_Hash **obj)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_HashDestroy (iqr_Hash **obj)
IQR_API iqr_retval	iqr_HashBegin (iqr_Hash *obj)
IQR_API iqr_retval	iqr_HashUpdate (iqr_Hash *obj, const uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_HashEnd (iqr_Hash *obj, uint8_t *digest, size_t digest_size)
IQR_API iqr_retval	iqr_HashMessage (iqr_Hash *obj, const uint8_t *buf, size_t buf_size, uint8_t *digest, size_t digest_size)
IQR_API iqr_retval	iqr_HashGetDigestSize (const iqr_Hash *obj, size_t *digest_size)
IQR_API iqr_retval	iqr_HashGetAlgorithmType (const iqr_Hash *obj, iqr_HashAlgorithmType *hash_algo)
IQR_API iqr_retval	iqr_HashAlgorithmGetDigestSize (const iqr_HashAlgorithmType hash_algo, size_t *digest_size)
IQR_API iqr_retval	iqr_HashSetSalt (iqr_Hash *obj, const uint8_t *salt, size_t salt_size)
IQR_API iqr_retval	iqr_HashGetSalt (const iqr_Hash *obj, uint8_t *salt, size_t salt_size)
IQR_API iqr_retval	iqr_HashGetSaltSize (const iqr_Hash *obj, size_t *salt_size)

Variables
IQR_EXTERN const iqr_HashCallbacks	IQR_HASH_DEFAULT_BLAKE2B_256
IQR_EXTERN const iqr_HashCallbacks	IQR_HASH_DEFAULT_BLAKE2B_512
IQR_EXTERN const iqr_HashCallbacks	IQR_HASH_DEFAULT_SHA2_256
IQR_EXTERN const iqr_HashCallbacks	IQR_HASH_DEFAULT_SHA2_384
IQR_EXTERN const iqr_HashCallbacks	IQR_HASH_DEFAULT_SHA2_512
IQR_EXTERN const iqr_HashCallbacks	IQR_HASH_DEFAULT_SHA3_256
IQR_EXTERN const iqr_HashCallbacks	IQR_HASH_DEFAULT_SHA3_512

Macro Definition Documentation

IQR_BLAKE2B_256_DIGEST_SIZE

#define IQR_BLAKE2B_256_DIGEST_SIZE   32

The size of a BLAKE2b-256 digest in bytes.

IQR_BLAKE2B_512_DIGEST_SIZE

#define IQR_BLAKE2B_512_DIGEST_SIZE   64

The size of a BLAKE2b-512 digest in bytes.

IQR_SHA2_256_DIGEST_SIZE

#define IQR_SHA2_256_DIGEST_SIZE   32

The size of a SHA2-256 digest in bytes.

IQR_SHA2_384_DIGEST_SIZE

#define IQR_SHA2_384_DIGEST_SIZE   48

The size of a SHA2-384 digest in bytes.

IQR_SHA2_512_DIGEST_SIZE

#define IQR_SHA2_512_DIGEST_SIZE   64

The size of a SHA2-512 digest in bytes.

IQR_SHA3_256_DIGEST_SIZE

#define IQR_SHA3_256_DIGEST_SIZE   32

The size of a SHA3-256 digest in bytes.

IQR_SHA3_512_DIGEST_SIZE

#define IQR_SHA3_512_DIGEST_SIZE   64

The size of a SHA3-512 digest in bytes.

Typedef Documentation

iqr_Hash

typedef struct iqr_Hash_struct iqr_Hash

The Hash object.

Enumeration Type Documentation

iqr_HashAlgorithmType

enum iqr_HashAlgorithmType

Hash algorithms supported by the toolkit.

Enumerator
IQR_HASHALGO_BLAKE2B_256	BLAKE2b-256 algorithm type identifier.
IQR_HASHALGO_BLAKE2B_512	BLAKE2b-512 algorithm type identifier.
IQR_HASHALGO_SHA2_256	SHA2-256 algorithm type identifier.
IQR_HASHALGO_SHA2_384	SHA2-384 algorithm type identifier.
IQR_HASHALGO_SHA2_512	SHA2-512 algorithm type identifier.
IQR_HASHALGO_SHA3_256	SHA3-256 algorithm type identifier.
IQR_HASHALGO_SHA3_512	SHA3-512 algorithm type identifier.

Function Documentation

iqr_HashAlgorithmGetDigestSize()

IQR_API iqr_retval iqr_HashAlgorithmGetDigestSize	(	const iqr_HashAlgorithmType	hash_algo,
		size_t *	digest_size
	)

Given a hash algorithm, return its digest size.

Parameters

[in]	hash_algo	A hash algorithm.
[out]	digest_size	The size of the algorithm's digest.

Returns

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

iqr_HashBegin()

IQR_API iqr_retval iqr_HashBegin

(

iqr_Hash *

obj

)

Begin the hashing process.

Parameters

[in]

obj

An iqr_Hash object.

Returns

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

iqr_HashCreate()

IQR_API iqr_retval iqr_HashCreate	(	const iqr_Context *	ctx,
		iqr_HashAlgorithmType	hash_algo,
		iqr_Hash **	obj
	)

Create and initialize a Hash object.

The resulting iqr_Hash represents the hash algorithm specified by this function. The caller must free the Hash object using iqr_HashDestroy().

The correct hashing algorithm must be registered via iqr_HashRegisterCallbacks(), otherwise IQR_ENOTREGISTERED is returned.

*obj must be set to NULL before calling iqr_HashCreate().

Parameters

[in]	ctx	An iqr_Context object.
[in]	hash_algo	The desired hash algorithm.
[out]	obj	An iqr_Hash object.

Returns

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

iqr_HashDestroy()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_HashDestroy

(

iqr_Hash **

obj

)

Clear and deallocate a Hash object.

obj will be set to NULL prior to returning.

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

Parameters

[in,out]

obj

An iqr_Hash object.

Returns

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

iqr_HashEnd()

IQR_API iqr_retval iqr_HashEnd	(	iqr_Hash *	obj,
		uint8_t *	digest,
		size_t	digest_size
	)

Finalize the hashing procedure and return the hash digest.

The digest buffer size is set based on which algorithm was specified at creation. The iqr_HashGetDigestSize() function returns the required digest size.

After a call to this function succeeds, the Hash object can be reused by calling iqr_HashBegin() again. All internal buffers are cleared and deallocated before iqr_HashEnd() returns.

Calling iqr_HashEnd() with digest set to NULL (and digest_size set to 0) lets you finalize the hashing procedure without retrieving the digest so the hash object can be reused.

Parameters

[in]	obj	An iqr_Hash object.
[out]	digest	A buffer that will receive the hash digest or NULL.
[in]	digest_size	The size of digest in bytes. Must be exactly the size returned by iqr_HashGetDigestSize() or 0 if digest is NULL.

Returns

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

iqr_HashGetAlgorithmType()

IQR_API iqr_retval iqr_HashGetAlgorithmType	(	const iqr_Hash *	obj,
		iqr_HashAlgorithmType *	hash_algo
	)

Retrieve the hash algorithm type.

Parameters

[in]	obj	An iqr_Hash object.
[out]	hash_algo	The retrieved algorithm type.

Returns

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

iqr_HashGetDigestSize()

IQR_API iqr_retval iqr_HashGetDigestSize	(	const iqr_Hash *	obj,
		size_t *	digest_size
	)

Retrieve the size of the resulting digest.

Parameters

[in]	obj	An iqr_Hash object.
[out]	digest_size	The resulting digest size.

Returns

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

iqr_HashGetSalt()

IQR_API iqr_retval iqr_HashGetSalt	(	const iqr_Hash *	obj,
		uint8_t *	salt,
		size_t	salt_size
	)

Retrieve the salt value.

When setting the salt with iqr_HashSetSalt(), it may be modified to match the hashing algorithm's block size.

Parameters

[in]	obj	An iqr_Hash object.
[out]	salt	A buffer to retrieve the salt.
[in]	salt_size	The size of salt in bytes. This must be exactly the size returned by iqr_HashGetSaltSize().

Returns

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

iqr_HashGetSaltSize()

IQR_API iqr_retval iqr_HashGetSaltSize	(	const iqr_Hash *	obj,
		size_t *	salt_size
	)

Retrieve the salt size.

Parameters

[in]	obj	An iqr_Hash object.
[out]	salt_size	Variable that will receive the salt size value.

Returns

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

iqr_HashMessage()

IQR_API iqr_retval iqr_HashMessage	(	iqr_Hash *	obj,
		const uint8_t *	buf,
		size_t	buf_size,
		uint8_t *	digest,
		size_t	digest_size
	)

Hash a single message.

This is the equivalent of calling iqr_HashBegin(), iqr_HashUpdate() with the specified data, and then iqr_HashEnd(). All internal buffers are cleared and deallocated before iqr_HashMessage() returns.

Parameters

[in]	obj	An iqr_Hash object.
[in]	buf	A buffer containing data to be hashed.
[in]	buf_size	The size of buf in bytes.
[out]	digest	A buffer that will receive the hash digest.
[in]	digest_size	The size of digest in bytes. Must be exactly the size returned by iqr_HashGetDigestSize() or 0 if digest is NULL.

Returns

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

iqr_HashRegisterCallbacks()

IQR_API iqr_retval iqr_HashRegisterCallbacks	(	iqr_Context *	ctx,
		iqr_HashAlgorithmType	hash_algo,
		const iqr_HashCallbacks *	cb
	)

Register a hashing implementation.

This function lets you specify the implementation for a specified hash algorithm. Hashing functions must be registered prior to using the hashing API (see the IQR_HASHALGO_* constants and the IQR_HASH_DEFAULT_* implementations).

Parameters

[in]	ctx	An iqr_Context object.
[in]	hash_algo	The hashing algorithm to override.
[in]	cb	The hashing implementation (see IQR_HASH_DEFAULT_*).

Returns

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

iqr_HashSetSalt()

IQR_API iqr_retval iqr_HashSetSalt	(	iqr_Hash *	obj,
		const uint8_t *	salt,
		size_t	salt_size
	)

Set a salt to apply during the hashing process.

By setting a salt, the hashing algorithm behaves differently. Calls to iqr_HashUpdate() incur an extra step where the salt is applied to the data prior to hashing.

The salt must be at least 128 bits (16 bytes) in length. If the salt buffer is smaller than the hashing algorithm's block length, then the salt will be concatenated with itself to meet the block length. If the salt buffer is too large, it will be truncated. The block length is dependent on the underlying hash algorithm.

This function can only be called prior to iqr_HashBegin() or after iqr_HashEnd(). The salt persists throughout the lifetime of the Hash object, though subsequent calls to iqr_HashSetSalt() will replace it.

Note

This function only works with Merkle-Damgard hashing algorithms such as SHA2-256 or SHA2-512.

Parameters

[in]	obj	An iqr_Hash object.
[in]	salt	A buffer containing the salt. Must be at least 128 bits (16 bytes) of data.
[in]	salt_size	The size of salt in bytes.

Returns

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

iqr_HashUpdate()

IQR_API iqr_retval iqr_HashUpdate	(	iqr_Hash *	obj,
		const uint8_t *	buf,
		size_t	buf_size
	)

Update the hashing process with new data.

Parameters

[in]	obj	An iqr_Hash object.
[in]	buf	A buffer containing data to be hashed.
[in]	buf_size	The size of buf in bytes.

Returns

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

Variable Documentation

IQR_HASH_DEFAULT_BLAKE2B_256

IQR_EXTERN const iqr_HashCallbacks IQR_HASH_DEFAULT_BLAKE2B_256

Internal Hash implementations.

Use these with iqr_HashRegisterCallbacks() to use the toolkit's implementations; no default implementation is configured before you call iqr_HashRegisterCallbacks().Internal BLAKE2b-256 implementation.

IQR_HASH_DEFAULT_BLAKE2B_512

IQR_EXTERN const iqr_HashCallbacks IQR_HASH_DEFAULT_BLAKE2B_512

Internal BLAKE2b-512 implementation.

IQR_HASH_DEFAULT_SHA2_256

IQR_EXTERN const iqr_HashCallbacks IQR_HASH_DEFAULT_SHA2_256

Internal SHA2-256 implementation.

IQR_HASH_DEFAULT_SHA2_384

IQR_EXTERN const iqr_HashCallbacks IQR_HASH_DEFAULT_SHA2_384

Internal SHA2-384 implementation.

IQR_HASH_DEFAULT_SHA2_512

IQR_EXTERN const iqr_HashCallbacks IQR_HASH_DEFAULT_SHA2_512

Internal SHA2-512 implementation.

IQR_HASH_DEFAULT_SHA3_256

IQR_EXTERN const iqr_HashCallbacks IQR_HASH_DEFAULT_SHA3_256

Internal SHA3-256 implementation.

IQR_HASH_DEFAULT_SHA3_512

IQR_EXTERN const iqr_HashCallbacks IQR_HASH_DEFAULT_SHA3_512

Internal SHA3-512 implementation.

Detailed Description

ISARA Radiate Security Solution Suite's Hash object API.

The Hash object provides a generic interface for hashing algorithms, such as SHA2-256. Hash implementations are registered globally via the Context object. Once you've registered the desired hash implementation, the rest of the library can create Hash objects as needed.

The toolkit also supports randomized hashing, as described in Strengthening Digital Signatures via Randomized Hashing by Halevi and Krawczyk. Randomized hashes apply additional salt to hashing operations, making the hash more resistant to collisions without modifying the underlying algorithm.

Copyright

Copyright 2015-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.