Synopsis

void AddEntropy(
         CONST_APTR data,
         ULONG length,
         ULONG bits );

Function

Mix externally-gathered entropy into the resource's pool.

Drivers and other subsystems that observe unpredictable events
(interrupt timing jitter, mouse/keyboard timing, network packet
arrival, etc.) can feed those samples here to improve the quality of
the CSPRNG.  The data is folded into the pool state; it can only ever
add to, never reduce, the unpredictability of future GetEntropy()
output.

Inputs

data   - pointer to the entropy samples to mix in.
length - number of bytes at data.
bits   - the caller's (conservative) estimate of how many bits of
         true entropy the samples contain.  Used only to update the
         informational counter reported by GetEntropyInfo(); it does
         not affect how the data is mixed.

Result

None.

Notes

Safe to call from multiple tasks.  Because it obtains a semaphore it
must not be called from interrupt context; an interrupt handler should
buffer its samples and hand them over from a task.

See also

GetEntropy() GetEntropyInfo()

Synopsis

LONG GetEntropy(
         APTR buffer,
         ULONG length );

Function

Fill a buffer with cryptographically-suitable random bytes.

The bytes are produced by the resource's ChaCha20 CSPRNG, which is
reseeded on every call from the generic software collector and, on
platforms that provide one, a CPU/board hardware entropy source (for
example the x86 RDRAND/RDSEED instructions).  Hardware output is only
ever mixed into the CSPRNG, never returned verbatim, so a weak or
compromised hardware source cannot weaken the result.

Inputs

buffer - where to store the random data.
length - the number of bytes wanted.

Result

The number of bytes written to buffer (always equal to length on
success), or -1 if buffer is NULL.

Example

UBYTE key[32];
struct Library *EntropyBase = OpenResource("entropy.resource");
if (EntropyBase)
    GetEntropy(key, sizeof(key));

Notes

This function is safe to call from multiple tasks; access to the pool
is serialised internally.  It must not be called from interrupts (it
obtains a semaphore).

See also

AddEntropy() GetEntropyInfo()

Synopsis

ULONG GetEntropyInfo();

Function

Report which entropy sources the running resource is drawing on.

Inputs

None.

Result

A mask of EIF_* flags (see <resources/entropy.h>):

EIF_SOFTWARE - the generic software collector is active (always set).
EIF_HARDWARE - a dedicated CPU/board hardware entropy source is in use.

The identity of any hardware source (for example which x86 instruction
is used) is an architecture-specific implementation detail and is
deliberately not reported here.

Example

if (GetEntropyInfo() & EIF_HARDWARE)
    ; // a hardware entropy source is in use

Notes

The flags are established once at resource initialisation and do not
change, so no locking is required to read them.

See also

GetEntropy() AddEntropy()