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, не реализованы. Их легко сконструировать, вызывая функции-команды в определенной последовательности.
Ожидается
Общее состояние связки функций не изменяется вне этих функций.
Предусловие
Все входные указатели низкоуровневых функций действительны.
Если не оговорено противное, то входные буферы функций связки не пересекаются.
Регулярность
Реализация для платформ 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]
l > 0 && l % 16 == 0 && l <= 256.
Ожидается [ERR_BAD_INPUT]
Буферы 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().
- Ожидается
(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.
- Ожидается
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().
- Ожидается
(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.
- Ожидается
bashPrgStart() < bashPrgAbsorb()*.
- Аргументы
buf данные
count число октетов данных
state [in,out] автомат
void bashPrgAbsorbStart (void * state)
Инициализируется загрузка данных в автомат state.
- Ожидается
bashPrgStart() < bashPrgAbsorbStart().
Прим.
В начале загрузки завершается предыдущая команда.
- Аргументы
state [in,out] автомат
void bashPrgAbsorbStep (const void * buf, size_t count, void * state)
Выполняется загрузка в автомат state фрагмента [count]buf.
- Ожидается
bashPrgAbsorbStart() < bashPrgAbsorbStep()*.
- Аргументы
buf данные
count число октетов данных
state [in,out] автомат
void bashPrgDecr (void * buf, size_t count, void * state)
С помощью автомата state расшифровываются данные [count]buf.
Предусловие
Автомат находится в ключевом режиме.
- Ожидается
bashPrgStart() < bashPrgDecr()*.
- Аргументы
buf [in,out] данные
count число октетов данных
state [in,out] автомат
void bashPrgDecrStart (void * state)
Инициализируется расшифрование данных с помощью автомата state.
Предусловие
Автомат находится в ключевом режиме.
- Ожидается
bashPrgStart() < bashPrgDecrStart().
Прим.
В начале расшифрования завершается предыдущая команда.
- Аргументы
state [in,out] автомат
void bashPrgDecrStep (void * buf, size_t count, void * state)
Выполняется расшифрование с помощью автомата state фрагмента [count]buf.
- Ожидается
bashPrgDecrStart() < bashPrgDecrStep()*.
- Аргументы
buf [in,out] данные
count число октетов данных
state [in,out] автомат
void bashPrgEncr (void * buf, size_t count, void * state)
С помощью автомата state зашифровываются данные [count]buf.
Предусловие
Автомат находится в ключевом режиме.
- Ожидается
bashPrgStart() < bashPrgEncr()*.
- Аргументы
buf [in,out] данные
count число октетов данных
state [in,out] автомат
void bashPrgEncrStart (void * state)
Инициализируется зашифрование с помощью автомата state.
- Ожидается
bashPrgStart() < bashPrgEncrStart().
Предусловие
Автомат находится в ключевом режиме.
Прим.
В начале зашифрования завершается предыдущая команда.
- Аргументы
state [in,out] автомат
void bashPrgEncrStep (void * buf, size_t count, void * state)
Выполняется зашифрование с помощью автомата state фрагмента [count]buf.
- Ожидается
bashPrgEncrStart() < bashPrgEncrStep()*.
- Аргументы
buf [in,out] данные
count число октетов данных
state [inout] автомат
void bashPrgRatchet (void * state)
Автомат state меняется так, что по новому состоянию трудно определить предыдущее.
- Ожидается
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,
- Ожидается
bashPrgStart() < bashPrgRestart()*.
Прим.
Если key_len != 0, то автомат переводится в ключевой режим.
- Аргументы
ann анонс
ann_len длина анонса в октетах
key ключ
key_len длина ключа в октетах
state автомат
void bashPrgSqueeze (void * buf, size_t count, void * state)
Из автомата state выгружаются данные [count]buf.
- Ожидается
bashPrgStart() < bashPrgSqueeze()*.
- Аргументы
buf данные
count число октетов данных
state [in,out] автомат
void bashPrgSqueezeStart (void * state)
Инициализируется выгрузка данных из автомата state.
- Ожидается
bashPrgStart() < bashPrgSqueezeStart().
Прим.
В начале выгрузки завершается предыдущая команда.
- Аргументы
state [in,out] автомат
void bashPrgSqueezeStep (void * buf, size_t count, void * state)
Выполняется выгрузка из автомата state фрагмента [count]buf.
- Ожидается
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 из исходного текста.