1brng.h(3) Library Functions Manual brng.h(3)
2
3
4
6 brng.h - Алгоритмы СТБ 34.101.47 (brng)
7
8
10 #include 'bee2/defs.h'
11
12
13 Функции
14 size_t brngCTR_keep ()
15 Длина состояния функций CTR.
16 void brngCTRStart (void *state, const octet key[32], const octet
17 iv[32])
18 Инициализация режима CTR.
19 void brngCTRStepR (void *buf, size_t count, void *state)
20 Генерация фрагмента в режиме CTR.
21 void brngCTRStepG (octet iv[32], void *state)
22 Получение синхропосылки режима CTR.
23 err_t brngCTRRand (void *buf, size_t count, const octet key[32], octet
24 iv[32])
25 Генерация в режиме CTR.
26 size_t brngHMAC_keep ()
27 Длина состояния функций HMAC.
28 void brngHMACStart (void *state, const octet key[], size_t key_len,
29 const octet iv[], size_t iv_len)
30 Инициализация режима HMAC.
31 void brngHMACStepR (void *buf, size_t count, void *state)
32 Генерация в режиме HMAC.
33 err_t brngHMACRand (void *buf, size_t count, const octet key[], size_t
34 key_len, const octet iv[], size_t iv_len)
35 Генерация в режиме HMAC.
36
38 Реализованы алгоритмы генерации псевдослучайных чисел, определенные в
39 СТБ 34.101.47 (brng). При ссылках на алгоритмы, таблицы, другие объекты
40 подразумеваются разделы СТБ 34.101.47-2012, в которых эти объекты
41 определены.
42
43 Во всех случаях в качестве вспомогательного алгоритма хэширования
44 используется belt-hash (см. СТБ 345.101.31).
45
46 В СТБ 34.101.47 определен вспомогательный алгоритм ключезависимого
47 хэширования HMAC. Реализация этого алгоритма на основе belt-hash
48 определена в belt.h.
49
50 Основные алгоритмы объединяются в группы, которые определяют следующие
51 криптографические механизмы:
52
53 • CTR --- генерация в режиме счетчика;
54
55 • HMAC --- генерация в режиме HMAC.
56
57 В механизме CTR используется ключ из 32 октетов. В механизме HMAC
58 используется ключ произвольной длины. Рекомендуется использовать ключ
59 из 32 октетов.
60
61 Каждый механизм реализуется связкой из двух функций. Эти функции
62 используют общее состояние, указатель на которое передается в функции
63 как дополнительный параметр. Имеются функция определения объема памяти
64 для состояния (_keep). Память для состояния готовит вызывающая
65 программа и она же отвечает за очистку памяти.
66
67 Состояние можно копировать как фрагмент памяти.
68
69 В связке обязательно имеется функция инициализации алгоритма (Start) и
70 одна или несколько функций генерации и получения служебных данных
71 (StepX).
72
73 Логика суффиксов функций StepX:
74
75 • R -- rand (сгенерировать);
76
77 • G -- get (получить синхропосылку).
78
79 Функция типа StepR соответствует интерфейсу gen_i (см. defs.h).
80
81 Функции связки спроектированы как максимально простые и эффективные. В
82 частности, в этих функциях не проверяются входные данные.
83
84 Каждая связка покрывается высокоуровневой функцией, которая
85 обрабатывает все данные целиком. В высокоуровневых функциях есть
86 проверка входных данных.
87
88 Ожидается
89 Общее состояние связки функций не изменяется вне этих функций.
90
91 Ожидается [ERR_BAD_INPUT]
92 Все входные указатели действительны.
93
94 Предусловие
95 Если не оговорено противное, то входные буферы функций связки не
96 пересекаются.
97
99 size_t brngCTR_keep ()
100 Возвращается длина состояния (в октетах) функций генерации в режиме
101 CTR.
102
103 Возвращает
104 Длина состояния.
105
106 err_t brngCTRRand (void * buf, size_t count, const octet key[32], octet
107 iv[32])
108 В буфер [count]buf записываются псевдослучайные данные, сгенерированные
109 в режиме CTR на ключе key при использовании синхропосылки iv.
110 Дополнительно в iv возвращается обновленная синхропосылка, которую
111 можно использовать при повторном вызове функции с тем же ключом.
112
113 Возвращает
114 ERR_OK, если данные успешно сгенерированы, и код ошибки в противном
115 случае.
116
117 Предупреждения
118 При многократном вызове функции с одним и тем же ключом должны
119 использоваться различные синхропосылки. При повторе синхропосылок
120 могут быть повторно сгенерированы те же данные.
121
122 Прим.
123 Первоначальное содержимое buf используется для формирования
124 дополнительного слова X алгоритма генерации (см. п. 6.2.2). Слово X
125 разбивается на последовательные блоки из 32 октетов, при
126 необходимости дополняясь нулевыми октетами.
127
128 Аргументы
129 buf дополн. / псевдослучайные данные
130 count число октетов buf
131 key ключ
132 iv первонач. / обновл. синхропосылка
133
134 void brngCTRStart (void * state, const octet key[32], const octet iv[32])
135 По ключу key и синхропосылке iv в state формируются структуры данных,
136 необходимые для генерации псевдослучайных чисел в режиме CTR.
137
138 Предусловие
139 По адресу state зарезервировано brngCTR_keep() октетов.
140
141 Предупреждения
142 При многократном вызове функции с одним и тем же ключом должны
143 использоваться различные синхропосылки. При повторе синхропосылок
144 могут быть повторно сгенерированы те же данные.
145
146 Прим.
147 Разрешается передавать нулевой указатель iv. В этом случае будет
148 использоваться нулевая синхропосылка.
149
150 Аргументы
151 state состояние
152 key ключ
153 iv синхропосылка
154
155 void brngCTRStepG (octet iv[32], void * state)
156 Возвращается синхропосылка iv, установленная при вызове brngCTRStart()
157 и измененная затем при последовательных вызовах brngCTRStepR().
158
159 Ожидается
160 (brngCTRStepR()* < brngCTRStepG())*.
161
162 Прим.
163 Если сгенерировано полное число блоков, то полученная синхропосылка
164 будет отличаться от ранее использованных. Поэтому эту синхропосылку
165 можно задавать при повторном вызове функций связки с тем же ключом.
166
167 Аргументы
168 iv синхропосылка
169 state состояние
170
171 void brngCTRStepR (void * buf, size_t count, void * state)
172 В буфер [count]buf записываются октеты, полученные в результате
173 псевдослучайной генерации в режиме CTR. При генерации используются
174 структуры данных, развернутые в state.
175
176 Ожидается
177 brngCTRStart() < brngCTRStepR()*.
178
179 Прим.
180 Данные в режиме CTR генерируются блоками по 32 октета. Реализована
181 буферизация блоков и функцию можно вызвать с произвольным значением
182 count. Если не все данные сгенерированного ранее блока
183 израсходованы, то они будут возвращены в первую очередь.
184
185 Первоначальное содержимое buf используется для формирования
186 дополнительного слова X алгоритма генерации (см. п. 6.2.2). Слово X
187 разбивается на последовательные блоки из 32 октетов, при
188 необходимости дополняясь нулевыми октетами.
189
190 Если работает буферизация и возвращаются данные сгенерированного
191 ранее блока, то соответствующие октеты buf не используются для
192 формирования слова X, эти октеты пропускаются. Поэтому, в
193 частности, строки
194
195 brngCTRStepR(buf + 16, 16, state), brngCTRStepR(buf + 16, 16, state);
196 brngCTRStepR(buf, 32, state);
197
198
199 вызываемые сразу после brngCTRStart(), не эквивалентны друг другу.
200
201 Аргументы
202 buf дополн. / псевдослучайные данные
203 count число октетов buf
204 state состояние
205
206 size_t brngHMAC_keep ()
207 Возвращается длина состояния (в октетах) функций генерации в режиме
208 HMAC.
209
210 Возвращает
211 Длина состояния.
212
213 err_t brngHMACRand (void * buf, size_t count, const octet key[], size_t
214 key_len, const octet iv[], size_t iv_len)
215 В буфер [count]buf записываются псевдослучайные данные, сгенерированные
216 в режиме HMAC на ключе [key_len]key при использовании синхропосылки
217 [iv_len]iv.
218
219 Ожидается [ERR_BAD_INPUT]
220 Буферы buf и iv не пересекаются.
221
222 Возвращает
223 ERR_OK, если данные успешно сгенерированы, и код ошибки в противном
224 случае.
225
226 Предупреждения
227 При многократном вызове функции с одним и тем же ключом должны
228 использоваться различные синхропосылки. При повторе синхропосылок
229 будут повторно сгенерированы те же данные.
230
231 Прим.
232 Ограничений на iv_len нет (ср. с функцией brngHMACStart()).
233
234 Рекомендуется использовать ключ из 32 октетов.
235
236 Аргументы
237 buf выходные данные
238 count число октетов buf
239 key ключ
240 key_len длина ключа в октетах
241 iv синхропосылка
242 iv_len длина синхропосылки в октетах
243
244 void brngHMACStart (void * state, const octet key[], size_t key_len, const
245 octet iv[], size_t iv_len)
246 По ключу [key_len]key и синхропосылке [iv_len]iv в state формируются
247 структуры данных, необходимые для генерации псевдослучайных чисел в
248 режиме HMAC.
249
250 Предусловие
251 По адресу state зарезервировано brngHMAC_keep() октетов.
252
253 Ожидается
254 Если длина синхропосылки в октетах (iv_len) больше 64, то буфер iv
255 остается корректным и постоянным вплоть до завершения работы с
256 механизмом.
257
258 Предупреждения
259 При многократном вызове функции с одним и тем же ключом должны
260 использоваться различные синхропосылки. При повторе синхропосылок
261 будут повторно сгенерированы те же данные.
262
263 Прим.
264 Рекомендуется использовать ключ из 32 октетов.
265
266 При iv_len <= 64 содержимое [iv_len]iv сохраняется в state.
267
268 Аргументы
269 state состояние
270 key ключ
271 key_len длина ключа в октетах
272 iv синхропосылка
273 iv_len длина синхропосылки в октетах
274
275 void brngHMACStepR (void * buf, size_t count, void * state)
276 В буфер [count]buf записываются октеты, полученные в результате
277 псевдослучайной генерации в режиме HMAC. При генерации используются
278 структуры данных, развернутые в state.
279
280 Ожидается
281 brngHMACStart() < brngHMACStepR()*.
282
283 Прим.
284 Данные в режиме HMAC генерируются блоками по 32 октета. Реализована
285 буферизация блоков и функцию можно вызвать с произвольным значением
286 count. Если не все данные сгенерированного ранее блока
287 израсходованы, то они будут возвращены в первую очередь.
288
289 Аргументы
290 buf псевдослучайные данные
291 count размер buf в октетах
292 state состояние
293
295 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
296
297
298
299Библиотека Bee2 Ср 19 Июл 2023 00:00:00 brng.h(3)