Random Number Functions

There are two groups of random number functions in GNU MP; older functions that call C library random number generators, rely on a global state, and aren't very random; and newer functions that don't have these problems. The newer functions are self-contained, they accept a random state parameter that supplants global state, and generate good random numbers.

The random state parameter is of the type gmp_randstate_t. It must be initialized by a call to one of the gmp_randinit functions (section Random State Initialization). The initial seed is set using one of the gmp_randseed functions (section Random State Initialization).

The size of the seed determines the number of different sequences of random numbers that is possible to generate. The "quality" of the seed is the randomness of a given seed compared to the previous seed used and affects the randomness of separate number sequences.

The algorithm for assigning seed is critical if the generated random numbers are to be used for important applications, such as generating cryptographic keys.

The traditional method is to use the current system time for seeding. One has to be careful when using the current time though. If the application seeds the random functions very often, say several times per second, and the resolution of the system clock is comparatively low, like one second, the same sequence of numbers will be generated until the system clock ticks. Furthermore, the current system time is quite easy to guess, so a system depending on any unpredictability of the random number sequence should absolutely not use that as its only source for a seed value.

On some systems there is a special device, often called /dev/random, which provides a source of somewhat random numbers more usable as seed.

The functions actually generating random functions are documented under "Miscellaneous Functions" in their respective function class: section Miscellaneous Functions, section Miscellaneous Functions.

Random State Initialization

See section Random Number Functions for a discussion on how to choose the initial seed value passed to these functions.

Function: void gmp_randinit (gmp_randstate_t state, gmp_randalg_t alg, ...)

Initialize random state variable state.

alg denotes what algorithm to use for random number generation. Use one of

• GMP_RAND_ALG_LC -- Linear congruential. A fast generator defined by X = (aX + c) mod m. A third argument size of type unsigned long int is required. size is the size of the largest good quality random number to be generated, expressed in number of bits. If the random generation functions are asked for a bigger random number than indicated by this parameter, two or more numbers of size bits will be generated and concatenated, resulting in a "bad" random number. This can be used to generate big random numbers relatively cheap if the quality of randomness isn't of great importance. a, c, and m are picked from a table where the modulus (m) is a power of 2 and the multiplier is congruent to 5 (mod 8). The choice is based on the size parameter. The maximum size supported by this algorithm is 128. If you need bigger random numbers, use your own scheme and call one of the other gmp_randinit functions.

If alg is 0 or GMP_RAND_ALG_DEFAULT, the default algorithm is used. The default algorithm is typically a fast algorithm like the linear congruential and requires a third size argument (see GMP_RAND_ALG_LC).

When you're done with a state variable, call gmp_randclear to deallocate any memory allocated by this function.

gmp_randinit may set the following bits in gmp_errno:

• GMP_ERROR_UNSUPPORTED_ARGUMENT -- alg is unsupported
• GMP_ERROR_INVALID_ARGUMENT -- size is too big

Function: void gmp_randinit_lc_2exp (gmp_randstate_t state, mpz_t a,

unsigned long int c, unsigned long int m2exp)

Initialize random state variable state with given linear congruential scheme.

Parameters a, c, and m2exp are the multiplier, adder, and modulus for the linear congruential scheme to use, respectively. The modulus is expressed as a power of 2, so that @ifnottex m = 2^m2exp.

The least significant bits of a random number generated by the linear congruential algorithm where the modulus is a power of two are not very random. Therefore, the lower half of a random number generated by an LC scheme initialized with this function is discarded. Thus, the size of a random number is m2exp / 2 (rounded upwards) bits when this function has been used for initializing the random state.

When you're done with a state variable, call gmp_randclear to deallocate any memory allocated by this function.

Function: void gmp_randseed (gmp_randstate_t state, mpz_t seed)

Function: void gmp_randseed_ui (gmp_randstate_t state, unsigned long int seed)

Set the initial seed value.

Parameter seed is the initial random seed. The function gmp_randseed_ui takes the seed as an unsigned long int rather than as an mpz_t.

Function: void gmp_randclear (gmp_randstate_t state)

Free all memory occupied by state. Make sure to call this function for all gmp_randstate_t variables when you are done with them.

Go to the first, previous, next, last section, table of contents.