The SHA2 family of hash functions. More...

#include "common.h"

Data Structures
struct	qsc_sha256_state
	The SHA2-256 digest state array. More...

struct	qsc_sha384_state
	The SHA2-384 digest state array. More...

struct	qsc_sha512_state
	The SHA2-512 digest state array. More...

struct	qsc_hmac256_state
	The HMAC(SHA2-256) state array. More...

struct	qsc_hmac512_state
	The HMAC(SHA2-512) state array. More...

Macros
#define	QSC_HKDF_256_KEY_SIZE 32ULL
	The HKDF-256 key size in bytes.

#define	QSC_HKDF_512_KEY_SIZE 64ULL
	The HKDF-512 key size in bytes.

#define	QSC_HMAC_256_KEY_SIZE 32ULL
	The recommended HMAC(SHA2-256) key size, minimum is 32 bytes.

#define	QSC_HMAC_512_KEY_SIZE 64ULL
	The recommended HMAC(SHA2-512) key size, minimum is 64 bytes.

#define	QSC_HMAC_256_MAC_SIZE 32ULL
	The HMAC-256 mac-code size in bytes.

#define	QSC_HMAC_512_MAC_SIZE 64ULL
	The HMAC-512 mac-code size in bytes.

#define	QSC_HMAC_256_RATE 64ULL
	The HMAC-256 input rate size in bytes.

#define	QSC_HMAC_512_RATE 128ULL
	The HMAC-512 input rate size in bytes.

#define	QSC_SHA2_256_HASH_SIZE 32ULL
	The SHA2-256 hash size in bytes.

#define	QSC_SHA2_384_HASH_SIZE 48ULL
	The SHA2-384 hash size in bytes.

#define	QSC_SHA2_512_HASH_SIZE 64ULL
	The SHA2-512 hash size in bytes.

#define	QSC_SHA2_256_RATE 64ULL
	The SHA2-256 absorption rate in bytes.

#define	QSC_SHA2_384_RATE 128ULL
	The SHA2-384 absorption rate in bytes.

#define	QSC_SHA2_512_RATE 128ULL
	The SHA2-512 absorption rate in bytes.

#define	QSC_SHA2_STATE_SIZE 8ULL
	The SHA2 state array size.

Functions
QSC_EXPORT_API void	qsc_sha256_compute (uint8_t output, const uint8_t message, size_t msglen)
	Process a message with SHA2-256 and return the hash code in the output byte array.

QSC_EXPORT_API void	qsc_sha256_dispose (qsc_sha256_state *ctx)
	Dispose of the SHA2-256 state.

QSC_EXPORT_API void	qsc_sha256_finalize (qsc_sha256_state ctx, uint8_t output)
	Finalize the message state and return the hash value in the output array.

QSC_EXPORT_API void	qsc_sha256_initialize (qsc_sha256_state *ctx)
	Initialize a SHA2-256 state structure.

QSC_EXPORT_API void	qsc_sha256_permute (uint32_t output, const uint8_t input)
	The SHA2-256 permutation function.

QSC_EXPORT_API void	qsc_sha256_update (qsc_sha256_state ctx, const uint8_t message, size_t msglen)
	Update SHA2-256 with message input.

QSC_EXPORT_API void	qsc_sha384_compute (uint8_t output, const uint8_t message, size_t msglen)
	Process a message with SHA2-384 and return the hash code in the output byte array.

QSC_EXPORT_API void	qsc_sha384_dispose (qsc_sha384_state *ctx)
	Dispose of the SHA2-384 state.

QSC_EXPORT_API void	qsc_sha384_finalize (qsc_sha384_state ctx, uint8_t output)
	Finalize the SHA2-384 state and return the hash value in the output array.

QSC_EXPORT_API void	qsc_sha384_initialize (qsc_sha384_state *ctx)
	Initialize a SHA2-384 state structure.

QSC_EXPORT_API void	qsc_sha384_update (qsc_sha384_state ctx, const uint8_t message, size_t msglen)
	Update SHA2-384 with message input.

QSC_EXPORT_API void	qsc_sha512_compute (uint8_t output, const uint8_t message, size_t msglen)
	Process a message with SHA2-512 and return the hash code in the output byte array.

QSC_EXPORT_API void	qsc_sha512_dispose (qsc_sha512_state *ctx)
	Dispose of the SHA2-512 state.

QSC_EXPORT_API void	qsc_sha512_finalize (qsc_sha512_state ctx, uint8_t output)
	Finalize the SHA2-512 state and return the hash value in the output array.

QSC_EXPORT_API void	qsc_sha512_initialize (qsc_sha512_state *ctx)
	Initialize a SHA2-512 state structure.

QSC_EXPORT_API void	qsc_sha512_permute (uint64_t output, const uint8_t input)
	The SHA2-512 permutation function.

QSC_EXPORT_API void	qsc_sha512_update (qsc_sha512_state ctx, const uint8_t message, size_t msglen)
	Update SHA2-512 with message input.

QSC_EXPORT_API void	qsc_hmac256_compute (uint8_t output, const uint8_t message, size_t msglen, const uint8_t *key, size_t keylen)
	Process a message with HMAC(SHA2-256) and return the MAC code in the output byte array.

QSC_EXPORT_API void	qsc_hmac256_dispose (qsc_hmac256_state *ctx)
	Dispose of the HMAC-256 state.

QSC_EXPORT_API void	qsc_hmac256_finalize (qsc_hmac256_state ctx, uint8_t output)
	Finalize the HMAC-256 state and return the MAC code in the output byte array.

QSC_EXPORT_API void	qsc_hmac256_initialize (qsc_hmac256_state ctx, const uint8_t key, size_t keylen)
	Initialize an HMAC-256 state structure with a key.

QSC_EXPORT_API void	qsc_hmac256_update (qsc_hmac256_state ctx, const uint8_t message, size_t msglen)
	Update HMAC-256 with message input.

QSC_EXPORT_API void	qsc_hmac512_compute (uint8_t output, const uint8_t message, size_t msglen, const uint8_t *key, size_t keylen)
	Process a message with HMAC(SHA2-512) and return the MAC code in the output byte array.

QSC_EXPORT_API void	qsc_hmac512_dispose (qsc_hmac512_state *ctx)
	Dispose of the HMAC-512 state.

QSC_EXPORT_API void	qsc_hmac512_finalize (qsc_hmac512_state ctx, uint8_t output)
	Finalize the HMAC-512 state and return the MAC code in the output byte array.

QSC_EXPORT_API void	qsc_hmac512_initialize (qsc_hmac512_state ctx, const uint8_t key, size_t keylen)
	Initialize an HMAC-512 state structure with a key.

QSC_EXPORT_API void	qsc_hmac512_update (qsc_hmac512_state ctx, const uint8_t message, size_t msglen)
	Update HMAC-512 with message input.

QSC_EXPORT_API void	qsc_hkdf256_expand (uint8_t output, size_t otplen, const uint8_t key, size_t keylen, const uint8_t *info, size_t infolen)
	Initialize an instance of HKDF(HMAC(SHA2-256)) and generate pseudo-random output.

QSC_EXPORT_API void	qsc_hkdf256_extract (uint8_t output, size_t otplen, const uint8_t key, size_t keylen, const uint8_t *salt, size_t saltlen)
	Extract a key from a combined key and salt input using HMAC(SHA2-256).

QSC_EXPORT_API void	qsc_hkdf512_expand (uint8_t output, size_t otplen, const uint8_t key, size_t keylen, const uint8_t *info, size_t infolen)
	Initialize an instance of HKDF(HMAC(SHA2-512)) and generate pseudo-random output.

QSC_EXPORT_API void	qsc_hkdf512_extract (uint8_t output, size_t otplen, const uint8_t key, size_t keylen, const uint8_t *salt, size_t saltlen)
	Extract a key from a combined key and salt input using HMAC(SHA2-512).

Detailed Description

The SHA2 family of hash functions.

This header contains the public API and documentation for the SHA2 digest functions, HMAC, and HKDF implementations. It supports SHA2-256, SHA2-384, and SHA2-512 variants. The API includes both short-form functions (processing the complete message in one call) and long-form functions (initialize, update, finalize) for incremental processing.

Example for SHA2-512 using the long-form API:

#define MSGLEN 200
uint8_t msg[MSGLEN] = { ... };
uint8_t otp[QSC_SHA2_512_HASH_SIZE] = { 0 };
qsc_sha512_state ctx;
 
qsc_sha512_initialize(&ctx);
qsc_sha512_update(&ctx, msg, MSGLEN);
qsc_sha512_finalize(&ctx, otp);

Reference Links:

Function Documentation

◆ qsc_hkdf256_expand()

QSC_EXPORT_API void qsc_hkdf256_expand	(	uint8_t *	output,
		size_t	otplen,
		const uint8_t *	key,
		size_t	keylen,
		const uint8_t *	info,
		size_t	infolen )

Initialize an instance of HKDF(HMAC(SHA2-256)) and generate pseudo-random output.

Parameters

output	[uint8_t*] The output pseudo-random byte array.
otplen	[size_t] The output array length.
key	[const uint8_t*] The HKDF key array.
keylen	[size_t] The key array length.
info	[const uint8_t*] The info array.
infolen	[size_t] The info array length.

◆ qsc_hkdf256_extract()

QSC_EXPORT_API void qsc_hkdf256_extract	(	uint8_t *	output,
		size_t	otplen,
		const uint8_t *	key,
		size_t	keylen,
		const uint8_t *	salt,
		size_t	saltlen )

Extract a key from a combined key and salt input using HMAC(SHA2-256).

Parameters

output	[uint8_t*] The output pseudo-random byte array.
otplen	[size_t] The output array length.
key	[const uint8_t*] The HKDF key array.
keylen	[size_t] The key array length.
salt	[const uint8_t*] The salt array.
saltlen	[size_t] The salt array length.

◆ qsc_hkdf512_expand()

QSC_EXPORT_API void qsc_hkdf512_expand	(	uint8_t *	output,
		size_t	otplen,
		const uint8_t *	key,
		size_t	keylen,
		const uint8_t *	info,
		size_t	infolen )

Initialize an instance of HKDF(HMAC(SHA2-512)) and generate pseudo-random output.

Parameters

output	[uint8_t*] The output pseudo-random byte array.
otplen	[size_t] The output array length.
key	[const uint8_t*] The HKDF key array.
keylen	[size_t] The key array length.
info	[const uint8_t*] The info array.
infolen	[size_t] The info array length.

◆ qsc_hkdf512_extract()

QSC_EXPORT_API void qsc_hkdf512_extract	(	uint8_t *	output,
		size_t	otplen,
		const uint8_t *	key,
		size_t	keylen,
		const uint8_t *	salt,
		size_t	saltlen )

Extract a key from a combined key and salt input using HMAC(SHA2-512).

Parameters

output	[uint8_t*] The output pseudo-random byte array.
otplen	[size_t] The output array length.
key	[const uint8_t*] The HKDF key array.
keylen	[size_t] The key array length.
salt	[const uint8_t*] The salt array.
saltlen	[size_t] The salt array length.

◆ qsc_hmac256_compute()

QSC_EXPORT_API void qsc_hmac256_compute	(	uint8_t *	output,
		const uint8_t *	message,
		size_t	msglen,
		const uint8_t *	key,
		size_t	keylen )

Process a message with HMAC(SHA2-256) and return the MAC code in the output byte array.

Warning: The output array must be at least 32 bytes in length.

Parameters

output	[uint8_t*] The output byte array; receives the MAC code.
message	[const uint8_t*] The message input byte array.
msglen	[size_t] The number of message bytes to process.
key	[const uint8_t*] The secret key array.
keylen	[size_t] The key array length.

◆ qsc_hmac256_dispose()

QSC_EXPORT_API void qsc_hmac256_dispose ( qsc_hmac256_state * ctx )

Dispose of the HMAC-256 state.

Parameters

ctx	[qsc_hmac256_state*] Pointer to the MAC state structure.

◆ qsc_hmac256_finalize()

QSC_EXPORT_API void qsc_hmac256_finalize	(	qsc_hmac256_state *	ctx,
		uint8_t *	output )

Finalize the HMAC-256 state and return the MAC code in the output byte array.

Warning: The output array must be sized correctly. Finalizes the message state; cannot be used in consecutive calls. The state must be initialized by the caller.

Parameters

ctx	[qsc_hmac256_state*] Pointer to the MAC state structure; must be initialized.
output	[uint8_t*] The output byte array; receives the MAC code.

◆ qsc_hmac256_initialize()

QSC_EXPORT_API void qsc_hmac256_initialize	(	qsc_hmac256_state *	ctx,
		const uint8_t *	key,
		size_t	keylen )

Initialize an HMAC-256 state structure with a key.

Parameters

ctx	[qsc_hmac256_state*] Pointer to the MAC state structure.
key	[const uint8_t*] Pointer to the secret key array.
keylen	[size_t] The key array length.

◆ qsc_hmac256_update()

QSC_EXPORT_API void qsc_hmac256_update	(	qsc_hmac256_state *	ctx,
		const uint8_t *	message,
		size_t	msglen )

Update HMAC-256 with message input.

Warning: State must be initialized by the caller.

Parameters

ctx	[qsc_hmac256_state*] Pointer to the MAC state structure.
message	[const uint8_t*] The input message byte array.
msglen	[size_t] The number of message bytes to process.

◆ qsc_hmac512_compute()

QSC_EXPORT_API void qsc_hmac512_compute	(	uint8_t *	output,
		const uint8_t *	message,
		size_t	msglen,
		const uint8_t *	key,
		size_t	keylen )

Process a message with HMAC(SHA2-512) and return the MAC code in the output byte array.

Warning: The output array must be at least 64 bytes in length.

Parameters

output	[uint8_t*] The output byte array; receives the MAC code.
message	[const uint8_t*] The message input byte array.
msglen	[size_t] The number of message bytes to process.
key	[const uint8_t*] The secret key array.
keylen	[size_t] The key array length.

◆ qsc_hmac512_dispose()

QSC_EXPORT_API void qsc_hmac512_dispose ( qsc_hmac512_state * ctx )

Dispose of the HMAC-512 state.

Parameters

ctx	[qsc_hmac512_state*] Pointer to the MAC state structure.

◆ qsc_hmac512_finalize()

QSC_EXPORT_API void qsc_hmac512_finalize	(	qsc_hmac512_state *	ctx,
		uint8_t *	output )

Finalize the HMAC-512 state and return the MAC code in the output byte array.

Warning: The output array must be sized correctly. Finalizes the message state; cannot be used in consecutive calls. The state must be initialized by the caller.

Parameters

ctx	[qsc_hmac512_state*] Pointer to the MAC state structure; must be initialized.
output	[uint8_t*] The output byte array; receives the MAC code.

◆ qsc_hmac512_initialize()

QSC_EXPORT_API void qsc_hmac512_initialize	(	qsc_hmac512_state *	ctx,
		const uint8_t *	key,
		size_t	keylen )

Initialize an HMAC-512 state structure with a key.

Parameters

ctx	[qsc_hmac512_state*] Pointer to the MAC state structure.
key	[const uint8_t*] Pointer to the secret key array.
keylen	[size_t] The key array length.

◆ qsc_hmac512_update()

QSC_EXPORT_API void qsc_hmac512_update	(	qsc_hmac512_state *	ctx,
		const uint8_t *	message,
		size_t	msglen )

Update HMAC-512 with message input.

Warning: State must be initialized by the caller.

Parameters

ctx	[qsc_hmac512_state*] Pointer to the MAC state structure.
message	[const uint8_t*] The input message byte array.
msglen	[size_t] The number of message bytes to process.

◆ qsc_sha256_compute()

QSC_EXPORT_API void qsc_sha256_compute	(	uint8_t *	output,
		const uint8_t *	message,
		size_t	msglen )

Process a message with SHA2-256 and return the hash code in the output byte array.

Parameters

output	[uint8_t*] The output byte array; receives the hash code.
message	[const uint8_t*] The message input byte array.
msglen	[size_t] The number of message bytes to process.

◆ qsc_sha256_dispose()

QSC_EXPORT_API void qsc_sha256_dispose ( qsc_sha256_state * ctx )

Dispose of the SHA2-256 state.

Parameters

ctx	[qsc_sha256_state*] Pointer to the cipher state structure.

◆ qsc_sha256_finalize()

QSC_EXPORT_API void qsc_sha256_finalize	(	qsc_sha256_state *	ctx,
		uint8_t *	output )

Finalize the message state and return the hash value in the output array.

Warning: The output array must be sized correctly. Finalizes the message state; cannot be used in consecutive calls. The state must be initialized by the caller.

Parameters

ctx	[qsc_sha256_state*] Pointer to the function state; must be initialized.
output	[uint8_t*] The output byte array; receives the hash code.

◆ qsc_sha256_initialize()

QSC_EXPORT_API void qsc_sha256_initialize ( qsc_sha256_state * ctx )

Initialize a SHA2-256 state structure.

Parameters

ctx	[qsc_sha256_state*] Pointer to the function state.

◆ qsc_sha256_permute()

QSC_EXPORT_API void qsc_sha256_permute	(	uint32_t *	output,
		const uint8_t *	input )

The SHA2-256 permutation function.

Internal function: Called by protocol hash and generation functions, or in the construction of other external protocols. Absorbs a message and permutes the state array.

Parameters

output	[uint32_t*] The function output; must be initialized.
input	[const uint8_t*] The input message byte array.

◆ qsc_sha256_update()

QSC_EXPORT_API void qsc_sha256_update	(	qsc_sha256_state *	ctx,
		const uint8_t *	message,
		size_t	msglen )

Update SHA2-256 with message input.

Warning: State must be initialized by the caller.

Parameters

ctx	[qsc_sha256_state*] Pointer to the function state.
message	[const uint8_t*] The input message byte array.
msglen	[size_t] The number of message bytes to process.

◆ qsc_sha384_compute()

QSC_EXPORT_API void qsc_sha384_compute	(	uint8_t *	output,
		const uint8_t *	message,
		size_t	msglen )

Process a message with SHA2-384 and return the hash code in the output byte array.

Warning: The output array must be at least 48 bytes in length.

Parameters

output	[uint8_t*] The output byte array; receives the hash code.
message	[const uint8_t*] The message input byte array.
msglen	[size_t] The number of message bytes to process.

◆ qsc_sha384_dispose()

QSC_EXPORT_API void qsc_sha384_dispose ( qsc_sha384_state * ctx )

Dispose of the SHA2-384 state.

Parameters

ctx	[qsc_sha384_state*] Pointer to the cipher state structure.

◆ qsc_sha384_finalize()

QSC_EXPORT_API void qsc_sha384_finalize	(	qsc_sha384_state *	ctx,
		uint8_t *	output )

Finalize the SHA2-384 state and return the hash value in the output array.

Warning: The output array must be sized correctly. Finalizes the message state; cannot be used in consecutive calls. The state must be initialized by the caller.

Parameters

ctx	[qsc_sha384_state*] Pointer to the function state; must be initialized.
output	[uint8_t*] The output byte array; receives the hash code.

◆ qsc_sha384_initialize()

QSC_EXPORT_API void qsc_sha384_initialize ( qsc_sha384_state * ctx )

Initialize a SHA2-384 state structure.

Parameters

ctx	[qsc_sha384_state*] Pointer to the function state.

◆ qsc_sha384_update()

QSC_EXPORT_API void qsc_sha384_update	(	qsc_sha384_state *	ctx,
		const uint8_t *	message,
		size_t	msglen )

Update SHA2-384 with message input.

Warning: State must be initialized by the caller.

Parameters

ctx	[qsc_sha384_state*] Pointer to the function state.
message	[const uint8_t*] The input message byte array.
msglen	[size_t] The number of message bytes to process.

◆ qsc_sha512_compute()

QSC_EXPORT_API void qsc_sha512_compute	(	uint8_t *	output,
		const uint8_t *	message,
		size_t	msglen )

Process a message with SHA2-512 and return the hash code in the output byte array.

Warning: The output array must be at least 64 bytes in length.

Parameters

output	[uint8_t*] The output byte array; receives the hash code.
message	[const uint8_t*] The message input byte array.
msglen	[size_t] The number of message bytes to process.

◆ qsc_sha512_dispose()

QSC_EXPORT_API void qsc_sha512_dispose ( qsc_sha512_state * ctx )

Dispose of the SHA2-512 state.

Parameters

ctx	[qsc_sha512_state*] Pointer to the cipher state structure.

◆ qsc_sha512_finalize()

QSC_EXPORT_API void qsc_sha512_finalize	(	qsc_sha512_state *	ctx,
		uint8_t *	output )

Finalize the SHA2-512 state and return the hash value in the output array.

Warning: The output array must be sized correctly. Finalizes the message state; cannot be used in consecutive calls. The state must be initialized by the caller.

Parameters

ctx	[qsc_sha512_state*] Pointer to the function state; must be initialized.
output	[uint8_t*] The output byte array; receives the hash code.

◆ qsc_sha512_initialize()

QSC_EXPORT_API void qsc_sha512_initialize ( qsc_sha512_state * ctx )

Initialize a SHA2-512 state structure.

Parameters

ctx	[qsc_sha512_state*] Pointer to the function state.

◆ qsc_sha512_permute()

QSC_EXPORT_API void qsc_sha512_permute	(	uint64_t *	output,
		const uint8_t *	input )

The SHA2-512 permutation function.

Internal function: Called by protocol hash and generation functions, or in the construction of other external protocols. Absorbs a message and permutes the state array.

Parameters

output	[uint64_t*] The function output; must be initialized.
input	[const uint8_t*] The input message byte array.

◆ qsc_sha512_update()

QSC_EXPORT_API void qsc_sha512_update	(	qsc_sha512_state *	ctx,
		const uint8_t *	message,
		size_t	msglen )

Update SHA2-512 with message input.

Warning: State must be initialized by the caller.

Parameters

ctx	[qsc_sha512_state*] Pointer to the function state.
message	[const uint8_t*] The input message byte array.
msglen	[size_t] The number of message bytes to process.

Data Structures

Macros

Functions

Detailed Description

Reference Links:

Function Documentation

◆ qsc_hkdf256_expand()

◆ qsc_hkdf256_extract()

◆ qsc_hkdf512_expand()

◆ qsc_hkdf512_extract()

◆ qsc_hmac256_compute()

◆ qsc_hmac256_dispose()

◆ qsc_hmac256_finalize()

◆ qsc_hmac256_initialize()

◆ qsc_hmac256_update()

◆ qsc_hmac512_compute()

◆ qsc_hmac512_dispose()

◆ qsc_hmac512_finalize()

◆ qsc_hmac512_initialize()

◆ qsc_hmac512_update()

◆ qsc_sha256_compute()

◆ qsc_sha256_dispose()

◆ qsc_sha256_finalize()

◆ qsc_sha256_initialize()

◆ qsc_sha256_permute()

◆ qsc_sha256_update()

◆ qsc_sha384_compute()

◆ qsc_sha384_dispose()

◆ qsc_sha384_finalize()

◆ qsc_sha384_initialize()

◆ qsc_sha384_update()

◆ qsc_sha512_compute()

◆ qsc_sha512_dispose()

◆ qsc_sha512_finalize()

◆ qsc_sha512_initialize()

◆ qsc_sha512_permute()

◆ qsc_sha512_update()