1bash.h(3) Library Functions Manual bash.h(3)
2
3
4
6 bash.h - Алгоритмы СТБ 34.101.77 (bash)
7
8
10 #include 'bee2/defs.h'
11
12
13 Функции
14 size_t bashF_deep ()
15 Глубина стека sponge-функции
16 void bashF (octet block[192], void *stack)
17 Sponge-функция
18 size_t bashHash_keep ()
19 Длина состояния функций хэширования
20 void bashHashStart (void *state, size_t l)
21 Инициализация хэширования
22 void bashHashStepH (const void *buf, size_t count, void *state)
23 Хэширование фрагмента данных
24 void bashHashStepG (octet hash[], size_t hash_len, void *state)
25 Определение хэш-значения
26 bool_t bashHashStepV (const octet hash[], size_t hash_len, void *state)
27 Проверка хэш-значения
28 err_t bashHash (octet hash[], size_t l, const void *src, size_t count)
29 Хэширование
30 size_t bashPrg_keep ()
31 Длина состояния автомата
32 void bashPrgStart (void *state, size_t l, size_t d, const octet ann[],
33 size_t ann_len, const octet key[], size_t key_len)
34 Инициализация автомата
35 void bashPrgRestart (const octet ann[], size_t ann_len, const octet
36 key[], size_t key_len, void *state)
37 Повторная инициализация автомата
38 void bashPrgAbsorbStart (void *state)
39 Начало загрузки данных
40 void bashPrgAbsorbStep (const void *buf, size_t count, void *state)
41 Шаг загрузки данных
42 void bashPrgAbsorb (const void *buf, size_t count, void *state)
43 Загрузка данных
44 void bashPrgSqueezeStart (void *state)
45 Начало выгрузки данных
46 void bashPrgSqueezeStep (void *buf, size_t count, void *state)
47 Шаг выгрузки данных
48 void bashPrgSqueeze (void *buf, size_t count, void *state)
49 Выгрузка данных
50 void bashPrgEncrStart (void *state)
51 Начало зашифрования
52 void bashPrgEncrStep (void *buf, size_t count, void *state)
53 Шаг зашифрования
54 void bashPrgEncr (void *buf, size_t count, void *state)
55 Зашифрование
56 void bashPrgDecrStart (void *state)
57 Начало расшифрования
58 void bashPrgDecrStep (void *buf, size_t count, void *state)
59 Шаг расшифрования
60 void bashPrgDecr (void *buf, size_t count, void *state)
61 Расшифрование
62 void bashPrgRatchet (void *state)
63 Необратимое изменение автомата
64
66 Алгоритмы СТБ 34.101.77
67
68 СТБ 34.101.77 определяет семейство алгоритмов хэширования на основе
69 sponge-функции bash-f, реализованной в bashF(). Sponge-функция имеет
70 самостоятельное значение и может использоваться за пределами модуля
71 bash. Глубина стека bashF() определяется с помощью функции
72 bashF_keep().
73
74 При сборке библиотеки через опцию BASH_PLATFORM можно запросить
75 использование реализации bashF(), оптимизированной для одной из 5
76 аппаратных платформ:
77
78 • 64-разрядной (BASH_64),
79
80 • 32-разрядной (BASH_32),
81
82 • Intel SSE2 (BASH_SSE2),
83
84 • Intel AVX2 (BASH_AVX2),
85
86 • Intel AVX512 (BASH_AVX512),
87
88 • ARM NEON (BASH_NEON). По умолчанию используется реализация для
89 платформы BASH_64 либо, если 64-разрядные регистры не поддерживаются,
90 BASH_32.
91
92 Глубина стека bashF() определяется с помощью функции bashF_deep().
93
94 Конкретный алгоритм хэширования bashHashNNN возвращает NNN-битовые
95 хэш-значения, где NNN кратно 32 и не превосходит 512. Параметр NNN
96 регулируется уровнем стойкости l = NNN / 2.
97
98 Хэширование выполняется по схеме:
99
100 • определить длину хэш-состояния с помощью функции bashHash_keep();
101
102 • подготовить буфер памяти для состояния;
103
104 • инициализировать состояние с помощью bashHashStart(). Передать в эту
105 функцию требуемый уровень стойкости;
106
107 • обработать фрагменты хэшируемых данных с помощью bashHashStepH();
108
109 • определить хэш-значение с помощью bashHashStepG() или проверить его с
110 помощью bashHashStepV().
111
112 Функции bashHashStart(), bashHashStepH(), bashHashStepG(),
113 bashHashStepV() используют общее хэш-состояние и образуют связку.
114 Функции связки являются низкоуровневыми --- в них не проверяются
115 входные данные. Связка покрывается высокоуровневой функцией bashHash().
116
117 Стандартные уровни l = 128, 192, 256 поддержаны макросами bashNNNXXX.
118
119 Кроме алгоритмов хэширования, СТБ 34.101.77 определяет
120 криптографический автомат на основе sponge-функции и программируемые
121 алгоритмы -- последовательности команд автомата. Длина состояния
122 автомата определяется с помощью функции bashPrg_keep().
123
124 Перечень команд:
125
126 • start (инициализировать);
127
128 • restart (повторно инициализировать);
129
130 • absorb (загрузить данные);
131
132 • squeeze (выгрузить данные);
133
134 • encrypt (зашифровать, сокращается до encr);
135
136 • decrypt (расшифровать, сокращается до decr);
137
138 • ratchet (необратимо изменить автомат).
139
140 Еще одна команда, commit, является внутренней, она вызывается из других
141 команд.
142
143 Команды start, restart, ratchet реализованы в функциях bashPrgStart(),
144 bashPrgRestart(), bashPrgRatchet().
145
146 Команды absorb, squeeze, encrypt, decrypt обрабатывают данные
147 потенциально произвольного объема. Поэтому предусмотрена стандартная
148 цепочечная обработка по схеме Start/Step. Схема поддерживается
149 функциями bashPrgCmdStart(), bashPrgCmdStep(), где Cmd -- имя команды.
150 Обратим внимание, что шаг Stop отсутствует. Он не нужен, потому что
151 команды автомата выполняются в отложенной манере --- команда
152 завершается при запуске следующей.
153
154 В функциях, реализующих команды, автомат программируемых алгоритмов
155 отождествляется со своим состоянием. Используется приемлемый (и
156 отражающий суть дела) жаргон: 'загрузить в автомат', 'выгрузить из
157 автомата'.
158
159 Конкретные программируемые алгоритмы, в том числе определенные в СТБ
160 34.101.77, не реализованы. Их легко сконструировать, вызывая
161 функции-команды в определенной последовательности.
162
163 Ожидается
164 Общее состояние связки функций не изменяется вне этих функций.
165
166 Предусловие
167 Все входные указатели низкоуровневых функций действительны.
168
169 Если не оговорено противное, то входные буферы функций связки не
170 пересекаются.
171
172 Регулярность
173 Реализация для платформ BASH_SSE2, BASH_AVX2, BASH_AVX512 могут
174 оставлять в стеке данные, которые не помещаются в расширенные
175 регистры соответствующих архитектур.
176
178 void bashF (octet block[192], void * stack)
179 Буфер block преобразуется с помощью sponge-функции bash-f.
180
181 Предусловие
182 Буфер block корректен.
183
184 Аргументы
185 block прообраз/образ
186 stack стек
187
188 size_t bashF_deep ()
189 Возвращается глубина стека (в октетах) sponge-функции.
190
191 Возвращает
192 Глубина стека.
193
194 err_t bashHash (octet hash[], size_t l, const void * src, size_t count)
195 С помощью алгоритма bash уровня стойкости l определяется хэш-значение
196 [l / 4]hash буфера [count]src.
197
198 Ожидается [ERR_BAD_PARAM]
199 l > 0 && l % 16 == 0 && l <= 256.
200
201 Ожидается [ERR_BAD_INPUT]
202 Буферы hash, src корректны.
203
204 Возвращает
205 ERR_OK, если хэширование завершено успешно, и код ошибки в
206 противном случае.
207
208 Прим.
209 Буферы могут пересекаться.
210
211 Аргументы
212 hash хэш-значение
213 l уровень стойкости
214 src данные
215 count число октетов данных
216
217 size_t bashHash_keep ()
218 Возвращается длина состояния (в октетах) алгоритмов хэширования bash.
219
220 Возвращает
221 Длина состояния.
222
223 void bashHashStart (void * state, size_t l)
224 В state формируются структуры данных, необходимые для хэширования с
225 помощью алгоритмов bash уровня l.
226
227 Предусловие
228 l > 0 && l % 16 == 0 && l <= 256.
229
230 По адресу state зарезервировано bashHash_keep() октетов.
231
232 Аргументы
233 state состояние
234 l уровень стойкости
235
236 void bashHashStepG (octet hash[], size_t hash_len, void * state)
237 Определяются первые октеты [hash_len]hash окончательного хэш-значения
238 всех данных, обработанных до этого функцией bashHashStepH().
239
240 Предусловие
241 hash_len <= l / 4, где l -- уровень стойкости, ранее переданный в
242 bashHashStart().
243
244 Ожидается
245 (bashHashStepH()* < bashHashStepG())*.
246
247 Прим.
248 Если продолжение хэширования не предполагается, то буферы hash и
249 state могут пересекаться.
250
251 Аргументы
252 hash хэш-значение
253 hash_len длина hash
254 state состояние
255
256 void bashHashStepH (const void * buf, size_t count, void * state)
257 Текущее хэш-значение, размещенное в state, пересчитывается по алгоритму
258 bash с учетом нового фрагмента данных [count]buf.
259
260 Ожидается
261 bashHashStart() < bashHashStepH()*.
262
263 Аргументы
264 buf данные
265 count число октетов данных
266 state состояние
267
268 bool_t bashHashStepV (const octet hash[], size_t hash_len, void * state)
269 Проверяется, что первые октеты окончательного хэш-значения всех данных,
270 обработанных до этого функцией bashHashStepH(), совпадают с
271 [hash_len]hash.
272
273 Предусловие
274 hash_len <= l / 4, где l -- уровень стойкости, ранее переданный в
275 bashHashStart().
276
277 Ожидается
278 (bashHashStepH()* < bashHashStepV())*.
279
280 Возвращает
281 Признак успеха.
282
283 Аргументы
284 hash контрольное хэш-значение
285 hash_len длина hash
286 state состояние
287
288 size_t bashPrg_keep ()
289 Возвращается длина состояния (в октетах) автомата программируемых
290 алгоритмов.
291
292 Возвращает
293 Длина состояния.
294
295 void bashPrgAbsorb (const void * buf, size_t count, void * state)
296 В автомат state загружаются данные [count]buf.
297
298 Ожидается
299 bashPrgStart() < bashPrgAbsorb()*.
300
301 Аргументы
302 buf данные
303 count число октетов данных
304 state автомат
305
306 void bashPrgAbsorbStart (void * state)
307 Инициализируется загрузка данных в автомат state.
308
309 Ожидается
310 bashPrgStart() < bashPrgAbsorbStart().
311
312 Прим.
313 В начале загрузки завершается предыдущая команда.
314
315 Аргументы
316 state автомат
317
318 void bashPrgAbsorbStep (const void * buf, size_t count, void * state)
319 Выполняется загрузка в автомат state фрагмента [count]buf.
320
321 Ожидается
322 bashPrgAbsorbStart() < bashPrgAbsorbStep()*.
323
324 Аргументы
325 buf данные
326 count число октетов данных
327 state автомат
328
329 void bashPrgDecr (void * buf, size_t count, void * state)
330 С помощью автомата state расшифровываются данные [count]buf.
331
332 Предусловие
333 Автомат находится в ключевом режиме.
334
335 Ожидается
336 bashPrgStart() < bashPrgDecr()*.
337
338 Аргументы
339 buf данные
340 count число октетов данных
341 state автомат
342
343 void bashPrgDecrStart (void * state)
344 Инициализируется расшифрование данных с помощью автомата state.
345
346 Предусловие
347 Автомат находится в ключевом режиме.
348
349 Ожидается
350 bashPrgStart() < bashPrgDecrStart().
351
352 Прим.
353 В начале расшифрования завершается предыдущая команда.
354
355 Аргументы
356 state автомат
357
358 void bashPrgDecrStep (void * buf, size_t count, void * state)
359 Выполняется расшифрование с помощью автомата state фрагмента
360 [count]buf.
361
362 Ожидается
363 bashPrgDecrStart() < bashPrgDecrStep()*.
364
365 Аргументы
366 buf данные
367 count число октетов данных
368 state автомат
369
370 void bashPrgEncr (void * buf, size_t count, void * state)
371 С помощью автомата state зашифровываются данные [count]buf.
372
373 Предусловие
374 Автомат находится в ключевом режиме.
375
376 Ожидается
377 bashPrgStart() < bashPrgEncr()*.
378
379 Аргументы
380 buf данные
381 count число октетов данных
382 state автомат
383
384 void bashPrgEncrStart (void * state)
385 Инициализируется зашифрование с помощью автомата state.
386
387 Ожидается
388 bashPrgStart() < bashPrgEncrStart().
389
390 Предусловие
391 Автомат находится в ключевом режиме.
392
393 Прим.
394 В начале зашифрования завершается предыдущая команда.
395
396 Аргументы
397 state автомат
398
399 void bashPrgEncrStep (void * buf, size_t count, void * state)
400 Выполняется зашифрование с помощью автомата state фрагмента [count]buf.
401
402 Ожидается
403 bashPrgEncrStart() < bashPrgEncrStep()*.
404
405 Аргументы
406 buf данные
407 count число октетов данных
408 state автомат
409
410 void bashPrgRatchet (void * state)
411 Автомат state меняется так, что по новому состоянию трудно определить
412 предыдущее.
413
414 Ожидается
415 bashPrgStart() < bashPrgRatchet().
416
417 Аргументы
418 state автомат
419
420 void bashPrgRestart (const octet ann[], size_t ann_len, const octet key[],
421 size_t key_len, void * state)
422 По анонсу [ann_len]ann и ключу [key_len]key выполняется повторная
423 инициализация автомата state.
424
425 Предусловие
426 ann_len % 4 == 0 && ann_len <= 60.
427
428 key_len % 4 == 0 && key_len <= 60.
429
430 key_len == 0 || key_len >= l / 8,
431
432 Ожидается
433 bashPrgStart() < bashPrgRestart()*.
434
435 Прим.
436 Если key_len != 0, то автомат переводится в ключевой режим.
437
438 Аргументы
439 ann анонс
440 ann_len длина анонса в октетах
441 key ключ
442 key_len длина ключа в октетах
443 state автомат
444
445 void bashPrgSqueeze (void * buf, size_t count, void * state)
446 Из автомата state выгружаются данные [count]buf.
447
448 Ожидается
449 bashPrgStart() < bashPrgSqueeze()*.
450
451 Аргументы
452 buf данные
453 count число октетов данных
454 state автомат
455
456 void bashPrgSqueezeStart (void * state)
457 Инициализируется выгрузка данных из автомата state.
458
459 Ожидается
460 bashPrgStart() < bashPrgSqueezeStart().
461
462 Прим.
463 В начале выгрузки завершается предыдущая команда.
464
465 Аргументы
466 state автомат
467
468 void bashPrgSqueezeStep (void * buf, size_t count, void * state)
469 Выполняется выгрузка из автомата state фрагмента [count]buf.
470
471 Ожидается
472 bashPrgSqueezeStart() < bashPrgSqueezeStep()*.
473
474 Аргументы
475 buf данные
476 count число октетов данных
477 state автомат
478
479 void bashPrgStart (void * state, size_t l, size_t d, const octet ann[],
480 size_t ann_len, const octet key[], size_t key_len)
481 По уровню стойкости l, емкости d, анонсу [ann_len]ann и ключу
482 [key_len]ley инициализуется автомат state.
483
484 Предусловие
485 l == 128 || l == 192 || l == 256.
486
487 d == 1 || d == 2.
488
489 ann_len % 4 == 0 && ann_len <= 60.
490
491 key_len % 4 == 0 && key_len <= 60.
492
493 key_len == 0 || key_len >= l / 8, где l --- уровень, заданный в
494 bashPrgStart().
495
496 По адресу state зарезервировано bashPrg_keep() октетов.
497
498 Прим.
499 Если key_len != 0, то автомат переводится в ключевой режим.
500
501 Аргументы
502 state автомат
503 l уровень стойкости
504 d емкость
505 ann анонс
506 ann_len длина анонса в октетах
507 key ключ
508 key_len длина ключа в октетах
509
511 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
512
513
514
515Библиотека Bee2 Ср 19 Июл 2023 00:00:00 bash.h(3)