bash.h - Man Page

Алгоритмы СТБ 34.101.77 (bash)

Synopsis

#include 'bee2/defs.h'

Функции

size_t bashF_deep ()
Глубина стека sponge-функции
void bashF (octet block[192], void *stack)
Sponge-функция
size_t bashHash_keep ()
Длина состояния функций хэширования
void bashHashStart (void *state, size_t l)
Инициализация хэширования
void bashHashStepH (const void *buf, size_t count, void *state)
Хэширование фрагмента данных
void bashHashStepG (octet hash[], size_t hash_len, void *state)
Определение хэш-значения
bool_t bashHashStepV (const octet hash[], size_t hash_len, void *state)
Проверка хэш-значения
err_t bashHash (octet hash[], size_t l, const void *src, size_t count)
Хэширование
size_t bashPrg_keep ()
Длина состояния автомата
void bashPrgStart (void *state, size_t l, size_t d, const octet ann[], size_t ann_len, const octet key[], size_t key_len)
Инициализация автомата
void bashPrgRestart (const octet ann[], size_t ann_len, const octet key[], size_t key_len, void *state)
Повторная инициализация автомата
void bashPrgAbsorbStart (void *state)
Начало загрузки данных
void bashPrgAbsorbStep (const void *buf, size_t count, void *state)
Шаг загрузки данных
void bashPrgAbsorb (const void *buf, size_t count, void *state)
Загрузка данных
void bashPrgSqueezeStart (void *state)
Начало выгрузки данных
void bashPrgSqueezeStep (void *buf, size_t count, void *state)
Шаг выгрузки данных
void bashPrgSqueeze (void *buf, size_t count, void *state)
Выгрузка данных
void bashPrgEncrStart (void *state)
Начало зашифрования
void bashPrgEncrStep (void *buf, size_t count, void *state)
Шаг зашифрования
void bashPrgEncr (void *buf, size_t count, void *state)
Зашифрование
void bashPrgDecrStart (void *state)
Начало расшифрования
void bashPrgDecrStep (void *buf, size_t count, void *state)
Шаг расшифрования
void bashPrgDecr (void *buf, size_t count, void *state)
Расшифрование
void bashPrgRatchet (void *state)
Необратимое изменение автомата

Подробное описание

Алгоритмы СТБ 34.101.77

СТБ 34.101.77 определяет семейство алгоритмов хэширования на основе sponge-функции bash-f, реализованной в bashF(). Sponge-функция имеет самостоятельное значение и может использоваться за пределами модуля bash. Глубина стека bashF() определяется с помощью функции bashF_keep().

При сборке библиотеки через опцию BASH_PLATFORM можно запросить использование реализации bashF(), оптимизированной для одной из 5 аппаратных платформ:

Глубина стека bashF() определяется с помощью функции bashF_deep().

Конкретный алгоритм хэширования bashHashNNN возвращает NNN-битовые хэш-значения, где NNN кратно 32 и не превосходит 512. Параметр NNN регулируется уровнем стойкости l = NNN / 2.

Хэширование выполняется по схеме:

Функции bashHashStart(), bashHashStepH(), bashHashStepG(), bashHashStepV() используют общее хэш-состояние и образуют связку. Функции связки являются низкоуровневыми --- в них не проверяются входные данные. Связка покрывается высокоуровневой функцией bashHash().

Стандартные уровни l = 128, 192, 256 поддержаны макросами bashNNNXXX.

Кроме алгоритмов хэширования, СТБ 34.101.77 определяет криптографический автомат на основе sponge-функции и программируемые алгоритмы -- последовательности команд автомата. Длина состояния автомата определяется с помощью функции bashPrg_keep().

Перечень команд:

Еще одна команда, commit, является внутренней, она вызывается из других команд.

Команды start, restart, ratchet реализованы в функциях bashPrgStart(), bashPrgRestart(), bashPrgRatchet().

Команды absorb, squeeze, encrypt, decrypt обрабатывают данные потенциально произвольного объема. Поэтому предусмотрена стандартная цепочечная обработка по схеме Start/Step. Схема поддерживается функциями bashPrgCmdStart(), bashPrgCmdStep(), где Cmd -- имя команды. Обратим внимание, что шаг Stop отсутствует. Он не нужен, потому что команды автомата выполняются в отложенной манере --- команда завершается при запуске следующей.

В функциях, реализующих команды, автомат программируемых алгоритмов отождествляется со своим состоянием. Используется приемлемый (и отражающий суть дела) жаргон: 'загрузить в автомат', 'выгрузить из автомата'.

Конкретные программируемые алгоритмы, в том числе определенные в СТБ 34.101.77, не реализованы. Их легко сконструировать, вызывая функции-команды в определенной последовательности.

Ожидается:\n Общее состояние связки функций не изменяется вне этих функций.

Предусловие

Все входные указатели низкоуровневых функций действительны.

Если не оговорено противное, то входные буферы функций связки не пересекаются.

Регулярность:\n Реализация для платформ BASH_SSE2, BASH_AVX2, BASH_AVX512 могут

оставлять в стеке данные, которые не помещаются в расширенные регистры соответствующих архитектур.

Функции

void bashF (octet block[192], void * stack)

Буфер block преобразуется с помощью sponge-функции bash-f.

Предусловие

Буфер block корректен.

Аргументы

block [in/out] прообраз/образ
stack [in/out] стек

size_t bashF_deep ()

Возвращается глубина стека (в октетах) sponge-функции.

Возвращает

Глубина стека.

err_t bashHash (octet hash[], size_t l, const void * src, size_t count)

С помощью алгоритма bash уровня стойкости l определяется хэш-значение [l / 4]hash буфера [count]src.

Ожидается [ERR_BAD_PARAM]:\n l > 0 && l % 16 == 0 && l <= 256.

Ожидается [ERR_BAD_INPUT]:\n Буферы hash, src корректны.

Возвращает

ERR_OK, если хэширование завершено успешно, и код ошибки в противном случае.

Прим.

Буферы могут пересекаться.

Аргументы

hash хэш-значение
l уровень стойкости
src данные
count число октетов данных

size_t bashHash_keep ()

Возвращается длина состояния (в октетах) алгоритмов хэширования bash.

Возвращает

Длина состояния.

void bashHashStart (void * state, size_t l)

В state формируются структуры данных, необходимые для хэширования с помощью алгоритмов bash уровня l.

Предусловие

l > 0 && l % 16 == 0 && l <= 256.

По адресу state зарезервировано bashHash_keep() октетов.

Аргументы

state состояние
l уровень стойкости

void bashHashStepG (octet hash[], size_t hash_len, void * state)

Определяются первые октеты [hash_len]hash окончательного хэш-значения всех данных, обработанных до этого функцией bashHashStepH().

Предусловие

hash_len <= l / 4, где l -- уровень стойкости, ранее переданный в bashHashStart().

Ожидается:\n (bashHashStepH()* < bashHashStepG())*.

Прим.

Если продолжение хэширования не предполагается, то буферы hash и state могут пересекаться.

Аргументы

hash хэш-значение
hash_len длина hash
state [in/out] состояние

void bashHashStepH (const void * buf, size_t count, void * state)

Текущее хэш-значение, размещенное в state, пересчитывается по алгоритму bash с учетом нового фрагмента данных [count]buf.

Ожидается:\n bashHashStart() < bashHashStepH()*.

Аргументы

buf данные
count число октетов данных
state [in/out] состояние

bool_t bashHashStepV (const octet hash[], size_t hash_len, void * state)

Проверяется, что первые октеты окончательного хэш-значения всех данных, обработанных до этого функцией bashHashStepH(), совпадают с [hash_len]hash.

Предусловие

hash_len <= l / 4, где l -- уровень стойкости, ранее переданный в bashHashStart().

Ожидается:\n (bashHashStepH()* < bashHashStepV())*.

Возвращает

Признак успеха.

Аргументы

hash контрольное хэш-значение
hash_len длина hash
state [in/out] состояние

size_t bashPrg_keep ()

Возвращается длина состояния (в октетах) автомата программируемых алгоритмов.

Возвращает

Длина состояния.

void bashPrgAbsorb (const void * buf, size_t count, void * state)

В автомат state загружаются данные [count]buf.

Ожидается:\n bashPrgStart() < bashPrgAbsorb()*.

Аргументы

buf данные
count число октетов данных
state [in/out] автомат

void bashPrgAbsorbStart (void * state)

Инициализируется загрузка данных в автомат state.

Ожидается:\n bashPrgStart() < bashPrgAbsorbStart().

Прим.

В начале загрузки завершается предыдущая команда.

Аргументы

state [in/out] автомат

void bashPrgAbsorbStep (const void * buf, size_t count, void * state)

Выполняется загрузка в автомат state фрагмента [count]buf.

Ожидается:\n bashPrgAbsorbStart() < bashPrgAbsorbStep()*.

Аргументы

buf данные
count число октетов данных
state [in/out] автомат

void bashPrgDecr (void * buf, size_t count, void * state)

С помощью автомата state расшифровываются данные [count]buf.

Предусловие

Автомат находится в ключевом режиме.

Ожидается:\n bashPrgStart() < bashPrgDecr()*.

Аргументы

buf [in/out] данные
count число октетов данных
state [in/out] автомат

void bashPrgDecrStart (void * state)

Инициализируется расшифрование данных с помощью автомата state.

Предусловие

Автомат находится в ключевом режиме.

Ожидается:\n bashPrgStart() < bashPrgDecrStart().

Прим.

В начале расшифрования завершается предыдущая команда.

Аргументы

state [in/out] автомат

void bashPrgDecrStep (void * buf, size_t count, void * state)

Выполняется расшифрование с помощью автомата state фрагмента [count]buf.

Ожидается:\n bashPrgDecrStart() < bashPrgDecrStep()*.

Аргументы

buf [in/out] данные
count число октетов данных
state [in/out] автомат

void bashPrgEncr (void * buf, size_t count, void * state)

С помощью автомата state зашифровываются данные [count]buf.

Предусловие

Автомат находится в ключевом режиме.

Ожидается:\n bashPrgStart() < bashPrgEncr()*.

Аргументы

buf [in/out] данные
count число октетов данных
state [in/out] автомат

void bashPrgEncrStart (void * state)

Инициализируется зашифрование с помощью автомата state.

Ожидается:\n bashPrgStart() < bashPrgEncrStart().

Предусловие

Автомат находится в ключевом режиме.

Прим.

В начале зашифрования завершается предыдущая команда.

Аргументы

state [in/out] автомат

void bashPrgEncrStep (void * buf, size_t count, void * state)

Выполняется зашифрование с помощью автомата state фрагмента [count]buf.

Ожидается:\n bashPrgEncrStart() < bashPrgEncrStep()*.

Аргументы

buf [in/out] данные
count число октетов данных
state [in/out] автомат

void bashPrgRatchet (void * state)

Автомат state меняется так, что по новому состоянию трудно определить предыдущее.

Ожидается:\n bashPrgStart() < bashPrgRatchet().

Аргументы

state [in/out] автомат

void bashPrgRestart (const octet ann[], size_t ann_len, const octet key[], size_t key_len, void * state)

По анонсу [ann_len]ann и ключу [key_len]key выполняется повторная инициализация автомата state.

Предусловие

ann_len % 4 == 0 && ann_len <= 60.

key_len % 4 == 0 && key_len <= 60.

key_len == 0 || key_len >= l / 8,

Ожидается:\n bashPrgStart() < bashPrgRestart()*.

Прим.

Если key_len != 0, то автомат переводится в ключевой режим.

Аргументы

ann анонс
ann_len длина анонса в октетах
key ключ
key_len длина ключа в октетах
state автомат

void bashPrgSqueeze (void * buf, size_t count, void * state)

Из автомата state выгружаются данные [count]buf.

Ожидается:\n bashPrgStart() < bashPrgSqueeze()*.

Аргументы

buf данные
count число октетов данных
state [in/out] автомат

void bashPrgSqueezeStart (void * state)

Инициализируется выгрузка данных из автомата state.

Ожидается:\n bashPrgStart() < bashPrgSqueezeStart().

Прим.

В начале выгрузки завершается предыдущая команда.

Аргументы

state [in/out] автомат

void bashPrgSqueezeStep (void * buf, size_t count, void * state)

Выполняется выгрузка из автомата state фрагмента [count]buf.

Ожидается:\n bashPrgSqueezeStart() < bashPrgSqueezeStep()*.

Аргументы

buf данные
count число октетов данных
state [in/out] автомат

void bashPrgStart (void * state, size_t l, size_t d, const octet ann[], size_t ann_len, const octet key[], size_t key_len)

По уровню стойкости l, емкости d, анонсу [ann_len]ann и ключу [key_len]ley инициализуется автомат state.

Предусловие

l == 128 || l == 192 || l == 256.

d == 1 || d == 2.

ann_len % 4 == 0 && ann_len <= 60.

key_len % 4 == 0 && key_len <= 60.

key_len == 0 || key_len >= l / 8, где l --- уровень, заданный в bashPrgStart().

По адресу state зарезервировано bashPrg_keep() октетов.

Прим.

Если key_len != 0, то автомат переводится в ключевой режим.

Аргументы

state автомат
l уровень стойкости
d емкость
ann анонс
ann_len длина анонса в октетах
key ключ
key_len длина ключа в октетах

Автор

Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.

Info

Пн 13 Фев 2023 Библиотека Bee2