An implementation of the Auto Entropy Collection Provider (ACP). More...

#include "common.h"

Macros
#define	QSC_ACP_SEED_MAX 10240000ULL
	The maximum number of bytes that can be generated in a single call to qsc_acp_generate.

Functions
QSC_EXPORT_API bool	qsc_acp_generate (uint8_t *output, size_t length)
	Generate cryptographically secure random bytes.

QSC_EXPORT_API uint16_t	qsc_acp_uint16 (void)
	Generate a cryptographically secure random 16-bit unsigned integer.

QSC_EXPORT_API uint32_t	qsc_acp_uint32 (void)
	Generate a cryptographically secure random 32-bit unsigned integer.

QSC_EXPORT_API uint64_t	qsc_acp_uint64 (void)
	Generate a cryptographically secure random 64-bit unsigned integer.

Detailed Description

An implementation of the Auto Entropy Collection Provider (ACP).

The Auto Entropy Collection Provider (ACP) is a comprehensive entropy gathering module designed to supply cryptographically secure random data. It aggregates entropy from multiple sources including system timers, system statistics, and hardware-based randomness via the RDRAND instruction. In addition, it leverages platform-specific providers such as Microsoft CryptGenRandom on Windows and /dev/urandom on POSIX systems when hardware-based sources are unavailable or insufficient. The collected entropy is processed using the cSHAKE-512 algorithm to derive a primary key that is then used to generate pseudorandom output.

Features

Aggregates entropy from system-level statistics and timers.
Integrates hardware-based randomness through the RDRAND instruction, with a fallback to system cryptographic service providers (e.g., CryptGenRandom, /dev/urandom).
Uses the cSHAKE-512 algorithm for robust key derivation and pseudorandom number generation.

Implementation Details

The ACP implementation employs a layered approach to entropy collection:

System Statistics: Uses system timestamps, computer names, process IDs, user names, and uptime.
Drive and Memory Statistics: Retrieves drive space and memory usage information.
Hardware Randomness: Utilizes the RDRAND instruction for high-quality randomness; if unavailable or failing, it falls back to the system cryptographic service provider (e.g., CryptGenRandom on Windows, /dev/urandom on POSIX systems).
Key Derivation: Aggregated entropy is processed via the cSHAKE-512 function (see qsc_cshake512_compute) to produce the final pseudorandom output.

Usage Example

#include "acp.h"
 
int main(void)
{
    uint8_t random_bytes[64];
    if (qsc_acp_generate(random_bytes, sizeof(random_bytes)))
    {
        // random_bytes now contains 64 bytes of cryptographically secure random data.
    }
 
    uint16_t rand16 = qsc_acp_uint16();
    uint32_t rand32 = qsc_acp_uint32();
    uint64_t rand64 = qsc_acp_uint64();
 
    return 0;
}

Reference Links

Macro Definition Documentation

◆ QSC_ACP_SEED_MAX

#define QSC_ACP_SEED_MAX 10240000ULL

The maximum number of bytes that can be generated in a single call to qsc_acp_generate.

This constant limits the output size to ensure that the internal entropy aggregation and key derivation process remains within safe operational parameters.

Function Documentation

◆ qsc_acp_generate()

QSC_EXPORT_API bool qsc_acp_generate	(	uint8_t *	output,
		size_t	length )

Generate cryptographically secure random bytes.

Aggregates entropy from multiple system sources including system statistics, hardware randomness (via RDRAND), and the system's cryptographic service provider. The collected entropy is then processed using the cSHAKE-512 algorithm to produce pseudorandom output.

Parameters

output	[uint8_t*] Pointer to the output buffer that will receive the random bytes.
length	[size_t] The number of random bytes to generate. Must not exceed QSC_ACP_SEED_MAX.

Returns: [bool] Returns true on success, or false if an error occurred during entropy collection or random byte generation.

See also: qsc_acp_uint16, qsc_acp_uint32, qsc_acp_uint64, qsc_cshake512_compute, qsc_rdp_generate, qsc_csp_generate

◆ qsc_acp_uint16()

QSC_EXPORT_API uint16_t qsc_acp_uint16 ( void )

Generate a cryptographically secure random 16-bit unsigned integer.

This function generates a 16-bit unsigned integer by calling qsc_acp_generate to obtain the necessary random bytes and assembling them in big-endian order.

Returns: [uint16_t] A 16-bit unsigned integer generated from high-quality random data.

See also: qsc_acp_generate

◆ qsc_acp_uint32()

QSC_EXPORT_API uint32_t qsc_acp_uint32 ( void )

Generate a cryptographically secure random 32-bit unsigned integer.

This function generates a 32-bit unsigned integer by calling qsc_acp_generate to obtain the necessary random bytes and assembling them in big-endian order.

Returns: [uint32_t] A 32-bit unsigned integer generated from high-quality random data.

See also: qsc_acp_generate

◆ qsc_acp_uint64()

QSC_EXPORT_API uint64_t qsc_acp_uint64 ( void )

Generate a cryptographically secure random 64-bit unsigned integer.

This function generates a 64-bit unsigned integer by calling qsc_acp_generate to obtain the necessary random bytes and assembling them in big-endian order.

Returns: [uint64_t] A 64-bit unsigned integer generated from high-quality random data.

See also: qsc_acp_generate

Macros

Functions