iqr_hash.h File Reference

ISARA Radiate Quantum-Safe Library's Hash object API. More...

Data Structures
struct	iqr_HashCallbacks

Macros
#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_SHA2_256 = 2,   IQR_HASHALGO_SHA2_384 = 3,   IQR_HASHALGO_SHA2_512 = 4,   IQR_HASHALGO_SHA3_256 = 5,   IQR_HASHALGO_SHA3_512 = 6 }

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)

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

Macro Definition Documentation

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_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 another value from iqr_retval.h if 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 another value from iqr_retval.h if 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 specified 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 another value from iqr_retval.h if an error occurs.

iqr_HashDestroy()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_HashDestroy

(

iqr_Hash **

obj

)

Clear and deallocate a Hash object.

obj is 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 another value from iqr_retval.h if 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.

Parameters

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

Returns

IQR_OK on success, or another value from iqr_retval.h if 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 another value from iqr_retval.h if 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 another value from iqr_retval.h if 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().

Returns

IQR_OK on success, or another value from iqr_retval.h if 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).

Registering a hash implementation runs a known-answer test to ensure the implementation is producing valid results.

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 another value from iqr_retval.h if 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 another value from iqr_retval.h if an error occurs.

Variable Documentation

IQR_HASH_DEFAULT_SHA2_256

const IQR_EXTERN iqr_HashCallbacks IQR_HASH_DEFAULT_SHA2_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 SHA2-256 implementation.

IQR_HASH_DEFAULT_SHA2_384

const IQR_EXTERN iqr_HashCallbacks IQR_HASH_DEFAULT_SHA2_384

Internal SHA2-384 implementation.

IQR_HASH_DEFAULT_SHA2_512

const IQR_EXTERN iqr_HashCallbacks IQR_HASH_DEFAULT_SHA2_512

Internal SHA2-512 implementation.

IQR_HASH_DEFAULT_SHA3_256

const IQR_EXTERN iqr_HashCallbacks IQR_HASH_DEFAULT_SHA3_256

Internal SHA3-256 implementation.

IQR_HASH_DEFAULT_SHA3_512

const IQR_EXTERN iqr_HashCallbacks IQR_HASH_DEFAULT_SHA3_512

Internal SHA3-512 implementation.

Detailed Description

ISARA Radiate Quantum-Safe Library's Hash object API.

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

Copyright

Copyright (C) 2015-2023, 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.