1rng.h(3) Library Functions Manual rng.h(3)
2
3
4
6 rng.h - Источники случайности и генераторы случайных чисел
7
8
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)