Generating random numbers (random_api.h)

The API is defined in the header file sysroot-*-kos/include/kos/random/random_api.h from the KasperskyOS SDK.

The API generates random numbers and includes functions that can be used to ensure high entropy (high level of unpredictability) of the seed value of the random number generator. The start number of the random number generator (seed) determines the sequence of the generated random numbers. In other words, if the same seed value is set, the generator creates identical sequences of random numbers. (The entropy of these numbers is fully determined by the entropy of the seed value, which means that these numbers are not entirely random, but pseudorandom.)

The random number generator of one process does not depend on the random number generators of other processes.

Information about API functions is provided in the table below.

Using the API

To generate a sequence of random byte values, call the KosRandomGenerate() or KosRandomGenerateEx() function.

Example use of the KosRandomGenerate() function:

size_t random_number;

if (KosRandomGenerate(sizeof random_number, &random_number) == rcOk) {

...

}

The KosRandomGenerateEx() function gets the quality level of the generated random values through the output parameter quality. The quality level can be high or low. High-quality random values are random values that are generated while fulfilling all of the following conditions:

1. When the seed value is changed, at least one entropy source is registered and data is successfully received from all registered entropy sources.

   To register the entropy source, call the KosRandomRegisterSrc() function. This function uses the callback parameter to receive the pointer to a callback function of the following type:

   typedef Retcode (*KosRandomSeedMethod)(void *context,

   rtl_size_t size,

   void *output);

   Using the context parameters, this callback function receives data with the specified size of bytes from the entropy source and writes this data to the output buffer. If the function returns rcOk, it is assumed that data was successfully received from the entropy source. An entropy source can be a digitalized signal of a sensor or a hardware-based random number generator, for example.

   To deregister an entropy source, call the KosRandomUnregisterSrc() function.

2. The random number generator is initialized if the quality level was low before changing the seed value while fulfilling condition 1.

   If the quality level is low, it cannot be changed to high without initializing the random number generator.

   To initialize a random number generator, call the KosRandomInitSeed() function. The entropy of data passed through the seed parameter must be guaranteed by the calling process.

3. The counter of random byte values that were generated after changing the seed value while fulfilling condition 1 does not exceed the system-defined limit.
4. The counter of time that has elapsed since changing the seed value while fulfilling condition 1 does not exceed the system-defined limit.

If at least one of these conditions is not fulfilled, the generated random values are deemed low-quality values.

When a process is started, the seed value is automatically defined by the system. Then the seed value is modified when doing the following:

• Generating a sequence of random values.

  Each successful call of the KosRandomGenerateEx() function with the size parameter greater than zero and each successful call of the KosRandomGenerate() function results in a change of the seed value of the random number generator, but not each seed change results in the receipt of data from registered entropy sources. The registered entropy sources are used only when condition 3 or 4 is not fulfilled. If at least one entropy source is registered, the time counter for the change in the seed value is reset. If data from at least one entropy source is successfully received, the counter of generated random byte values is also reset.

  The quality level may change from high to low.

• Initializing a random number generator.

  Each successful call of the KosRandomInitSeed() function changes the seed value by using the data that is passed through the seed parameter and received from registered entropy sources. If at least one registered entropy source is available, the counters for generated byte values and the time of a change in the seed value are reset. Otherwise, only the counter of generated random byte values is reset.

  The quality level may change from high to low, and vice versa.

• Registering an entropy source.

  Each successful call of the KosRandomRegisterSrc() function changes the seed value by using the data only from the registered entropy source. The counter of the generated random byte values is also reset.

  The quality level may not change.

A possible scenario for generating high-quality random values includes the following steps:

1. Register at least one source of entropy by calling the KosRandomRegisterSrc() function.
2. Generate a sequence of random values by calling the KosRandomGenerateEx() function.
3. Check the quality level of the random values.

   If the quality level is low, initialize the random number generator by calling the KosRandomInitSeed() function, and proceed to step 2.

   If the quality level is high, proceed to step 4.

4. Use random values.

To get the quality level without generating random values, call the KosRandomGenerateEx() function with the values 0 and RTL_NULL in the size and output parameters, respectively.

Information about API functions

random_api.h functions

Function	Information about the function
KosRandomInitSeed()	Purpose Initializes the random number generator. Parameters [in] seed – pointer to the byte array that is used to change the seed value. The array must have a size of 32 bytes. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KosRandomGenerate()	Purpose Generates a sequence of random byte values. Parameters [in] size – size (in bytes) of the buffer used to store the sequence. [out] output – pointer to the buffer used to store the sequence. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KosRandomGenerateEx()	Purpose Generates a sequence of random byte values. Parameters [in] size – size (in bytes) of the buffer used to store the sequence. [out] output – pointer to the buffer used to store the sequence. [out] quality – pointer to the boolean value that is true if the generated random values have high quality, and false if the generated random values have low quality. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KosRandomRegisterSrc()	Purpose Registers an entropy source. Parameters [in] callback – pointer to the function that receives data from the entropy source to change the seed value. [in,optional] context – pointer to the parameters passed to the function defined through the callback parameter, or RTL_NULL if there are no parameters. [in] size – size (in bytes) of the data that should be received from the entropy source when calling the function defined through the callback parameter. The size must be at least 32 bytes. [out] handle – address of the pointer used to deregister the entropy source. Returned values If successful, the function returns rcOk, otherwise it returns an error code.
KosRandomUnregisterSrc()	Purpose Deregisters the source of entropy. Parameters [in] handle – pointer that is received when registering the source of entropy. Returned values If successful, the function returns rcOk, otherwise it returns an error code.

Page top