Единая библиотека PKCS #11 предоставляет высокоуровневый интерфейс (см. API Единой библиотеки PKCS #11) для взаимодействия с JaCarta-2 ГОСТ по стандарту PKCS #11 v2.30.
Для Microsoft Windows Единая библиотека PKCS #11 не требует установки в систему и входит в состав JaCarta-2 SDK в виде динамической библиотеки:
SDK/lib/Win32/jcPKCS11-2.dll
– библиотека под 32–битную архитектуру;SDK/lib/Win64/jcPKCS11-2.dll
– библиотека под 64–битную архитектуру.Шаги по установке библиотеки:
System Integrity Protection
.Перезагрузите компьютер. При включении зажмите на клавиатуре клавиши ⌘ R (Command+R).
После загрузки ОС на экране появится меню восстановления. Откройте раздел “Утилиты” и запустите “Терминал”.
В открывшемся окне Терминала выполните команду:
$ csrutil disable
Перезагрузите компьютер через меню, чтобы настройки вступили в силу.
Установить пакет pcsc-lite, если он не установлен.
Например, пакет можно установить при помощи пакетного менеджера Homebrew:
$ brew install pcsc-lite
Установить библиотеку.
Запустите инсталлятор SDK/lib/macOS/jcPKCS11-2_x.x.x.x.pkg
и следуйте инструкциям установщика.
Библиотека будет установлена в качестве Framework в /Library/Frameworks/jcPKCS11-2.framework
.
System Integrity Protection
.Перезагрузите компьютер. При включении зажмите на клавиатуре клавиши ⌘ R (Command+R).
После загрузки ОС на экране появится меню восстановления. Откройте раздел “Утилиты” и запустите “Терминал”.
В открывшемся окне Терминала выполните команду:
$ csrutil enable
Перезагрузите компьютер через меню, чтобы настройки вступили в силу.
Шаги по установке библиотеки:
Установить библиотеку.
SDK/lib/linux-i386/jcPKCS11-2_x.x.x.x_i386.deb
. Библиотека будет установлена в /usr/lib/libjcPKCS11-2.so
.SDK/lib/linux-i386/jcPKCS11-2_x.x.x.x_i386.rpm
. Библиотека будет установлена в /usr/lib/libjcPKCS11-2.so
.SDK/lib/linux-x86_64/jcPKCS11-2_x.x.x.x_amd64.deb
. Библиотека будет установлена в /usr/lib/libjcPKCS11-2.so
.SDK/lib/linux-x86_64/jcPKCS11-2_x.x.x.x_x86_64.rpm
. Библиотека будет установлена в /usr/lib64/libjcPKCS11-2.so
.Совет
В документации по Единой библиотеке PKCS #11 в разделах:
Для использования jcPKCS11-2 в проекте выполните следующие шаги:
Прилинкуйте библиотеку к проекту. Пути до библиотеки в зависимости от ОС:
SDK/lib/Win32/jcPKCS11-2.dll
;SDK/lib/Win64/jcPKCS11-2.dll
..pkg
пакета – /Library/Frameworks/jcPKCS11-2.framework
..deb
пакета – /usr/lib/libjcPKCS11-2.so
;.rpm
пакета – /usr/lib/libjcPKCS11-2.so
..deb
пакета – /usr/lib/libjcPKCS11-2.so
;.rpm
пакета – /usr/lib64/libjcPKCS11-2.so
.Примечание
В примерах, входящих в состав JaCarta-2 SDK, путь до библиотеки (PKCS_LIB_PATH
)
устанавливается в SDK/sources/CMakeLists.sdk
, а затем используется в
SDK/sources/common/tools.make
и SDK/sources/common/P11Loader.cpp
.
В коде подключите заголовочный файл jcPKCS11.h
.
Пример:
#include "jcPKCS11.h"
Если вы подключаете динамическую библиотеку в Runtime, то подгрузите из нее необходимые функции.
Вызовите функцию C_GetFunctionList()
для получения функций стандарта PKCS #11, реализованных в библиотеке.
Все они описаны в разделе Функции, входящие в стандарт PKCS #11.
Пример:
/// ...
// Список функций, входящих в стандарт PKCS #11
CK_FUNCTION_LIST_PTR funcs = NULL_PTR;
// Загрузить функцию для получения списка функций, входящих в стандарт PKCS #11
CK_C_GetFunctionList C_GetFunctionList = (CK_C_GetFunctionList) GetFunction(libHandle, "C_GetFunctionList");
if (C_GetFunctionList == NULL_PTR)
{
printf("ERROR: C_GetFunctionList hasn't been found in module\n");
return;
}
// Загрузить функции, входящие в стандарт PKCS #11
rv = C_GetFunctionList(&funcs);
if (rv != CKR_OK)
{
printf("ERROR: C_GetFunctionList is failed: 0x%08x\n", rv);
return;
}
printf("C_GetFunctionList - OK\n");
/// ...
// Использование на примере инициализации библиотеки
rv = funcs->C_Initialize(NULL_PTR);
if (rv != CKR_OK)
{
printf("ERROR: C_Initialize is failed: 0x%08x\n", rv);
return;
}
printf("C_Initialize - OK\n");
/// ...
Вызовите функцию JC_GetFunctionList()
для получения дополнительных функций, реализованных в библиотеке, но не входящих в стандарт PKCS #11.
Все они описаны в разделе Функции, не входящие в стандарт PKCS #11.
Этот шаг следует выполнять, если Вам требуются функции расширения.
Пример:
/// ...
// Список дополнительных функций, не входящих в стандарт PKCS #11
JC_FUNCTION_LIST_PTR funcsExtra = NULL_PTR;
// Загрузить функцию для получения списка дополнительных функций, не входящих в стандарт PKCS #11
FP_JC_GetFunctionList JC_GetFunctionList = (FP_JC_GetFunctionList) GetFunction(libHandle, "JC_GetFunctionList");
if (JC_GetFunctionList == NULL_PTR)
{
printf("ERROR: C_GetFunctionList hasn't been found in module\n");
return;
}
// Загрузить дополнительные функции, не входящие в стандарт PKCS #11
rv = JC_GetFunctionList(&funcsExtra);
if (rv != CKR_OK)
{
printf("ERROR: JC_GetFunctionList is failed: 0x%08x\n", rv);
return;
}
printf("JC_GetFunctionList - OK\n");
/// ...
// Использование на примере получения версии библиотеки jcPKCS11-2
JC_VERSION_INFO versionInfo;
CK_RV rv = funcsExtra->JC_GetVersionInfo(&versionInfo);
if (rv != CKR_OK)
{
printf("ERROR: JC_GetVersionInfo is failed: 0x%08x\n", rv);
return;
}
printf("JC_GetVersionInfo - OK\n");
/// ...
Примечание
В примерах, входящих в состав JaCarta-2 SDK, класс P11Loader
демонстрирует использование библиотеки jcPKCS11-2 под
Microsoft Windows, macOS и GNU/Linux.
Класс объявлен и реализован в SDK/sources/common/P11Loader.h
и SDK/sources/common/P11Loader.cpp
соответственно.
Проект готов для использования Единой библиотеки PKCS #11.
Примеры JaCarta-2 SDK предназначены для сборки на платформах Microsoft Windows, GNU/Linux и macOS. Для сборки примеров необходима утилита CMake минимальной версии 2.8 (рекомендуется 3.6), генерирующая проектные файлы для сборки примеров (.sln, Makefile).
./sources/make.bat
(проекты будут располагаться в каталоге ./out
, исполняемые файлы в ./bin
);./sources/make.sh
(артефакты сборки будут располагаться в каталоге ./out
, исполняемые файлы в ./bin
).Дополнительные рекомендации указаны в комментариях к каждому примеру.
CertificateRenewal
– применение функций расширения JC_CreateCertificateRenewal()
и JC_CreateCertificateRenewal2()
для создания запроса на перевыпуск сертификата.certificateRequest
– составление запроса на сертификат и записи полученного сертификата на JaCarta-2 ГОСТ.CMS
– создание и расшифрование CMS сообщений, использующих алгоритмы
ГОСТ Р 34.10–2001, ГОСТ Р 34.10–2012 и ГОСТ 28147–89.cmsSignAndVerify
– создание и проверку сообщений в формате CMS типа signed data.data
– поиск, создание и удаление бинарных объектов.deriveKey2012
– пример демонстрирует следующие действия:digest2012
– генерация хэш-последовательности по ГОСТ Р 34.10–2012 (длина ключа 256 бит) и ГОСТ Р 34.10–2012 (длина ключа 512 бит).encryptDecrypt
– зашифрование и расшифрование данных согласно ГОСТ 28147–89.getCertificateInfo
– получение информации о сертификатах на JaCarta-2 ГОСТ.HMAC
– вычисление и проверку HMAC по RFC 2104 c использованием алгоритмов вычисления хэш-суммы:info
– получение информации о библиотеке, слоте и токене.initUser
– очистка всех пользовательских данных с JaCarta-2 ГОСТ и автоматическое создание файловой системы PKCS #11.MAC
– создание и проверка имитовставки согласно ГОСТ 28147–89.pinUser
– смена PIN-кода пользователя.pinUserUnblock
– снятие блокировки PIN-кода пользователя с помощью предъявления PUK-кода.signAndVerify
– пример демонстрирует следующие действия:signAndVerify2012
– пример демонстрирует следующие действия:signAndVerifyCryptoPro
– пример демонстрирует следующие действия:signAndVerifyCryptoPro2012
– пример демонстрирует следующие действия:signAndVerifyExternalHash2012
– пример демонстрирует следующие действия:signAndVerifySignaturePIN
– использование дополнительного PIN-кода подписи для подтверждения операции.verifyWithChainOfTrust
– пример демонстрирует проверку цепочки сертификатов:PIN-код подписи используется как дополнительный фактор для подтверждения операции подписи. Его использование не отменяет необходимость предъявления PIN-кода пользователя для работы в режиме пользователя.
Установка, смена и предъявление
PIN-код подписи устанавливается с помощью функции JC_KT2_SetSignaturePIN()
.
После установки PIN-код подписи пользователь уже не сможет его удалить, только изменить на новый.
Для изменения PIN-кода подписи необходимо вызвать функцию JC_KT2_ChangeSignaturePIN()
.
PIN-код подписи может быть удалён только после инициализации устройства администратором с помощью ПО «АРМ администратора безопасности JaCarta-2 ГОСТ» или «АРМ разработчика JaCarta-2 ГОСТ».
PIN-код подписи предъявляется с помощью функции C_Login()
с параметром
userType равном CKU_SIGNATURE
. Вызов C_Logout()
переключит
текущую сессию в гостевую. Т.е. нельзя отменить PIN-код подписи
отдельно от сессии пользователя.
Использование PIN-кода подписи
Предъявление PIN-кода подписи является опциональным для каждой ключевой пары на устройстве.
Необходимость предъявления задаётся атрибутом CKA_ALWAYS_AUTHENTICATE
:
CK_TRUE
– необходимо предъявление PIN-кода подписи;CK_FALSE
– предъявление PIN-кода подписи не требуется.Атрибут неизменяемый, т.е. необходимость использования PIN-кода подписи для каждой ключевой пары задаётся на этапе её создания.
Подготовка PIN-кода подписи к использованию:
JC_KT2_SetSignaturePIN()
.C_GenerateKeyPair()
,
где в шаблоне закрытого ключа установить атрибут CKA_ALWAYS_AUTHENTICATE
в CK_TRUE
.Примечание
Если не установить PIN-код подписи, но при этом создать ключевую пару с необходимостью его предъявления, то такой ключевой парой нельзя будет подписать до установки PIN-кода подписи.
Использование PIN-кода подписи:
C_Login()
с параметром userType равном CKU_USER
.
Произойдет переход в пользовательскую сессию.C_Login()
с параметром userType равном CKU_SIGNATURE
.
Сессия не изменится, т.е. останется пользовательской.C_Login()
.
Произойдет переход в гостевую сессию.Для его включения необходимо вызвать функцию C_Login()
с параметром userType равном CKU_USER_SM
.
Примечание
Строгий сеанс не поддерживается для смарт-карт JaCarta-2 ГОСТ, подключенных к Антифрод-терминалу.