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 аппаратных платформ:
- 64-разрядной (BASH_64),
- 32-разрядной (BASH_32),
- Intel SSE2 (BASH_SSE2),
- Intel AVX2 (BASH_AVX2),
- Intel AVX512 (BASH_AVX512),
- ARM NEON (BASH_NEON). По умолчанию используется реализация для платформы BASH_64 либо, если 64-разрядные регистры не поддерживаются, BASH_32.
Глубина стека bashF() определяется с помощью функции bashF_deep().
Конкретный алгоритм хэширования bashHashNNN возвращает NNN-битовые хэш-значения, где NNN кратно 32 и не превосходит 512. Параметр NNN регулируется уровнем стойкости l = NNN / 2.
Хэширование выполняется по схеме:
- определить длину хэш-состояния с помощью функции bashHash_keep();
- подготовить буфер памяти для состояния;
- инициализировать состояние с помощью bashHashStart(). Передать в эту функцию требуемый уровень стойкости;
- обработать фрагменты хэшируемых данных с помощью bashHashStepH();
- определить хэш-значение с помощью bashHashStepG() или проверить его с помощью bashHashStepV().
Функции bashHashStart(), bashHashStepH(), bashHashStepG(), bashHashStepV() используют общее хэш-состояние и образуют связку. Функции связки являются низкоуровневыми --- в них не проверяются входные данные. Связка покрывается высокоуровневой функцией bashHash().
Стандартные уровни l = 128, 192, 256 поддержаны макросами bashNNNXXX.
Кроме алгоритмов хэширования, СТБ 34.101.77 определяет криптографический автомат на основе sponge-функции и программируемые алгоритмы -- последовательности команд автомата. Длина состояния автомата определяется с помощью функции bashPrg_keep().
Перечень команд:
- start (инициализировать);
- restart (повторно инициализировать);
- absorb (загрузить данные);
- squeeze (выгрузить данные);
- encrypt (зашифровать, сокращается до encr);
- decrypt (расшифровать, сокращается до decr);
- ratchet (необратимо изменить автомат).
Еще одна команда, 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 из исходного текста.