rng.h - Man Page

Источники случайности и генераторы случайных чисел

Synopsis

#include 'bee2/defs.h'

Функции

err_t rngReadSource (size_t *read, void *buf, size_t count, const char *source_name)
Получение данных от источников случайности
bool_t rngTestFIPS1 (const octet buf[2500])
Тест знаков FIPS 140.
bool_t rngTestFIPS2 (const octet buf[2500])
Покер-тест FIPS 140.
bool_t rngTestFIPS3 (const octet buf[2500])
Тест серий FIPS 140.
bool_t rngTestFIPS4 (const octet buf[2500])
Тест длинных серий FIPS 140.
err_t rngCreate (read_i source, void *source_state)
Создание генератора
bool_t rngIsValid ()
Корректный генератор?
void rngStepR (void *buf, size_t count, void *state)
Генерация случайных чисел
void rngStepR2 (void *buf, size_t count, void *state)
Облегченная генерация случайных чисел
void rngClose ()
Закрытие генератора

Подробное описание

Источники случайности

В системе может быть несколько источников случайности. Получение данных от источников реализуется через интерфейс read_i. Внутренние источники поддерживаются функцией rngReadSource().

При обработке запроса на чтение данных источники обрабатывает свои наблюдения, учитывая оценки энтропии. При необходимости наблюдения сжимаются. В результате обработки запроса будут возвращены высокоэнтропийные данные. Их объем может быть меньше запрошенного.

При обработке запроса может произойти сбой источника или время снятия наблюдений может оказаться неприемлемо большим. В таких случаях также будет возвращено меньше данных, чем запрашивалось.

Статистическое тестирование

Реализованы статистические тесты стандарта FIPS 140-2. В этих тестах обрабатывает последовательность двоичных символов длины 20000 (2500 байтов).

Уровень значимости тестов p = 0.01. С такой вероятностью истинно случайная последовательность не пройдет тест. Известно, что тесты FIPS слабо зависимы. Поэтому истинно случайная последовательность не пройдет батарею из n тестов с вероятностью 1 - (1 - p)^n ≈ n p.

Регулярность:\n Обрабатываемые в тестах данные не считаются секретными. Эти данные

не должны использовать для построения ключей.

Генератор случайных чисел

Выходные случайные числа можно использовать для построения ключей и других критических объектов.

Генератор является единственным в библиотеке.

Генератор можно использовать в многопоточных приложениях.

При создании генератора опрашиваются все доступные источники случайности. Данные от источников объединяются и хэшируются с помощью механизма beltHash (см. crypto/belt.h). Хэш-значение используется как ключ механизма brngCTR (см. crypto/brng.h).

При функционировании генератора выполняются последовательные обращения к brngCTR. При подготовке обращений могут использоваться данные от доступных источников случайности. Эти данные используются в качестве входного буфера функции brngCTRStepR().

Данные от источников используются в функции rngStepR() и не используются в функции rngStepR2(). Первую функцию можно применять время от времени (например, во время согласования общего ключа перед передачей данных), вторую -- регулярно (в процессе передачи данных).

Функции

void rngClose ()

Генератор случайных чисел закрывается.

Предусловие

Генератор корректен.

err_t rngCreate (read_i source, void * source_state)

Создается генератор случайных чисел. При создании используются источники, поддерживаемые функцией rngReadSource(), а также возможно дополнительный источник source с состоянием source_state.

Ожидается [ERR_BAD_ENTROPY]:\n В совокупности все работоспособные источники

выдают не менее 32 октетов случайных данных.

Ожидается:\n Источники случайности выдают высокоэнтропийные данные.

Возвращает

Признак успеха.

Прим.

При нулевом source дополнительный источник не используется.

Функцию rngCreate() можно вызывать многократно. При повторных обращениях накопленные энтропийные данные сохраняются, к ним добавляются данные, полученные от дополнительного источника source. У источника запрашивается 32 октета, но он может выдать меньше. Данные не запрашиваются, если источник отсутствует.

Поддерживается счетчик обращений к rngCreate(). Счетчик уменьшается функцией rngClose(). При достижении счетчиком нулевого значения накопленные энтропийные данные (в том числе ключ криптографической постобработки) уничтожаются.

Аргументы

source дополнительный источник
source_state состояние дополнительного источника

bool_t rngIsValid ()

Проверяется корректность генератора случайных чисел.

Возвращает

Признак корректности.

err_t rngReadSource (size_t * read, void * buf, size_t count, const char * source_name)

Данные от источника случайности с именем source_name записываются в буфер [count]buf. По адресу read возвращается число полученных октетов. Поддерживаются следующие имена источников:

·

·

·

·

Предусловие

Буфер buf корректен.

Указатель read корректен.

Возвращает

ERR_OK, если получено определенное число октетов (возможно меньшее count и возможно нулевое) и источник сохранил работоспособность, ERR_MAX, если получено меньше чем count октетов и источник отказал, или другой код ошибки.

Предупреждения

Если при работе с источниками 'trng', 'trng2' длина выходного буфера меньше длины машинного слова, то функция возвратит ERR_OK, но ни одного октета данных сгенерировано не будет.

Прим.

Ошибкой не считается ситуация, когда сгенерировано меньше чем count октетов. Данная ситуация может быть связана с ожиданием накопления наблюдений.

Передавая count == 0, можно проверить наличие источника.

Поддержан интерфейс read_i.

Аргументы

read число прочитанных октетов
buf прочитанные данные
count длина buf в октетах
source_name [in/out] имя источника

void rngStepR (void * buf, size_t count, void * state)

В буфер [count]buf записываются случайные октеты, построенные с помощью генератора случайных чисел. При формировании выходных октетов используются данные от источников случайности.

Ожидается:\n rngСreate() < rngStepR()*.

Предусловие

Генератор корректен.

Прим.

Поддержан интерфейс gen_i (defs.h).

Состояние state не используется. Оно передается в функцию только для того, чтобы поддержать интерфейс gen_i.

Запрашивается count октетов от источников. Будет возвращено меньше октетов только если все источники отказали.

Аргументы

buf буфер
count размер буфера (в октетах)
state [in/out] состояние (игнорируется)

void rngStepR2 (void * buf, size_t count, void * state)

В буфер [count]buf записываются случайные октеты, построенные с помощью генератора случайных чисел. При формировании выходных октетов данные от источников случайности не используются.

Ожидается:\n rngСreate() < rngStepR2()*.

Предусловие

Генератор корректен.

Прим.

Поддержан интерфейс gen_i (defs.h).

Состояние state не используется. Оно передается в функцию только для того, чтобы поддержать интерфейс gen_i.

Аргументы

buf буфер
count размер буфера (в октетах)
state [in/out] состояние (игнорируется)

bool_t rngTestFIPS1 (const octet buf[2500])

К последовательности buf применяется тест знаков FIPS.

Предусловие

Буфер buf корректен.

Возвращает

Признак успешного прохождения теста.

Прим.

Определяется величина S -- число единиц в последовательности. Тест пройден, если 9725 < S < 10275.

Аргументы

buf тестируемая последовательность

bool_t rngTestFIPS2 (const octet buf[2500])

К последовательности buf применяется покер-тест FIPS.

Предусловие

Буфер buf корректен.

Возвращает

Признак успешного прохождения теста.

Прим.

Последовательность разбивается на 5000 тетрад. Тетрады интерпретируются как числа от 0 до 15. Определяется статистика S = 16 \sum _{i=0}^15 S_i^2 - (5000)^2, где S_i -- количество появлений числа i среди тетрад. Тест пройден, если 10800 < S < 230850.

Аргументы

buf тестируемая последовательность

bool_t rngTestFIPS3 (const octet buf[2500])

К последовательности buf применяется тест серий FIPS.

Предусловие

Буфер buf корректен.

Возвращает

Признак успешного прохождения теста.

Прим.

Определяются серии (максимальные последовательности повторяющихся соседних битов) различных длин. Тест пройден, если и для серий из нулей, и для серий из единиц выполняется: S_1 ∈ [2315, 2685], S_2 ∈ [1114, 1386], S_3 ∈ [527, 723], S_4 ∈ [240, 384], S_5, S_6+ ∈ [103, 209]. Здесь S_i -- количество серий длины i = 1, 2, ..., S_6+ = S_6 + S_7 + ....

Бит с номером i: wwTestBit((const word*)buf, i).

Аргументы

buf тестируемая последовательность

bool_t rngTestFIPS4 (const octet buf[2500])

К последовательности buf применяется тест серий FIPS.

Предусловие

Буфер buf корректен.

Возвращает

Признак успешного прохождения теста.

Прим.

Тест пройден, если в последовательности отсутствуют серии длины 26 и больше.

Бит с номером i: wwTestBit((const word*)buf, i).

Аргументы

buf тестируемая последовательность

Автор

Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.

Info

Пн 13 Фев 2023 Библиотека Bee2