Генерация случайных чисел (random_api.h)

API определен в заголовочном файле sysroot-*-kos/include/kos/random/random_api.h из состава KasperskyOS SDK.

API позволяет генерировать случайные числа, а также включает функции, которые можно использовать, чтобы обеспечить высокую энтропию (высокий уровень непредсказуемости) начального значения генератора случайных чисел. Начальное значение генератора случайных чисел (англ. seed) определяет последовательность генерируемых случайных чисел. То есть после установки одного и того же начального значения генератор создает одинаковые последовательности случайных чисел. (Энтропия таких чисел полностью определяется энтропией начального значения, поэтому точнее их называть не случайными, а псевдослучайными.)

Генератор случайных чисел одного процесса не зависит от генераторов случайных чисел других процессов.

Сведения о функциях API приведены в таблице ниже.

Использование API

Чтобы сгенерировать последовательность случайных байтовых значений, нужно вызвать функцию KosRandomGenerate() или KosRandomGenerateEx().

Пример использования функции KosRandomGenerate():

size_t random_number;

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

...

}

Функция KosRandomGenerateEx() позволяет получить уровень качества сгенерированных случайных значений через выходной параметр quality. Уровень качества может быть высоким или низким. Высококачественными считаются случайные значения, которые сгенерированы при выполнении всех следующих условий:

1. На момент изменения начального значения генератора случайных чисел зарегистрирован хотя бы один источник энтропии, и успешно получены данные из всех зарегистрированных источников энтропии.

   Чтобы зарегистрировать источник энтропии, нужно вызвать функцию KosRandomRegisterSrc(). Через параметр callback эта функция принимает указатель на callback-функцию следующего типа:

   typedef Retcode (*KosRandomSeedMethod)(void *context,

   rtl_size_t size,

   void *output);

   Эта callback-функция должна, используя параметры context, получить данные размером size байт из источника энтропии и записать их в буфер output. Если функция возвращает rcOk, то считается, что данные из источника энтропии были получены успешно. Источником энтропии может быть, например, оцифрованный сигнал какого-либо датчика или аппаратный генератор случайных чисел.

   Чтобы дерегистрировать источник энтропии, нужно вызвать функцию KosRandomUnregisterSrc().

2. Выполнена инициализация генератора случайных чисел, если до изменения начального значения генератора случайных чисел с выполнением условия 1 уровень качества был низким.

   Если уровень качества низкий, то сделать его высоким без инициализации генератора случайных чисел нельзя.

   Чтобы инициализировать генератор случайных чисел, нужно вызвать функцию KosRandomInitSeed(). Энтропию данных, передаваемых через параметр seed, должен гарантировать вызывающий процесс.

3. Счетчик случайных байтовых значений, которые сгенерированы после изменения начального значения генератора случайных чисел с выполнением условия 1, не превышает заданный в системе лимит.
4. Счетчик времени, которое прошло после изменения начального значения генератора случайных чисел с выполнением условия 1, не превышает заданный в системе лимит.

Если хотя бы одно из этих условий не выполняется, сгенерированные случайные значения считаются низкокачественными.

При запуске процесса начальное значение генератора случайных чисел задается системой автоматически. Затем начальное значение генератора случайных чисел изменяется в следующих случаях:

• Генерация последовательности случайных значений.

  Каждый успешный вызов функции KosRandomGenerateEx() с параметром size больше нуля и каждый успешный вызов функции KosRandomGenerate() изменяют начальное значение генератора случайных чисел, но не каждое такое изменение выполняется с получением данных из зарегистрированных источников энтропии. Зарегистрированные источники энтропии используются только при нарушении условия 3 или 4. При этом, если зарегистрирован хотя бы один источник энтропии, то сбрасывается счетчик времени изменения начального значения генератора случайных чисел. А если данные из хотя бы одного источника энтропии получены успешно, то также сбрасывается счетчик сгенерированных случайных байтовых значений.

  Уровень качества может измениться с высокого на низкий.

• Инициализация генератора случайных чисел.

  Каждый успешный вызов функции KosRandomInitSeed() изменяет начальное значение генератора случайных чисел, используя данные, переданные через параметр seed и полученные из зарегистрированных источников энтропии. При наличии хотя бы одного зарегистрированного источника энтропии сбрасываются счетчики сгенерированных случайных байтовых значений и времени изменения начального значения генератора случайных чисел. В противном случае сбрасывается только счетчик сгенерированных случайных байтовых значений.

  Уровень качества может измениться с высокого на низкий и наоборот.

• Регистрация источника энтропии.

  Каждый успешный вызов функции KosRandomRegisterSrc() изменяет начальное значение генератора случайных чисел, используя данные только из регистрируемого источника энтропии. При этом сбрасывается счетчик сгенерированных случайных байтовых значений.

  Уровень качества не может измениться.

Возможный сценарий генерации случайных значений высокого качества включает следующие шаги:

1. Зарегистрировать хотя бы один источник энтропии вызовом функции KosRandomRegisterSrc().
2. Сгенерировать последовательность случайных значений вызовом функции KosRandomGenerateEx().
3. Проверить уровень качества случайных значений.

   Если уровень качества низкий, инициализировать генератор случайных чисел вызовом функции KosRandomInitSeed() и перейти к шагу 2.

   Если уровень качестве высокий, перейти к шагу 4.

4. Использовать случайные значения.

Чтобы получить уровень качества без генерации случайных значений, нужно вызвать функцию KosRandomGenerateEx() со значениями 0 и RTL_NULL в параметрах size и output соответственно.

Сведения о функциях API

Функции random_api.h

Функция	Сведения о функции
KosRandomInitSeed()	Назначение Инициализирует генератор случайных чисел. Параметры [in] seed – указатель на байтовый массив, который используется, чтобы изменить начальное значение генератора случайных чисел. Массив должен иметь размер 32 байта. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosRandomGenerate()	Назначение Генерирует последовательность случайных байтовых значений. Параметры [in] size – размер буфера для сохранения последовательности (в байтах). [out] output – указатель на буфер для сохранения последовательности. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosRandomGenerateEx()	Назначение Генерирует последовательность случайных байтовых значений. Параметры [in] size – размер буфера для сохранения последовательности (в байтах). [out] output – указатель на буфер для сохранения последовательности. [out] quality – указатель на булевое значение, которое истинно, если сгенерированные случайные значения имеют высокое качество, и ложно, если сгенерированные случайные значения имеют низкое качество. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosRandomRegisterSrc()	Назначение Регистрирует источник энтропии. Параметры [in] callback – указатель на функцию, которая позволяет получить данные из источника энтропии для изменения начального значения генератора случайных чисел. [in,optional] context – указатель на параметры, передаваемые функции, заданной через параметр callback, или RTL_NULL, если параметров нет. [in] size – размер данных (в байтах), которые нужно получить из источника энтропии при вызове функции, заданной через параметр callback. Должен быть не менее 32 байт. [out] handle – адрес указателя, используемого для дерегистрации источника энтропии. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.
KosRandomUnregisterSrc()	Назначение Дерегистрирует источник энтропии. Параметры [in] handle – указатель, который получен при регистрации источника энтропии. Возвращаемые значения В случае успеха возвращает rcOk, иначе возвращает код ошибки.

В начало