1rng.h(3)                   Library Functions Manual                   rng.h(3)
2
3
4

NAME

6       rng.h - Источники случайности и генераторы случайных чисел
7
8

SYNOPSIS

10       #include 'bee2/defs.h'
11
12
13   Функции
14       bool_t rngTestFIPS1 (const octet buf[2500])
15           Тест знаков FIPS 140.
16       bool_t rngTestFIPS2 (const octet buf[2500])
17           Покер-тест FIPS 140.
18       bool_t rngTestFIPS3 (const octet buf[2500])
19           Тест серий FIPS 140.
20       bool_t rngTestFIPS4 (const octet buf[2500])
21           Тест длинных серий FIPS 140.
22       err_t rngESRead (size_t *read, void *buf, size_t count, const char
23           *source)
24           Чтение данных от источника энтропии
25       err_t rngESTest (const char *source)
26           Статистическое тестирование источника энтропии
27       err_t rngESHealth ()
28           Проверка работоспособности источников энтропии
29       err_t rngESHealth2 ()
30           Усиленная проверка работоспособности источников энтропии
31       err_t rngCreate (read_i source, void *source_state)
32           Создание генератора
33       bool_t rngIsValid ()
34           Корректный генератор?
35       void rngStepR (void *buf, size_t count, void *state)
36           Генерация случайных чисел
37       void rngStepR2 (void *buf, size_t count, void *state)
38           Облегченная генерация случайных чисел
39       void rngRekey ()
40           Обновление ключа генератора
41       void rngClose ()
42           Закрытие генератора
43

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

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

46       Реализованы статистические тесты стандарта FIPS 140-2. В этих тестах
47       обрабатывает последовательность двоичных символов длины 20000 (2500
48       байтов).
49
50       Уровень значимости тестов p = 0.01. С такой вероятностью истинно
51       случайная последовательность не пройдет тест. Известно, что тесты FIPS
52       слабо зависимы. Поэтому истинно случайная последовательность не пройдет
53       батарею из n тестов с вероятностью 1 - (1 - p)^n ≈ n p.
54
55       Регулярность
56           Обрабатываемые в тестах данные не считаются секретными. Эти данные
57           не должны использовать для построения ключей.
58

Источники энтропии

60       В системе может быть несколько источников энтропии. Чтение данных от
61       источников реализуется через интерфейс read_i. Внутренние источники
62       поддерживаются функцией rngESRead().
63
64       При обработке запроса на чтение данных источники обрабатывает свои
65       наблюдения, учитывая оценки энтропии. При необходимости наблюдения
66       сжимаются. В результате обработки запроса будут возвращены
67       высокоэнтропийные данные. Их объем может быть меньше запрошенного.
68
69       При обработке запроса может произойти сбой источника или время снятия
70       наблюдений может оказаться неприемлемо большим. В таких случаях также
71       будет возвращено меньше данных, чем запрашивалось.
72

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

74       Выходные случайные числа можно использовать для построения ключей и
75       других критических объектов.
76
77       Генератор является единственным в библиотеке.
78
79       Генератор можно использовать в многопоточных приложениях.
80
81       При создании генератора опрашиваются все доступные источники
82       случайности. Данные от источников объединяются и хэшируются с помощью
83       механизма beltHash (см. crypto/belt.h). Хэш-значение используется как
84       ключ механизма brngCTR (см. crypto/brng.h).
85
86       При функционировании генератора выполняются последовательные обращения
87       к brngCTR. При подготовке обращений могут использоваться данные от
88       доступных источников случайности. Эти данные используются в качестве
89       входного буфера функции brngCTRStepR().
90
91       Данные от источников используются в функции rngStepR() и не
92       используются в функции rngStepR2(). Первую функцию можно применять
93       время от времени (например, во время согласования общего ключа перед
94       передачей данных), вторую -- регулярно (в процессе передачи данных).
95
96       С помощью функции rngRekey() можно обновить ключ генератора. После
97       обновления ключа случайные числа, сгенерированные ранее, будет
98       невозможно определить даже если при их генерации не использовались
99       источники энтропии, а новый ключ стал известен противнику.
100

Функции

102   void rngClose ()
103       Генератор случайных чисел закрывается.
104
105       Предусловие
106           Генератор корректен.
107
108   err_t rngCreate (read_i source, void * source_state)
109       Создается генератор случайных чисел. При создании используются
110       источники, поддерживаемые функцией rngESRead(), а также возможно
111       дополнительный источник source с состоянием source_state.
112
113       Ожидается [ERR_NOT_ENOUGH_ENTROPY]
114           В совокупности все работоспособные источники выдают не менее 32
115           октетов случайных данных.
116
117       Ожидается
118           Источники случайности выдают высокоэнтропийные данные.
119
120       Возвращает
121           Признак успеха.
122
123       Прим.
124           При нулевом source дополнительный источник не используется.
125
126           Функцию rngCreate() можно вызывать многократно. При повторных
127           обращениях накопленные энтропийные данные сохраняются, к ним
128           добавляются данные, полученные от дополнительного источника source.
129
130           У каждого источника запрашивается 32 октета данных, но он может
131           выдать меньше. Данные не запрашиваются, если источник отсутствует.
132
133           Поддерживается счетчик обращений к rngCreate(). Счетчик уменьшается
134           функцией rngClose(). При достижении счетчиком нулевого значения
135           накопленные энтропийные данные (в том числе ключ криптографической
136           постобработки) уничтожаются.
137
138       Аргументы
139           source дополнительный источник
140           source_state состояние дополнительного источника
141
142   err_t rngESHealth ()
143       Проверяется, что cреди штатных источников энтропии, которые выдерживают
144       статистическое тестирование, имеется один физический источник либо не
145       менее двух разных альтернативных.
146
147       Возвращает
148           ERR_OK, если проверка прошла успешно, ERR_NOT_ENOUGH_ENTROPY, если
149           недостает одного работоспособного источника, и ERR_BAD_ENTROPY в
150           остальных случаях.
151
152       Прим.
153           Проверяемые требования -- это требования СТБ 34.101.27 уровня 1.
154
155   err_t rngESHealth2 ()
156       Проверяется, что среди источников энтропии, которые выдерживают
157       статистическое тестирование, имеется один физический источник.
158
159       Возвращает
160           ERR_OK, если проверка прошло успешно, и ERR_BAD_ENTROPY в противном
161           случае.
162
163       Прим.
164           Проверяемые требования -- это требования СТБ 34.101.27 уровня 2 и
165           выше.
166
167   err_t rngESRead (size_t * read, void * buf, size_t count, const char *
168       source)
169       Данные от источника энтропии source записываются в буфер [count]buf. По
170       адресу read возвращается число прочитанных октетов. Поддерживаются
171       следующие источники:
172
173       •
174
175       •
176
177       •
178
179       •
180
181       Предусловие
182           Буфер buf корректен.
183
184           Указатель read корректен.
185
186       Возвращает
187           ERR_OK, если получено определенное число октетов (возможно меньшее
188           count и возможно нулевое) и источник сохранил работоспособность,
189           ERR_BAD_ENTROPY, если получено меньше чем count октетов и источник
190           отказал, или другой код ошибки.
191
192       Предупреждения
193           Если при работе с источниками 'trng', 'trng2' длина выходного
194           буфера меньше 4, то функция возвратит ERR_OK, но ни одного октета
195           данных сгенерировано не будет.
196
197       Прим.
198           Ошибкой не считается ситуация, когда сгенерировано меньше чем count
199           октетов. Данная ситуация может быть связана с ожиданием накопления
200           наблюдений.
201
202           Передавая count == 0, можно проверить наличие источника.
203
204           Поддержан интерфейс read_i.
205
206       Аргументы
207           read число прочитанных октетов
208           buf прочитанные данные
209           count длина buf в октетах
210           source источник
211
212   err_t rngESTest (const char * source)
213       Проводится статистическое тестирование источника энтропии source: к
214       данным, полученным от источника, применяются тесты FIPS. Тестирование
215       завершается успешно, если все тесты FIPS пройдены.
216
217       Возвращает
218           ERR_OK, если тестирование прошло успешно, и код ошибки в противном
219           случае.
220
221       Аргументы
222           source источник
223
224   bool_t rngIsValid ()
225       Проверяется корректность генератора случайных чисел.
226
227       Возвращает
228           Признак корректности.
229
230   void rngRekey ()
231       Ключ генератора обновляется: в его качестве выступают генеририруемые
232       случайные числа. При обновлении ключа данные от источников энтропии не
233       используются.
234
235       Ожидается
236           rngСreate() < rngRekey()*.
237
238       Предусловие
239           Генератор корректен.
240
241   void rngStepR (void * buf, size_t count, void * state)
242       В буфер [count]buf записываются случайные октеты, построенные с помощью
243       генератора случайных чисел. При формировании выходных октетов
244       используются данные от источников случайности.
245
246       Ожидается
247           rngСreate() < rngStepR()*.
248
249       Предусловие
250           Генератор корректен.
251
252       Прим.
253           Поддержан интерфейс gen_i (defs.h).
254
255           Состояние state не используется. Оно передается в функцию только
256           для того, чтобы поддержать интерфейс gen_i.
257
258           Запрашивается count октетов от источников. Будет возвращено меньше
259           октетов только если все источники отказали.
260
261       Аргументы
262           buf буфер
263           count размер буфера (в октетах)
264           state состояние (игнорируется)
265
266   void rngStepR2 (void * buf, size_t count, void * state)
267       В буфер [count]buf записываются случайные октеты, построенные с помощью
268       генератора случайных чисел. При формировании выходных октетов данные от
269       источников энтропии не используются.
270
271       Ожидается
272           rngСreate() < rngStepR2()*.
273
274       Предусловие
275           Генератор корректен.
276
277       Прим.
278           Поддержан интерфейс gen_i (defs.h).
279
280           Состояние state не используется. Оно передается в функцию только
281           для того, чтобы поддержать интерфейс gen_i.
282
283       Аргументы
284           buf буфер
285           count размер буфера (в октетах)
286           state состояние (игнорируется)
287
288   bool_t rngTestFIPS1 (const octet buf[2500])
289       К последовательности buf применяется тест знаков FIPS.
290
291       Предусловие
292           Буфер buf корректен.
293
294       Возвращает
295           Признак успешного прохождения теста.
296
297       Прим.
298           Определяется величина S -- число единиц в последовательности. Тест
299           пройден, если 9725 < S < 10275.
300
301       Аргументы
302           buf тестируемая последовательность
303
304   bool_t rngTestFIPS2 (const octet buf[2500])
305       К последовательности buf применяется покер-тест FIPS.
306
307       Предусловие
308           Буфер buf корректен.
309
310       Возвращает
311           Признак успешного прохождения теста.
312
313       Прим.
314           Последовательность разбивается на 5000 тетрад. Тетрады
315           интерпретируются как числа от 0 до 15. Определяется статистика S =
316           16 \sum _{i=0}^15 S_i^2 - (5000)^2, где S_i -- количество появлений
317           числа i среди тетрад. Тест пройден, если 10800 < S < 230850.
318
319       Аргументы
320           buf тестируемая последовательность
321
322   bool_t rngTestFIPS3 (const octet buf[2500])
323       К последовательности buf применяется тест серий FIPS.
324
325       Предусловие
326           Буфер buf корректен.
327
328       Возвращает
329           Признак успешного прохождения теста.
330
331       Прим.
332           Определяются серии (максимальные последовательности повторяющихся
333           соседних битов) различных длин. Тест пройден, если и для серий из
334           нулей, и для серий из единиц выполняется: S_1 ∈ [2315, 2685], S_2 ∈
335           [1114, 1386], S_3 ∈ [527, 723], S_4 ∈ [240, 384], S_5, S_6+ ∈ [103,
336           209]. Здесь S_i -- количество серий длины i = 1, 2, ..., S_6+ = S_6
337           + S_7 + ....
338
339           Бит с номером i: wwTestBit((const word*)buf, i).
340
341       Аргументы
342           buf тестируемая последовательность
343
344   bool_t rngTestFIPS4 (const octet buf[2500])
345       К последовательности buf применяется тест серий FIPS.
346
347       Предусловие
348           Буфер buf корректен.
349
350       Возвращает
351           Признак успешного прохождения теста.
352
353       Прим.
354           Тест пройден, если в последовательности отсутствуют серии длины 26
355           и больше.
356
357           Бит с номером i: wwTestBit((const word*)buf, i).
358
359       Аргументы
360           buf тестируемая последовательность
361

Автор

363       Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
364
365
366
367Библиотека Bee2                 Пт 23 Июн 2023                        rng.h(3)