rng.h - Man Page
Источники случайности и генераторы случайных чисел
Synopsis
#include 'bee2/defs.h'
Функции
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 rngESRead (size_t *read, void *buf, size_t count, const char *source)
Чтение данных от источника энтропии
err_t rngESTest (const char *source)
Статистическое тестирование источника энтропии
err_t rngESHealth ()
Проверка работоспособности источников энтропии
err_t rngESHealth2 ()
Усиленная проверка работоспособности источников энтропии
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 rngRekey ()
Обновление ключа генератора
void rngClose ()
Закрытие генератора
Подробное описание
Статистическое тестирование
Реализованы статистические тесты стандарта FIPS 140-2. В этих тестах обрабатывает последовательность двоичных символов длины 20000 (2500 байтов).
Уровень значимости тестов p = 0.01. С такой вероятностью истинно случайная последовательность не пройдет тест. Известно, что тесты FIPS слабо зависимы. Поэтому истинно случайная последовательность не пройдет батарею из n тестов с вероятностью 1 - (1 - p)^n ≈ n p.
Регулярность
Обрабатываемые в тестах данные не считаются секретными. Эти данные не должны использовать для построения ключей.
Источники энтропии
В системе может быть несколько источников энтропии. Чтение данных от источников реализуется через интерфейс read_i. Внутренние источники поддерживаются функцией rngESRead().
При обработке запроса на чтение данных источники обрабатывает свои наблюдения, учитывая оценки энтропии. При необходимости наблюдения сжимаются. В результате обработки запроса будут возвращены высокоэнтропийные данные. Их объем может быть меньше запрошенного.
При обработке запроса может произойти сбой источника или время снятия наблюдений может оказаться неприемлемо большим. В таких случаях также будет возвращено меньше данных, чем запрашивалось.
Генератор случайных чисел
Выходные случайные числа можно использовать для построения ключей и других критических объектов.
Генератор является единственным в библиотеке.
Генератор можно использовать в многопоточных приложениях.
При создании генератора опрашиваются все доступные источники случайности. Данные от источников объединяются и хэшируются с помощью механизма beltHash (см. crypto/belt.h). Хэш-значение используется как ключ механизма brngCTR (см. crypto/brng.h).
При функционировании генератора выполняются последовательные обращения к brngCTR. При подготовке обращений могут использоваться данные от доступных источников случайности. Эти данные используются в качестве входного буфера функции brngCTRStepR().
Данные от источников используются в функции rngStepR() и не используются в функции rngStepR2(). Первую функцию можно применять время от времени (например, во время согласования общего ключа перед передачей данных), вторую -- регулярно (в процессе передачи данных).
С помощью функции rngRekey() можно обновить ключ генератора. После обновления ключа случайные числа, сгенерированные ранее, будет невозможно определить даже если при их генерации не использовались источники энтропии, а новый ключ стал известен противнику.
Функции
void rngClose ()
Генератор случайных чисел закрывается.
Предусловие
Генератор корректен.
err_t rngCreate (read_i source, void * source_state)
Создается генератор случайных чисел. При создании используются источники, поддерживаемые функцией rngESRead(), а также возможно дополнительный источник source с состоянием source_state.
Ожидается [ERR_NOT_ENOUGH_ENTROPY]
В совокупности все работоспособные источники выдают не менее 32 октетов случайных данных.
Ожидается
Источники случайности выдают высокоэнтропийные данные.
Возвращает
Признак успеха.
Прим.
При нулевом source дополнительный источник не используется.
Функцию rngCreate() можно вызывать многократно. При повторных обращениях накопленные энтропийные данные сохраняются, к ним добавляются данные, полученные от дополнительного источника source.
У каждого источника запрашивается 32 октета данных, но он может выдать меньше. Данные не запрашиваются, если источник отсутствует.
Поддерживается счетчик обращений к rngCreate(). Счетчик уменьшается функцией rngClose(). При достижении счетчиком нулевого значения накопленные энтропийные данные (в том числе ключ криптографической постобработки) уничтожаются.
- Аргументы
source дополнительный источник
source_state состояние дополнительного источника
err_t rngESHealth ()
Проверяется, что cреди штатных источников энтропии, которые выдерживают статистическое тестирование, имеется один физический источник либо не менее двух разных альтернативных.
- Возвращает
ERR_OK, если проверка прошла успешно, ERR_NOT_ENOUGH_ENTROPY, если недостает одного работоспособного источника, и ERR_BAD_ENTROPY в остальных случаях.
Прим.
Проверяемые требования -- это требования СТБ 34.101.27 уровня 1.
err_t rngESHealth2 ()
Проверяется, что среди источников энтропии, которые выдерживают статистическое тестирование, имеется один физический источник.
- Возвращает
ERR_OK, если проверка прошло успешно, и ERR_BAD_ENTROPY в противном случае.
Прим.
Проверяемые требования -- это требования СТБ 34.101.27 уровня 2 и выше.
err_t rngESRead (size_t * read, void * buf, size_t count, const char * source)
Данные от источника энтропии source записываются в буфер [count]buf. По адресу read возвращается число прочитанных октетов. Поддерживаются следующие источники:
·
·
·
·
Предусловие
Буфер buf корректен.
Указатель read корректен.
- Возвращает
ERR_OK, если получено определенное число октетов (возможно меньшее count и возможно нулевое) и источник сохранил работоспособность, ERR_BAD_ENTROPY, если получено меньше чем count октетов и источник отказал, или другой код ошибки.
Предупреждения
Если при работе с источниками 'trng', 'trng2' длина выходного буфера меньше 4, то функция возвратит ERR_OK, но ни одного октета данных сгенерировано не будет.
Прим.
Ошибкой не считается ситуация, когда сгенерировано меньше чем count октетов. Данная ситуация может быть связана с ожиданием накопления наблюдений.
Передавая count == 0, можно проверить наличие источника.
Поддержан интерфейс read_i.
- Аргументы
read число прочитанных октетов
buf прочитанные данные
count длина buf в октетах
source источник
err_t rngESTest (const char * source)
Проводится статистическое тестирование источника энтропии source: к данным, полученным от источника, применяются тесты FIPS. Тестирование завершается успешно, если все тесты FIPS пройдены.
- Возвращает
ERR_OK, если тестирование прошло успешно, и код ошибки в противном случае.
- Аргументы
source источник
bool_t rngIsValid ()
Проверяется корректность генератора случайных чисел.
Возвращает
Признак корректности.
void rngRekey ()
Ключ генератора обновляется: в его качестве выступают генеририруемые случайные числа. При обновлении ключа данные от источников энтропии не используются.
- Ожидается
rngСreate() < rngRekey()*.
Предусловие
Генератор корректен.
void rngStepR (void * buf, size_t count, void * state)
В буфер [count]buf записываются случайные октеты, построенные с помощью генератора случайных чисел. При формировании выходных октетов используются данные от источников случайности.
- Ожидается
rngСreate() < rngStepR()*.
Предусловие
Генератор корректен.
Прим.
Поддержан интерфейс gen_i (defs.h).
Состояние state не используется. Оно передается в функцию только для того, чтобы поддержать интерфейс gen_i.
Запрашивается count октетов от источников. Будет возвращено меньше октетов только если все источники отказали.
- Аргументы
buf буфер
count размер буфера (в октетах)
state состояние (игнорируется)
void rngStepR2 (void * buf, size_t count, void * state)
В буфер [count]buf записываются случайные октеты, построенные с помощью генератора случайных чисел. При формировании выходных октетов данные от источников энтропии не используются.
- Ожидается
rngСreate() < rngStepR2()*.
Предусловие
Генератор корректен.
Прим.
Поддержан интерфейс gen_i (defs.h).
Состояние state не используется. Оно передается в функцию только для того, чтобы поддержать интерфейс gen_i.
- Аргументы
buf буфер
count размер буфера (в октетах)
state состояние (игнорируется)
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 из исходного текста.