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.
Алгоритмы объединяются в группы, которые определяют следующие криптографические механизмы (режимы):
- HOTP --- пароли на основе событий (RFC 4226);
- TOTP --- пароли на основе времени (RFC 6238);
- OCRA --- пароли на основе запросов (RFC 6287).
Каждый механизм реализуется связкой из нескольких функций. Эти функции используют общее состояние, указатель на которое передается в функции как дополнительный параметр. Имеются функция определения объема памяти для состояния (_keep). Память для состояния готовит вызывающая программа и она же отвечает за очистку памяти. Состояние можно копировать как фрагмент памяти.
В связке обязательно имеется функция инициализации режима (Start) и одна или несколько функций обработки фрагментов данных и получения результатов обработки (StepX).
Логика суффиксов функций StepX:
- S -- set (установить данные сеанса);
- R -- rand (сгенерировать пароль);
- V -- verify (проверить пароль, восстановить синхронизацию);
- G -- get (получить обновленные данные сеанса).
Функции связки спроектированы как максимально простые и эффективные. В частности, в этих функциях не проверяются входные данные.
Каждая связка покрывается высокоуровневой функцией, которая обрабатывает все данные целиком. В высокоуровневых функциях есть проверка входных данных.
В функции botpDT() реализован вспомогательный алгоритм 'динамической обрезки' (dynamic truncation). Функцию можно использовать с произвольными имитовставками (а не только с имитовставками hmac-hbelt).
В режимах HOTP и OCRA используется счетчик -- строка из 8 октетов. Эта строка интерпретируются как число по правилам big-endian ('от старших к младшим'), принятым в RFC 4226. Пароли генерируются на последовательных \mod 2^64 значениях счетчика. Инкремент счетчика реализован в функции botpCtrNext().
Ожидается
Общее состояние связки функций не изменяется вне этих функций.
Ожидается [ERR_BAD_INPUT]
Все входные указатели высокоуровневых функций действительны.
Предусловие
Все входные указатели низкоуровневых функций действительны. Размер буфера строки на 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 используются следующие параметры:
- q -- запрос (клиента, сервера или составной);
- ctr -- счетчик;
- p -- хэш-значение статического пароля клиента и сервера;
- t -- округленная отметка времени;
- s -- идентификатор сеанса между клиентом и сервером.
Параметры 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]
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.
- Ожидается
botpHOTPStepS() < botpHOTPStepG().
- Аргументы
ctr счетчик
state состояние
void botpHOTPStepR (char * otp, void * state)
По числу digit, ключу и счетчику, размещенным в state, генерируется одноразовый пароль из digit десятичных символов. После генерации пароля счетчик инкрементируется.
- Ожидается
botpHOTPStepS() < botpHOTPStepR()*.
- Аргументы
otp одноразовый пароль
state состояние
void botpHOTPStepS (void * state, const octet ctr[8])
В state устанавливается счетчик ctr.
- Ожидается
botpHOTPStart() < botpHOTPStepS().
- Аргументы
state состояние
ctr счетчик
bool_t botpHOTPStepV (const char * otp, void * state)
По числу digit, ключу и счетчику, размещенным в state, строится одноразовый пароль из digit десятичных цифр. Построенный пароль сравнивается с otp. Если пароли совпадают, то счетчик инкрементируется.
- Ожидается
botpHOTPStepS() < botpHOTPStepV()*.
Возвращает
Признак совпадения паролей.
Прим.
Функция регулярна: полностью проверяется даже заведомо неверный пароль.
- Аргументы
otp контрольный пароль
state состояние
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]
6 <= digit && digit <= 8.
Ожидается [ERR_BAD_PWD]
Пароль 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]
Формат suite корректен.
Ожидается [ERR_BAD_PARAMS]
4 <= q_len && q_len < = 2 * q_max, где q_max -- максимальная длина одиночного запроса, указанная в suite.
Ожидается [ERR_BAD_TIME]
Если suite задает использование t, то t != TIME_ERR.
Ожидается
Формат 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.
- Ожидается
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.
Ожидается
Формат q соответствует типу, указанному в suite.
- Ожидается
botpOCRAStart() < [botpOCRAStepS()] < botpOCRAStepR()*.
- Аргументы
otp одноразовый пароль
q запрос
q_len длина запроса в октетах
t округленная отметка времени
state состояние
void botpOCRAStepS (void * state, const octet ctr[8], const octet p[], const octet s[])
В state устанавливаются счетчик ctr, хэш-значение p статического пароля, идентификатор сеанса s.
- Ожидается
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.
Ожидается
Формат q соответствует типу, указанному в suite.
- Ожидается
botpOCRAStart() < [botpOCRAStepS()] < botpOCRAStepV()*.
- Возвращает
TRUE, если пароль подошел, и FALSE в противном случае.
- Аргументы
otp контрольный пароль
q запрос
q_len длина запроса в октетах
t округленная отметка времени
state состояние
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]
Формат suite корректен.
Ожидается [ERR_BAD_PARAMS]
4 <= q_len && q_len < = 2 * q_max, где q_max -- максимальная длина одиночного запроса, указанная в suite.
Ожидается [ERR_BAD_TIME]
Если suite задает использование t, то t != TIME_ERR.
Ожидается [ERR_BAD_PWD]
Пароль otp подошел.
Ожидается
Формат 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]
6 <= digit && digit <= 8.
- Ожидается [ERR_BAD_TIME]
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.
- Ожидается
botpTOTPStart() < botpTOTPStepR()*.
- Аргументы
otp одноразовый пароль
t округленная отметка времени
state состояние
bool_t botpTOTPStepV (const char * otp, tm_time_t t, void * state)
По округленной отметке t текущего времени, по числу digit и ключу, размещенным в state, строится одноразовый пароль из digit символов. Полученный пароль сравнивается с otp.
- Предусловие
t != TIME_ERR.
- Ожидается
botpTOTPStart() < botpTOTPStepV()*.
- Возвращает
TRUE, если пароль подошел, и FALSE в противном случае.
- Аргументы
otp контрольный пароль
t округленная отметка времени
state состояние
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]
6 <= digit && digit <= 8.
Ожидается [ERR_BAD_TIME]
t != TIME_ERR.
Ожидается [ERR_BAD_PWD]
Пароль otp подошел.
- Возвращает
ERR_OK в случае успеха или код ошибки.
- Аргументы
otp контрольный пароль
key ключ
key_len длина ключа в октетах
t округленная отметка времени
Автор
Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.