hcg.h File Reference

Contains the public API and documentation for the HCG pseudo-random bytes generator. More...

#include "common.h"
#include "sha2.h"

Go to the source code of this file.

Data Structures
struct	qsc_hcg_state
	The HCG state structure. More...

Macros
#define	QSC_HCG_KEY_SIZE   64ULL
	The HCG internal key size.
#define	QSC_HCG_INFO_SIZE   19ULL
	The HCG default info size.
#define	QSC_HCG_MAX_INFO_SIZE   56ULL
	The HCG maximum info size.
#define	QSC_HCG_NONCE_SIZE   8ULL
	The HCG nonce size.
#define	QSC_HCG_RESEED_THRESHHOLD   65535ULL
	The HCG reseed threshold.
#define	QSC_HCG_SEED_SIZE   64ULL
	The HCG seed size.

Functions
QSC_EXPORT_API void	qsc_hcg_dispose (qsc_hcg_state *ctx)
	Dispose of the HCG DRBG state.
QSC_EXPORT_API void	qsc_hcg_initialize (qsc_hcg_state *ctx, const uint8_t *seed, size_t seedlen, const uint8_t *info, size_t infolen, bool pres)
	Initialize the pseudo-random provider state with a seed and optional personalization string.
QSC_EXPORT_API void	qsc_hcg_generate (qsc_hcg_state *ctx, uint8_t *output, size_t otplen)
	Generate pseudo-random bytes using the generator.
QSC_EXPORT_API void	qsc_hcg_update (qsc_hcg_state *ctx, const uint8_t *seed, size_t seedlen)
	Update the generator with new keying material.

Detailed Description

Contains the public API and documentation for the HCG pseudo-random bytes generator.

The HCG (HMAC-based Custom Generator) pseudo-random bytes generator is designed to produce pseudo-random bytes using an HMAC-based construction similar to the HKDF Expand key derivation function. It utilizes a 128-bit nonce, a default info parameter, and supports predictive resistance. When predictive resistance is enabled, new random seed material is injected at initialization and at defined output boundaries (default: 64 kilobytes) to convert the generator from deterministic to non-deterministic. The generator state can be updated with new seed material via the update function, and the dispose function must be called to securely erase the state.

// Example usage:
uint8_t seed[32] = { ... };
uint8_t info[32] = { ... };
 
// Allocate state and output buffer
qsc_hcg_state ctx;
uint8_t rnd[200] = { 0 };
 
// Initialize the generator with predictive resistance enabled
qsc_hcg_initialize(&ctx, seed, sizeof(seed), info, sizeof(info), true);
 
// Generate pseudo-random output
qsc_hcg_generate(&ctx, rnd, sizeof(rnd));

Reference Links:

• NIST FIPS 180-4 (SHA-2 Standard)
• RFC 2104 (HMAC)
• NIST SP 800-90A (Deterministic Random Bit Generators)

Function Documentation

qsc_hcg_dispose()

QSC_EXPORT_API void qsc_hcg_dispose

(

qsc_hcg_state *

ctx

)

Dispose of the HCG DRBG state.

Warning

The dispose function must be called when disposing of the generator.

Parameters

ctx	[qsc_hcg_state*] A pointer to the HCG state structure.

qsc_hcg_generate()

QSC_EXPORT_API void qsc_hcg_generate	(	qsc_hcg_state *	ctx,
		uint8_t *	output,
		size_t	otplen )

Generate pseudo-random bytes using the generator.

Warning

The generator must be initialized before calling this function.

Parameters

ctx	[qsc_hcg_state*] A pointer to the HCG state structure.
output	[uint8_t*] A pointer to the output buffer that will receive the pseudo-random bytes.
otplen	[size_t] The requested number of bytes to generate.

qsc_hcg_initialize()

QSC_EXPORT_API void qsc_hcg_initialize	(	qsc_hcg_state *	ctx,
		const uint8_t *	seed,
		size_t	seedlen,
		const uint8_t *	info,
		size_t	infolen,
		bool	pres )

Initialize the pseudo-random provider state with a seed and optional personalization string.

Parameters

ctx	[qsc_hcg_state*] A pointer to the HCG state structure.
seed	[const uint8_t*] A pointer to the random seed. (32 bytes instantiates a 256-bit generator; 64 bytes instantiates a 512-bit generator.)
seedlen	[size_t] The length of the input seed in bytes.
info	[const uint8_t*] A pointer to the optional personalization string.
infolen	[size_t] The length of the personalization string in bytes.
pres	[bool] Enable predictive resistance; if true, random seed material is injected periodically.

qsc_hcg_update()

QSC_EXPORT_API void qsc_hcg_update	(	qsc_hcg_state *	ctx,
		const uint8_t *	seed,
		size_t	seedlen )

Update the generator with new keying material.

The new seed material is absorbed into the HMAC state.

Parameters

ctx	[qsc_hcg_state*] A pointer to the HCG state structure.
seed	[const uint8_t*] A pointer to the random update seed.
seedlen	[size_t] The length of the update seed in bytes.