photon-beetle-prng.h File Reference

Pseudorandom number generator (PRNG) for PHOTON-Beetle. More...

#include <stddef.h>

Go to the source code of this file.

Data Structures
union	photon_beetle_prng_state_t
	State information for a PHOTON-256 based PRNG. More...

Functions
void	photon_beetle_prng_add_ident (const unsigned char *data, size_t size)
	Adds unique identification information for this device to the global pool. More...
int	photon_beetle_prng_init (photon_beetle_prng_state_t *state)
	Initializes a PHOTON-256 based PRNG. More...
void	photon_beetle_prng_free (photon_beetle_prng_state_t *state)
	Frees a PHOTON-256 based PRNG and destroys all sensitive information. More...
int	photon_beetle_prng_reseed (photon_beetle_prng_state_t *state)
	Forces a PHOTON-256 based PRNG to re-seed from the system TRNG. More...
void	photon_beetle_prng_feed (photon_beetle_prng_state_t *state, const unsigned char *data, size_t size)
	Feeds data into a PHOTON-256 based PRNG state to seed it from other sources besides the system TRNG. More...
int	photon_beetle_prng_fetch (photon_beetle_prng_state_t *state, unsigned char *data, size_t size)
	Fetches data from a PHOTON-256 based PRNG state. More...
int	photon_beetle_prng_generate (unsigned char *data, size_t size)
	Fetches random data using a PHOTON-256 based PRNG. More...

Detailed Description

Pseudorandom number generator (PRNG) for PHOTON-Beetle.

This PRNG implementation uses the SpongePRNG construction with PHOTON-256 as the sponge permutation.

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

Function Documentation

void photon_beetle_prng_add_ident	(	const unsigned char *	data,
		size_t	size
	)

Adds unique identification information for this device to the global pool.

Parameters

data	Points to the identification information.
size	Number of bytes of identification information.

The application should use this function at startup to add serial numbers and other unique identification information to the global pool for the PRNG. This data does not need to be secret but can help make the generated output unique for each device.

Note

This function is not thread-safe so it should be called at startup before threads start using the PRNG to generate random data.

void photon_beetle_prng_feed	(	photon_beetle_prng_state_t *	state,
		const unsigned char *	data,
		size_t	size
	)

Feeds data into a PHOTON-256 based PRNG state to seed it from other sources besides the system TRNG.

Parameters

state	PRNG state to be feed new seed data.
data	Points to the data to be fed into the PRNG state.
size	Number of bytes of data to be fed into the PRNG state.

int photon_beetle_prng_fetch	(	photon_beetle_prng_state_t *	state,
		unsigned char *	data,
		size_t	size
	)

Fetches data from a PHOTON-256 based PRNG state.

Parameters

state	PRNG state to fetch data from.
data	Points to a buffer to receive the generated random data.
size	Number of bytes of random data to be generated.

Returns

Zero if the PRNG was re-seeded from the system TRNG during the fetch but there is no system TRNG or it has failed.

void photon_beetle_prng_free

(

photon_beetle_prng_state_t *

state

)

Frees a PHOTON-256 based PRNG and destroys all sensitive information.

Parameters

state

PRNG state to be freed.

int photon_beetle_prng_generate	(	unsigned char *	data,
		size_t	size
	)

Fetches random data using a PHOTON-256 based PRNG.

Parameters

data	Points to a buffer to receive the generated random data.
size	Number of bytes of random data to be generated.

Returns

Non-zero if the PRNG was initialized from system TRNG data, or zero if there is no system TRNG or it has failed.

This function will create a temporary PRNG state object, seed it from the system TRNG, and then generate size bytes of random data. It is intended for quick one-off generation of random material.

int photon_beetle_prng_init

(

photon_beetle_prng_state_t *

state

)

Initializes a PHOTON-256 based PRNG.

Parameters

state

PRNG state to be initialized.

Returns

Non-zero if the PRNG was initialized from system TRNG data, or zero if there is no system TRNG or it has failed.

This function will fetch fresh data from the system TRNG to prepare the PRNG state to generate random data.

int photon_beetle_prng_reseed

(

photon_beetle_prng_state_t *

state

)

Forces a PHOTON-256 based PRNG to re-seed from the system TRNG.

Parameters

state

PRNG state to be re-seeded.

Returns

Non-zero if the PRNG was re-seeded from system TRNG data, or zero if there is no system TRNG or it has failed.