1bash.h(3) Library Functions Manual bash.h(3)
2
6 bash.h - Алгоритмы СТБ 34.101.77 (bash)
7
10 #include 'bee2/defs.h'
11 Функции
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 СТБ 34.101.77 определяет семейство алгоритмов хэширования на основе
69 sponge-функции bash-f, реализованной в bashF(). Sponge-функция имеет
70 самостоятельное значение и может использоваться за пределами модуля
71 bash. Глубина стека bashF() определяется с помощью функции
72 bashF_keep().
73 При сборке библиотеки через опцию BASH_PLATFORM можно запросить
75 использование реализации bashF(), оптимизированной для одной из 5
76 аппаратных платформ:
77 • 64-разрядной (BASH_64),
79 • 32-разрядной (BASH_32),
81 • Intel SSE2 (BASH_SSE2),
83 • Intel AVX2 (BASH_AVX2),
85 • Intel AVX512 (BASH_AVX512),
87 • ARM NEON (BASH_NEON). По умолчанию используется реализация для
89 платформы BASH_64 либо, если 64-разрядные регистры не поддерживаются,
90 BASH_32.
91 Глубина стека bashF() определяется с помощью функции bashF_deep().
93 Конкретный алгоритм хэширования bashHashNNN возвращает NNN-битовые
95 хэш-значения, где NNN кратно 32 и не превосходит 512. Параметр NNN
96 регулируется уровнем стойкости l = NNN / 2.
97 Хэширование выполняется по схеме:
99 • определить длину хэш-состояния с помощью функции bashHash_keep();
101 • подготовить буфер памяти для состояния;
103 • инициализировать состояние с помощью bashHashStart(). Передать в эту
105 функцию требуемый уровень стойкости;
106 • обработать фрагменты хэшируемых данных с помощью bashHashStepH();
108 • определить хэш-значение с помощью bashHashStepG() или проверить его с
110 помощью bashHashStepV().
111 Функции bashHashStart(), bashHashStepH(), bashHashStepG(),
113 bashHashStepV() используют общее хэш-состояние и образуют связку.
114 Функции связки являются низкоуровневыми --- в них не проверяются
115 входные данные. Связка покрывается высокоуровневой функцией bashHash().
116 Стандартные уровни l = 128, 192, 256 поддержаны макросами bashNNNXXX.
118 Кроме алгоритмов хэширования, СТБ 34.101.77 определяет
120 криптографический автомат на основе sponge-функции и программируемые
121 алгоритмы -- последовательности команд автомата. Длина состояния
122 автомата определяется с помощью функции bashPrg_keep().
123 Перечень команд:
125 • start (инициализировать);
127 • restart (повторно инициализировать);
129 • absorb (загрузить данные);
131 • squeeze (выгрузить данные);
133 • encrypt (зашифровать, сокращается до encr);
135 • decrypt (расшифровать, сокращается до decr);
137 • ratchet (необратимо изменить автомат).
139 Еще одна команда, commit, является внутренней, она вызывается из других
141 команд.
142 Команды start, restart, ratchet реализованы в функциях bashPrgStart(),
144 bashPrgRestart(), bashPrgRatchet().
145 Команды absorb, squeeze, encrypt, decrypt обрабатывают данные
147 потенциально произвольного объема. Поэтому предусмотрена стандартная
148 цепочечная обработка по схеме Start/Step. Схема поддерживается
149 функциями bashPrgCmdStart(), bashPrgCmdStep(), где Cmd -- имя команды.
150 Обратим внимание, что шаг Stop отсутствует. Он не нужен, потому что
151 команды автомата выполняются в отложенной манере --- команда
152 завершается при запуске следующей.
153 В функциях, реализующих команды, автомат программируемых алгоритмов
155 отождествляется со своим состоянием. Используется приемлемый (и
156 отражающий суть дела) жаргон: 'загрузить в автомат', 'выгрузить из
157 автомата'.
158 Конкретные программируемые алгоритмы, в том числе определенные в СТБ
160 34.101.77, не реализованы. Их легко сконструировать, вызывая
161 функции-команды в определенной последовательности.
162 Ожидается
164 Общее состояние связки функций не изменяется вне этих функций.
165 Предусловие
167 Все входные указатели низкоуровневых функций действительны.
168 Если не оговорено противное, то входные буферы функций связки не
170 пересекаются.
171 Регулярность
173 Реализация для платформ BASH_SSE2, BASH_AVX2, BASH_AVX512 могут
174 оставлять в стеке данные, которые не помещаются в расширенные
175 регистры соответствующих архитектур.
176
178 void bashF (octet block[192], void * stack)
179 Буфер block преобразуется с помощью sponge-функции bash-f.
180 Предусловие
182 Буфер block корректен.
183 Аргументы
185 block прообраз/образ
186 stack стек
187 size_t bashF_deep ()
189 Возвращается глубина стека (в октетах) sponge-функции.
190 Возвращает
192 Глубина стека.
193 err_t bashHash (octet hash[], size_t l, const void * src, size_t count)
195 С помощью алгоритма bash уровня стойкости l определяется хэш-значение
196 [l / 4]hash буфера [count]src.
197 Ожидается [ERR_BAD_PARAM]
199 l > 0 && l % 16 == 0 && l <= 256.
200 Ожидается [ERR_BAD_INPUT]
202 Буферы hash, src корректны.
203 Возвращает
205 ERR_OK, если хэширование завершено успешно, и код ошибки в
206 противном случае.
207 Прим.
209 Буферы могут пересекаться.
210 Аргументы
212 hash хэш-значение
213 l уровень стойкости
214 src данные
215 count число октетов данных
216 size_t bashHash_keep ()
218 Возвращается длина состояния (в октетах) алгоритмов хэширования bash.
219 Возвращает
221 Длина состояния.
222 void bashHashStart (void * state, size_t l)
224 В state формируются структуры данных, необходимые для хэширования с
225 помощью алгоритмов bash уровня l.
226 Предусловие
228 l > 0 && l % 16 == 0 && l <= 256.
229 По адресу state зарезервировано bashHash_keep() октетов.
231 Аргументы
233 state состояние
234 l уровень стойкости
235 void bashHashStepG (octet hash[], size_t hash_len, void * state)
237 Определяются первые октеты [hash_len]hash окончательного хэш-значения
238 всех данных, обработанных до этого функцией bashHashStepH().
239 Предусловие
241 hash_len <= l / 4, где l -- уровень стойкости, ранее переданный в
242 bashHashStart().
243 Ожидается
245 (bashHashStepH()* < bashHashStepG())*.
246 Прим.
248 Если продолжение хэширования не предполагается, то буферы hash и
249 state могут пересекаться.
250 Аргументы
252 hash хэш-значение
253 hash_len длина hash
254 state состояние
255 void bashHashStepH (const void * buf, size_t count, void * state)
257 Текущее хэш-значение, размещенное в state, пересчитывается по алгоритму
258 bash с учетом нового фрагмента данных [count]buf.
259 Ожидается
261 bashHashStart() < bashHashStepH()*.
262 Аргументы
264 buf данные
265 count число октетов данных
266 state состояние
267 bool_t bashHashStepV (const octet hash[], size_t hash_len, void * state)
269 Проверяется, что первые октеты окончательного хэш-значения всех данных,
270 обработанных до этого функцией bashHashStepH(), совпадают с
271 [hash_len]hash.
272 Предусловие
274 hash_len <= l / 4, где l -- уровень стойкости, ранее переданный в
275 bashHashStart().
276 Ожидается
278 (bashHashStepH()* < bashHashStepV())*.
279 Возвращает
281 Признак успеха.
282 Аргументы
284 hash контрольное хэш-значение
285 hash_len длина hash
286 state состояние
287 size_t bashPrg_keep ()
289 Возвращается длина состояния (в октетах) автомата программируемых
290 алгоритмов.
291 Возвращает
293 Длина состояния.
294 void bashPrgAbsorb (const void * buf, size_t count, void * state)
296 В автомат state загружаются данные [count]buf.
297 Ожидается
299 bashPrgStart() < bashPrgAbsorb()*.
300 Аргументы
302 buf данные
303 count число октетов данных
304 state автомат
305 void bashPrgAbsorbStart (void * state)
307 Инициализируется загрузка данных в автомат state.
308 Ожидается
310 bashPrgStart() < bashPrgAbsorbStart().
311 Прим.
313 В начале загрузки завершается предыдущая команда.
314 Аргументы
316 state автомат
317 void bashPrgAbsorbStep (const void * buf, size_t count, void * state)
319 Выполняется загрузка в автомат state фрагмента [count]buf.
320 Ожидается
322 bashPrgAbsorbStart() < bashPrgAbsorbStep()*.
323 Аргументы
325 buf данные
326 count число октетов данных
327 state автомат
328 void bashPrgDecr (void * buf, size_t count, void * state)
330 С помощью автомата state расшифровываются данные [count]buf.
331 Предусловие
333 Автомат находится в ключевом режиме.
334 Ожидается
336 bashPrgStart() < bashPrgDecr()*.
337 Аргументы
339 buf данные
340 count число октетов данных
341 state автомат
342 void bashPrgDecrStart (void * state)
344 Инициализируется расшифрование данных с помощью автомата state.
345 Предусловие
347 Автомат находится в ключевом режиме.
348 Ожидается
350 bashPrgStart() < bashPrgDecrStart().
351 Прим.
353 В начале расшифрования завершается предыдущая команда.
354 Аргументы
356 state автомат
357 void bashPrgDecrStep (void * buf, size_t count, void * state)
359 Выполняется расшифрование с помощью автомата state фрагмента
360 [count]buf.
361 Ожидается
363 bashPrgDecrStart() < bashPrgDecrStep()*.
364 Аргументы
366 buf данные
367 count число октетов данных
368 state автомат
369 void bashPrgEncr (void * buf, size_t count, void * state)
371 С помощью автомата state зашифровываются данные [count]buf.
372 Предусловие
374 Автомат находится в ключевом режиме.
375 Ожидается
377 bashPrgStart() < bashPrgEncr()*.
378 Аргументы
380 buf данные
381 count число октетов данных
382 state автомат
383 void bashPrgEncrStart (void * state)
385 Инициализируется зашифрование с помощью автомата state.
386 Ожидается
388 bashPrgStart() < bashPrgEncrStart().
389 Предусловие
391 Автомат находится в ключевом режиме.
392 Прим.
394 В начале зашифрования завершается предыдущая команда.
395 Аргументы
397 state автомат
398 void bashPrgEncrStep (void * buf, size_t count, void * state)
400 Выполняется зашифрование с помощью автомата state фрагмента [count]buf.
401 Ожидается
403 bashPrgEncrStart() < bashPrgEncrStep()*.
404 Аргументы
406 buf данные
407 count число октетов данных
408 state автомат
409 void bashPrgRatchet (void * state)
411 Автомат state меняется так, что по новому состоянию трудно определить
412 предыдущее.
413 Ожидается
415 bashPrgStart() < bashPrgRatchet().
416 Аргументы
418 state автомат
419 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 Предусловие
426 ann_len % 4 == 0 && ann_len <= 60.
427 key_len % 4 == 0 && key_len <= 60.
429 key_len == 0 || key_len >= l / 8,
431 Ожидается
433 bashPrgStart() < bashPrgRestart()*.
434 Прим.
436 Если key_len != 0, то автомат переводится в ключевой режим.
437 Аргументы
439 ann анонс
440 ann_len длина анонса в октетах
441 key ключ
442 key_len длина ключа в октетах
443 state автомат
444 void bashPrgSqueeze (void * buf, size_t count, void * state)
446 Из автомата state выгружаются данные [count]buf.
447 Ожидается
449 bashPrgStart() < bashPrgSqueeze()*.
450 Аргументы
452 buf данные
453 count число октетов данных
454 state автомат
455 void bashPrgSqueezeStart (void * state)
457 Инициализируется выгрузка данных из автомата state.
458 Ожидается
460 bashPrgStart() < bashPrgSqueezeStart().
461 Прим.
463 В начале выгрузки завершается предыдущая команда.
464 Аргументы
466 state автомат
467 void bashPrgSqueezeStep (void * buf, size_t count, void * state)
469 Выполняется выгрузка из автомата state фрагмента [count]buf.
470 Ожидается
472 bashPrgSqueezeStart() < bashPrgSqueezeStep()*.
473 Аргументы
475 buf данные
476 count число октетов данных
477 state автомат
478 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 Предусловие
485 l == 128 || l == 192 || l == 256.
486 d == 1 || d == 2.
488 ann_len % 4 == 0 && ann_len <= 60.
490 key_len % 4 == 0 && key_len <= 60.
492 key_len == 0 || key_len >= l / 8, где l --- уровень, заданный в
494 bashPrgStart().
495 По адресу state зарезервировано bashPrg_keep() октетов.
497 Прим.
499 Если key_len != 0, то автомат переводится в ключевой режим.
500 Аргументы
502 state автомат
503 l уровень стойкости
504 d емкость
505 ann анонс
506 ann_len длина анонса в октетах
507 key ключ
508 key_len длина ключа в октетах
509
511 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
512Библиотека Bee2 Пт 23 Июн 2023 bash.h(3)