ascon-trng.h File Reference

Access to the system's random number source. More...

#include <ascon/permutation.h>
#include "ascon-select-trng.h"

Go to the source code of this file.

Classes
struct	ascon_trng_state_t
	State of the random number source. More...

Macros
#define	ASCON_SYSTEM_SEED_SIZE   32
	Number of bytes to request from the system TRNG to seed a PRNG. More...
#define	ASCON_TRNG_MIXER_RATE   8U

Functions
int	ascon_trng_generate (unsigned char *out, size_t outlen)
	Generates a buffer of bytes from the system TRNG source. More...
int	ascon_trng_init (ascon_trng_state_t *state)
	Initializes the random number source for generating a sequence of masking material at high speed. More...
void	ascon_trng_free (ascon_trng_state_t *state)
	Frees the random number source and destroys any sensitive material. More...
uint32_t	ascon_trng_generate_32 (ascon_trng_state_t *state)
	Generates a 32-bit random value for masking operations. More...
uint64_t	ascon_trng_generate_64 (ascon_trng_state_t *state)
	Generates a 64-bit random value for masking operations. More...
int	ascon_trng_reseed (ascon_trng_state_t *state)
	Reseeds the random number source. More...

Detailed Description

Access to the system's random number source.

This is not a public API and should only be used by the library itself. Applications should use the ASCON-PRNG API instead.

The data that comes out of the system's random number source may not be very good for direct application use with non-uniform entropy distribution in the output.

If the source is embedded in a chip then the user may have reason to distrust the chip vendor.

ASCON-PRNG will destroy any watermarks from the chip vendor and spread out the entropy in the source before passing the data to the application.

The library uses this API internally for masking, so the functions ascon_trng_generate_32() and ascon_trng_generate_64() should try to generate reasonable values rapidly.

Definition in file ascon-trng.h.

Macro Definition Documentation

ASCON_SYSTEM_SEED_SIZE

#define ASCON_SYSTEM_SEED_SIZE   32

Number of bytes to request from the system TRNG to seed a PRNG.

Definition at line 58 of file ascon-trng.h.

ASCON_TRNG_MIXER_RATE

#define ASCON_TRNG_MIXER_RATE   8U

Rate of squeezing data out of the PRNG state

Definition at line 74 of file ascon-trng.h.

Function Documentation

ascon_trng_free()

void ascon_trng_free

(

ascon_trng_state_t *

state

)

Frees the random number source and destroys any sensitive material.

Parameters

state

State information for the source.

Definition at line 47 of file ascon-trng-mixer.c.

ascon_trng_generate()

int ascon_trng_generate	(	unsigned char *	out,
		size_t	outlen
	)

Generates a buffer of bytes from the system TRNG source.

Parameters

out	Output buffer to be filled with random bytes.
outlen	Length of the output buffer in bytes.

Returns

Non-zero if the system random number source is working; zero if there is no system random number source or it has failed.

This function should try to generate high quality random data even if it is a little slower.

Definition at line 192 of file ascon-trng-none.c.

ascon_trng_generate_32()

uint32_t ascon_trng_generate_32

(

ascon_trng_state_t *

state

)

Generates a 32-bit random value for masking operations.

Parameters

state

State information for the source.

Returns

A random 32-bit value.

This function must operate quickly as it is used in high frequency masking operations. The source may not be reseeded automatically.

Definition at line 53 of file ascon-trng-mixer.c.

ascon_trng_generate_64()

uint64_t ascon_trng_generate_64

(

ascon_trng_state_t *

state

)

Generates a 64-bit random value for masking operations.

Parameters

state

State information for the source.

Returns

A random 64-bit value.

This function must operate quickly as it is used in high frequency masking operations. The source may not be reseeded automatically.

Definition at line 75 of file ascon-trng-mixer.c.

ascon_trng_init()

int ascon_trng_init

(

ascon_trng_state_t *

state

)

Initializes the random number source for generating a sequence of masking material at high speed.

Parameters

state

Returns state information for accessing the source.

Returns

Non-zero if the random number source was initialized, or zero if there is no random number source available.

Definition at line 33 of file ascon-trng-mixer.c.

ascon_trng_reseed()

int ascon_trng_reseed

(

ascon_trng_state_t *

state

)

Reseeds the random number source.

Parameters

state

State information for the source.

Returns

Non-zero if we have a random number source, or zero if we don't or it is inoperable.

Not all random numbers sources require reseeding, but it is a good idea to call this on a regular basis regardless.

Definition at line 98 of file ascon-trng-mixer.c.