1botp.h(3) Library Functions Manual botp.h(3)
2
6 botp.h - Алгоритмы управления одноразовыми паролями
7
10 #include 'bee2/defs.h'
11 #include 'bee2/core/tm.h'
12 Функции
15 void botpDT (char *otp, size_t digit, const octet mac[], size_t
16 mac_len)
17 Построение пароля по имитовставке
18 void botpCtrNext (octet ctr[8])
19 Следующий счетчик
20 size_t botpHOTP_keep ()
21 Длина состояния функций HOTP.
22 void botpHOTPStart (void *state, size_t digit, const octet key[],
23 size_t key_len)
24 Инициализация режима HOTP.
25 void botpHOTPStepS (void *state, const octet ctr[8])
26 Установка счетчика режима HOTP.
27 void botpHOTPStepR (char *otp, void *state)
28 Генерация очередного пароля в режиме HOTP.
29 bool_t botpHOTPStepV (const char *otp, void *state)
30 Проверка очередного пароля в режиме HOTP.
31 void botpHOTPStepG (octet ctr[8], const void *state)
32 Возврат счетчика
33 err_t botpHOTPRand (char *otp, size_t digit, const octet key[], size_t
34 key_len, const octet ctr[8])
35 Генерация пароля в режиме HOTP.
36 err_t botpHOTPVerify (const char *otp, const octet key[], size_t
37 key_len, const octet ctr[8])
38 Проверка пароля в режиме HOTP.
39 size_t botpTOTP_keep ()
40 Длина состояния функций TOTP.
41 void botpTOTPStart (void *state, size_t digit, const octet key[],
42 size_t key_len)
43 Инициализация режима TOTP.
44 void botpTOTPStepR (char *otp, tm_time_t t, void *state)
45 Генерация очередного пароля в режиме TOTP.
46 bool_t botpTOTPStepV (const char *otp, tm_time_t t, void *state)
47 Проверка очередного пароля в режиме TOTP.
48 err_t botpTOTPRand (char *otp, size_t digit, const octet key[], size_t
49 key_len, tm_time_t t)
50 Генерация пароля в режиме TOTP.
51 err_t botpTOTPVerify (const char *otp, const octet key[], size_t
52 key_len, tm_time_t t)
53 Проверка пароля в режиме TOTP.
54 size_t botpOCRA_keep ()
55 Длина состояния функций OCRA.
56 bool_t botpOCRAStart (void *state, const char *suite, const octet
57 key[], size_t key_len)
58 Инициализация режима OCRA.
59 void botpOCRAStepS (void *state, const octet ctr[8], const octet p[],
60 const octet s[])
61 Установка данных сеанса режима OCRA.
62 void botpOCRAStepR (char *otp, const octet q[], size_t q_len, tm_time_t
63 t, void *state)
64 Генерация очередного пароля в режиме OCRA.
65 bool_t botpOCRAStepV (const char *otp, const octet q[], size_t q_len,
66 tm_time_t t, void *state)
67 Проверка очередного пароля в режиме OCRA.
68 void botpOCRAStepG (octet ctr[8], const void *state)
69 Возврат счетчика
70 err_t botpOCRARand (char *otp, const char *suite, const octet key[],
71 size_t key_len, const octet q[], size_t q_len, const octet ctr[8],
72 const octet p[], const octet s[], tm_time_t t)
73 Генерация пароля в режиме OCRA.
74 err_t botpOCRAVerify (const char *otp, const char *suite, const octet
75 key[], size_t key_len, const octet q[], size_t q_len, const octet
76 ctr[8], const octet p[], const octet s[], tm_time_t t)
77 Проверка пароля в режиме TOTP.
78
81 Реализованы алгоритмы управления одноразовыми паролями. Алгоритмы
82 соответствуют стандартам RFC 4226, RFC 6238, RFC 6287 и базируются на
83 механизме имитозащиты HMAC[belt-hash], определенному в СТБ 34.101.47 и
84 реализованному в модуле belt.
85 Пароль представляет собой строку из digit символов алфавита {'0' -
87 '9'}, 4 <= digit <= 9.
88 Алгоритмы объединяются в группы, которые определяют следующие
90 криптографические механизмы (режимы):
91 • HOTP --- пароли на основе событий (RFC 4226);
93 • TOTP --- пароли на основе времени (RFC 6238);
95 • OCRA --- пароли на основе запросов (RFC 6287).
97 Каждый механизм реализуется связкой из нескольких функций. Эти функции
99 используют общее состояние, указатель на которое передается в функции
100 как дополнительный параметр. Имеются функция определения объема памяти
101 для состояния (_keep). Память для состояния готовит вызывающая
102 программа и она же отвечает за очистку памяти. Состояние можно
103 копировать как фрагмент памяти.
104 В связке обязательно имеется функция инициализации режима (Start) и
106 одна или несколько функций обработки фрагментов данных и получения
107 результатов обработки (StepX).
108 Логика суффиксов функций StepX:
110 • S -- set (установить данные сеанса);
112 • R -- rand (сгенерировать пароль);
114 • V -- verify (проверить пароль, восстановить синхронизацию);
116 • G -- get (получить обновленные данные сеанса).
118 Функции связки спроектированы как максимально простые и эффективные. В
120 частности, в этих функциях не проверяются входные данные.
121 Каждая связка покрывается высокоуровневой функцией, которая
123 обрабатывает все данные целиком. В высокоуровневых функциях есть
124 проверка входных данных.
125 В функции botpDT() реализован вспомогательный алгоритм 'динамической
127 обрезки' (dynamic truncation). Функцию можно использовать с
128 произвольными имитовставками (а не только с имитовставками hmac-hbelt).
129 В режимах HOTP и OCRA используется счетчик -- строка из 8 октетов. Эта
131 строка интерпретируются как число по правилам big-endian ('от старших к
132 младшим'), принятым в RFC 4226. Пароли генерируются на последовательных
133 \mod 2^64 значениях счетчика. Инкремент счетчика реализован в функции
134 botpCtrNext().
135 Ожидается
137 Общее состояние связки функций не изменяется вне этих функций.
138 Ожидается [ERR_BAD_INPUT]
140 Все входные указатели высокоуровневых функций действительны.
141 Предусловие
143 Все входные указатели низкоуровневых функций действительны. Размер
144 буфера строки на 1 октет больше длины строки (с учетом завершающего
145 нулевого октета).
146 Если не оговорено противное, то входные буферы функций связки не
148 пересекаются.
149
151 При выработке, а также при успешной проверке пароля в функциях
152 botpHOTPStepR(), botpHOTPStepV() счетчик, размещенный в состоянии,
153 инкрементируется. Обновленный счетчик можно использовать для генерации
154 или проверки нового пароля. Выгрузить счетчик из состояния можно с
155 помощью функции botpHOTPStepG().
156
158 Текущее время --- это, так называемое, UNIX-время --- число секунд,
159 прошедших с момента 1970-01-01T00:00:00Z. Текущее время t округляется.
160 Округление выполняется с параметрами t0 -- базовая отметка времени и ts
161 -- шаг времени. Округление состоит в замене t на (t - t0) / ts. Если t
162 < t0, то округление завершится с ошибкой. Округление можно выполнить с
163 помощью функции tmTimeRound(). Эта функция возвращает TIME_ERR при
164 ошибках получения отметки текущего времени или ее округления.
165 При округлении рекомендуется использовать t0 = 0 и ts = 30 или 60.
167 Отметка времени представляется типом tm_time_t. Отметка преобразуется в
169 счетчик режима HOTP, т.е. в 64-разрядное беззнаковое число.
170
172 В режиме OCRA используются следующие параметры:
173 • q -- запрос (клиента, сервера или составной);
175 • ctr -- счетчик;
177 • p -- хэш-значение статического пароля клиента и сервера;
179 • t -- округленная отметка времени;
181 • s -- идентификатор сеанса между клиентом и сервером.
183 Параметры ctr, p, s описывают сеанс между клиентом и сервером.
185 Параметры ctr, p, t, s являются необязательными.
186 Необходимость использования того или иного параметра, а также формат
188 параметра, его длина, параметры округления времени определяются
189 строковым описателем suite.
190 Запрос q может быть 3 типов: A (буквенно-цифровой), N (цифровой) и H
192 (шестнадцатеричный). Формат запроса в функциях OCRA не проверяется. Для
193 предварительной проверки запроса можно использовать функции
194 strIsAlphanumeric(), decIsValid(), hexIsValid().
195 Запрос q может быть одиночным или двойным. Если q -- одиночный, то его
197 длина лежит в пределах от 4 до q_max, где q_max -- максимальная длина,
198 указанная в suite. Если q -- двойной, то его длина лежит в пределах от
199 8 до 2 * q_max. За подготовку составного запроса отвечает вызывающая
200 программа.
201
203 void botpCtrNext (octet ctr[8])
204 Счетчик ctr режимов HOTP и OCRA инкрементируется \mod 2^64.
205 void botpDT (char * otp, size_t digit, const octet mac[], size_t mac_len)
207 По имитовставке [mac_len]mac строится одноразовый пароль otp из digit
208 десятичных цифр.
209 Предусловие
211 4 <= digit && digit <= 10.
212 mac_len >= 20.
214 size_t botpHOTP_keep ()
216 Возвращается длина состояния (в октетах) функций механизма HOTP.
217 Возвращает
219 Длина состояния.
220 err_t botpHOTPRand (char * otp, size_t digit, const octet key[], size_t
222 key_len, const octet ctr[8])
223 По ключу [key_len]key и счетчику ctr генерируется одноразовый пароль
224 otp из digit десятичных символов.
225 Ожидается [ERR_BAD_PARAMS]
227 6 <= digit && digit <= 8.
228 Возвращает
230 ERR_OK, если пароль успешно сгенерирован, и код ошибки в противном
231 случае.
232 Аргументы
234 otp одноразовый пароль
235 digit длина пароля
236 key ключ
237 key_len длина ключа в октетах
238 ctr счетчик
239 void botpHOTPStart (void * state, size_t digit, const octet key[], size_t
241 key_len)
242 По числу digit ключу [key_len]key в state формируются структуры данных,
243 необходимые для управления паролями длины digit в режиме HOTP.
244 Предусловие
246 6 <= digit && digit <= 8.
247 По адресу state зарезервировано botpHOTP_keep() октетов.
249 Прим.
251 Рекомендуется использовать ключ из 32 октетов.
252 Аргументы
254 state состояние
255 digit число цифр в пароле
256 key ключ
257 key_len длина ключа в октетах
258 void botpHOTPStepG (octet ctr[8], const void * state)
260 В ctr возвращается текущий счетчик, размещенный в state.
261 Ожидается
263 botpHOTPStepS() < botpHOTPStepG().
264 Аргументы
266 ctr счетчик
267 state состояние
268 void botpHOTPStepR (char * otp, void * state)
270 По числу digit, ключу и счетчику, размещенным в state, генерируется
271 одноразовый пароль из digit десятичных символов. После генерации пароля
272 счетчик инкрементируется.
273 Ожидается
275 botpHOTPStepS() < botpHOTPStepR()*.
276 Аргументы
278 otp одноразовый пароль
279 state состояние
280 void botpHOTPStepS (void * state, const octet ctr[8])
282 В state устанавливается счетчик ctr.
283 Ожидается
285 botpHOTPStart() < botpHOTPStepS().
286 Аргументы
288 state состояние
289 ctr счетчик
290 bool_t botpHOTPStepV (const char * otp, void * state)
292 По числу digit, ключу и счетчику, размещенным в state, строится
293 одноразовый пароль из digit десятичных цифр. Построенный пароль
294 сравнивается с otp. Если пароли совпадают, то счетчик инкрементируется.
295 Ожидается
297 botpHOTPStepS() < botpHOTPStepV()*.
298 Возвращает
300 Признак совпадения паролей.
301 Прим.
303 Функция регулярна: полностью проверяется даже заведомо неверный
304 пароль.
305 Аргументы
307 otp контрольный пароль
308 state состояние
309 err_t botpHOTPVerify (const char * otp, const octet key[], size_t key_len,
311 const octet ctr[8])
312 По ключу [key_len]key и счетчику ctr строится одноразовый пароль из
313 digit = strLen(otp) символов. Построенный пароль сравнивается с otp.
314 Ожидается [ERR_BAD_PWD]
316 6 <= digit && digit <= 8.
317 Ожидается [ERR_BAD_PWD]
319 Пароль otp совпадает с построенным.
320 Возвращает
322 ERR_OK в случае успеха или код ошибки.
323 Аргументы
325 otp контрольный пароль
326 key ключ
327 key_len длина ключа в октетах
328 ctr счетчик
329 size_t botpOCRA_keep ()
331 Возвращается длина состояния (в октетах) функций механизма OCRA.
332 Возвращает
334 Длина состояния.
335 err_t botpOCRARand (char * otp, const char * suite, const octet key[],
337 size_t key_len, const octet q[], size_t q_len, const octet ctr[8],
338 const octet p[], const octet s[], tm_time_t t)
339 По описателю suite, ключу [key_len]key, запросу q, счетчику ctr,
340 хэш-значению p статического пароля, идентификатору сеанса s и
341 округленной отметке t текущего времени генерируется одноразовый пароль
342 otp.
343 Ожидается [ERR_BAD_FORMAT]
345 Формат suite корректен.
346 Ожидается [ERR_BAD_PARAMS]
348 4 <= q_len && q_len < = 2 * q_max, где q_max -- максимальная длина
349 одиночного запроса, указанная в suite.
350 Ожидается [ERR_BAD_TIME]
352 Если suite задает использование t, то t != TIME_ERR.
353 Ожидается
355 Формат q соответствует типу, указанному в suite.
356 Возвращает
358 ERR_OK, если пароль успешно сгенерирован, и код ошибки в противном
359 случае.
360 Аргументы
362 otp одноразовый пароль
363 suite описатель
364 key ключ
365 key_len длина ключа в октетах
366 q запрос
367 q_len длина запроса в октетах
368 ctr счетчик
369 p хэш-значение статического пароля
370 s идентификатор сеанса
371 t округленная отметка времени
372 bool_t botpOCRAStart (void * state, const char * suite, const octet key[],
374 size_t key_len)
375 По описателю suite и ключу [key_len]key в state формируются структуры
376 данных, необходимые для управления паролями в режиме OCRA.
377 Предусловие
379 По адресу state зарезервировано botpOCRA_keep() октетов.
380 Возвращает
382 TRUE, если описатель корректен, и FALSE в противном случае.
383 Прим.
385 Рекомендуется использовать ключ из 32 октетов.
386 Аргументы
388 state состояние
389 suite описатель
390 key ключ
391 key_len длина ключа в октетах
392 void botpOCRAStepG (octet ctr[8], const void * state)
394 В ctr возвращается текущий счетчик, размещенный в state.
395 Ожидается
397 botpOCRAStepS() < botpHOTPStepG().
398 Аргументы
400 ctr счетчик
401 state состояние
402 void botpOCRAStepR (char * otp, const octet q[], size_t q_len, tm_time_t t,
404 void * state)
405 По запросу [q_len]q и округленной отметке t текущего времени, по
406 описателю suite, ключу и данным сеанса, размещенным в state,
407 генерируется одноразовый пароль otp. Длина otp определяется описателем
408 suite. Если suite задает использование счетчика, то после генерации
409 пароля он инкрементируется.
410 Предусловие
412 4 <= q_len && q_len < = 2 * q_max, где q_max -- максимальная длина
413 одиночного запроса, указанная в suite.
414 Если suite задает использование t, то t != TIME_ERR.
416 Ожидается
418 Формат q соответствует типу, указанному в suite.
419 Ожидается
421 botpOCRAStart() < [botpOCRAStepS()] < botpOCRAStepR()*.
422 Аргументы
424 otp одноразовый пароль
425 q запрос
426 q_len длина запроса в октетах
427 t округленная отметка времени
428 state состояние
429 void botpOCRAStepS (void * state, const octet ctr[8], const octet p[],
431 const octet s[])
432 В state устанавливаются счетчик ctr, хэш-значение p статического
433 пароля, идентификатор сеанса s.
434 Ожидается
436 botpOCRAStart() < botpOCRAStepS().
437 Прим.
439 Каждый из параметров ctr, p, s является необязательным. Указатель
440 на необязательный параметр не контролируется.
441 Функцию можно не вызывать, если все параметры необязательны.
443 Аргументы
445 state состояние
446 ctr счетчик
447 p хэш-значение статического пароля
448 s идентификатор сеанса
449 bool_t botpOCRAStepV (const char * otp, const octet q[], size_t q_len,
451 tm_time_t t, void * state)
452 По запросу [q_len]q и округленной отметке t текущего времени, по
453 описателю suite, ключу и данным сеанса, размещенным в state, строится
454 одноразовый пароль. Длина пароля определяется описателем suite.
455 Построенный пароль сравнивается c otp. Если suite задает использование
456 счетчика, то после успешной проверки пароля он инкрементируется.
457 Предусловие
459 4 <= q_len && q_len < = 2 * q_max, где q_max -- максимальная длина
460 одиночного запроса, указанная в suite.
461 Если suite задает использование t, то t != TIME_ERR.
463 Ожидается
465 Формат q соответствует типу, указанному в suite.
466 Ожидается
468 botpOCRAStart() < [botpOCRAStepS()] < botpOCRAStepV()*.
469 Возвращает
471 TRUE, если пароль подошел, и FALSE в противном случае.
472 Аргументы
474 otp контрольный пароль
475 q запрос
476 q_len длина запроса в октетах
477 t округленная отметка времени
478 state состояние
479 err_t botpOCRAVerify (const char * otp, const char * suite, const octet
481 key[], size_t key_len, const octet q[], size_t q_len, const octet
482 ctr[8], const octet p[], const octet s[], tm_time_t t)
483 По описателю suite, ключу [key_len]key, запросам [q_len]q, счетчику
484 ctr, хэш-значению p статического пароля, идентификатору сеанса s и
485 округленной отметке t текущего времени строится одноразовый пароль.
486 Построенный пароль сравнивается с otp.
487 Ожидается [ERR_BAD_FORMAT]
489 Формат suite корректен.
490 Ожидается [ERR_BAD_PARAMS]
492 4 <= q_len && q_len < = 2 * q_max, где q_max -- максимальная длина
493 одиночного запроса, указанная в suite.
494 Ожидается [ERR_BAD_TIME]
496 Если suite задает использование t, то t != TIME_ERR.
497 Ожидается [ERR_BAD_PWD]
499 Пароль otp подошел.
500 Ожидается
502 Формат q соответствует типу, указанному в suite.
503 Возвращает
505 ERR_OK в случае успеха или код ошибки.
506 Аргументы
508 otp контрольный пароль
509 suite описатель
510 key ключ
511 key_len длина ключа в октетах
512 q запрос
513 q_len длина запроса в октетах
514 ctr счетчик
515 p хэш-значение статического пароля
516 s идентификатор сеанса
517 t округленная отметка времени
518 size_t botpTOTP_keep ()
520 Возвращается длина состояния (в октетах) функций механизма TOTP.
521 Возвращает
523 Длина состояния.
524 err_t botpTOTPRand (char * otp, size_t digit, const octet key[], size_t
526 key_len, tm_time_t t)
527 По числу digit, ключу [key_len]key и округленной отметке t текущего
528 времени генерируется одноразовый пароль otp из digit цифр.
529 Ожидается [ERR_BAD_PARAMS]
531 6 <= digit && digit <= 8.
532 Ожидается [ERR_BAD_TIME]
534 t != TIME_ERR.
535 Возвращает
537 ERR_OK, если пароль успешно сгенерирован, и код ошибки в противном
538 случае.
539 Аргументы
541 otp одноразовый пароль
542 digit длина пароля
543 key ключ
544 key_len длина ключа в октетах
545 t округленная отметка времени
546 void botpTOTPStart (void * state, size_t digit, const octet key[], size_t
548 key_len)
549 По числу digit и ключу [key_len]key в state формируются структуры
550 данных, необходимые для управления паролями длины digit в режиме TOTP.
551 Предусловие
553 6 <= digit && digit <= 8.
554 По адресу state зарезервировано botpTOTP_keep() октетов.
556 Прим.
558 Рекомендуется использовать ключ из 32 октетов.
559 Аргументы
561 state состояние
562 digit число цифр в пароле
563 key ключ
564 key_len длина ключа в октетах
565 void botpTOTPStepR (char * otp, tm_time_t t, void * state)
567 По округленной отметке t текущего времени, по числу digit и ключу,
568 размещенным в state, генерируется одноразовый пароль otp из digit
569 десятичных символов.
570 Предусловие
572 t != TIME_ERR.
573 Ожидается
575 botpTOTPStart() < botpTOTPStepR()*.
576 Аргументы
578 otp одноразовый пароль
579 t округленная отметка времени
580 state состояние
581 bool_t botpTOTPStepV (const char * otp, tm_time_t t, void * state)
583 По округленной отметке t текущего времени, по числу digit и ключу,
584 размещенным в state, строится одноразовый пароль из digit символов.
585 Полученный пароль сравнивается с otp.
586 Предусловие
588 t != TIME_ERR.
589 Ожидается
591 botpTOTPStart() < botpTOTPStepV()*.
592 Возвращает
594 TRUE, если пароль подошел, и FALSE в противном случае.
595 Аргументы
597 otp контрольный пароль
598 t округленная отметка времени
599 state состояние
600 err_t botpTOTPVerify (const char * otp, const octet key[], size_t key_len,
602 tm_time_t t)
603 По ключу [key_len]key и округленной отметке t текущего времени строится
604 одноразовый пароль из strLen(otp) символов. Построенный пароль
605 сравнивается с otp.
606 Ожидается [ERR_BAD_PWD]
608 6 <= digit && digit <= 8.
609 Ожидается [ERR_BAD_TIME]
611 t != TIME_ERR.
612 Ожидается [ERR_BAD_PWD]
614 Пароль otp подошел.
615 Возвращает
617 ERR_OK в случае успеха или код ошибки.
618 Аргументы
620 otp контрольный пароль
621 key ключ
622 key_len длина ключа в октетах
623 t округленная отметка времени
624
626 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
627Библиотека Bee2 Пт 23 Июн 2023 botp.h(3)