cgul_random_bbs.h File Reference

PRNG (Blum-Blum-Shub) More...

#include "cgul_common.h"
#include "cgul_big_integer.h"
#include "cgul_exception.h"

Include dependency graph for cgul_random_bbs.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef typedefCGUL_BEGIN_C struct cgul_random_bbs *	cgul_random_bbs_t

Functions
CGUL_EXPORT cgul_random_bbs_t	cgul_random_bbs__new (cgul_exception_t *cex)
CGUL_EXPORT cgul_random_bbs_t	cgul_random_bbs__new_from_seed (cgul_exception_t *cex, cgul_big_integer_t seed)
CGUL_EXPORT void	cgul_random_bbs__delete (cgul_random_bbs_t r)
CGUL_EXPORT void	cgul_random_bbs__next (cgul_exception_t *cex, cgul_random_bbs_t r, cgul_big_integer_t next)
CGUL_EXPORT void	cgul_random_bbs__next_in_range (cgul_exception_t *cex, cgul_random_bbs_t r, cgul_big_integer_t next, cgul_big_integer_t range_max)

Detailed Description

Blum-Blum-Shub (BBS) pseudo-random number generator. This class has not been audited for security or cryptography purposes. It should only be used for general statistical purposes. Because the BBS PRNG only generates one bit per iteration, it is the slowest of the PRNGs in cgul. On the other hand, a correctly coded BBS PRNG has the best theoretical guarantee for generating random numbers.

Author

Paul Serice

Typedef Documentation

cgul_random_bbs_t

typedef typedefCGUL_BEGIN_C struct cgul_random_bbs* cgul_random_bbs_t

Opaque pointer to a cgul_random_bbs instance.

Function Documentation

cgul_random_bbs__new()

CGUL_EXPORT cgul_random_bbs_t cgul_random_bbs__new

(

cgul_exception_t *

cex

)

Create a new cgul_random_bbs object seeding it with the value returned by time(), i.e., the 32-bit seconds since the epoch. The caller is responsible for freeing the object by calling cgul_random_bbs__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.

Parameters

[in,out]

cex

c-style exception

Returns

new cgul_random_bbs instance

cgul_random_bbs__new_from_seed()

CGUL_EXPORT cgul_random_bbs_t cgul_random_bbs__new_from_seed	(	cgul_exception_t *	cex,
		cgul_big_integer_t	seed
	)

Create a new cgul_random_bbs object seeding it with the value the user passes in seed. The caller is responsible for freeing the object by calling cgul_random_bbs__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	seed	seed value

Returns

new cgul_random_bbs instance

cgul_random_bbs__delete()

CGUL_EXPORT void cgul_random_bbs__delete

(

cgul_random_bbs_t

r

)

This method frees all internally allocated memory. Do not attempt to dereference r after calling this method.

Parameters

[in]

r

cgul_random_bbs instance

cgul_random_bbs__next()

CGUL_EXPORT void cgul_random_bbs__next	(	cgul_exception_t *	cex,
		cgul_random_bbs_t	r,
		cgul_big_integer_t	next
	)

The next element in the random number sequence is returned in next. Because Blum-Blum-Shub is a bit generator, the random numbers returned are only 1-bit wide. It is possible to generate larger random numbers by calling cgul_random_bbs__next_in_range() which will assemble the larger numbers from multiple iterations of the generator.

Parameters

[in]	cex	c-style exception
[in]	r	cgul_random_bbs instance
[out]	next	next element in the random number sequence

See also

cgul_random_bbs__next_in_range()

cgul_random_bbs__next_in_range()

CGUL_EXPORT void cgul_random_bbs__next_in_range	(	cgul_exception_t *	cex,
		cgul_random_bbs_t	r,
		cgul_big_integer_t	next,
		cgul_big_integer_t	range_max
	)

If the value returned by cgul_random_bbs__next() is not the exact range that is needed, this method can limit or extend the return value to [0, range_max). If range_max is larger than the number of bits that can be generated in one iteration, multiple iterations will be used.

Parameters

[in]	cex	c-style exception
[in]	r	cgul_random_bbs instance
[out]	next	next element in the random number sequence
[in]	range_max	exclusive limit on the maximum value returned