csg.h File Reference

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

#include "common.h"
#include "sha3.h"

Go to the source code of this file.

Data Structures
struct	qsc_csg_state
	The CSG state structure. More...

Macros
#define	QSC_CSG_256_SEED_SIZE   32ULL
	The CSG-256 seed size in bytes.
#define	QSC_CSG_512_SEED_SIZE   64ULL
	The CSG-512 seed size in bytes.
#define	QSC_CSG_RESEED_THRESHHOLD   1024000ULL
	The re-seed threshold interval in bytes.

Functions
QSC_EXPORT_API void	qsc_csg_dispose (qsc_csg_state *ctx)
	Dispose of the DRBG state.
QSC_EXPORT_API void	qsc_csg_initialize (qsc_csg_state *ctx, const uint8_t *seed, size_t seedlen, const uint8_t *info, size_t infolen, bool predres)
	Initialize the pseudo-random provider state with a seed and optional personalization string.
QSC_EXPORT_API void	qsc_csg_generate (qsc_csg_state *ctx, uint8_t *output, size_t otplen)
	Generate pseudo-random bytes.
QSC_EXPORT_API void	qsc_csg_update (qsc_csg_state *ctx, const uint8_t *seed, size_t seedlen)
	Update the DRBG with new seed material.

Detailed Description

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

The CSG (Custom SHAKE Generator) pseudo-random bytes generator uses the Keccak cSHAKE XOF function to produce pseudo-random bytes from seeded custom SHAKE generators. If a 32-byte seed is used, the implementation uses cSHAKE-256; if a 64-byte seed is used, cSHAKE-512 is used. An optional predictive resistance feature, enabled during initialization, injects random bytes periodically into the generator for non-deterministic output.

Example Usage:

// external key and optional custom arrays
uint8_t seed[32] = { ... };
uint8_t info[32] = { ... };
 
// random bytes
uint8_t rnd[200] = { 0 };
 
// initialize with seed and optional personalization; enable predictive resistance
qsc_csg_initialize(ctx, seed, sizeof(seed), info, sizeof(info), true);
 
// generate the pseudo-random output
qsc_csg_generate(ctx, rnd, sizeof(rnd));

Remarks

CSG uses the Keccak cSHAKE XOF function for pseudo-random generation. It caches pseudo-random bytes internally so that the generator can be reused without re-initialization in an online configuration. The generator can also be updated with new seed material.

Reference Links:

• FIPS 202: SHA-3 Standard
• NIST Special Publication 800-90A

Function Documentation

qsc_csg_dispose()

QSC_EXPORT_API void qsc_csg_dispose

(

qsc_csg_state *

ctx

)

Dispose of the DRBG state.

Securely destroys the internal state of the DRBG.

Parameters

ctx	[qsc_csg_state*] Pointer to the DRBG state structure.

qsc_csg_generate()

QSC_EXPORT_API void qsc_csg_generate	(	qsc_csg_state *	ctx,
		uint8_t *	output,
		size_t	otplen )

Generate pseudo-random bytes.

Generates pseudo-random output using the DRBG. The generator must be initialized first.

Parameters

ctx	[qsc_csg_state*] Pointer to the DRBG state structure.
output	[uint8_t*] Pointer to the output array for pseudo-random bytes.
otplen	[size_t] The number of bytes to generate.

qsc_csg_initialize()

QSC_EXPORT_API void qsc_csg_initialize	(	qsc_csg_state *	ctx,
		const uint8_t *	seed,
		size_t	seedlen,
		const uint8_t *	info,
		size_t	infolen,
		bool	predres )

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

The seed must be either 32 bytes (for a 256-bit generator) or 64 bytes (for a 512-bit generator). An optional personalization string and a predictive resistance flag may also be provided.

Parameters

ctx	[qsc_csg_state*] Pointer to the DRBG state structure.
seed	[const uint8_t*] Pointer to the random seed. (32 bytes instantiates cSHAKE-256; 64 bytes instantiates cSHAKE-512.)
seedlen	[size_t] The length of the seed in bytes.
info	[const uint8_t*] Pointer to the optional personalization string.
infolen	[size_t] The length of the personalization string in bytes.
predres	[bool] Enable predictive resistance; if true, random bytes are injected periodically.

qsc_csg_update()

QSC_EXPORT_API void qsc_csg_update	(	qsc_csg_state *	ctx,
		const uint8_t *	seed,
		size_t	seedlen )

Update the DRBG with new seed material.

The new seed material is absorbed into the Keccak state.

Parameters

ctx	[qsc_csg_state*] Pointer to the DRBG state structure.
seed	[const uint8_t*] Pointer to the update seed.
seedlen	[size_t] The length of the update seed in bytes.