random.h File Reference

Pseudorandom number generator (PRNG) built around ASCON. More...

#include <ascon/xof.h>

Go to the source code of this file.

Classes
struct	ascon_random_state_t
	State information for a pseudorandom number generator. More...

Functions
int	ascon_random (unsigned char *out, size_t outlen)
	Gets a block of random data from the system. More...
int	ascon_random_init (ascon_random_state_t *state)
	Initializes a pseudorandom number generator from the system random number source. More...
void	ascon_random_free (ascon_random_state_t *state)
	Frees a pseudorandom number generator and destroys any sensitive values. More...
void	ascon_random_fetch (ascon_random_state_t *state, unsigned char *out, size_t outlen)
	Fetches data from a pseudorandom number generator. More...
int	ascon_random_reseed (ascon_random_state_t *state)
	Explicitly re-seeds a pseudorandom number generator from the system random number source. More...
void	ascon_random_feed (ascon_random_state_t *state, const unsigned char *entropy, size_t size)
	Feeds entropy into a pseudorandom number generator. More...

Detailed Description

Pseudorandom number generator (PRNG) built around ASCON.

This PRNG implementation uses the SpongePRNG construction with ASCON as the sponge permutation.

Reference: "Sponge-based pseudo-random number generators", Guido Bertoni et al, https://keccak.team/files/SpongePRNG.pdf

Definition in file random.h.

Function Documentation

ascon_random()

int ascon_random	(	unsigned char *	out,
		size_t	outlen
	)

Gets a block of random data from the system.

Parameters

out	Buffer to fill with the random data.
outlen	Number of bytes of random data to generate.

Returns

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

In the case of a zero return, the returned data may be predictable so the application should probably avoid using it.

This function does not directly return the output of the system random number source. It will process the output with ASCON-XOF to remove any watermarks or bias from untrustworthy TRNG's. And it will spread the entropy uniformly throughout the returned data.

This function is suitable for relatively rare events such as the generation of session keys or password salts. If you need a large amount of continuous random data, then use ascon_random_init() instead.

See also

ascon_random_init()

Examples

asconcrypt/asconcrypt.c.

Definition at line 27 of file ascon-random.c.

ascon_random_feed()

void ascon_random_feed	(	ascon_random_state_t *	state,
		const unsigned char *	entropy,
		size_t	size
	)

Feeds entropy into a pseudorandom number generator.

Parameters

state	The pseudorandom number generator to feed the entropy into.
entropy	Points to a buffer containing the entropy.
size	Number of bytes of entropy to add, which can be zero to "stir" the random pool but not introduce any new entropy.

This API does not keep track of how much entropy has been collected. Estimating the amount of entropy contained in noise sources is difficult and would make the API very complex.

The application can keep track of "entropy credits" itself if that is important. And then only call ascon_random_fetch() when it judges that the entropy pool is sufficiently populated.

Definition at line 135 of file ascon-prng.c.

ascon_random_fetch()

void ascon_random_fetch	(	ascon_random_state_t *	state,
		unsigned char *	out,
		size_t	outlen
	)

Fetches data from a pseudorandom number generator.

Parameters

state	The pseudorandom number generator state to use.
out	Points to a buffer to receive the random data.
outlen	Number of bytes of random data to fetch.

See also

ascon_random_reseed()

Definition at line 90 of file ascon-prng.c.

ascon_random_free()

void ascon_random_free

(

ascon_random_state_t *

state

)

Frees a pseudorandom number generator and destroys any sensitive values.

Parameters

state

The pseudorandom number generator state to free.

See also

ascon_random_init()

Definition at line 82 of file ascon-prng.c.

ascon_random_init()

int ascon_random_init

(

ascon_random_state_t *

state

)

Initializes a pseudorandom number generator from the system random number source.

Parameters

state

The pseudorandom number generator state to initialize.

Returns

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

In the case of a zero return, the returned data may be predictable so the application should avoid using the pseudorandom number generator unless it has some other source of entropy it can use.

Note

If this function returns zero, then the state is still usable to generate data at a lower level of quality. The state must be freed explicitly with ascon_random_free() regardless of the return value from this function.

See also

ascon_random_fetch(), ascon_random_feed()

Definition at line 66 of file ascon-prng.c.

ascon_random_reseed()

int ascon_random_reseed

(

ascon_random_state_t *

state

)

Explicitly re-seeds a pseudorandom number generator from the system random number source.

Parameters

state

The pseudorandom number generator to re-seed.

Returns

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

The pseudorandom number generator will be re-seeded periodically by ascon_random_fetch() but the application can choose to re-seed more often if it needs fresh random data.

See also

ascon_random_fetch()

Definition at line 116 of file ascon-prng.c.