brng.h - Man Page
Алгоритмы СТБ 34.101.47 (brng)
Synopsis
#include 'bee2/defs.h'
Функции
size_t brngCTR_keep ()
Длина состояния функций CTR.
void brngCTRStart (void *state, const octet key[32], const octet iv[32])
Инициализация режима CTR.
void brngCTRStepR (void *buf, size_t count, void *state)
Генерация фрагмента в режиме CTR.
void brngCTRStepG (octet iv[32], void *state)
Получение синхропосылки режима CTR.
err_t brngCTRRand (void *buf, size_t count, const octet key[32], octet iv[32])
Генерация в режиме CTR.
size_t brngHMAC_keep ()
Длина состояния функций HMAC.
void brngHMACStart (void *state, const octet key[], size_t key_len, const octet iv[], size_t iv_len)
Инициализация режима HMAC.
void brngHMACStepR (void *buf, size_t count, void *state)
Генерация в режиме HMAC.
err_t brngHMACRand (void *buf, size_t count, const octet key[], size_t key_len, const octet iv[], size_t iv_len)
Генерация в режиме HMAC.
Подробное описание
Реализованы алгоритмы генерации псевдослучайных чисел, определенные в СТБ 34.101.47 (brng). При ссылках на алгоритмы, таблицы, другие объекты подразумеваются разделы СТБ 34.101.47-2012, в которых эти объекты определены.
Во всех случаях в качестве вспомогательного алгоритма хэширования используется belt-hash (см. СТБ 345.101.31).
В СТБ 34.101.47 определен вспомогательный алгоритм ключезависимого хэширования HMAC. Реализация этого алгоритма на основе belt-hash определена в belt.h.
Основные алгоритмы объединяются в группы, которые определяют следующие криптографические механизмы:
- CTR --- генерация в режиме счетчика;
- HMAC --- генерация в режиме HMAC.
В механизме CTR используется ключ из 32 октетов. В механизме HMAC используется ключ произвольной длины. Рекомендуется использовать ключ из 32 октетов.
Каждый механизм реализуется связкой из двух функций. Эти функции используют общее состояние, указатель на которое передается в функции как дополнительный параметр. Имеются функция определения объема памяти для состояния (_keep). Память для состояния готовит вызывающая программа и она же отвечает за очистку памяти.
Состояние можно копировать как фрагмент памяти.
В связке обязательно имеется функция инициализации алгоритма (Start) и одна или несколько функций генерации и получения служебных данных (StepX).
Логика суффиксов функций StepX:
- R -- rand (сгенерировать);
- G -- get (получить синхропосылку).
Функция типа StepR соответствует интерфейсу gen_i (см. defs.h).
Функции связки спроектированы как максимально простые и эффективные. В частности, в этих функциях не проверяются входные данные.
Каждая связка покрывается высокоуровневой функцией, которая обрабатывает все данные целиком. В высокоуровневых функциях есть проверка входных данных.
Ожидается
Общее состояние связки функций не изменяется вне этих функций.
Ожидается [ERR_BAD_INPUT]
Все входные указатели действительны.
Предусловие
Если не оговорено противное, то входные буферы функций связки не пересекаются.
Функции
size_t brngCTR_keep ()
Возвращается длина состояния (в октетах) функций генерации в режиме CTR.
Возвращает
Длина состояния.
err_t brngCTRRand (void * buf, size_t count, const octet key[32], octet iv[32])
В буфер [count]buf записываются псевдослучайные данные, сгенерированные в режиме CTR на ключе key при использовании синхропосылки iv. Дополнительно в iv возвращается обновленная синхропосылка, которую можно использовать при повторном вызове функции с тем же ключом.
- Возвращает
ERR_OK, если данные успешно сгенерированы, и код ошибки в противном случае.
Предупреждения
При многократном вызове функции с одним и тем же ключом должны использоваться различные синхропосылки. При повторе синхропосылок могут быть повторно сгенерированы те же данные.
Прим.
Первоначальное содержимое buf используется для формирования дополнительного слова X алгоритма генерации (см. п. 6.2.2). Слово X разбивается на последовательные блоки из 32 октетов, при необходимости дополняясь нулевыми октетами.
- Аргументы
buf дополн. / псевдослучайные данные
count число октетов buf
key ключ
iv первонач. / обновл. синхропосылка
void brngCTRStart (void * state, const octet key[32], const octet iv[32])
По ключу key и синхропосылке iv в state формируются структуры данных, необходимые для генерации псевдослучайных чисел в режиме CTR.
Предусловие
По адресу state зарезервировано brngCTR_keep() октетов.
Предупреждения
При многократном вызове функции с одним и тем же ключом должны использоваться различные синхропосылки. При повторе синхропосылок могут быть повторно сгенерированы те же данные.
Прим.
Разрешается передавать нулевой указатель iv. В этом случае будет использоваться нулевая синхропосылка.
- Аргументы
state состояние
key ключ
iv синхропосылка
void brngCTRStepG (octet iv[32], void * state)
Возвращается синхропосылка iv, установленная при вызове brngCTRStart() и измененная затем при последовательных вызовах brngCTRStepR().
- Ожидается
(brngCTRStepR()* < brngCTRStepG())*.
Прим.
Если сгенерировано полное число блоков, то полученная синхропосылка будет отличаться от ранее использованных. Поэтому эту синхропосылку можно задавать при повторном вызове функций связки с тем же ключом.
- Аргументы
iv синхропосылка
state состояние
void brngCTRStepR (void * buf, size_t count, void * state)
В буфер [count]buf записываются октеты, полученные в результате псевдослучайной генерации в режиме CTR. При генерации используются структуры данных, развернутые в state.
- Ожидается
brngCTRStart() < brngCTRStepR()*.
Прим.
Данные в режиме CTR генерируются блоками по 32 октета. Реализована буферизация блоков и функцию можно вызвать с произвольным значением count. Если не все данные сгенерированного ранее блока израсходованы, то они будут возвращены в первую очередь.
Первоначальное содержимое buf используется для формирования дополнительного слова X алгоритма генерации (см. п. 6.2.2). Слово X разбивается на последовательные блоки из 32 октетов, при необходимости дополняясь нулевыми октетами.
Если работает буферизация и возвращаются данные сгенерированного ранее блока, то соответствующие октеты buf не используются для формирования слова X, эти октеты пропускаются. Поэтому, в частности, строки
brngCTRStepR(buf + 16, 16, state), brngCTRStepR(buf + 16, 16, state); brngCTRStepR(buf, 32, state);
вызываемые сразу после brngCTRStart(), не эквивалентны друг другу.
- Аргументы
buf дополн. / псевдослучайные данные
count число октетов buf
state состояние
size_t brngHMAC_keep ()
Возвращается длина состояния (в октетах) функций генерации в режиме HMAC.
Возвращает
Длина состояния.
err_t brngHMACRand (void * buf, size_t count, const octet key[], size_t key_len, const octet iv[], size_t iv_len)
В буфер [count]buf записываются псевдослучайные данные, сгенерированные в режиме HMAC на ключе [key_len]key при использовании синхропосылки [iv_len]iv.
Ожидается [ERR_BAD_INPUT]
Буферы buf и iv не пересекаются.
- Возвращает
ERR_OK, если данные успешно сгенерированы, и код ошибки в противном случае.
Предупреждения
При многократном вызове функции с одним и тем же ключом должны использоваться различные синхропосылки. При повторе синхропосылок будут повторно сгенерированы те же данные.
Прим.
Ограничений на iv_len нет (ср. с функцией brngHMACStart()).
Рекомендуется использовать ключ из 32 октетов.
- Аргументы
buf выходные данные
count число октетов buf
key ключ
key_len длина ключа в октетах
iv синхропосылка
iv_len длина синхропосылки в октетах
void brngHMACStart (void * state, const octet key[], size_t key_len, const octet iv[], size_t iv_len)
По ключу [key_len]key и синхропосылке [iv_len]iv в state формируются структуры данных, необходимые для генерации псевдослучайных чисел в режиме HMAC.
Предусловие
По адресу state зарезервировано brngHMAC_keep() октетов.
Ожидается
Если длина синхропосылки в октетах (iv_len) больше 64, то буфер iv остается корректным и постоянным вплоть до завершения работы с механизмом.
Предупреждения
При многократном вызове функции с одним и тем же ключом должны использоваться различные синхропосылки. При повторе синхропосылок будут повторно сгенерированы те же данные.
Прим.
Рекомендуется использовать ключ из 32 октетов.
При iv_len <= 64 содержимое [iv_len]iv сохраняется в state.
- Аргументы
state состояние
key ключ
key_len длина ключа в октетах
iv синхропосылка
iv_len длина синхропосылки в октетах
void brngHMACStepR (void * buf, size_t count, void * state)
В буфер [count]buf записываются октеты, полученные в результате псевдослучайной генерации в режиме HMAC. При генерации используются структуры данных, развернутые в state.
- Ожидается
brngHMACStart() < brngHMACStepR()*.
Прим.
Данные в режиме HMAC генерируются блоками по 32 октета. Реализована буферизация блоков и функцию можно вызвать с произвольным значением count. Если не все данные сгенерированного ранее блока израсходованы, то они будут возвращены в первую очередь.
- Аргументы
buf псевдослучайные данные
count размер buf в октетах
state состояние
Автор
Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.