1btok.h(3) Library Functions Manual btok.h(3)
2
6 btok.h - Криптографическая архитектура СТБ 34.101.79 (btok)
7
10 #include 'bee2/defs.h'
11 #include 'bee2/core/apdu.h'
12 #include 'bee2/crypto/bake.h'
13 Классы
16 struct btok_pwd_state
17 Состояние парольного автомата
18 struct btok_cvc_t
19 Информационное содержание CV-сертификата
20 Перечисления
22 enum btok_pin_state
23 Состояние PIN парольного автомата
24 enum btok_auth_state
25 Статус аутентификации парольного автомата
26 enum btok_pwd_event
27 События парольного автомата
28 Функции
30 bool_t btokPwdTransition (btok_pwd_state *state, btok_pwd_event event)
31 Обработка события парольным автоматом
32 err_t btokCVCCheck (const btok_cvc_t *cvc)
33 Проверка содержания CV-сертификата
34 err_t btokCVCCheck2 (const btok_cvc_t *cvc, const btok_cvc_t *cvca)
35 Проверка содержания CV-сертификата с учетом данных издателя
36 err_t btokCVCWrap (octet cert[], size_t *cert_len, btok_cvc_t *cvc,
37 const octet privkey[], size_t privkey_len)
38 Создание CV-сертификата
39 err_t btokCVCUnwrap (btok_cvc_t *cvc, const octet cert[], size_t
40 cert_len, const octet pubkey[], size_t pubkey_len)
41 Разбор CV-сертификата
42 err_t btokCVCIss (octet cert[], size_t *cert_len, btok_cvc_t *cvc,
43 const octet certa[], size_t certa_len, const octet privkeya[],
44 size_t privkeya_len)
45 Выпуск CV-сертификата
46 size_t btokCVCLen (const octet der[], size_t count)
47 Точная длина CV-сертификата
48 err_t btokCVCVal (const octet cert[], size_t cert_len, const octet
49 certa[], size_t certa_len, const octet *date)
50 Проверка CV-сертификата
51 err_t btokCVCVal2 (btok_cvc_t *cvc, const octet cert[], size_t
52 cert_len, const btok_cvc_t *cvca, const octet *date)
53 Проверка CV-сертификата в цепочке
54 err_t btokCVCMatch (const octet cert[], size_t cert_len, const octet
55 privkey[], size_t privkey_len)
56 Проверка соответствия CV-сертификата
57 size_t btokSM_keep ()
58 Длина состояния SM.
59 void btokSMStart (void *state, const octet key[32])
60 Инициализация функций SM.
61 void btokSMCtrInc (void *state)
62 Увеличение счетчика SM.
63 err_t btokSMCmdWrap (octet apdu[], size_t *count, const apdu_cmd_t
64 *cmd, void *state)
65 Кодирование и установка защиты команды с помощью SM.
66 err_t btokSMCmdUnwrap (apdu_cmd_t *cmd, size_t *size, const octet
67 apdu[], size_t count, void *state)
68 Декодирование и снятие защиты команды с помощью SM.
69 err_t btokSMRespWrap (octet apdu[], size_t *count, const apdu_resp_t
70 *resp, void *state)
71 Кодирование и установка защиты ответа с помощью SM.
72 err_t btokSMRespUnwrap (apdu_resp_t *resp, size_t *size, const octet
73 apdu[], size_t count, void *state)
74 Декодирование и снятие защиты ответа с помощью SM.
75 size_t btokBAuthT_keep (size_t l)
76 Длина состояния функций BAUTH на стороне Т
77 err_t btokBAuthTStart (void *state, const bign_params *params, const
78 bake_settings *settings, const octet privkey[], const bake_cert
79 *cert)
80 Инициализация протокола BAUTH на стороне Т
81 size_t btokBAuthCT_keep (size_t l)
82 Длина состояния функций BAUTH на стороне КТ
83 err_t btokBAuthCTStart (void *state, const bign_params *params, const
84 bake_settings *settings, const octet privkey[], const bake_cert
85 *cert)
86 Инициализация протокола BAUTH на стороне КТ
87 err_t btokBAuthCTStep2 (octet out[], const bake_cert *certt, void
88 *state)
89 Шаг 2 протокола BAUTH.
90 err_t btokBAuthTStep3 (octet out[], const octet in[], void *state)
91 Шаг 3 протокола BAUTH.
92 err_t btokBAuthCTStep4 (octet out[], const octet in[], void *state)
93 Шаг 4 протокола BAUTH.
94 err_t btokBAuthTStep5 (const octet in[], size_t in_len, bake_certval_i
95 val_ct, void *state)
96 Шаг 5 протокола BAUTH.
97 err_t btokBAuthCTStepG (octet key[32], void *state)
98 Извлечение ключа протокола BAUTH на стороне КТ
99 err_t btokBAuthTStepG (octet key[32], void *state)
100 Извлечение ключа протокола BAUTH на стороне T.
101
103 Реализованы отдельные механизмы СТБ 34.101.79 (btok):
104 • управление облегченными (Card Verifiable, CV) сертификатами.
106 Ожидается [ERR_BAD_INPUT]
108 Все входные указатели действительны. Исключение составляют
109 оговоренные случаи. К ним относится запрос на определение объема
110 памяти, которую требуется зарезервировать при повторном вызове
111 (конструкция [len?]ptr).
112
114 Управление CV-сертификатами реализовано в соответствии с профилем,
115 заданным в СТБ 34.101.79. Профиль назначает:
116 • использование стандартных долговременных параметров bign-curve256v1,
118 bign-curve384v1 и bign-curve512v1;
119 • использование алгоритмов bign-sign для выработки и проверки подписи;
121 • использование алгоритмов belt-hash, bash384, bash512 для хэширования
123 подписываемых данных;
124 • использование (опциональное) 5-октетного слова прав доступа к
126 прикладной программе eId;
127 • использование (опциональное) 2-октетного слова прав доступа к
129 прикладной программе eSign;
130 • использование специфических объектных идентификаторов, в частности,
132 bign-pubkey.
133 В реализации профиль СТБ 34.101.79 расширен: в сертификатах могут
135 использоваться ключи и алгоритмы bign96 (см. bign96.h). В частности,
136 открытые ключи могут лежать как на стандартных кривых bign-curve256v1,
137 bign-curve384v1 и bign-curve512v1, так и на кривой bign-curve192v1.
138 Информационные поля CV-сертификата перечислены в структуре btok_cvc_t.
140 Сертификат представляет собой DER-код данных полей.
141 Отсутствие в сертификате слова прав доступа означает, что оно является
143 нулевым, т.е. что права доступа отстутствуют. По кодировании
144 сертификата нулевое слово прав доступа опускается. При этом наличие в
145 декодируемом сертификате нулевого слова не считается ошибкой.
146 Дата в сертификате задается 6 октетами по схеме YYMMDD (см. tm.h).
148
150 Защищенное соединение (Secure Messaging) -- это правила защиты
151 APDU-команд и APDU-ответов. Общие правила огранизации защищенного
152 соединения определены в ISO/IEC 7816-4, конкретные правила, которые
153 собственно и реализованы, --- в СТБ 34.101.79.
154 Состояние SM содержит три объекта:
156 • ключ имитозащиты (belt-mac);
158 • ключ шифрования (belt-cfb);
160 • счетчик.
162 Защита организована по схеме encrypt-then-mac: сначала тело
164 команды/ответа зашифровывается, а затем к шифртексту присоединяется
165 имитовставка, которая покрывает шифртекст и открытые данные
166 команды/ответа.
167 Счетчик используется в качестве синхропосылки при шифровании. Перед
169 установкой защиты или ее снятием счетчик инкрементируется.
170 Первоначально счетчик равняется нулю.
171 Контролируется следующая логика:
173 • установка/снятие защиты команды выполняется с нечетными значениями
175 счетчика;
176 • установка/снятие защиты команды выполняется с четными значениями
178 счетчика.
179 Ожидается
181 Состояние функций SM не изменяется вне этих функций.
182 Предусловие
184 Указатели функций SM корректны, если не оговорено противное.
185 Входные и выходные буферы функций SM не пересекаются друг с другом.
187 Прим.
189 Признаком защиты команды является бит 0x04 в поле CLA.
190
192 Протокол выполняется между терминалом (T) и криптографическим токеном
193 (КТ, cryptographic token = CT).
194 Для настройки протокола используется структура bake_settings (см.
196 bake.h). В терминах протоколов Bake в роли стороны A выступает
197 терминал, в роли стороны B -- криптографический токен.
198 Терминал всегда подтверждает сформированный ключ, т.е. проходит
200 аутентификацию перед КТ. Поэтому в структуре bake_settings флаг kca
201 должен равняться TRUE.
202 КТ проходит аутентификацию перед КТ опционально: в структуре
204 bake_settings флаг kcb может принимать как значение TRUE, так и
205 значение FALSE.
206 Ожидается [ERR_BAD_INPUT]
208 Все входные указатели, за исключением оговоренных случаев,
209 корректны.
210 Ожидается
212 При пошаговом выполнении протокола данные, переданные при
213 инициализации через указатели, остаются корректными и постоянными
214 на протяжении всего выполнения протокола.
215
217 size_t btokBAuthCT_keep (size_t l)
218 Определяется длина состояния (в октетах) функций протокола BAUTH на
219 стороне КТ.
220 Возвращает
222 Длина состояния.
223 Аргументы
225 l уровень стойкости
226 err_t btokBAuthCTStart (void * state, const bign_params * params, const
228 bake_settings * settings, const octet privkey[], const bake_cert *
229 cert)
230 По параметрам params, настройкам settings, личному ключу [l / 4]privkey
231 и сертификату cert соответствующего открытого ключа в state формируются
232 структуры данных, необходимые для выполнения протокола BAUTH на стороне
233 КТ.
234 Предусловие
236 По адресу state зарезервировано btokBAuthCT_keep() октетов.
237 Ожидается [ERR_BAD_PARAMS]
239 Параметры params корректны.
240 Ожидается [ERR_BAD_INPUT]
242 settings->kca == TRUE.
243 Ожидается [ERR_BAD_INPUT]
245 Указатель settings->helloa нулевой, либо буфер
246 [settings->helloa_len]settings->helloa корректен. Аналогичное
247 требование касается полей settings->hellob, settings->hellob_len.
248 Ожидается [ERR_BAD_RNG]
250 Генератор settings->rng (с состоянием settings->rng_state)
251 корректен.
252 Ожидается
254 Генератор settings->rng является криптографически стойким.
255 Ожидается [ERR_BAD_CERT]
257 Сертификат cert корректен.
258 Ожидается
260 Ключ privkey и сертификат cert согласованы. Если согласование
261 нарушено, то протокол будет завершен с ошибкой.
262 Возвращает
264 ERR_OK, если инициализация успешно выполнена, и код ошибки в
265 противном случае.
266 Аргументы
268 state состояние
269 params долговременные параметры
270 settings настройки
271 privkey личный ключ
272 cert сертификат
273 err_t btokBAuthCTStep2 (octet out[], const bake_cert * certt, void * state)
275 КТ выполняет шаг 2 протокола BAUTH, обрабатывая сертификат терминала
276 certt и используя состоянием state. При успешном выполнении шага
277 формируется сообщение M1 = [5 l / 8 + 16]out.
278 Ожидается
280 btokBAuthCTStart() < btokBAuthCTStep2().
281 Возвращает
283 ERR_OK, если шаг успешно выполнен, и код ошибки в противном случае.
284 Прим.
286 Приветственное сообщение КТ в M1 не передаются.
287 Аргументы
289 out выходное сообщение M1
290 certt сертификат терминала
291 state состояние
292 err_t btokBAuthCTStep4 (octet out[], const octet in[], void * state)
294 КТ выполняет шаг 4 протокола BAUTH, обрабатывая сообщение M2 = [8]in,
295 если не требуется аутентификация перед Т, или M2 = [8 + 16]in, если не
296 требуется, и используя состояние state. Если аутентификация перед КТ
297 требуется, то при успешном выполнении шага формируется сообщение M3 =
298 [l / 4 + cert->len + 8]out.
299 Ожидается
301 btokBAuthCTStep2() < btokBAuthCTStep4().
302 Ожидается
304 btokBAuthTStep3() << btokBAuthCTStep4().
305 Возвращает
307 ERR_OK, если шаг успешно выполнен, и код ошибки в противном случае.
308 Аргументы
310 out выходное сообщение M3
311 in входное сообщение M2
312 state состояние
313 err_t btokBAuthCTStepG (octet key[32], void * state)
315 КТ определяет общий секретный ключ key, полученный с помощью протокола
316 BAUTH с состоянием state.
317 Ожидается
319 btokBAuthCTStep4() < btokBAuthCTStepG().
320 Возвращает
322 ERR_OK, если ключ успешно извлечен, и код ошибки в противном
323 случае.
324 Аргументы
326 key общий ключ
327 state состояние
328 size_t btokBAuthT_keep (size_t l)
330 Определяется длина состояния (в октетах) функций протокола BAUTH на
331 стороне Т.
332 Возвращает
334 Длина состояния.
335 Аргументы
337 l уровень стойкости
338 err_t btokBAuthTStart (void * state, const bign_params * params, const
340 bake_settings * settings, const octet privkey[], const bake_cert *
341 cert)
342 По параметрам params, настройкам settings, личному ключу [l / 4]privkey
343 и сертификату cert соответствующего открытого ключа в state формируются
344 структуры данных, необходимые для выполнения протокола BAUTH на стороне
345 T.
346 Предусловие
348 По адресу state зарезервировано btokBAuthT_keep() октетов.
349 Ожидается [ERR_BAD_PARAMS]
351 Параметры params корректны.
352 Ожидается [ERR_BAD_INPUT]
354 settings->kca == TRUE.
355 Ожидается [ERR_BAD_INPUT]
357 Указатель settings->helloa нулевой, либо буфер
358 [settings->helloa_len]settings->helloa корректен. Аналогичное
359 требование касается полей settings->hellob, settings->hellob_len.
360 Ожидается [ERR_BAD_RNG]
362 Генератор settings->rng (с состоянием settings->rng_state)
363 корректен.
364 Ожидается
366 Генератор settings->rng является криптографически стойким.
367 Ожидается [ERR_BAD_CERT]
369 Сертификат cert корректен.
370 Ожидается
372 Ключ privkey и сертификат cert согласованы. Если согласование
373 нарушено, то протокол будет завершен с ошибкой.
374 Возвращает
376 ERR_OK, если инициализация успешно выполнена, и код ошибки в
377 противном случае.
378 Аргументы
380 state состояние
381 params долговременные параметры
382 settings настройки
383 privkey личный ключ
384 cert сертификат
385 err_t btokBAuthTStep3 (octet out[], const octet in[], void * state)
387 Т выполняет шаг 3 протокола BAUTH, обрабатывая сообщение M1 = [5 l / 8
388 + 16]in и используя состояние state. При успешном выполнении шага
389 формируется сообщение M2 = [8]out, если не требуется аутентификация
390 перед Т, или M2 = [8 + 16]out, если требуется.
391 Ожидается
393 btokBAuthTStart() < btokBAuthTStep3().
394 Ожидается
396 btokBAuthCTStep2() << btokBAuthTStep3().
397 Возвращает
399 ERR_OK, если шаг успешно выполнен, и код ошибки в противном случае.
400 Аргументы
402 out выходное сообщение M2
403 in входное сообщение M1
404 state состояние
405 err_t btokBAuthTStep5 (const octet in[], size_t in_len, bake_certval_i
407 val_ct, void * state)
408 Т выполняет шаг 5 протокола BAUTH, обрабатывая сообщение M3 =
409 [in_len]in и используя состояние state. Т проверяет присланный в M3
410 сертификат КТ с помощью функции val_ct.
411 Ожидается [ERR_BAD_LOGIC]
413 settings->kcb == TRUE, т.е. требуется аутентификация КТ перед Т.
414 Ожидается
416 btokBAuthTStep3() < btokBAuthTStep5().
417 Ожидается
419 btokBAuthCTStep4() << btokBAuthTStep5().
420 Возвращает
422 ERR_OK, если шаг успешно выполнен, и код ошибки в противном случае.
423 Аргументы
425 in входное сообщение M3
426 in_len длина in
427 val_ct функция проверки сертификата КТ
428 state состояние
429 err_t btokBAuthTStepG (octet key[32], void * state)
431 Т определяет общий секретный ключ key, полученный с помощью протокола
432 BAUTH с состоянием state.
433 Ожидается
435 Если КТ аутентифицируется перед терминалом, то btokBAuthTStep5() <
436 btokBAuthTStepG(), иначе btokBAuthTStep3() < btokBAuthTStepG().
437 Возвращает
439 ERR_OK, если ключ успешно извлечен, и код ошибки в противном
440 случае.
441 Аргументы
443 key общий ключ
444 state состояние
445 err_t btokCVCCheck (const btok_cvc_t * cvc)
447 Проверяется корректность содержания cvc CV-сертификата. Проверка
448 завершается успешно, если:
449 • cтроки cvc->authority и cvc->holder состоят из печатаемых символов;
451 • длины строк cvc->authority и cvc->holder лежат в диапазоне от 8 до
453 12;
454 • даты cvc->from и cvc->until корректны;
456 • cvc->from <= cvc->until;
458 • открытый ключ [cvc->pubkey_len]cvc->pubkey корректен (лежит на одной
460 из кривых bign-curveXXXv1).
461 Возвращает
463 ERR_OK, если проверка прошла успешно, и код ошибки в противном
464 случае.
465 Прим.
467 Подпись cvc->sig не проверяется.
468 Аргументы
470 cvc содержание сертификата
471 err_t btokCVCCheck2 (const btok_cvc_t * cvc, const btok_cvc_t * cvca)
473 Проверяется корректность содержания cvc CV-сертификата с учетом
474 содержания cvca сертификата (потенциального) издателя. Проверка
475 завершается успешно, если:
476 • btokCVCCheck(cvc) == ERR_OK;
478 • cvc->authority == cvca->holder;
480 • даты cvca->from и cvca->until корректны;
482 • cvca->from <= cvc->from && cvc->from <= cvca->until.
484 Возвращает
486 ERR_OK, если проверка прошла успешно, и код ошибки в противном
487 случае.
488 Прим.
490 Подпись cvc->sig не проверяется.
491 Аргументы
493 cvc содержание сертификата
494 cvca содержание сертификата издателя
495 err_t btokCVCIss (octet cert[], size_t * cert_len, btok_cvc_t * cvc, const
497 octet certa[], size_t certa_len, const octet privkeya[], size_t
498 privkeya_len)
499 Выпускается CV-сертификат [cert_len?]cert с содержанием cvc. При
500 выпуске используются личный ключ [privkeya_len]privkeya и сертификат
501 [certa_len]certa издателя. Подпись сертификата сохраняется в
502 [cvc->sig_len]cvc->sig. Перед выпуском проверяются следующие условия:
503 • certa имеет корректный формат;
505 • btokCVCCheck2(cvc, cvca) == ERR_OK, где cvca -- содержание certa;
507 • открытый ключ в certa соответствует личному ключу privkeya.
509 Возвращает
511 ERR_OK, если сертификат успешно выпущен, и код ошибки в противном
512 случае.
513 Прим.
515 Используется детерминированный режим выработки подписи. Если
516 инициализирован штатный ГСЧ, то дополнительно используются данные
517 от него.
518 Аргументы
520 cert сертификат
521 cert_len длина cert в октетах
522 cvc содержание сертификата
523 certa сертификат издателя
524 certa_len длина certa в октетах
525 privkeya личный ключ издателя
526 privkeya_len длина privkeya в октетах
527 size_t btokCVCLen (const octet der[], size_t count)
529 Определяется точная длина CV-сертификата, размещенного в префиксе
530 DER-кода [count]der.
531 Возвращает
533 Длина сертификата или SIZE_MAX в случае ошибки.
534 Прим.
536 Корректность CV-сертификата не проверяется.
537 Аргументы
539 der DER-код
540 count длина der в октетах
541 err_t btokCVCMatch (const octet cert[], size_t cert_len, const octet
543 privkey[], size_t privkey_len)
544 Проверяется соответствие между CV-сертификатом [cert_len]cert и личным
545 ключом [privkey_len]privkey. Проверка завершается успешно, если:
546 • cert имеет корректный формат;
548 • открытый ключ cert соответствует privkey.
550 Возвращает
552 ERR_OK, если соответствие подтверждено, и код ошибки в противном
553 случае.
554 Аргументы
556 cert сертификат
557 cert_len длина cert в октетах
558 privkey личный ключ
559 privkey_len длина privkey в октетах
560 err_t btokCVCUnwrap (btok_cvc_t * cvc, const octet cert[], size_t cert_len,
562 const octet pubkey[], size_t pubkey_len)
563 Определяется и проверяется содержание cvc CV-сертификата
564 [cert_len]cert. При проверке используется открытый ключ
565 [pubkey_len]pubkey. Проверка завершается успешно, если:
566 • btokCVCCheck(cvc) == ERR_OK;
568 • подпись cert признается корректной на открытом ключе pubkey. Может
570 передаваться нулевая длина pubkey_len, и тогда:
571 • подпись не проверяется, если pubkey == 0;
573 • подпись проверяется на открытом ключе сертификата, если pubkey ==
575 cvc->pubkey;
576 • индуцируется ошибка, если pubkey != 0 && pubkey != cvc->pubkey.
578 Возвращает
580 ERR_OK, если сертификат успешно разобран, и код ошибки в противном
581 случае.
582 Прим.
584 Даже если подпись не проверяется, ее длина все равно
585 контролируется. Неверная длина расценивается как ошибка формата.
586 Длина cert должна в точности равняться cert_len. Противное
588 считается ошибкой формата.
589 Аргументы
591 cvc содержание сертификата
592 cert сертификат
593 cert_len длина cert в октетах
594 pubkey открытый ключ
595 pubkey_len длина pubkey в октетах
596 err_t btokCVCVal (const octet cert[], size_t cert_len, const octet certa[],
598 size_t certa_len, const octet * date)
599 Проверяется корректность CV-сертификата [cert_len]cert на дату date,
600 для чего используется сертификат издателя [certa_len]certa. Проверка
601 завершается успешно, если:
602 • certa имеет корректный формат;
604 • cert разбирается без ошибок на открытом ключе из certa;
606 • btokCVCCheck2(cvc, cvca) == ERR_OK, где cvc и cvca -- содержание cert
608 и certa соответственно;
609 • date попадает в срок действия cert. Указатель date может быть
611 нулевым, и тогда последняя проверка не выполняется.
612 Возвращает
614 ERR_OK, если сертификат признан корректным, и код ошибки в
615 противном случае.
616 Прим.
618 Текущую дату можно определить с помощью функции tmDate2().
619 Аргументы
621 cert сертификат
622 cert_len длина cert в октетах
623 certa сертификат издателя
624 certa_len длина certa в октетах
625 date дата проверки
626 err_t btokCVCVal2 (btok_cvc_t * cvc, const octet cert[], size_t cert_len,
628 const btok_cvc_t * cvca, const octet * date)
629 Проверяется корректность CV-сертификата [cert_len]cert на дату date,
630 для чего используется содержание cvca сертификата издателя. В случае
631 успеха определяется содержание cvc проверяемого сертификата. Проверка
632 завершается успешно, если:
633 • cert имеет корректный формат;
635 • имя издателя в cert совпадает с именем владельца в cvca;
637 • подпись cert признается корректной на открытом ключе из cvca;
639 • срок действия, заданный в cvca, корректен;
641 • начало действия cert не выходит за пределы срока действия cvca;
643 • date попадает в срок действия cert. Указатель date может быть
645 нулевым, и тогда последняя проверка не выполняется. Указатель cvc
646 может быть нулевым, и тогда содержание проверяемого сертификата не
647 возвращается.
648 Возвращает
650 ERR_OK, если сертификат признан корректным, и код ошибки в
651 противном случае.
652 Прим.
654 Текущую дату можно определить с помощью функции tmDate2().
655 Интерфейс ориентирован на проверку цепочки сертификатов. Цепочка
657 certa, certb, certc,... проверяется следующим образом:
658 • btokCVCUnwrap(cvca, certa, certa_len, 0, 0);
660 • btokCVCVal2(cvcb, certb, certb_len, cvca, 0);
662 • btokCVCVal2(cvcc, certc, certc_len, cvcb, date);
664 • ...
666 Прим.
668 Если certa является самоподписанным и требуется проверить его
669 подпись, то первая строчка в предыдущем коде должна выглядеть
670 следующим образом:
671 • btokCVCUnwrap(cvca, certa, certa_len, cvca->pubkey, 0);
673 Аргументы
675 cvc содержание сертификата
676 cert сертификат
677 cert_len длина cert в октетах
678 cvca содержание сертификата издателя
679 date дата проверки
680 err_t btokCVCWrap (octet cert[], size_t * cert_len, btok_cvc_t * cvc, const
682 octet privkey[], size_t privkey_len)
683 Создается CV-сертификат [cert_len?]cert с содержанием cvc. Сертификат
684 подписывается на личном ключе [privkey_len]privkey. Подпись сохраняется
685 в [cvc->sig_len]cvc->sig. Если cvc->pubkey_len == 0, то открытый ключ
686 [cvc->pubkey_len]cvc->pubkey строится по privkey и выходной сертификат
687 выступает в роли доказательства владения личным ключом. Непосредственно
688 перед созданием сертификата проверяется содержание cvc. Проверка
689 завершается успешно, если:
690 • btokCVCCheck(cvc) == ERR_OK.
692 Возвращает
694 ERR_OK, если сертификат успешно создан, и код ошибки в противном
695 случае.
696 Прим.
698 Используется детерминированный режим выработки подписи. Если
699 инициализирован штатный ГСЧ, то дополнительно используются данные
700 от него.
701 Устанавливая cvc->pubkey_len == 0 && cvc->authority == cvc->holder,
703 можно создать самоподписанный сертификат.
704 Устанавливая cvc->pubkey_len == 0 && cvc->authority != cvc->holder,
706 можно создать предварительный сертификат, подпись которого будет
707 изменена в дальнейшем стороной cvc->authority. Предварительный
708 сертификат доказывает владение стороной cvc->holder личным ключом,
709 которому соответствует открытый ключ cvc->pubkey. Предварительный
710 сертификат выступает в роли запроса на выпуск сертификата.
711 Аргументы
713 cert сертификат
714 cert_len длина cert в октетах
715 cvc содержание сертификата
716 privkey личный ключ
717 privkey_len длина privkey в октетах
718 bool_t btokPwdTransition (btok_pwd_state * state, btok_pwd_event event)
720 Парольный автомат с состоянием state обрабатывает событие event.
721 Состояние может изменяться при обработке.
722 Предусловие
724 Указатель state корректен.
725 Возвращает
727 TRUE, если событие event является допустимым и поэтому обработано,
728 и FALSE в противном случае.
729 Аргументы
731 state состояние
732 event событие
733 size_t btokSM_keep ()
735 Возвращается длина состояния (в октетах) функций SM.
736 Возвращает
738 Длина состояния.
739 err_t btokSMCmdUnwrap (apdu_cmd_t * cmd, size_t * size, const octet apdu[],
741 size_t count, void * state)
742 Код команды [count]apdu декодируется и одновременно с него снимается
743 защита с помощью объектов SM, размещенных в state. Результат
744 возвращается в буфере [size?]cmd. Указатель state может быть нулевым, и
745 тогда выполняется только декодирование, без снятия защиты. Указатель
746 cmd может быть нулевым, и тогда выполняется только проверка формата
747 кода, без контроля целостности.
748 Предусловие
750 По адресу state зарезервировано btokSM_keep() октетов.
751 Ожидается
753 btokSMStart() < btokSMCmdUnwrap()*.
754 Ожидается [ERR_BAD_APDU]
756 Если state != 0, то в cmd->cla установлен бит 0x04 (признак
757 защиты). Если state == 0, то бит снят.
758 Ожидается [ERR_BAD_LOGIC]
760 Непосредственно а момент снятия защиты (cmd != 0 && state != 0)
761 счетчик SM принимает нечетное значение.
762 Возвращает
764 ERR_OK в случае успеха и код ошибки в противном случае.
765 Аргументы
767 cmd команда
768 size размер буфера для команды
769 apdu код команды
770 count длина кода команды
771 state состояние SM
772 err_t btokSMCmdWrap (octet apdu[], size_t * count, const apdu_cmd_t * cmd,
774 void * state)
775 Команда cmd кодируется и защищается с помощью объектов SM, размещенных
776 в state. Результат возвращается в буфере [count?]apdu. Указатель state
777 может быть нулевым, и тогда выполняется только кодирование, без защиты.
778 Предусловие
780 По адресу state зарезервировано btokSM_keep() октетов.
781 Ожидается
783 btokSMStart() < btokSMCmdWrap()*.
784 Ожидается [ERR_BAD_APDU]
786 В cmd->cla снят бит 0x04 (признак защиты).
787 Ожидается [ERR_BAD_LOGIC]
789 Непосредственно а момент установки защиты (apdu != 0 && state != 0)
790 счетчик SM принимает нечетное значение.
791 Возвращает
793 ERR_OK в случае успеха и код ошибки в противном случае.
794 Аргументы
796 apdu код команды
797 count длина кода команды
798 cmd команда
799 state состояние SM
800 void btokSMCtrInc (void * state)
802 Счетчик, размещенный в состоянии state, увеличивается на 1.
803 Предусловие
805 По адресу state зарезервировано btokSM_keep() октетов.
806 Ожидается
808 btokSMStart() < btokSMCtrInc()*.
809 Прим.
811 Отправитель команд и ответов должен увеличивать счетчик всякий раз
812 перед установкой их защиты. Соответственно получатель должен
813 увеличивать счетчик всякий раз перед снятием защиты.
814 Установка и снятие защиты команд должны выполняться с нечетными
816 значениями счетчика. Установка и снятие защиты ответов -- с
817 четными.
818 Аргументы
820 state состояние SM
821 err_t btokSMRespUnwrap (apdu_resp_t * resp, size_t * size, const octet
823 apdu[], size_t count, void * state)
824 Код ответа [count]apdu декодируется и одновременно с него снимается
825 защита с помощью объектов SM, размещенных в state. Результат
826 возвращается в буфере [size?]resp. Указатель state может быть нулевым,
827 и тогда выполняется только декодирование, без снятия защиты. Указатель
828 resp может быть нулевым, и тогда выполняется только проверка формата
829 кода, без контроля целостности.
830 Предусловие
832 По адресу state зарезервировано btokSM_keep() октетов.
833 Ожидается
835 btokSMStart() < btokSMRespUnwrap()*.
836 Ожидается [ERR_BAD_LOGIC]
838 Непосредственно а момент снятия защиты (resp != 0 && state != 0)
839 счетчик SM принимает четное значение.
840 Возвращает
842 ERR_OK в случае успеха и код ошибки в противном случае.
843 Аргументы
845 resp ответ
846 size размер буфера для ответа
847 apdu код ответа
848 count длина кода ответа
849 state состояние SM
850 err_t btokSMRespWrap (octet apdu[], size_t * count, const apdu_resp_t *
852 resp, void * state)
853 Ответ resp кодируется и защищается с помощью объектов SM, размещенных в
854 state. Результат возвращается в буфере [count?]apdu. Указатель state
855 может быть нулевым, и тогда выполняется только кодирование, без защиты.
856 Предусловие
858 По адресу state зарезервировано btokSM_keep() октетов.
859 Ожидается
861 btokSMStart() < btokSMRespWrap()*.
862 Ожидается [ERR_BAD_LOGIC]
864 Непосредственно а момент установки защиты (apdu != 0 && state != 0)
865 счетчик SM принимает четное значение.
866 Возвращает
868 ERR_OK в случае успеха и код ошибки в противном случае.
869 Аргументы
871 apdu код ответа
872 count длина кода ответа
873 resp ответ
874 state состояние SM
875 void btokSMStart (void * state, const octet key[32])
877 По ключу key в state формируются объекты, необходимые для управления
878 защищенным соединением.
879 Предусловие
881 По адресу state зарезервировано btokSM_keep() октетов.
882 Прим.
884 В перечень объектов входит счетчик, первоначально равный нулю.
885 Аргументы
887 state состояние SM
888 key ключ
889
891 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
892Библиотека Bee2 Пт 23 Июн 2023 btok.h(3)