scb.h File Reference

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

#include "qsccommon.h"
#include "sha3.h"

Go to the source code of this file.

Data Structures
struct	qsc_scb_state
	The SCB state structure. More...

Macros
#define	QSC_SCB_256_SEED_SIZE   32U
	The SCB-256 seed size.
#define	QSC_SCB_512_SEED_SIZE   64U
	The SCB-512 seed size.
#define	QSC_SCB_L2CACHE_DEFAULT_SIZE   (1024ULL * 256ULL)
	The default L2 cache size (256 KiB).
#define	QSC_SCB_MEMORY_COST_SIZE   (1024ULL * 1024ULL)
	The base memory cost of 1 MiB.
#define	QSC_SCB_MEMORY_MAXIMUM   128U
	The maximum memory cost.
#define	QSC_SCB_MEMORY_MINIMUM   1U
	The minimum memory cost.
#define	QSC_SCB_CPU_MINIMUM   1U
	The minimum CPU cost multiplier.
#define	QSC_SCB_CPU_MAXIMUM   1000U
	The maximum CPU cost multiplier.

Functions
QSC_EXPORT_API void	qsc_scb_dispose (qsc_scb_state *ctx)
	[void] Dispose of the DRBG state.
QSC_EXPORT_API void	qsc_scb_initialize (qsc_scb_state *ctx, const uint8_t *seed, size_t seedlen, const uint8_t *info, size_t infolen, size_t cpucost, size_t memcost)
	[void] Initialize the pseudo-random provider state with a seed and optional personalization string.
QSC_EXPORT_API bool	qsc_scb_generate (qsc_scb_state *ctx, uint8_t *output, size_t otplen)
	[void] Generate pseudo-random bytes using the random provider.
QSC_EXPORT_API void	qsc_scb_update (qsc_scb_state *ctx, const uint8_t *seed, size_t seedlen)
	[void] Update the random provider with new keying material.

Detailed Description

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

SCB (SHAKE Cost Based Key Derivation Function) is a cost-based KDF that employs the Keccak cSHAKE XOF to generate pseudo-random bytes from a seeded custom SHAKE generator. Depending on the key length, it uses either cSHAKE-256 (for 32-byte keys) or cSHAKE-512 (for 64-byte keys). Additionally, SCB incorporates a cost mechanism with configurable CPU and memory costs to resist brute-force attacks.

Example Usage:

// External key and optional info arrays
uint8_t seed[32] = { ... };
uint8_t info[32] = { ... };
 
// Output bytes buffer
uint8_t rnd[200] = { 0U };
 
// Initialize with seed, optional info, CPU cost of 2 iterations, and memory cost of 1 MiB
qsc_scb_initialize(ctx, seed, sizeof(seed), info, sizeof(info), 2, 1);
 
// Generate pseudo-random output
qsc_scb_generate(ctx, rnd, sizeof(rnd));

Reference Links:

• SHA3 Specification (FIPS 202)
• NIST Pseudorandom Generator Guidelines (SP 800-90A)

Function Documentation

qsc_scb_dispose()

QSC_EXPORT_API void qsc_scb_dispose

(

qsc_scb_state *

ctx

)

[void] Dispose of the DRBG state.

Parameters

ctx	[qsc_scb_state*] A pointer to the DRBG state structure.

qsc_scb_generate()

QSC_EXPORT_API bool qsc_scb_generate	(	qsc_scb_state *	ctx,
		uint8_t *	output,
		size_t	otplen )

[void] Generate pseudo-random bytes using the random provider.

Parameters

ctx	[qsc_scb_state*] A pointer to the function state.
output	[uint8_t*] A pointer to the pseudo-random output array.
otplen	[size_t] The number of bytes to generate.

Returns

[bool] Returns true on success.

qsc_scb_initialize()

QSC_EXPORT_API void qsc_scb_initialize	(	qsc_scb_state *	ctx,
		const uint8_t *	seed,
		size_t	seedlen,
		const uint8_t *	info,
		size_t	infolen,
		size_t	cpucost,
		size_t	memcost )

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

Parameters

ctx	[qsc_scb_state*] A pointer to the function state.
seed	[const uint8_t*] A pointer to the random seed (32 bytes instantiates cSHAKE-256; 64 bytes instantiates cSHAKE-512).
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.
cpucost	[size_t] The number of iterations for the internal cost mechanism.
memcost	[size_t] The memory cost in mebibytes (minimum 1, maximum 10000).

qsc_scb_update()

QSC_EXPORT_API void qsc_scb_update	(	qsc_scb_state *	ctx,
		const uint8_t *	seed,
		size_t	seedlen )

[void] Update the random provider with new keying material.

Parameters

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