1brng.h(3) Library Functions Manual brng.h(3)
2
6 brng.h - Алгоритмы СТБ 34.101.47 (brng)
7
10 #include 'bee2/defs.h'
11 Функции
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 Во всех случаях в качестве вспомогательного алгоритма хэширования
44 используется belt-hash (см. СТБ 345.101.31).
45 В СТБ 34.101.47 определен вспомогательный алгоритм ключезависимого
47 хэширования HMAC. Реализация этого алгоритма на основе belt-hash
48 определена в belt.h.
49 Основные алгоритмы объединяются в группы, которые определяют следующие
51 криптографические механизмы:
52 • CTR --- генерация в режиме счетчика;
54 • HMAC --- генерация в режиме HMAC.
56 В механизме CTR используется ключ из 32 октетов. В механизме HMAC
58 используется ключ произвольной длины. Рекомендуется использовать ключ
59 из 32 октетов.
60 Каждый механизм реализуется связкой из двух функций. Эти функции
62 используют общее состояние, указатель на которое передается в функции
63 как дополнительный параметр. Имеются функция определения объема памяти
64 для состояния (_keep). Память для состояния готовит вызывающая
65 программа и она же отвечает за очистку памяти.
66 Состояние можно копировать как фрагмент памяти.
68 В связке обязательно имеется функция инициализации алгоритма (Start) и
70 одна или несколько функций генерации и получения служебных данных
71 (StepX).
72 Логика суффиксов функций StepX:
74 • R -- rand (сгенерировать);
76 • G -- get (получить синхропосылку).
78 Функция типа StepR соответствует интерфейсу gen_i (см. defs.h).
80 Функции связки спроектированы как максимально простые и эффективные. В
82 частности, в этих функциях не проверяются входные данные.
83 Каждая связка покрывается высокоуровневой функцией, которая
85 обрабатывает все данные целиком. В высокоуровневых функциях есть
86 проверка входных данных.
87 Ожидается
89 Общее состояние связки функций не изменяется вне этих функций.
90 Ожидается [ERR_BAD_INPUT]
92 Все входные указатели действительны.
93 Предусловие
95 Если не оговорено противное, то входные буферы функций связки не
96 пересекаются.
97
99 size_t brngCTR_keep ()
100 Возвращается длина состояния (в октетах) функций генерации в режиме
101 CTR.
102 Возвращает
104 Длина состояния.
105 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 Возвращает
114 ERR_OK, если данные успешно сгенерированы, и код ошибки в противном
115 случае.
116 Предупреждения
118 При многократном вызове функции с одним и тем же ключом должны
119 использоваться различные синхропосылки. При повторе синхропосылок
120 могут быть повторно сгенерированы те же данные.
121 Прим.
123 Первоначальное содержимое buf используется для формирования
124 дополнительного слова X алгоритма генерации (см. п. 6.2.2). Слово X
125 разбивается на последовательные блоки из 32 октетов, при
126 необходимости дополняясь нулевыми октетами.
127 Аргументы
129 buf дополн. / псевдослучайные данные
130 count число октетов buf
131 key ключ
132 iv первонач. / обновл. синхропосылка
133 void brngCTRStart (void * state, const octet key[32], const octet iv[32])
135 По ключу key и синхропосылке iv в state формируются структуры данных,
136 необходимые для генерации псевдослучайных чисел в режиме CTR.
137 Предусловие
139 По адресу state зарезервировано brngCTR_keep() октетов.
140 Предупреждения
142 При многократном вызове функции с одним и тем же ключом должны
143 использоваться различные синхропосылки. При повторе синхропосылок
144 могут быть повторно сгенерированы те же данные.
145 Прим.
147 Разрешается передавать нулевой указатель iv. В этом случае будет
148 использоваться нулевая синхропосылка.
149 Аргументы
151 state состояние
152 key ключ
153 iv синхропосылка
154 void brngCTRStepG (octet iv[32], void * state)
156 Возвращается синхропосылка iv, установленная при вызове brngCTRStart()
157 и измененная затем при последовательных вызовах brngCTRStepR().
158 Ожидается
160 (brngCTRStepR()* < brngCTRStepG())*.
161 Прим.
163 Если сгенерировано полное число блоков, то полученная синхропосылка
164 будет отличаться от ранее использованных. Поэтому эту синхропосылку
165 можно задавать при повторном вызове функций связки с тем же ключом.
166 Аргументы
168 iv синхропосылка
169 state состояние
170 void brngCTRStepR (void * buf, size_t count, void * state)
172 В буфер [count]buf записываются октеты, полученные в результате
173 псевдослучайной генерации в режиме CTR. При генерации используются
174 структуры данных, развернутые в state.
175 Ожидается
177 brngCTRStart() < brngCTRStepR()*.
178 Прим.
180 Данные в режиме CTR генерируются блоками по 32 октета. Реализована
181 буферизация блоков и функцию можно вызвать с произвольным значением
182 count. Если не все данные сгенерированного ранее блока
183 израсходованы, то они будут возвращены в первую очередь.
184 Первоначальное содержимое buf используется для формирования
186 дополнительного слова X алгоритма генерации (см. п. 6.2.2). Слово X
187 разбивается на последовательные блоки из 32 октетов, при
188 необходимости дополняясь нулевыми октетами.
189 Если работает буферизация и возвращаются данные сгенерированного
191 ранее блока, то соответствующие октеты buf не используются для
192 формирования слова X, эти октеты пропускаются. Поэтому, в
193 частности, строки
194 brngCTRStepR(buf + 16, 16, state), brngCTRStepR(buf + 16, 16, state);
196 brngCTRStepR(buf, 32, state);
197 вызываемые сразу после brngCTRStart(), не эквивалентны друг другу.
200 Аргументы
202 buf дополн. / псевдослучайные данные
203 count число октетов buf
204 state состояние
205 size_t brngHMAC_keep ()
207 Возвращается длина состояния (в октетах) функций генерации в режиме
208 HMAC.
209 Возвращает
211 Длина состояния.
212 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 Ожидается [ERR_BAD_INPUT]
220 Буферы buf и iv не пересекаются.
221 Возвращает
223 ERR_OK, если данные успешно сгенерированы, и код ошибки в противном
224 случае.
225 Предупреждения
227 При многократном вызове функции с одним и тем же ключом должны
228 использоваться различные синхропосылки. При повторе синхропосылок
229 будут повторно сгенерированы те же данные.
230 Прим.
232 Ограничений на iv_len нет (ср. с функцией brngHMACStart()).
233 Рекомендуется использовать ключ из 32 октетов.
235 Аргументы
237 buf выходные данные
238 count число октетов buf
239 key ключ
240 key_len длина ключа в октетах
241 iv синхропосылка
242 iv_len длина синхропосылки в октетах
243 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 Предусловие
251 По адресу state зарезервировано brngHMAC_keep() октетов.
252 Ожидается
254 Если длина синхропосылки в октетах (iv_len) больше 64, то буфер iv
255 остается корректным и постоянным вплоть до завершения работы с
256 механизмом.
257 Предупреждения
259 При многократном вызове функции с одним и тем же ключом должны
260 использоваться различные синхропосылки. При повторе синхропосылок
261 будут повторно сгенерированы те же данные.
262 Прим.
264 Рекомендуется использовать ключ из 32 октетов.
265 При iv_len <= 64 содержимое [iv_len]iv сохраняется в state.
267 Аргументы
269 state состояние
270 key ключ
271 key_len длина ключа в октетах
272 iv синхропосылка
273 iv_len длина синхропосылки в октетах
274 void brngHMACStepR (void * buf, size_t count, void * state)
276 В буфер [count]buf записываются октеты, полученные в результате
277 псевдослучайной генерации в режиме HMAC. При генерации используются
278 структуры данных, развернутые в state.
279 Ожидается
281 brngHMACStart() < brngHMACStepR()*.
282 Прим.
284 Данные в режиме HMAC генерируются блоками по 32 октета. Реализована
285 буферизация блоков и функцию можно вызвать с произвольным значением
286 count. Если не все данные сгенерированного ранее блока
287 израсходованы, то они будут возвращены в первую очередь.
288 Аргументы
290 buf псевдослучайные данные
291 count размер buf в октетах
292 state состояние
293
295 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
296Библиотека Bee2 Пт 23 Июн 2023 brng.h(3)