botp.h - Man Page

Алгоритмы управления одноразовыми паролями

Synopsis

#include 'bee2/defs.h'
#include 'bee2/core/tm.h'

Функции

void botpDT (char *otp, size_t digit, const octet mac[], size_t mac_len)
Построение пароля по имитовставке
void botpCtrNext (octet ctr[8])
Следующий счетчик
size_t botpHOTP_keep ()
Длина состояния функций HOTP.
void botpHOTPStart (void *state, size_t digit, const octet key[], size_t key_len)
Инициализация режима HOTP.
void botpHOTPStepS (void *state, const octet ctr[8])
Установка счетчика режима HOTP.
void botpHOTPStepR (char *otp, void *state)
Генерация очередного пароля в режиме HOTP.
bool_t botpHOTPStepV (const char *otp, void *state)
Проверка очередного пароля в режиме HOTP.
void botpHOTPStepG (octet ctr[8], const void *state)
Возврат счетчика
err_t botpHOTPRand (char *otp, size_t digit, const octet key[], size_t key_len, const octet ctr[8])
Генерация пароля в режиме HOTP.
err_t botpHOTPVerify (const char *otp, const octet key[], size_t key_len, const octet ctr[8])
Проверка пароля в режиме HOTP.
size_t botpTOTP_keep ()
Длина состояния функций TOTP.
void botpTOTPStart (void *state, size_t digit, const octet key[], size_t key_len)
Инициализация режима TOTP.
void botpTOTPStepR (char *otp, tm_time_t t, void *state)
Генерация очередного пароля в режиме TOTP.
bool_t botpTOTPStepV (const char *otp, tm_time_t t, void *state)
Проверка очередного пароля в режиме TOTP.
err_t botpTOTPRand (char *otp, size_t digit, const octet key[], size_t key_len, tm_time_t t)
Генерация пароля в режиме TOTP.
err_t botpTOTPVerify (const char *otp, const octet key[], size_t key_len, tm_time_t t)
Проверка пароля в режиме TOTP.
size_t botpOCRA_keep ()
Длина состояния функций OCRA.
bool_t botpOCRAStart (void *state, const char *suite, const octet key[], size_t key_len)
Инициализация режима OCRA.
void botpOCRAStepS (void *state, const octet ctr[8], const octet p[], const octet s[])
Установка данных сеанса режима OCRA.
void botpOCRAStepR (char *otp, const octet q[], size_t q_len, tm_time_t t, void *state)
Генерация очередного пароля в режиме OCRA.
bool_t botpOCRAStepV (const char *otp, const octet q[], size_t q_len, tm_time_t t, void *state)
Проверка очередного пароля в режиме OCRA.
void botpOCRAStepG (octet ctr[8], const void *state)
Возврат счетчика
err_t botpOCRARand (char *otp, const char *suite, const octet key[], size_t key_len, const octet q[], size_t q_len, const octet ctr[8], const octet p[], const octet s[], tm_time_t t)
Генерация пароля в режиме OCRA.
err_t botpOCRAVerify (const char *otp, const char *suite, const octet key[], size_t key_len, const octet q[], size_t q_len, const octet ctr[8], const octet p[], const octet s[], tm_time_t t)
Проверка пароля в режиме TOTP.

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

Общие положения

Реализованы алгоритмы управления одноразовыми паролями. Алгоритмы соответствуют стандартам RFC 4226, RFC 6238, RFC 6287 и базируются на механизме имитозащиты HMAC[belt-hash], определенному в СТБ 34.101.47 и реализованному в модуле belt.

Пароль представляет собой строку из digit символов алфавита {'0' - '9'}, 4 <= digit <= 9.

Алгоритмы объединяются в группы, которые определяют следующие криптографические механизмы (режимы):

Каждый механизм реализуется связкой из нескольких функций. Эти функции используют общее состояние, указатель на которое передается в функции как дополнительный параметр. Имеются функция определения объема памяти для состояния (_keep). Память для состояния готовит вызывающая программа и она же отвечает за очистку памяти. Состояние можно копировать как фрагмент памяти.

В связке обязательно имеется функция инициализации режима (Start) и одна или несколько функций обработки фрагментов данных и получения результатов обработки (StepX).

Логика суффиксов функций StepX:

Функции связки спроектированы как максимально простые и эффективные. В частности, в этих функциях не проверяются входные данные.

Каждая связка покрывается высокоуровневой функцией, которая обрабатывает все данные целиком. В высокоуровневых функциях есть проверка входных данных.

В функции botpDT() реализован вспомогательный алгоритм 'динамической обрезки' (dynamic truncation). Функцию можно использовать с произвольными имитовставками (а не только с имитовставками hmac-hbelt).

В режимах HOTP и OCRA используется счетчик -- строка из 8 октетов. Эта строка интерпретируются как число по правилам big-endian ('от старших к младшим'), принятым в RFC 4226. Пароли генерируются на последовательных \mod 2^64 значениях счетчика. Инкремент счетчика реализован в функции botpCtrNext().

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

Ожидается [ERR_BAD_INPUT]:\n Все входные указатели высокоуровневых функций

действительны.

Предусловие

Все входные указатели низкоуровневых функций действительны. Размер буфера строки на 1 октет больше длины строки (с учетом завершающего нулевого октета).

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

Режим HOTP

При выработке, а также при успешной проверке пароля в функциях botpHOTPStepR(), botpHOTPStepV() счетчик, размещенный в состоянии, инкрементируется. Обновленный счетчик можно использовать для генерации или проверки нового пароля. Выгрузить счетчик из состояния можно с помощью функции botpHOTPStepG().

Режим TOTP

Текущее время --- это, так называемое, UNIX-время --- число секунд, прошедших с момента 1970-01-01T00:00:00Z. Текущее время t округляется. Округление выполняется с параметрами t0 -- базовая отметка времени и ts -- шаг времени. Округление состоит в замене t на (t - t0) / ts. Если t < t0, то округление завершится с ошибкой. Округление можно выполнить с помощью функции tmTimeRound(). Эта функция возвращает TIME_ERR при ошибках получения отметки текущего времени или ее округления.

При округлении рекомендуется использовать t0 = 0 и ts = 30 или 60.

Отметка времени представляется типом tm_time_t. Отметка преобразуется в счетчик режима HOTP, т.е. в 64-разрядное беззнаковое число.

Режим OCRA

В режиме OCRA используются следующие параметры:

Параметры ctr, p, s описывают сеанс между клиентом и сервером. Параметры ctr, p, t, s являются необязательными.

Необходимость использования того или иного параметра, а также формат параметра, его длина, параметры округления времени определяются строковым описателем suite.

Запрос q может быть 3 типов: A (буквенно-цифровой), N (цифровой) и H (шестнадцатеричный). Формат запроса в функциях OCRA не проверяется. Для предварительной проверки запроса можно использовать функции strIsAlphanumeric(), decIsValid(), hexIsValid().

Запрос q может быть одиночным или двойным. Если q -- одиночный, то его длина лежит в пределах от 4 до q_max, где q_max -- максимальная длина, указанная в suite. Если q -- двойной, то его длина лежит в пределах от 8 до 2 * q_max. За подготовку составного запроса отвечает вызывающая программа.

Функции

void botpCtrNext (octet ctr[8])

Счетчик ctr режимов HOTP и OCRA инкрементируется \mod 2^64.

void botpDT (char * otp, size_t digit, const octet mac[], size_t mac_len)

По имитовставке [mac_len]mac строится одноразовый пароль otp из digit десятичных цифр.

Предусловие

4 <= digit && digit <= 10.

mac_len >= 20.

size_t botpHOTP_keep ()

Возвращается длина состояния (в октетах) функций механизма HOTP.

Возвращает

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

err_t botpHOTPRand (char * otp, size_t digit, const octet key[], size_t key_len, const octet ctr[8])

По ключу [key_len]key и счетчику ctr генерируется одноразовый пароль otp из digit десятичных символов.

Ожидается [ERR_BAD_PARAMS]:\n 6 <= digit && digit <= 8.

Возвращает

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

Аргументы

otp одноразовый пароль
digit длина пароля
key ключ
key_len длина ключа в октетах
ctr счетчик

void botpHOTPStart (void * state, size_t digit, const octet key[], size_t key_len)

По числу digit ключу [key_len]key в state формируются структуры данных, необходимые для управления паролями длины digit в режиме HOTP.

Предусловие

6 <= digit && digit <= 8.

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

Прим.

Рекомендуется использовать ключ из 32 октетов.

Аргументы

state состояние
digit число цифр в пароле
key ключ
key_len длина ключа в октетах

void botpHOTPStepG (octet ctr[8], const void * state)

В ctr возвращается текущий счетчик, размещенный в state.

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

Аргументы

ctr счетчик
state состояние

void botpHOTPStepR (char * otp, void * state)

По числу digit, ключу и счетчику, размещенным в state, генерируется одноразовый пароль из digit десятичных символов. После генерации пароля счетчик инкрементируется.

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

Аргументы

otp одноразовый пароль
state [in/out] состояние

void botpHOTPStepS (void * state, const octet ctr[8])

В state устанавливается счетчик ctr.

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

Аргументы

state состояние
ctr счетчик

bool_t botpHOTPStepV (const char * otp, void * state)

По числу digit, ключу и счетчику, размещенным в state, строится одноразовый пароль из digit десятичных цифр. Построенный пароль сравнивается с otp. Если пароли совпадают, то счетчик инкрементируется.

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

Возвращает

Признак совпадения паролей.

Прим.

Функция регулярна: полностью проверяется даже заведомо неверный пароль.

Аргументы

otp контрольный пароль
state [in/out] состояние

err_t botpHOTPVerify (const char * otp, const octet key[], size_t key_len, const octet ctr[8])

По ключу [key_len]key и счетчику ctr строится одноразовый пароль из digit = strLen(otp) символов. Построенный пароль сравнивается с otp.

Ожидается [ERR_BAD_PWD]:\n 6 <= digit && digit <= 8.

Ожидается [ERR_BAD_PWD]:\n Пароль otp совпадает с построенным.

Возвращает

ERR_OK в случае успеха или код ошибки.

Аргументы

otp контрольный пароль
key ключ
key_len длина ключа в октетах
ctr счетчик

size_t botpOCRA_keep ()

Возвращается длина состояния (в октетах) функций механизма OCRA.

Возвращает

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

err_t botpOCRARand (char * otp, const char * suite, const octet key[], size_t key_len, const octet q[], size_t q_len, const octet ctr[8], const octet p[], const octet s[], tm_time_t t)

По описателю suite, ключу [key_len]key, запросу q, счетчику ctr, хэш-значению p статического пароля, идентификатору сеанса s и округленной отметке t текущего времени генерируется одноразовый пароль otp.

Ожидается [ERR_BAD_FORMAT]:\n Формат suite корректен.

Ожидается [ERR_BAD_PARAMS]:\n 4 <= q_len && q_len < = 2 * q_max,

где q_max -- максимальная длина одиночного запроса, указанная в suite.

Ожидается [ERR_BAD_TIME]:\n Если suite задает использование t, то t != TIME_ERR.

Ожидается:\n Формат q соответствует типу, указанному в suite.

Возвращает

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

Аргументы

otp одноразовый пароль
suite описатель
key ключ
key_len длина ключа в октетах
q запрос
q_len длина запроса в октетах
ctr счетчик
p хэш-значение статического пароля
s идентификатор сеанса
t округленная отметка времени

bool_t botpOCRAStart (void * state, const char * suite, const octet key[], size_t key_len)

По описателю suite и ключу [key_len]key в state формируются структуры данных, необходимые для управления паролями в режиме OCRA.

Предусловие

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

Возвращает

TRUE, если описатель корректен, и FALSE в противном случае.

Прим.

Рекомендуется использовать ключ из 32 октетов.

Аргументы

state состояние
suite описатель
key ключ
key_len длина ключа в октетах

void botpOCRAStepG (octet ctr[8], const void * state)

В ctr возвращается текущий счетчик, размещенный в state.

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

Аргументы

ctr счетчик
state состояние

void botpOCRAStepR (char * otp, const octet q[], size_t q_len, tm_time_t t, void * state)

По запросу [q_len]q и округленной отметке t текущего времени, по описателю suite, ключу и данным сеанса, размещенным в state, генерируется одноразовый пароль otp. Длина otp определяется описателем suite. Если suite задает использование счетчика, то после генерации пароля он инкрементируется.

Предусловие

4 <= q_len && q_len < = 2 * q_max, где q_max -- максимальная длина одиночного запроса, указанная в suite.

Если suite задает использование t, то t != TIME_ERR.

Ожидается:\n Формат q соответствует типу, указанному в suite.

Ожидается:\n botpOCRAStart() < [botpOCRAStepS()] < botpOCRAStepR()*.

Аргументы

otp одноразовый пароль
q запрос
q_len длина запроса в октетах
t округленная отметка времени
state [in/out] состояние

void botpOCRAStepS (void * state, const octet ctr[8], const octet p[], const octet s[])

В state устанавливаются счетчик ctr, хэш-значение p статического пароля, идентификатор сеанса s.

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

Прим.

Каждый из параметров ctr, p, s является необязательным. Указатель на необязательный параметр не контролируется.

Функцию можно не вызывать, если все параметры необязательны.

Аргументы

state состояние
ctr счетчик
p хэш-значение статического пароля
s идентификатор сеанса

bool_t botpOCRAStepV (const char * otp, const octet q[], size_t q_len, tm_time_t t, void * state)

По запросу [q_len]q и округленной отметке t текущего времени, по описателю suite, ключу и данным сеанса, размещенным в state, строится одноразовый пароль. Длина пароля определяется описателем suite. Построенный пароль сравнивается c otp. Если suite задает использование счетчика, то после успешной проверки пароля он инкрементируется.

Предусловие

4 <= q_len && q_len < = 2 * q_max, где q_max -- максимальная длина одиночного запроса, указанная в suite.

Если suite задает использование t, то t != TIME_ERR.

Ожидается:\n Формат q соответствует типу, указанному в suite.

Ожидается:\n botpOCRAStart() < [botpOCRAStepS()] < botpOCRAStepV()*.

Возвращает

TRUE, если пароль подошел, и FALSE в противном случае.

Аргументы

otp контрольный пароль
q запрос
q_len длина запроса в октетах
t округленная отметка времени
state [in/out] состояние

err_t botpOCRAVerify (const char * otp, const char * suite, const octet key[], size_t key_len, const octet q[], size_t q_len, const octet ctr[8], const octet p[], const octet s[], tm_time_t t)

По описателю suite, ключу [key_len]key, запросам [q_len]q, счетчику ctr, хэш-значению p статического пароля, идентификатору сеанса s и округленной отметке t текущего времени строится одноразовый пароль. Построенный пароль сравнивается с otp.

Ожидается [ERR_BAD_FORMAT]:\n Формат suite корректен.

Ожидается [ERR_BAD_PARAMS]:\n 4 <= q_len && q_len < = 2 * q_max,

где q_max -- максимальная длина одиночного запроса, указанная в suite.

Ожидается [ERR_BAD_TIME]:\n Если suite задает использование t, то t != TIME_ERR.

Ожидается [ERR_BAD_PWD]:\n Пароль otp подошел.

Ожидается:\n Формат q соответствует типу, указанному в suite.

Возвращает

ERR_OK в случае успеха или код ошибки.

Аргументы

otp контрольный пароль
suite описатель
key ключ
key_len длина ключа в октетах
q запрос
q_len длина запроса в октетах
ctr счетчик
p хэш-значение статического пароля
s идентификатор сеанса
t округленная отметка времени

size_t botpTOTP_keep ()

Возвращается длина состояния (в октетах) функций механизма TOTP.

Возвращает

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

err_t botpTOTPRand (char * otp, size_t digit, const octet key[], size_t key_len, tm_time_t t)

По числу digit, ключу [key_len]key и округленной отметке t текущего времени генерируется одноразовый пароль otp из digit цифр.

Ожидается [ERR_BAD_PARAMS]:\n 6 <= digit && digit <= 8.

Ожидается [ERR_BAD_TIME]:\n t != TIME_ERR.

Возвращает

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

Аргументы

otp одноразовый пароль
digit длина пароля
key ключ
key_len длина ключа в октетах
t округленная отметка времени

void botpTOTPStart (void * state, size_t digit, const octet key[], size_t key_len)

По числу digit и ключу [key_len]key в state формируются структуры данных, необходимые для управления паролями длины digit в режиме TOTP.

Предусловие

6 <= digit && digit <= 8.

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

Прим.

Рекомендуется использовать ключ из 32 октетов.

Аргументы

state состояние
digit число цифр в пароле
key ключ
key_len длина ключа в октетах

void botpTOTPStepR (char * otp, tm_time_t t, void * state)

По округленной отметке t текущего времени, по числу digit и ключу, размещенным в state, генерируется одноразовый пароль otp из digit десятичных символов.

Предусловие

t != TIME_ERR.

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

Аргументы

otp одноразовый пароль
t округленная отметка времени
state [in/out] состояние

bool_t botpTOTPStepV (const char * otp, tm_time_t t, void * state)

По округленной отметке t текущего времени, по числу digit и ключу, размещенным в state, строится одноразовый пароль из digit символов. Полученный пароль сравнивается с otp.

Предусловие

t != TIME_ERR.

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

Возвращает

TRUE, если пароль подошел, и FALSE в противном случае.

Аргументы

otp контрольный пароль
t округленная отметка времени
state [in/out] состояние

err_t botpTOTPVerify (const char * otp, const octet key[], size_t key_len, tm_time_t t)

По ключу [key_len]key и округленной отметке t текущего времени строится одноразовый пароль из strLen(otp) символов. Построенный пароль сравнивается с otp.

Ожидается [ERR_BAD_PWD]:\n 6 <= digit && digit <= 8.

Ожидается [ERR_BAD_TIME]:\n t != TIME_ERR.

Ожидается [ERR_BAD_PWD]:\n Пароль otp подошел.

Возвращает

ERR_OK в случае успеха или код ошибки.

Аргументы

otp контрольный пароль
key ключ
key_len длина ключа в октетах
t округленная отметка времени

Автор

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

Info

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