iqr_hash.h File Reference

Data Structures
struct	iqr_HashCallbacks

Macros
#define	IQR_SHA2_224_DIGEST_SIZE   28
	Size of a SHA-224 digest in bytes. More...
#define	IQR_SHA2_256_DIGEST_SIZE   32
	Size of a SHA-256 digest in bytes. More...
#define	IQR_SHA2_384_DIGEST_SIZE   48
	Size of a SHA-384 digest in bytes. More...
#define	IQR_SHA2_512_DIGEST_SIZE   64
	Size of a SHA-512 digest in bytes. More...
#define	IQR_SHA3_224_DIGEST_SIZE   28
	Size of a SHA3-224 digest in bytes. More...
#define	IQR_SHA3_256_DIGEST_SIZE   32
	Size of a SHA3-256 digest in bytes. More...
#define	IQR_SHA3_384_DIGEST_SIZE   48
	Size of a SHA3-384 digest in bytes. More...
#define	IQR_SHA3_512_DIGEST_SIZE   64
	Size of a SHA3-512 digest in bytes. More...

Typedefs
typedef struct iqr_Hash_struct	iqr_Hash

Enumerations
enum	iqr_HashAlgorithmType {   IQR_HASHALGO_SHA2_256,   IQR_HASHALGO_SHA2_512,   IQR_HASHALGO_SHA3_256,   IQR_HASHALGO_SHA3_512 }

Functions
IQR_API iqr_retval	iqr_HashRegisterCallbacks (iqr_Context *ctx, iqr_HashAlgorithmType algo, const iqr_HashCallbacks *cb)
IQR_API iqr_retval	iqr_HashCreate (const iqr_Context *ctx, iqr_HashAlgorithmType 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 *data, size_t 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 *data, size_t data_size, uint8_t *digest, size_t digest_size)
IQR_API iqr_retval	iqr_HashGetDigestSize (const iqr_Hash *obj, size_t *size)
IQR_API iqr_retval	iqr_HashGetAlgorithmType (const iqr_Hash *obj, iqr_HashAlgorithmType *algo)
IQR_API iqr_retval	iqr_HashAlgorithmGetDigestSize (const iqr_HashAlgorithmType 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_SHA2_256
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_SHA2_224_DIGEST_SIZE

#define IQR_SHA2_224_DIGEST_SIZE   28

Size of a SHA-224 digest in bytes.

IQR_SHA2_256_DIGEST_SIZE

#define IQR_SHA2_256_DIGEST_SIZE   32

Size of a SHA-256 digest in bytes.

IQR_SHA2_384_DIGEST_SIZE

#define IQR_SHA2_384_DIGEST_SIZE   48

Size of a SHA-384 digest in bytes.

IQR_SHA2_512_DIGEST_SIZE

#define IQR_SHA2_512_DIGEST_SIZE   64

Size of a SHA-512 digest in bytes.

IQR_SHA3_224_DIGEST_SIZE

#define IQR_SHA3_224_DIGEST_SIZE   28

Size of a SHA3-224 digest in bytes.

IQR_SHA3_256_DIGEST_SIZE

#define IQR_SHA3_256_DIGEST_SIZE   32

Size of a SHA3-256 digest in bytes.

IQR_SHA3_384_DIGEST_SIZE

#define IQR_SHA3_384_DIGEST_SIZE   48

Size of a SHA3-384 digest in bytes.

IQR_SHA3_512_DIGEST_SIZE

#define IQR_SHA3_512_DIGEST_SIZE   64

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_SHA2_256	SHA-256 algorithm type identifier.
IQR_HASHALGO_SHA2_512	SHA-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	algo,
		size_t *	digest_size
	)

Given a hash algorithm, return its digest size.

Parameters

[in]	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	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.

Parameters

[in]	ctx	An iqr_Context object.
[in]	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.

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.

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 the digest buffer. Must be the correct digest size or 0; see the digest size constants or call iqr_HashGetDigestSize().

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 *	algo
	)

Retrieve the hash algorithm type.

Parameters

[in]	obj	An iqr_Hash object.
[out]	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 *	size
	)

Retrieve the size of the resulting digest.

Parameters

[in]	obj	An iqr_Hash object.
[out]	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	Size of the salt buffer. This must be equivalent to 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 *	data,
		size_t	data_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().

Parameters

[in]	obj	An iqr_Hash object.
[in]	data	The data to be hashed.
[in]	data_size	The size of the data buffer, in bytes.
[out]	digest	A buffer that will receive the hash digest.
[in]	digest_size	The size of the digest buffer. Must be the correct digest size; see the digest size constants or call iqr_HashGetDigestSize().

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	algo,
		const iqr_HashCallbacks *	cb
	)

Register a default 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_HASH_DEFAULT_* constants).

Parameters

[in]	ctx	An iqr_Context object.
[in]	algo	The hashing algorithm to override.
[in]	cb	The hashing functions (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 works with Merkle-Damgard (SHA-256 or SHA-512) hashing functions only.

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	Size of the salt buffer.

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 *	data,
		size_t	size
	)

Update the hashing process with new data.

Parameters

[in]	obj	An iqr_Hash object.
[in]	data	The data to be hashed.
[in]	size	The size of the data buffer.

Returns

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

Variable Documentation

IQR_HASH_DEFAULT_SHA2_256

IQR_EXTERN const iqr_HashCallbacks IQR_HASH_DEFAULT_SHA2_256

Internal SHA-2 and SHA-3 implementations.

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

IQR_HASH_DEFAULT_SHA2_512

IQR_EXTERN const iqr_HashCallbacks IQR_HASH_DEFAULT_SHA2_512

Internal SHA-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 Toolkit's Hash object API.

The Hash object provides a generic interface for hashing algorithms, such as SHA-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-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.